fix(plex): an HLS session's file names are one vocabulary, and a name it cannot produce fails at once

Round 5 added a guard so a request for a segment beyond the produced region
answers instead of polling out the full timeout — the route is a SYNC one, so
every such wait parks a threadpool worker and, through `current_user`, a pooled
DB connection. Measured against real ffmpeg, the guard could not fire where it
mattered.

`-hls_segment_filename seg_%v_%d.ts` substitutes the VARIANT first: a dual-audio
session writes seg_0_0.ts (video) and seg_a0_0.ts / seg_a1_0.ts (the `name:aN`
renditions). The regex read those as sequence-first, so every video segment
parsed as segment 0 and every audio segment did not parse at all — the guard was
inert on every multi-audio item, which is most of this library. `_seg()` carried
the same inversion: the warm-up waited 8 s for `seg_1_0.ts`, a name ffmpeg never
writes, on every multi-audio session start AND every seek-restart.

The layout is now one constant plus one parser (`segment_name` /
`_SEG_NAME_RE`), with a test pinning them to each other, instead of three
comments that could drift — and they had drifted, all three ways.

The guard is also a positive rule now. It was a blocklist, so anything that was
not a single-audio segment name was waved through: `GET …/anything.m3u8` still
parked a worker for 30 s, while the route's comment claimed a flood of hopeless
names was what it prevented. A session produces its playlists and its segments
and nothing else. `.vtt` leaves `_HLS_CT` with it — ffmpeg runs with `-sn` and
subtitles are a separate route, so that extension could only ever name a file
that will not arrive.

Also here:
- A 5000-digit segment index reached the client as a 500: `int()` on an
  unbounded digit run raises past 4300 digits and only OSError was caught. The
  name is bounded on the route and the index in the regex — the same bug class
  the subtitle routes were bounded for.
- A session torn down between the wait and the read is a 404, not a 500. `_kill`
  rmtrees the directory and no lock spans those two steps; the player's recovery
  is keyed on the STATUS, so a 500 skipped the reclaim and ended playback with
  "couldn't play" instead of restarting at the playhead. The trigger is ordinary
  — `loadSession` awaits the new session before destroying the old hls instance.
- Two comments claimed an open player checkpoints every 10 s "whether or not it
  is playing", which is the stated reason the 30 s finished-idle reap is safe.
  `flush` sends nothing once the finish latch is up, or before a position is
  known. The states it does cover — playing or paused mid-item — are the ones
  the rule needs; the comments now say that instead of more.
- The route's tests leave the DB lane: the route reads nothing from the database
  since the auto-start was removed, and there those four regressions SKIP on a
  machine with no Postgres while pytest prints green.

14 tests, mutation-checked: the old parse, the old warm-up name, the blocklist,
both bounds off the absurd name, the unguarded read, and the route dropping
`proc` — each red on the test that names it.

backend/app/routes/plex/playback.py

