16 KiB
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 ECMAScriptNumber::toString;JsPrettyFormatterisserde_json's pretty formatter with that rule;to_js_prettyandpretty_js_round_tripproduceJSON.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 fieldsskip_serializing_if = "Option::is_none", nullable fields plainOption, unknown keys ignored where Zod strips them.cargo test -p faunosteo-core --features tswrites the TypeScript types topackages/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 whenpkg/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; checksThreads: 1in/proc/self/status; disables core dumps (PR_SET_DUMPABLE 0,RLIMIT_CORE 0: a dump would hold the uploaded photo);RLIMIT_AS512 MiB,RLIMIT_CPU10 s soft / 12 s hard (soft = hard made the kernel SIGKILL first, finding §5.4); seccomp allowlist installed with TSYNC,KillProcesson anything else, with argument filters:tkill/tgkillmay only send SIGABRT to the child's own pid (never a signal to the keyed parent or a sibling),mmapmay not mapPROT_EXEC; then reads ≤ 5 MiB on stdin, sniffs the format (JPEG, PNG, WebP), decodes withimage::Limits(sides ≤ 4096, alloc 256 MiB), applies the EXIF orientation,resize_to_fill512 × 512, encodes lossy WebP (q 82) throughlibwebp-sys(C, this process only), writes stdout. Exit codes inexit_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::inspectparses the RIFF container only (chunk allowlistVP8X,VP8,VP8L,ALPH; canvas size from the headers, the frame size must agree with the canvas; anyEXIF,XMP,ICCPor 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 plainrundoes 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 theSECCOMP-MARKERline for the strace derivation),--violate(getcwdafter 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(beforecheck): builds the builder image, runsdocker/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; thecore-wasmproofs run becausepkg/exists. - Job
docker: application image, workerteststage (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 manualcargo deny check advisories, out of the blocking path on purpose.release-images.yml: manual only, onmainordevelop; the dispatch input is a typed choice re-validated through an environment variable; the RustSec advisories gate runs first; an ephemeralbuildxbuilder 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-jobDOCKER_CONFIGremoved at the end;actions/checkoutpinned to a commit. It pushesfaunosteo_app:<sha>andfaunosteo_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_unwindcannot 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)onreport-v3.demo.json,report-v2.full.json, the 296 KB equinedocument.jsonand the 84 KBreport-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 printed1715.428571428571and123456789012345670000. Thefloat_roundtripfeature (enabled inCargo.toml) fixes it; the module grew from 187 KB to 225 KB raw. - Optional fields absent, nullable fields
null, unknown keys ignored,unresolved: falserefused; the currentReportZoneSchemaandSheetRefSchema(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): exactlyread write mmap munmap mremap exit_group getrandom. musl's mallocng used neitherbrknormprotect; nofutexin 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 underRLIMIT_AS,--spin→ parent deadline,--spin→ SIGXCPU 24 at the CPU soft limit, libwebp ≥ 1.6.0). - Findings: with
RLIMIT_CPUsoft = 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/*@v4tags inci.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 addsreqwestand 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_archselects the seccomp architecture, the syscall numbers come fromlibc).