Realtime socket

NexusRealtimeErrorEventArgsCopy Anchor Link

class Inverge.Nexus.Realtime.NexusRealtimeErrorEventArgs

Why a realtime connection failed or dropped.

ExceptionCopy Anchor Link

Exception? Exception { get; }

The underlying exception, when there was one.

IsBillingSuspendedCopy Anchor Link

bool IsBillingSuspended { get; }

Whether the handshake was refused because the organisation's data plane is suspended for unpaid invoices.

The server reports this distinctly from a bad key precisely so a client can tell "pay the bill" apart from "fix your credentials" and stop retrying.

IsUnauthorizedCopy Anchor Link

bool IsUnauthorized { get; }

Whether the API key was rejected.

MessageCopy Anchor Link

string Message { get; }

The server's message, or the transport's.

NexusRealtimeMessageCopy Anchor Link

class Inverge.Nexus.Realtime.NexusRealtimeMessage

One message received from a realtime room.

EventNameCopy Anchor Link

string EventName { get; }

The event name the message was emitted under.

PayloadCopy Anchor Link

JsonNode? Payload { get; }

The payload, as JSON. null when the emit carried none.

RawTextCopy Anchor Link

string? RawText { get; }

The raw frame text, for when the payload will not parse as expected.

As()Copy Anchor Link

T? As<T>(JsonSerializerOptions? options = null)

Deserializes the payload into T.

Reflection-based, so a trimmed or native-AOT host should read Payload directly, or pass a options built from a source-generated context.

Parameters

Returns T?

NexusRealtimeOptionsCopy Anchor Link

class Inverge.Nexus.Realtime.NexusRealtimeOptions

How the realtime connection behaves.

NexusRealtimeOptionsCopy Anchor Link

new NexusRealtimeOptions()

AckTimeoutCopy Anchor Link

TimeSpan AckTimeout { get; set; }

How long to wait for a server acknowledgement of join, leave or emit.

ConnectionTimeoutCopy Anchor Link

TimeSpan ConnectionTimeout { get; set; }

How long to wait for the handshake.

DeviceKeyCopy Anchor Link

string? DeviceKey { get; set; }

The device key to correlate this connection with.

DistinctIdCopy Anchor Link

string? DistinctId { get; set; }

The identity to connect as, carried in the handshake.

Optional, and only used for the user-journey correlation of realtime traffic. Room membership does not depend on it.

ExtraHeadersCopy Anchor Link

IDictionary<string, string> ExtraHeaders { get; }

Extra handshake headers.

PreferWebSocketCopy Anchor Link

bool PreferWebSocket { get; set; }

Connect over WebSocket immediately rather than upgrading from long-polling.

On by default: a server-side listener has no reason to start on polling, and skipping the upgrade removes a round trip and a class of proxy-breaks-the-upgrade failure.

ReconnectionCopy Anchor Link

bool Reconnection { get; set; }

Reconnect automatically after a dropped connection.

ReconnectionAttemptsCopy Anchor Link

int ReconnectionAttempts { get; set; }

How many reconnect attempts before giving up.

ReconnectionDelayMaxCopy Anchor Link

TimeSpan ReconnectionDelayMax { get; set; }

Longest delay between reconnect attempts.

SessionKeyCopy Anchor Link

string? SessionKey { get; set; }

The session key to correlate this connection with.

StopOnBillingSuspendedCopy Anchor Link

bool StopOnBillingSuspended { get; set; }

Stop reconnecting when the server refuses the handshake with billing_suspended.

On by default, and worth leaving on. A suspension is resolved by paying an invoice, not by retrying: a client that keeps reconnecting hammers the server every few seconds for as long as the suspension lasts, and buries the one error message that would have explained it.

UrlCopy Anchor Link

string? Url { get; set; }

The Socket.IO origin. Defaults to the client's RealtimeUrl, or its API origin.

NexusRealtimeSocketCopy Anchor Link

class Inverge.Nexus.Realtime.NexusRealtimeSocket

A Socket.IO connection to the Nexus realtime plane, for receiving room traffic.

The core SDK's Realtime resource only emits. Use this when a .NET process needs to listen — a worker reacting to room traffic, a bridge into another system, a test harness.

Rooms are environment-scoped. The key you connect with must belong to the same environment that emits, or you will sit in silence that looks exactly like a bug in your handler.

Handlers registered before connecting are attached on connect, and joined rooms are re-joined after every reconnect — server-side membership does not survive one, so without that a reconnected socket goes quiet permanently.

NexusRealtimeSocketCopy Anchor Link

new NexusRealtimeSocket(INexusClient client, Action<NexusRealtimeOptions>? configure = null)

Creates a socket from a configured client.

Parameters

NexusRealtimeSocketCopy Anchor Link

new NexusRealtimeSocket(NexusOptions options, Action<NexusRealtimeOptions>? configure = null)

Creates a socket from options.

Parameters

IsConnectedCopy Anchor Link

bool IsConnected { get; }

Whether the socket is currently connected.

RoomsCopy Anchor Link

IReadOnlyCollection<string> Rooms { get; }

The rooms this socket believes it has joined.

SocketIdCopy Anchor Link

string? SocketId { get; }

The server's id for this socket, once connected.

ConnectedCopy Anchor Link

event EventHandler Connected

Raised once the handshake succeeds, including after a reconnect.

DisconnectedCopy Anchor Link

event EventHandler<string> Disconnected

Raised when the connection drops, carrying the reason.

ErrorCopy Anchor Link

event EventHandler<NexusRealtimeErrorEventArgs> Error

Raised when the server refuses the connection or reports an error.

ConnectAsync()Copy Anchor Link

Task ConnectAsync(CancellationToken cancellationToken = default)

Opens the connection. Idempotent.

Parameters

DisconnectAsync()Copy Anchor Link

Task DisconnectAsync()

Closes the connection.

DisposeAsync()Copy Anchor Link

ValueTask DisposeAsync()

Returns ValueTask

EmitAsync()Copy Anchor Link

Task<JsonNode?> EmitAsync(string room, string eventName, object? payload = null, CancellationToken cancellationToken = default)

Emits over the socket.

From a server, the HTTP client.Realtime.EmitAsync is usually the better choice: it needs no live connection and it is retried and reported like any other API call.

Parameters

Returns Task<JsonNode?>

JoinAsync()Copy Anchor Link

Task<JsonNode?> JoinAsync(string room, CancellationToken cancellationToken = default)

Joins a room. Idempotent, and re-applied automatically after a reconnect.

Parameters

Returns Task<JsonNode?>

LeaveAsync()Copy Anchor Link

Task<JsonNode?> LeaveAsync(string room, CancellationToken cancellationToken = default)

Leaves a room, and stops re-joining it on reconnect.

Parameters

Returns Task<JsonNode?>

Off()Copy Anchor Link

void Off(string eventName)

Removes every handler for an event name.

Parameters

On()Copy Anchor Link

void On(string eventName, Func<NexusRealtimeMessage, Task> handler)

Registers an async handler for an event name. Several handlers per event are allowed.

Parameters

On()Copy Anchor Link

void On(string eventName, Action<NexusRealtimeMessage> handler)

Registers a synchronous handler for an event name.

Parameters