Server-Sent Events (SSE)
A purpose-built viewer for text/event-stream endpoints. Connect, watch events flow in, filter by event type, and export the log.
What works
Section titled “What works”- Connect to any
text/event-streamURL. {{variables}}in the URL — autocompleted and highlighted (unresolved names are flagged). Resolved from globals, the environment, the collection and its folders at connect time.- Automatic reconnect with
Last-Event-IDresume — a dropped stream is reestablished after the server’sretry:interval and sends the last-seenid:back as theLast-Event-IDheader, so a well-behaved server can pick up where it left off. See Reconnection behavior. - Per-connection event-type filter — narrow the view to a single event name; each connection keeps its own filter.
- Freeze & export the log — freeze pauses the view while messages keep arriving (a counter shows how many are new; search and filters still apply), and export downloads the current filtered log as JSON or NDJSON (one message per line).
- Long-running session — stays open until you disconnect; capped by your platform’s connection budget.
- Per-tab streams — each tab owns its stream, and a stream keeps running while its tab is in the background. Closing a tab with a live stream asks first.
- Capped log — the log keeps the newest 1,000 events per connection; once older ones are dropped a notice shows how many. Scrolling up stops autoscroll and shows a Jump to latest pill.
- Cleartext guard — connecting over
http://with credentials configured (auth or auth headers) asks before sending them unencrypted. - Resizable config pane — the Options (N) toggle opens headers, query params, auth and the resume options (N counts what differs from a fresh request) in their own pane above the event timeline; drag the divider (or focus it and use the arrow keys) to resize. The position is remembered.
- JSON pretty-printing — when the event
data:is valid JSON. - Custom request headers + structured auth — Basic, Bearer, API Key, and OAuth 2.0 (API-key-in-query supported) applied at connect. In the CLI, external secret references on SSE items resolve like HTTP and fail the item explicitly when no resolver is available. Restura does not use the browser
EventSourceAPI — the stream is proxied through the Worker on web and over IPC on desktop, so custom headers and auth work on both platforms. A request with no auth inherits from its folder or collection. Auth or a variable stored as a keychain or external secret refuses the connection instead of connecting without it. Sign-at-wire and challenge schemes — AWS SigV4, OAuth 1.0a, WSSE, Digest, NTLM — can’t be applied to SSE, so a connection that uses one (own or inherited) is refused with a message and not made, in the app, workflows and the CLI. - Header table — bulk edit (one
key: valueper line,//to disable a row) and an optional description per row; header values resolve{{variables}}. - Code generation — the Code button copies the connection as browser
EventSource(no custom headers),fetch+ReadableStream(supports headers), orcurl -N. Headers are used as typed:{{variables}}stay unresolved and Auth-tab credentials are not included.
Reconnection behavior
Section titled “Reconnection behavior”- When an open stream ends or errors, the status changes to reconnecting and Restura reconnects after the reconnection time — 1 s by default, or the server’s last
retry:value. Each attempt is logged and counted in the Reconnect stat. - Reconnects send
Last-Event-ID: <last id seen>when “Reconnect on resume” is on (default), so a spec-compliant server replays only what you missed. The same header is sent when you click Connect again yourself. - The last event ID is tracked per the spec: an
id:persists across later events until a new one arrives, a data-less heartbeat block carrying onlyid:still moves it, and an emptyid:resets it — after which noLast-Event-IDheader is sent. - Restura does not reconnect when the server says not to: a non-2xx status,
204 No Content, or a response whoseContent-Typeisn’ttext/event-stream. A connect that fails before the stream has ever opened isn’t retried either. Network failures on a reconnect (server unreachable, or the web proxy’s own502/504while the upstream restarts) are retried. - Up to 5 consecutive reconnect attempts are made without receiving an event; after that the stream is marked disconnected. The count resets once a reconnected stream delivers an event — a server that accepts and immediately closes doesn’t reconnect forever.
- Clicking Stop cancels any pending reconnect — a deliberate stop leaves the connection closed.
- The CLI captures a stream for a fixed window and does not reconnect.
When SSE vs WebSocket
Section titled “When SSE vs WebSocket”- SSE is one-way (server → client). Perfect for log tailing, AI streaming responses, live notifications.
- WebSocket is bidirectional. Use it when the client also needs to send mid-stream.
- GraphQL subscriptions can ride either — see GraphQL.
Gotchas
Section titled “Gotchas”- Line endings — LF, CR and CRLF are all accepted, including a CRLF pair split across network packets.
retry:must be plain digits — values like1e3,0x10or-1are ignored, per spec.- Comment lines (
: ...) are ignored, per spec — servers use them as heartbeats to keep intermediaries from timing out the connection. They won’t show up as events. - Multi-line
data:fields are joined with\nbefore display — a server that splits one logical payload across severaldata:lines is reassembled, not shown as separate events. event:defaults tomessagewhen the server omits it — the event-type filter and timeline both use that default name.- Trailing data without a final blank line is dropped, matching browser
EventSourcebehavior — a stream that ends mid-event (no terminating\n\n) loses that last partial event. - Sign-at-wire auth schemes don’t apply to SSE — with AWS SigV4, OAuth 1.0a, WSSE, Digest or NTLM the connection is refused (it is not made); use header-based auth (Bearer, API key, Basic, OAuth 2.0) instead.
- Many AI providers (OpenAI, Anthropic, OpenRouter) stream completions over SSE. Restura’s AI assistant does this internally.
- Stream assertions are not available yet. In the app, each stream you start writes one History entry when it first connects (auto-reconnects don’t add more), with inline credentials and URL secrets redacted as for HTTP; SSE has no script hook, and the desktop collection runner skips SSE requests. The CLI runs SSE requests in a collection (capturing events for
--sse-durationms or until--sse-events N) and writes the captured events to the JSON report asstreamEvents, but a test script only sees the status, headers, timing and byte count — not the events.
Test it locally
Section titled “Test it locally”The local test stack serves /stream/sse (plus /stream/sse-named, /stream/sse-resume, and /stream/sse-comments for exercising named events, Last-Event-ID resume, and comment/multi-line-data parsing) off the same http://localhost:8080 the rest of the HTTP fixtures use — no auth required. Boot it with npm run echo:local (or make echo-local), then connect straight at it; the generated importable collection also includes a ready-to-send SSE request.
Related
Section titled “Related”- WebSocket
- AI assistant — uses SSE internally to stream provider responses.
- Local test stack — echo-local’s SSE routes for exercising resume and parsing edge cases.