Lyo.Job.Models 2.0.0

Lyo.Job.Models

Shared DTOs, builders, enums, metrics constants, distributed-tracing helpers, and message-queue contracts for Lyo job management. Consumed by Lyo.Job.Postgres (the API host), Lyo.Job.Scheduler, Lyo.Job.Worker, Lyo.Job.Alerts, and any Blazor / client code that talks to the job service.

Multi-targets netstandard2.0 and net10.0 so the same DTOs flow through legacy callers and modern .NET hosts.

This package is a contract library. It has no AddXxx DI registration. Hosts reference it for DTOs, builders, metrics constants, and IJobEventPublisher. Wire persistence via Lyo.Job.Postgres, scheduling via Lyo.Job.Scheduler, and workers via Lyo.Job.Worker.

Examples

Retry backoff (JobRetryBackoff)

// Linear: baseSeconds × attempt
// Exponential: baseSeconds × 2^(attempt-1) with ±25% jitter
var delay = JobRetryBackoff.ComputeBackoffSeconds(
    baseSeconds: 60, attempt: 3, JobRetryBackoffType.Exponential);

Builders (Builders/)

using Lyo.Common.Metadata.Records;

var definition = JobDefinitionBuilder
    .New("Nightly Sync", "Pulls everything from the upstream API")
    .ForCSharpWorker()
    .SetType("Import")
    .AddJobParameter("BatchSize", LyoTypeInfo.Int, 500)
    .Build();

var run = JobRunBuilder
    .New(definition.Id, "scheduler")
    .AddParameter("BatchSize", 1000)
    .Build();

Hardening model

Priority dispatch, retention, misfire handling, exponential backoff, idempotency, rate limiting, SLA tracking, alerting, blackout calendars, batch fan-out, workflows, encryption markers, and audit correlation are all driven by knobs on definitions, schedules, and runs:

JobDefinitionReq defaults

flowchart TB
    subgraph models [Lyo.Job.Models]
        Def[JobDefinitionReq]
        Sch[JobScheduleReq + Calendar]
        Run[JobRunReq]
        Wf[JobWorkflowReq]
    end
    subgraph runtime [Runtime packages]
        PG[Lyo.Job.Postgres]
        SchSvc[Lyo.Job.Scheduler]
        Wkr[Lyo.Job.Worker]
    end
    Def --> PG
    Sch --> SchSvc
    Run --> PG
    Run --> Wkr
    Wf --> SchSvc

Requests and responses

Under Request/ and Response/. Every lifecycle entity has a create/update request DTO and a read response DTO:

Dashboards get JobInfo, which wraps a JobDefinitionRes together with last / last successful / last failed runs.

Typed access to parameter and result bags on JobRunRes is GetParameterValueAs<T>, GetResultValueAs<T>, GetParameterDictionary, and GetResultDictionary. Those, plus the list-level accessors in Lyo.Parameters.LyoKeyedValueExtensions (GetInt, GetLong, GetDecimal, GetBool, GetGuid, GetDateTime, GetEnum<T>, GetRegex, GetAs<T>), go through Lyo.Common.Core.Conversion.TypeConversion: lookups ignore key case, booleans parse leniently (1/0, y/n, yes/no, t/f, on/off), and GetAs<T> deserializes JSON-typed parameter values into complex types. GetDateTime keeps round-trip ("O") parsing so UTC timestamps preserve their kind, and a format passed to GetAs<T> uses the format-aware ToScalar<T> path.

Builders (Builders/)

Request DTOs can be assembled with fluent factories instead of raw initializers.

• JobDefinitionBuilder. New(name), SetDescription, SetType, ForPythonWorker / ForCSharpWorker, AsImportInCSharp, helpers for schedule/parameter/trigger/restriction, and email parameters. AddBlackoutWindow / WithBlackoutCalendar set a definition-level default cascaded to every schedule (by id or inline). Build() returns JobDefinitionReq.
• JobScheduleBuilder. Weekdays, EveryDay, SetMonths, SetDays, SetTimes, SetInterval, cron helpers, WithMisfirePolicy, WithBlackoutCalendar, AddBlackoutWindow, Build() → JobScheduleReq.
• JobBlackoutCalendarBuilder. AddBlackoutWindow(...) with JobBlackoutPolicy (Defer / Skip); AddBlackoutHoliday(HolidayInfo, ...) / AddBlackoutHolidays(...) / AddFederalHolidayBlackouts() store one window per holiday (HolidaySlug); AddBlackoutCalendarDays(...) stores month flags plus days of month. JobBlackoutCalendarEvaluator.AdjustSlotForBlackout matches those rules at runtime. Build() → JobBlackoutCalendarReq.
• JobScheduleBuilder.WithBlackoutCalendar. Override on one schedule: link by Guid, or create inline via Action<JobBlackoutCalendarBuilder>.
• JobWorkflowBuilder. Ordered steps with DependsOnStepIds and JobWorkflowFailurePolicy. Build() → JobWorkflowReq.
• JobRunResultBuilder, JobRunBuilder, JobTriggerBuilder. As before; JobRunBuilder supports AddEncryptedParameter.

