Files
faunosteo/docs/development/RUST.md
T

16 KiB
Raw Blame History

Rust in the Faunosteo monorepo

Status: plan R0 (foundation), 2026-10-12, on feature/rust-r0-foundation. Rule and roadmap: RUST_ARCHITECTURE_REVIEW.md (rule "Rust by default", Part III boundary rules, Part VI phases R0–R5, Annex B R0 scope, Annex C owner amendments). R0 ships the toolchain, the workspace skeleton, the worker's sandboxed child, the browser module loader and seven experimental proofs. No application behaviour, interface, archive or database changes; the frontend does not load the module before R2; the worker's job loop arrives at R1.

1. Toolchain: reproducible in Docker, never on the VPS

Every cargo command runs inside the reference builder image, so CI and a developer machine use the same compiler and the production VPS never needs Rust (images are built in CI and pulled by digest, DEPLOY.md "Image deploy by digest").

Piece Where Pinned by
Rust 1.99.0, edition 2024, rustfmt, clippy, wasm32-unknown-unknown docker/rust-builder.Dockerfile (FROM rust:1.99.0-bookworm) rust-toolchain.toml (same channel; a difference would make rustup download inside the container)
wasm-bindgen-cli 0.2.129 same image wasm-bindgen = "=0.2.129" in Cargo.toml; docker/wasm-build.sh refuses to run when Cargo.lock and the CLI differ
cargo-deny 0.20.2 same image deny.toml
worker builder crates/worker/Dockerfile (FROM rust:1.99.0-alpine3.24, build-base for libwebp) same channel

Commands (root package.json):

pnpm rust:builder   # builds faunosteo_rust_builder:1.99.0 once (about 6 minutes cold)
pnpm rust:check     # docker/rust-check.sh: fmt --check, clippy -D warnings (all targets),
                    # cargo test (core, wasm), ts-rs export, cargo deny licenses/bans/sources
pnpm wasm:build     # crates/wasm → packages/core-wasm/pkg (git-ignored), prints raw and gzip sizes
pnpm worker:test    # crates/worker/Dockerfile stage test: 13 sandbox tests + seccomp derivation
pnpm worker:image   # runtime image faunosteo_worker:dev (distroless/static:nonroot)
bash docker/rust-run.sh cargo <anything>   # any cargo command in the builder

docker/rust-run.sh mounts the repository at /w and keeps Cargo's registry and the target directory in the named volumes faunosteo_cargo_registry and faunosteo_rust_target (incremental builds take seconds). A local rustup is optional for the inner loop (same rust-toolchain.toml); the container is the arbiter.

2. Workspace

Cargo.toml              workspace (resolver 3), pinned [workspace.dependencies], lints, profiles
rust-toolchain.toml     channel 1.99.0, components rustfmt + clippy
rustfmt.toml            edition 2024, max_width 100
clippy.toml             disallowed-methods: std::time::*::now, std::fs::*, std::env::var* (the core)
deny.toml               licences allow-list, bans (duplicates warn, wildcards deny, path deps allowed), sources
.cargo/config.toml      wasm shadow stack 1 MiB (explicit), TS_RS_EXPORT_DIR = packages/core-wasm/types
crates/core             faunosteo-core: lib, no I/O (lint), serde + serde_json only
crates/wasm             faunosteo-wasm: cdylib facade over core (wasm-bindgen)
crates/worker           faunosteo-worker: bin + lib (image, libwebp-sys, seccompiler, rlimit)
packages/core-wasm      loader, generated types (committed), vitest proofs

Lints: unwrap_used, expect_used and disallowed_methods are errors in the libraries (tests allow them explicitly at the top of the file); unsafe_code is forbidden everywhere except the worker (libwebp FFI, each block with a SAFETY comment). Dependencies are optimised even in debug builds (profile.dev.package."*") because the sandbox tests decode 4096² images under a 10 s CPU limit.

