Expand description
Wire protocol for indicatrix-worker.
It covers the read-only design-library sync protocol every build speaks, and
(optionally) offloading indicatrix spectral ray-sample computation to it as a
remote render worker.
Types, codec, and framing, plus one small client: enroll::claim opens a
TcpStream to a worker’s enrollment listener. Everything else operates on an
in-memory buffer, a [u8] slice, or a generic Read/Write, so the crate is
testable with std::io::Cursor. apps/indicatrix-worker wires these to a real
TcpStream/TLS connection.
§The render feature
Off by default. [scene] and messages::RenderRequest/ClientMessage::RenderRequest
need indicatrix’s resolved scene/material types; everything else (library,
tls, enroll, token, framing, handshake) is always available,
indicatrix-free.
§The compression feature
On by default. Adds the compressed payload encodings (zstd, lz4_flex) and the PNG
display codec (png). Without it the crate still speaks the full protocol but only
offers, accepts and decodes PayloadEncoding::Raw and raw RGBA8 display frames.
§Why sample-index partitioning
Samples are additive and order-independent, so a remote node’s contribution is just
more terms in the viewer’s Vec<Vec3> sum – no per-tile stitching needed. Work
splits by SAMPLE INDEX rather than screen-space tile, since a gem only occupies part
of the frame and background pixels are nearly free to trace (tile partitioning would
load-balance badly). Relies on RNG seeds deriving from hash_u32(pixel_index, sample_number) with decorrelated per-bounce streams. Additivity against
trace_spectral_ray itself is verified in apps/indicatrix-worker’s
render_core::mod (around its partition test) and live_split (around its own).
§Modules
library: read-only design-library sync protocol, always available.- [
scene] (renderfeature): [scene::SceneState], everything a worker needs to trace a frame’s samples, fully resolved. radiance: per-pixelVec<Vec3>radiance-buffer codec, raw POD bytes viabytemuck(hot path, no serialization framework), plus the v14 lossless payload encodings (byte shuffle + zstd/LZ4) with bounded decoding.display: the v14 8-bit picture payloads (DISPLAY_FRAME,FINAL_IMAGE), raw RGBA8 or PNG.messages:HELLO/WELCOMEand the taggedClientMessage/StreamEventfamilies, withpostcardencode/decode.framing: length-prefixed message framing over anyRead/Write.handshake: build-compatibility check refusing to pair a viewer and worker running differentindicatrixphysics.tls: mutual-TLS config (private CA, TLS 1.3 only) plus the client-certificate fingerprint allowlist standing in for revocation – “may this peer talk to me”, separate fromhandshake’s “same physics” check. Backs both protocols.client: viewer-side protocol driver –HELLO/WELCOME, a handshake-only test connection,RenderRequest/CANCELframing, and the epoch-gated accumulator that sumsFRAMEdeltas while keepingPREVIEWdisplay-only.token: compactGW1-...codec for one-time worker-enrollment tokens.enroll: enrollment wire messages and claiming client – verifies a worker’s enrollment listener against the CA fingerprint a token commits to, then redeems it for a certificate bundle. Shared byindicatrix-worker’scert claimandindicatrix-cut’s token-redeem UI.
Modules§
- client
- Viewer-side protocol driver – see this doc comment’s “Modules” section.
Viewer-side (client) protocol driver for talking to a
indicatrix-worker. - display
- The v14 8-bit picture payloads (
DISPLAY_FRAME,FINAL_IMAGE) – see this doc comment’s “Modules” section. Lossless encode/decode of the v14 8-bit picture payloads. - enroll
- Enrollment wire messages and claiming client – see this doc comment’s “Modules” section. The enrollment wire protocol, and the claiming half of token-based enrollment.
- framing
- Length-prefixed message framing over any
Read/Write– see this doc comment’s “Modules” section. Length-prefixed message framing over anyRead/Write. - handshake
- Build-compatibility check – see this doc comment’s “Modules” section. Build-compatibility verification.
- library
- Read-only design-library sync protocol, always available – see this doc comment’s “Modules” section. The read-only design-library sync protocol.
- messages
HELLO/WELCOMEand the taggedClientMessage/StreamEventfamilies – see this doc comment’s “Modules” section. The wire messages, and encode/decode for each over a length-prefixedcrate::framingstream.- radiance
- Per-pixel radiance-buffer codec and the v14 lossless payload encodings – see this doc comment’s “Modules” section. Codec for the per-frame radiance buffer.
- tls
- Mutual-TLS config and the client-certificate fingerprint allowlist – see this doc
comment’s “Modules” section.
Mutual-TLS configuration for
indicatrix-net’s transport. - token
- Compact
GW1-...codec for one-time worker-enrollment tokens – see this doc comment’s “Modules” section. Compact, phone-transcribable encoding for one-time enrollment tokens.