Reference

.NET client

Package Trax.Client·Namespace Trax.Client·Source TraxClient.cs, TraxDocument.cs, TraxHttpTransport.cs, TraxAnswer.cs, Optional.cs, TraxJson.cs, GraphQLSubscriptionSocket.cs

Trax.Client sends a Trax host's GraphQL documents from .NET: a query or mutation as an HTTP POST, a subscription over one graphql-transport-ws socket. A document goes by the persisted id the host registered it under, or as text to a host that runs it unregistered. Every answer is a value: data, the host's errors, or a transport failure. A refusal never throws.

dotnet add package Trax.Client

It references the base class library and nothing else, so a terminal tool, a MAUI app or a Blazor WebAssembly app can take it. It is marked trimmable and AOT-compatible, and builds with the trim and AOT analyzers reporting nothing; see Trimming and native AOT for what a trimmed app passes it. The typed documents it sends are generated: trax client --operations --lang csharp writes a TraxDocument<TVariables, TResult> per document with its variables and result records, in the namespace --namespace names. Trax.StateMachine.Client posts and subscribes through this package too.

Signatures

public sealed class TraxClient
{
    public TraxClient(ITraxTransport transport, TraxClientOptions? options = null);
    public static readonly IReadOnlyList<TimeSpan> DefaultResubscribeDelays;
    public ITraxTransport Transport { get; }
 
    public Task<TraxAnswer<TResult>> SendAsync<TVariables, TResult>(
        TraxDocument<TVariables, TResult> document, TVariables variables, CancellationToken cancellationToken = default);
    public IDisposable Subscribe<TVariables, TResult>(
        TraxDocument<TVariables, TResult> document, TVariables variables, Action<TraxStreamEvent<TResult>> onEvent);
}
 
public abstract record TraxDocument(string Name, TraxOperationKind Kind, string? Id, string Text);
public sealed record TraxDocument<TVariables, TResult>(string Name, TraxOperationKind Kind, string? Id, string Text)
    : TraxDocument(Name, Kind, Id, Text);
 
public interface ITraxTransport
{
    Task<TraxAnswer> ExecuteAsync(TraxRequest request, CancellationToken cancellationToken = default);
    IDisposable Subscribe(TraxRequest request, ISubscriptionSink sink);
}
 
public sealed class TraxHttpTransport : ITraxTransport
{
    public TraxHttpTransport(TraxHttpTransportOptions options);
    public JsonObject Payload(TraxRequest request);
}
 
public sealed class GraphQLSubscriptionSocket : ISubscriptionSocket, IAsyncDisposable
{
    public GraphQLSubscriptionSocket(GraphQLSubscriptionSocketOptions options);
    public IDisposable Subscribe(JsonObject payload, ISubscriptionSink sink);
}
 
public readonly record struct Optional<T>
{
    public Optional(T value);
    public bool HasValue { get; }
    public T Value { get; }
}

Members

Sending

Documents

Answers

Transports

The socket

Behavior

• Totality. SendAsync and ExecuteAsync answer every refusal and every transport failure as a value: an unreachable host, a broken or oversized body, an answer that does not fit the result. A timeout the caller did not ask for is a Failure; a cancellation the caller asked for throws. The only other throws are SendAsync's ArgumentExceptions, for a subscription document or for variables that do not serialize to a JSON object, before anything is sent.
• By id or by text. A document with an id goes by its id unless ById says otherwise, and its text is then not sent at all. A host that requires persisted operations accepts only those. Either way the request carries operationName.
• Streams. A Subscribe stream ends for good (Ended) when the host completes it (no errors, no failure), answers a frame with errors or refuses the subscription (Errors, or a Failure when the refusal carried none), or with a Failure when it closes the socket with a 44xx code, answers the upgrade 401 or 403, sends a frame that does not fit the result, when the transport has no socket or the socket was disposed, or when onEvent throws. Anything else that drops the stream, a close, a broken connection, an unanswered ping or a malformed message, is Interrupted, said once, and the stream is subscribed again after the next of ResubscribeDelays, starting over at the first once a subscription starts. Resumed follows, before the new subscription's first Next; frames sent meanwhile are lost, so read again what the stream may have missed. Disposing the handle ends the stream and cancels a pending resubscribe.
• Optional fields. A generated variables or input record types a field the host may leave as it is as an Optional<T>, so MaxActiveJobs = null sends "maxActiveJobs": null and leaving it unset sends nothing, with TraxJson.Options or any options in TraxClientOptions.Json. Read back, a member that is absent is unset and one that is null is a null that was sent.
• Redirects. An HttpClient follows redirects by default and drops only Authorization when it does, so a default header such as X-Api-Key would follow a redirect to whatever host it names. Build the client on a handler with AllowAutoRedirect = false, as the example does; a GraphQL endpoint has no reason to redirect a POST. An answer from another scheme, host or port than the endpoint's, which is what a client that followed a redirect hands back, is a Failure rather than an answer, but by then the request has reached that host. GraphQLSubscriptionSocket follows no redirect of its upgrade either, since connection_init carries the credential: a redirected upgrade fails the connection. Outside a browser it upgrades through its own handler, so a proxy, credentials, client certificates, a certificate callback or cookies set in ConfigureSocket are moved onto that handler.

