D2: Browser terminal I/O over HTTP

[Teagan42]

Part of #2

D2 — Browser terminal I/O over HTTP

Labels: wayfinder:grilling status:closed
Blocked by: R1 (closed)
Blocks: D8

Resolution

R1 confirmed the transport is already websocket (/ws/control, /ws/terminal/{termID} via github.com/coder/websocket), xterm.js is present, and PTY resize is a text control frame — none of that changes. Spec fragment for what does change to support proxied/containerized deployment:

• Server-side keepalive — spec adding periodic websocket ping frames (server → client, 30s interval) on both /ws/control and /ws/terminal/{termID}. Prevents idle-drop through common reverse proxies (nginx default 60s, cloud proxies similar). Small change in internal/server/{server.go,terminals.go}; the existing // No WriteTimeout comment at server.go:349 remains correct — pings are frame-level, not connection-timeout.
• REST hardening — spec a ReadHeaderTimeout (e.g. 10s) on the http.Server. Minor hardening for a network-exposed service; unrelated to websockets, but this is the natural ticket to note it. No WriteTimeout or IdleTimeout — websocket handlers hijack the connection.
• Non-changes, explicit (to prevent implementers re-litigating):
  • xterm.js resize protocol: existing text control frames on /ws/terminal/{termID}. No change.
  • Reconnection: existing frontend behavior. No change.
• Reverse-proxy docs — the docs ticket (D8) should mention that operators using nginx/traefik/caddy must forward Upgrade/Connection headers; 30s server pings mean no proxy_read_timeout tuning is required.

Question

Spec the transport that carries live PTY session I/O between the container's backend and a browser tab:

• Protocol: websocket vs. SSE + POST vs. something else. Justify against reconnection, resize events, and back-pressure.
• URL/path shape (e.g. /api/sessions/:id/pty), and how session ids are minted/authorized within the single-user assumption.
• Resize/heartbeat semantics — how the frontend signals window size, how the backend detects a dead tab.
• Reuse: does the browser use the same transport the webview uses today, or does web mode get its own path? (Depends on R1.)
• xterm.js: confirm it's already in web/src (or spec adding it) and note the version pinning strategy.

Deliverable: a protocol note in the spec, tight enough that an implementer can build to it without further decisions.