feat(workspace): real-stack avatar e2e, compose worker service, STORAGE.md contract

packages/supabase/tests/e2e/avatar-flow.e2e.ts (pnpm e2e:avatar through
scripts/avatar-e2e.sh: worker container on the Supabase network, 5 s sweep,
no quarantine grace; a fresh account per run): clean upload and owner-only
download (Bob, anon, quarantine key, direct final-key write refused),
replacement purged after the grace (queue clock shifted through psql), late
bytes through a still-valid signed upload URL swept, hostile and corrupted
uploads rejected with closed codes, removal with the purge queue drained.
Worker: the Storage API answers a missing object with HTTP 400 and
statusCode 404; normalised to 404 so a purge of a never-written key is acked.
docker-compose.yml: service worker under the worker profile (read-only,
cap_drop ALL, no-new-privileges, 512m, 1 cpu, 64 pids, .env.worker, external
Supabase network). docs/development/STORAGE.md: the implementation contract.
This commit is contained in:
bchanot committed 2026-10-13 19:39:51 +02:00
1 parent 0410af0c35
commit 0c6053c174
7 files changed
+798 -7

No files matched your search

+32 -6
View File
@@ -153,10 +153,12 @@ impl Backend for HttpBackend {
.header("Authorization", &format!("Bearer {}", self.key))
.call()
.map_err(network)?;
if response.status().as_u16() == 404 {
return Ok(());
// A missing object is a purge already done (HTTP 404, or this Storage API's
// HTTP 400 body with statusCode 404, normalised by `classify`).
match expect_success(&mut response) {
Err(BackendError::Status(404)) => Ok(()),
other => other,
}
expect_success(&mut response)
}
fn mark_quarantine_purged(&self, asset_id: &str) -> BackendResult<()> {
@@ -224,15 +226,24 @@ fn expect_success(response: &mut Response<ureq::Body>) -> BackendResult<()> {
Err(classify(status, &text))
}
/// A PostgREST `P0001` body names a closed refusal; any other status is reported as such.
/// A PostgREST `P0001` body names a closed refusal; a Storage API "not found" (HTTP 400
/// with `statusCode` 404 on this image family) is reported as 404; any other status as such.
pub fn classify(status: u16, body: &str) -> BackendError {
if let Ok(value) = serde_json::from_str::<Value>(body)
&& value.get("code").and_then(Value::as_str) == Some("P0001")
let Ok(value) = serde_json::from_str::<Value>(body) else {
return BackendError::Status(status);
};
if value.get("code").and_then(Value::as_str) == Some("P0001")
&& let Some(message) = value.get("message").and_then(Value::as_str)
&& is_closed_code(message)
{
return BackendError::Refused(message.to_owned());
}
if status == 400
&& (value.get("statusCode").and_then(Value::as_str) == Some("404")
|| value.get("error").and_then(Value::as_str) == Some("not_found"))
{
return BackendError::Status(404);
}
BackendError::Status(status)
}
@@ -265,6 +276,21 @@ mod tests {
BackendError::Status(400)
);
assert_eq!(classify(500, "not json"), BackendError::Status(500));
// storage-api v1.79 answers a missing object with HTTP 400 and statusCode "404".
assert_eq!(
classify(
400,
r#"{"statusCode":"404","error":"not_found","message":"Object not found"}"#
),
BackendError::Status(404)
);
assert_eq!(
classify(
400,
r#"{"statusCode":"400","error":"InvalidRequest","message":"x"}"#
),
BackendError::Status(400)
);
}
#[test]
+32
View File
@@ -13,3 +13,35 @@ services:
env_file:
- .env
restart: unless-stopped
# Files worker (plan Step 8 / Rust R1, docs/development/STORAGE.md §3): the keyed
# job loop and the keyless decode child, one static binary on distroless. Started
# only with the `worker` profile: `docker compose --profile worker up -d worker`.
# It joins the Supabase compose network (never a published port) and reads its
# own env file, separate from the app's: SUPABASE_URL, SUPABASE_SERVICE_ROLE_KEY,
# WORKER_ID (chmod 600, excluded from any backup copy of env files).
worker:
container_name: faunosteo_worker
profiles: ["worker"]
build:
context: .
dockerfile: crates/worker/Dockerfile
image: faunosteo_worker:local
env_file:
- .env.worker
command: ["run"]
read_only: true
cap_drop: [ALL]
security_opt:
- no-new-privileges:true
mem_limit: 512m
cpus: 1
pids_limit: 64
networks:
- supabase
restart: unless-stopped
networks:
supabase:
external: true
# Local CLI stack: supabase_network_faunosteo; self-hosted compose: its own name.
name: ${SUPABASE_NETWORK:-supabase_network_faunosteo}
+327
View File
@@ -0,0 +1,327 @@
# Files foundation: Supabase Storage, the `assets` table and the Rust worker
Status: Step 8 / Rust R1, 2026-10-13, branch `feature/step-08-files-foundation`.
Design origin: `STEP8_FILES_ANALYSIS.md` (D1 to D9 validated by the owner, D1
amended to the Rust worker of `RUST_ARCHITECTURE_REVIEW.md` Part IV). This
file is the implementation contract: table, keys, RPCs, policies, worker
behaviour and client flow are what the code and the tests pin.
First consumer: the profile photo (avatar). Every other bucket exists, closed.
---
## 1. Model
### 1.1 Statuses
```text
pending_upload ─(confirm_asset_upload)─► uploaded ─(complete_avatar_job)─► clean
│ │
│ begin supersedes / 24 h expiry ├─(reject_avatar_job, 3rd expired lease)─► rejected
▼ ▼
deleted ◄──────(remove_avatar, replacement by a newer clean row, begin supersedes)
```
`deleted` and `rejected` are terminal: the row stays (history, purge
bookkeeping) and matches no read or upload predicate.
### 1.2 `public.assets`
| Column | Type | Rule |
|---|---|---|
| `id` | uuid pk | |
| `owner_id` | uuid → `profiles.id` on delete cascade | |
| `kind` | text | `'profile_avatar'` only in Step 8 (CHECK) |
| `bucket_id` | text | `'avatars'` for that kind (CHECK) |
| `object_key` | text unique | final key, server-built: `profiles/<owner_id>/<id>/avatar.webp` |
| `quarantine_key` | text | `quarantine/<owner_id>/<id>/upload`; null once the worker confirmed the quarantine object is gone |
| `status` | `public.asset_status` | enum above |
| `declared_mime` | text | `image/jpeg`, `image/png`, `image/webp` (CHECK) |
| `declared_size` | integer | 1 … 5 242 880 (CHECK), the transport size announced by the browser |
| `byte_size`, `sha256` | integer, text | the clean output, set by `complete_avatar_job` |
| `rejection_reason` | text | closed set `unsupported_type`, `decode_failed`, `dimensions`, `processing_error`; non-null iff `rejected` (CHECK) |
| `attempts` | smallint | leases taken; the 3rd expired lease rejects with `processing_error` |
| `locked_at`, `lock_token` | timestamptz, uuid | the lease: set by `claim_avatar_jobs`, required by `complete` / `reject`, 10 min validity |
| `created_at`, `updated_at` | timestamptz | trigger `set_updated_at` |
Indexes: unique partial `assets_one_clean_avatar (owner_id) where kind =
'profile_avatar' and status = 'clean'` ("the" avatar of an account is its
single clean row: no profile column, D5); `assets_claimable (created_at)
where status = 'uploaded'`; `assets_owner_idx (owner_id, created_at desc)`.
Privileges: `revoke all` from `public`, `anon`, `authenticated`; `grant
select (id, owner_id, kind, bucket_id, object_key, status, declared_mime,
declared_size, byte_size, sha256, rejection_reason, created_at, updated_at)`
to `authenticated` (the lease columns and `quarantine_key` stay server-side;
a client must list its columns, `select=*` is refused). RLS
`assets_select_own` (`owner_id = auth.uid()`). No INSERT / UPDATE / DELETE
policy: every write is an RPC.
### 1.3 Buckets (all private)
| Bucket | Step 8 state |
|---|---|
| `avatars` | open: SELECT + INSERT policies through `assets`, 5 MiB, `image/jpeg`, `image/png`, `image/webp` |
| `logos`, `professional-documents`, `client-files`, `animal-files`, `report-files`, `imports` | closed: row exists, `public = false`, no policy names it, no cap or MIME list yet (their step sets them) |
| `anatomical-sheet-assets` | untouched (migration `20261009100000`, read through the sheet) |
The migration upserts the rows (`on conflict (id) do update set public =
false`) so it converges on the local stack, the VPS and a managed project.
### 1.4 Keys
- Built by `begin_avatar_upload` from uuids; the user's filename never
reaches the server; one canonical name per kind (`avatar.webp`).
- Policies compare whole strings (`name = quarantine_key`, `name =
object_key`): no prefix match, no `storage.foldername()`, so PGlite and the
real stack evaluate the same expression.
- The worker validates every key it receives from the database before
putting it in a URL: exactly four segments, `profiles|quarantine`, two
uuids, `avatar.webp|upload`.
---
## 2. RPCs
Every function is `security definer`, `set search_path = ''`, authorisation
before lookup, EXECUTE revoked from `public` / `anon` / `authenticated` and
granted to the one role that calls it. Business refusals raise SQLSTATE
`P0001` with the closed code as the message (PostgREST answers 400 with
`{"code":"P0001","message":"<code>"}`); authorisation refusals raise
`42501` (403).
### 2.1 Browser (`authenticated`)
| RPC | Effect | Refusals (message) |
|---|---|---|
| `begin_avatar_upload(declared_mime text, declared_size integer) returns jsonb` | locks the caller's `profiles` row (`for update`); checks the type and the size; rate: at most 10 rows created by the caller in the last hour, every status counted; global ceiling: `sum(declared_size)` of non-deleted rows below `private.storage_ceiling()` (10 GiB); supersedes the caller's `pending_upload` / `uploaded` rows (→ `deleted`); inserts the row; returns `{"asset_id", "bucket_id", "quarantine_key"}` | `unsupported_type`, `too_large`, `rate_limited`, `storage_full` |
| `confirm_asset_upload(asset_id uuid) returns void` | own `pending_upload` row with a `storage.objects` row at `(bucket_id, quarantine_key)` whose `metadata->>'size'` is within the cap → `uploaded` | `not_found` (unknown or not own), `invalid_state` (not pending), `upload_missing` (no object yet), `too_large` (object over the cap: the row is deleted) |
| `remove_avatar() returns integer` | every `profile_avatar` row of the caller in `pending_upload` / `uploaded` / `clean` → `deleted`; returns the count; logs `asset.avatar_removed` | none (0 rows is fine) |
`auth.uid() is null` → `42501` on all three.
### 2.2 Worker (`service_role`)
| RPC | Effect |
|---|---|
| `claim_avatar_jobs(max_jobs integer) returns table (asset_id, owner_id, bucket_id, object_key, quarantine_key, lock_token, attempts)` | first rejects (`processing_error`) every `uploaded` row whose lease expired with `attempts >= 3`; then claims `uploaded` rows with `locked_at is null or locked_at < now() - 10 min` and `attempts < 3`, oldest first, `for update skip locked`, at most `max_jobs` (capped at 10): `locked_at = now()`, `attempts + 1`, fresh `lock_token`. VOLATILE (a STABLE function would run read-only through PostgREST) |
| `complete_avatar_job(asset_id uuid, lock_token uuid, byte_size integer, sha256 text) returns void` | guard: `status = 'uploaded'` and the token matches, else `invalid_state`. In one transaction: the owner's previous `clean` avatar → `deleted` (trigger enqueues its object 48 h later), the row → `clean` with `byte_size` / `sha256`, lease cleared; logs `asset.avatar_set` (actor null = worker, target = owner) |
| `reject_avatar_job(asset_id uuid, lock_token uuid, reason text) returns void` | same guard; `reason` in the closed set else `invalid_reason`; → `rejected`; logs `asset.rejected` with the reason |
| `mark_quarantine_purged(asset_id uuid) returns void` | `clean` row → `quarantine_key = null` (after the worker deleted the quarantine object); other statuses: no-op |
| `claim_purges(max_items integer) returns table (purge_id, bucket_id, object_name)` | queue rows with `not_before <= now()` and no live lease (`locked_at` null or older than 10 min), `for update skip locked`, at most `max_items` (capped at 100); sets `locked_at` |
| `ack_purge(purge_id uuid) returns void` | deletes the queue row (a missing object counted as success by the worker) |
| `claim_quarantine_leftovers(older_than_seconds integer, max_items integer) returns table (bucket_id, object_name, asset_id)` | `storage.objects` under `quarantine/` in `avatars`, created before `now() - older_than`, whose row is not `pending_upload` / `uploaded` (anti-join on `quarantine_key`); `asset_id` is the matching row when one exists (the worker calls `mark_quarantine_purged` for a `clean` one) |
| `expire_pending_uploads(max_age_seconds integer) returns integer` | `pending_upload` rows older than the age → `deleted` (trigger enqueues their keys); returns the count |
The three stale-task guards together: a superseded or removed row is
`deleted` (never `uploaded`, so no `complete`); a `complete` from an expired
lease carries a stale `lock_token` and is refused even while the row is
still `uploaded`; the purge of an old key never touches a newer row's
object (keys embed the asset id).
### 2.3 `storage.objects` policies (bucket `avatars`)
| Policy | Command | Expression |
|---|---|---|
| `avatars_read` | SELECT, `authenticated` | `bucket_id = 'avatars' and private.can_read_avatar_object((select auth.uid()), name)` = a `clean` row of the caller with `object_key = name` |
| `avatars_upload` | INSERT, `authenticated` | `bucket_id = 'avatars' and private.can_upload_avatar_object((select auth.uid()), name)` = a `pending_upload` row of the caller with `quarantine_key = name` |
No UPDATE / DELETE policy exists for any API role. The pgTAP census asserts
that every policy on `storage.objects` pins exactly one bucket literal and
counts them: 2 on `avatars`, 1 on `anatomical-sheet-assets`, 0 elsewhere,
total 3.
### 2.4 Purge queue (`private.object_purge_queue`)
`(id, bucket_id, object_name, not_before, enqueued_at, locked_at, attempts)`,
unique on `(bucket_id, object_name)` (a second enqueue keeps the earliest
`not_before`). Fed by triggers on `assets`:
| Transition | `object_key` | `quarantine_key` |
|---|---|---|
| → `deleted` | `now() + 48 h` | `now() + 1 h` |
| → `rejected` | `now() + 1 h` (a clean object may exist after a PUT before a 3rd expired lease) | `now() + 1 h` |
| row DELETE (account cascade) | `now() + 48 h` | `now() + 1 h` |
A `clean` row's `object_key` is never enqueued (test). The 48 h grace is the
backup invariant of §5.
---
## 3. The worker (`crates/worker`, container `faunosteo_worker`)
### 3.1 Process model
One static musl binary, two roles in one container:
- `faunosteo-worker run`: the keyed parent. Holds `SUPABASE_SERVICE_ROLE_KEY`,
talks to PostgREST and the Storage API over HTTP, never decodes a pixel.
- `faunosteo-worker decode`: the child spawned per job by the parent with an
empty environment and piped stdin/stdout (R0 sandbox unchanged: `Threads:
1`, no core dump, `RLIMIT_AS` 512 MiB, `RLIMIT_CPU` 10 s / 12 s, seccomp
allowlist, 5 MiB input, 512 KiB output, 20 s deadline). It sees no key,
no file, no network.
The parent checks the child's output at container level only
(`webp_check`: RIFF structure, chunk allowlist, 512 × 512 canvas, no
metadata chunk), hashes it and uploads it.
### 3.2 Configuration (environment of the parent only)
| Variable | Required | Default | Meaning |
|---|---|---|---|
| `SUPABASE_URL` | yes | | origin of the stack (`http://supabase_kong_faunosteo:8000` from the Supabase compose network, `http://127.0.0.1:54321` natively) |
| `SUPABASE_SERVICE_ROLE_KEY` | yes | | the service key; never printed; the JWT `exp` claim, when the key is a JWT, is logged at start and warned about 30 days ahead |
| `WORKER_ID` | no | `worker-<pid>` | tag of every log line |
| `WORKER_POLL_SECONDS` | no | `2` | idle interval between claims |
| `WORKER_SWEEP_SECONDS` | no | `600` | interval of the sweeper |
| `WORKER_QUARANTINE_GRACE_SECONDS` | no | `10800` | age before a quarantine leftover is deleted (above the 2 h validity of a signed upload URL) |
| `WORKER_PENDING_MAX_AGE_SECONDS` | no | `86400` | age before a never-confirmed `pending_upload` row is expired |
| `WORKER_ONCE` | no | unset | `1` = one claim pass and one sweep, then exit (tests) |
`faunosteo-worker run --check` prints the resolved configuration without
any secret value. Exit 0 when the worker could start (libwebp ≥ 1.6.0, both
required variables set, URL parseable) or when no worker variable is set at
all (an unconfigured image is a valid artifact check, `scripts/check-all.sh`);
a partial or invalid configuration exits 2 naming the variable, a too-old
libwebp exits 18.
### 3.3 HTTP endpoints used (service key: `apikey` and `Authorization: Bearer`)
| Call | Request |
|---|---|
| RPC | `POST <url>/rest/v1/rpc/<name>`, JSON body, `Content-Type: application/json`, `Prefer: return=representation` |
| download quarantine | `GET <url>/storage/v1/object/<bucket>/<key>`, body read with a 5 MiB + 1 cap; a body over the cap (impossible through the bucket cap and `confirm_asset_upload`, kept as a guard) is a content refusal: the row is rejected `decode_failed` and the worker logs `download_overflow` |
| upload clean | `POST <url>/storage/v1/object/<bucket>/<key>`, `Content-Type: image/webp`, `x-upsert: true` (idempotent on retry) |
| delete object | `DELETE <url>/storage/v1/object/<bucket>/<key>` (a missing object counts as done: HTTP 404, or the HTTP 400 with `statusCode` 404 this Storage API version answers) |
Every call: 30 s global timeout, 5 s connect timeout, no redirect follow,
`http_status_as_error(false)` so each status is classified by the caller.
Keys are validated (§1.4) before any URL is built.
### 3.4 One job
```text
claim_avatar_jobs(1) stage claim deadline 35 s
GET quarantine stage download 35 s 404 → reject decode_failed (bytes never landed; the row said uploaded)
spawn decode child, feed bytes stage decode 25 s
Produced(webp) → POST clean (upsert) → complete_avatar_job(asset, token, size, sha256)
stage upload 35 s, stage commit 35 s
→ DELETE quarantine → mark_quarantine_purged (best effort: the sweeper finishes it)
Rejected{code} → reject_avatar_job(asset, token, code) code ∈ unsupported_type | decode_failed | dimensions | resource_limit→decode_failed
Signalled / Timeout / OutputOverflow / Failed
→ reject_avatar_job(asset, token, 'processing_error') (logged with signal number / detail)
Broken{code} → log level=error event=child_broken, leave the lease (the row is retried, 3rd lease rejects), stop the loop with exit code 20
complete refused (invalid_state: superseded, removed, stale lease)
→ log, delete nothing: the purge queue owns every object of a terminal row
```
Every network failure in a stage leaves the row to its lease (re-claimed
after 10 min, rejected `processing_error` on the 3rd expiry). A stage that
exceeds its deadline makes the watchdog thread exit the process (code 21);
Docker's restart policy brings it back.
### 3.5 Sweeper (every `WORKER_SWEEP_SECONDS`, and once at start)
1. `expire_pending_uploads(WORKER_PENDING_MAX_AGE_SECONDS)`.
2. `claim_purges(100)` → DELETE each object (404 = done) → `ack_purge`.
3. `claim_quarantine_leftovers(WORKER_QUARANTINE_GRACE_SECONDS, 100)` →
DELETE each object → `mark_quarantine_purged(asset_id)` when present.
Those are the only deletions the worker ever makes: a key it did not get
from the queue or the leftover query is never deleted.
### 3.6 Logs
One JSON object per line on stdout, fields from an allowlist only: `ts`,
`level`, `event`, `worker_id`, `asset_id`, `stage`, `code`, `signal`,
`http_status`, `duration_ms`, `count`, `detail` (worker-authored text only).
The child's stderr is child-controlled: it is logged under `child_stderr`
JSON-escaped and truncated to 200 bytes, never raw. No key, no URL with a
token, no user content.
---
## 4. Client flow (browser, anon key + user JWT)
1. Pick: `<input type="file" accept="image/jpeg,image/png,image/webp">`.
The first bytes are sniffed (`FF D8 FF`, PNG signature, `RIFF….WEBP`);
anything else, SVG included, is refused with `unsupported_type` before
any decode. `File.size` over 20 MiB → `too_large`.
2. Transport: `createImageBitmap` → canvas with the longest side at 1024 px
→ `toBlob('image/jpeg', 0.9)`; over 5 MiB after that → `too_large`.
The preview shows that blob. Nothing uploaded yet.
3. "Enregistrer la photo": `begin_avatar_upload('image/jpeg', blob.size)` →
`storage.from('avatars').upload(quarantine_key, blob, { upsert: false,
contentType: 'image/jpeg' })` → `confirm_asset_upload(asset_id)`.
4. Poll the own row every 1 s, 30 s at most: `clean` → download
`object_key` (`storage.from('avatars').download`), keep a blob URL in the
auth store; `rejected` → message per code; still `uploaded` after 30 s →
"processing, come back later" (the next mount polls again).
5. "Supprimer la photo": confirmation dialog → `remove_avatar()` → monogram.
Closed failure kinds the UI phrases (`AssetFailure.kind`): `too_large`,
`unsupported_type`, `rate_limited`, `storage_full`, `upload_missing`,
`invalid_state`, `not_found`, `network`, `unknown`; rejection codes of a row:
`unsupported_type`, `decode_failed`, `dimensions`, `processing_error`.
No signed URL, no bearer token: the download runs under the SELECT policy
and stops at the row flip (D7). The production CSP already allows `blob:`
images; `connect-src` must name the Supabase origin (DEPLOY.md).
---
## 5. Operations
### 5.1 Reconciliation (read-only, operator)
```sql
-- objects without a row (any status) and rows whose object is missing
select o.bucket_id, o.name from storage.objects o
where o.bucket_id = 'avatars'
and not exists (select 1 from public.assets a where a.object_key = o.name or a.quarantine_key = o.name);
select a.id, a.object_key from public.assets a
where a.status = 'clean'
and not exists (select 1 from storage.objects o where o.bucket_id = a.bucket_id and o.name = a.object_key);
```
Deletions stay row-driven (queue and leftover sweep); the query only reports.
### 5.2 Backups (self-hosted, file backend)
Order: database dump first (whole instance, `storage` schema included),
files second, within 48 h of each other. With the 48 h purge grace every
`clean` row of the dump still has its object in the file snapshot (the
invariant the restore checks with the second query above). Restore: stop
the worker, restore the database, restore the volume, run the
reconciliation, start the worker. Tooling (restic, retention, drill) is the
deployment runbook's (plan Step 27).
### 5.3 Managed migration
Same migrations (`supabase db push`); rows (`auth.users`, `public`), then the
objects driven by the rows (`clean` rows and confirmed sheet assets:
download, verify sha256, upload at the same key, verify), write freeze while
copying (worker stopped), reconciliation on the destination, switch
`SUPABASE_URL` and the keys of the app and the worker.
---
## 6. Development
```bash
pnpm db:start # local stack (migrations + seed)
pnpm worker:image # faunosteo_worker:dev
docker run --rm --read-only --cap-drop ALL --security-opt no-new-privileges:true \
--network supabase_network_faunosteo \
-e SUPABASE_URL=http://supabase_kong_faunosteo:8000 \
-e SUPABASE_SERVICE_ROLE_KEY="$(pnpm -s supabase status -o env | sed -n 's/^SERVICE_ROLE_KEY="\(.*\)"/\1/p')" \
faunosteo_worker:dev run
pnpm --filter @faunosteo/supabase test:e2e # real-stack end-to-end (needs the worker above)
pnpm e2e:avatar # scripts/avatar-e2e.sh: the three lines above in one, worker started with a 5 s sweep and no quarantine grace
```
`docker compose --profile worker up worker` runs the same container from
`docker-compose.yml` with `.env.worker` (`SUPABASE_URL`,
`SUPABASE_SERVICE_ROLE_KEY`, `WORKER_ID`; `chmod 600`, never in the app
`.env`, never in a backup of env files).
+2 -1
View File
@@ -37,7 +37,8 @@
"wasm:build": "bash scripts/wasm-build.sh",
"wasm:build:docker": "bash docker/rust-run.sh bash scripts/wasm-build.sh",
"worker:test": "docker build -f crates/worker/Dockerfile --target test -t faunosteo_worker:test .",
"worker:image": "docker build -f crates/worker/Dockerfile -t faunosteo_worker:dev ."
"worker:image": "docker build -f crates/worker/Dockerfile -t faunosteo_worker:dev .",
"e2e:avatar": "bash scripts/avatar-e2e.sh"
},
"devDependencies": {
"pnpm": "10.13.1",
@@ -0,0 +1,331 @@
/**
* Avatar flow against the real local stack and the worker container
* (docs/development/STORAGE.md §4, §3; STEP8_FILES_ANALYSIS IV.2 "integration"
* and "real-stack e2e"). Run through `pnpm e2e:avatar` (scripts/avatar-e2e.sh),
* which starts the worker with a 5 s sweep and a 0 s quarantine grace.
*
* Environment: SUPABASE_URL, SUPABASE_ANON_KEY, SUPABASE_SERVICE_ROLE_KEY
* (the service key is used for inspection only: listing objects and shifting
* the purge clock through psql in the database container).
*/
import { createHash } from 'node:crypto'
import { execFileSync } from 'node:child_process'
import { deflateSync } from 'node:zlib'
import { createClient, type SupabaseClient } from '@supabase/supabase-js'
import {
beginAvatarUpload,
confirmAssetUpload,
downloadAvatar,
fetchOwnAvatarState,
removeAvatar,
uploadToQuarantine,
type AssetRow,
type Database,
} from '../../src'
const URL_ = process.env.SUPABASE_URL
const ANON = process.env.SUPABASE_ANON_KEY
const SERVICE = process.env.SUPABASE_SERVICE_ROLE_KEY
const DB_CONTAINER = process.env.AVATAR_E2E_DB_CONTAINER ?? 'supabase_db_faunosteo'
const PASSWORD = 'LocalDev-only-password-1'
const BOB = 'bob@faunosteo.local'
const WORKER_WAIT_MS = 60_000
type Client = SupabaseClient<Database>
function anonClient(): Client {
return createClient<Database>(URL_ ?? '', ANON ?? '', {
auth: { persistSession: false, autoRefreshToken: false },
})
}
async function signedIn(email: string): Promise<Client> {
const client = anonClient()
const { error } = await client.auth.signInWithPassword({ email, password: PASSWORD })
if (error) throw new Error(`sign-in ${email}: ${error.message}`)
return client
}
function serviceClient(): Client {
return createClient<Database>(URL_ ?? '', SERVICE ?? '', {
auth: { persistSession: false, autoRefreshToken: false },
})
}
// --- fixtures ---------------------------------------------------------------
const CRC_TABLE = new Uint32Array(256).map((_, n) => {
let c = n
for (let k = 0; k < 8; k++) c = c & 1 ? 0xedb88320 ^ (c >>> 1) : c >>> 1
return c >>> 0
})
function crc32(bytes: Uint8Array): number {
let c = 0xffffffff
for (const b of bytes) c = CRC_TABLE[(c ^ b) & 0xff] ^ (c >>> 8)
return (c ^ 0xffffffff) >>> 0
}
function chunk(type: string, payload: Uint8Array): Uint8Array {
const out = new Uint8Array(12 + payload.length)
const view = new DataView(out.buffer)
view.setUint32(0, payload.length)
out.set(Buffer.from(type, 'ascii'), 4)
out.set(payload, 8)
const crc = crc32(out.subarray(4, 8 + payload.length))
view.setUint32(8 + payload.length, crc)
return out
}
/** A valid RGBA PNG gradient of the given size (no dependency, like the worker's fixtures). */
function png(width: number, height: number): Uint8Array {
const raw = new Uint8Array(height * (1 + width * 4))
for (let y = 0; y < height; y++) {
const row = y * (1 + width * 4)
raw[row] = 0
for (let x = 0; x < width; x++) {
const i = row + 1 + x * 4
raw[i] = (x * 255) / width
raw[i + 1] = (y * 255) / height
raw[i + 2] = 128
raw[i + 3] = 255
}
}
const ihdr = new Uint8Array(13)
const view = new DataView(ihdr.buffer)
view.setUint32(0, width)
view.setUint32(4, height)
ihdr.set([8, 6, 0, 0, 0], 8)
return Buffer.concat([
Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]),
chunk('IHDR', ihdr),
chunk('IDAT', deflateSync(raw)),
chunk('IEND', new Uint8Array(0)),
])
}
const asBlob = (bytes: Uint8Array, type: string) => new Blob([Uint8Array.from(bytes)], { type })
// --- helpers ----------------------------------------------------------------
async function waitFor<T>(
read: () => Promise<T | null>,
timeoutMs: number,
label: string,
): Promise<T> {
const started = Date.now()
for (;;) {
const value = await read()
if (value !== null) return value
if (Date.now() - started > timeoutMs) throw new Error(`timeout: ${label}`)
await new Promise((r) => setTimeout(r, 1000))
}
}
async function ownRow(client: Client, userId: string, assetId: string): Promise<AssetRow | null> {
const { data, error } = await client
.from('assets')
.select('id, owner_id, kind, bucket_id, object_key, status, declared_mime, declared_size, byte_size, sha256, rejection_reason, created_at, updated_at')
.eq('owner_id', userId)
.eq('id', assetId)
.maybeSingle()
if (error) throw new Error(error.message)
return data
}
/** Row once the worker has settled it (clean or rejected). */
function settled(client: Client, userId: string, assetId: string) {
return waitFor(
async () => {
const row = await ownRow(client, userId, assetId)
return row && (row.status === 'clean' || row.status === 'rejected') ? row : null
},
WORKER_WAIT_MS,
`worker verdict on ${assetId}`,
)
}
/** Upload one blob end to end and return the settled row. */
async function uploadAndSettle(
client: Client,
userId: string,
blob: Blob,
declaredMime: 'image/jpeg' | 'image/png' | 'image/webp',
): Promise<AssetRow> {
const ticket = await beginAvatarUpload(client, { declaredMime, declaredSize: blob.size })
await uploadToQuarantine(client, { ...ticket, blob })
await confirmAssetUpload(client, ticket.assetId)
return settled(client, userId, ticket.assetId)
}
/** True when the service role can still download the object (it bypasses the policies). */
async function objectExists(service: Client, bucket: string, key: string): Promise<boolean> {
const { data, error } = await service.storage.from(bucket).download(key)
return !error && data !== null && data.size > 0
}
function psql(sql: string): string {
return execFileSync('docker', [
'exec', DB_CONTAINER, 'psql', '-U', 'postgres', '-d', 'postgres', '-Atc', sql,
]).toString().trim()
}
/** Moves every due date of the purge queue to now (the grace is 48 h / 1 h in production). */
function expeditePurges(): void {
psql('update private.object_purge_queue set not_before = now() where not_before > now()')
}
/** Purge entries still queued for an account (served entries are acked, hence deleted). */
function queuedPurges(userId: string): number {
return Number(psql(`select count(*) from private.object_purge_queue where object_name like '%/${userId}/%'`))
}
async function downloadFails(client: Client, key: string): Promise<boolean> {
const { data, error } = await client.storage.from('avatars').download(key)
return Boolean(error) || data === null
}
function sha256(bytes: Uint8Array): string {
return createHash('sha256').update(bytes).digest('hex')
}
// --- suite ------------------------------------------------------------------
const configured = Boolean(URL_ && ANON && SERVICE)
describe.skipIf(!configured)('avatar flow on the real stack', () => {
const service = serviceClient()
let alice: Client
let aliceId: string
let bob: Client
beforeAll(async () => {
// A fresh account per run keeps the seeded accounts clean and the per-hour rate out of reach.
const email = `e2e-avatar-${Date.now()}@faunosteo.local`
const created = await service.auth.admin.createUser({
email,
password: PASSWORD,
email_confirm: true,
user_metadata: { display_name: 'E2E Avatar', locale: 'fr' },
})
if (created.error || !created.data.user) throw new Error(`createUser: ${created.error?.message}`)
aliceId = created.data.user.id
alice = await signedIn(email)
bob = await signedIn(BOB)
})
afterAll(async () => {
if (aliceId) await service.auth.admin.deleteUser(aliceId)
})
it('cleans a valid upload, and only the owner can download the result', async () => {
const source = png(640, 480)
const row = await uploadAndSettle(alice, aliceId, asBlob(source, 'image/png'), 'image/png')
expect(row.status).toBe('clean')
const blob = await downloadAvatar(alice, row.object_key)
const bytes = new Uint8Array(await blob.arrayBuffer())
expect(Buffer.from(bytes.subarray(0, 4)).toString('ascii')).toBe('RIFF')
expect(Buffer.from(bytes.subarray(8, 12)).toString('ascii')).toBe('WEBP')
expect(row.byte_size).toBe(bytes.length)
expect(row.sha256).toBe(sha256(bytes))
expect(bytes.length).toBeLessThan(512 * 1024)
const quarantineKey = `quarantine/${aliceId}/${row.id}/upload`
expect(await downloadFails(alice, quarantineKey)).toBe(true)
expect(await downloadFails(bob, row.object_key)).toBe(true)
expect(await downloadFails(anonClient(), row.object_key)).toBe(true)
const bobRows = await bob.from('assets').select('id').eq('owner_id', aliceId)
expect(bobRows.data).toEqual([])
const direct = await alice.storage.from('avatars').upload(row.object_key, asBlob(source, 'image/png'), {
upsert: false,
contentType: 'image/png',
})
expect(direct.error).not.toBeNull()
// The worker deleted the quarantine object once the row was clean.
await waitFor(
async () => ((await objectExists(service, 'avatars', quarantineKey)) ? null : true),
30_000,
'quarantine object deleted',
)
})
it('replaces the photo and purges the previous object after its grace', async () => {
const before = await fetchOwnAvatarState(alice, aliceId)
const previous = before.clean
expect(previous).not.toBeNull()
const row = await uploadAndSettle(alice, aliceId, asBlob(png(300, 700), 'image/png'), 'image/png')
expect(row.status).toBe('clean')
const state = await fetchOwnAvatarState(alice, aliceId)
expect(state.clean?.id).toBe(row.id)
expect(await downloadFails(alice, previous!.object_key)).toBe(true)
expect(await objectExists(service, 'avatars', previous!.object_key)).toBe(true)
expeditePurges()
await waitFor(
async () => ((await objectExists(service, 'avatars', previous!.object_key)) ? null : true),
30_000,
'replaced object purged after its grace',
)
})
it('sweeps bytes landed through a still-valid signed upload URL after the row moved on', async () => {
const stale = await beginAvatarUpload(alice, { declaredMime: 'image/png', declaredSize: 1000 })
const signed = await alice.storage.from('avatars').createSignedUploadUrl(stale.quarantineKey)
expect(signed.error).toBeNull()
// A new pick supersedes the row; the signed URL is still valid for two hours.
const fresh = await beginAvatarUpload(alice, { declaredMime: 'image/png', declaredSize: 1000 })
expect(fresh.assetId).not.toBe(stale.assetId)
const late = await alice.storage
.from('avatars')
.uploadToSignedUrl(stale.quarantineKey, signed.data!.token, asBlob(png(100, 100), 'image/png'), {
contentType: 'image/png',
})
// Either the API refused the late upload, or the sweeper removes the leftover.
if (!late.error) {
await waitFor(
async () => ((await objectExists(service, 'avatars', stale.quarantineKey)) ? null : true),
30_000,
'late quarantine bytes swept',
)
}
const staleRow = await ownRow(alice, aliceId, stale.assetId)
expect(staleRow?.status).toBe('deleted')
expect(await downloadFails(alice, stale.quarantineKey)).toBe(true)
})
it('rejects hostile and corrupted uploads with closed codes', async () => {
const html = Buffer.from('<!doctype html><script>alert(1)</script>')
const htmlRow = await uploadAndSettle(alice, aliceId, asBlob(html, 'image/jpeg'), 'image/jpeg')
expect(htmlRow.status).toBe('rejected')
expect(htmlRow.rejection_reason).toBe('unsupported_type')
const truncated = png(200, 200).subarray(0, 80)
const truncatedRow = await uploadAndSettle(alice, aliceId, asBlob(truncated, 'image/png'), 'image/png')
expect(truncatedRow.status).toBe('rejected')
expect(truncatedRow.rejection_reason).toBe('decode_failed')
const tinyRow = await uploadAndSettle(alice, aliceId, asBlob(png(32, 32), 'image/png'), 'image/png')
expect(tinyRow.status).toBe('rejected')
expect(tinyRow.rejection_reason).toBe('dimensions')
})
it('removes the photo, cuts the download at once and empties the objects after the grace', async () => {
const row = await uploadAndSettle(alice, aliceId, asBlob(png(512, 512), 'image/png'), 'image/png')
expect(row.status).toBe('clean')
expect(await removeAvatar(alice)).toBeGreaterThanOrEqual(1)
expect(await downloadFails(alice, row.object_key)).toBe(true)
const state = await fetchOwnAvatarState(alice, aliceId)
expect(state.clean).toBeNull()
expeditePurges()
await waitFor(
async () => {
const listed = await service.storage.from('avatars').list(`profiles/${aliceId}`, { limit: 100 })
const remaining = (listed.data ?? []).length
return remaining === 0 ? true : null
},
30_000,
'every object of the account purged',
)
// Every served entry was acked, a missing object counting as purged.
await waitFor(async () => (queuedPurges(aliceId) === 0 ? true : null), 30_000, 'purge queue drained')
})
})
+17
View File
@@ -0,0 +1,17 @@
import { defineConfig } from 'vitest/config'
/**
* Real-stack end-to-end suite (tests/e2e/*.e2e.ts): needs the local Supabase
* stack and the worker container (scripts/avatar-e2e.sh starts both sides).
* Kept out of the default `test:run` include on purpose.
*/
export default defineConfig({
test: {
environment: 'node',
globals: true,
include: ['tests/e2e/**/*.e2e.ts'],
fileParallelism: false,
testTimeout: 120_000,
hookTimeout: 120_000,
},
})
+57
View File
@@ -0,0 +1,57 @@
#!/usr/bin/env bash
# Real-stack end-to-end run of the avatar flow (docs/development/STORAGE.md §6):
# starts the worker container against the local Supabase stack with a fast sweep
# and no quarantine grace, runs packages/supabase/tests/e2e, stops the container.
# Needs: `pnpm db:start` done, Docker, the worker image (`pnpm worker:image`,
# built here when absent). The keys come from `supabase status`; the service key
# reaches the container through a 600-mode temporary env file, never the command line.
set -euo pipefail
cd "$(dirname "$0")/.."
network="${SUPABASE_NETWORK:-supabase_network_faunosteo}"
kong="${SUPABASE_INTERNAL_URL:-http://supabase_kong_faunosteo:8000}"
image="${WORKER_IMAGE:-faunosteo_worker:dev}"
name="faunosteo_worker_e2e"
status="$(node_modules/.bin/supabase status -o env 2>/dev/null)" \
|| { echo "avatar-e2e: the local stack is not running (pnpm db:start)" >&2; exit 1; }
value() { printf '%s\n' "$status" | sed -n "s/^$1=\"\(.*\)\"$/\1/p"; }
api_url="$(value API_URL)"
anon_key="$(value ANON_KEY)"
service_key="$(value SERVICE_ROLE_KEY)"
[ -n "$api_url" ] && [ -n "$anon_key" ] && [ -n "$service_key" ] \
|| { echo "avatar-e2e: could not read the keys from supabase status" >&2; exit 1; }
if ! docker image inspect "$image" >/dev/null 2>&1; then
echo "== building $image"
docker build -f crates/worker/Dockerfile -t "$image" .
fi
env_file="$(mktemp)"
chmod 600 "$env_file"
cleanup() {
echo "== worker log (last lines)"
docker logs --tail 40 "$name" 2>/dev/null || true
docker rm -f "$name" >/dev/null 2>&1 || true
rm -f "$env_file"
}
trap cleanup EXIT
{
echo "SUPABASE_URL=$kong"
echo "SUPABASE_SERVICE_ROLE_KEY=$service_key"
echo "WORKER_ID=e2e"
echo "WORKER_POLL_SECONDS=1"
echo "WORKER_SWEEP_SECONDS=5"
echo "WORKER_QUARANTINE_GRACE_SECONDS=0"
} > "$env_file"
docker rm -f "$name" >/dev/null 2>&1 || true
echo "== starting $name on $network"
docker run -d --name "$name" --read-only --cap-drop ALL \
--security-opt no-new-privileges:true --memory 512m --cpus 1 --pids-limit 64 \
--network "$network" --env-file "$env_file" "$image" run >/dev/null
echo "== e2e suite"
SUPABASE_URL="$api_url" SUPABASE_ANON_KEY="$anon_key" SUPABASE_SERVICE_ROLE_KEY="$service_key" \
pnpm --filter @faunosteo/supabase test:e2e