Compatibility

Understand which Sockudo features are Pusher-compatible and which require Protocol V2 or Sockudo-native SDKs.

Sockudo's compatibility rule is simple: Protocol V1 preserves Pusher behavior; Protocol V2 adds Sockudo-native behavior.

Pusher-compatible

Feature	Compatibility
Public channels	V1 and V2
Private channels	V1 and V2
Presence channels	V1 and V2
Encrypted channels	V1 and V2 with compatible auth
HTTP publish	Pusher-compatible
Batch publish	Pusher-compatible
Channel state	Pusher-compatible
Webhook validation	Pusher-compatible shape
Laravel Echo	Use Protocol V1 / Pusher-compatible settings
pusher-js	Use Protocol V1 / Pusher-compatible settings

Sockudo-native

Feature	Requirement
`message_id`	Protocol V2
`serial` and `stream_id`	Protocol V2
Connection recovery	Protocol V2
Subscribe-time rewind	Protocol V2
Delta compression	Protocol V2 and Sockudo client SDK
Tag filtering	Protocol V2 and Sockudo client SDK
Mutable messages	Protocol V2
Annotations	Protocol V2 APIs and SDK helpers
Push management	Sockudo HTTP API and server SDK push helpers
AI Transport	Protocol V2, `ai-transport` Cargo feature, and runtime `[ai_transport]` enabled

Migration strategy

Run Pusher-compatible clients against Sockudo first.
Verify public, private, presence, encrypted, webhook, and backend publish flows.
Adopt Sockudo server SDKs where you need idempotency, history, annotations, or push.
Move selected clients to Sockudo-native SDKs and enable V2.

Push notifications are not part of the Pusher WebSocket protocol. They are Sockudo-native HTTP APIs. Existing Pusher-compatible realtime clients can still coexist with Sockudo push because push is managed by backend services and device registration flows.

AI Transport compatibility

AI Transport is additive and default-off. The server release order is:

Ship Sockudo with the ai-transport feature available but runtime-disabled by default.
Release Sockudo client SDK support after server, SDK, and conformance evidence is green.
Enable AI Transport only for V2 clients and scoped channel prefixes.

Surface	Compatibility
Protocol V1 / pusher-js canary	Must remain byte-identical with AI Transport disabled
Protocol V2 non-AI clients	Existing recovery, rewind, history, mutable messages, annotations, and push remain additive
`@sockudo/ai-transport`	Requires server AI Transport feature, runtime profile, and `@sockudo/client`
`@ably/ai-transport`	Optional `ably-compat` feature exposing the tested Ably REST and WebSocket surface, excluding Live Objects; see Ably REST, WebSocket, and AI Transport compatibility
Existing client SDKs	Full product parity depends on Protocol V2 feature enablement in each SDK
Server HTTP SDKs	Existing Pusher-compatible publish APIs continue to work; AI helpers are additive

Sockudo does not claim full Ably platform compatibility. The evidence-backed wording is Ably REST and WebSocket compatibility, excluding Live Objects. The opt-in ably-compat surface is validated against pinned Node, browser, strict-upstream-pending, and AI Transport manifests in sockudo-compatibility/. Exactly the two Live Objects files and the multiple/non-WebSocket transport file are excluded. testExcludes and the selected-lane known-failure entries are empty; upstream-default pending results are audited and executed separately, without changing their bodies, assertions, or expected values. A default-lane pass is not reported as a strict-completeness or browser pass.

The current dated evidence is not release-complete: Node defaults are green at 575 passes and AIT is 50/50, while strict completeness and all browser release lanes remain red. The authoritative counts and blockers are recorded in sockudo-compatibility/findings/2026-07-15-final-verification.md.

The implementation is isolated in crates/sockudo-ably-compat and constructed per server instance. Its realtime surface is WebSocket-only; Ably fallback transports are intentionally unsupported.

Compatibility performance evidence

Compatibility releases use two complementary guards:

make ably-compat-bench measures the production JSON/MessagePack codec, commit-envelope and history projection, error encoding, maximum 4,096-message recovery projection, and the actual subscriber registry plus bounded socket queues at 1, 100, 1,000, and 10,000 subscribers. Fanout assertions require one shared encoded buffer per active wire format.
tests/load/ably-compat/capacity-runner.mjs starts real one-node and Redis/Postgres-backed two-node topologies. The release profile covers steady and burst publish, 64 KiB and encrypted values, 1,000-subscriber fanout, 10% stalled peers, recovery, presence, append, stats, and push enqueue workloads.

Only executable result documents with a binary hash, exact config hash, evidence-harness hashes, hardware/tool metadata, latencies, throughput, resource samples, runtime counters, and zero-loss/duplicate/reordering/unexpected-delivery audits count as evidence. The driver retains exact bounded sequence bitmaps and a deterministic capped latency reservoir, never full delivered payloads. Plan output and .not-run manifests are rejected. The release guard also requires RSS to plateau under stalled peers and after disconnect, and can compare three or more independent current/baseline runs with a one-sided statistical regression test.

Release gates

Protocol-visible server PRs must pass the Protocol Change checklist and relevant fixtures for the changed surface. When protocol-owned paths change, CI also requires the sockudo-js compatibility lane because that SDK is the reference client for cross-SDK compatibility.

SDK release workflows must run their conformance lanes against both the latest released Sockudo server and server main before publishing. API-diff jobs block non-additive public API changes unless the release is intentionally major.

Rollback starts by disabling the new server feature flag. Client packages can then be pinned back independently because valid V1 and existing V2 traffic remain compatible.

GA evidence is tracked in docs/specs/ai-transport-ga-readiness.md.