Skip to main content

indicatrix_net/
lib.rs

1//! Wire protocol for `indicatrix-worker`.
2//!
3//! It covers the read-only design-library sync protocol every build speaks, and
4//! (optionally) offloading `indicatrix` spectral ray-sample computation to it as a
5//! remote render worker.
6//!
7//! Types, codec, and framing, plus one small client: [`enroll::claim`] opens a
8//! `TcpStream` to a worker's enrollment listener. Everything else operates on an
9//! in-memory buffer, a `[u8]` slice, or a generic `Read`/`Write`, so the crate is
10//! testable with `std::io::Cursor`. `apps/indicatrix-worker` wires these to a real
11//! `TcpStream`/TLS connection.
12//!
13//! # The `render` feature
14//!
15//! Off by default. [`scene`] and `messages::RenderRequest`/`ClientMessage::RenderRequest`
16//! need `indicatrix`'s resolved scene/material types; everything else ([`library`],
17//! [`tls`], [`enroll`], [`token`], [`framing`], [`handshake`]) is always available,
18//! `indicatrix`-free.
19//!
20//! # The `compression` feature
21//!
22//! On by default. Adds the compressed payload encodings (`zstd`, `lz4_flex`) and the PNG
23//! display codec (`png`). Without it the crate still speaks the full protocol but only
24//! offers, accepts and decodes `PayloadEncoding::Raw` and raw RGBA8 display frames.
25//!
26//! # Why sample-index partitioning
27//!
28//! Samples are additive and order-independent, so a remote node's contribution is just
29//! more terms in the viewer's `Vec<Vec3>` sum -- no per-tile stitching needed. Work
30//! splits by SAMPLE INDEX rather than screen-space tile, since a gem only occupies part
31//! of the frame and background pixels are nearly free to trace (tile partitioning would
32//! load-balance badly). Relies on RNG seeds deriving from `hash_u32(pixel_index,
33//! sample_number)` with decorrelated per-bounce streams. Additivity against
34//! `trace_spectral_ray` itself is verified in `apps/indicatrix-worker`'s
35//! `render_core::mod` (around its partition test) and `live_split` (around its own).
36//!
37//! # Modules
38//!
39//! - [`library`]: read-only design-library sync protocol, always available.
40//! - [`scene`] (`render` feature): [`scene::SceneState`], everything a worker needs to
41//!   trace a frame's samples, fully resolved.
42//! - [`radiance`]: per-pixel `Vec<Vec3>` radiance-buffer codec, raw POD bytes via
43//!   `bytemuck` (hot path, no serialization framework), plus the v14 lossless payload
44//!   encodings (byte shuffle + zstd/LZ4) with bounded decoding.
45//! - [`display`]: the v14 8-bit picture payloads (`DISPLAY_FRAME`, `FINAL_IMAGE`), raw
46//!   RGBA8 or PNG.
47//! - [`messages`]: `HELLO`/`WELCOME` and the tagged `ClientMessage`/`StreamEvent`
48//!   families, with `postcard` encode/decode.
49//! - [`framing`]: length-prefixed message framing over any `Read`/`Write`.
50//! - [`handshake`]: build-compatibility check refusing to pair a viewer and worker
51//!   running different `indicatrix` physics.
52//! - [`tls`]: mutual-TLS config (private CA, TLS 1.3 only) plus the client-certificate
53//!   fingerprint allowlist standing in for revocation -- "may this peer talk to me",
54//!   separate from [`handshake`]'s "same physics" check. Backs both protocols.
55//! - [`client`]: viewer-side protocol driver -- `HELLO`/`WELCOME`, a handshake-only test
56//!   connection, `RenderRequest`/`CANCEL` framing, and the epoch-gated accumulator that
57//!   sums `FRAME` deltas while keeping `PREVIEW` display-only.
58//! - [`token`]: compact `GW1-...` codec for one-time worker-enrollment tokens.
59//! - [`enroll`]: enrollment wire messages and claiming client -- verifies a worker's
60//!   enrollment listener against the CA fingerprint a token commits to, then redeems it
61//!   for a certificate bundle. Shared by `indicatrix-worker`'s `cert claim` and
62//!   `indicatrix-cut`'s token-redeem UI.
63
64/// Viewer-side protocol driver -- see this doc comment's "Modules" section.
65pub mod client;
66/// The v14 8-bit picture payloads (`DISPLAY_FRAME`, `FINAL_IMAGE`) -- see this doc
67/// comment's "Modules" section.
68pub mod display;
69/// Enrollment wire messages and claiming client -- see this doc comment's "Modules"
70/// section.
71pub mod enroll;
72/// Length-prefixed message framing over any `Read`/`Write` -- see this doc comment's
73/// "Modules" section.
74pub mod framing;
75/// Build-compatibility check -- see this doc comment's "Modules" section.
76pub mod handshake;
77/// Read-only design-library sync protocol, always available -- see this doc comment's
78/// "Modules" section.
79pub mod library;
80/// `HELLO`/`WELCOME` and the tagged `ClientMessage`/`StreamEvent` families -- see this
81/// doc comment's "Modules" section.
82pub mod messages;
83/// Per-pixel radiance-buffer codec and the v14 lossless payload encodings -- see this
84/// doc comment's "Modules" section.
85pub mod radiance;
86/// [`scene::SceneState`] (`render` feature only).
87///
88/// Everything a worker needs to trace a frame's samples, fully resolved -- see this doc
89/// comment's "Modules" section.
90#[cfg(feature = "render")]
91pub mod scene;
92/// Mutual-TLS config and the client-certificate fingerprint allowlist -- see this doc
93/// comment's "Modules" section.
94pub mod tls;
95/// Compact `GW1-...` codec for one-time worker-enrollment tokens -- see this doc
96/// comment's "Modules" section.
97pub mod token;
98
99#[cfg(feature = "render")]
100pub use scene::SceneState;