WebSocket Protocol

WebSocket connection protocol, message format, and lifecycle

Connection Lifecycle

The WebSocket connection follows a specific lifecycle:

Message Format

All WebSocket messages use SuperJSON encoding for type-safe serialization.

Base Event Structure

interface WebSocketEvent<T = unknown> {
  type: string
  data: T
  metadata: {
    source: MetadataEventSource
    event: {
      id: string
      parentId?: string
    }
  }
  route?: {
    destinations?: Array<string | RouteTargetExpression>
    bypass?: boolean
  }
}

type · string · required

Event type identifier (e.g., 'module:authenticate', 'ui:configure')

data · T · required

Event-specific payload data

metadata.source · MetadataEventSource · required

Source information including plugin identity

metadata.event.id · string · required

Unique event identifier for tracing

metadata.event.parentId · string

Parent event ID for request-response correlation

route.destinations · Array<string | RouteTargetExpression>

Target destinations for event routing

route.bypass · boolean

Whether to bypass routing policies (requires devtools label)

Event Types

Authentication Events

module:authenticate

Sent by client to authenticate with the server.

{
  type: 'module:authenticate',
  data: {
    token: string
  }
}

module:authenticated

Server response indicating authentication status.

{
  type: 'module:authenticated',
  data: {
    authenticated: boolean
  }
}

Module Registration

module:announce

Client announces itself to the module registry.

{
  type: 'module:announce',
  data: {
    name: string
    index?: number
    identity: MetadataEventSource
  }
}

name · string · required

Module name (must be non-empty string)

index · number

Module instance index (must be non-negative integer)

identity · MetadataEventSource · required

Module identity with plugin information

registry:modules:sync

Server broadcasts current module registry to newly connected clients.

{
  type: 'registry:modules:sync',
  data: {
    modules: Array<{
      name: string
      index?: number
      identity: MetadataEventSource
    }>
  }
}

Configuration Events

ui:configure

Sent from UI to configure a specific module.

{
  type: 'ui:configure',
  data: {
    moduleName: string
    moduleIndex?: number
    identity?: MetadataEventSource
    config: Record<string, unknown>
  }
}

The server transforms this into module:configure and routes it to the target module:

{
  type: 'module:configure',
  data: {
    config: Record<string, unknown>
  }
}

Heartbeat Events

transport:connection:heartbeat

Bidirectional heartbeat messages to maintain connection health.

{
  type: 'transport:connection:heartbeat',
  data: {
    kind: 'ping' | 'pong'
    message: MessageHeartbeat | string
    at: number  // timestamp
  }
}

kind · 'ping' | 'pong' · required

Heartbeat message type

message · MessageHeartbeat | string · required

Heartbeat message content

at · number · required

Unix timestamp in milliseconds

Error Events

error

Server error response.

{
  type: 'error',
  data: {
    message: string
  }
}

Connection Management

Peer State

The server maintains the following state for each connected peer:

interface AuthenticatedPeer {
  peer: Peer
  authenticated: boolean
  name: string
  index?: number
  identity?: MetadataEventSource
  lastHeartbeatAt: number
}

Heartbeat Timeout

Connections are automatically closed if no heartbeat is received within the configured timeout period (default: 60 seconds).

// Client should send heartbeat ping before timeout
const heartbeatInterval = setInterval(() => {
  client.send({
    type: 'transport:connection:heartbeat',
    data: {
      kind: 'ping',
      message: MessageHeartbeat.Ping,
      at: Date.now()
    }
  })
}, 30000) // Send every 30 seconds

Best Practices

Always include metadata.source

The server uses source metadata for module identification and routing. Always include complete plugin identity information.

Handle authentication properly

If the server requires authentication, wait for module:authenticated before announcing your module.

Implement heartbeat

Send heartbeat pings at regular intervals (recommended: every 30 seconds) to prevent connection timeout.

Use event IDs for tracing

Generate unique event IDs and use parentId for request-response correlation to enable end-to-end tracing.

Handle reconnection

Implement exponential backoff for reconnection attempts when connection is lost.

Error Handling

Common error scenarios:

Error Message	Cause	Solution
not authenticated	Client sent event before authentication	Wait for authentication confirmation
invalid JSON	Malformed message	Use SuperJSON for serialization
invalid token	Wrong authentication token	Verify token configuration
module not found	Target module not registered	Wait for registry sync before sending
Field validation errors	Invalid field values in events	Check field type and range requirements

Next Steps

Event System

Learn about event routing and middleware

Server SDK

Use the client SDK for easy integration