.NET realtime

Use Sockudo.Client for .NET realtime applications with Protocol V2, recovery, filters, deltas, and push proxy helpers.

10 min read
View .mdEdit on GitHub

Sockudo.Client is the official .NET realtime SDK for Sockudo. It keeps the Pusher subscribe/bind model, defaults to Protocol V2, and still supports Protocol V1 compatibility. It covers public, private, presence, and encrypted channels, capability tokens, connection recovery, tag filters, JSON/MessagePack/Protobuf wire formats, Fossil and Xdelta3/VCDIFF delta reconstruction, mutable messages, and push proxy helpers.

The current package (2.2.0) targets .NET 10 (net10.0). It is the realtime client: it holds only the public app key. Choose SockudoServer instead when the process needs app credentials to publish or authorize clients over HTTP.

Install

Install the published NuGet package:

Terminal window
dotnet add package Sockudo.Client --version 2.2.0

Or add it directly to your project file:

MyApp.csproj
<PackageReference Include="Sockudo.Client" Version="2.2.0" />

For local monorepo development, reference client-sdks/sockudo-dotnet/src/Sockudo.Client/Sockudo.Client.csproj directly.

Connect

A SockudoClient owns one WebSocket connection to Sockudo. Channels are named streams multiplexed over that connection: you subscribe to a channel, then bind callbacks to the event names published on it. SockudoOptions is a record whose only required argument is Cluster; pass everything else as named arguments.

Program.cs
using Sockudo.Client;
await using var client = new SockudoClient(
"app-key",
new SockudoOptions(
Cluster: "local",
ForceTls: false,
WsHost: "127.0.0.1",
WsPort: 6001,
ConnectionRecovery: true
)
);
client.Bind("state_change", (value, _) =>
{
var change = (StateChange)value!;
Console.WriteLine($"connection: {change.Previous} -> {change.Current}");
});
var channel = client.Subscribe("public-updates");
channel.Bind("price-updated", (data, meta) => Console.WriteLine(data));
await client.ConnectAsync();
await Task.Delay(TimeSpan.FromSeconds(30));
await client.DisconnectAsync();

When the server accepts the connection, the output starts with:

connection: initialized -> connecting
connection: connecting -> connected

For production, use the public ingress or load-balancer hostname with ForceTls: true. Reuse one client for the application lifetime rather than opening a WebSocket per operation. SockudoClient implements IAsyncDisposable; disposing it disconnects and releases its HttpClient.

Common options

OptionTypeDefaultDescription
ClusterstringrequiredCluster name. Must be non-empty; also used to derive default hosts.
ProtocolVersionint22 is Protocol V2. Any value below 2 uses Protocol V1 (pusher: prefixes).
ForceTlsbool?nullAnything other than false connects over wss.
WsHoststring?nullWebSocket host. Falls back to ws-<cluster>.sockudo.io.
WsPort / WssPortint80 / 443Ports for ws and wss.
EnabledTransportsIReadOnlyList<SockudoTransport>?nullRestrict to SockudoTransport.Ws and/or SockudoTransport.Wss.
ConnectionRecoveryboolfalseTrack stream positions and send a V2 resume after reconnect.
WireFormatSockudoWireFormatJsonV2 wire format: Json, MessagePack, or Protobuf.
EchoMessagesbooltrueV2: whether the server echoes this connection’s own publishes back to it.
MessageDeduplicationbooltrueDrop repeated message_id values.
MessageDeduplicationCapacityint1000Size of the deduplication window.
ActivityTimeoutTimeSpan?120 sV1 idle time before the client sends a ping.
UnavailableTimeoutTimeSpan?10 sTime without a connection before the state becomes unavailable.
MaxReconnectAttemptsint?6Reconnect attempts before giving up. null is unlimited.
MaxReconnectGapInSecondsdouble120.0Upper bound on the backoff delay.
ReconnectJitterdouble0.0Fraction of each backoff delay to randomize, clamped to 0–1.
AppendRollupWindowint?nullV2 AI append rollup window: 0, 20, 40, 100, or 500.

