@torrent-tv/proxy 2.9.35 → 2.9.37

package/CHANGELOG.md

@@ -1,6 +1,14 @@
+## 2.9.37
+
+- **Fix**: Scrubbing (server-side seek) no longer hangs the player. A far segment request restarts ffmpeg at that position; native players (notably iOS HLS) issue a burst of scattered far requests after a scrub (observed: `367 → 732 → 369 → 368 → 370`, tens of seconds apart), and the old fixed 4 s cooldown only suppressed restarts within 4 s of the last — so each scattered request restarted ffmpeg and it ping-ponged between positions, producing nothing and stalling playback. Far requests are now **debounced**: the target index is recorded and a short settle timer armed (1.2 s quiet period, 2.5 s hard cap from the burst's first request); further far requests re-arm it and update the target to the latest index; when it settles, ffmpeg restarts once at that index. "Last index wins" self-corrects — a wrong target costs at most one extra settle, never the old infinite loop. The settle timer is cleared on session disposal. (OpenSpec change `seek-debounce`.)
+
+## 2.9.36
+
+- **New**: Chunked request bodies over the data channel (OpenSpec change `chunked-request-bodies`). Large request bodies — notably the source registration, whose body is the base64 `.torrent` (hundreds of KB for a multi-season pack) — now arrive as bounded binary frames (the response-frame layout) announced by a `request-start` message, and are reassembled and run through the same path as a single-message request. Bounded: 32 MB per-body cap, a 60 s TTL for incomplete bodies, an abort frame that drops partial state at once, and all per-channel state freed on channel close. This removes the single-message size ceiling symmetrically with responses (which already stream in chunks). Logged as `body=<bytes> bytes (chunked)`.
+
 ## 2.9.35
 
-- **Fix**: Large torrents (many files / seasons) no longer fail with "Trying to send message larger than max-message-size" when a file is picked. The browser sends the source registration body — the base64-encoded `.torrent` — in a single data-channel message; a big multi-season pack's `.torrent` carries thousands of piece hashes (e.g. Poirot, 13 seasons: 420 KB → ~560 KB base64), exceeding libdatachannel's default advertised limit of 256 KB, so the browser's `channel.send()` threw. The proxy now advertises a 16 MB `a=max-message-size`, so the browser permits the large send. Responses (proxy→browser) were already safe — they stream in small chunks. Verified the SDP now carries `a=max-message-size:16777216` (was `262144`).
+- **Fix**: Large torrents (many files / seasons) no longer fail with "Trying to send message larger than max-message-size" when a file is picked. The browser sends the source registration body — the base64-encoded `.torrent` — in a single data-channel message; a big multi-season pack's `.torrent` carries thousands of piece hashes (e.g. Poirot, 13 seasons: 420 KB → ~560 KB base64), exceeding libdatachannel's default advertised limit of 256 KB, so the browser's `channel.send()` threw. The proxy now advertises a 16 MB `a=max-message-size`, so a large single send still works while already-open tabs run the old bundle. Verified the SDP now carries `a=max-message-size:16777216` (was `262144`).
 
 ## 2.9.34
 

package/openspec/changes/chunked-request-bodies/design.md

@@ -0,0 +1,81 @@
+# Design: Chunked request bodies (proxy side)
+
+Written to be executed as specified — the wire format, constants, limits
+and do-NOT list are normative. Read before coding:
+
+- `services/data-channel-handler.js`: the whole file — the wire-protocol
+  doc comment (~lines 9–37), `handleChannel` (onMessage string handling),
+  `handleRequest`, `sendChunk` (the response frame writer whose layout the
+  request frames mirror), `send`.
+
+## Wire protocol (additions)
+
+Existing messages are UNCHANGED. New:
+
+    Browser → Proxy, announcing a chunked request:
+      { type: "request-start", requestId, method, path, query, headers,
+        bodyBytes }          // bodyBytes = exact total body size in bytes
+
+    Browser → Proxy, body frames (BINARY messages — today the proxy only
+    ever receives strings, so binary is unambiguous):
+      byte 0        flags     bit 0: done (last frame)
+                              bit 1: aborted (drop this request, no reply)
+      byte 1        idLen     requestId length in bytes
+      bytes 2..2+N  requestId (ASCII)
+      bytes 2+N..   payload   raw body bytes (UTF-8 of the body string;
+                              may be empty on a done/abort frame)
+
+Identical layout to the response frames (`sendChunk`) — one mental model,
+and the browser already has a parser for it (its builder mirrors it).
+
+No capability negotiation: POC, single-proxy pool, lockstep releases
+(proxy first, then server). The 16 MB `maxMessageSize` advertisement in
+webrtc-manager.js (pending 2.9.35) stays as a one-line transition cover
+for tabs still running the single-send bundle.
+
+## Constants
+
+    PROXY_MAX_REQUEST_BODY_BYTES = 32 * 1024 * 1024
+    PARTIAL_REQUEST_TTL_MS = 60_000
+
+## Assembly (all state per channel, inside `handleChannel`'s closure)
+
+    const partials = new Map(); // requestId → { meta, chunks: [], receivedBytes, timer }
+
+- `request-start`: validate like a legacy request (same path allowlist —
+  run the SAME validation before accepting the body; reject with
+  `response-error` immediately on a bad path). Reject `bodyBytes` >
+  PROXY_MAX_REQUEST_BODY_BYTES with `response-error` "Request body too
+  large." and do NOT create state. Otherwise store `{ meta, chunks: [],
+  receivedBytes: 0 }` and arm the TTL timer.
+- Binary frame: parse header; unknown requestId → ignore (stale/aborted).
+  bit 1 (aborted) → clear timer, delete entry, no reply. Append payload,
+  add to receivedBytes; receivedBytes > bodyBytes (or > the cap) →
+  `response-error` + drop. bit 0 (done): concat chunks → body string via
+  `Buffer.concat(...).toString("utf8")`; receivedBytes !== bodyBytes →
+  `response-error` "Request body size mismatch." and drop; else clear
+  timer, delete entry, and execute through the SAME code path a legacy
+  `request` message takes (factor `handleRequest` so both entry points
+  call one function with `{requestId, method, path, query, headers, body}`).
+- TTL fire: delete entry, log
+  `[dc] Session …: dropped stale partial request <id8> (<receivedBytes>B)`.
+- `channel.onClosed`: clear ALL timers and the map (extend the existing
+  handler — do not replace its logging).
+
+## Logging
+
+Chunked request execution logs the SAME `[dc] <method> <path>` line as
+legacy, with `body=<bytes> bytes (chunked)`.
+
+## Rules — do NOT
+
+- Do NOT change the legacy `{type:"request"}` handling, the response
+  framing, ping/pong, or the path allowlist semantics.
+- Do NOT add capability/version negotiation — POC decision, revisit only
+  when the pool has independently-updated proxies.
+- Do NOT revert the 16 MB `maxMessageSize` advertisement (pending 2.9.35).
+- Do NOT hold partial bodies beyond the TTL or channel lifetime; no global
+  (cross-channel) state.
+- Do NOT create a new proxy version: fold into the pending 2.9.35
+  CHANGELOG entry (accumulate bullets, per the versioning rules) and the
+  pending addon 0.2.56 entry.

package/openspec/changes/chunked-request-bodies/proposal.md

@@ -0,0 +1,53 @@
+# Proposal: Chunked request bodies over the data channel (proxy side)
+
+## Why
+
+The browser sends every request as ONE data-channel message, body included.
+Registering a source carries the base64-encoded `.torrent` as that body — a
+big multi-season pack (Poirot, 13 seasons: 420 KB `.torrent` → ~560 KB
+base64) exceeded libdatachannel's default advertised `a=max-message-size`
+of 256 KB, so the browser's `send()` threw "Trying to send message larger
+than max-message-size" and playback dead-ended.
+
+The committed-but-unpublished stopgap (advertise 16 MB, pending 2.9.35)
+lifts the ceiling but keeps the flaw: any single-message body still has a
+hard cap, and a large message is buffered whole on both ends. Responses
+already solved this properly — they stream as small binary frames. Requests
+should be symmetric.
+
+## What Changes
+
+- **Inbound binary body frames.** The proxy accepts request bodies as
+  binary frames with EXACTLY the response-frame layout
+  (`[flags][idLen][requestId][payload]`, bit 0 = done; new bit 1 = aborted),
+  announced by a new `{type:"request-start", …, bodyBytes}` control message.
+  On the done frame the assembled body runs through the SAME request
+  execution path as a legacy request. Bounded: per-body cap 32 MB, partial
+  bodies dropped after a 60 s TTL or an abort frame, all per-channel state
+  freed on channel close.
+- **No capability negotiation.** POC: the pool is one proxy, released in
+  lockstep with the site (proxy first, then server). The browser just uses
+  chunked frames for large bodies; this proxy just understands them.
+- **The 16 MB `max-message-size` advertisement (pending 2.9.35) stays** —
+  a single config value, no logic: it covers the transition window while
+  already-open tabs still run the single-send bundle.
+- **Observability**: the `[dc]` request log line reports chunked bodies
+  (`body=<bytes> bytes (chunked)`).
+
+Browser-side counterpart (chunk writer, threshold, backpressure, abort) is
+the server repo's `chunked-request-bodies` change. Release order: proxy
+(with addon bump) FIRST, then server.
+
+## Capabilities
+
+### New Capabilities
+
+- `chunked-request-bodies`: request-body transport over the data channel.
+
+## Impact
+
+- `services/data-channel-handler.js` — binary inbound frame parsing;
+  per-channel partial-body assembly with caps/TTL; `request-start`
+  handling; shared execution path.
+- Release: folds into the PENDING proxy 2.9.35 (extend its CHANGELOG entry;
+  do not create a new version) + ha-addon 0.2.56 (same rule).

package/openspec/changes/chunked-request-bodies/specs/chunked-request-bodies/spec.md

@@ -0,0 +1,30 @@
+# chunked-request-bodies — delta spec (proxy)
+
+## ADDED Requirements
+
+### Requirement: Request bodies arrive in bounded binary chunks
+
+The proxy SHALL accept a request whose body is delivered as binary frames
+(mirroring the response-frame layout) announced by a `request-start`
+control message, assemble it, and execute it through the same path as a
+single-message request. Assembly SHALL be bounded: a per-body byte cap, a
+TTL for incomplete bodies, an abort flag that drops the partial state, and
+release of all partial state when the channel closes. Legacy single-message
+requests SHALL keep working unchanged.
+
+#### Scenario: Large .torrent registration
+- **WHEN** the browser registers a multi-season torrent whose base64 body
+  exceeds any single-message limit
+- **THEN** the body arrives in frames, the source registers, and the
+  response streams back exactly as for a small request
+
+#### Scenario: Oversized or inconsistent body
+- **WHEN** the announced or delivered size exceeds the cap, or the
+  delivered bytes do not match the announcement
+- **THEN** the proxy replies with a response-error for that request and
+  drops the partial state; the channel and other requests are unaffected
+
+#### Scenario: Sender vanishes mid-body
+- **WHEN** frames stop arriving (tab closed, aborted without a frame)
+- **THEN** the partial body is dropped after the TTL (or immediately on
+  channel close) and its memory is released

package/openspec/changes/chunked-request-bodies/tasks.md

@@ -0,0 +1,40 @@
+# Tasks: Chunked request bodies (proxy side)
+
+Execute in order; design.md is normative. Read the code regions listed at
+its top first.
+
+## 1. Implementation
+
+- [ ] 1.1 `data-channel-handler.js`: factor the execution tail of
+      `handleRequest` so a legacy `request` message and an assembled
+      chunked request run the SAME function. `node --check`.
+- [ ] 1.2 `request-start` + binary inbound frames + per-channel assembly
+      with cap (32 MB), size-mismatch check, abort flag (bit 1), TTL
+      (60 s), cleanup on channel close. Unknown-requestId frames ignored.
+- [ ] 1.3 Logging: `body=<bytes> bytes (chunked)` on execution; stale-drop
+      line on TTL.
+
+## 2. Verification
+
+- [ ] 2.1 Node loopback test (two node-datachannel PeerConnections in one
+      script, like the SDP test): drive a request-start + 64 KB frames of a
+      ~600 KB body through a real channel into a handler instance wired to
+      a stub local server; assert the assembled body bytes match and a
+      response comes back. Also: abort frame → no reply, state dropped;
+      oversized announcement → response-error.
+- [ ] 2.2 Legacy regression: single-message request path byte-identical
+      behaviour (run an existing small request through both entry points).
+- [ ] 2.3 E2E (after the server-side change lands in preview): local stack
+      — preview server + local proxy (`node bin/cli.js --server-url
+      ws://localhost:8080`), register the real Poirot `.torrent`
+      (C:\Users\AntonNemtsev\Downloads\Пуаро_…​.torrent, ~560 KB base64)
+      via the UI; plan returns; `[dc] … body=… (chunked)` in the proxy log.
+
+## 3. Release
+
+- [ ] 3.1 EXTEND the pending 2.9.35 CHANGELOG entry (do not bump again) and
+      the pending addon 0.2.56 entry.
+- [ ] 3.2 `npm run patch` in proxy (publishes 2.9.35), push addon bump,
+      update the addon in HA; verify `Starting @torrent-tv/proxy v2.9.35`
+      in the addon log. Proxy FIRST, then addon, then the server-side
+      change releases independently.

