Websocket Connection
Developmentwebsocket-connectionWebsocket Connection is an Agent Skill for development published in the lichtblick-suite/lichtblick repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.
Deep WebSocket connection knowledge: FoxgloveWebSocketPlayer state machine, WorkerSocketAdapter postMessage protocol, the Foxglove WebSocket protocol handshake, RAF-based state emission, and reconnection.
QUICK START
How to use this skill
Bring this guide into your coding agent with a prompt tailored to the tool you use.
- Open your project in Codex.
- Copy and paste the prompt below.
- Review files and risks before approving any action.
Prompt to paste
Inspect the Agent Skill at https://github.com/lichtblick-suite/lichtblick/blob/HEAD/.github/skills/websocket-connection/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/websocket-connection, but wait for my approval before writing files or running scripts.
Copying this prompt does not install or run the skill. Review third-party files before use.
WebSocket Connection Skill
The real-time data path from a robot/simulation/bridge to visualization.
Architecture
Foxglove WebSocket Server (robot/bridge)
│ WebSocket protocol
▼
WorkerSocketAdapter (Worker thread)
│ postMessage (raw, not Comlink)
▼
FoxgloveWebSocketPlayer (main thread)
│
▼
MessagePipeline → Panels
Core Files
| File | Role |
|---|---|
packages/suite-base/src/players/FoxgloveWebSocketPlayer/index.ts | Player implementation for WebSocket connections |
packages/suite-base/src/players/FoxgloveWebSocketPlayer/WorkerSocketAdapter.ts | Offloads WebSocket I/O to a Worker |
packages/suite-base/src/players/FoxgloveWebSocketPlayer/worker.ts | Worker-side WebSocket handling |
Foxglove WebSocket Protocol
Connection Lifecycle
- Server sends
serverInfo(capabilities, session ID) - Server sends
advertisewith available channels (topic + schema) - Client sends
subscribewith channel IDs - Server streams
messageDatabinary frames - Client can
publishmessages back to the server
Key Operations
serverInfo— server capabilities, session IDadvertise/unadvertise— channel availability (topics can appear/disappear)subscribe/unsubscribe— client topic selectionmessageData— binary message payload with channel ID + timestamptime— server clock synchronizationparameterValues— server parameters
FoxgloveWebSocketPlayer
Message Processing
- Messages arrive as binary frames via WebSocket
- Deserialized on the main thread (unlike file-based players, which decode in a Worker)
- Accumulated in a
parsedMessagesqueue - Queue flushed on
requestAnimationFrame→ emits state to the pipeline
Connection Management
- Auto-reconnect with exponential backoff
- Handles
advertise/unadvertisedynamically - Subscription changes are sent immediately to the server (no debounce)
State Emission
requestAnimationFrame-driven flush of the message queue- Coalesces all messages received between frames into one state update (max ~60 updates/sec)
- Prevents UI thrashing during high-frequency bursts
WorkerSocketAdapter
- The WebSocket connection lives in a dedicated Worker
- Avoids main-thread blocking during TLS handshake / large frame parsing
- Communicates with the main thread via raw
postMessage(not Comlink) - Binary frames are transferred (zero-copy) using
TransferableArrayBuffers
Performance Notes
- Main-thread deserialization — current limitation; high message rates can drop frames
- RAF-based flush — batches messages per animation frame
- Binary transfer —
ArrayBuffertransferred from the Worker (zero-copy) - Subscription filtering — only subscribed topics are sent → reduces bandwidth
- Backpressure — if the main thread can't keep up, messages queue in the Worker
Skills Reference
- For Worker patterns: load
web-workersskill - For deserialization of incoming frames: load
deserializationskill