Faactory.Canonical.Client 0.1.0

Canonical Client

Client for the built-in Canonical WebSocket protocol.

await using var client = await CanonicalClient.ConnectAsync(
    new Uri( "wss://example.com/canonical" ) );

CanonicalResponse response = await client.ExecuteAsync(
    "apps.deploy",
    payload );

CanonicalResponse<DeployResponse> typedResponse =
    await client.ExecuteAsync<DeployResponse>(
        "apps.deploy",
        new DeployRequest( "app" ) );

await foreach ( CanonicalEvent evt in client.ReadAllAsync( "apps.watch", payload ) )
{
    // Handle the event.
}

await using Stream stream = await client.StreamAsync(
    "apps.logs",
    payload );

The raw API exposes payloads as JsonElement. The generic ExecuteAsync<T>() overload uses JsonSerializerOptions.Web for request and response payloads. Canonical errors throw CanonicalClientException.

ExecuteAsync() accepts responses only. ReadAllAsync() accepts events and ends at the final response. StreamAsync() exposes text and binary output through one Stream.

To configure ClientWebSocketOptions, supply a repeatable connection factory:

await using var client = await CanonicalClient.ConnectAsync(
    async cancellationToken =>
    {
        var socket = new ClientWebSocket();

        try
        {
            socket.Options.SetRequestHeader( "Authorization", token );

            await socket.ConnectAsync( uri, cancellationToken );

            return socket;
        }
        catch
        {
            socket.Dispose();

            throw;
        }
    } );

The URI and factory overloads reconnect for later requests after a connection fails. In-flight requests fail and are never replayed. Reconnection uses capped exponential delay configured through CanonicalClientOptions.

Passing one open WebSocket to the constructor disables reconnection because the client cannot replace that socket. The client always takes ownership of its sockets.

CanonicalClientOptions limits active requests, message size, unread events, and unread stream bytes. It also controls reconnection attempts and delay. A slow consumer fails only its request; it does not block the shared connection.

Transport keepalive is configured through ClientWebSocketOptions in the connection factory. There is no application-level idle timeout because a valid request may remain silent.

Cancelling a call stops the local wait. The client drains that request until its final response because the protocol has no cancellation message.