Subscribe and bind events

Subscribe returns the channel immediately and sends the subscription once the socket is connected. Bind returns a string token you can pass to Unbind to remove exactly that handler.

Orders.cs
var orders = client.Subscribe("orders");
orders.Bind("sockudo:subscription_succeeded", (_, _) =>
Console.WriteLine("orders is live"));
orders.Bind("sockudo:subscription_error", (error, _) =>
Console.Error.WriteLine($"orders subscription failed: {error}"));
var orderToken = orders.Bind("order.created", (data, meta) =>
Console.WriteLine($"order: {data} from user {meta?.UserId}"));
// Receive every event on the channel, for logging or reducers.
orders.BindGlobal((eventName, data) => Console.WriteLine($"{eventName} {data}"));

A connected socket can still have a pending or rejected channel. Wait for the subscription-success event before treating channel data as live. Clean up bindings and subscriptions with Unbind, UnsubscribeAsync, and DisconnectAsync:

orders.Unbind("order.created", orderToken);
await client.UnsubscribeAsync("orders");

Client events (client-*) can be sent with channel.TriggerAsync("client-typing", data) on authorized channels.

Private and presence channels

Anyone with your public app key can open a socket, so Sockudo will not let a client join a private-*, presence-*, or private-encrypted-* channel on its own say-so. Instead, the SDK asks your backend to sign the subscription. Your backend checks the caller’s session, decides whether that user may join that exact channel, and returns a signature made with the app secret. Sockudo verifies the signature before admitting the socket.

The default authorizer sends a form-encoded POST with socket_id and channel_name to ChannelAuthorization.Endpoint (default /sockudo/auth) and expects JSON with auth, plus channel_data for presence and shared_secret for encrypted channels. Use an absolute URL unless you supply an HttpClient with a BaseAddress.

Program.cs
var client = new SockudoClient(
"app-key",
new SockudoOptions(
Cluster: "local",
WsHost: "127.0.0.1",
WsPort: 6001,
ForceTls: false,
ChannelAuthorization: new ChannelAuthorizationOptions(
Endpoint: "https://api.example.com/sockudo/auth",
HeadersProvider: () => new Dictionary<string, string>
{
["Authorization"] = $"Bearer {session.AccessToken}",
}
)
)
);
var channel = client.Subscribe("private-orders");
channel.Bind("order-placed", (data, meta) => Console.WriteLine(data));
await client.ConnectAsync();

To produce the signature yourself, supply CustomHandler, which receives a ChannelAuthorizationRequest and returns ChannelAuthorizationData:

ChannelAuthorization: new ChannelAuthorizationOptions(
CustomHandler: async request =>
{
var signed = await backend.SignChannelAsync(request.SocketId, request.ChannelName);
return new ChannelAuthorizationData(
Auth: signed.Auth,
ChannelData: signed.ChannelData
);
}
)

Presence

Subscribing to a presence-* name returns a PresenceChannel. Its Members collection (Count, MyId, Me, Member(id)) is filled from the subscription-success payload and kept current as members join, leave, or update.

Lobby.cs
var presence = (PresenceChannel)client.Subscribe("presence-lobby");
presence.Bind("sockudo:subscription_succeeded", (_, _) =>
Console.WriteLine($"members: {presence.Members.Count}"));
presence.Bind("sockudo:member_added", (member, _) =>
Console.WriteLine($"joined: {member}"));
presence.Bind("sockudo:member_removed", (member, _) =>
Console.WriteLine($"left: {member}"));
presence.Bind("sockudo:presence_update", (member, _) =>
Console.WriteLine($"updated: {member}"));
await presence.UpdateAsync(new Dictionary<string, object?>
{
["status"] = "editing",
});

