Lyo.Job.Models 1.0.1

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, Lyo.Job.SignalR, 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();

Production 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:

Production hardening model — 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.

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). Constants.Rest.Job — CRUD routes plus lifecycle endpoints (RunStarted, RunFinished, RunRequeue, 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)
• 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)