docs(docs): RUST.md with the R0 proofs, DEPLOY image deploy by digest + CSP note, workspace/test strategy/packages/CLAUDE.md, CHANGELOG; chore(memory): TODO R0
This commit is contained in:
1 parent
4833fd29ef
commit
9d3e0294e2
8 files changed
+376
-3
No files matched your search
@@ -0,0 +1,260 @@
|
||||
# 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`):
|
||||
|
||||
```bash
|
||||
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
|
||||
|
||||
```text
|
||||
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`; `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; 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}`, `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; any `EXIF`, `XMP `, `ICCP` or unknown
|
||||
chunk refuses the output; owner amendment of D-R4).
|
||||
- `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 + `scripts/derive-seccomp.sh`), `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; builds and pushes `faunosteo_app:<sha>`
|
||||
and `faunosteo_worker:<sha>` to the registry of the `REGISTRY` secret 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 musl binary that ships, 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
|
||||
|
||||
```bash
|
||||
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
|
||||
|
||||
- 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`).
|
||||
@@ -17,6 +17,9 @@ Status: Step 0 deliverable, 2026-10-08. Current state: 32 files under
|
||||
| Migration | `supabase db reset` from zero + seed + regression fixtures | CI | every PR touching `supabase/` |
|
||||
| PDF regression | vitest golden tests: text extraction of generated PDFs, attachment roundtrip, raster hash on fixed inputs | `packages/pdf/tests` | CI |
|
||||
| SQL/TS contract | generated types diff check | CI | every PR touching `supabase/` |
|
||||
| Rust core and facade | `cargo test` (unit + fixture tests reading the repository JSON in place), `clippy -D warnings`, `cargo deny`; ts-rs types drift check | `crates/*`, CI job `rust` through the builder image | CI on every PR |
|
||||
| Rust/TS contract | vitest proofs on the built module: byte equality with `JSON.stringify(…, null, 2)` on the real documents, optional/nullable shape read by the current Zod schemas, panic and stack traps, served size budget | `packages/core-wasm/tests` (skipped with a notice when `pkg/` is absent) | CI `check` after `wasm:build` |
|
||||
| Worker sandbox | integration tests against the musl binary that ships: fixture corpus through the full sandbox, refusals, SIGSYS on a denied syscall, output cap, `RLIMIT_AS` abort, `RLIMIT_CPU`, deadline; seccomp allowlist derived by `strace` and compared | `crates/worker/tests`, Dockerfile stage `test` | CI `docker` job |
|
||||
|
||||
Browser-only code (`svgToPng`, `DOMParser` in the importer) runs under
|
||||
happy-dom where sufficient and under Playwright when real rendering matters
|
||||
|
||||
@@ -34,8 +34,15 @@ Future units, created only by the step that needs them:
|
||||
| Path | Role | Created at |
|
||||
|---|---|---|
|
||||
| `apps/public-web` | SSR public site (landing, practitioner profiles, search) | plan Step 22 |
|
||||
| `apps/worker` | Node job runner (emails, expiry, calendar sync, imports) | plan Step 19 |
|
||||
| `crates/worker` | Rust job runner (avatars at R1, then emails, expiry, calendar sync, imports) — created at R0, replaces the planned `apps/worker` | R0 (2026-10-12) |
|
||||
| `packages/*` | shared domain, anatomy, pdf, i18n, supabase, config, ui | see `packages/README.md` |
|
||||
|
||||
Rust workspace (plan R0, `docs/development/RUST.md`): `Cargo.toml` at the
|
||||
root with `crates/core` (library), `crates/wasm` (browser facade, built into
|
||||
`packages/core-wasm/pkg`) and `crates/worker` (binary). Every cargo command
|
||||
runs through the builder image (`pnpm rust:check`, `pnpm wasm:build`); the
|
||||
pnpm workspace gains `packages/core-wasm` (loader, generated types, proofs),
|
||||
whose tests skip with a notice when the module has not been built.
|
||||
| `supabase/` | migrations, functions, seed, tests | plan Step 3 |
|
||||
|
||||
## 2. Why this layout now
|
||||
|
||||
Reference in new issue
Block a user