Protocol V2 presence data can change without a leave/rejoin cycle. UpdateAsync throws on Protocol V1.

User sign-in

Configure UserAuthenticationOptions (default endpoint /sockudo/user-auth, expecting auth and user_data) and sign in after connecting when the application uses user-targeted events or watchlists:

var client = new SockudoClient(
"app-key",
new SockudoOptions(
Cluster: "local",
WsHost: "127.0.0.1",
WsPort: 6001,
ForceTls: false,
UserAuthentication: new UserAuthenticationOptions(
Endpoint: "https://api.example.com/sockudo/user-auth"
)
)
);
await client.ConnectAsync();
await client.User.SignInAsync();

Bind user events with client.User.Bind(...) and watchlist events with client.Watchlist.Bind(...).

Capability tokens

Protocol V2 connections can carry a scoped capability token in the initial WebSocket URL. Supply a static Token, an async TokenProvider, or both:

Program.cs
var client = new SockudoClient(
"app-key",
new SockudoOptions(
Cluster: "local",
WsHost: "realtime.example.com",
ForceTls: true,
TokenAuthentication: new TokenAuthenticationOptions(
TokenProvider: cancellationToken =>
FetchSockudoTokenAsync(cancellationToken)
)
)
);
client.Bind("sockudo:auth_success", (data, _) => Console.WriteLine(data));
client.Bind("error", (error, _) =>
{
if (error is TokenExpiredException or TokenRevokedException)
{
Console.WriteLine(error);
}
});
await client.ConnectAsync();
  • When TokenProvider returns a JWT with exp, the SDK parses iat/exp without validating the signature and schedules a sockudo:auth refresh at 80% of the token lifetime. If iat is missing, the schedule is based on the current time and exp.
  • Opaque tokens, unparsable tokens, and static Token values without a provider are reactive/manual only. Call client.RefreshAuthAsync() to push a fresh token yourself.
  • On sockudo:token_expired with code 40142, the SDK calls TokenProvider and sends a refresh frame. Without a provider it raises TokenExpiredException on error.
  • Code 40160 is surfaced as TokenRevokedException with no in-place retry.

Protocol V2 features

Protocol V2 is the default in this SDK. It keeps the same channel model but attaches continuity metadata (message_id, serial, stream_id) to broadcasts and unlocks server-side filtering, deltas, rewind, and mutable messages. See Protocol V2 for the wire-level contract.

Recovery and rewind

With ConnectionRecovery: true, the client records the latest position for each channel and sends sockudo:resume after reconnecting. Rewind asks the server to replay recent history at subscribe time, by count (new SubscriptionRewind.Count(n)) or by age (new SubscriptionRewind.Seconds(n)).

Market.cs
var market = client.Subscribe(
"market:btc",
new SubscriptionOptions(Rewind: new SubscriptionRewind.Seconds(30))
);
market.Bind("sockudo:rewind_complete", (data, _) => Console.WriteLine(data));
client.Bind("sockudo:resume_success", (data, _) => Console.WriteLine(data));
client.Bind("sockudo:resume_failed", (data, _) =>
Console.WriteLine($"reload authoritative state: {data}"));

On sockudo:resume_failed, the SDK drops the stored position and delta state for that channel and resubscribes it, but your derived state may have a gap. Discard it and load a fresh snapshot.

For gap-free late-join backfills, successful subscriptions expose channel.AttachSerial when the server includes attach_serial, and channel history accepts UntilAttach:

var history = await market.ChannelHistoryAsync(
new ChannelHistoryParams(Limit: 100, UntilAttach: true)
);

ChannelHistoryAsync, GetMessageAsync, and GetMessageVersionsAsync call your VersionedMessages.Endpoint proxy.

Filters