2.1 Boundary rules in code (review III.3)

  • faunosteo_core::facade::call(op, json) -> json: one operation name, one JSON text in, the outcome envelope out ({"ok":true,"value":…} or {"ok":false,"kind":…,"detail":…}), never a panic on content. R0 ops: core_version, pretty_json, sheet_ref, report_zone.
  • faunosteo_core::json: js_number(f64) prints floats as ECMAScript Number::toString; JsPrettyFormatter is serde_json's pretty formatter with that rule; to_js_pretty and pretty_js_round_trip produce JSON.stringify(v, null, 2) byte for byte (proof §5.2).
  • faunosteo_core::domain::report: SheetRef, ReportZone, Vertebra, LateralSide, Unresolved, field order of the Zod schemas, optional fields skip_serializing_if = "Option::is_none", nullable fields plain Option, unknown keys ignored where Zod strips them. cargo test -p faunosteo-core --features ts writes the TypeScript types to packages/core-wasm/types (committed; CI fails on drift).
  • packages/core-wasm/src/index.ts: loadCore() instantiates a fresh module each time (cache-busting import of the glue), callCore() parses the envelope, isCoreBuilt() lets the proofs skip when pkg/ is absent.

3. The worker (R0 skeleton, R1 job loop)

faunosteo-worker is one static musl binary with subcommands dispatched by a plain main (no async runtime, no thread), so decode installs its sandbox in a single-threaded process:

  • decode: refuses a non-empty environment; checks Threads: 1 in /proc/self/status; disables core dumps (PR_SET_DUMPABLE 0, RLIMIT_CORE 0: a dump would hold the uploaded photo); RLIMIT_AS 512 MiB, RLIMIT_CPU 10 s soft / 12 s hard (soft = hard made the kernel SIGKILL first, finding §5.4); seccomp allowlist installed with TSYNC, KillProcess on anything else, with argument filters: tkill/tgkill may only send SIGABRT to the child's own pid (never a signal to the keyed parent or a sibling), mmap may not map PROT_EXEC; then reads ≤ 5 MiB on stdin, sniffs the format (JPEG, PNG, WebP), decodes with image::Limits (sides ≤ 4096, alloc 256 MiB), applies the EXIF orientation, resize_to_fill 512 × 512, encodes lossy WebP (q 82) through libwebp-sys (C, this process only), writes stdout. Exit codes in exit_codes.rs (10–18, never 1, 101 or a signal number).
  • the parent side (spawn::Spawner, used by the tests now and by R1): env_clear, stdin/stdout/stderr piped, output read up to 512 KiB (the child is killed past it), 20 s deadline, classification of every exit (Produced, Rejected{code} for the content codes 12 to 17, Broken{code} when the child could not even start (usage, non-empty environment, sandbox failure, internal: R1 alerts instead of blaming the upload), Signalled{signal}, OutputOverflow, Timeout, Failed). The parent never decodes: webp_check::inspect parses the RIFF container only (chunk allowlist VP8X, VP8 , VP8L, ALPH; canvas size from the headers, the frame size must agree with the canvas; any EXIF, XMP , ICCP or unknown chunk refuses the output; owner amendment of D-R4). The child's stderr (≤ 4 KiB) is child-controlled text: R1 never logs it raw (LRN-044).
  • run --check: prints the resolved configuration without secrets (which variables are set, the linked libwebp version, refused below 1.6.0). A plain run does nothing before R1 and says so.
  • version: binary, workspace and libwebp versions.
  • test hooks (--features test-hooks, never in a release build): fixtures generated in memory (no binary in git), --no-seccomp (rlimits only, prints the SECCOMP-MARKER line for the strace derivation), --violate (getcwd after the filter), --flood, --alloc-gib n, --spin, print-allowlist.

Image: crates/worker/Dockerfile, stages build (release, static), test (sandbox tests and scripts/derive-seccomp.sh on the release profile with the test-hooks feature, so the binary under test differs from the shipped one by the feature-gated hooks only), runtime (gcr.io/distroless/static-debian12:nonroot, USER nonroot, ENTRYPOINT /faunosteo-worker, CMD run --check). Measured 2026-10-12: image 8.7 MB (one static binary), run --check exits 0 with --read-only --cap-drop ALL --security-opt no-new-privileges:true.

