docs(docs): Step 8 / R1 — files foundation, worker loop, avatar: CLAUDE, DEPLOY (.env.worker, CSP), SUPABASE, RUST, TEST_STRATEGY, WORKSPACE, IDENTITY §5, design README, plan as-built note, CHANGELOG; R1 plan and verifier contract

This commit is contained in:
bchanot committed 2026-10-13 19:39:52 +02:00
1 parent 0c6053c174
commit 62eb4e5d82
13 files changed
+235 -35

No files matched your search

+43 -13
View File
@@ -1,12 +1,13 @@
# 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.
Status: plan R0 (foundation, validated 2026-10-13) and R1 (the Step 8 worker,
2026-10-13, `feature/step-08-files-foundation`). Rule and roadmap:
`RUST_ARCHITECTURE_REVIEW.md` (rule "Rust by default", Part III boundary
rules, Part IV the worker, Part VI phases R0–R5, Annex B R0 scope, Annex C
owner amendments). R0 shipped the toolchain, the workspace skeleton, the
worker's sandboxed child, the browser module loader and seven experimental
proofs; R1 ships the worker's job loop and sweeper for the avatar pipeline
(`STORAGE.md` §3). The frontend does not load the browser module before R2.
## 1. Toolchain: native on the development machine, reproducible in Docker, never on the VPS
@@ -141,11 +142,36 @@ under a 10 s CPU limit.
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)
## 3. The worker (R0 sandboxed child, 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:
sandbox in a single-threaded process. R1 (Step 8) adds the keyed parent:
`run` polls `claim_avatar_jobs` through PostgREST every 2 s, downloads the
quarantine object, feeds it to a `decode` child, uploads the 512 × 512 WebP
at the final key, commits the row (`complete_avatar_job` with the lease
token), deletes the quarantine object, and sweeps (expired uploads, the
purge queue, quarantine leftovers) every 10 minutes. Modules: `config` (env,
secret newtype that no Debug output prints, JWT expiry), `log` (JSON lines,
field allowlist, child stderr escaped and cut at 200 bytes), `keys` (strict
four-segment key shapes validated before any URL), `backend` (trait, closed
`BackendError`), `http` (ureq 3 on rustls + ring with the bundled roots, 30 s
global / 5 s connect timeouts, no redirect, `P0001` bodies → closed
refusals, the Storage API's HTTP 400 + `statusCode` 404 → 404), `decoder`,
`job` (the STORAGE.md §3.4 mapping), `sweep` (§3.5), `watchdog` (per-stage
deadlines, exit 21 on overrun; `Broken` child → exit 20), `run`
(`WORKER_ONCE`, `--check`). Library choice recorded against the review's
Part V list: `ureq` instead of `tokio` + `reqwest`, hand-written JSON lines
instead of `tracing`, a 25-line base64url decoder instead of `base64`: the
loop is sequential, nothing needs an async runtime, and the keyed process
keeps a smaller dependency tree (34 → 84 crates, `aws-lc-rs` absent, no
cmake on Alpine). The decode child's traced syscall set did not change with
the parent's TLS code (§5.4 re-run at R1: the same seven). Image 11.6 MB
(8.7 MB at R0: ring + rustls). Tests: `crates/worker/tests/job_loop.rs` (11,
fake backend + fake decoder) and the module unit tests run natively; the
real-stack end-to-end runs through `pnpm e2e:avatar` (`STORAGE.md` §6).
The sandboxed child, unchanged from R0:
- `decode`: refuses a non-empty environment; checks `Threads: 1` in
`/proc/self/status`; disables core dumps (`PR_SET_DUMPABLE 0`,
@@ -181,8 +207,10 @@ sandbox in a single-threaded process:
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.
variables are set, the linked libwebp version, refused below 1.6.0, the
JWT expiry of the service key); exit 0 when startable or when no worker
variable is set at all, 2 on a partial configuration. `run` starts the loop
(STORAGE.md §3.2 for the variables).
- `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,
@@ -406,8 +434,10 @@ pnpm check:all # everything above bu
- 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.
- HTTPS from the worker: R1 links `ureq` with rustls and the bundled
`webpki-roots` (distroless has no CA bundle; none is needed), but every
run so far targets the local stack over plain HTTP on the Docker network;
the first managed (HTTPS) target proves the roots.
- The forge runner's cache and timings (§5.7), and the workflow files
themselves: no runner exists, none of the three workflows has ever run
(§4).