Reference

Glossary

The names Trax uses, in the code and in these pages. Where a term has a familiar equivalent, its entry starts with it (Roughly:); the rest of the entry is the exact meaning. Each entry says where the type lives; Packages says which package to install for it. Each term is a heading, so a link can name it, as the operations console's help links do: /docs/reference/glossary#manifest-group.

The railway words

The railway picture. Stations Cart, Address, Payment, Placing and Placed sit on a track. A signal stands before Placing. The PlaceOrder train has left Placing and passes junctions on its way to Placed. Stations are states, tracks are moves, signals are guards, trains are the work, junctions are its steps.

Trax uses railway words, and the picture holds:

  • Stations are states: where the process waits for someone to act.
  • Tracks are moves: the only ways from one station to the next. There is no track from Cart straight to Placed.
  • Signals are guards: checks a move must pass before it is allowed.
  • Trains are the work, such as reserving stock or taking a payment. A train never waits: it leaves a station and runs without stopping to the next one. Not every move needs a train; here only Placing starts one.
  • Junctions are steps: the points a train passes on its way. If you know railways, note that in Trax a junction is a step on a train's route, not a place where tracks split.

You lay the stations, the track and the signals, and you build the trains and their junctions. Trax runs the railway: it keeps every process at exactly one station, lets nothing past a signal that says no, and dispatches the trains.

Trains and junctions

Train

Roughly: a workflow, or one use case.

Train<TIn, TOut> in Trax.Core.Train. A class that takes one input, runs the chain its Junctions() method declares, and returns either the output or the exception that stopped it. See Trains and Junctions.

ServiceTrain

Roughly: a workflow whose every run is recorded.

ServiceTrain<TIn, TOut> in Trax.Effect.Services.ServiceTrain. A train that records each run as a Metadata row and runs the registered effects around it. It implements IServiceTrain<TIn, TOut>, and its Run is sealed, so what runs is always the declared chain. The base class for trains the mediator, scheduler and API can run.

Route

IRoute<TIn, TOut> in Trax.Core.Route: anything with Run(input, cancellationToken) that produces an output or fails. Every train is a route. AddScopedTraxRoute<IMyTrain, MyTrain>() registers a train under its interface.

Junction

Roughly: one step of a workflow.

Junction<TIn, TOut> in Trax.Core.Junction. One step of a chain: its Run(TIn) returns Task<TOut>. Trax builds a junction through its single public constructor, taking each argument from Memory first and the DI container second.

EffectJunction

EffectJunction<TIn, TOut> in Trax.Effect.Services.EffectJunction. A junction whose runs the junction effects (the junction logger, junction progress) can see. It works only inside a ServiceTrain and throws a TrainException in any other train.

Chain

Roughly: the steps, in order.

The sequence of junctions a train declares in Junctions(), written with Chain<TJunction>(), ShortCircuit<TJunction>() and Resolve(). See Building Chains.

Chain verification

The check AddMediator registers: at host startup it replays every registered train's chain and refuses to start when one cannot run, naming the train, the step and the missing type. See Troubleshooting.

Memory

Roughly: the values a run has so far, looked up by type.

The values a running train holds, keyed by type. It starts with the train's input, and each junction's output is added to it. A junction's input, and each constructor argument Memory can supply, is taken from it by type. See Memory.

Right track / left track

Roughly: the success path and the failure path.

A chain's two outcomes, as Trax.Core's Either<Exception, T>. Right carries the value on to the next junction; left carries the exception past every remaining junction to the train's result.

Checkpoint

Roughly: a save point a later run resumes from.

Checkpoint<TState>() in a chain: stores a state the chain declares, so a later run of the same input resumes after it instead of running every step before it again. See Checkpoint.

Decider

Roughly: whatever answers a branching question: a rule, a lookup, a model.

IDecider in Trax.Core.Decisions: what answers a train's typed questions (Decide) about a value in Memory, such as a model. With decision recording on, each answer is stored, and a requeued run replays it rather than asking again. See Decisions.

ShortCircuit

Roughly: an early return.

A chain step that ends the train early with its output when it succeeds, and lets the chain continue when it throws. See ShortCircuit.

Effects and recording

Effect

Roughly: middleware around every run.

Something that runs alongside every ServiceTrain run without being part of its chain. An effect provider (IEffectProvider in Trax.Effect.Services.EffectProvider) tracks the run's models and persists them when the train saves. Effects are added on the AddEffects builder: a data provider, AddJson(), SaveTrainParameters(). See Effect Providers.

Junction effect

An effect that runs before and after each EffectJunction rather than around the whole train: AddJunctionLogger() and AddJunctionProgress().

Data provider

The effect that stores runs: UsePostgres(...), UseSqlite(...) or UseInMemory(), one package each. The scheduler, junction progress and state machines refuse to start without one.

Metadata

Roughly: the record of one run.

Metadata in Trax.Effect.Models.Metadata, a row of trax.metadata. One per ServiceTrain run: the train's name, its TrainState (Pending, InProgress, Completed, Failed, Cancelled), start and end times, input and output when SaveTrainParameters() stores them, and on failure the junction, exception, reason and stack trace. ParentId links a run to the run that started it. See Metadata.

Run

One execution of a ServiceTrain, from its input to its output or the failure that stopped it, stored as one Metadata row. The operations console and the GraphQL operations fields call it a run; a retry or a requeue is a new run, never a change to an old one. See Metadata.

