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 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 |
| 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 |
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.