package/openspec/changes/seek-debounce/design.md

@@ -0,0 +1,118 @@
+# Design: Debounce server-side seek restarts
+
+Normative — member names, constants, and edge cases as written. Read before
+coding:
+
+- `services/hls-session-manager.js`: `#ensureEncodingFor(session, index)`
+  (line ~1478 — the restart decision), the session object shape where
+  `lastRestartAt` / `pendingRestartIndex` / `encodeStartIndex` live (~883),
+  `#startEncodeRun`, `disposeSession` (must clear timers), and the constants
+  block (~36–58).
+
+## Current behaviour (what we are replacing)
+
+`#ensureEncodingFor` runs per segment request:
+
+1. Compute the look-ahead window `[head, currentSeg + MAX_LOOKAHEAD_SEGMENTS]`.
+2. In window → return (the running encode will reach it).
+3. Out of window (a seek) → if `now - lastRestartAt < RESTART_COOLDOWN_MS`,
+   skip; else `#startEncodeRun(session, index)` immediately.
+
+The cooldown is a fixed 4 s gap. Requests spaced wider than 4 s each restart
+→ ping-pong. That is the bug.
+
+## New behaviour: settle window (debounce)
+
+Keep steps 1–2. Replace step 3 with a debounce:
+
+    far request (index outside window):
+      session.seekTarget = index                       // last far index wins
+      if (!session.seekSettleTimer):
+        session.seekFirstFarAt = now()
+      else:
+        clearTimeout(session.seekSettleTimer)
+      const waited = now() - session.seekFirstFarAt
+      const delay = waited >= SEEK_SETTLE_MAX_MS ? 0
+                    : Math.min(SEEK_SETTLE_MS, SEEK_SETTLE_MAX_MS - waited)
+      session.seekSettleTimer = setTimeout(() => fireSettledSeek(session), delay)
+      return                                            // do NOT restart now
+
+    fireSettledSeek(session):
+      const target = session.seekTarget
+      session.seekSettleTimer = null
+      session.seekTarget = null
+      session.seekFirstFarAt = 0
+      if (session disposed or target == null) return
+      // Minimum gap between actual restarts (defensive; the settle already
+      // collapses bursts). If still cooling down, re-arm once for the
+      // remaining cooldown instead of restarting.
+      const sinceRestart = now() - (session.lastRestartAt ?? 0)
+      if (sinceRestart < RESTART_COOLDOWN_MS):
+        session.seekFirstFarAt = now()
+        session.seekTarget = target
+        session.seekSettleTimer = setTimeout(() => fireSettledSeek(session),
+                                             RESTART_COOLDOWN_MS - sinceRestart)
+        return
+      log(`transcode ${id} seek settle → restart at #${target}`)
+      this.#startEncodeRun(session, target)             // sets lastRestartAt
+
+Notes:
+- `timer.unref?.()` on each `setTimeout` so a pending settle never keeps the
+  process alive (mirror the codebase's other timers).
+- A far request whose `index` equals the current `seekTarget` still re-arms
+  the timer (the player is still asking for the same place — that is fine, it
+  just extends the quiet period up to the cap).
+- If, while a settle is pending, the running encode advances so a later
+  request falls back INSIDE the window, that request returns at step 2 and
+  does not touch the settle. The pending settle still fires for the recorded
+  target; that is acceptable (it restarts at a position the player recently
+  wanted). Simplicity over cleverness.
+
+## Constants (add to the constants block)
+
+    // Quiet period after a far (seek) segment request before ffmpeg is
+    // restarted at it. Further far requests within the period re-arm it, so a
+    // scrub that emits a burst of scattered requests collapses to ONE restart
+    // at the position the player ended on.
+    SEEK_SETTLE_MS = 1200
+    // Hard cap on the total settle wait measured from the first far request of
+    // a burst, so a still-moving scrubber cannot delay a real seek forever.
+    SEEK_SETTLE_MAX_MS = 2500
+
+`MAX_LOOKAHEAD_SEGMENTS` and `RESTART_COOLDOWN_MS` keep their current values;
+`RESTART_COOLDOWN_MS` is now only the floor between actual restarts.
+
+## Session state (add where lastRestartAt is initialised, ~883)
+
+    seekSettleTimer: null,   // pending settle timer handle or null
+    seekTarget: null,        // pending far segment index to restart at
+    seekFirstFarAt: 0,       // timestamp of the first far request in the burst
+
+## Disposal
+
+`disposeSession` (and any teardown that abandons a session) MUST
+`clearTimeout(session.seekSettleTimer)` and null it, so a settle cannot fire
+after disposal and restart a dead session.
+
+## Why proxy-side, not client-side (the user's original framing)
+
+The user asked for a scrubber-release debounce. On the in-page media-chrome
+control that is possible but fragile, and — decisively — it cannot cover the
+iOS **native fullscreen** player, whose scrubber the web app does not control;
+the failing session was exactly iOS. The proxy sees the segment requests from
+EVERY client (native iOS, hls.js, direct `<video>`), so debouncing the
+restart here is the one place that fixes all of them. An in-page scrubber
+debounce may still be added later as a responsiveness nicety; it is not a
+substitute and is out of scope here.
+
+## Verification
+
+- Unit-test the timing/target logic in isolation (a fake session + a fake
+  clock/`setTimeout`): a burst of far requests `367,732,369,368,370` within
+  the window collapses to a single `#startEncodeRun` at the LAST index (370),
+  and a lone later far request triggers exactly one more restart.
+- `node --check`.
+- Field: the earlier hang scenario (scrub Poirot on iOS) should now produce a
+  single `seek settle → restart` log line per scrub instead of a train of
+  `seek → restart` lines, and playback should resume after one settle + the
+  (separate, unavoidable) cold-segment wait.

package/openspec/changes/seek-debounce/proposal.md

@@ -0,0 +1,59 @@
+# Proposal: Debounce server-side seek restarts
+
+## Why
+
+Field evidence (iPhone/Safari, Poirot, 2026-07-09): after a scrub the player
+hung indefinitely. The proxy restarts ffmpeg at a requested segment when the
+request lands outside the look-ahead window (server-side seek). The native
+iOS player issued scattered segment requests after the seek —
+`367 → 732 → 369 → 368 → 370` — each 25–35 s apart. The existing guard
+(`RESTART_COOLDOWN_MS = 4000`) only suppresses restarts within 4 s of the
+last one, so with requests spaced far wider than that, EVERY scattered
+request restarted ffmpeg at a new position. ffmpeg ping-ponged between
+positions and never finished a single segment, so playback stalled at
+`currentTime` with `bufferedAhead=0` — "заглохло наглухо".
+
+The fix is the user's idea placed where every client is covered (including
+the iOS native fullscreen player, whose scrubber the web app cannot control):
+don't act on the first far request — wait for the burst to settle, then
+restart ONCE at the position the player ended on.
+
+## What Changes
+
+- Replace the fixed post-restart cooldown as the anti-thrash mechanism with a
+  **settle window**. When a segment request lands outside the look-ahead
+  window (a seek), the proxy does NOT restart immediately: it records the
+  requested index as the pending seek target and arms a short quiet-period
+  timer. Each further far request updates the target to the latest index and
+  re-arms the timer (debounce). When the quiet period elapses with no new far
+  request, ffmpeg restarts ONCE at the pending target. A hard cap bounds the
+  total wait so a genuine seek is never delayed more than a fixed budget even
+  while the scrubber is still moving.
+- Meanwhile the segment route behaves exactly as today — it long-polls and
+  the client retries — so the player simply waits out the (short) settle
+  instead of driving restarts.
+- "Last far index wins" self-corrects: if the settle resolves on the wrong
+  position (e.g. a lone probe request), the player's next request re-arms one
+  more settle — at most one extra cycle, never the old infinite ping-pong.
+
+Out of scope (documented in design.md): an optional client-side scrubber
+debounce for the in-page media-chrome control (helps responsiveness but does
+NOT cover iOS native fullscreen, so the proxy-side settle is the must-have);
+the cold-torrent piece-download and weak-host encode latency that make the
+FIRST post-seek segment slow regardless — the settle removes the infinite
+thrash, not the one-time seek latency.
+
+## Capabilities
+
+### Modified Capabilities
+
+- `seek-debounce` (server-side HLS seeking): far-segment requests are
+  debounced into a single ffmpeg restart at the settled position.
+
+## Impact
+
+- `services/hls-session-manager.js` — `#ensureEncodingFor` gains the settle
+  window; per-session settle state; `disposeSession` clears the timer;
+  constants. `RESTART_COOLDOWN_MS` is retained only as a minimum gap between
+  actual restarts.
+- Proxy release + ha-addon version bump (per release rules).