ExternalId

A string id meant for use outside the database. On a Manifest it is the stable name the scheduling APIs key on: scheduling the same ExternalId again updates that manifest instead of adding one. On a Metadata row it is typically a GUID by which other systems refer to the run.

Lifecycle hook

An ITrainLifecycleHook, registered with AddLifecycleHook. Trax calls its OnStarted, OnCompleted, OnFailed, OnCancelled and OnStateChanged as a run changes state, each optional; an exception it throws is logged and never fails the train. See AddLifecycleHook.

Broadcaster

UseBroadcaster(...): publishes train lifecycle events to other processes through a transport such as RabbitMQ, or to browsers through SignalR. See Broadcaster Sinks.

Log

A row of trax.log: one ILogger message captured by AddDataContextLogging. See Debugging with the Log Table.

The mediator

Mediator

Roughly: a dispatcher from an input type to the train that handles it.

What AddMediator(...) registers: it discovers the trains in the assemblies you name, so callers can run a train without referencing its class. See Mediator.

TrainBus

ITrainBus in Trax.Mediator.Services.TrainBus. RunAsync<TOut>(input) finds the train registered for the input's type and runs it. When none is registered it throws NoTrainForInputException. See TrainBus.

Scheduling

Manifest

Roughly: a saved schedule entry, like one line of a crontab.

Manifest in Trax.Effect.Models.Manifest, a row of trax.manifest. A job definition: which train to run, the input to run it with, when (cron, interval, once, after a parent manifest succeeds, or only when triggered), and its retry and timeout policy. Each run of a manifest creates a Metadata row. See Scheduling.

IManifestProperties

The marker interface in Trax.Effect.Models.Manifest (package Trax.Effect, not Trax.Scheduler) that a scheduled train's input type implements, so the scheduler can store the input on the manifest and rebuild it for each run. The type must round-trip through System.Text.Json.

Manifest group

Roughly: a concurrency pool for scheduled jobs.

A row of trax.manifest_group: settings shared by the manifests in it, MaxActiveJobs (how many may run at once), Priority (dispatch order between groups) and IsEnabled. See Concurrency.

Work queue

Roughly: runs waiting to start.

trax.work_queue: runs that have been asked for but not yet dispatched. Every source of a run (a due manifest, a trigger, a dashboard re-run) adds an entry, and the job dispatcher takes entries from it. An entry is Queued, Dispatched or Cancelled.

Background job

A row of trax.background_job: a dispatched run waiting for a local worker, which claims the row, runs the train and deletes the row.

Dead letter

A row of trax.dead_letter, created when a manifest's failed runs exceed its MaxRetries. It waits as AwaitingIntervention until an operator retries it (Retried) or acknowledges it (Acknowledged). See Dead Letters.

Bulk operation

One action (cancel, requeue, acknowledge, queue, enable or disable) applied to every row a list's filter matched when it started, run in batches on the server, with a count of what took and why each id that did not was refused. Started with startBulkOperation, from the operations console's batch bar or GraphQL. See Bulk operations.

Manifest manager

The scheduler's own train that runs each cycle: it cancels timed-out jobs, reaps stale and failed runs into dead letters, and turns due manifests into work queue entries. See Manifest Manager.

Job dispatcher

The scheduler's own train that takes queued work queue entries, applies the global and per-group limits, and hands each one to a job submitter. See Job Dispatcher.

Job runner

The scheduler's own train that runs one dispatched job: it loads the job's Metadata and manifest, then runs the train through the TrainBus. See Job Runner.

Local worker / remote worker

Where a dispatched job runs. Local workers are threads in the scheduler's own process, the default with Postgres or SQLite. Remote workers are other processes reached over HTTP, SQS or AWS Lambda. See Remote Execution.

Job submitter

IJobSubmitter in Trax.Scheduler.Services.JobSubmitter: what the job dispatcher hands a run to. PostgresJobSubmitter writes it to trax.background_job for local workers or AddTraxWorker processes; the remote submitters post it over HTTP, SQS or AWS Lambda.

Dependent train

Roughly: a job that runs after another one succeeds.

A manifest with ScheduleType.Dependent: rather than running on a timer, it runs after its parent manifest's latest success. See Dependent Trains.

API and state machines

Query model

An EF entity marked [TraxQueryModel] (in Trax.Effect.Attributes), which AddTraxGraphQL serves as a filterable, paged query under discover. See Query models.

TraxPrincipal

TraxPrincipal in Trax.Api.Auth: the authenticated caller as Trax sees it, with a scheme-qualified id such as TraxApiKey:alice, its roles and its claims. See TraxPrincipal.

State machine

Roughly: a long-lived record that moves between named states.

A machine deriving Machine<TState, TTrigger> in Trax.StateMachine.Persistence: states, triggers and a context record, stored as a language-neutral snapshot that the C# engine and its TypeScript twin both read. See State Machines.

Run-once effect

Roughly: an idempotent side effect, the kind usually called "exactly-once".

An ISnapshotEffect bound to a transition with RunsOnce<TEffect>(), or any call made through IdempotentEffect. Trax records its result once per intent, and a retry, a second device or a repeated send replays that result instead of calling again. The call itself is at least once: if the process dies after the downstream system acted but before the receipt was recorded, the lease expires and the effect runs again under the same key. The effect passes that key to the system it calls, so the downstream system can tell it is a repeat. See Effects.