Pusher Protocol

Pusher protocol compatibility and message formats

Overview

Sockudo implements the Pusher Protocol v7, providing full compatibility with Pusher client libraries and APIs. This means you can use existing Pusher SDKs (JavaScript, iOS, Android, etc.) with Sockudo without modification.

Protocol Constants

PROTOCOL_VERSION: 7
ACTIVITY_TIMEOUT: 120 seconds
PONG_TIMEOUT: 30 seconds
CHANNEL_NAME_MAX_LENGTH: 200 characters
EVENT_NAME_MAX_LENGTH: 200 characters

WebSocket Connection

Connection URL

Clients connect to Sockudo using a WebSocket URL with the app key:

ws://your-server.com/app/{app_key}

For SSL/TLS:

wss://your-server.com/app/{app_key}

Connection Established

Upon successful connection, the server sends a pusher:connection_established event:

{
  "event": "pusher:connection_established",
  "data": {
    "socket_id": "1234.5678",
    "activity_timeout": 120
  }
}

The socket_id uniquely identifies this connection and is used for authentication and excluding messages from the sender.

Message Format

Base Message Structure

All messages exchanged between client and server follow this structure:

interface PusherMessage {
  event?: string;           // Event name (e.g., "pusher:subscribe")
  channel?: string;         // Channel name (optional)
  data?: MessageData;       // Payload (string or structured)
  name?: string;            // Alternative event name field
  user_id?: string;         // User identifier for presence
  tags?: Record<string, string>;  // Filtering tags (Sockudo extension)
  sequence?: number;        // Delta compression sequence (Sockudo extension)
  conflation_key?: string;  // Message grouping key (Sockudo extension)
}

Message Data Types

The data field can be:

1. String - JSON-encoded string

   {"event": "my-event", "data": "{\"message\": \"hello\"}"}
   

2. Structured - Object with specific fields

   {
     "event": "pusher:subscribe",
     "data": {
       "channel": "private-chat",
       "auth": "app_key:signature"
     }
   }
   

3. Raw JSON - Direct JSON value

   {"event": "my-event", "data": {"count": 42}}
   

Standard Events

Connection Events

pusher:connection_established Sent when client connects successfully.

pusher:error Sent when an error occurs.

{
  "event": "pusher:error",
  "data": {
    "code": 4001,
    "message": "Application does not exist"
  }
}

pusher:ping / pusher:pong Heartbeat mechanism to detect connection health.

Subscription Events

pusher:subscribe Client requests to join a channel.

{
  "event": "pusher:subscribe",
  "data": {
    "channel": "my-channel"
  }
}

pusher_internal:subscription_succeeded Server confirms successful subscription.

{
  "event": "pusher_internal:subscription_succeeded",
  "channel": "my-channel",
  "data": {}
}

pusher:unsubscribe Client leaves a channel.

{
  "event": "pusher:unsubscribe",
  "data": {
    "channel": "my-channel"
  }
}

Presence Events

pusher_internal:member_added New member joins a presence channel.

{
  "event": "pusher_internal:member_added",
  "channel": "presence-room",
  "data": {
    "user_id": "123",
    "user_info": {"name": "Alice"}
  }
}

pusher_internal:member_removed Member leaves a presence channel.

{
  "event": "pusher_internal:member_removed",
  "channel": "presence-room",
  "data": {
    "user_id": "123"
  }
}

Client Events

Clients can trigger events on private and presence channels (prefixed with client-):

{
  "event": "client-typing",
  "channel": "private-chat-room",
  "data": {"user": "Alice"}
}

Client events are only allowed on private-* and presence-* channels for security reasons.

HTTP API

Sockudo provides a REST API compatible with Pusher’s HTTP API for triggering events:

Trigger Event

POST /apps/{app_id}/events

{
  "name": "my-event",
  "channel": "my-channel",
  "data": "{\"message\": \"hello\"}",
  "socket_id": "1234.5678"  // Optional: exclude this connection
}

Batch Events

POST /apps/{app_id}/batch_events

{
  "batch": [
    {"name": "event1", "channel": "channel1", "data": "..."},
    {"name": "event2", "channel": "channel2", "data": "..."}
  ]
}

Channel Information

GET /apps/{app_id}/channels

Returns list of active channels.

GET /apps/{app_id}/channels/{channel_name}

Returns information about a specific channel:

{
  "occupied": true,
  "subscription_count": 5,
  "user_count": 3  // For presence channels
}

Presence Channel Users

GET /apps/{app_id}/channels/{channel_name}/users

{
  "users": [
    {"id": "123"},
    {"id": "456"}
  ]
}

Terminate User Connections

POST /apps/{app_id}/users/{user_id}/terminate_connections

Disconnects all connections for a specific user.

Sockudo Extensions

Sockudo adds several protocol extensions while maintaining backward compatibility:

Delta Compression

Reduce bandwidth by sending only message differences:

{
  "event": "pusher:delta",
  "channel": "ticker",
  "data": {
    "delta": "base64_encoded_delta",
    "base_seq": 10,
    "target_seq": 11,
    "algorithm": "fossil"
  }
}

Clients opt-in with:

{"event": "pusher:enable_delta_compression"}

Tag Filtering

Server-side message filtering based on tags:

// Server publishes with tags
{
  "name": "score-update",
  "channel": "match:123",
  "data": "{...}",
  "tags": {
    "event_type": "goal",
    "team": "home"
  }
}

// Client subscribes with filter
{
  "event": "pusher:subscribe",
  "data": {
    "channel": "match:123",
    "filter": {"event_type": {"eq": "goal"}}
  }
}

Cache Channels

Channels with #cache prefix support persistent data:

my-channel#cache-{ttl}

Clients receive cached data immediately upon subscription.

Error Codes

Sockudo uses standard Pusher error codes:

Code	Description
4000	Application only accepts SSL connections
4001	Application does not exist
4003	Application disabled
4004	Application over connection quota
4005	Path not found
4006	Invalid version string format
4007	Unsupported protocol version
4008	No protocol version supplied
4009	Connection is unauthorized
4100	Over capacity (slow consumer)
4200	Generic error
4201	Pong reply not received in time
4202	Closed after inactivity
4301	Client sent message too large

Protocol Validation

Channel Names

• Maximum 200 characters
• Allowed characters: a-zA-Z0-9_\-=@,.;
• Special prefixes:
  • private- - Private channels
  • presence- - Presence channels
  • private-encrypted- - End-to-end encrypted channels
  • #cache - Cache channels

Event Names

• Maximum 200 characters
• client- prefix reserved for client-triggered events
• pusher: and pusher_internal: prefixes reserved for system events

Next Steps

Channels

Learn about different channel types

Authentication

Secure private and presence channels

Client Libraries

Connect with Pusher-compatible SDKs

HTTP API

Trigger events via REST API