Author and serve a machine
Source Fluent.cs, StateMachinesBuilderExtensions.cs
This builds a checkout machine (Cart, Review, Paid) whose Pay event charges a card once per order, registers
it in a host, and serves it to clients under the machines GraphQL root. What a machine is, and why the snapshot is
shaped the way it is, is in State machines.
1. Declare the machine
Subclass Machine<TState, TTrigger> over your own state and trigger enums, and declare everything in Configure:
each state's context record, each event's guard, reducer and caller rule, the committed state, and the one
irreversible effect. Mark the class [TraxMachine] to serve it to clients; an unmarked machine is reachable only from
host code.
A served machine has to be declarative (guards and reducers written as data, so it has an
IR) and user-owned, and it must declare who may do everything a
client can do: a rule on every event and on its Start, and an owner-only or stricter rule on Get, Watch and
Discard, with Watch at least as strict as Get, since the push carries what get answers. The host refuses to start, listing every gap in one exception, until it does.
using System.Text.Json.Nodes;
using Trax.Effect.Attributes;
using Trax.StateMachine;
using Trax.StateMachine.Persistence;
using static Trax.StateMachine.Rules;
public enum CheckoutState
{
Cart,
Review,
Paid,
}
public enum CheckoutTrigger
{
ChooseItems,
Next,
Back,
Pay,
}
public sealed record EmptyStart;
public sealed record CartContext
{
public List<string> Items { get; init; } = [];
}
public sealed record PaidContext
{
public List<string> Items { get; init; } = [];
public string Receipt { get; init; } = "";
}
public sealed record ItemsInput
{
public List<string> Items { get; init; } = [];
}
public sealed record PayInput
{
public string Receipt { get; init; } = "";
}
[TraxMachine]
public sealed class CheckoutMachine : Machine<CheckoutState, CheckoutTrigger>
{
private static readonly Rule HasItems = Field((CartContext c) => c.Items).CountGreaterThan(0);
protected override void Configure(IMachineBuilder<CheckoutState, CheckoutTrigger> m)
{
m.Id("checkout")
.Version(1)
.StartsAt(CheckoutState.Cart, () => new JsonObject { ["items"] = new JsonArray() })
.Start<EmptyStart>(s => s.Reduce(Keep()).AnyAuthenticated())
.Get(r => r.OwnerOnly())
.Watch(r => r.OwnerOnly())
.Discard(r => r.OwnerOnly());
m.In(CheckoutState.Cart)
.Context<CartContext>()
.On(CheckoutTrigger.ChooseItems)
.AnyAuthenticated()
.WithInput<ItemsInput>()
.Reduce(Set((CartContext c) => c.Items).FromInput((ItemsInput i) => i.Items))
.To(CheckoutState.Cart)
.On(CheckoutTrigger.Next)
.AnyAuthenticated()
.When(HasItems)
.Because("Choose an item before reviewing.")
.To(CheckoutState.Review);
m.In(CheckoutState.Review)
.Context<CartContext>()
.On(CheckoutTrigger.Back)
.AnyAuthenticated()
.To(CheckoutState.Cart)
.On(CheckoutTrigger.Pay)
.AnyAuthenticated()
.WithInput<PayInput>()
.When(All(HasItems, Input((PayInput i) => i.Receipt).NonEmpty()))
.Because("Checkout needs items and a receipt to be paid.")
.RunsOnce<ICharge>("checkout:charge")
.Reduce(Set((PaidContext c) => c.Receipt).FromInput((PayInput i) => i.Receipt))
.To(CheckoutState.Paid);
m.In(CheckoutState.Paid).Context<PaidContext>().Committed();
}
}Pay is bound to the effect, so no client fires it with a receipt: the server runs the charge and fires Pay with
the receipt the charge returned, as input["receipt"]. Paid is committed, so no save can put a draft there or take
one out. Every builder call is listed in Machine authoring,
the guard and reduction forms in the Rules vocabulary, and the
records' mapping to JSON in Context and input schemas.
2. Implement the effect
The effect is an interface over ISnapshotEffect, implemented in the host. The runner calls the overload that takes
the effect's key, which is the same for every run of one send; pass it to the system you call as its idempotency
key. The effect gets the server's stored snapshot, never the client's, so price from what the server holds.
using Trax.StateMachine;
using Trax.StateMachine.Persistence;
public interface ICharge : ISnapshotEffect;
public sealed class GatewayCharge(IPaymentGateway gateway) : ICharge
{
public Task<string> Run(Snapshot snapshot, string effectKey, CancellationToken cancellationToken)
{
var items = snapshot.Context["items"]!.AsArray().Select(i => i!.GetValue<string>()).ToList();
return gateway.Charge(items, idempotencyKey: effectKey, cancellationToken);
}
public Task<string> Run(Snapshot snapshot, CancellationToken cancellationToken = default) =>
throw new NotSupportedException("Trax runs a machine's effect with its key.");
}Return a non-empty receipt. Throwing means the charge did not happen and a retry runs it again; an
OperationCanceledException means the outcome is unknown, and the effect is taken over under the same key once its
lease passes. The details are in Effects.
3. Map the caller to a user key
Drafts are scoped by a user key, which the host supplies through ISnapshotPrincipal. Over Trax's TraxCaller:
using Trax.Api.Auth;
using Trax.StateMachine.Persistence;
public sealed class TraxCallerSnapshotPrincipal(TraxCaller caller) : ISnapshotPrincipal
{
public string? CurrentUserKey => caller.IsAuthenticated ? caller.Principal!.Id : null;
}A request with no user key is refused as UNAUTHENTICATED. Authentication itself is the host's: see
Secure a GraphQL host.
4. Register the machine in the host
AddStateMachines discovers every machine in the assemblies it is given and wires the snapshot store, the
effect-claim ledger, the run-once runner and the registry over the data provider configured in AddEffects.
Call it after AddEffects and before AddMediator. A served machine's operations are persisted documents that
carry the machine's version, so the GraphQL host must call UsePersistedOperations; a host that serves a machine
without it refuses to start.
using Trax.Api.GraphQL.Extensions;
using Trax.Api.GraphQL.PersistedOperations.Extensions;
using Trax.Effect.Data.Postgres.Extensions;
using Trax.Effect.Extensions;
using Trax.StateMachine.Persistence;
using Trax.Mediator.Extensions;
builder.Services.AddTrax(trax =>
trax.AddEffects(effects => effects.UsePostgres(connectionString))
.AddStateMachines(typeof(CheckoutMachine).Assembly)
.AddMediator(typeof(CheckoutMachine).Assembly));
builder.Services.AddScoped<ISnapshotPrincipal, TraxCallerSnapshotPrincipal>();
builder.Services.AddScoped<ICharge, GatewayCharge>();
builder.Services.AddTraxGraphQL(graphql =>
graphql.UsePersistedOperations(persisted => persisted.SingleNode()));SingleNode() suits one process; more than one node uses UseRabbitMqInvalidation(connectionString, o => o.SigningKey = key), as
Turn on persisted operations describes. Host options (draft expiry, the per-user draft
cap, the change feed) are under AddStateMachines.
The rules for which registered machines are served, and the refusals for a marked subclass or a duplicate id, are
under Serving a machine.
Persisted operations are required by default (RequirePersisted(true)), so a document sent as text, including one
typed into the GraphQL IDE at /trax/graphql, is refused with PERSISTED_OPERATION_REQUIRED; with
DisableIntrospection() the IDE cannot load the schema either.
5. Call it from a client
The machine is now machines { checkout { ... } }: start, one mutation per client event (chooseItems, next,
back), the effect event pay, discard, and the get query, each answering with the state, its typed context and
the revision, or a problem. With persisted operations required (the default), a client sends each operation by
its persisted id, which it reads from the exported client manifest at build time; the
TypeScript client does that from the machine's
documents. The chooseItems operation, written out as a document (the generated one selects every field of the
answer):
mutation ($id: UUID!, $input: ItemsInput!, $requestId: String!) {
machines { checkout { chooseItems(id: $id, input: $input, requestId: $requestId) {
id revision state context { items receipt } problem { code message } } } }
}Every refusal is a typed problem in the data, never a thrown error: GUARD_FAILED carries the Because text,
FORBIDDEN a caller the event's rule refuses, REQUEST_ID_REUSED a retry that changed its request. Fields, answers
and limits are in the machines root, and every code in
Result codes.
12. Checkout is a state machine builds one step by step and serves it. The State Machine sample is another runnable version: two machines, a GraphQL host, a run-once charge over the wire, a forward migration and a server-checked total.
Serve the generic mutations instead
A host can also serve six generic stateMachine mutations that take the machine as an argument. They are off by
default, and the opt-in requires an authorization policy:
using Trax.Effect.Data.Postgres.Extensions;
using Trax.Effect.Extensions;
using Trax.StateMachine.Persistence;
using Trax.Mediator.Extensions;
builder.Services.AddTrax(trax =>
trax.AddEffects(effects => effects.UsePostgres(connectionString))
.AddStateMachines(
o => o.ExposeGenericStateMachineMutations(g => g.Policy = "machine-clients"),
assembly)
.AddMediator(assembly));The host registers the policy with ASP.NET Core authorization, as for a train's [TraxAuthorize(Policy = ...)].
While the opt-in is on, every user-owned machine is reachable through the generic mutations, so each must declare the
same rules a marked machine does. The mutations are listed in
Generic state-machine mutations.
Keep the two runtimes in parity
A TypeScript twin and the differential corpus that proves it matches the server are generated from the machine's IR
by trax machine generate; The codegen pipeline explains both and how to
author the corpus's inputs with .Differential(...).
SDK Reference
AddStateMachines | Machine authoring | Effects | Persistence ports | Machines root | UsePersistedOperations