Tag filters run on the server, so non-matching messages never reach the client. Build them with Filter (Eq, Neq, Inside, NotIn, Exists, NotExists, StartsWith, EndsWith, Contains, Gt, Gte, Lt, Lte, And, Or, Not). Event-name lists and a bounded JMESPath Expression can be combined with tags; every supplied component must match. A plain string converts to a SubscriptionExpression.

Prices.cs
var prices = client.Subscribe(
"price:btc",
new SubscriptionOptions(
Filter: Filter.And(
Filter.Eq("market", "spot"),
Filter.Gt("spread", "0")
),
Events: new[] { "price.updated" },
Expression: "data.price >= `100`"
)
);

Delta compression

Deltas shrink large, repetitive payloads by sending only the change against the previous message. Combine them with filters and bounded rewind for high-volume state feeds:

var orderBook = client.Subscribe(
"orderbook:btc-usd",
new SubscriptionOptions(
Delta: new ChannelDeltaSettings(
Enabled: true,
Algorithm: DeltaAlgorithm.Xdelta3
),
Rewind: new SubscriptionRewind.Seconds(30)
)
);
orderBook.Bind("snapshot", (data, meta) => Console.WriteLine(data));

Set DeltaCompression: new DeltaOptions(...) on SockudoOptions for OnStats and OnError callbacks, and read totals with client.GetDeltaStats(). On a missing delta base, discard derived state and load a fresh snapshot. See Filters and delta compression.

Mutable messages

Protocol V2 mutable messages arrive as sockudo:message.update, sockudo:message.delete, and sockudo:message.append. An update replaces local content with the full payload, a delete is the latest visible version and may carry null data, and an append concatenates onto the current string. Apply them in serial order:

Chat.cs
MutableMessageState? state = null;
var chat = client.Subscribe("chat:room-1");
chat.BindGlobal((eventName, data) =>
{
if (data is not SockudoEvent ev || !MutableMessageReducer.IsMutableMessageEvent(ev))
return;
try
{
state = MutableMessageReducer.ReduceMutableMessageEvent(state, ev);
Console.WriteLine($"{state.MessageSerial} {state.Action} {state.Data}");
}
catch (InvalidOperationException ex)
{
Console.Error.WriteLine($"mutable message reduction failed: {ex.Message}");
}
});

If an append arrives without a known base, fetch the latest visible version first with GetMessageAsync.

Configure VersionedMessages: new VersionedMessagesOptions(Endpoint: ...) to create and mutate messages through a trusted backend. The client posts actions such as publish_create, message_append, message_update, and message_delete; the backend signs and forwards them to the Sockudo HTTP API.

var created = await chat.CreateVersionedMessageAsync(
"chat.message",
"Hello",
new VersionedMessageCreateOptions(MessageId: "message-1")
);
await chat.AppendVersionedMessageAsync(created.MessageSerial, " world");
await chat.UpdateVersionedMessageAsync(
created.MessageSerial,
new VersionedMessageMutationOptions(Data: "Hello world!")
);
await chat.DeleteVersionedMessageAsync(created.MessageSerial);

Each call resolves to a VersionedMessageAck. See Mutable messages.

Presence history

Presence history is proxy-backed. Sockudo.Client does not sign the server REST API directly; configure PresenceHistory.Endpoint to call your own backend proxy, which signs and forwards the request to Sockudo.

LobbyHistory.cs
var client = new SockudoClient(
"app-key",
new SockudoOptions(
Cluster: "local",
WsHost: "127.0.0.1",
WsPort: 6001,
PresenceHistory: new PresenceHistoryOptions(
Endpoint: "https://api.example.com/sockudo/presence-history"
)
)
);
var lobby = (PresenceChannel)client.Subscribe("presence-lobby");
var page = await lobby.HistoryAsync(
new PresenceHistoryParams(Limit: 50, Direction: "newest_first")
);
if (page.HasNext())
{
var nextPage = await page.NextAsync();
}
var snapshot = await lobby.SnapshotAsync(new PresenceSnapshotParams(AtSerial: 4));

