Skip to content
Restura Docs

WebSocket

Restura’s WebSocket client gives you a full session viewer: every frame sent and received, with timestamps, payload type, and a search bar over the transcript.

What works

Section titled “What works”
  • Connect to ws:// and wss:// URLs.
  • Subprotocols + handshake headers — editable while disconnected (e.g. a Sec-WebSocket-Protocol such as graphql-transport-ws); the negotiated subprotocol is surfaced after the upgrade.
  • Custom headers during the upgrade — desktop only (sent natively via the main process); the browser WebSocket API can’t set upgrade headers.
  • Send text frames with the editor; auto-detects JSON for pretty printing.
  • Send binary frames — paste hex, upload a file, or use a script.
  • Auto-reconnect — backoff with jitter, configurable per session.
  • Auth on connect — Bearer, Basic, API Key, OAuth 2.0, carried as upgrade headers on desktop.
  • Ping / pong — visible in the transcript so you can verify keepalives.

Web-specific path

Section titled “Web-specific path”

The browser WebSocket API can’t set custom headers on the upgrade, and the web build currently connects directly with the browser API — so handshake headers configured in the UI are not sent on web (a system message in the transcript says so when it happens). A Worker relay (/api/ws-ticket → /api/ws) exists server-side to lift this limitation but is not wired into the renderer yet. Use the desktop app when the server requires upgrade headers.

Desktop-specific path

Section titled “Desktop-specific path”

The Electron main process opens the socket directly with the native ws library, so:

  • Custom headers go straight on the upgrade frame — no Worker ticket needed.
  • The connection is pinned to a pre-validated IP at connect time, closing the DNS-rebind window that pre-flight validation alone leaves open (see ADR 0006).
  • Redirects on the upgrade are followed.

Tips

Section titled “Tips”
  • Save a session: every send/receive is stored in history, replayable later.
  • Combine with scripts for assertions on incoming frames.
  • For Socket.IO (which is not a plain WebSocket), use the Socket.IO protocol.
Section titled “Related”
ResturaThe API client that speaks every protocol.
Built byDipjyoti MetiaGitHubMIT licensed