Trimming and native AOT

TraxJson.Options reads types by reflection, which a trimmed or native AOT app turns off by default, and is annotated so. Such an app passes TraxClientOptions.Json with a source-generated JsonSerializerContext as its resolver; the client adds what leaves unset Optional<T> fields out. The context lists the generated records and every T an Optional<T> wraps, since it cannot see through Optional<T>'s converter. Without one, and with reflection off, the TraxClient constructor throws ArgumentException rather than failing on the first request.

[JsonSerializable(typeof(DisableManifestVariables))]
[JsonSerializable(typeof(DisableManifestResult))]
[JsonSerializable(typeof(string))] // each T an Optional<T> wraps
internal sealed partial class ShopJson : JsonSerializerContext;
 
var client = new TraxClient(
    transport,
    new TraxClientOptions { Json = new JsonSerializerOptions(JsonSerializerDefaults.Web) { TypeInfoResolver = ShopJson.Default } }
);

Example

using System.Text.Json.Nodes;
using Trax.Client;
 
// No automatic redirects: a redirect would carry X-Api-Key to whatever host it names.
using var http = new HttpClient(new SocketsHttpHandler { AllowAutoRedirect = false });
http.DefaultRequestHeaders.Add("X-Api-Key", configuration["Trax:ApiKey"]);
 
await using var socket = new GraphQLSubscriptionSocket(
    new GraphQLSubscriptionSocketOptions
    {
        Endpoint = new Uri("wss://shop.example/trax/graphql"),
        ConnectionParams = _ =>
            ValueTask.FromResult<JsonObject?>(new JsonObject { ["apiKey"] = configuration["Trax:ApiKey"] }),
    }
);
var client = new TraxClient(
    new TraxHttpTransport(
        new TraxHttpTransportOptions
        {
            Http = http,
            Endpoint = new Uri("https://shop.example/trax/graphql"),
            Socket = socket,
        }
    )
);
 
// DisableManifest and OnTrainStateChanged are generated documents.
var answer = await client.SendAsync(Documents.DisableManifest, new DisableManifestVariables("nightly-sync"));
if (!answer.Succeeded)
    Console.WriteLine($"{answer.Code}: {answer.Message}"); // a refusal or a transport failure, never a throw
 
using var feed = client.Subscribe(
    Documents.OnTrainStateChanged,
    TraxNoVariables.Instance,
    streamEvent =>
    {
        switch (streamEvent)
        {
            case TraxStreamEvent<OnTrainStateChangedResult>.Next next:
                Console.WriteLine($"{next.Data.OnTrainStateChanged.TrainName}: {next.Data.OnTrainStateChanged.TrainState}");
                break;
            case TraxStreamEvent<OnTrainStateChangedResult>.Resumed:
                Console.WriteLine("Reconnected: read the runs again.");
                break;
        }
    }
);

See also

• Client API, the package's index.
• Persisted Operations, how a host registers the documents it accepts by id.
• .NET machine client, which drives a served machine through this package.
• trax client, which generates the typed documents.