Reference

UseSignalRHub

Package Trax.Effect.Broadcaster.SignalRNamespaces Trax.Effect.Broadcaster.SignalR.Extensions, Trax.Effect.Broadcaster.SignalR.Configuration.SignalRSinkOptions, Trax.Effect.Broadcaster.SignalR.ModelsSource SignalRBroadcasterExtensions.cs, SignalRSinkOptions/, Models/

Adds a SignalR sink to the broadcaster, so clients connected to the Trax hub receive train lifecycle events as they happen. It runs beside a transport such as UseRabbitMq, or on its own when the runs and the clients share a process.

Signature

public static BroadcasterBuilder UseSignalRHub(
    this BroadcasterBuilder builder,
    Action<SignalRSinkOptions>? configure = null
)

Parameters

ParameterTypeDescription
configureAction<SignalRSinkOptions>?Filters, projections and the delivery queue

Options

MethodParametersDescription
OnlyForEventsparams string[] eventTypesRestrict to listed event types (Started, Completed, Failed, Cancelled, StateChanged). Multiple calls accumulate. Without a call, every event type is allowed.
OnlyForTrains<T1>() ... <T1, T2, T3>()type parametersRestrict to listed train interface types. Stores typeof(T).FullName (the canonical identifier Trax puts on the wire), not the short name.
OnlyForTrainsparams Type[]Same as the generic overloads. Throws if any type is not an interface.
WithProjection<TClient>Func<TrainLifecycleEventMessage, TClient>Replace the default TraxClientEvent projection. Last call wins.
WithJunctionEventsnoneAlso send junction events through the "JunctionEvent" client method, without answers. Off by default.
WithJunctionAnswersnoneAs WithJunctionEvents, with each question's answer and confidence and the names and question keys of steps on a track
WithJunctionProjection<TClient>Func<TrainLifecycleEventMessage, TClient>As WithJunctionEvents, with junction events in a shape of your own. Used instead of the default payload whether WithJunctionAnswers is called before or after it. WithProjection shapes train events only.
WithDeliveryQueueCapacityint capacityHow many events may wait for delivery to clients. Default SignalRSinkOptions.DefaultDeliveryQueueCapacity (1024). Throws ArgumentOutOfRangeException below 1. See Delivery.

Returns

BroadcasterBuilder, for chaining.

Behavior

The sink is registered as both an ITrainLifecycleHook (so local-process events flow directly) and an ITrainEventHandler (so events arriving over a transport like RabbitMQ also reach connected clients). A single singleton dispatcher backs both paths. The host maps the hub with MapTraxTrainEventHub, which needs AddSignalR() and an authorization posture. Each run is handed a forwarder to the dispatcher rather than the dispatcher itself, so the end of a run, which disposes its hooks, never stops the sink. Data-change signals (DataChanged) arriving over the transport are not sent to clients.

Default projection

When WithProjection is not called, every event that passes the filters is projected to a TraxClientEvent:

FieldTypeSource
MetadataIdlongTrainLifecycleEventMessage.MetadataId
ExternalIdstringTrainLifecycleEventMessage.ExternalId
TrainNamestringTrainLifecycleEventMessage.TrainName (interface FullName)
EventTypestringStarted | Completed | Failed | Cancelled | StateChanged
TimestampDateTimeTrainLifecycleEventMessage.Timestamp
FailureReasonstring?Always null, and left off the wire

The failure reason is the text the failing code put in its exception message, and every client the hub admits receives every train's events, so the default projection does not send it. The Executor, TrainState, Output, HostName, HostEnvironment and FailureException fields on the original message are dropped too. WithProjection sends any of them. The reasoning is recorded in Trax.Effect's ADR 0017.

Sending a failure reason

FailureException carries the short type name of the exception the run recorded. Sending the reason only for a TrainException, the type a train author throws for a message meant to be read, is the rule GraphQL subscriptions apply to clients outside the operations view; the second example below does it. A subclass of TrainException reports its own type name. The SignalR Broadcaster sample uses this projection and tests both cases.

Junction events

On a host that calls AddJunctionEvents(), the sink can also send each step of a run. Without one of the three options below it sends none.

A junction event goes to the same clients as its train's events and passes the same filters: OnlyForTrains applies to it, and so does OnlyForEvents when it was called, in which case the junction event types to send (JunctionStarted, JunctionCompleted, JunctionFailed, JunctionCancelled, Decided, DecisionRefused, Routed) must be listed too.

By default each step is projected to a TraxJunctionClientEvent and sent through the "JunctionEvent" client method:

