Oxicloud/benches/ROUND10.md

# Round 10 — auth alloc purge, parent-resolution herd batching, query-shape pack, NC conditional revalidation

Benchmark-gated, same rule as ROUND2-9: every change ships with a
BEFORE/AFTER benchmark and equivalence/safety gates; an AFTER that doesn't
beat its BEFORE gets rolled back or redesigned. Two items this round went
through exactly that loop: the stack integer formatters first benchmarked
SLOWER than `to_string()` and were rewritten (§13) before adoption, and the
first parent-batching design (a channel task) measured 66 µs of pure hop
overhead per sequential miss and was replaced by the leader-inline protocol
(§10) before adoption.

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

## Summary

| # | change | key metric | before → after |
|--:|---|---|---|
| 1 | Authenticated-request identity build (`Arc<str>` claims + inline `SmolStr` role) | allocs / ns per request | 4 → 1 allocs · 77 → 59 ns |
| 2 | Basic-auth cache hit (`Arc<str>` cached identity) | allocs / ns per DAV request | 3 → 0 allocs · 62 → 41 ns |
| 3 | Share download metadata double-fetch → `_preloaded` | queries / ms per download | 2 → 1 · 0.700 → 0.321 ms (**2.18x**) |
| 4 | Contact-group summary → `COUNT(*)` | ms, 500-member group | 5.76 → 0.39 (**14.9x**) |
| 5 | `save_faces` per-face INSERT loop → UNNEST batch | ms, 30-face image | 5.90 → 1.52 (**3.9x**) |
| 6 | Playlist reorder per-track UPDATE loop → UNNEST | ms, 500-track reorder | 167.0 → 2.6 (**63.7x**), now atomic |
| 7 | Search page files∥folders `tokio::join!` | ms per search | 4.16 → 2.87 (**1.45x**) |
| 8 | Move pre-check drive lookups `join!` | ms per move | 0.664 → 0.311 (**2.14x**) |
| 9 | Trash listing partial `(drive_id, trashed_at) WHERE is_trashed` | ms per page (30-drive box) | 0.615 → 0.496 (**1.2x**) |
| 10 | Parent-resolution herd batching (leader-inline) | parent queries, 100-thumb cold herd | **100 → 2** · herd wall 65.5 → 35.4 ms (**1.9x**) |
| 11 | Folder-cascade single-flight (`try_get_with`) | ltree queries, same-folder cold herd | K → 1 (rode along with §10's gates) |
| 12 | NC preview + avatar honour `If-None-Match` | bytes/req on revalidation (e2e) | preview 5 004 → 0 · avatar 196 992 → 0 |
| 13 | `common::fmt` integer LUT rewrite | ns/op vs `to_string()` | i64: 33.7 → **16.1** (std: 22.5) |
| 14 | NC PROPFIND int props + trashbin dates → stack fmt | allocs per 500-row page / 2000-item bin | 1 501 → 1 · 4 002 → 2 (wall 1.11x / 1.13x) |
| 15 | WebDAV scope probe, base_url snapshot, cookie OnceLock, JWT keys, cipher Arc, request-id | see §15 | e.g. base_url listing 71.5 µs → 1 ns |
| 16 | CalDAV update/delete gate narrow read | ms (11 KB `ical_data` row) | 0.323 → 0.308 (1.05x + 11 KB less wire) |
| 17 | Legacy favorites/recents rows: binary UUID decode | ms per 500-row page | 2.80 → 2.58 (**1.09x**) |
| 18 | SPA: search stale-guard + AbortController | completed round-trips, 10-query burst | 10 → 1; stale-clobber eliminated |
| 19 | SPA: `getFolder` in-flight dedup | requests per cold deep-link | 2 → 1 |
| 20 | SPA: `gridColumns` matchMedia hoist | MQL constructions / 10k calls | 10 000 → 0 · 13.4 → 2.6 ms (**5.2x**) |

Plus: `count_files` (a dead port method whose impl ran the full paginated
search) deleted outright; NC chunk PUT retry-probe folded into the open
(`create_new`, one stat less per chunk); tantivy per-query analyzer
double-clone dropped.

## [1][2] Auth hot path — the ROUND6/9 deferred "cheapest known win"

Every authenticated request built `CurrentUser` by deep-cloning
`username`/`email` out of the cached `Arc<TokenClaims>` and `to_string`ing
the live role — the exact 2-allocs-per-request item deferred since ROUND6,
plus two more nobody had counted (`flags.role.to_string()` in
`decide_live_role`, and the Basic-auth cache handing out 3 owned Strings
per moka hit on every DAV request).

Now: `TokenClaims.username/email` are `Arc<str>` (serde `rc`, same one
allocation at decode time), `CurrentUser.username/email` are `Arc<str>`
(refcount bumps), `CurrentUser.role` is an inline `SmolStr` fed by
`LiveRole::Active(SmolStr)` + the new `UserRole::as_str()` (`&'static`,
zero alloc), and `CachedBasicAuthResult` carries the same types so a
Basic hit is bumps + a 24-byte memcpy. JSON wire shape is unchanged
(byte-identity gated); OpenAPI keeps `String` via `value_type`.

```
cargo run --release --features bench --example bench_round10_micro
# [1] identity build  BEFORE 77.2 ns / 4.00 allocs → AFTER 59.0 / 1.00
#     gate: fields + serialized JSON byte-identical
# [2] basic-auth hit  BEFORE 62.2 ns / 3.00 allocs → AFTER 40.9 / 0.00
```

The JWT service also stopped rebuilding `EncodingKey`/`DecodingKey`/
`Validation` per call (now fields; the verify-miss path drops 4 allocs,
§15), and `generate_access_token`'s `format!("{}", role)` became
`as_str().to_string()`.

## [3] Share download — the handler already had the DTO

`serve_share_file` fetched the file DTO for ETag/Range handling, then
called `get_file_optimized`, which re-ran the same metadata query. The
authenticated download path already used `get_file_optimized_preloaded`;
the public-share path now does too (the DTO is moved, not cloned — the
one later use of `size` is captured first).

```
cargo run --release --features bench --example bench_round10_queries
# [1] BEFORE 2 queries 0.700 ms/download → AFTER 1 query 0.321 ms (2.18x)
```

## [4] Contact-group summary — 500 vCards hydrated to compute `len()`

`get_group` called `get_contacts_in_group` — full rows (vCard TEXT that
can carry base64 photos + 3 JSONB arrays parsed per contact) — and kept
only the count. New `count_contacts_in_group` port method backed by
`SELECT COUNT(*)` on `group_memberships`.

```
# [3] 500 members: BEFORE hydrate-all 5.762 ms → AFTER COUNT(*) 0.387 (14.9x)
```

## [5][6] Write-path N+1 loops → one UNNEST statement

- `save_faces`: one INSERT per face inside a transaction → a single
  multi-row `INSERT … SELECT FROM unnest(...)` (the `bbox` float4[] rides
  as 4 parallel component arrays, reassembled server-side). 30-face image:
  5.90 → 1.52 ms (**3.9x**); gate re-reads a stored row field-by-field.
- `reorder_items`: one autocommit UPDATE per track (non-atomic — a
  mid-loop failure left a half-applied order) → one
  `UPDATE … FROM unnest($1) WITH ORDINALITY`. 500-track reorder:
  167.0 → 2.6 ms (**63.7x**); gate compares every final position.

## [7][8] Independent awaits overlapped (`join!`, decide-by-bench)

- `SearchService::search` awaited the content-index lookup, the file page
  and the folder query serially in both branches; `suggest_with_perms` had
  the correct shape since ROUND4. All three are independent; the two SQL
  arms measured 4.16 → 2.87 ms (**1.45x**) with identical results.
  (Content-index enabled widens the win — the Tantivy arm is the long pole
  and now overlaps both queries.)
- File/folder move pre-check ran the source-drive-policies and
  destination-drive point reads serially before comparing:
  0.664 → 0.311 ms (**2.14x**). Adopted per the ROUND6 protocol (these are
  two independent point reads whose server-side execution parallelizes —
  the shape that wins even on a local socket).
- The NC PROPFIND folder-HEADER trio (favorites + oc:fileid + dead props
  for the folder's own entry, on the TTFB critical path of every folder
  PROPFIND) got the same `join!` ROUND9 gave the per-page child triples.

## [9] Trash listing — the dropped-index gap

Migration 20260904 removed `user_id` and with it the only trash-listing
index; what remained forced either a live-rows scan of the drive
(`idx_files_drive_id`) or an all-tenants trash scan
(`idx_files_trash_expiry`). New partial pair
`(drive_id, trashed_at) WHERE is_trashed` (migration 20260920000000)
bounds the read to the caller's drives' trashed rows, pre-ordered for the
`trashed_at`/`deletion_date` keysets. On a 30-drive box (3 000 live + 25
trashed each): 0.615 → 0.496 ms (**1.2x**); the gap widens with drive size
since the BEFORE plan scans live rows. Identical row sets gated; the
retention sweeper keeps its global expiry index.

## [10][11] Cold-album herd — parent batching + cascade single-flight

ROUND9 §10 left the cold first view paying one parent PK read per photo
and noted batching "needs a wider engine API". It doesn't: the browser
fires its thumbnail requests near-simultaneously, so the batching can live
INSIDE `file_parent_folder_cached`:

- **Leader-inline protocol** (`parent_batch` slot): an idle miss marks
  itself leader (one mutex op) and runs its point query exactly as before
  — the sequential path is unchanged (a channel-task design measured
  ~66 µs/miss of hop overhead and was REJECTED). Misses arriving while
  the leader is in flight park a oneshot; the leader serves them all with
  ONE `id = ANY($1)` charity batch after its own read; a second wave is
  handed to a detached drainer so the leader's response is never delayed
  by more than one batch. A cancelled leader's guard wakes every parked
  waiter to re-elect; waiters that exhaust retries fall back to the
  inline point read. Requested-but-absent ids memoise as `None`,
  matching the point read's semantics.
- **`cascade_grant_cached` → `try_get_with`** (the ROUND3 auth-herd
  pattern): K concurrent files of one album all recurse into the SAME
  folder decision; get→compute→insert let each run the ltree query.
  Single-flight collapses that to one loader; moka never caches loader
  errors, preserving error semantics.

```
cargo run --release --features bench --example bench_thumbnail_cascade_cache
# thumbs=100 (folder-grant recipient, no drive membership)
# ROUND8 cold (union/file)      65.59 ms   655.90 µs/thumb
# AFTER cold sequential         65.53 ms   655.33 µs/thumb  (parity — no
#   sequential regression from the protocol; this box's high per-query
#   latency compresses the R9 decomposition margin visible on faster I/O)
# AFTER warm (revalidation)      0.14 ms     1.42 µs/thumb  (unchanged)
# AFTER herd (concurrent cold)  35.35 ms   353.47 µs/thumb  (~1.9x vs
#   sequential cold — and the real shape of a grid's first view)
#   parent queries for the herd: 2   (was 100)
# gates: all original ROUND8/9 safety gates (outsider denied, clear_role
#   revoke denies immediately, direct-grant sibling isolation) plus NEW:
#   herd answers == point-read answers per file, parent queries < K/4
```

## [12] NC preview + avatar — ETag existed, nobody compared it

- `/index.php/core/preview` set an immutable ETag but never read
  `If-None-Match` — every gallery revalidation re-ran NC-id resolve, file
  fetch, authz, blob-hash query, thumbnail cache read and full body. The
  handler now answers 304 right after the authz check (never before it).
- `/index.php/avatar/{user}/{size}` had no ETag at all, and re-decoded the
  stored data URI on every request (for WebP avatars: a full image decode
  + PNG encode per request). Now: content-hash ETag (over the stored URI,
  computed before any decode), 304 on match, and the WebP→PNG transcode
  memoised in a 32-entry moka keyed by content hash.

End-to-end (real server + curl loops, the PHOTOS-ETAG methodology; 60
requests per arm):

```
# preview  200: 5 004 bytes/req  1.35 ms   →  304: 0 bytes  1.25 ms
# avatar   200: 196 992 bytes/req 2.30 ms  →  304: 0 bytes  1.97 ms
# gates: fresh GET 200 with ETag; matching If-None-Match → 304 empty;
#        stale If-None-Match → full 200. All six pass.
```

Per NC client per cache-lapse this removes ~197 KB (avatar) + ~5 KB/photo
(previews) of transfer plus the per-request DB/disk work behind them.

## [13] `common::fmt` — the bench caught our own helpers losing

The round's first micro run showed the PROPFIND int-field port SLOWER on
wall despite 1 500 fewer allocs. An isolated interleaved probe confirmed:
the byte-at-a-time div-by-10 loop in `u64_str` (33.7 ns) lost to
`u64::to_string()` (22.5 ns) — std renders via a 2-digit lookup table.
Rewrote `u64_str`/`i64_str` (and the date helpers' `push2`) on the same
`DEC_LUT` technique, dropping `i64_str`'s temp-buffer copy:

```
# interleaved probe, 20M ops/arm
# to_string 22.5 ns   i64_str BEFORE 33.7 ns → AFTER 16.1 ns
# to_rfc2822 42.7 ns  rfc2822_utc 33.6 ns
```

This speeds every existing ROUND4-9 call site (`d:getcontentlength`,
`oc:size`, digest lengths, dates) as well as the new ones.

## [14] NC PROPFIND / trashbin emit stragglers

With §13 in place, the remaining `to_string()`/`to_rfc2822()` fields moved
to the stack helpers: `oc:fileid`, `nc:creation_time`, `nc:upload_time`,
quota bytes (files + folders writers), and the trashbin's per-item
modified/deletion-time/fileid (which still ran the chrono interpreter).

```
# [3] 500-row page  BEFORE 95.5 µs / 1501 allocs → AFTER 86.3 / 1   (1.11x)
# [4] 2000-item bin BEFORE 318.5 µs / 4002 allocs → AFTER 280.7 / 2 (1.13x)
# gates: XML byte-identical in both harnesses
```

## [15] Micro-pack (each gated in `bench_round10_micro`)

- **WebDAV scope probe**: `format!("{prefix}/")` per request → borrow-only
  `strip_prefix` pair. 38 → 3.5 ns, 1 → 0 allocs, identical routing.
- **`ShareService.base_url`**: `env::var("OXICLOUD_BASE_URL")` + rebuild
  PER DTO ROW → constructor snapshot. 500-row listing: 71.5 µs → 1 ns.
- **`cookie_secure`**: 4 env-var resolutions + duplicate SECURITY log
  lines per login → `OnceLock` (process-invariant by definition).
- **JWT verify miss**: fresh `Validation` + `DecodingKey` per decode →
  service fields. 4 748 → 4 527 ns, 17 → 13 allocs (HMAC dominates).
- **`EncryptedBlobBackend`**: per-op clone of the expanded AES-256 round
  keys → `Arc` bump. 30.8 → 13.3 ns per hand-off.
- **Request-id header**: `Uuid::to_string` + `HeaderValue::from_str` →
  stack-encode. 85 → 46 ns, 2 → 1 allocs, identical bytes.
- **NC chunk PUT**: the retry-detection `stat` per chunk folded into the
  open — `stream_body_to_path` now opens `create_new` first and reports
  `created_fresh` (AlreadyExists → truncate-open), the ROUND9 §5a pattern
  applied to the NC surface.

## [16] CalDAV update/delete gate — narrow `calendar_id` read

The service fetched the FULL event row (with `ical_data` — 11 KB in the
benched shape, unbounded with attendees/VALARMs) only to read
`.calendar_id` for the authz gate. New `find_calendar_id_by_event_id`
scalar. 0.323 → 0.308 ms on a local socket (1.05x) — adopted for the
direction: the win is the row width off the wire, which grows with event
size and network distance. (This is NOT the deferred authz-reorder — the
gate still runs before the mutation, same order.)

## [17] Legacy favorites/recents rows — the ROUND6 §10 port, with a catch

The two legacy listing methods still shipped `::TEXT` casts. Porting them
to binary decode surfaced that `auth.user_favorites.id` is a SERIAL
`integer`, not a UUID — the bench's identity gate caught the wrong decode
before it could ship (decode as `i32`, render app-side). 500-row page:
2.80 → 2.58 ms (**1.09x**), rendered tuples identical.

## [18][19][20] SPA pack (vitest gates)

```
cd frontend && npx vitest run src/routes/search/staleGuard.bench.test.ts \
  src/lib/api/endpoints/folderDedup.bench.test.ts src/lib/utils/grid.bench.test.ts
```

- **Search stale-response guard** (the flag open since ROUND7): rapid-fire
  query/sort/filter changes had no seq token and no abort — a slow older
  response could clobber a newer one, and superseded recursive searches
  ran to completion server-side. `run()` now carries a sequence token +
  `AbortController` (threaded through `searchFiles`/`searchSuggest`);
  AppShell's suggest box got the same guard. 10-query burst: completed
  round-trips 10 → 1; final result provably fresh (BEFORE ends on the
  STALE query).
- **`getFolder` in-flight dedup** (the `resolveUser` pattern): cold
  deep-links fired the same folder-metadata GET twice (breadcrumbs +
  drive-id resolver). Concurrent duplicates now share one request;
  sequential calls still refetch (freshness unchanged, gated).
- **`gridColumns`**: a fresh `matchMedia` (style read) per call inside the
  grid windowing derives → one module-level MQL fed by its `change`
  listener (the photos-timeline fix applied to the shared util). 10k
  calls: 10 000 → 0 MQL constructions, 13.4 → 2.6 ms; output identity
  gated across the breakpoint, crossings propagate via the listener.

## Rejected / reworked this round (the discipline working)

- **Channel-task parent batcher**: correct, but the mpsc+oneshot
  round-trip measured 65.9 µs per sequential miss — a pure regression for
  the non-concurrent case. Replaced with leader-inline (§10).
- **First stack-formatter port**: slower than `to_string()` on wall
  (§13); adopted only after the LUT rewrite made it faster on BOTH axes.
- **`uf.id` as binary UUID**: wrong type entirely (SERIAL int) — the
  equivalence gate caught it; shipped as `i32` decode instead.

## Deferred / flagged (not shipped this round)

- **CalDAV authz-before-fetch reorder** — still awaiting maintainer
  sign-off per the authz-change convention (ROUND9 flag stands).
- **Grouped file/grid views are unvirtualized** (files group-by and
  ResourceList grid sections mount every row; the flat/list paths are
  windowed) — a UI-behaviour change big enough to want its own pass.
- **`search_files_paginated`'s `COUNT(*) OVER()` + OFFSET** — keyset would
  change the API's total-count contract; needs a product decision on
  whether search totals can become approximate/capped.
- **`ResourceList.selectedEntries`** recomputes an O(N) filter per
  selection toggle once the toolbar is visible; hosts often shadow it
  with their own copy. Needs a small API rework (getter or id-index).
- **Chunk-upload `progress.bin`** full rewrite per chunk (REST surface) —
  debouncing trades crash-resume granularity; flagged for discussion.
- **`CachedBlobBackend::local_blob_path`** sync `stat` on the reactor
  (remote-backend deployments' media hooks) — needs an async variant of
  the port method; low urgency.