Protocol V2

Use Sockudo-native realtime semantics for recovery, rewind, deltas, filters, history, annotations, and mutable messages.

Protocol V2 is Sockudo's native protocol. It keeps the channel model familiar while adding metadata and events that are intentionally not part of Pusher compatibility mode.

Enable V2

const client = new Sockudo("app-key", {
  wsHost: "127.0.0.1",
  wsPort: 6001,
  forceTLS: false,
  protocolVersion: 2,
  connectionRecovery: true,
});

V2 metadata

V2 broadcasts can include:

Field	Purpose
`message_id`	Stable broadcast identity for deduplication.
`serial`	Stream position used for continuity.
`stream_id`	Opaque stream identity.
`extras`	Headers, tags, echo controls, idempotency metadata, and feature-specific data.

When recovery is enabled, V2 sockudo_internal:subscription_succeeded acknowledgements also include a stream_id and serial. Store that initial position even if no application events have been received yet; it lets the client resume an attached but idle channel and receive messages published during a short disconnect.

Successful V2 subscriptions may include attach_serial in sockudo_internal:subscription_succeeded when durable history is enabled for the channel. That value is the channel history head captured at attach time.

Native events

Protocol V2 uses sockudo: and sockudo_internal: prefixes for system events. Protocol V1 keeps pusher: and pusher_internal: prefixes.

Recovery contract

Recovery is authoritative only when Sockudo returns a successful resume. If the stream reset, buffer expired, or continuity cannot be proven, the client must resubscribe and rebuild state.

client.bind("sockudo:resume_success", (payload) => {
  console.log("recovered", payload.recovered);
});

client.bind("sockudo:resume_failed", (payload) => {
  console.warn("rebuild state", payload);
});

When payload.code === "position_expired", resubscribe and use channel history with until_attach: true to backfill up to the new attach serial.

Client history

V2 clients request channel history over the WebSocket with the existing channel_history action:

{
  "event": "sockudo:channel_history",
  "data": {
    "channel": "chat",
    "limit": 100,
    "direction": "backwards",
    "cursor": null,
    "until_attach": true
  }
}

The response event is sockudo:channel_history. It returns items, has_more, next_cursor, bounds, continuity, and stream_state. limit defaults to 100 and is capped at 1000. until_attach: true returns only history at or below the subscription attach_serial, so combining those items with live messages produces a gap-free view without duplicates.

Heartbeats

Protocol V2 prefers native WebSocket ping/pong frames. Browser-like runtimes may still use lightweight sockudo:ping and sockudo:pong fallback messages for liveness checks. Fallback heartbeat messages are not broadcast continuity events and do not carry message_id, serial, or stream_id.

Use cases

Use V2 for:

collaboration documents that need reconnect continuity
dashboards that benefit from deltas
market data streams with tag filters
chat systems with mutable messages and annotations
mobile apps combining realtime channels and push notifications
operators who need history and recovery visibility