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:
1 parent
0c6053c174
commit
62eb4e5d82
13 files changed
+235
-35
No files matched your search
+43
-13
@@ -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).
|
||||
|
||||
Reference in new issue
Block a user