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
+11
-1
@@ -135,7 +135,17 @@ feat/findings-tree-v2 merged (FindingsTreePicker tracked in HEAD); all work belo
|
||||
- [ ] 8.5 docs: STORAGE.md (model, keys, statuses, purge/grace rules, reconciliation query, backup ordering + invariant, managed migration runbook), DEPLOY.md (worker, env file, network, CSP connect-src), SUPABASE.md, CLAUDE.md, CHANGELOG, plan note (worker early, SVG processor → Step 13); CI jobs
|
||||
- [ ] 8.6 verify: root check, PGlite + real stack pgTAP, types, docker builds (app + worker), real-stack e2e (sign allowed/denied), gates verifier + security; memory; stop for user validation
|
||||
- [ ] Rust by default (rule adopted 2026-10-12, BDR-043; orientation + 10 principles VALIDATED by the owner 2026-10-12, BDR-044; study `docs/development/RUST_ARCHITECTURE_REVIEW.md` rev 2 + Annex A decision table + Annex B R0 scope on chore/step-08-files-analysis; AWAITING the owner's validation of decisions D-R1..D-R14 (D-R6 withdrawn); R0 and Step 8 NOT started until then). Roadmap (each phase: oracles frozen with the old code, consumer-driven deletion, rollback row, gates):
|
||||
- [ ] R0 foundation (inside Step 8, Annex B): Docker builder image = reference toolchain (rustup optional locally, never on the VPS), Cargo workspace (`crates/core`, `wasm`, `worker` skeletons), toolchain pin, deny.toml, lints, CI job `rust`, worker image started once against the local stack, app wasm stage built but not loaded, `docs/development/RUST.md`, DEPLOY.md (images pulled by digest, CSP `'wasm-unsafe-eval'`, gzip wasm, VPS headroom, rollback = previous digest); 7 experimental proofs kept as tests (wasm panic/re-instantiate, js_number + optional/nullable vs Zod, musl + libwebp build, traced seccomp child, CSP headless, size/instantiate, runner caches)
|
||||
- [ ] R0 foundation (GO 2026-10-12, BDR-045; branch feature/rust-r0-foundation; Annex B; owner constraints: builds reproducible in Docker, no Rust on the VPS, live deployment untouched, frontend never loads the module, no R1):
|
||||
- [x] R0.1 toolchain: `docker/rust-builder.Dockerfile` (rust:1.99.0-bookworm + wasm target + wasm-bindgen-cli 0.2.129 + cargo-deny 0.20.2 + rustfmt/clippy), `docker/rust-run.sh` (named volumes faunosteo_cargo_registry / faunosteo_rust_target), `docker/rust-check.sh`, `docker/wasm-build.sh` (CLI/crate version lock), root scripts rust:builder / rust:check / wasm:build / worker:test / worker:image
|
||||
- [x] R0.2 workspace: Cargo.toml (3 members, pinned deps, lints unwrap/expect/disallowed_methods, dev deps optimised), rust-toolchain.toml 1.99.0, rustfmt/clippy/deny config, .cargo/config.toml (wasm stack 1 MiB, TS_RS_EXPORT_DIR), Cargo.lock, .gitignore/.dockerignore (target, pkg)
|
||||
- [x] R0.3 crates/core: js_number + JsPrettyFormatter (JSON.stringify semantics), report contract types (SheetRef, ReportZone, Vertebra, LateralSide, Unresolved) with optional-absent / nullable-null, facade `call(op, json)` with closed kinds; 12 cargo tests + ts-rs export (4 types committed under packages/core-wasm/types)
|
||||
- [x] R0.4 crates/wasm: facade (core_version, call, panic_for_test, recurse_for_test); build 224,713 B raw / 85 KB gzip (float_roundtrip on), instantiate ≈ 3 ms in Node
|
||||
- [x] R0.5 crates/worker: plain main, `decode` child (env check → rlimits AS 512 MiB / CPU 10 s soft, 12 s hard → seccomp allowlist TSYNC kill) → image decode with Limits → orientation → resize_to_fill 512 → libwebp-sys lossy; parent `Spawner` (env_clear, 512 KiB output cap, deadline, signal classification) + `webp_check` (RIFF allowlist, dims, no metadata); `run --check`, `version`; test-hooks (fixtures, violate, flood, alloc, spin, print-allowlist); Dockerfile alpine musl → test stage (sandbox tests + strace derivation) → distroless/static:nonroot
|
||||
- [x] R0.6 packages/core-wasm: loader (lazy, Node bytes), generated types, vitest proofs (facade, serialisation byte-equal with JSON.stringify on 4 real documents + number cases + Zod readers, panic/stack traps, size budget) skipped with a notice when pkg/ is absent
|
||||
- [ ] R0.7 proofs recorded with numbers in RUST.md: panic=abort + fresh instance path; float_roundtrip finding; musl static + libwebp ≥ 1.6 build; seccomp allowlist derived by strace and proven on the corpus; CSP with/without 'wasm-unsafe-eval' under the production nginx config (headless Chromium); size/instantiate; runner cache (not measurable here: documented as pending on the forge)
|
||||
- [ ] R0.8 CI: job `rust` (builder image, fmt/clippy/test/deny, wasm build, types drift), worker test stage + runtime image build in the docker job, nightly advisories, manual `release-images` workflow (digest output, no auto deploy)
|
||||
- [ ] R0.9 docs: docs/development/RUST.md, DEPLOY.md (prepared: pull by digest, CSP line, gzip wasm, rollback = previous digest; live deployment unchanged), WORKSPACE.md, packages/README.md, CLAUDE.md (stack, map, commands), TEST_STRATEGY.md, CHANGELOG
|
||||
- [ ] R0.10 gates: `pnpm check` (existing suites untouched), verifier contract, security-auditor; memory (BDR/LRN/EVAL/journal); stop for owner validation, R1 not started
|
||||
- [ ] R1 = Step 8 worker in Rust (replaces 8.2 below): decode child dispatched before any thread, empty env, RLIMIT_AS/CPU, traced seccomp allowlist, `image` + `moxcms` + `libwebp-sys` in the child, parent RIFF-header check only, 512 KiB output cap, per-stage deadlines, service key
|
||||
- [ ] R2 domain core (before Step 9): sheet/report/archive contracts, `SheetHandle` + `SheetIndexData`, reducers, Finding builder, vertebra selection, publish gate; wasm facade (JSON strings, ts-rs types, poison + reinstantiate, lazy init); app switched; 3 envelopes frozen first; N-1 reader test; draft quarantine; conformance fixtures + generated pgTAP; `packages/domain` frozen for engine/pipeline
|
||||
- [ ] R3 anatomy core: tree, one sanitiser, serialiser, layer renderer, `compose_view_svg`; app canvas switched; composed views frozen as trees first
|
||||
|
||||
@@ -6,6 +6,10 @@ Versions follow [Semantic Versioning](https://semver.org/).
|
||||
|
||||
## [Unreleased]
|
||||
|
||||
### Added (Rust foundation, plan R0)
|
||||
|
||||
- **Rust by default** (rule adopted 2026-10-12, `docs/development/RUST_ARCHITECTURE_REVIEW.md`): Cargo workspace with three crates, `crates/core` (contracts and the JavaScript-compatible JSON formatter, no I/O by lint), `crates/wasm` (browser facade built into `packages/core-wasm/pkg`) and `crates/worker` (the future file-processing worker: sandboxed `decode` child with rlimits and a seccomp allowlist derived by `strace`, image decoding in pure Rust, lossy WebP through libwebp confined to the child, parent-side container check; `run --check` only, no job loop before R1). Reference toolchain in Docker (`docker/rust-builder.Dockerfile`, `pnpm rust:check`, `pnpm wasm:build`), worker image on `distroless/static`, CI job `rust`, nightly advisories, manual digest-tagged image workflow (no deploy). R0 proofs recorded in `docs/development/RUST.md`: `float_roundtrip` required for JSON parity, traps leave a wasm instance unusable (fresh instance per recovery), CSP needs `'wasm-unsafe-eval'`. No application behaviour, interface, archive or database change; the frontend does not load the module.
|
||||
|
||||
### Added (SaaS migration, plan Step 7)
|
||||
|
||||
- **Identity (Step 7)** — sign-in and sign-up by email/password (confirmation mandatory, policy 12 chars + lower/upper/digit), password recovery, OAuth buttons (Google, Apple) driven by `APP_AUTH_PROVIDERS`, landing route for confirmation / OAuth links; the guarded `/app` shell (desktop sidebar, light top bar, mobile drawer) with a dashboard (greeting, profile completeness, local tool, account) and **Mon compte** (personal, professional, preferences, security). Profile columns `practice_name`, `professional_title`, `siret` (migration `20261011100000`, pgTAP 009), language synced with `profiles.locale`, platform roles shown read-only. GoTrue TOTP enabled server-side; MFA enforcement for platform roles documented as a gap (`docs/development/IDENTITY.md`). The local tool (`/`, `/new`, `/editor`) stays unauthenticated; the Home header links to the space only when Supabase is configured.
|
||||
|
||||
@@ -52,6 +52,9 @@ MVP species: equine only. Open-source MIT.
|
||||
| DB client | @supabase/supabase-js (packages/supabase) | 2.x |
|
||||
| SQL tests | pgTAP under supabase/tests, run by `supabase test db` and by PGlite (Dockerless) | PGlite 0.3 |
|
||||
| Deploy | Docker multi-stage → nginx:alpine | — |
|
||||
| Rust (core, wasm facade, worker) | Rust pinned by `rust-toolchain.toml`, edition 2024; every cargo command runs in `docker/rust-builder.Dockerfile` (`pnpm rust:check`, `pnpm wasm:build`), never on the VPS | 1.99.0 |
|
||||
| WASM glue | wasm-bindgen crate = CLI version (locked in `docker/wasm-build.sh`), `ts-rs` types committed under `packages/core-wasm/types` | 0.2.129 / 12 |
|
||||
| Worker image | `crates/worker/Dockerfile`: `rust:1.99.0-alpine3.24` (musl, libwebp via `cc`) → `distroless/static:nonroot`; sandbox tests + seccomp derivation in the `test` stage | — |
|
||||
|
||||
---
|
||||
|
||||
@@ -99,6 +102,13 @@ pnpm build:preview # SHEET_BUNDLE=draft build (manual validation, preview de
|
||||
pnpm preview:draft # same, then serves it
|
||||
pnpm import:equine # regenerate legacy-import/ and draft/ (document, migration map, review drawings)
|
||||
pnpm report:compare <pdf|dir>... # archive check: attachment vs its v3 reading, unresolved items flagged (docs/PDF-FORMAT.md)
|
||||
|
||||
# Rust (docs/development/RUST.md) — all through the builder image, no toolchain on the host
|
||||
pnpm rust:builder # build docker/rust-builder.Dockerfile once (faunosteo_rust_builder:1.99.0)
|
||||
pnpm rust:check # fmt --check, clippy -D warnings, cargo test (core, wasm), ts-rs export, cargo deny
|
||||
pnpm wasm:build # crates/wasm → packages/core-wasm/pkg (git-ignored); then the core-wasm vitest proofs run
|
||||
pnpm worker:test # crates/worker/Dockerfile stage test: sandbox tests + seccomp derivation on the musl binary
|
||||
pnpm worker:image # runtime image faunosteo_worker:dev (distroless/static, `run --check`)
|
||||
```
|
||||
|
||||
## Docker commands
|
||||
@@ -244,7 +254,14 @@ faunosteo/
|
||||
│ │ └─ draft/ ← GENERATED working revision: document, cleaned horse.svg, sheet-ref, report-migration-map, CHANGELOG, REVIEW-REPORT, review/*.svg, equine_draft.sql
|
||||
│ └─ tests/*.sql ← pgTAP: allowed + denied paths per policy
|
||||
├─ packages/README.md ← shared packages index
|
||||
├─ .gitea/workflows/ci.yml ← CI: install, typecheck, test, lint, build, docker
|
||||
├─ packages/core-wasm/ ← @faunosteo/core-wasm: loader of the browser module (pkg/ built, git-ignored), ts-rs types (committed), R0 proofs (panic, serialisation, size)
|
||||
├─ crates/ ← Rust workspace (Cargo.toml, rust-toolchain.toml, deny.toml, clippy.toml, .cargo/config.toml at the root)
|
||||
│ ├─ core/ ← faunosteo-core: contracts (report types), js_number + JS pretty formatter, facade `call(op, json)`; no I/O, no clock (lint-enforced)
|
||||
│ ├─ wasm/ ← faunosteo-wasm: wasm-bindgen facade (core_version, call, R0 trap proofs)
|
||||
│ └─ worker/ ← faunosteo-worker: plain main; `decode` sandboxed child (rlimits, seccomp allowlist, image → libwebp), parent Spawner + RIFF check, `run --check`; Dockerfile, scripts/derive-seccomp.sh
|
||||
├─ docker/rust-builder.Dockerfile, rust-run.sh, rust-check.sh, wasm-build.sh, csp-proof/ ← reference Rust toolchain + the CSP proof
|
||||
├─ .gitea/workflows/ci.yml ← CI: rust job (builder image, fmt/clippy/test/deny, types drift, wasm), install, typecheck, test, lint, build, docker (app + worker test stage + runtime)
|
||||
├─ .gitea/workflows/{rust-advisories,release-images}.yml ← nightly RustSec advisories; manual digest-tagged image publication (no deploy)
|
||||
├─ .claude/{tasks/TODO.md,memory/,audits/}
|
||||
├─ Dockerfile, docker-compose.yml, docker/
|
||||
├─ .env.example, .editorconfig, .nvmrc, .node-version, .npmrc, .prettierrc.json
|
||||
@@ -492,6 +509,7 @@ the owner's validation before any implementation; release 0.2.0 unaffected).
|
||||
- Import never parses untrusted PDF object graphs: the attachment is located by byte scan and inflated under the 16 MiB cap (BLK-009). Opening the import to external users is gated by `docs/development/PDF_IMPORT_HARDENING.md` §5 (BDR-040).
|
||||
- After PDF roundtrip tests fail: check attachment bytes, then the layered reader (report first, envelope metadata, snapshot/branding/labels), then DecompressionStream inflation. Goldens under `apps/app/tests/fixtures/goldens/step6` are never regenerated without a user decision.
|
||||
- Node 24 / pnpm 10.13.1: `corepack enable` or `corepack pnpm`; never a global install.
|
||||
- Rust: never on the host or the VPS; `pnpm rust:check` and `pnpm wasm:build` run inside the builder image. Before every Rust commit: `pnpm rust:check` green, `pnpm worker:test` green when `crates/worker` changed, the ts-rs types under `packages/core-wasm/types` committed, `Cargo.lock` committed. The core takes ids, time and bytes as inputs (clippy `disallowed_methods`); the worker child is the only process that decodes untrusted bytes.
|
||||
- SQL change: `pnpm --filter @faunosteo/supabase test:run` (PGlite) before commit; `pnpm db:reset && pnpm db:test`
|
||||
on the real stack when Docker is available; regenerate types (`pnpm db:types`).
|
||||
|
||||
|
||||
@@ -21,6 +21,13 @@ The host should publish only ports `22`, `80`, `443` to the internet. The
|
||||
container port (`8080` by default) should stay loopback-only — the host
|
||||
reverse proxy reads from it on `127.0.0.1:8080`.
|
||||
|
||||
Rust (plan R0, `docs/development/RUST.md`): the repository also builds a
|
||||
worker image (`crates/worker/Dockerfile`, static musl binary on
|
||||
`distroless/static`, container `faunosteo_worker`). It is not deployed yet
|
||||
(its job loop arrives at R1); the live deployment above is unchanged. The
|
||||
production VPS never needs a Rust toolchain: images are built in CI and
|
||||
pulled by digest ("Image deploy by digest", prepared below).
|
||||
|
||||
### Reference sheet in the image (SHEET_BUNDLE)
|
||||
|
||||
The application needs an anatomical sheet to work. Until sheets are served by
|
||||
@@ -563,6 +570,64 @@ already exported are unaffected.
|
||||
|
||||
---
|
||||
|
||||
## Image deploy by digest (prepared at R0, not yet applied)
|
||||
|
||||
Decision D-R13 (`docs/development/RUST_ARCHITECTURE_REVIEW.md` Annex A and
|
||||
C): production images are built in CI and the VPS pulls them; it never
|
||||
compiles the Rust project, and the DEV1-XS memory limit stops mattering for
|
||||
builds. The procedure below is prepared and documented now; it replaces
|
||||
"Routine deploys" and "Rollback" above **only when the first image built
|
||||
this way is deployed, after a separate validation**. Until then the live
|
||||
deployment keeps building on the VPS as documented above.
|
||||
|
||||
1. Build and publish: run the manual workflow `release-images`
|
||||
(`.gitea/workflows/release-images.yml`, `workflow_dispatch`, never on
|
||||
push) on the forge. It pushes `faunosteo_app:<sha>` and
|
||||
`faunosteo_worker:<sha>` to the container registry named by the
|
||||
`REGISTRY` secret (the forge's own Gitea registry is the recommended
|
||||
choice, Scaleway Container Registry the alternative) and prints their
|
||||
digests in the job summary. No workflow deploys anything.
|
||||
2. Pin: `docker-compose.yml` on the VPS references the images by digest
|
||||
(`image: <registry>/<owner>/faunosteo_app@sha256:…`); the digest is the
|
||||
only thing that changes at a deploy, by hand, after validation.
|
||||
3. Deploy: `docker compose pull && docker compose up -d` (no `--build`), then
|
||||
the post-deploy checks of "Routine deploys".
|
||||
4. Rollback: set the previous digest back in `docker-compose.yml` and run
|
||||
step 3 again; nothing is rebuilt and nothing needs crates.io or npm.
|
||||
5. Registry credentials on the VPS: a read-only token in `~/.docker/config.json`
|
||||
of the deploy user, never in the repository.
|
||||
|
||||
Prerequisites checked at R0 and to re-check before the first digest deploy:
|
||||
disk headroom on the VPS for two image generations (app ≈ 100 MB,
|
||||
worker ≈ 9 MB, measured at R0), the registry reachable from the VPS, `docker compose pull`
|
||||
working with the read-only token.
|
||||
|
||||
### WebAssembly and the CSP (from R2 on)
|
||||
|
||||
The application does not load the Rust core module before plan R2. When it
|
||||
does, the two `Content-Security-Policy` headers of this file (nginx and
|
||||
Caddy options) must carry `'wasm-unsafe-eval'` in `script-src`:
|
||||
|
||||
```text
|
||||
script-src 'self' 'wasm-unsafe-eval';
|
||||
```
|
||||
|
||||
Proven at R0 under the production nginx image and headers with headless
|
||||
Chrome for Testing 156 (`docker/csp-proof/run.sh`, result in
|
||||
`docs/development/RUST.md` §5): with `script-src 'self'` the browser refuses
|
||||
to compile the module ("Compiling or instantiating WebAssembly module
|
||||
violates the following Content Security policy directive"); with the keyword
|
||||
the module instantiates. `'wasm-unsafe-eval'` allows WebAssembly compilation
|
||||
only, never `eval` or inline scripts (the proof's inline variant was still
|
||||
blocked). Browser floor for the keyword: Chrome 97, Firefox 102, Safari 16
|
||||
(the Vite 7 baseline). The `.wasm` file is served as `application/wasm` by
|
||||
`nginx:1.31-alpine` out of the box; at R2 `docker/nginx.conf` gains
|
||||
`gzip_static on;` for a precompressed `.wasm.gz` (or `gzip_types
|
||||
application/wasm`) and the served, compressed size is what the D-R13 budget
|
||||
counts.
|
||||
|
||||
---
|
||||
|
||||
## Health checks
|
||||
|
||||
| URL | Expected |
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -13,6 +13,12 @@ Planned packages and the step that creates each one:
|
||||
| `@faunosteo/pdf` | browser-free PDF engine (**created**, Step 6): report archive export from explicit inputs (report, sheet snapshot, branding, labels, rasterizer), layered archive reading, SVG sanitiser, page renderers | Step 6 (PDF archives) |
|
||||
| `@faunosteo/i18n` | FR/EN dictionaries (no React) + `useT` | first second consumer (public-web or worker) |
|
||||
| `@faunosteo/supabase` | browser client factory, generated database types, PGlite harness running the pgTAP suite, sheet publish gate | **created**, Step 3 |
|
||||
| `@faunosteo/core-wasm` | loader of the Rust core compiled to WebAssembly (`pkg/` built by `pnpm wasm:build`, git-ignored), TypeScript types of the contracts generated by ts-rs (committed), the R0 proofs (panic and stack traps, JSON.stringify parity, Zod readers, size budget) | **created**, R0 (Rust review) |
|
||||
|
||||
From R2 on, the Rust core (`crates/core`) replaces the TypeScript business
|
||||
logic of `domain`, `anatomy` and `pdf` phase by phase
|
||||
(`docs/development/RUST_ARCHITECTURE_REVIEW.md` Part VI); each TypeScript
|
||||
package is deleted in the phase that switches its last consumer.
|
||||
| `@faunosteo/config` | runtime config resolution shared by app, public-web, worker | with public-web |
|
||||
| `@faunosteo/ui` | UI primitives and design tokens | only when public-web reuses them |
|
||||
|
||||
|
||||
Reference in new issue
Block a user