Oxicloud/benches/ROUND12.md

Round 12 — auth write-path narrowing, fused quota gate, moka blob-cache index, media single-read, sized listing JSON

Benchmark-gated, same rule as ROUND2-11: every change ships with a BEFORE/AFTER benchmark and an equivalence/safety gate; an AFTER that doesn't beat its BEFORE gets rolled back or redesigned. One candidate went through exactly that loop this round (§Rejected): the single-pass compression predicate — the profiler-plausible "28 redundant Content-Type reads" turned out to cost ~4.6 ns TOTAL once monomorphized, and the fused replacement measured within noise, so the declarative chain stays.

Measured on 4 cores / 15 GiB, local PostgreSQL 16 (fsync off), release profile; frontend on Node 22 / vitest 4. Reproduce any row with the command in its section.

Summary

#	change	key metric	before → after
Q1	NC sharee search: username-only projection (was 21 wide columns incl. the ≤512 KiB avatar per match)	26-row page, 3 000 users, all matches avatared	11.77 → 2.37 ms (4.98x)
Q1b	+ gin_trgm_ops indexes on auth.users (migration 20260719000000)	same page, leading-wildcard ILIKE	→ 0.215 ms (54.7x total)
Q2	Password login: redundant full-row update_user deleted (create_session already stamps last_login_at)	ms/login, 256 KiB avatar	2.96 → 0.67 (4.45x) · −1 txn, −17-column rewrite, −512 KiB clone
Q3	Email-verified stamp → narrow conditional UPDATE (magic-link)	ms/stamp	2.20 → 0.25 (8.9x)
Q3b	OIDC repeat login → in-memory compare, sync only on change	queries per repeat login	full-row rewrite (2.37 ms) → 0 queries
Q4	Refresh-token rotation: 2 transactions → 1 (rotate_session)	ms/rotation	1.135 → 0.959 (1.18x)
Q5	WOPI CheckFileInfo triple → tokio::join! (real PgAclEngine)	ms/call	cold 0.485 → 0.363 (1.34x) · warm 0.228 → 0.209
Q6	Upload quota pair → ONE fused read (user envelope + drive cap) — NC chunk PUT pays it per chunk	ms/check	0.350 → 0.193 (1.81x) · 2 → 1 queries/chunk
M1	Listing JSON: pre-sized buffer (sized_json) vs axum Json's 128 B seed	500-row page	282.4 → 201.0 µs (1.40x) · 13 → 2 allocs
M3	Security headers: 4 SetResponseHeaderLayer + CSP middleware → 1 fused pass	per request (incl. router)	5.35 → 3.74 µs (1.43x) · −26 allocs
M4	Media capture-metadata: single-read (images were read 2-3×, videos opened 2×)	warm geomean / cold cache	1.44x warm · 1.6-3.2x cold · opens 2-3 → 1
M5	Chunked-upload session ops: 5 → 3 map lookups + stack-encoded uuid compare	ns per chunk (prepare+commit)	469 → 366 (1.28x) · −2 allocs
B1	Blob-cache index: Mutex<LruCache> → moka byte-weigher	pure index probes, K readers	K=2 2.17x, K=4 1.61x, K=8 1.46x (mutex scaled NEGATIVELY: 2.08 → 1.07 Mops/s from 1 → 2 readers)
B2	put_blob populates the cache BEFORE the inner backend consumes the source (was: after → failed 100%)	first read after whole-file put	full remote re-download → local hit
F1	SPA list view: 150 px icon thumbnails (was 400 px preview into a 40 px slot)	pixels per list thumbnail	~7.1x fewer (≈4-5x fewer bytes)

[Q1] NC sharee search — the 512 KiB-per-row autocomplete

cargo run --release --features bench --example bench_round12_queries   # §1

