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.
Sockudo's third-party compatibility layers are community-built and community-maintained. They are not products of Pusher or Ably, and those companies do not provide support for Sockudo. Use Sockudo's project and community support channels for help.
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 compatibility
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-transportfeature 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
in two layers. Pull requests fetch the current main heads of ably-js, ably-go, and
ably-ai-transport-js, record their resolved commit IDs, and run the Node REST/WebSocket, official
Go unit and JSON/MsgPack integration, and complete AI Transport suites against the pull request.
Realtime is forced to WebSocket; Live Objects and multiple/non-WebSocket transport coverage are
excluded. Three named ably-js SDK/harness-only assertions are also excluded: the Comet inventory
and two default TLS/port checks overridden by local routing. The Go and AI Transport suites have no
test exclusions.
Pinned Node, browser, strict-upstream-pending, Go, and AI Transport manifests remain the source of reproducible release evidence. Upstream-default pending results are audited and executed separately, without changing their bodies, assertions, or expected values. A latest-upstream or default-lane pass is not reported as a strict-completeness, browser, or immutable release-evidence pass.
The current pinned source-build evidence is green: Node defaults are 575/575, strict completeness is 250/250, Chromium defaults are 574/574 with no browser-boundary errors, Chromium strict is 250/250, and AIT is 50/50. Release verification is separate: an explicit published tag must pass the checksum-verifying released-binary workflow before that tag is promoted as verified.
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-benchmeasures 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.mjsstarts 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.