package/openspec/changes/seek-debounce/specs/seek-debounce/spec.md

@@ -0,0 +1,41 @@
+# seek-debounce — delta spec (proxy)
+
+## ADDED Requirements
+
+### Requirement: Scattered post-seek segment requests collapse to one restart
+
+When segment requests land outside the running encode's look-ahead window
+(server-side seeks), the proxy SHALL NOT restart ffmpeg on each one. It SHALL
+wait a short settle period, treating further out-of-window requests as
+re-arming the period and updating the target to the most recently requested
+index, and then restart the encoder exactly once at the settled target. A
+fixed cap SHALL bound the total settle wait so a genuine seek is not delayed
+indefinitely while the scrubber is still moving. During the settle the
+segment route behaves as before (long-poll / client retry).
+
+#### Scenario: Scrub emits a burst of scattered requests
+- **WHEN** a player, after a seek, requests several far-apart segments in
+  quick succession (e.g. 367, 732, 369, 368, 370)
+- **THEN** ffmpeg is restarted only once, at the last requested index, and
+  produces a continuous run from there — no ping-pong between positions
+
+#### Scenario: Settle resolves on the wrong position
+- **WHEN** the settled restart target turns out not to be where the player
+  ultimately needs to play (e.g. it was a lone probe request)
+- **THEN** the player's next out-of-window request arms exactly one more
+  settle and one more restart — never an unbounded restart loop
+
+#### Scenario: Request falls back inside the window
+- **WHEN** a requested segment is within the current run's look-ahead window
+- **THEN** it is served by the running encode with no restart and without
+  affecting any pending settle
+
+### Requirement: A pending settle never outlives its session
+
+When a session is disposed, any pending settle timer SHALL be cleared so it
+cannot fire and restart a disposed session.
+
+#### Scenario: Session disposed mid-settle
+- **WHEN** a session with a pending seek-settle timer is disposed (idle TTL,
+  shutdown, or teardown)
+- **THEN** the timer is cleared and no encode restart occurs afterwards

