Trax.Mediator 1.23.1

Trax.Mediator

Dispatch station for Trax trains. Hand it the cargo and it routes it to the right train, no need to know which train handles what.

Trax is a .NET framework for writing business operations as trains: a ServiceTrain<TIn, TOut> runs a chain of junctions, and every run is recorded. Trax.Mediator adds the ITrainBus, which finds the train registered for an input's type and runs it, so callers depend on the input type rather than on a train class. It also scans assemblies to register trains, keeps the registry of known trains, enforces [TraxAuthorize] on trains, and caps concurrent runs.

dotnet add package Trax.Mediator
dotnet add package Trax.Effect.Data.InMemory   # or Trax.Effect.Data.Postgres

A minimal host: one train, registered by scanning, run through the bus.

using LanguageExt;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;
using Trax.Core.Junction;
using Trax.Effect.Data.InMemory.Extensions;
using Trax.Effect.Extensions;
using Trax.Effect.Services.ServiceTrain;
using Trax.Mediator.Extensions;
using Trax.Mediator.Services.TrainBus;

var builder = Host.CreateApplicationBuilder(args);

builder.Services.AddTrax(trax =>
    trax.AddEffects(effects => effects.UseInMemory())
        .AddMediator(mediator => mediator.ScanAssemblies(typeof(Program).Assembly))
);

using var host = builder.Build();
await host.StartAsync(); // startup checks every train's chain and refuses to start on a bad one

using var scope = host.Services.CreateScope();
var trainBus = scope.ServiceProvider.GetRequiredService<ITrainBus>();

var greeting = await trainBus.RunAsync<Greeting>(new GreetRequest("Jane"));
Console.WriteLine(greeting.Message); // Hello, Jane!

public record GreetRequest(string Name);
public record Greeting(string Message);

// Every train needs its own interface; the bus resolves the train through it.
public interface IGreetTrain : IServiceTrain<GreetRequest, Greeting>;

public class GreetTrain : ServiceTrain<GreetRequest, Greeting>, IGreetTrain
{
    protected override Task<Either<Exception, Greeting>> Junctions() =>
        Chain<BuildGreetingJunction>().Resolve();
}

public class BuildGreetingJunction : Junction<GreetRequest, Greeting>
{
    public override Task<Greeting> Run(GreetRequest input) =>
        Task.FromResult(new Greeting($"Hello, {input.Name}!"));
}

ITrainBus is scoped, so resolve it from a scope (in ASP.NET Core, inject it into a controller or endpoint). The documentation is at traxsharp.net/docs.

The Trax Stack

Trax is a layered framework split across several repos. You can stop at whatever layer solves your problem. You are here: Trax.Mediator.

Full documentation: traxsharp.net/docs.

The Problem

When one part of your system needs to send a train, it has to know exactly which train class to use. Controllers depend on concrete train types, stops that trigger other trains need direct references, and everything gets coupled together.

With TrainBus

TrainBus is a dispatch station. At startup it builds a map of what cargo goes on which train. To send something, you just drop off the cargo:

public class OrderController(ITrainBus trainBus) : ControllerBase
{
    [HttpPost]
    public async Task<IActionResult> Create(OrderRequest request)
    {
        var receipt = await trainBus.RunAsync<OrderReceipt>(request);
        return Ok(receipt);
    }
}

No reference to ProcessOrderTrain. The dispatch station looks at the cargo type and sends it on the right train.

Installation

dotnet add package Trax.Mediator

Trax.Mediator depends on Trax.Effect, which depends on Trax.Core. Both are pulled in transitively.

For tests, Trax.Mediator.Testing ships TrainGuards.EveryTrainHasInterface(assemblies), an architecture guard that lists every ServiceTrain missing its I{Name} interface:

dotnet add package Trax.Mediator.Testing

Setup

Register your train assemblies during startup. The dispatch station scans them for all IServiceTrain<TIn, TOut> implementations and builds the cargo-to-train map automatically:

builder.Services.AddTrax(trax =>
    trax.AddEffects(effects => effects.UsePostgres(connectionString))
        .AddMediator(typeof(Program).Assembly)
);

Multiple assemblies:

builder.Services.AddTrax(trax =>
    trax.AddEffects(effects => effects.UsePostgres(connectionString))
        .AddMediator(
            typeof(Program).Assembly,
            typeof(SomeTrainInAnotherProject).Assembly
        )
);

That's it. Every IServiceTrain<TIn, TOut> in those assemblies is now dispatchable through ITrainBus.

Usage

Dispatching a train

// With a return value: send cargo, get a delivery back
var user = await trainBus.RunAsync<User>(new CreateUserRequest
{
    Email = "jane@example.com",
    Name = "Jane"
});

// One-way: send cargo, no delivery expected
await trainBus.RunAsync(new SendNotificationRequest { UserId = userId });

Cancellation

var receipt = await trainBus.RunAsync<OrderReceipt>(request, cancellationToken);

The cancellation signal is forwarded to the train and all its stops.

Nested trains

A stop can dispatch another train mid-journey. The nested train records its own run, which is not linked to the outer one: the bus does not set its ParentId. Do not pass the current train's Metadata to try to link them; the metadata argument is for running as a pre-created Pending record, and a running train's metadata is refused with a TrainException.

public class SendWelcomeEmailJunction(ITrainBus trainBus) : Junction<User, Unit>
{
    public override async Task<Unit> Run(User input)
    {
        await trainBus.RunAsync(new SendEmailRequest
        {
            To = input.Email,
            Template = "welcome"
        });

        return Unit.Default;
    }
}

The departure board

The dispatch station exposes a registry of all known trains, which is useful for tooling and dashboards:

public class TrainListEndpoint(ITrainRegistry registry)
{
    public IEnumerable<string> GetTrainNames()
        => registry.InputTypeToTrain.Values.Select(t => t.Name);
}

How It Works

At startup, AddMediator scans the provided assemblies for types implementing IServiceTrain<TIn, TOut>. It builds a dictionary from cargo type (input) to train type and registers each train in the DI container. When you call RunAsync<TOut>(input), the dispatch station looks up input.GetType(), resolves the matching train from DI, and sends it on its way.

Next Layer

When you need recurring background jobs with retries and dead-lettering, move up to Trax.Scheduler.

License

MIT

Trademark & Brand Notice

Trax is an open-source .NET framework provided by TraxSharp. This project is an independent community effort and is not affiliated with, sponsored by, or endorsed by the Utah Transit Authority, Trax Retail, or any other entity using the "Trax" name in other industries.