review(363): robustness + wording fixes from cold review
Build ErsatzTV Image / CI image pin matches docker/ci (pull_request) Successful in 6s
Build ErsatzTV Image / API docs in sync (OpenAPI + endpoint index) (pull_request) Successful in 11s
Build ErsatzTV Image / Docs update reminder (pull_request) Successful in 7s
Build ErsatzTV Image / Formatting (changed .cs conform to .editorconfig) (pull_request) Successful in 9s
Build ErsatzTV Image / decisions.md append-only (pull_request) Successful in 20s
Build ErsatzTV Image / Functional E2E (curl contracts) (pull_request) Successful in 15m47s
Build ErsatzTV Image / Build & test (.NET) (pull_request) Successful in 19m11s
Build ErsatzTV Image / EF migration integrity (SQLite + MySql) (pull_request) Successful in 20m48s
Build ErsatzTV Image / Build & push image (amd64) (pull_request) Has been skipped

- check seed_library_path succeeded (print lastrowid) so a silent seeding
  failure surfaces as a FAIL instead of degrading Flow A to an advisory skip
  with no diagnostic (Medium)
- anchor the scan-status match to '"libraryId":2,' so it can't substring-match
  "libraryId":20/23 if the suite ever creates more libraries (Low)
- drop the no-op ?deep=true (local scans always ForceScan; deep only affects
  Plex/Jellyfin/Emby) + note why (Low)
- soften "guaranteed 409" for the scan flow to note the tiny residual TOCTOU
  gap the multi-second scan covers; Flow B stays race-free by construction (Low)
- correct the "WAL tolerates a second writer" wording to the real reason (the
  busy-timeout retry serializes the writer) in the script + both docs (Nit)
- use TEST-NET-1 192.0.2.1 (RFC 5737) instead of RFC1918 10.255.255.1 for the
  non-routable Jellyfin address (Nit)