Proxy endpoints keep the app secret server-side. They must authenticate the caller, check channel access, bound page sizes, and forward opaque cursors. See Presence history.

Binary wire formats

Set WireFormat: SockudoWireFormat.MessagePack or SockudoWireFormat.Protobuf to negotiate a binary encoding. Both preserve byte[] message data as native binary. MessagePack uses the additive ["binary", <bin>] tagged value; existing string and JSON variants are unchanged.

Encrypted channels

private-encrypted-* channels decrypt payloads automatically using the SharedSecret returned by your auth endpoint or custom handler. Handlers receive already-decrypted data.

var docs = client.Subscribe("private-encrypted-documents");
docs.Bind("doc-updated", (data, meta) => Console.WriteLine(data));

A custom handler must populate SharedSecret (a base64-encoded 32-byte secret); without it the subscription fails with AuthFailure. Client events are not supported on encrypted channels. Keep the encryption master key on the backend and continue to use TLS.

Connection lifecycle and reconnection

The connection moves through ConnectionState values: Initialized, Connecting, Connected, Reconnecting, Unavailable, Disconnected, and Failed. Each change emits state_change with a StateChange(Previous, Current) of lowercase names, followed by an event named after the new state ("connected", "reconnecting", …). Read the current value from client.ConnectionState and the socket ID from client.SocketId.

var stateToken = client.Bind("state_change", (value, _) =>
{
var change = (StateChange)value!;
Console.WriteLine($"connection: {change.Previous} -> {change.Current}");
});
client.Bind("connected", (_, _) =>
Console.WriteLine($"socket id: {client.SocketId}"));
client.Bind("reconnecting", (_, _) =>
Console.WriteLine("reconnecting"));
await client.ConnectAsync();
// Later, during shutdown:
client.Unbind("state_change", stateToken);
await client.DisconnectAsync();

Unexpected disconnects use quadratic backoff (0s, 1s, 4s, 9s) capped at MaxReconnectGapInSeconds (120 seconds by default) and emit ConnectionState.Reconnecting. Protocol retry and TLS-upgrade close codes reconnect immediately. The default limit is six attempts; set MaxReconnectAttempts to null for unlimited retries. The counter resets after a successful connection and on explicit connect or disconnect calls. When attempts run out, the state becomes Disconnected.

var options = new SockudoOptions(
Cluster: "local",
MaxReconnectAttempts: 10,
MaxReconnectGapInSeconds: 60,
ReconnectJitter: 0.5
);

On Protocol V2, Sockudo uses native WebSocket ping/pong frames for heartbeats. .NET runtimes may still use lightweight sockudo:ping / sockudo:pong fallback messages; those are excluded from recovery metadata such as message_id, serial, and stream_id.

Error handling

All SDK exceptions derive from SockudoException.

Exception or eventRaised whenWhat to do
SockudoExceptionEmpty key or cluster at construction, invalid handshakeFix configuration.
UnsupportedFeatureToken auth or presence updates on Protocol V1, client events on encrypted channels, history or mutation helpers without a configured proxy endpointSwitch to Protocol V2, configure the endpoint, or change the call.
BadEventNameTriggerAsync with a name that does not start with client-Prefix client events with client-.
AuthFailure (StatusCode)Auth endpoint returns 4xx/5xx or omits shared_secret for an encrypted channelSurfaces as channel subscription_error with type = "AuthError". Treat 401/403 as a permission problem, not a reconnect loop.
TokenExpiredException (Code 40142)Token expired and no provider can refresh itSupply a TokenProvider or reconnect with a fresh token.
TokenRevokedException (Code 40160)Server revoked the capability tokenSign the user out or obtain new credentials.
DeltaFailure and other decode errorsA delta could not be reconstructedNot thrown to callers: the message is dropped, the error goes to DeltaOptions.OnError, and delta stats count it. Reload derived state if failures persist.
ArgumentOutOfRangeExceptionAppendRollupWindow is not an allowed valueUse 0, 20, 40, 100, or 500.

