feat(std.http): SSE upgrade-in-place, and the retry: field

[paul-hammant]

Two additions to std.http, both requested by the Datastar SDK port and both confirmed against their reply before building rather than inferred from reading their code.

1. response_upgrade_sse(res)

server_sse registers a whole route as SSE, so the decision is made before the request is parsed. A handler that must answer 400 on a malformed body and only then stream cannot use it:

stream, derr = events_frames(doc)
if derr != "" { respond_error(res, 400, derr); return }   // still an ordinary response
sse, err = http.response_upgrade_sse(res)                  // NOW become a stream

The Datastar port worked around this by seizing the raw socket with response_accept_tunnel.

That workaround is silently plaintext-only

http_response_accept_tunnel returns NULL when conn->ssl || conn->pure_tls — a raw std.tcp socket cannot carry TLS framing. So every SSE endpoint built that way fails the moment it is served over HTTPS, with a runtime error string rather than anything a build or test would catch. They had not spotted it; their whole conformance matrix is plain HTTP.

This upgrade writes through conn_send, the connection's own send path, so it works over TLS. Verified end-to-end against a real HTTPS server with a self-signed cert, not asserted from reading the code.

The contract question they asked

They asked what happens when the handler has already touched res, since the 400-first flow means it may have. Answered explicitly in the doc comment and enforced:

• headers set earlier are discarded — the SSE head is fixed, and a stale Content-Type/Content-Length would corrupt the stream;
• a response that already has a body is refused — that body is data the caller believes it sent, and silently dropping it would lose it.

2. sse_send_full(sse, event, data, id, retry_ms)

retry: was emitted nowhere. It is SSE's own reconnection-backoff field, so a surface writing id:/event:/data: but not retry: is incomplete rather than merely minimal — that is the reason to add it. That 5 of the Datastar port's 20 cross-SDK conformance goldens require it is corroboration, not the argument.

sse_send and sse_send_id are unchanged, passing 0 to omit the field. Order on the wire is id, event, retry, data — retry: must precede the data lines, because the blank line dispatches the event and a field after the data would land in the next one.

What they asked me not to build

• No compression coupling. They argued the negotiation strategy is SDK-specific and that a compressing upgrade call "would make the simple case easy and the Datastar case unreachable". Agreed — zlib.stream_* composes over the returned handle instead.
• No client-side SSE reader. They said their conformance suite drives the real upstream Go runner and their one streaming test reads raw bytes off a socket, so nothing wants it.

Testing

The suite asserts the four behaviours that matter: a handler answers 400 without upgrading, the upgraded response carries the fixed SSE head, retry: appears before the data lines, and upgrading over a committed body is refused.

Verified on three platforms rather than CI alone:

	build	http_sse_upgrade	http_server_sse (existing)	unit
Linux	✅	PASS	PASS	409/409
macOS 15.7.7	✅	PASS	PASS	409/409
Windows MSYS2	✅	SKIP-WIN (by design)	SKIP-WIN	397/397

The existing http_server_sse passing everywhere is the guard that the route-based path is unregressed.

Two pre-existing failures seen on those boxes, both confirmed on clean main and unrelated: http_server_h2 (HTTP/2 framing) and the Windows -lfyaml link error (#1896).

🤖 Generated with Claude Code