@@ -323,9 +323,13 @@ def item_progress(
     `_should_push_resume`). `final` (sent on pause / seek / pagehide / unmount) pushes immediately and
     resets the throttle window, so Plex sees a settled position the instant the user pauses or seeks."""
     it = item_or_404(db, rating_key)
-    # An open player checkpoints every 10 s whether or not it is playing, so this is the signal that a
-    # PAUSED viewer still wants their HLS session — the one thing `last_access` could not see, since
-    # it moved only on a file fetch and a paused player fetches nothing (see stream.reap_idle).
+    # A player parked mid-item — playing or PAUSED — checkpoints every 10 s, so this is the signal
+    # that such a viewer still wants their HLS session: the one thing `last_access` could not see,
+    # since it moved only on a file fetch and a paused player fetches nothing (see
+    # stream.reap_idle). It is NOT every open player: `usePlexProgress.flush` sends nothing once the
+    # finish latch is up, or before the first position is known. Those are the states in which
+    # reaping is the right answer anyway, and a viewer who scrubs back into a reaped session gets
+    # the same 404 → reclaim the player already handles.
     plex_stream.touch_session(str(rating_key))
     position = max(0, int(body.position_seconds))
     duration = int(body.duration_seconds)
@@ -622,11 +626,18 @@ def stream_file(
     return FileResponse(str(src))  # Starlette honours the Range header (206)
 
 
+# What a session directory can contain, and nothing else. No `.vtt`: ffmpeg runs with `-sn` and
+# subtitles are independent tracks served by GET /subtitle, so a WebVTT name here could only ever be
+# a name that will not arrive — and accepting it cost a 20 s parked worker per request.
 _HLS_CT = {
     ".m3u8": "application/vnd.apple.mpegurl",
     ".ts": "video/mp2t",
-    ".vtt": "text/vtt",
 }
+# A real artifact name is ~20 characters. The bound is what keeps an absurd one out of the parser:
+# `int()` on an unbounded digit run raises ValueError past 4300 digits (CPython's
+# `sys.get_int_max_str_digits`), which reached the client as a 500 — the same shape of bug the
+# subtitle routes were bounded for (`_RatingKey`, above).
+_HLS_NAME_MAX = 128
 
 
 @router.get("/stream/{rating_key}/hls/{session_id}/{filename}")
@@ -650,17 +661,24 @@ def stream_hls_file(
     auto-start could only ever begin at 0, silently throwing away the viewer's position."""
     # Filename must be a plain hls artifact — no path separators, only the expected extensions.
     ext = "." + filename.rsplit(".", 1)[-1] if "." in filename else ""
-    if ext not in _HLS_CT or "/" in filename or "\\" in filename or ".." in filename:
+    if (
+        len(filename) > _HLS_NAME_MAX
+        or ext not in _HLS_CT
+        or "/" in filename
+        or "\\" in filename
+        or ".." in filename
+    ):
         raise HTTPException(status_code=404, detail="Not found")
     s = plex_stream.current_session(str(rating_key))
     if s is None or s.id != session_id:
         raise HTTPException(status_code=404, detail="No active playback session")
     path = s.dir / filename
-    # A segment beyond the generated region can never arrive: ffmpeg writes them in order, so if the
-    # predecessor is not there this one is not next. Answering now instead of waiting it out is what
-    # keeps a seek past the produced region — or a deliberate flood of hopeless names — from parking
-    # threadpool workers and their DB connections (see `segment_may_arrive`).
-    if not plex_stream.segment_may_arrive(s.dir, filename):
+    # Only a name this session can actually produce is worth waiting for: the playlists, and a
+    # segment whose predecessor is already on disk (ffmpeg writes them in order, so if it is not
+    # there this one is not next). Answering now instead of waiting it out is what keeps a seek past
+    # the produced region — or a deliberate flood of hopeless names — from parking threadpool
+    # workers and their DB connections (see `artifact_may_arrive`).
+    if not plex_stream.artifact_may_arrive(s.dir, filename):
         raise HTTPException(status_code=404, detail="Not available yet")
     timeout = 30 if ext == ".m3u8" else 20
     # `proc` so a session whose ffmpeg has already exited answers at once instead of polling out the
@@ -669,8 +687,19 @@ def stream_hls_file(
     # past the produced region was enough to do it (round 5).
     if not plex_stream.wait_for(path, timeout, proc=s.proc):
         raise HTTPException(status_code=404, detail="Not available yet")
+    try:
+        content = path.read_bytes()
+    except OSError:
+        # The session was torn down between the wait and the read — `_kill` rmtrees the whole
+        # directory, and nothing holds `_lock` across those two steps. It has to present as the same
+        # 404 a gone session does: the player's recovery is keyed on the STATUS (`code === 404`), so
+        # a 500 here skipped the reclaim and ended playback with "couldn't play" instead of
+        # restarting at the playhead. Ordinary trigger: `loadSession` awaits the new session — which
+        # kills and rmtrees the old one — before destroying the old hls instance, so the outgoing
+        # instance's in-flight segment request races the rmtree on every seek-restart.
+        raise HTTPException(status_code=404, detail="No active playback session") from None
     return Response(
-        content=path.read_bytes(),
+        content=content,
         media_type=_HLS_CT[ext],
         headers={"Cache-Control": "no-store"},
     )