IJobDispatcher

Namespace Tracon · Assembly Tracon.Abstractions.dll

Queues a job for a registered IJobHandler.

public interface IJobDispatcher

Remarks

The supported way for consumer code to create work. IJobStore stays the persistence surface: it takes a fully formed JobRecord, so the caller has to invent the identifier, the status and the timestamps, and it accepts any handler key, including one nobody registered — such a job only fails later, in the worker. This interface closes both gaps.

Call this interface to queue work; Tracon supplies the implementation, so do not implement or replace it. To run work of your own kind, implement IJobHandler.

It performs no authorization of its own: the caller is already inside the process. The HTTP surface has its own, narrower gate (TraconSchedulingOptions.HttpSchedulableHandlerKeys).

Lifetime: registered as a singleton and safe to call from any thread; it holds no per-call state.

Tenant: takes an expected tenant — JobRequest.TenantId is required and is the tenant the job is queued for. The ambient tenant is not consulted; a caller that wants it passes it explicitly.

Delivery: queueing itself is exactly one row — the method either returns a queued JobRecord or throws, and it never retries on its own. What happens afterwards is the queue’s contract, and that is at-least-once: the handler may run more than once for the job this call created (see IJobHandler.ExecuteAsync).

Attribution: a JobHandlerKeys.Workflow or JobHandlerKeys.AgentBatch job carries the user and labels IRunAttributionContext resolves at the time of this call: the current request, or an open AmbientRunAttributionScope with the built-in context. The worker that runs the job sees neither, so they are written into the stored payload as the envelope {"items": [...], "userId": "...", "labels": {...}}, and every run the job starts is attributed to them. A payload that is already such an envelope keeps its own attribution. No other handler key is changed.

Methods

EnqueueAsync(JobRequest, CancellationToken)

Validates the request and queues the job.

ValueTask<JobRecord> EnqueueAsync(JobRequest request, CancellationToken cancellationToken = default)

Parameters

request JobRequest

What to run, for whom, and with what input.

cancellationToken CancellationToken

The cancellation token.

Returns

ValueTask<JobRecord>

The queued job record, with its identifier and counters filled in.

Exceptions

ArgumentNullException

request is null.

ArgumentException

JobRequest.HandlerKey is not registered, the request’s tenant, target or lane is not valid, JobRequest.MaxDuration is outside one millisecond to about 49.7 days, or a workflow or agent batch payload is an attribution envelope that is malformed or breaks a RunLabels limit.