zig runtime: real WebSocket support on current turboapi-core architecture

[justrach]

Why a replacement issue

Issue #24 was written against an older architecture and references a Rust-side websocket.rs implementation that is no longer the right baseline for current main.

TurboAPI now has:

• Python-side WebSocket API/decorator surface in python/turboapi/websockets.py
• route registration for @app.websocket(...)
• documentation that still says Zig/runtime WebSocket support is planned
• no actual Zig runtime upgrade / frame / connection implementation in the current HTTP core

This replacement issue tracks the work against the current codebase shape.

Current state

What exists:

• WebSocket and WebSocketDisconnect Python API objects
• app.websocket() registration on the Python side
• parity-style tests for decorator/API surface

What does not exist yet in the Zig runtime:

• HTTP upgrade handling in the live server path
• WebSocket frame parsing/serialization
• live connection lifecycle wiring between the server and Python callbacks
• broadcast/pub-sub/runtime connection management

Task

Transport/runtime

• detect and validate Connection: Upgrade / Upgrade: websocket requests in the Zig HTTP server path
• implement the opening handshake (Sec-WebSocket-Key / accept hash)
• add frame parsing and serialization for text, binary, ping/pong, and close frames
• handle fragmentation/limits conservatively or explicitly document unsupported cases

Python integration

• bind accepted connections to the existing Python WebSocket API surface
• support accept(), close(), send_text(), send_bytes(), send_json(), receive_*() on real runtime connections
• map disconnects and protocol errors to WebSocketDisconnect

Tests/docs

• add exact runtime tests that prove a real Zig-backed WebSocket echo/connect/disconnect path works
• update docs/WEBSOCKET.md and README once runtime support actually exists
• document what is and is not supported in the first shipped version

Non-goals for the first pass

• full pub/sub manager if basic connection support is not stable yet
• advanced extensions/compression unless explicitly implemented
• claiming production readiness before the runtime path exists and is tested

Related issues

• supersedes the stale architecture/context in Zig backend: WebSocket support #24
• keep Zig backend: HTTP/2 and TLS support #23 separate for HTTP/2 + TLS
• keep middleware/tail-latency concerns in compat: middleware stacking, streaming responses & tail latency under load #36

[justrach]

Confirmed current state on `main` (verified 2026-05-10 against `release/1.0.30`):

Python side — exists and works in-process:

• `python/turboapi/websockets.py` — `WebSocket`, `WebSocketDisconnect`, `WebSocketRoute` API surface.
• `python/turboapi/main_app.py` — `@app.websocket(path)` registration on `app._websocket_routes`.
• All 4 `TestWebSocket` API-surface tests pass after test: re-enable TestWebSocket + add SSE wire-format coverage (#146) #162 fixes them (`asyncio.run` instead of `@pytest.mark.asyncio`).

Zig side — does not exist:

• `zig/src/server.zig` has zero references to `websocket`, `Sec-WebSocket`, or `Upgrade`. No HTTP upgrade handling, no handshake, no frame layer.
• `WebSocket.send_text/.recv_text/...` push to in-process `asyncio.Queue`s that are never connected to any socket.

So the API surface tests pass, but a real client connecting to `@app.websocket("/ws")` will get a 4xx (no upgrade handshake), or possibly hang on the regular HTTP code path.

Issue #146 (user building ChatGPT-style backend) reinforces the priority — they need both real SSE (tracked in #163) AND real WebSocket. The original task list in this issue is still the right work; just flagging that the API surface is already in place and tested, so the work is purely Zig-side transport + Python↔Zig bridging.

[justrach]

End-to-end probe confirms WS is non-functional over the Zig backend. Reproducer at `/tmp/turboapi_ws_probe.py` (re-runnable).

Built a minimal app with `@app.websocket("/ws")` doing `accept(); send_text("hello"); close()`. Started on :18766. Hit with two clients in parallel.

Wire behavior — raw HTTP upgrade request (proper `Upgrade: websocket` + `Sec-WebSocket-Key` + `Sec-WebSocket-Version: 13`):

```
HTTP/1.1 404 Not Found
Server: TurboAPI
Content-Type: application/json
Content-Length: 22

{"error": "Not Found"}
```

Zig treats it as plain HTTP `GET /ws`, finds no route, returns JSON 404. The upgrade headers are silently ignored.

Wire behavior — `websockets` library v16.0:
```
websockets.exceptions.InvalidStatus: server rejected WebSocket connection: HTTP 404
```
Same 404, same root cause.

Extra finding — Python side is also incomplete, not just Zig:

• `python/turboapi/main_app.py:194-209`: `app.websocket(path)` writes the handler into `self._websocket_routes`.
• That dict is only ever assigned, never read anywhere in the codebase (verified `zigrep -n "_websocket_routes"` returns just the two assignment sites).
• Server startup prints `Total routes: 1` (only `/ping` from the test app), confirming the WS handler is never registered with the Zig router either — even if Zig had upgrade support, there's no dispatch path to reach the handler.

So the WS API surface (`@app.websocket`, `WebSocket`, `WebSocketDisconnect`) is real Python code with passing unit tests, but `_websocket_routes` is a write-only dict from a real-client perspective. The original task list in this issue is still the right work; just adds one more entry: wire `_websocket_routes` into a dispatcher that the new Zig upgrade path can call into.