Connection-level failures, server error frames, and token errors are delivered to the client error event:

client.Bind("error", (error, _) =>
{
switch (error)
{
case TokenRevokedException revoked:
Console.Error.WriteLine($"token revoked: {revoked.Reason}");
break;
case SockudoException sockudo:
Console.Error.WriteLine($"sockudo error: {sockudo.Message}");
break;
default:
Console.Error.WriteLine($"server error: {error}");
break;
}
});

Make event processing idempotent and reload state after failed recovery. Handle auth failure, token expiry, rate limiting, and transport failure as different cases.

Platform notes

Hosting and lifetime

  • Register the client as a singleton or hosted-service dependency and dispose it during shutdown.
  • Pass cancellation tokens through long-running application operations; ConnectAsync, DisconnectAsync, and the proxy helpers accept them.
  • Keep callbacks short and move blocking work away from the receive path.
  • Protect history, mutation, and push proxy endpoints with the application’s normal authorization.
  • Test reconnects, service restarts, token rotation, and graceful host shutdown.

Push proxy helper

SockudoPushRegistration points at your backend proxy, never at Sockudo directly. Keep Sockudo app secrets on the backend. PublishAsync and PublishBatchAsync always send sync = false and should expect 202 Accepted with a publish_id; list helpers use limit and cursor.

Push.cs
var push = new SockudoPushRegistration(
new PushRegistrationOptions(
Endpoint: "https://api.example.com/sockudo/push",
Headers: new Dictionary<string, string>
{
["Authorization"] = "Bearer session-token",
}
)
);
var publish = await push.PublishAsync(
new Dictionary<string, object?>
{
["recipients"] = new[]
{
new Dictionary<string, object?> { ["type"] = "channel", ["channel"] = "orders" },
},
["payload"] = new Dictionary<string, object?>
{
["title"] = "Order updated",
["body"] = "Ready for pickup",
},
}
);
Console.WriteLine(publish["publish_id"]);
var page = await push.ListChannelSubscriptionsAsync(
new PushSubscriptionParams(DeviceId: "device-1", Limit: 20)
);
Console.WriteLine(page["next_cursor"]);

Apple Live Activities

ActivityKit runs in the iOS host and Widget Extension because its APIs use the application’s custom ActivityAttributes; from .NET (for example a .NET for iOS or MAUI app) you reach it through a small Swift binding. Sockudo.Client ships the typed pieces around it: ApnsLiveActivityTokenUpdate for uploading push-to-start and activity token rotations to your backend, and ApnsLiveActivityPublishRequest with SockudoPushRegistration.PublishLiveActivityAsync for proxies that let a user publish to their own activities.

var update = ApnsLiveActivityTokenUpdate.Activity(activityId, ApnsLiveActivityTokenUpdate.EncodeHex(tokenBytes));
await backend.ReplaceLiveActivityTokenAsync(update.ToJson());
await push.PublishLiveActivityAsync(
new ApnsLiveActivityPublishRequest(
PublishId: "ride-184-update-42",
Recipient: new ApnsLiveActivityTokenRecipient(currentActivityToken),
LiveActivity: new ApnsLiveActivityPayload(
ApnsLiveActivityEvent.Update,
Timestamp: DateTimeOffset.UtcNow.ToUnixTimeSeconds(),
ContentState: new Dictionary<string, object?> { ["status"] = "arriving", ["etaMinutes"] = 1 })));

The builders validate the same rules the server enforces (lowPower is broadcast-only, start requires attributesType, attributes, and alert, input push token and channel are mutually exclusive) and throw ArgumentException before any request is sent. Broadcast requests use ApnsLiveActivityBroadcastRecipient(channelId, ApnsChannelStoragePolicy.MostRecent).

Next steps