4. CI

  • Job rust (before check): builds the builder image, runs docker/rust-check.sh, checks the committed ts-rs types for drift, builds the browser module (size printed).
  • Job check: builds the module the same way, then the existing Node pipeline; the core-wasm proofs run because pkg/ exists.
  • Job docker: application image, worker test stage (sandbox tests and seccomp derivation on the musl binary that ships), worker runtime image started once with --read-only --cap-drop ALL.
  • rust-advisories.yml: nightly and manual cargo deny check advisories, out of the blocking path on purpose.
  • release-images.yml: manual only, on main or develop; the dispatch input is a typed choice re-validated through an environment variable; the RustSec advisories gate runs first; an ephemeral buildx builder with its own cache builds the images (nothing a PR build left in the daemon's cache mounts or volumes can reach a release image); secrets reach the shell through env only, the login lives in a per-job DOCKER_CONFIG removed at the end; actions/checkout pinned to a commit. It pushes faunosteo_app:<sha> and faunosteo_worker:<sha> and prints their digests. Deploys nothing (DEPLOY.md "Image deploy by digest").

Not measured here: the forge runner's cache behaviour and cold build times (the runner was not available from this host). The builder image build took about 6 minutes cold on the development host; both image builds reuse BuildKit cache mounts (faunosteo_cargo_registry_musl, faunosteo_target_musl).

5. R0 proofs (2026-10-12, development host, Docker 29.8 rootless, kernel 7.0)

Each proof is a permanent test; the numbers are what the run produced.

5.1 Panic strategy on wasm32 (packages/core-wasm/tests/panic.test.ts)

  • A Rust panic reaches JavaScript as WebAssembly.RuntimeError (unreachable): the module is panic = abort, catch_unwind cannot be used there.
  • Exhausting the 1 MiB shadow stack (2 000 000 frames of 128 bytes) traps (RuntimeError) instead of corrupting memory.
  • After a stack-exhaustion trap, the next call on the same instance fails in the allocator (memory access out of bounds, deterministic). After a plain panic the same instance still answers, with a stack pointer that was never unwound: the dangerous case. Rule for R2: no instance is reused after any trap; a fresh instance is a new module record (the wasm-bindgen glue caches its instance in a module variable, and the ESM cache returns the same module for the same URL: loadCore() imports with a cache-busting query; in the browser the glue must be a static asset imported the same way, or the core runs in a Worker recreated on trap).

5.2 Serialisation contract (tests/serialisation.test.ts, crates/core/tests)

  • Byte equality with JSON.stringify(JSON.parse(text), null, 2) on report-v3.demo.json, report-v2.full.json, the 296 KB equine document.json and the 84 KB report-migration-map.json, plus a number corpus (1523, 1715.4285714285713, 0.85, 1e+21, 1e-7, 0.000001, -0 → 0, 123456789012345680000, 5e-324, 1.7976931348623157e+308).
  • Finding: serde_json's default float parser is a documented fast path that can be one ULP off; the first run printed 1715.428571428571 and 123456789012345670000. The float_roundtrip feature (enabled in Cargo.toml) fixes it; the module grew from 187 KB to 225 KB raw.
  • Optional fields absent, nullable fields null, unknown keys ignored, unresolved: false refused; the current ReportZoneSchema and SheetRefSchema (Zod 3, @faunosteo/domain) parse what the core writes.

5.3 musl static binary with libwebp (crates/worker/Dockerfile)

Builds on rust:1.99.0-alpine3.24 with build-base; libwebp-sys 0.14.4 compiles its vendored libwebp with cc; WebPGetEncoderVersion() reports 1.6.0 (logged by run --check, test the_linked_libwebp_is_recent_enough). The runtime image carries the one static binary.

5.4 seccomp allowlist, derived and proven (crates/worker/tests/sandbox.rs)

  • Derivation (scripts/derive-seccomp.sh, strace over png, jpeg, webp, a 4096 × 4096 JPEG and a 3000 × 3000 PNG, after the marker): exactly read write mmap munmap mremap exit_group getrandom. musl's mallocng used neither brk nor mprotect; no futex in a single-threaded decode. The allowlist is that set plus the abort path (rt_sigaction, rt_sigprocmask, getpid, gettid, tkill, tgkill, exit).
  • Proven on the release-profile musl binary with the test hooks, inside Docker's default seccomp profile: 13 tests green (png_jpeg_and_webp_decode_through_the_full_sandbox, inputs_at_the_caps_decode_within_the_limits (4096²), dimensions 32 px and 20 000² header, GIF and SVG refused, truncated PNG, non-empty environment refused, --violate → SIGSYS 31, --flood → output cut, --alloc-gib 2 → SIGABRT 6 under RLIMIT_AS, --spin → parent deadline, --spin → SIGXCPU 24 at the CPU soft limit, libwebp ≥ 1.6.0).
  • Findings: with RLIMIT_CPU soft = hard the kernel sends SIGKILL (hard limit checked first), indistinguishable from the parent's deadline kill; the soft limit is now two seconds below the hard one. The 4096² decode exceeded 10 s of CPU in an unoptimised debug build: dependencies are optimised in every profile.

5.5 CSP with 'wasm-unsafe-eval' (docker/csp-proof/run.sh)

Served packages/core-wasm/pkg through nginx:1.31-alpine with docker/nginx.conf plus the exact Content-Security-Policy of DEPLOY.md, loaded by headless Chrome for Testing 156:

Header Result
production (script-src 'self') FAIL WebAssembly.instantiateStreaming(): Compiling or instantiating WebAssembly module violates the following Content Security policy directive because 'unsafe-eval' is not an allowed source of script in the following Content Security Policy directive: "script-src 'self'"
script-src 'self' 'wasm-unsafe-eval' OK 0.1.0 (module instantiated, core_version() answered)

The keyword allows WebAssembly compilation only: an inline <script> variant stayed blocked under both headers. nginx serves .wasm as application/wasm out of the box.

5.6 Served size and instantiate time (tests/size.test.ts)

faunosteo_wasm_bg.wasm: 224 713 bytes raw, 85 396 bytes gzip-9 (with float_roundtrip; 186 805 / 72 917 without), instantiate 2.7 ms in Node 24. The D-R13 budget (600 KB compressed) is asserted by the test from R0 on.

5.7 Runner caches and build times

Not measurable from this host (no forge runner here). Recorded instead: builder image cold build about 6 minutes; worker test stage cold about 2 minutes, warm under 30 s with the BuildKit cache mounts; the wasm build under 10 s warm. The first run on the forge records its own numbers here.

6. Reproduction

pnpm rust:builder && pnpm rust:check          # §2, §5.2 (cargo side)
pnpm wasm:build && pnpm --filter @faunosteo/core-wasm test:run   # §5.1, §5.2, §5.6
pnpm worker:test                               # §5.3, §5.4 (tests + derivation in the build log)
pnpm worker:image && docker run --rm --read-only --cap-drop ALL faunosteo_worker:dev   # §3
CHROME=<chromium binary> bash docker/csp-proof/run.sh   # §5.5 (playwright-core on NODE_PATH)

7. What stays hypothetical after R0

  • Follow-ups from the R0 security audit, owned by R1 unless stated: base images pinned by digest in the three Dockerfiles (today by tag, as the existing Dockerfile); a verification decode of the child's output in a second sandboxed child (the RIFF check validates the container, not the bitstream); the shared BuildKit cache mounts of the CI builds (the release workflow already uses its own builder); actions/*@v4 tags in ci.yml (pre-existing practice) to pin by commit at Step 27.
  • The browser-side fresh-instance mechanism (static glue URL with a cache-busting query under Vite, or a Worker per instance) is designed, not built: R2 builds and tests it.
  • HTTPS from the worker (CA bundle of distroless, webpki-roots): no HTTP client in the R0 binary; R1 adds reqwest and the CI HTTPS call.
  • The forge runner's cache and timings (§5.7).
  • The allowlist is x86_64; an aarch64 host would need its own derivation (target_arch selects the seccomp architecture, the syscall numbers come from libc).