JobHandlerKeys

Namespace Tracon · Assembly Tracon.Abstractions.dll

The built-in job handler keys, plus validation for the keys a consumer registers.

public static class JobHandlerKeys

Inheritance

object ← JobHandlerKeys

Inherited Members

object.GetType(), object.MemberwiseClone(), object.ToString(), object.Equals(object?), object.Equals(object?, object?), object.ReferenceEquals(object?, object?), object.GetHashCode()

Remarks

A handler key is a job’s identity: it is both how the job is classified (JobRecord.HandlerKey, the handlerKey query filter, the tracon.job.handler_key metric tag) and how the background worker picks the IJobHandler that executes it. There is no second field; a key registered with AddJobHandler<T>(key) is dispatched by exact, ordinal match, so registration order never decides the winner.

Grouping is done with the namespace prefix: everything Tracon ships starts with tracon., and a consumer picks its own prefix (contoso.). JobRecord.Lane (capacity) and JobRecord.TargetName (the handler’s input) stay separate from the key.

Fields

AgentBatch

Runs an agent as a batch over a set of inputs.

public const string AgentBatch = "tracon.agent-batch"

Field Value

string

AgentRun

A single queued (durable) agent run.

public const string AgentRun = "tracon.agent-run"

Field Value

string

Remarks

Runs started with Prefer: respond-async run under this key. Unlike JobHandlerKeys.AgentBatch, it does not require an item set, and the run identifier is generated IN ADVANCE by the caller (the HTTP layer) — JobRecord.Id carries the same value as the run identifier.

ApprovalResume

A new run that resumes a queued run after an approval decision.

public const string ApprovalResume = "tracon.approval-resume"

Field Value

string

Remarks

separate from JobHandlerKeys.AgentRun: the old run row closed with RunStatus.AwaitingApproval never changes again (the same principle as RunStatus.AwaitingInput); this job opens a new runs row with a new run identifier. The payload carries the identifier of the PendingApproval record whose decision was made.

Eval

An evaluation (eval) run over a suite’s cases.

public const string Eval = "tracon.eval"

Field Value

string

OnlineEval

Scores a sampled production run.

public const string OnlineEval = "tracon.online-eval"

Field Value

string

Remarks

The payload is empty or for diagnostics; the identifier of the run to score is the job item itself (JobItemRecord.Input) — the same pattern as how the JobHandlerKeys.Eval job carries a case identifier.

ReservedPrefix

The prefix reserved for the handlers Tracon itself ships.

public const string ReservedPrefix = "tracon."

Field Value

string

Remarks

Registering a consumer handler under this prefix throws at startup, so a built-in key can never be shadowed by accident.

Retention

A retention sweep. JobRecord.TargetName is either a specific RetentionTargets value or "*", which processes all enabled policies.

public const string Retention = "tracon.retention"

Field Value

string

RunContinuation

A new run, in the SAME session, that continues an interrupted run.

public const string RunContinuation = "tracon.run-continuation"

Field Value

string

Remarks

separate from JobHandlerKeys.AgentRun and JobHandlerKeys.ApprovalResume: triggered by orphaned-run reconciliation, not by a client request. The old run row stays RunStatus.Failed and never changes again; this job opens a new runs row whose ContinuedFromRunId points at it.

WebhookDelivery

A single webhook delivery attempt. The payload carries the delivery record’s identifier; the body is read from the webhook_deliveries table.

public const string WebhookDelivery = "tracon.webhook-delivery"

Field Value

string

Workflow

Runs a workflow once for each pending item of the job.

public const string Workflow = "tracon.workflow"

Field Value

string

Remarks

The handler starts runs. It does not answer a pending request: that goes through the respond endpoint.

When TraconWorkflowOptions.ResumeInterruptedRuns is on, the handler writes the run identifier on the item before the run starts. A job leased again after a crash or a shutdown finds that item still pending and resumes its run from the latest checkpoint instead of starting it again.

WorkflowRun

One queued workflow operation: a run, a resume or a response to a pending request, started with Prefer: respond-async.

public const string WorkflowRun = "tracon.workflow-run"

Field Value

string

Remarks

The HTTP layer checks the caller (attribution, authorization, session ownership, quota, parameters, the response’s shape) BEFORE it queues the job, and generates the run identifier in advance: JobRecord.Id carries the same value as the run identifier, as for JobHandlerKeys.AgentRun. The job has no items.

This key cannot be scheduled over HTTP. Its payload names the run and the operation to apply, and the checks above run only when the job is queued; a payload written by hand would skip them.

Properties

BuiltIn

Every key Tracon itself ships, in no particular order.

public static IReadOnlyList<string> BuiltIn { get; }

Property Value

IReadOnlyList<string>

Methods

IsReserved(string?)

Checks whether key falls inside the JobHandlerKeys.ReservedPrefix namespace.

public static bool IsReserved(string? key)

Parameters

key string?

The candidate key.

Returns

bool

true if the key is reserved for Tracon.

IsValidKey(string?)

Checks whether key is a valid handler key: 1-128 characters, lowercase ASCII letters, digits, ., _, or -, starting with a letter or digit.

public static bool IsValidKey(string? key)

Parameters

key string?

The candidate key.

Returns

bool

true if the key is valid.

Remarks

Uppercase letters are rejected, not normalized — the same reasoning as JobLanes.IsValidName. Keys are compared ordinally everywhere (dispatch, queries, metric tags), so allowing case variants would let "Contoso.Report" and "contoso.report" silently become two different handlers, and a job queued under one of them would never find its handler.