.NET realtime
Use Sockudo.Client for .NET realtime applications with Protocol V2, recovery, filters, deltas, and push proxy helpers.
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:
dotnet add package Sockudo.Client --version 2.2.0Or add it directly to your project file:
<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.
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 -> connectingconnection: connecting -> connectedFor 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
| Option | Type | Default | Description |
|---|---|---|---|
Cluster | string | required | Cluster name. Must be non-empty; also used to derive default hosts. |
ProtocolVersion | int | 2 | 2 is Protocol V2. Any value below 2 uses Protocol V1 (pusher: prefixes). |
ForceTls | bool? | null | Anything other than false connects over wss. |
WsHost | string? | null | WebSocket host. Falls back to ws-<cluster>.sockudo.io. |
WsPort / WssPort | int | 80 / 443 | Ports for ws and wss. |
EnabledTransports | IReadOnlyList<SockudoTransport>? | null | Restrict to SockudoTransport.Ws and/or SockudoTransport.Wss. |
ConnectionRecovery | bool | false | Track stream positions and send a V2 resume after reconnect. |
WireFormat | SockudoWireFormat | Json | V2 wire format: Json, MessagePack, or Protobuf. |
EchoMessages | bool | true | V2: whether the server echoes this connection’s own publishes back to it. |
MessageDeduplication | bool | true | Drop repeated message_id values. |
MessageDeduplicationCapacity | int | 1000 | Size of the deduplication window. |
ActivityTimeout | TimeSpan? | 120 s | V1 idle time before the client sends a ping. |
UnavailableTimeout | TimeSpan? | 10 s | Time without a connection before the state becomes unavailable. |
MaxReconnectAttempts | int? | 6 | Reconnect attempts before giving up. null is unlimited. |
MaxReconnectGapInSeconds | double | 120.0 | Upper bound on the backoff delay. |
ReconnectJitter | double | 0.0 | Fraction of each backoff delay to randomize, clamped to 0–1. |
AppendRollupWindow | int? | null | V2 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.
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.
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.
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:
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
TokenProviderreturns a JWT withexp, the SDK parsesiat/expwithout validating the signature and schedules asockudo:authrefresh at 80% of the token lifetime. Ifiatis missing, the schedule is based on the current time andexp. - Opaque tokens, unparsable tokens, and static
Tokenvalues without a provider are reactive/manual only. Callclient.RefreshAuthAsync()to push a fresh token yourself. - On
sockudo:token_expiredwith code40142, the SDK callsTokenProviderand sends a refresh frame. Without a provider it raisesTokenExpiredExceptiononerror. - Code
40160is surfaced asTokenRevokedExceptionwith 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)).
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.
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:
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.
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 event | Raised when | What to do |
|---|---|---|
SockudoException | Empty key or cluster at construction, invalid handshake | Fix configuration. |
UnsupportedFeature | Token auth or presence updates on Protocol V1, client events on encrypted channels, history or mutation helpers without a configured proxy endpoint | Switch to Protocol V2, configure the endpoint, or change the call. |
BadEventName | TriggerAsync 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 channel | Surfaces 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 it | Supply a TokenProvider or reconnect with a fresh token. |
TokenRevokedException (Code 40160) | Server revoked the capability token | Sign the user out or obtain new credentials. |
DeltaFailure and other decode errors | A delta could not be reconstructed | Not thrown to callers: the message is dropped, the error goes to DeltaOptions.OnError, and delta stats count it. Reload derived state if failures persist. |
ArgumentOutOfRangeException | AppendRollupWindow is not an allowed value | Use 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.
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).