Lyo.Job.Models 1.0.7

Lyo.Job.Models

Shared DTOs, builders, enums, metrics constants, distributed-tracing helpers, and message-queue contracts for the Lyo job-management subsystem. 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/)

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

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

Hardening model

Definitions, schedules, and runs carry the knobs that power priority dispatch, retention, misfire handling, exponential backoff, idempotency, rate limiting, SLA tracking, alerting, blackout calendars, batch fan-out, workflows, encryption markers, and audit correlation:

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

Located under Request/ and Response/. Each lifecycle entity has a request DTO for create/update and a response DTO for reads:

JobInfo bundles a JobDefinitionRes with its last / last successful / last failed runs for dashboards.

JobRunRes exposes GetParameterValueAs<T>, GetResultValueAs<T>, GetParameterDictionary, and GetResultDictionary for typed access to parameter and result bags. These, and the list-level accessors in JobRunParameterExtensions (GetInt, GetLong, GetDecimal, GetBool, GetGuid, GetDateTime, GetEnum<T>, GetRegex, GetAs<T>), delegate to Lyo.Common.Conversion.TypeConversion: key lookups are case-insensitive, 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 passing a format to GetAs<T> uses the format-aware ToScalar<T> path.

Builders (Builders/)

Fluent factories for assembling request DTOs without dropping into raw initializers.

• JobDefinitionBuilder. New(name), SetDescription, SetType, ForCSharpWorker / ForPythonWorker, AsImportInCSharp, schedule/parameter/trigger/restriction helpers, email-parameter helpers. WithBlackoutCalendar / AddBlackoutWindow set a definition-level default cascaded to every schedule (by id or inline). Build() returns JobDefinitionReq.
• JobScheduleBuilder. EveryDay, Weekdays, SetMonths, SetDays, SetTimes, SetInterval, cron helpers, WithMisfirePolicy, WithBlackoutCalendar, AddBlackoutWindow, Build() → JobScheduleReq.
• JobBlackoutCalendarBuilder. AddBlackoutWindow(...) with JobBlackoutPolicy (Skip / Defer); AddBlackoutHoliday(HolidayInfo, ...) / AddBlackoutHolidays(...) / AddFederalHolidayBlackouts() expand Lyo.DateAndTime.HolidayInfo records into concrete dated windows at build time. Build() → JobBlackoutCalendarReq.
• JobScheduleBuilder.WithBlackoutCalendar. per-schedule override: link by Guid, or inline create via Action<JobBlackoutCalendarBuilder>.
• JobWorkflowBuilder. ordered steps with DependsOnStepIds and JobWorkflowFailurePolicy. Build() → JobWorkflowReq.
• JobTriggerBuilder, JobRunBuilder, JobRunResultBuilder. As before; JobRunBuilder supports AddEncryptedParameter.

Enums

Distributed tracing (JobTracing)

ActivitySource name: Lyo.Job. Helpers: StartCreateRun, StartRun, FinishRun, StartWorkerExecution (links to queue envelope TraceId), TryParseParentContext. Register the source in your 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. JobWorkerBase fills built-in keys on register and heartbeat; host extras from GetWorkerMetadata() merge last.

Metrics (Constants.Metrics)

Recorded via IMetrics when registered in hosting packages:

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

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

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

Workers also inherit queue.worker.* metrics from QueueWorkerBase.

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. API responses mask encrypted parameters (***); 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.
• JobRunParameterExtensions. typed getters on parameter/result lists.

Dependencies

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

• Lyo.Api.Models (direct, lyo)
• Lyo.DateAndTime (direct, lyo)
• Lyo.Exceptions (direct, lyo)
• Lyo.Schedule.Models (direct, lyo)
• System.Diagnostics.DiagnosticSource 10.0.5 (direct, microsoft, netstandard2.0)
• Lyo.Common (transitive, lyo)
• Lyo.Query.Models (transitive, lyo)
• Lyo.Result (transitive, lyo)
• Microsoft.Extensions.Logging.Abstractions 10.0.5 (transitive, microsoft)
• System.Memory 4.6.3 (transitive, microsoft, netstandard2.0)
• System.Text.Json 10.0.5 (transitive, microsoft, netstandard2.0)