Re-verified: fresh-instance harness runs green (38/38), lock section
deterministic. Functional E2E CI job already green on the prior head.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This commit is contained in:
2026-07-18 15:33:39 +02:00
co-authored by Claude Opus 4.8
parent 8a85f9ddb5
commit 4345180a56
3 changed files with 50 additions and 31 deletions
+1 -1
View File
@@ -296,7 +296,7 @@ re-run by hand, turning them into a CI regression net (ersatztv#299). It is the
**Lock-contention 409s (ersatztv#363).** The harness now seeds rows the API can't create — a
`LibraryPath` and a Jellyfin media-source — directly into the running instance's SQLite DB (via
python3's stdlib `sqlite3`; WAL mode tolerates the second writer), and synthesizes media with the
python3's stdlib `sqlite3`, whose busy-timeout retry serializes behind the app's writer), and synthesizes media with the
image's ffmpeg, to exercise two `IEntityLocker` contracts **deterministically** (it only fires the
racing request once the lock is *provably* held, never a sleep-and-hope): (a) the **library-scan
"already scanning" 409** — seed ~60 tiny clips into the built-in Shows library so the scanner
+2 -2
View File
@@ -158,8 +158,8 @@ What it covers. Most assertions are curl-only (no seeded media / ffmpeg / browse
an `ETag` → `PUT` with a stale `If-Match` `412`, current `200`, malformed `400`.
- **Lock contention (409)** — the two `IEntityLocker` 409s, made **deterministic** by firing the
racing request only once the lock is *provably* held (never a sleep-and-hope). Both seed rows the
API can't create straight into the running instance's DB via python3's stdlib `sqlite3` (WAL mode
tolerates the second writer):
API can't create straight into the running instance's DB via python3's stdlib `sqlite3` (whose
busy-timeout retry serializes behind the app's writer):
- **library-scan "already scanning"**: seed ~60 tiny ffmpeg clips into the built-in Shows library
(Id=2) so the scanner subprocess runs a few seconds → `POST .../scan?deep=true` `202` → poll
`GET /libraries/scan-status` until library 2 shows active (that window is a strict subset of the
+47 -28
View File
@@ -23,8 +23,9 @@
# 4. Auth / CSRF / security-stamp (setup-claim, read-gate, CSRF gate, login, logout+revoke).
#
# Section 3 is the first that isn't curl-only: it seeds rows the API can't create (a LibraryPath and
# a media-source) straight into the running instance's SQLite DB (via python3's stdlib sqlite3 — WAL
# mode tolerates a second writer) and, for the scan flow, synthesizes media with ffmpeg. Both 409s
# a media-source) straight into the running instance's SQLite DB (via python3's stdlib sqlite3, whose
# busy-timeout retry serializes behind the app's writer) and, for the scan flow, synthesizes media
# with ffmpeg. Both 409s
# are made DETERMINISTIC (no racy sleep-and-hope) — see the section header for how. The scan flow is
# skipped (advisory) when ffmpeg is absent; the collections flow needs neither ffmpeg nor a scanner.
#
@@ -187,28 +188,34 @@ expect_status "PUT with a malformed If-Match -> 400" 400 PUT "$BASE_URL/api/v1/r
# few seconds. The scan-status "active" window is a strict SUBSET of the scan lock's held window
# (ScannerProxyService.StartScan happens after locker.LockLibrary, EndScan before UnlockLibrary --
# ErsatzTV/Services/ScannerService.cs), so once GET /libraries/scan-status shows the library
# active, the lock is provably held and a second POST .../scan is a guaranteed 409.
# active the lock is provably held and a second POST .../scan is a 409 -- deterministic bar a
# tiny residual TOCTOU gap (observe-active -> 2nd POST lands) that the multi-second scan covers.
#
# B. External-collections "already scanning" 409 (per-family lock). The controller takes the lock
# SYNCHRONOUSLY before returning 202 (JellyfinMediaSourcesController), so the 202 itself proves
# the lock is held; pointing the seeded source at a non-routable address keeps the background
# sync hung so the window stays wide open. GET /media-sources/collections-scan-status corroborates.
# the lock is held (race-free by construction); pointing the seeded source at a non-routable
# address keeps the background sync hung so the window stays wide open. GET
# /media-sources/collections-scan-status corroborates.
#
# Seeding writes rows the API can't create (LibraryPath, media-source) directly into the instance's
# SQLite DB via python3's stdlib sqlite3 (already a hard dep of this harness); WAL mode tolerates the
# second writer. Runs on the machine key, before the auth section (which claims the admin) -- these
# never claim it. Flow A is skipped (advisory) without ffmpeg; Flow B needs neither ffmpeg nor a scanner.
# SQLite DB via python3's stdlib sqlite3 (already a hard dep of this harness); the connection's
# busy-timeout retry serializes this second writer behind the app. Runs on the machine key, before the
# auth section (which claims the admin) -- these never claim it. Flow A is skipped (advisory) without
# ffmpeg; Flow B needs neither ffmpeg nor a scanner.
section "Lock contention (409): scan-in-progress + collections-in-progress"
DB="$CONFIG_DIR/ersatztv.sqlite3"
# seed_library_path PATH LIBRARY_ID -- attach a folder to a built-in local library (parameterized).
# seed_library_path PATH LIBRARY_ID -- attach a folder to a built-in local library (parameterized);
# prints the new LibraryPath row id so the caller can detect a silent seeding failure.
seed_library_path() {
python3 - "$DB" "$1" "$2" <<'PY'
import sqlite3, sys
con = sqlite3.connect(sys.argv[1], timeout=10)
con.execute("INSERT INTO LibraryPath (Path, LibraryId) VALUES (?, ?)", (sys.argv[2], int(sys.argv[3])))
con = sqlite3.connect(sys.argv[1], timeout=10) # busy-timeout retry serializes this second writer
cur = con.cursor()
cur.execute("INSERT INTO LibraryPath (Path, LibraryId) VALUES (?, ?)", (sys.argv[2], int(sys.argv[3])))
con.commit()
print(cur.lastrowid)
PY
}
@@ -218,7 +225,7 @@ PY
seed_jellyfin_source() {
python3 - "$DB" "$1" <<'PY'
import sqlite3, sys
con = sqlite3.connect(sys.argv[1], timeout=10)
con = sqlite3.connect(sys.argv[1], timeout=10) # busy-timeout retry serializes this second writer
cur = con.cursor()
cur.execute("INSERT INTO MediaSource DEFAULT VALUES")
msid = cur.lastrowid
@@ -245,22 +252,32 @@ else
# 60 distinct episode files (the scanner ffprobes each) -> a multi-second scan even on fast CI
# I/O, so the poll->fire gap (one HTTP round-trip) is comfortably inside the lock window.
for n in $(seq -w 1 60); do cp "$SEED_SRC" "$SEED_SEASON/Show Lock - s01e$n.mkv"; done
seed_library_path "$SEED_ROOT" 2 # Shows is the built-in library Id=2 (docs/e2e-local.md recipe)
expect_status "POST /libraries/2/scan?deep=true -> 202 (queued)" 202 POST "$BASE_URL/api/v1/libraries/2/scan?deep=true" \
-H "X-Api-Key: $API_KEY" -H 'Content-Type: application/json' -d '{}'
# Poll scan-status until the scan is provably in flight, then fire the racing scan.
scan_active=""
for _ in $(seq 1 100); do
if api "$BASE_URL/api/v1/libraries/scan-status" | grep -q '"libraryId":2'; then scan_active=1; break; fi
sleep 0.1
done
if [ -n "$scan_active" ]; then
ok "scan-status shows library 2 active (scan lock provably held)"
expect_status "second POST /libraries/2/scan while scanning -> 409" 409 POST "$BASE_URL/api/v1/libraries/2/scan" \
-H "X-Api-Key: $API_KEY" -H 'Content-Type: application/json' -d '{}'
# Shows is the built-in library Id=2 (docs/e2e-local.md recipe). Check the seed succeeded -- a
# silent failure would leave library 2 with no paths, the scan a no-op, and the 409 un-asserted.
if [ -z "$(seed_library_path "$SEED_ROOT" 2)" ]; then
bad "could not seed a LibraryPath row for the scan-lock flow (library 2)"
else
# Never observed active within 10s: don't assert a race we can't prove we won (advisory skip).
skip "library-2 scan never observed active within 10s -> not asserting the 409 (seed=60 files)"
# No ?deep -- local scans always ForceScan (ForceScanLocalLibrary.ForceScan is hardcoded true;
# `deep` only matters for Plex/Jellyfin/Emby), so a fresh library 2 scan runs unconditionally.
expect_status "POST /libraries/2/scan -> 202 (queued)" 202 POST "$BASE_URL/api/v1/libraries/2/scan" \
-H "X-Api-Key: $API_KEY" -H 'Content-Type: application/json' -d '{}'
# Poll scan-status until the scan is provably in flight, then fire the racing scan. The active
# window is a strict subset of the lock's held window, so this is deterministic bar a tiny
# residual TOCTOU gap (observe-active -> 2nd POST lands) that the multi-second scan covers.
# Match the id exactly (trailing comma) so "libraryId":2 can't match "libraryId":20 etc.
scan_active=""
for _ in $(seq 1 100); do
if api "$BASE_URL/api/v1/libraries/scan-status" | grep -q '"libraryId":2,'; then scan_active=1; break; fi
sleep 0.1
done
if [ -n "$scan_active" ]; then
ok "scan-status shows library 2 active (scan lock provably held)"
expect_status "second POST /libraries/2/scan while scanning -> 409" 409 POST "$BASE_URL/api/v1/libraries/2/scan" \
-H "X-Api-Key: $API_KEY" -H 'Content-Type: application/json' -d '{}'
else
# Never observed active within 10s: don't assert a race we can't prove we won (advisory skip).
skip "library-2 scan never observed active within 10s -> not asserting the 409 (seed=60 files)"
fi
fi
else
bad "ffmpeg present but failed to synthesize the seed clip for the scan-lock flow"
@@ -270,7 +287,9 @@ else
fi
# --- Flow B: external-collections already-scanning 409 (per-family lock; no ffmpeg/scanner) ---
MSID="$(seed_jellyfin_source 'http://10.255.255.1:8096')"
# TEST-NET-1 (RFC 5737) is guaranteed non-routable, so the background sync hangs; but Flow B is
# race-free regardless (the 202 already proves the lock held -- the hang only widens the margin).
MSID="$(seed_jellyfin_source 'http://192.0.2.1:8096')"
if [ -n "$MSID" ]; then
ok "seeded Jellyfin media source id=$MSID (non-routable -> sync hangs, lock stays held)"
expect_status "POST /media-sources/jellyfin/$MSID/scan-collections -> 202" 202 POST "$BASE_URL/api/v1/media-sources/jellyfin/$MSID/scan-collections" \