3.6 KiB
iris
A sandbox screen over ONE ZAP stream. iris runs in the pod (iris attach
through the exec channel), the viewer runs in the app, and cloud's bridge
between them redeems the ticket and moves frames. No port, no page, no VNC.
| path | what |
|---|---|
schema/iris.zap |
the wire. schema/golden.txt pins Go's bytes; Rust and TS tests must match |
iris.go, iris_zap.go |
Go binding (zapgen) + framing; cloud imports github.com/hanzoai/iris |
src/ |
the daemon (Rust): cdp source = chrome-headless-shell over a pipe |
viewer/ |
@hanzo/iris: TS core (codec, credit, input) + <Screen> (web worker canvas; RN Skia) |
bench/ |
probe page + harness for the design's benchmark table |
Wire
Frame = [u32 LE 1+len][dir][body] (zap-proto/go transport). Over the
WebSocket the length is dropped: one binary message = [dir][body].
dir 3Open. body = rpc request envelope: Method 1 (Iris.watch), PromiseID = stream id, Cap = ticket (UTF-8), Payload =Hello.dir 4Msg. body =[u32 LE stream][ZAP message]; kind = header msgType (flags >> 8), numbers in the schema comments /iris.go.dir 5End. body =[u32 LE stream].
Client speaks first. The bridge allows 5 s and 4 KiB before Open, redeems Cap
(single-use, 30 s, owner-minted), strips it, and passes the frame on with the
length prefix restored. iris never sees a ticket. Any failure is Bye{Code}
then End then close: 400 bad open, 401 ticket, 404/409 sandbox, 408 slow open,
413 big open, 502 iris gone, 503 no browser.
Semantics
- Size first, then frames. Coordinates are CSS px in Size's space; Dpr ≤ 2.
- Credit. Hello.Credit is the window (viewer: 2, agent: 0). A frame is the
tiles up to
Last, and costs one credit. The viewer returnsCredit{Seq, N:1, DecodeUs}per PRESENTED frame. At 0 nothing is sent and the next frame supersedes the last (the daemon holds one JPEG, never a queue); a viewer whose credit comes back after a skip gets the latest frame. Chrome's screencast ack is withheld while no viewer holds credit, so Chrome coalesces instead of encoding. Hidden viewer = no credit = no bytes. - Sharpen. 200 ms after the last frame, one q90
Page.captureScreenshotreplaces it (TurboVNC's lossless refresh, in JPEG). - Refresh{Q} answers with one whole-screen Tile at Q, credit or not.
- Resize sets the viewport (last one wins); Size + a full frame follow.
- Input. Pointer is full state (DOM
buttons, CDP modifier bits: Alt 1, Ctrl 2, Meta 4, Shift 8). Wheel dx/dy in CSS px, DOM sign. Key = X keysym + evdev code. Commit and client Clip insert text. A client's release on disconnect: its held buttons and keys are released. - Server Clip = the page copied. Cursor.Css = the CSS cursor under the
pointer. Want{1,Many} = a file chooser opened; answer
Files{Paths}(paths in the sandbox). Point = another client's pointer. - Cdp{Id, Json}: raw CDP
{"method","params"}on the shown page (or the browser forTarget.*/Browser.*); the reply isCdp{Id, response}. Agents readAccessibility.getFullAXTree/DOMSnapshothere first and ask for pixels only with Refresh. A ticket holder already has exec, so raw CDP grants nothing new.
Daemon
iris attach joins stdio to /run/iris/sock (dir 0700), starting
iris serve if nobody answers; serve signals readiness on a pipe, never a
poll. One Chrome per pod, started on first attach, --remote-debugging-pipe
(no port), --no-sandbox (gVisor; the pod is the boundary). Exits 5 min after
the last client. All state lives on one hub thread fed by a channel; its only
timers are the sharpen and idle deadlines.