docs(docs): Rust review annexes — expanded decision table D-R1..D-R14 and R0 scope (Docker builder toolchain, 7 experimental proofs); chore(memory): BDR-044 orientation validated, journal, TODO R0
This commit is contained in:
1 parent
3fbf34f663
commit
51667788e5
4 files changed
+108
-2
No files matched your search
@@ -849,3 +849,103 @@ Rust worker" from this review on; the worker credential stays the service
|
||||
key, the dedicated role being a Step 27 option (IV.4). D-R6 of revision 1
|
||||
(that role) is therefore no longer a decision of this study, which is why
|
||||
the numbering skips it.
|
||||
|
||||
---
|
||||
|
||||
## Annex A. Decision table (expanded for the owner's validation, 2026-10-12)
|
||||
|
||||
Orientation validated by the owner on 2026-10-12 with ten principles (Rust
|
||||
worker at Step 8, Cargo workspace, native and WASM libraries, progressive
|
||||
anatomy migration, PDF migration under complete compatibility proofs, React
|
||||
and PostgreSQL/Supabase kept, testable increments with rollback, no premature
|
||||
deletion of TypeScript still in use, fully dockerised infrastructure with
|
||||
production builds outside the small VPS, WASM compatibility with the
|
||||
production CSP proven before activation). The detailed decisions below await
|
||||
validation. Impact tags: SEC security, HIST historical data, PERF browser
|
||||
performance, UI interfaces, DEPLOY deployment.
|
||||
|
||||
| Id, subject | Recommendation | Relevant alternatives | Advantages / drawbacks | Risks | If validated | Impacts |
|
||||
|---|---|---|---|---|---|---|
|
||||
| D-R1 workspace layout | Three crates: `core` (feature-gated library, tool binaries behind `cli`), `wasm` (cdylib facade), `worker` (binary) | Six crates per boundary (rev 1); one crate holding the facade too (wasm-bindgen would pollute native builds); one crate per module | One dependency graph and one test run; features keep the worker lean / feature combinations must be tested in CI (`--no-default-features`, `--all-features`); core compile time grows with modules | Accidental I/O or clock in core (lint `disallowed_methods`); feature creep | R0 creates the three crates and the lint set | none |
|
||||
| D-R2 PDF engine | Reader and writer ported together at R4 on `pdf-writer` with the Standard 14 AFM metrics (kerning-inclusive widths); a draw-log golden for lines, rectangles and colours frozen with the TS engine before the port; TTF fonts as a separate later change | Reader first, writer later (two phases, longer hybrid); writer on `krilla` + TTF at once (no Standard 14 page text, goldens regenerated blind); keep pdf-lib for writing (unmaintained, contradicts the rule) | The 39 goldens stay the exact oracle; `packages/pdf` deleted in one phase; no object streams by construction / largest single phase; AFM files vendored under the APAFML notice | Kerning, rounding, ICU dates or `f32` coordinates moving a run (caught by goldens and the `lopdf` read-back); viewer compatibility of classic xref (standard) | Golden regeneration decision for the additive draw-log golden; the gated functions port (D-R12); rollback note in DEPLOY.md as for Step 6 | HIST, DEPLOY |
|
||||
| D-R3 rasteriser | Browser canvas stays the app's rasteriser between the two core calls; `resvg` native only in tools and worker if a server-side rendering need appears; nothing resvg in the browser bundle | `resvg` lazy-loaded in the browser (949 KB gzip, anti-aliasing change, new raster goldens); `resvg` everywhere for identical bytes server and browser | No bundle growth, no visual change, no golden change / browser and future server renderings would differ (only matters if server rendering appears) | Browser rasteriser limits unmeasured (true today already) | Export becomes `compose_export_views` → rasterise → `write_archive`; `browserRasterizer.ts` kept as DOM adapter | PERF, UI |
|
||||
| D-R4 lossy WebP encoder | `libwebp-sys` 0.14 (libwebp ≥ 1.6.0, C) confined to the sandboxed child; output checked by the parent at container level only | Lossless WebP via `image-webp` (pure Rust; avatars 5 to 10× larger); AVIF via `ravif` (pure Rust, slower encode, changes D4's format); wait for a pure-Rust lossy encoder (`oxideav-webp`, months old) | Standard output, small files, mature encoder / C compiled in the worker build (Alpine `build-base`), vendored version invisible to RustSec (logged at start, checked in CI) | libwebp CVEs (historically decoder side); mitigation = process confinement, rlimits, seccomp, version check | R0 spike proves the musl static build with `cc`; R1 implements | SEC, DEPLOY |
|
||||
| D-R5 sheet identity at R5 | `documentSha256` = sha256 of the bytes the Rust pipeline emits; generated dirs leave Prettier's scope; the one-time hash change makes older archives and drafts rebase once with a visible message and 0 unresolved items | Keep a Node Prettier step to preserve the bytes (rev 1; chains the identity to a JS formatter); hash of canonical JSON (RFC 8785, `serde_jcs`): identity independent of formatting forever, one more concept | Simplest rule, matches today's semantics (the file is the identity) / one import notice per old archive after R5 | None on data (rebase keeps everything); user confusion if the message is not worded for "identical content" | R5 regenerates the seed golden knowingly; CHANGELOG entry; the import and restore messages re-read for the 0-unresolved case | HIST, UI |
|
||||
| D-R7 form validation | Stays TypeScript (React-bound); a separate chore gives the constraints one home (hand-written constants module checked by a PGlite test against `pg_constraint` and `config.toml`, counting rule recorded) | Rust validation through the wasm per field (render-path calls on every keystroke); constants generated from the SQL migrations (rev 1: a DDL interpreter for eleven numbers) | Forms stay responsive and simple; the drift found by the inventory is closed / constants hand-written (kept honest by the test) | low | A small chore branch, any time; no UI change | UI |
|
||||
| D-R8 public web (Step 22) | Keep Astro (global SEO/GEO rule); record the Rust exception | Zola (Rust static generator, no islands, no React); Leptos/Dioxus SSR (immature SEO tooling, contradicts "React stays"); Next.js (global rule names Astro) | SEO/GEO tooling and islands / a TypeScript app in a Rust-by-default repository | none now | Exception recorded; Step 22 brainstorm re-checks per the global rule | DEPLOY |
|
||||
| D-R9 Edge Functions | Retired from the plan; webhooks and OAuth callbacks served by the worker's `serve` subcommand behind the reverse proxy | Edge Functions (Deno can run the wasm core; limits, hand deployment on self-hosted); a separate HTTP container; `pg_net`/`pg_cron` for some jobs | One runtime, one image, Rust / the worker gains an inbound route at Steps 21 and 23 and uptime expectations | Inbound surface (signature checks, proxy rate limits, monitoring at Step 27) | `BACKEND_ARCHITECTURE.md` §6 updated; Steps 21 and 23 designs change | SEC, DEPLOY |
|
||||
| D-R10 order | R0 + R1 within Step 8; R2 before Step 9; R3, R4, R5 before Step 13, interleaved with Steps 9 to 12 | R2 after Steps 9 to 12 (more TypeScript rules to migrate twice); R3 to R5 after Step 13 (impossible: the Rust worker needs the Rust sanitiser at Step 13) | Every later step writes its rules in Rust once / Steps 9 to 12 slowed by the migrations | Velocity of the functional steps | TODO order; Step 9 starts after R2 | DEPLOY |
|
||||
| D-R11 archive attachment bytes | New contract adopted at R2: declared field order (struct order), `js_number` floats, optional absent, nullable `null`; every previous reader keeps parsing it (permanent N-1 reader test); existing PDFs untouched. At R2 the frozen TS engine still writes the attachment from the core's objects (order changes, floats printed by JS); at R4 the Rust writer serialises fully | Reproduce the insertion order of the TS store exactly (fragile mirror); keep TS serialisation of the attachment until R4 (same end state, same key-order change) | Declared and testable order / byte diff against pre-R2 exports (no reader depends on order; Zod ignores it) | A reader depending on key order (none known) | Struct field orders documented; N-1 reader test added at R2 and kept | HIST |
|
||||
| D-R12 gated functions | Explicit go to port `readArchiveDocument`, `readReportArchive`, `readAttachedDocument` and `rebaseReportOnSheet` with behaviour preserved (CLAUDE.md gate) | Keep the TypeScript readers and rebase permanently (two implementations, contradicts the rule) | One reader for browser, worker and tools / the highest-stakes port (user data) | Behaviour drift on archives; mitigation = exact-object oracles, all fixtures, hostile corpus through the wasm build, N-1 test | The port follows the oracle suites; any behaviour change needs its own decision | SEC, HIST |
|
||||
| D-R13 serving the wasm | CSP `script-src 'self' 'wasm-unsafe-eval'` in both `DEPLOY.md` examples; gzip for `.wasm`; images built in CI and pulled by digest (no compile on the VPS); served module ≤ 600 KB compressed enforced in CI; registry = the forge's Gitea container registry (recommended; Scaleway Container Registry as alternative) | `'unsafe-eval'` (broader, rejected); inline the module as base64 (CSP still applies, bigger); Brotli (nginx module needed); build on the VPS (rejected) | Minimal CSP relaxation specific to WebAssembly; deploy and rollback never compile / `'wasm-unsafe-eval'` needs Chrome 97+, Firefox 102+, Safari 16+ (Vite 7 baseline); an older browser lands in `core_unavailable` | Registry credentials on the VPS; CSP forgotten on one proxy (sanity-check row) | DEPLOY.md rewritten at R0 (procedure prepared, applied at the first image deployed: worker at R1); the deploy procedure change is validated separately | SEC, PERF, DEPLOY |
|
||||
| D-R14 BLK-009 and the reader | R4 runs the reader in a terminated Web Worker and records the `PDF_IMPORT_HARDENING.md` §5 browser measurements (Chromium, Firefox, Safari, one low-end phone); the external-user import gate (BDR-040) stays open until every §5 item is done | Main-thread synchronous reader (memory never shrinks, UI blocked); server-side import only (Step 15) | Bounded blast radius, measurable, import off the main thread / a second instantiation per import; a browser runner (Playwright) introduced for the measurements | Safari worker + wasm specifics; measurement effort | R4 includes the browser measurement campaign; the gate stays open | SEC, PERF |
|
||||
|
||||
## Annex B. R0 scope (owner's clarification request, 2026-10-12)
|
||||
|
||||
R0 is the foundation phase inside Step 8. It changes no production
|
||||
artifact, implements no feature and starts only on the owner's go.
|
||||
|
||||
### B.1 Toolchain, reproducible in Docker
|
||||
|
||||
- Reference build environment = a Docker builder image
|
||||
(`docker/rust-builder.Dockerfile`, `FROM rust:1.99.0-bookworm`, plus
|
||||
`wasm32-unknown-unknown`, `wasm-bindgen-cli` at the version in
|
||||
`Cargo.lock`, `cargo-deny`, `binaryen` for `wasm-opt`), used by CI and by
|
||||
the application and worker image builds. The worker's own builder stays
|
||||
`rust:1.99.0-alpine3.24` (musl, `build-base` for libwebp).
|
||||
- The development host may install `rustup` for the inner loop (same
|
||||
`rust-toolchain.toml`, so the same compiler); the containerised build is
|
||||
the arbiter. Root scripts: `pnpm rust:check` (fmt, clippy, test, deny)
|
||||
and `pnpm wasm:build`, each runnable locally or through the builder image
|
||||
(`docker run --rm -v "$PWD":/w`).
|
||||
- The production VPS never gets Rust: it pulls images by digest.
|
||||
|
||||
### B.2 Workspace
|
||||
|
||||
- `Cargo.toml` (workspace, `[workspace.dependencies]`, `[workspace.lints]`:
|
||||
`unwrap_used`, `expect_used`, `disallowed_methods` for `std::time`,
|
||||
`std::fs`, `std::env` in core), `rust-toolchain.toml`, `rustfmt.toml`,
|
||||
`clippy.toml`, `deny.toml`, `.cargo/config.toml` (wasm stack size,
|
||||
`-C link-arg=-zstack-size`).
|
||||
- `crates/core` (modules declared, `SheetRef` + `Locale` types, the
|
||||
`js_number` formatter, the conformance fixture loader), `crates/wasm`
|
||||
(facade exporting `core_version()` and one JSON round-trip call),
|
||||
`crates/worker` (binary with `run` printing its configuration and
|
||||
`decode` wired to the sandbox spike, no job logic).
|
||||
- `packages/core-wasm/package.json` committed, `pkg/` ignored.
|
||||
|
||||
### B.3 Docker and CI
|
||||
|
||||
- Worker image built from the skeleton (Alpine musl builder →
|
||||
`distroless/static:nonroot`), started once in CI against the local stack
|
||||
with no job (proves transport configuration, CA bundle, non-root,
|
||||
read-only).
|
||||
- Application image: the wasm stage added and exercised in CI, its output
|
||||
not loaded by the application until R2.
|
||||
- CI job `rust` before `check`: fmt, clippy, test, `cargo deny check
|
||||
licenses bans sources`, wasm build artifact; `docker` job builds both
|
||||
images; registry push by tag and digest prepared (registry decision in
|
||||
D-R13); nightly advisories job; CI duration and runner cache behaviour
|
||||
recorded in `RUST.md`.
|
||||
|
||||
### B.4 Feasibility proofs (experimental, each one a permanent test)
|
||||
|
||||
| Proof | Why it conditions a choice | How | Lives on as |
|
||||
|---|---|---|---|
|
||||
| Panic strategy on wasm32 | III.3 rule 5 (poison and re-instantiate) | a facade call that panics; observe `WebAssembly.RuntimeError`; re-instantiate; call again; try a deep recursion at the configured stack size | vitest in `packages/core-wasm` |
|
||||
| Serialisation contract | D-R11, I.2 (`js_number`, optional vs nullable) | parse `report-v3.demo.json` and `document.json` with serde, re-emit through the custom formatter, compare byte for byte with `JSON.stringify(JSON.parse(x), null, 2)`; a struct with optional and nullable fields parsed by the current Zod schemas | cargo test + vitest N-1 reader seed |
|
||||
| musl static binary with libwebp (`cc`) | D-R4 | build the worker skeleton with `libwebp-sys` on the Alpine builder; log `WebPGetEncoderVersion` | the worker image build in CI |
|
||||
| seccomp allowlist derivation and application | Part IV (traced allowlist, `Threads: 1`, TSYNC) | `decode` spike: minimal `image` decode of one JPEG, one PNG, one WebP at the caps, traced with `strace -f` in the production image under Docker rootless; filter installed before any thread; disallowed syscall kills the child; environment empty | the sandbox test of R1 |
|
||||
| CSP with `'wasm-unsafe-eval'` | D-R13, owner principle "proven before activation" | serve the wasm artifact under the production nginx config with the DEPLOY.md headers in headless Chromium: instantiation succeeds with the keyword, fails without it; result written in DEPLOY.md | CI headless check |
|
||||
| Served size and instantiate time | D-R13 budget | measure raw and gzip bytes of the skeleton module and its instantiate time; set the budget check | CI size check |
|
||||
| Runner caches and build times | VIII.3 | time the cold and warm `rust` job with and without `Swatinem/rust-cache` on the Gitea runner | `RUST.md` numbers |
|
||||
|
||||
### B.5 R0 exit criteria
|
||||
|
||||
`cargo test`, `clippy`, `deny` green in CI through the builder image; worker
|
||||
image < 30 MB, non-root, starts against the local stack; the seven proofs
|
||||
recorded in `RUST.md` with their numbers; `DEPLOY.md` rewritten (pull by
|
||||
digest, CSP line, gzip, VPS headroom, rollback = previous digest) without
|
||||
touching the live deployment; `pnpm check` unchanged; no production
|
||||
artifact changed. Owner validation closes R0; R1 (the Step 8 worker) starts
|
||||
on a separate go.
|
||||
Reference in new issue
Block a user