Reference

.NET client

Package Trax.StateMachine.Client·Namespace Trax.StateMachine.Client·Source ServerMachineController.cs, IMachineServer.cs, GraphQLMachineServer.cs, GraphQLSubscriptionSocket.cs, MachinePredictor.cs

Trax.StateMachine.Client drives one instance of a machine a host serves on its typed machines root, from any .NET frontend or service: Blazor WebAssembly, .NET MAUI, Avalonia, WPF, or a service driving a machine on another host. It is the C# counterpart of the TypeScript package's ServerMachineController and createMachineServer, and it passes the same client conformance transcripts.

dotnet add package Trax.StateMachine.Client

It references Trax.StateMachine and Trax.Client, and nothing from Trax.Api, so it fits a MAUI or Blazor WebAssembly app. It sends each operation by the persisted id the host's client manifest lists, never a document of its own, so a host that requires persisted operations accepts it.

Signatures

public sealed class ServerMachineController : IDisposable
{
    public ServerMachineController(ServerMachineOptions options);
    public static readonly IReadOnlyList<TimeSpan> DefaultRetryDelays;
 
    public MachineView View { get; }
    public event EventHandler? Changed;
 
    public Task StartAsync();
    public Task<SendOutcome> SendAsync(string trigger, JsonNode? input = null);
    public Task<SendOutcome> RetryAsync();
    public bool CanSend(string trigger, JsonNode? input = null);
    public IReadOnlyList<string> AvailableTriggers();
    public void Dispose();
}
 
public sealed partial class GraphQLMachineServer : IMachineServer
{
    public GraphQLMachineServer(GraphQLMachineServerOptions options);
    public static readonly IReadOnlyList<TimeSpan> DefaultResubscribeDelays;
    public Task<ServerProblem?> DiscardAsync(string id, string requestId, CancellationToken cancellationToken = default);
}
 
public static class MachinePredictor
{
    public static IMachinePredictor FromIr(ClientManifestMachine machine);
    public static IMachinePredictor For<TState, TTrigger>(BuiltMachine<TState, TTrigger> machine)
        where TState : struct, Enum
        where TTrigger : struct, Enum;
}

Members

Driving an instance

Predicting

FromIr is the usual choice: the app needs only the manifest. It has no handler for a custom rule, so an event whose prediction depends on a custom guard, custom state requirement or custom reduction goes with no clientResult, and the view shows the server's answer when it comes rather than a guess. For suits an app that already compiles the host's machine, and custom rules then predict with their C# handlers. Without a predictor the app shows each event once the server answers it.

Talking to a host

The socket is Trax.Client's, in the namespace Trax.Client: GraphQLSubscriptionSocket, its options, the ISubscriptionSocket and ISubscriptionSink seam (Subscribe(payload, sink), and the sink's Next, Error, Complete and Started), SocketClosedException and SubscriptionErrorException. The Trax.Client reference describes them. The server subscribes with a payload of the changed document's persisted id and the instance id as its variables. A SocketClosedException whose CloseStatus is 4401 or 4403, or whose HttpStatus is 401 or 403, is the host refusing the socket: subscribing again would get the same answer, so the stream delivers Refused (UNAUTHENTICATED for 4401 and 401, FORBIDDEN for 4403 and 403, with the exception's message, which names the code) and is not subscribed again. Every other Error the socket raises, and every Complete, is a stream that ended without saying why, which it subscribes to again after ResubscribeDelays.

Behavior

The controller behaves as the TypeScript ServerMachineController does, and the client conformance kit (Trax.StateMachine/conformance/client/) holds both to the same transcripts.

• Ordering. Every snapshot, pushed or answered, carries its revision; one at or below the revision held is dropped. An answer with no revision is applied and not ordered. A push of another incarnation (the instance was deleted and created again) makes the controller read the instance again rather than compare revisions across incarnations.
• Effects. An event bound to the machine's effect is sent with no prediction, and nothing queued after it is predicted until it answers. So is an event with an edge that rests on a custom rule the predictor has no handler for.
• Timers are the server's: DueAt is shown and never fired. An answer that does not know it keeps the one held while the state stays; entering a timed state without one reads the instance once for it.
• Stopping. A gone instance, CLIENT_OUTDATED and a socket the host refused (UNAUTHENTICATED or FORBIDDEN) stop the controller for good, and every queued send settles Stopped. A snapshot the predictor cannot read stops it as CLIENT_OUTDATED too.
• Transport. An endpoint must be https (wss for the socket) unless its host is loopback (localhost, 127.0.0.0/8, ::1). Any other http or ws endpoint throws when the server or socket is built, since whatever authenticates the client would travel in cleartext; AllowInsecureTransport accepts it on a network you trust. An answer larger than MaxResponseSize fails its request as a transport failure, and a socket message larger than MaxMessageSize fails the connection, which is subscribed again; neither is read into memory first.
• Threads. The controller works on one exclusive scheduler, so it handles one thing at a time whichever thread calls it. Changed is raised there: read View and marshal to the UI thread in the handler, and do not block on the controller from it.

Example

var manifest = ClientManifest.Read(await File.ReadAllTextAsync("manifest.json"));
var turnstile = manifest.Machines.Single(m => m.Id == "turnstile");
 
await using var socket = new GraphQLSubscriptionSocket(
    new GraphQLSubscriptionSocketOptions { Endpoint = new Uri("wss://shop.example/trax/graphql") }
);
// No automatic redirects: a redirect would carry any default header but Authorization to whatever host it names.
using var http = new HttpClient(new SocketsHttpHandler { AllowAutoRedirect = false });
var server = new GraphQLMachineServer(
    new GraphQLMachineServerOptions
    {
        Http = http,
        Endpoint = new Uri("https://shop.example/trax/graphql"),
        Machine = turnstile,
        Socket = socket,
    }
);
 
using var controller = new ServerMachineController(
    new ServerMachineOptions
    {
        Machine = turnstile,
        Server = server,
        Predictor = MachinePredictor.FromIr(turnstile),
    }
);
await controller.StartAsync();
 
var outcome = await controller.SendAsync("Coin", new JsonObject { ["coin"] = "quarter" });
// SendOutcome.Confirmed when the server stored it; Refused, Failed or Stopped otherwise, never a throw

See also

• TypeScript package, the same client for a web page.
• Client manifest, where the documents come from.
• The machines root, the operations the client sends.
• Result codes, the codes every answer carries.