Junction Progress
Source Trax.Effect.JunctionProvider.Progress/
The junction progress provider gives real-time visibility into which junction a train is currently executing and enables between-junction cancellation. It registers two junction-effect providers under a single call: CancellationCheckProvider and JunctionProgressProvider.
Registration
dotnet add package Trax.Effect.JunctionProvider.Progressusing Trax.Effect.Data.Postgres.Extensions;
using Trax.Effect.Extensions;
using Trax.Effect.JunctionProvider.Progress.Extensions;
services.AddTrax(trax => trax
.AddEffects(effects => effects
.UsePostgres(connectionString)
.AddJunctionProgress()
)
);What It Registers
AddJunctionProgress registers two junction-effect providers that run in order on every junction:
1. CancellationCheckProvider
Runs before each junction executes. It queries the database for the train's CancellationRequested flag. If the flag is true, it throws an OperationCanceledException and the junction never starts.
The provider uses IDataContextProviderFactory to create a fresh DbContext for each check. This guarantees it always reads the latest database state, even if the cancellation was requested by a different server or process.
After junction execution, this provider is a no-op.
2. JunctionProgressProvider
Runs before each junction to set two columns on the train's Metadata:
| Field | Value |
|---|---|
CurrentlyRunningJunction | The name of the junction about to execute |
JunctionStartedAt | DateTime.UtcNow at the moment the junction begins |
After each junction completes, it clears both columns back to null, or, while a sibling Parallel branch is still running a junction, shows that junction instead.
It writes the two columns, and only those, through a database context of its own, never through the train's effect runner. One writer per run makes the writes, one at a time. A change made while a write is in flight waits for the next write, and every change made in the meantime shares it, so branches that start junctions together wait for at most two writes rather than queueing for one each. The junction waits for the write before it, so the columns show it before it runs; it does not wait for the write after it.
The write after a junction does not take the train's cancellation token, and a failure of it is logged rather than thrown. By then the junction's work has returned, so the write is bookkeeping about work that happened. A caller that cancelled while a junction was finishing its work still gets that work recorded Completed, as it is without junction progress, and a database error on this write does not turn a finished junction into a failed run.
Before the run records its outcome it waits for the writer to finish, and the outcome write always clears both columns. A run cancelled mid-junction, or one whose branch was stopped by a failing sibling, never reaches the write after that junction; the outcome write clears what it left.
Execution Order
CancellationCheck runs first, before JunctionProgress sets the columns. This means:
- CancellationCheckProvider queries the DB for
CancellationRequested - If cancellation is requested, the junction never starts, and no progress columns are written
- If not cancelled, JunctionProgressProvider sets
CurrentlyRunningJunctionandJunctionStartedAt - The junction executes
- JunctionProgressProvider clears both columns
Requires EffectJunction
Both providers run only around junctions that inherit from EffectJunction<TIn, TOut>. See EffectJunction vs Junction.
Cancellation across servers
The cancellation check is the between-junction half of Trax's cancellation: a cancel requested on another server reaches the run as the CancellationRequested flag, read before its next junction. Stopping a run from outside explains both paths.
Dashboard Integration
When a train is InProgress, the dashboard detail page displays the current junction name and how long it has been running, drawn from the CurrentlyRunningJunction and JunctionStartedAt columns.
Performance Considerations
Junction progress adds 3 database round-trips per junction: the cancellation check reads the run's CancellationRequested flag, then one write before the junction (set CurrentlyRunningJunction) and one after (clear it). For a train with N junctions, that's N reads and at most 2N writes on top of the normal metadata saves; a write after one junction and the write before the next often share one.
The cancellation check opens a new DbContext for its read, from the data provider's connection pool. Each progress write opens one too and updates the two columns in a single statement, without loading the row.
The calls are per host: a host that does not call AddJunctionProgress() runs none of them, and its runs show no current junction and cannot be cancelled between junctions from another server.