Enums

Distributed tracing (JobTracing)

The ActivitySource is named Lyo.Job. Helpers: StartCreateRun, StartRun, FinishRun, StartWorkerExecution (links to queue envelope TraceId), TryParseParentContext. Register the source in the host OpenTelemetry / ActivityListener pipeline so spans from Lyo.Job.Postgres, Lyo.Job.Worker, and the scheduler correlate.

Event publisher (Events/IJobEventPublisher)

• PublishRunCreatedAsync(runId, workerType, priority = 0). priority honored when the broker queue supports x-max-priority.
• PublishRunStartedAsync, PublishRunFinishedAsync, PublishRunCancelledAsync, PublishDefinitionUpdatedAsync.
• PublishAlertAsync(definitionId, runId, alertType, message). routes to job.notifications.alert.
• Subscribers: definition updates, run completions, run cancellations. SubscribeToRunCancellationsAsync must broadcast to every subscribed instance (implementations use per-instance exclusive queues, job.run.{workerType}.cancel.{instanceId}). A shared competing-consumer queue would silently lose cancellations for scaled-out worker types. Workers may pass instanceSuffix so the exclusive cancel queue name is known for instance metadata.

Worker instance metadata (Constants.WorkerMetadata)

JobWorkerInstanceReq.Metadata is a string bag. Built-in keys are filled by JobWorkerBase on register and heartbeat; host extras from GetWorkerMetadata() merge last.

Metrics (Constants.Metrics)

When hosting packages register IMetrics, these are recorded:

Metrics (Constants.Metrics). job.scheduler.*

Metrics (Constants.Metrics). job.service.*

Metrics (Constants.Metrics). job.worker.*

queue.worker.* metrics from QueueWorkerBase are inherited by workers as well.

Metrics (Constants.Metrics). job.maintenance.*

Metrics (Constants.Metrics). job.sla.*

Constants

Constants.Mq. Topology including JobAlertRoutingKey (job.notifications.alert) and WaitQueueSuffix / QueueGetJobRunCreatedWait. Constants.Rest.Job. CRUD routes plus lifecycle endpoints (RunStarted, RunFinished, RunRequeue, RunsResync, RunHeartbeat, RunChildren, DefinitionsLatestRuns, WorkerInstances, BlackoutCalendars, Workflows, …).

Parameter encryption (Security/IJobParameterEncryptionService)

Interface implemented by Lyo.Job.Postgres.JobParameterEncryptionService. Encrypted parameters are masked (***) on API responses; the worker-trusted Started endpoint decrypts values server-side so executing workers receive real values (workers with the service registered can also decrypt any remaining EncryptedValue locally).

Extensions

• JobScheduleExtensions.ToScheduleDefinition(...). Converts schedule DTOs to Lyo.Schedule.Models.ScheduleDefinition.
• Typed parameter getters. Lyo.Parameters.LyoKeyedValueExtensions works against any ILyoKeyedValue list, so Job, Reporting, and Config share one implementation. The old job-only JobRunParameterExtensions shim is gone — import Lyo.Parameters instead.

Dependencies

Generated from ProjectReference / PackageReference (same model as docs/Lyo.ProjectGraph.html).

• Lyo.Api.Models (direct, lyo)
• Lyo.Common.Metadata (direct, lyo)
• Lyo.DateAndTime (direct, lyo)
• Lyo.Parameters (direct, lyo)
• Lyo.Schedule.Models (direct, lyo)
• System.Diagnostics.DiagnosticSource 10.0.5 (direct, microsoft, netstandard2.0)
• Lyo.Common.Core (transitive, lyo)
• Lyo.Common.Json (transitive, lyo)
• Lyo.Exceptions (transitive, lyo)
• Lyo.Query.Models (transitive, lyo)
• Microsoft.Bcl.AsyncInterfaces 10.0.5 (transitive, microsoft, netstandard2.0)
• System.Memory 4.6.3 (transitive, microsoft, netstandard2.0)
• System.Text.Json 10.0.5 (transitive, microsoft, netstandard2.0)