package/openspec/changes/seek-debounce/tasks.md

@@ -0,0 +1,33 @@
+# Tasks: Debounce server-side seek restarts
+
+## 1. Implementation (proxy)
+
+- [x] 1.1 Add `SEEK_SETTLE_MS = 1200` and `SEEK_SETTLE_MAX_MS = 2500` to the
+      constants block in `hls-session-manager.js`.
+- [x] 1.2 Add session state `seekSettleTimer: null`, `seekTarget: null`,
+      `seekFirstFarAt: 0` where `lastRestartAt` is initialised.
+- [x] 1.3 Rewrite the out-of-window branch of `#ensureEncodingFor` as the
+      settle/debounce (design.md): record target, arm/re-arm the timer with
+      the capped delay, restart once on fire (`#fireSettledSeek`), re-arm for
+      the cooldown remainder if still cooling down. `timer.unref?.()`.
+- [x] 1.4 `disposeSession`: clear `seekSettleTimer` and null it.
+- [x] 1.5 Restart log line: `transcode <id> seek settle → restart at segment #<target>`.
+
+## 2. Verification
+
+- [x] 2.1 Timing/target logic verified with a fake-clock replica: burst
+      `367,732,369,368,370` → one restart at 370; lone later far request →
+      exactly one more restart (900); disposal mid-settle → no restart; the
+      2.5 s cap forces a fire while the scrubber keeps moving. (Replica, not
+      the wired private method — the methods are private and `#startEncodeRun`
+      spawns ffmpeg; the wired code mirrors the replica.)
+- [x] 2.2 `node --check services/hls-session-manager.js`.
+
+## 3. Release
+
+- [ ] 3.1 CHANGELOG (proxy, next patch) + `npm run patch` (user OTP).
+- [ ] 3.2 Bump `ha-addon/torrent_tv_proxy/config.yaml` + CHANGELOG; push;
+      update the addon in HA.
+- [ ] 3.3 Field: scrub Poirot on iOS → a single `seek settle → restart` per
+      scrub (not a train of `seek → restart`), playback resumes after the
+      settle + the unavoidable cold-segment wait.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@torrent-tv/proxy",
-  "version": "2.9.35",
+  "version": "2.9.37",
   "description": "Torrent proxy client that exposes webseed-like HTTP stream endpoint.",
   "license": "GPL-3.0-or-later",
   "publishConfig": {

package/services/data-channel-handler.js

@@ -95,35 +95,149 @@ export function createDataChannelHandler({ proxyPort, onLog }) {
    * @returns {void}
    */
   function handleChannel(sessionId, channel) {
-    log(`[dc] Session ${sessionId.slice(0, 8)}: channel open`);
+    const tag = sessionId.slice(0, 8);
+    log(`[dc] Session ${tag}: channel open`);
+
+    // Partial chunked-request bodies in flight on THIS channel, keyed by
+    // requestId. Each entry buffers frames until the done frame, then runs the
+    // assembled request through the same path as a single-message request.
+    /** @type {Map<string, { meta: object, chunks: Buffer[], receivedBytes: number, bodyBytes: number, timer: ReturnType<typeof setTimeout> }>} */
+    const partials = new Map();
+
+    const dropPartial = (requestId) => {
+      const entry = partials.get(requestId);
+      if (entry) {
+        clearTimeout(entry.timer);
+        partials.delete(requestId);
+      }
+    };
+
+    /**
+     * Begin assembling a chunked request. Validates the path and size up front
+     * so an invalid or oversized request never buffers a body.
+     *
+     * @param {any} message - The `request-start` control message.
+     */
+    const startPartialRequest = (message) => {
+      const { requestId, method, path, query, headers, bodyBytes } = message ?? {};
+      if (typeof requestId !== "string" || requestId.length === 0) {
+        return;
+      }
+      if (!isValidRequestPath(path)) {
+        send(channel, { type: "response-error", requestId, error: "Invalid request path." });
+        return;
+      }
+      if (!Number.isInteger(bodyBytes) || bodyBytes < 0 || bodyBytes > PROXY_MAX_REQUEST_BODY_BYTES) {
+        send(channel, { type: "response-error", requestId, error: "Request body too large." });
+        return;
+      }
+      dropPartial(requestId); // replace any stale entry with the same id
+      const timer = setTimeout(() => {
+        const entry = partials.get(requestId);
+        partials.delete(requestId);
+        log(`[dc] Session ${tag}: dropped stale partial request ${requestId.slice(0, 8)} (${entry?.receivedBytes ?? 0}B)`);
+      }, PARTIAL_REQUEST_TTL_MS);
+      partials.set(requestId, {
+        meta: { requestId, method, path, query, headers },
+        chunks: [],
+        receivedBytes: 0,
+        bodyBytes,
+        timer
+      });
+    };
+
+    /**
+     * Handle a binary body frame for a chunked request.
+     * Layout: [flags(1)][idLen(1)][requestId(ASCII)][payload].
+     *
+     * @param {Buffer} buf
+     */
+    const handleBodyFrame = (buf) => {
+      if (buf.length < 2) {
+        return;
+      }
+      const flags = buf[0];
+      const idLen = buf[1];
+      if (buf.length < 2 + idLen) {
+        return;
+      }
+      const requestId = buf.toString("ascii", 2, 2 + idLen);
+      const entry = partials.get(requestId);
+      if (!entry) {
+        return; // stale / already-dropped / aborted
+      }
+      if (flags & 2) {
+        // Aborted by the browser — drop silently, no reply.
+        dropPartial(requestId);
+        return;
+      }
+      if (buf.length > 2 + idLen) {
+        const payload = buf.subarray(2 + idLen);
+        entry.chunks.push(Buffer.from(payload));
+        entry.receivedBytes += payload.length;
+      }
+      if (entry.receivedBytes > entry.bodyBytes || entry.receivedBytes > PROXY_MAX_REQUEST_BODY_BYTES) {
+        dropPartial(requestId);
+        send(channel, { type: "response-error", requestId, error: "Request body size mismatch." });
+        return;
+      }
+      if (flags & 1) {
+        // Done frame — assemble and execute.
+        dropPartial(requestId);
+        if (entry.receivedBytes !== entry.bodyBytes) {
+          send(channel, { type: "response-error", requestId, error: "Request body size mismatch." });
+          return;
+        }
+        const body = Buffer.concat(entry.chunks).toString("utf8");
+        void handleRequest(channel, { ...entry.meta, body }, true).catch((error) => {
+          log(`[dc] Session ${tag}: request error: ${error?.message ?? error}`);
+        });
+      }
+    };
 
     channel.onMessage((raw) => {
-      /** @type {DataChannelRequest | { type: "ping", id: string }} */
+      // Binary messages are chunked-request body frames; the proxy otherwise
+      // only ever receives JSON strings, so the type discriminates cleanly.
+      if (typeof raw !== "string") {
+        handleBodyFrame(Buffer.isBuffer(raw) ? raw : Buffer.from(raw));
+        return;
+      }
+
+      /** @type {DataChannelRequest | { type: string, id?: string }} */
       let message;
       try {
-        message = JSON.parse(typeof raw === "string" ? raw : raw.toString());
+        message = JSON.parse(raw);
       } catch {
         return;
       }
 
       if (message.type === "request") {
         void handleRequest(channel, message).catch((error) => {
-          log(`[dc] Session ${sessionId.slice(0, 8)}: request error: ${error?.message ?? error}`);
+          log(`[dc] Session ${tag}: request error: ${error?.message ?? error}`);
         });
         return;
       }
 
+      if (message.type === "request-start") {
+        startPartialRequest(message);
+        return;
+      }
+
       if (message.type === "ping") {
         send(channel, { type: "pong", id: message.id });
       }
     });
 
     channel.onClosed(() => {
-      log(`[dc] Session ${sessionId.slice(0, 8)}: channel closed`);
+      for (const entry of partials.values()) {
+        clearTimeout(entry.timer);
+      }
+      partials.clear();
+      log(`[dc] Session ${tag}: channel closed`);
     });
 
     channel.onError((err) => {
-      log(`[dc] Session ${sessionId.slice(0, 8)}: channel error: ${err}`);
+      log(`[dc] Session ${tag}: channel error: ${err}`);
     });
   }
 
@@ -138,24 +252,22 @@ export function createDataChannelHandler({ proxyPort, onLog }) {
    * @param {DataChannelRequest} req
    * @returns {Promise<void>}
    */
-  async function handleRequest(channel, req) {
+  async function handleRequest(channel, req, viaChunks = false) {
     const { requestId, method, path, query, headers: forwardedHeaders, body } = req;
 
     // Reject paths that are not absolute, contain traversal sequences, or
     // do not start with a known proxy route prefix.  All valid browser-side
     // requests use /api/*, /stream, /transcode/*, /health, or /healthz.
-    if (
-      typeof path !== "string" ||
-      !path.startsWith("/") ||
-      path.includes("..") ||
-      !PATH_ALLOWLIST_RE.test(path)
-    ) {
+    if (!isValidRequestPath(path)) {
       send(channel, { type: "response-error", requestId, error: "Invalid request path." });
       return;
     }
 
     const queryInfo = query ? `?${query}` : "";
-    const bodyInfo = body != null && typeof body === "string" && body.length > 0 ? ` body=${body.length} bytes` : "";
+    const bodyInfo =
+      body != null && typeof body === "string" && body.length > 0
+        ? ` body=${body.length} bytes${viaChunks ? " (chunked)" : ""}`
+        : "";
     log(`[dc] ${method} ${path}${queryInfo}${bodyInfo}`);
 
     const targetUrl = `http://127.0.0.1:${proxyPort}${path}${query ? `?${query}` : ""}`;
@@ -328,6 +440,27 @@ export function createDataChannelHandler({ proxyPort, onLog }) {
  */
 const PATH_ALLOWLIST_RE = /^(?:\/api\/|\/stream(?:$|\?)|\/?transcode\/|\/health(?:z)?(?:$|\?))/;
 
+/**
+ * True when `path` is an absolute, traversal-free path on a known proxy route.
+ * Shared by the single-message and chunked request entry points.
+ *
+ * @param {unknown} path
+ * @returns {boolean}
+ */
+function isValidRequestPath(path) {
+  return (
+    typeof path === "string" &&
+    path.startsWith("/") &&
+    !path.includes("..") &&
+    PATH_ALLOWLIST_RE.test(path)
+  );
+}
+
+/** Max assembled size of a chunked request body (guards proxy memory). */
+const PROXY_MAX_REQUEST_BODY_BYTES = 32 * 1024 * 1024;
+/** Drop an incomplete chunked body if no further frame arrives within this window. */
+const PARTIAL_REQUEST_TTL_MS = 60_000;
+
 /** Pause sending body chunks once the channel buffer exceeds this many bytes. */
 const DC_BUFFER_HIGH_WATER = 8 * 1024 * 1024;
 /** Resume sending once the channel buffer drains to this many bytes. */

package/services/hls-session-manager.js

@@ -43,6 +43,17 @@ const MAX_LOOKAHEAD_SEGMENTS = 8;
 // succession (stall-recovery seeks); without a cooldown ffmpeg ping-pongs
 // between positions, restarting endlessly and producing nothing.
 const RESTART_COOLDOWN_MS = 4_000;
+// Seek debounce. A far (out-of-window) segment request is a server-side seek.
+// Rather than restart ffmpeg on the first one, wait a short quiet period:
+// further far requests re-arm it and update the target to the latest index, so
+// a scrub that emits a burst of scattered requests (e.g. iOS native HLS firing
+// 367,732,369,368,370 seconds apart) collapses to ONE restart at the position
+// the player ended on, instead of ping-ponging ffmpeg between positions and
+// producing nothing.
+const SEEK_SETTLE_MS = 1_200;
+// Hard cap on the total settle wait, measured from the first far request of a
+// burst, so a still-moving scrubber cannot delay a genuine seek forever.
+const SEEK_SETTLE_MAX_MS = 2_500;
 // Idle TTL: a session is disposed this long after the last segment/playlist
 // access. Kept short so an ffmpeg process does not keep burning CPU after the
 // viewer stops or navigates away. Active playback refreshes the timer on every
@@ -884,6 +895,12 @@ export class HlsSessionManager {
       pendingRestartIndex: -1,
       // Timestamp of the last encode (re)start, for the restart cooldown.
       lastRestartAt: 0,
+      // Seek debounce: pending settle timer, the far segment index to restart
+      // at once the burst settles, and the timestamp of the burst's first far
+      // request (for the SEEK_SETTLE_MAX_MS cap).
+      seekSettleTimer: null,
+      seekTarget: null,
+      seekFirstFarAt: 0,
       progress: {
         state: "starting",
         processedSeconds: 0,
@@ -1492,22 +1509,52 @@ export class HlsSessionManager {
     if (withinWindow) {
       return;
     }
-    if (session.pendingRestartIndex === index) {
+    // Far request = a server-side seek. Do NOT restart on the first one:
+    // debounce a burst of scattered requests into a single restart at the
+    // position the player ended on. Record the latest target and (re)arm the
+    // settle timer; the caller long-polls / the client retries meanwhile.
+    session.seekTarget = index;
+    if (session.seekSettleTimer) {
+      clearTimeout(session.seekSettleTimer);
+    } else {
+      session.seekFirstFarAt = Date.now();
+    }
+    const waited = Date.now() - session.seekFirstFarAt;
+    const delay = waited >= SEEK_SETTLE_MAX_MS ? 0 : Math.min(SEEK_SETTLE_MS, SEEK_SETTLE_MAX_MS - waited);
+    session.seekSettleTimer = setTimeout(() => this.#fireSettledSeek(session), delay);
+    session.seekSettleTimer.unref?.();
+  }
+
+  /**
+   * Fire a settled server-side seek: restart the encoder once at the target
+   * recorded during the settle window. Enforces the restart cooldown as a
+   * floor between actual restarts (re-arming for the remainder if still
+   * cooling down). No-op for a disposed session or a cleared target.
+   *
+   * @param {HlsSession} session
+   * @returns {void}
+   */
+  #fireSettledSeek(session) {
+    const target = session.seekTarget;
+    session.seekSettleTimer = null;
+    if (!session || session.state === "disposed" || target == null) {
+      session.seekTarget = null;
+      session.seekFirstFarAt = 0;
       return;
     }
-    // Restart cooldown: a stalled player requests several distant segments in
-    // quick succession; without this guard ffmpeg ping-pongs between them and
-    // never makes progress. Skip the restart during the cooldown — the caller
-    // long-polls / the client retries, and a genuine seek is honored once the
-    // cooldown elapses.
+    // Minimum gap between actual restarts (the settle already collapses bursts;
+    // this only guards back-to-back seeks). If still cooling down, re-arm once
+    // for the remaining cooldown instead of restarting now.
     const sinceLastRestart = Date.now() - (session.lastRestartAt ?? 0);
     if (sinceLastRestart < RESTART_COOLDOWN_MS) {
+      session.seekSettleTimer = setTimeout(() => this.#fireSettledSeek(session), RESTART_COOLDOWN_MS - sinceLastRestart);
+      session.seekSettleTimer.unref?.();
       return;
     }
-    logger.info(
-      `transcode ${session.id} seek → restart at segment #${index} (encode head #${head}, current #${currentSeg})`
-    );
-    this.#startEncodeRun(session, index);
+    session.seekTarget = null;
+    session.seekFirstFarAt = 0;
+    logger.info(`transcode ${session.id} seek settle → restart at segment #${target}`);
+    this.#startEncodeRun(session, target);
   }
 
   /**
@@ -1743,6 +1790,13 @@ export class HlsSessionManager {
     this.sessionsById.delete(sessionId);
     this.sessionIdBySource.delete(session.sourceMapKey);
 
+    // Clear any pending seek-settle timer so it cannot fire and restart a
+    // disposed session.
+    if (session.seekSettleTimer) {
+      clearTimeout(session.seekSettleTimer);
+      session.seekSettleTimer = null;
+    }
+
     if (session.ffmpeg && !session.ffmpeg.killed) {
       session.ffmpeg.kill("SIGTERM");
       await waitForChildExit(session.ffmpeg);