FieldTypeSource
MetadataId, ExternalId, TrainName, EventType, TimestampAs on TraxClientEvent
PositionintWhere the step falls in the run, from 0
KindstringJunction, Choice, Score, YesNo or Route
NamestringThe junction's class name, or the question's key. (withheld) for any step on a track (a junction, a question or a route) unless WithJunctionAnswers() was called, and always for one the run withheld after a [TraxSensitive] route.
StatestringInProgress, Completed, Failed or Cancelled
StartedAt, EndedAt, DurationMsWhen the step started and ended, and its duration
FailureClass, FailureExceptionstring?How a failed junction's failure is classified, and its exception's type name
QuestionKeystring?The question's key, for a question or a track. Null, and left off the wire, whenever Name is withheld.
Answer, ConfidenceNull, and left off the wire, unless WithJunctionAnswers() was called
ReplayedboolWhether the answer was replayed from an earlier run
AnswerWithheldboolTrue for a question about a [TraxSensitive] type, and for a question or route the run withheld after one
NameWithheldboolTrue when Name is withheld
TrackPositionint?For any step, the position of the route whose track it is on; left off the wire when null
NodeIdstring?The id of the declared node the step ran for. Null, and left off the wire, whenever Name is withheld.
BranchPathstring?The Parallel branch the step ran in. Left off the wire outside any branch and whenever Name is withheld.

Every client the hub admits receives every train's events, so the default payload carries no answer or confidence, and no name or question key for a step on a track, since which steps ran names the track taken. Each step's kind, position, state, timing and failure class are still sent. WithJunctionAnswers() adds the rest; answers to questions about a [TraxSensitive] type stay withheld. No payload carries an input, output or failure message. When the delivery queue is full, an incoming train event takes the place of the oldest queued junction event before it is dropped itself, so steps are given up first.

Delivery

The lifecycle hook and the event handler do not wait for clients. They apply the filters and write the event to a bounded queue, then return. One background sender takes events off the queue in the order they were raised, applies the projection, and sends each to Clients.All. A train's OnStarted, OnCompleted, OnFailed, OnCancelled and OnStateChanged therefore take the same time whether the connected clients are fast, slow or stalled.

Delivery is best effort. Clients.All waits for every connection, so a client that cannot keep up slows the sender for everyone until MapTraxTrainEventHub's send timeout disconnects it. If clients fall behind by more than the queue's capacity, further events are dropped rather than holding up trains. The first drop logs a Warning naming the capacity, and when the queue next empties a second Warning gives how many were dropped.

The dispatcher is also a hosted service. When the host stops, it stops accepting events and waits for the queued ones to be sent, within the host's shutdown timeout; whatever is left when that timeout runs out is abandoned and logged. The reasoning is recorded in Trax.Effect's ADR 0012.

Error handling

If the hub send fails for any reason (e.g. a client disconnects mid-send, a transient transport error), the background sender logs at Error level and carries on with the next event. A slow or broken client never throws out of the lifecycle hook or event handler, and never holds them up.

Examples

builder.Services.AddSignalR();
 
builder.Services.AddTrax(trax => trax
    .AddEffects(effects => effects
        .UsePostgres(connectionString)
        .UseBroadcaster(b => b
            .UseRabbitMq(rabbitMqConnectionString, opts =>
                opts.SigningKey = Convert.FromBase64String(configuration["Trax:BroadcastSigningKey"]!))
            .UseSignalRHub(opts => opts
                .OnlyForEvents("Completed", "Failed")
                .OnlyForTrains<IShipOrderTrain, IRunAuditTrain>()))
    )
    .AddMediator(typeof(IShipOrderTrain).Assembly)
);
 
var app = builder.Build();
app.UseAuthentication();
app.UseAuthorization();
app.MapTraxTrainEventHub(hub => hub.RequireAuthorization("TraxEvents"));

Clients the TraxEvents policy admits receive a TrainEvent for every Completed or Failed event of the two trains, including runs on other processes, which arrive over RabbitMQ.

A projection that sends the failure reason only for a TrainException:

using Trax.Core.Exceptions;
using Trax.Effect.Services.TrainEventBroadcaster;
 
services.AddTrax(trax => trax
    .AddEffects(effects => effects
        .UsePostgres(connectionString)
        .UseBroadcaster(b => b.UseSignalRHub(opts => opts.WithProjection(LiveTrainEvent.From)))
    )
    .AddMediator(typeof(IShipOrderTrain).Assembly)
);
 
public sealed record LiveTrainEvent(
    string ExternalId, string TrainName, string EventType, DateTime Timestamp, string? FailureReason)
{
    public static LiveTrainEvent From(TrainLifecycleEventMessage message) =>
        new(message.ExternalId, message.TrainName, message.EventType, message.Timestamp,
            message.EventType != "Failed" ? null
            : message.FailureException == nameof(TrainException) ? message.FailureReason
            : "The run failed.");
}

Junction events for one train, with a larger delivery queue:

services.AddTrax(trax => trax
    .AddEffects(effects => effects
        .UsePostgres(connectionString)
        .AddJunctionEvents()
        .UseBroadcaster(b => b.UseSignalRHub(opts => opts
            .OnlyForTrains<IShipOrderTrain>()
            .WithJunctionEvents()
            .WithDeliveryQueueCapacity(4096)))
    )
    .AddMediator(typeof(IShipOrderTrain).Assembly)
);

See also