#WebSocket and SSE

Streaming sessions surface in the Stream response tab, are captured in history, and can be consumed by captures and scripts.

##Server-Sent Events (@sse)

Add # @sse to keep an HTTP request open for events:

### Notifications
# @name notifications
# @sse duration=2m idle=15s max-events=250
GET https://api.example.com/notifications

@sse accepts the following options:

If the server returns a non-2xx status or a content type other than text/event-stream, Resterm shows a normal HTTP response so you can inspect it. For a successful stream, Resterm shows the events and their details in the Stream tab and saves them in history. Templates and scripts can read eventCount, byteCount, duration, reason, error, errorClass, and dropped from the summary. A non-zero dropped value means the retained transcript is incomplete. reason has one of these values:

Reaching idle, duration, max-events, or max-bytes ends the stream without an error. The saved data includes everything read before the limit was reached. If the stream ends for any other reason, the request fails and summary.error contains the error message. Resterm still saves the transcript. A configured duration is a normal limit; an expired run deadline is a timeout failure.

##WebSockets (@websocket, @ws)

Use # @websocket to negotiate an upgrade, then describe scripted interactions with # @ws lines:

### Chat session
# @name chatSession
# @websocket timeout=10s idle-timeout=4s subprotocols=chat.v2,json compression=true
# @ws send {"type":"hello"}
# @ws wait 1s
# @ws send-json {"type":"message","text":"Hello from Resterm"}
# @ws ping heartbeat
# @ws close 1000 "client done"
GET wss://chat.example.com/room

Available WebSocket options:

Supported @ws steps:

When the handshake fails, Resterm shows the HTTP response to help you find the problem. During a successful session, events appear in the UI and history together with their direction, opcode, size, and close status. Templates and scripts can read sentCount, receivedCount, duration, closedBy, closeCode, closeReason, errorClass, and dropped from the summary. closedBy has one of these values:

error, canceled, and a timeout with an errorClass cause the request to fail. Resterm keeps the transcript in every case.

Heads-up: When you keep a WebSocket URL in @const, @global, or @var, write the request line as GET {{ws.url}} (or whichever variable you use). The parser needs the explicit method to recognise the line as a WebSocket request before template expansion. Literal ws:// / wss:// URLs without a method still work when written directly.

##Stream tab, history, and console

• The Stream tab appears automatically whenever a streaming session is active. Scroll to review frames, press b to bookmark important events, and switch tabs with the arrow keys (Ctrl+H / Ctrl+L).
• While the Stream tab is focused, use g+w then i to toggle the interactive WebSocket console, p to send ping, c to close gracefully, or l to clear the live buffer. If the console is focused for typing, press Esc first. Inside the console, cycle payload modes with F2, send payloads with Ctrl+S or Ctrl+Enter, and reuse previous payloads with the arrow keys.
• Completed transcripts are saved alongside the request in history with summary headers (X-Resterm-Stream-Type, X-Resterm-Stream-Summary). Scripts and captures can access the same data via stream.* templates and APIs (see Scripting).