Explanation

Trains and junctions

Source Junction.cs, EffectJunction.cs, ServiceTrain.cs

A train is a typed unit of work, TIn to TOut, whose body is a chain of junctions. A junction does one thing: it takes one input and returns one output. The train runs its junctions in order over a Memory of typed values, and each junction's input is found there by type and its output stored there. The first junction that throws stops the chain, and the train returns that exception instead of an output. Core explains that railway.

Where to put trains and their files in a project is a how-to: Organize trains in a project.

Junctions

using System.ComponentModel.DataAnnotations;
using Trax.Core.Functional;
using Trax.Core.Junction;
 
public class ValidateEmailJunction(IUserRepository users) : Junction<CreateUserRequest, Unit>
{
    public override async Task<Unit> Run(CreateUserRequest input)
    {
        if (await users.GetByEmailAsync(input.Email) is not null)
            throw new ValidationException($"Email {input.Email} already exists");
 
        return Unit.Default;
    }
}

A junction takes its dependencies through its constructor; the train builds it from the container when the chain reaches it. Throwing is how a junction fails, so a junction reads like ordinary code and the train, not the junction, decides what a failure does to the rest of the chain.

A junction also carries the run's CancellationToken as a property, set before Run is called. How cancellation works covers it, and Make a junction cancellable shows how to use it.

EffectJunction vs Junction

There are two base classes, and a junction's code is the same under either.

Junction<TIn, TOut>, in Trax.Core, handles the input, the output and the railway. It records nothing and has no hooks, so it runs anywhere a chain runs, including a plain Train constructed with new.

EffectJunction<TIn, TOut>, in Trax.Effect, derives from it and makes the junction observable when it runs inside a ServiceTrain. It records a junction metadata entry (name, input and output types, start and end times, railway state, and the id of the run it belongs to), and the junction effect providers (AddJunctionLogger, AddJunctionProgress, junction events) hook into its lifecycle before and after it runs. On a plain Junction those providers record nothing, and they do not say so.

using System.ComponentModel.DataAnnotations;
using Trax.Core.Functional;
using Trax.Effect.Services.EffectJunction;
 
public class ValidateEmailEffectJunction(IUserRepository users)
    : EffectJunction<CreateUserRequest, Unit>
{
    public override async Task<Unit> Run(CreateUserRequest input)
    {
        if (await users.GetByEmailAsync(input.Email) is not null)
            throw new ValidationException($"Email {input.Email} already exists");
 
        return Unit.Default;
    }
}

The split exists so that Trax.Core stays free of the effect system: a library of junctions can be written against Junction and run in a plain Train with no database and no container. The cost is a choice per junction. An EffectJunction needs the ServiceTrain it reports to, so one run inside a plain Train throws TrainException (Cannot run an EffectJunction (<junction>) against a non-ServiceTrain (<train>)).

The run id the metadata entry carries (Metadata.TrainMetadataId) is the primary key of the run's trax.metadata row, which lets a junction read its own run back, for example to check that it has not been failed before it performs a side effect. Identifying the run from inside a junction explains why the junction's registration lifetime matters when it does.

Declaring the chain

using Trax.Core.Functional;
using Trax.Effect.Services.ServiceTrain;
 
public class CreateUserTrain : ServiceTrain<CreateUserRequest, User>, ICreateUserTrain
{
    protected override Task<Either<Exception, User>> Junctions() =>
        Chain<ValidateEmailJunction>().Chain<CreateUserJunction>().Resolve();
}

Junctions() returns Task<Either<Exception, TOut>>, and the chain ends in Resolve(), which yields the train's output from Memory or the exception that stopped the chain. The framework seeds Memory with the input before the chain runs. The chain methods (Chain, ShortCircuit, Extract, AddServices and the rest) are protected methods on the train, and each returns a MonadTask, so the calls chain. Building chains describes what each one does on the railway.

There is no escape hatch, on purpose

Junctions() is the only way to declare a chain. RunInternal is private and Activate is internal, so a train cannot build its chain imperatively. Upgrading a train that used them is covered in Removal of RunInternal and Activate.

