AddJunctionEvents

Publishes each step of every run (each junction as it starts and ends, each question a routing step asks and the answer the run acts on, each track it takes) and records it in trax.junction_run. Off unless this is called. See Junction Events.

Signature

public static TraxEffectBuilderWithData AddJunctionEvents(
    this TraxEffectBuilderWithData configurationBuilder
)

Defined on TraxEffectBuilderWithData, so it comes after a data provider. Called before one, it is a compile error: Call UsePostgres(...), UseSqlite(...) or UseInMemory(...) before AddJunctionEvents().

Returns

TraxEffectBuilderWithData, for continued chaining.

Example

services.AddTrax(trax => trax
    .AddEffects(effects => effects
        .UsePostgres(connectionString)
        .AddDecisionRecording()
        .AddJunctionEvents()
        .UseBroadcaster(b => b
            .UseRabbitMq(rabbitMqUrl)
            .UseSignalRHub(opts => opts.WithJunctionEvents()))
    )
);

What it registers

Calling AddJunctionEvents() more than once registers these once.

Event types

Each step is a TrainLifecycleEventMessage whose EventType is one of these constants, with the step in Junction (a JunctionEventPayload). TrainLifecycleEventMessage.IsJunctionEvent(eventType) says whether an event type is one of them.

JunctionEventPayload

// Trax.Effect.Services.TrainEventBroadcaster
public sealed record JunctionEventPayload(
    int Position,
    JunctionRunKind Kind,
    string Name,
    JunctionRunState State,
    DateTime StartedAt,
    DateTime? EndedAt = default,
    double? DurationMs = default,
    FailureClass? FailureClass = default,
    string? FailureException = null,
    string? QuestionKey = null,
    string? Answer = null,
    double? Confidence = default,
    bool Replayed = false,
    string? Decider = null,
    bool AnswerWithheld = false,
    int? Attempt = default,
    bool NameWithheld = false,
    int? TrackPosition = default
)
{
    public const string WithheldName = "(withheld)";
}

It never carries a junction's input or output, the train's input or output, a failure's message, or the state, instructions or criteria of a question. On a withheld track the number, kinds, positions and timing of steps, a failed junction's exception type and failure class, the run's own failure junction and any train started on the track stay visible; see Withholding an answer.

IJunctionEventHandler

// Trax.Effect.Services.TrainEventBroadcaster
public interface IJunctionEventHandler
{
    Task HandleAsync(TrainLifecycleEventMessage message, CancellationToken ct);
}

Register implementations in the container. Each message has a junction event type and a non-null Junction. Junction events reach only these handlers, never an ITrainEventHandler.

• On the host that runs the train, a handler is called on the run's path, resolved from the run's scope, right after the step is published. The next junction waits for it, so it must return quickly and queue anything slow.
• On other hosts it is called by TrainEventReceiverService for steps arriving over the transport, resolved from a fresh scope per message. A step this host published is not delivered to it twice.
• Whatever it throws is logged and does not reach the run or the other handlers.

JunctionRun and ForRun

Each stored step is a JunctionRun on IDataContext.JunctionRuns, with the payload's fields except Decider, plus Id and MetadataId. Read one run's steps, ordered by position, with ForRun:

// Trax.Effect.Data.JunctionEvents
public static IOrderedQueryable<JunctionRun> ForRun(
    this IQueryable<JunctionRun> runs,
    long metadataId
)

var steps = await dataContext.JunctionRuns.AsNoTracking().ForRun(metadataId).ToListAsync(ct);

The API's operations.junctionRuns and the dashboard's timeline read through it too.

Remarks

• Nothing it does can fail a run or change a junction's result: a failure to store, broadcast or hand out a step is logged and swallowed.
• A step is stored by a background writer, in order and in batches, through a data context of its own, so the run never waits on the database. A full queue drops a step, counted and logged. A junction whose end was dropped stays InProgress after its run has ended, so read a row's state together with its run's.
• A run's rows are deleted with its metadata row, by the foreign key's cascade.
• Only EffectJunctions are steps. A junction skipped because an earlier one failed is not a step, and a run that is not saved (no metadata row) publishes none.
• A custom ITrainEventBroadcaster is handed every junction event too, on the run's path; it should queue rather than wait, and may route steps apart from train events.
• A run of a manifest carries its attempt: 1 plus the manifest's failed runs since its last completed or cancelled one, read once when the run begins from the manifest's 1000 most recent runs (a longer streak is reported as 1001) and waited on for at most a second. A failure to read it leaves it out.
• Junction events carry FailureJunction as null; the run's own Failed event names the junction.
• With RabbitMQ, steps go to their own exchange, and after a failure there are dropped untried for a backoff of one second doubling to a minute; see UseBroadcaster: RabbitMQ. With SignalR, they reach clients only after WithJunctionEvents().

Package

dotnet add package Trax.Effect.Data

The extension is in namespace Trax.Effect.Data.Extensions.