Protocol Overview

The Passage Platform protocol defines how workers, clients, and the session actor communicate over WebSockets.

Architecture

Worker ──ws──→ Session Actor ──ws──→ Client SDK
       ←── results ←──────────── ←── executes commands

The session actor is a stateful server-side process that acts as a relay between two WebSocket connections.

Message flow

All messages are JSON objects with a type field that determines the message kind. Messages are prefixed by their source:

• worker.* — Messages from the worker to the server
• client.* — Messages from the client SDK to the server
• server.* — Messages from the server to either worker or client

Key principles

• One command at a time — Only one command can be pending at a time
• Database is truth — All state is persisted, not held in memory
• Resumable — The session actor can be evicted and resumed transparently
• Token auth on upgrade — Authentication happens at WebSocket upgrade time

Next steps

• WebSocket Connection — How to connect
• Messages — Full message catalog