A ServiceTrain cannot override Run either. Run(input, ct) is a sealed override, the Run(input, metadata) overloads are not virtual, and NewMonad(), which builds the monad the chain runs on, is sealed. Run owns what wraps the chain: the metadata row, the lifecycle hooks and the outcome write. An override that did its own work, or skipped base.Run, would run untracked while every surface still reported the train. A plain Train<TIn, TOut> from Trax.Core keeps a virtual Run and NewMonad(), because it has none of that to protect.

That is what makes a chain readable before it runs. A chain assembled in code has no single shape, so the host could not check it, and a chain that varied by input would mean the shape checked is not necessarily the shape that runs. Keeping the guarantee means the declaration is the only option.

Two rules follow from it.

A chain cannot read the value being processed. TrainInput and TrainOutput throw ChainDeclarationException while a chain is being declared. Work that needs the input belongs in a junction, which receives it as its argument.

A value a later junction reads comes from something the chain declares. Usually that is an earlier junction, whose return value lands in Memory keyed by its output type. The chain can also seed Memory with AddServices(value) (stored under the interface type it names) or Extract<TIn, TOut>(value) (stores the TOut member of the value it is given). What is gone is Activate's way of handing objects in from outside the declaration.

The host checks every chain before it serves traffic

Because a chain is a declaration of types, whether it can run is decidable without running it. AddMediator registers a hosted service that reads every registered train's chain at startup and refuses to start the host when one of them cannot run: a junction that needs a value nothing before it produces, a junction Trax cannot build, a chain that reads the input, a train whose constructor needs something the container does not register. Every train is checked before anything is reported, so one start lists every fault.

The alternative was to let each of those fail at runtime, which surfaces each one only on the path that hits it, and for a rarely run train that can be a long way from the deploy that broke it. Startup chain check lists every fault, every warning, and how to turn the check off.

What the check counts as available

The check replays the rules a run uses to store and find values in Memory, so what it accepts is what a run would find: the input under its declared type and interfaces, a junction's output under exactly its declared type, and a short circuit's output not at all, because it is present on only one of its two paths. The full table is in Startup chain check.

Lifecycle hooks

ServiceTrain has four protected virtual hooks a train overrides to react to its own runs: OnStarted, OnCompleted, OnFailed and OnCancelled. They default to no-ops.

using Trax.Core.Functional;
using Trax.Effect.Models.Metadata;
using Trax.Effect.Services.ServiceTrain;
 
public class NotifyingCreateUserTrain(ISlackClient slack)
    : ServiceTrain<CreateUserRequest, User>,
        ICreateUserTrain
{
    protected override Task<Either<Exception, User>> Junctions() =>
        Chain<ValidateEmailJunction>().Chain<CreateUserJunction>().Resolve();
 
    protected override async Task OnFailed(
        Metadata metadata,
        Exception exception,
        CancellationToken ct
    ) => await slack.PostAsync($"User creation failed: {exception.Message}", ct);
}

Each hook receives the run's metadata as it stands at that point: OnStarted sees the input, OnCompleted the output too, OnFailed and OnCancelled the failure. A hook that throws is logged and never fails the run, because a notification that failed is not a reason to report the work as failed. Global lifecycle hooks see every train's runs and fire before the train's own. OnFailed sees the failure's FailureClass, which an IFailureClassifier the host registers decides; see Failure classification.

OnQueue (enqueue-time hook)

OnQueue, DeferQueuePromotion and QueueSubjectKey are a different kind of hook: the mediator's queue path calls them when it accepts a mutation, before the train runs, and a throw refuses the mutation. Enqueue hooks describes each one. A side effect written in OnQueue and the work queue row are two writes, and a train that returns a subject key stops two queued mutations for the same record from running at once; How queued work stays durable and serialized explains both.

SDK Reference

Junctions | Chain | Resolve | ServiceTrain | Junction | EffectJunction | TrainException | AddLifecycleHook