handle_sharees_search fired search_users per keystroke — the full 21-column row (incl. the ≤512 KiB avatar data-URI image, TOAST-detoasted per match) hydrated into User → UserDto, of which the handler read ONLY username. And the leading-wildcard ILIKE '%q%' had no trigram index, so every keystroke seq-scanned auth.users (contacts/files/folders all have gin_trgm_ops; users was the gap). Now: search_usernames port method (same WHERE/ORDER/LIMIT, username-only projection; NULL usernames filtered app-side exactly like the wide flow's post-limit filter) + the two trgm indexes. Gates: identical username lists, with and without the indexes. The wide method stays for the admin table (which serializes image).

[Q2][Q3][Q3b] Auth write-path narrowing

cargo run --release --features bench --example bench_round12_queries   # §2-3

• Login ran update_user(user.clone()) — a transaction rewriting all 17 columns (incl. the avatar, plus a 512 KiB deep clone to feed it) — purely to persist last_login_at… which create_session overwrites in its own transaction three lines later. Nothing reads the row in between (verified). The call is deleted; the in-memory register_login() stays so the response DTO carries the timestamp.
• Magic-link redemption kept its update_user for the email-verified stamp only (last-login again covered by create_session) — now a narrow WHERE … AND email_verified_at IS NULL single-column UPDATE, idempotency moved into SQL (gated: second stamp is a 0-row no-op, first timestamp preserved).
• OIDC repeat login additionally syncs the IdP avatar. The row fetched by get_user_by_oidc_subject already carries the stored avatar + verification stamp, so the service now compares IN MEMORY and issues NO query at all on the repeat-login common case (same picture, already verified) — the bench's §3b arm is the reason: even a guarded IS DISTINCT FROM no-op UPDATE ships the ≤512 KiB avatar parameter over the wire just to compare it (1.20 ms vs the 2.37 ms full-row rewrite; the in-memory skip makes it 0). When something DID change, sync_oidc_login_profile runs the guarded narrow UPDATE (image + conditional stamp, update_storage_usage pattern) instead of the 17-column rewrite.

[Q4] Refresh rotation — one transaction

refresh_token paid two full BEGIN/COMMIT pairs per rotation (revoke_session then create_session), and DAV clients rotate constantly. New rotate_session(old_id, new_session) port method: revoke + insert + last-login stamp in one with_transaction. Gates: old session revoked, new session live, reuse-detection semantics untouched (family revocation still fires on replay). The per-rotation "Session … revoked" info-line is gone with the old method call (routine rotation is not a security event; explicit logout/family revocation still log).

[Q5] WOPI CheckFileInfo — three independent lookups overlapped

The handler ran require(Read) → get_file → check(Update) serially; all three key off (caller, file) alone. Now tokio::join! with results evaluated in the original precedence (Read gate first, then 404, then the can_write hint — deny responses byte-identical; the Update probe still skips its query when the token has no write claim). Same fusion applied to authorize_wopi_access (host page / editor-url). Cold is the shape that matters: office editors poll CheckFileInfo through a session, but each (file × TTL-window) pays the cold chain once.

[Q6] Fused upload-quota gate

refuse_if_over_quota (NC chunked PUT — runs on EVERY chunk) issued the user-envelope read and the drive-cap read serially. One LEFT JOIN row now carries both counter pairs; the verdict evaluators were extracted (eval_user_envelope / eval_drive_cap) and are shared by the old point methods and the fused one, so every error string is identical by construction. Gates: verdict identity across ok / drive-over / user-over (precedence) / unlimited / missing-drive. A check_upload_quotas_by_folder twin exists for folder-keyed callers; the three REST once-per-upload pair sites were left as-is (their two checks carry different rejection logs, and one query per whole upload isn't worth entangling that — see §Skipped).

[M1] sized_json — the 128-byte seed on every listing

cargo run --release --features bench --example bench_round12_micro    # §1

axum's Json serializes into BytesMut::with_capacity(128); a 500-row listing (~190 KB) grows it through ~11 doubling reallocs, memcpy-ing ~1.3× the payload. interfaces::api::sized_json pre-sizes from the row count (FileDto ≈ 380 B serialized; estimate 384) and serves byte-identical output (gated). Applied to the four hot listing responses: list_files (which is UNBOUNDED — no page cap), folder resources, photos timeline, search (both verbs).

[M3] Security-header stack 5 → 1

The CSP middleware already post-processed every response; the four static headers (x-content-type-options, x-frame-options, referrer-policy, permissions-policy) each rode their own SetResponseHeaderLayer on top. Folded into the same pass — inserted before the 304 early-return because the standalone layers stamped 304s too. Gate: status + full sorted header set byte-identical for json / html / 304 through real axum routers.

[M4] Media capture-metadata single-read (the ROUND11 deferred lead)

cargo run --release --features bench --example bench_round12_micro    # §4

extract_blocking read each image once wholesale for kamadak, then nom-exif re-opened the SAME file (read_exif(path)), and date-less images paid a third open (read_track(path) fallback). Videos opened twice (a doomed read_exif sniff, then read_track). Now: nom-exif parses from the kamadak buffer zero-copy (MediaSource::from_memory over the same Bytes allocation, API verified on the pinned 3.6.1), one reused MediaParser, and videos open once with a kind() dispatch. The track fallback for images SURVIVES (fed from the same bytes) — it covers MIME-mislabeled rows, the only case where it ever produced a date; behaviour is observable-identical (gated over dated/undated JPEG, PNG, crafted MP4 — corpus asserted non-vacuous: the crafted EXIF date and mvhd creation time must actually extract). Warm: 1.44x geomean. Cold cache (drop_caches arms): dated JPEG 0.81 → 0.34 ms, undated 0.97 → 0.30, PNG 0.12 → 0.06, MP4 0.050 → 0.032. Per-image opens 2-3 → 1; the backfill sweeps multiply this by the library size.

[M5] Chunked-upload session ops

prepare_chunk ran verify_session_owner (own DashMap lookup + a Uuid::to_string) then re-fetched the same entry; commit_chunk did the same plus its get_mut (3 lookups + allocation per chunk). The owner gate now rides the operation's own lookup (same anti-enum not-found for unknown and foreign sessions — gated), and the uuid compares against a stack-encoded hyphenated form. 5 → 3 shard-lock round-trips and −2 allocs per chunk cycle.

[B1][B2] Blob-cache: moka byte-weigher index + the put_blob ordering fix

cargo run --release --features bench --example bench_blob_cache_index
cargo run --release --features bench --example bench_blob_cache        # regression guard

The ROUND11 deferred headline. The cache index was a tokio::sync::Mutex<LruCache>: every cached chunk read took the one global async mutex to probe+promote (LRU get needs &mut), so a 100-chunk video playback was 100 serialized critical sections and concurrent readers contended process-wide — measured NEGATIVE scaling (2.08 → 1.07 Mops/s going from 1 to 2 readers). moka::sync::Cache with a byte weigher makes the probe lock-free (K=2 2.17x, K=8 1.46x; end-to-end warm reads with real files 1.00-1.15x on this 4-core box — the gap is the index share of the path and widens with cores/readers). moka also absorbs the byte budget: the manual current_size counter + collect_evictions sweep are gone; an eviction listener unlinks size-evicted .blob files. Safety gates: budget enforced (100 × 1 MiB into a 10 MiB cap → ≥88 files unlinked, survivors readable), a Replaced entry does NOT unlink its file, Explicit invalidations unlink at their call sites, and the per-hash single-flight still collapses 16 concurrent misses to 1 fetch. The CachedRef clone bundle (incl. a cache_dir PathBuf clone paid on every HIT for a miss-only struct) is gone — internals now borrow self.

Two behavioural notes, both strict improvements: the write-through PUT paths now respect the byte budget (the old index deliberately skipped eviction there, letting write bursts overshoot until the next read-miss); and a restored over-budget cache trims at startup instead of on the next insert.

B2 (the ROUND11 correctness note): put_blob populated the cache AFTER inner.put_blob — but every inner backend consumes the source file (local renames it, S3/Azure delete it post-upload), so the fs::copy failed 100% of the time, silently (let _), and the first read after a whole-file put (the backend-migration copier) re-downloaded the blob from the remote. Cache-first now, with invalidate+unlink if the inner put fails so a rejected blob can never be served. The round-3 stampede guard re-run passes against the migrated backend (16 → 1 remote fetches, cache file verified).

[F1] SPA list-view thumbnails (vitest gate)

cd frontend && npx vitest run src/lib/api/endpoints/round12.bench.test.ts

Both views requested the 400 px preview rendition; the list row draws it in a 40×40 slot (the 150 px icon rendition is already ≥2× retina density there). thumbSizeForView switches list rows to icon — ~7.1x fewer pixels per thumbnail, roughly 4-8 KB vs 20-40 KB encoded WebP each, across files/recent/favorites/trash/shared list views. Grid keeps preview (100×70 slot at 2x DPR genuinely needs it).

Rejected / reworked this round (the discipline working)

• Single-pass compression predicate: the sweep flagged "~28 redundant Content-Type header reads per compressible response" in main.rs's And-chain. The bench says otherwise: the monomorphized chain runs in 4.6 ns / 0 allocs total (straight-line inlined probes), and the hand-fused single-pass node measured 5.2 ns on the compressible hot case — within noise, sometimes slower. Not shipped; the declarative chain stays. bench_round12_micro §2 keeps the reproducible evidence.

Considered and skipped (cost/benefit, not measurement)

• REST per-upload quota pair fusion (multipart / native-chunked / delta): the two checks sit in separate if blocks with distinct rejection logs and folder-id guards; fusing saves ONE query per whole upload (not per chunk) and would entangle that flow. The NC per-chunk site — the hot one — is fused (Q6).
• NC per-session quota budget cache (0 queries per chunk instead of 1): needs a staleness/invalidation story vs concurrent sessions; the fused read already halves the per-chunk cost with bit-identical semantics. Flagged for a future round.
• lto = "fat" on the release profile: the bench profile already uses it; flipping release trades a large link-time regression for every contributor and CI/Docker build against a low-single-digit runtime gain. That's a project-level call for maintainers, not a bench-gated code change — flagged, not shipped.

Deferred / flagged (not shipped this round)

• Grouped file/grid views are still unvirtualized (files route groupBy != '' mounts EVERY row in both view modes; ResourceList's grouped GRID branch too — trash is grouped-by-default). Design prepared this round: flatten groups into the existing VirtualRows (photos-timeline pattern — headers as first-class rows, grid rows as fixed-height strips of gridColumns(width) tiles), which also collapses the per-section VirtualList scroll listeners the grouped LIST path pays today (one getBoundingClientRect per section per scroll tick). This is the next round's headline; it wants its own pass with UI gates.
• Duplicate TraceLayer on /api (routes.rs layers it again under the global ClientIpMakeSpan layer) and the per-request client_ip String in the span factory — small, want their own measured arms.
• CachedBlobBackend::local_blob_path sync stat (ROUND10/11 flag stands — background-extraction paths only; needs an async port variant).
• Media hooks read the same blob up to 3× per upload (thumbnail + capture-metadata + faces each pull it independently; the latter two read the RAW blob path directly, bypassing the content cache — and, on encrypted deployments, reading ciphertext: correctness note for maintainers, same class as the ROUND11 put_blob note).
• mp3_duration::from_path full-file frame scan runs even when the ID3 TLEN tag is present (ingest-path only). Preferring TLEN is a speed/accuracy tradeoff on VBR files — maintainer call.
• Thumbnail orientation re-parses EXIF that capture-metadata also parses; reusing the persisted orientation is ordering-dependent (hooks run concurrently) — needs a small sequencing decision.

Environment / methodology

• cargo run --release --features bench --example bench_round12_queries — needs Postgres; seeds and sweeps its own fixtures (BENCH_PASSES, BENCH_SHR_USERS, BENCH_WOPI_FILES, BENCH_WARM_ITERS).
• cargo run --release --features bench --example bench_round12_micro — counting allocator; §4's cold arms drop the page cache (root; set BENCH_COLD_ITERS=0 to skip).
• cargo run --release --features bench --example bench_blob_cache_index — index scaling + eviction/single-flight safety gates.
• cargo run --release --features bench --example bench_blob_cache — round-3 cross-round regression guard (passes against the moka index).
• cd frontend && npx vitest run src/lib/api/endpoints/round12.bench.test.ts.