Prewarm a VOD source before load(): the cache exists, but only after the session that fills it

[superuser404notfound]

Reported over Discord by the author of Snappier IPTV, who embeds the engine: is there a plan for preloading / caching of VOD content, in the shape KSPlayer offers as an addon?

Half of that already exists, and the half that does not is the half the request is actually about.

What the engine does today

On the VOD paths the engine owns, bytes are already cached on disk for the life of the session:

• The loopback native path fills a SegmentCache: a sliding window with a backward retention budget, so a seek back into watched content is a hit and never reaches the origin again (Loopback-HLS: a single backward seek on heavy 4K can wedge the segment producer (video stalls, audio continues -> A/V desync) #93, Forward-buffer window: 150-segment ceiling silently caps an "unbounded pre-buffer" host option (#102 follow-up) #207). Forward depth is the host's to set through LoadOptions.forwardBufferSegments, up to the whole source, bounded by min(2 GiB, a quarter of free space) with the cap relaxed when the host opts into a large window (configurable forward-buffer window (LoadOptions.forwardBufferSegments) #102, Forward-buffer window: 150-segment ceiling silently caps an "unbounded pre-buffer" host option (#102 follow-up) #207).
• The software VOD path has its own disk FIFO read-ahead since fix(cache): retain software VOD read-ahead across cache-local seeks #512, with the consumer cursor moving alone when a seek lands inside it.
• Within one open, ResidentSpan keeps the head and a speculative tail span so the box-chain walk of a non-fast-start MP4 does not pay a round trip for bytes the reader already had (VOD cold-start pays a mandatory sequential head→tail→re-anchor round trip on non-fast-start MP4 sources — request for parallel fetch or moov-offset hint #281).

Two limits follow from where that state lives:

• It is per session. The segment cache is <tmp>/aether-segments/<uuid>/, flock-held and swept when the session ends (SegmentCache.init's stale-session sweep deletes a concurrent >1h session's directory — the age check has no liveness half #451). Nothing survives the item, let alone the app.
• It is route-bound. On the nativeRemoteHLS bypass AVPlayer fetches the URL itself, so there is no loopback and no cache at all. That is the route an IPTV host takes for an m3u8; a progressive VOD URL (mkv / mp4) takes the loopback path and gets everything above.

What is missing

There is no way to warm anything before load(). Every session starts cold, and a cold open is not free: measured against a 300 ms origin, a non-fast-start MP4 costs two to three sequential round trips before the first sample read, and on a slow origin the first byte of the data connection is the whole perceived start time (#281 and the layout matrix that came out of it). For a host whose UI knows what is next (the next episode, the item under the cursor), those seconds are spendable in advance and are not being spent.

Shape under consideration

A source-level byte prewarm rather than a segment-level one:

• A URL-keyed, process-wide store of resident spans, beside SourceContentLengthCache and SuffixRangeSupport, which are already exactly this shape.
• A public call that fills it for a URL the engine is not playing: the head span, the trailing object where the layout has one, and a bounded run of media bytes.
• AVIOReader consults it on open, at the same place it consults the retained spans today, so a later load() of that URL adopts the bytes and skips the round trips.

Route-independent across the paths the engine owns (loopback native, software host, side demuxers), and by construction not applicable to nativeRemoteHLS, where the engine issues no requests.

Two things it has to get right:

• Identity. The warmed bytes have to be adoptable by a session created later, which is why the key is the source URL and not a session object.
• Arbitration. A speculative fetch that nothing waits on loses its race structurally, which VOD cold-start pays a mandatory sequential head→tail→re-anchor round trip on non-fast-start MP4 sources — request for parallel fetch or moov-offset hint #281 paid for once already. Prewarm has to run under the same per-origin request budget as playback (One request per 32 MB gets me rate limited, and a 429 then kills the session for good #377), and yield to a playing session rather than compete with it for the uplink.

Explicitly out of scope here: persistence across app launches, and offline download. Those are a different feature with a different lifetime and a different disk contract, and are not needed for the reported case.

[superuser404notfound]

Released in 7.7.0 (7b427be). AetherEngine.prewarm(url:httpHeaders:byteBudget:), with isPrewarmed(url:), discardPrewarmedSources() and defaultPrewarmByteBudget alongside it. Contract and limits in docs/api.md; aetherctl play --prewarm measures it against a real origin.

[superuser404notfound]

Reopening until the reporter has had a chance to try it against a real IPTV panel: the measurement that matters here cannot be made on loopback, and this repo's own tests are the only thing that has exercised it so far.

[alsoeoe]

I tested the new prewarm API with a real remote Matroska/MKV source and found a gap between prewarm() and the subsequent load().

Environment:

• AetherEngine revision: fa67d586
• Container: Matroska/MKV
• Source: a stable resolver URL that returns HTTP 302 to a temporary CDN URL

Observed behavior:

1. Prewarm runs before playback and successfully downloads the source head:

   [SourcePrewarm] warmed ... head=8388608B tail=0B

2. During prewarm, the original URL is resolved through HTTP 302 and the final CDN URL is already known.

3. When playback starts, Aether creates a new AVIOReader and requests the original resolver URL again instead of reusing the final URL resolved during prewarm.

4. The repeated redirect added about 3.2 seconds of TTFB in this test:

   • resolver 302 TTFB: ~3247 ms
   • CDN first-byte latency: ~113 ms
   • player mount to playing: ~1.93 s after the source was resolved

This appears related to #12, which caches the resolved redirect URL inside one playback session. However, that resolved URL does not appear to be handed off from the prewarm reader to the playback reader.

Expected behavior:

• prewarm() should pass the final resolved URL to the following load(), or
• the redirect mapping should be cached by the original source URL across prewarm/load, while retaining the existing fallback to the original URL when the CDN URL expires or returns 401/403/404/410.

There is also an MKV-specific observation: prewarm fetched the head only (tail=0B), but FFmpeg immediately requested bytes near EOF while opening this file. Therefore, the prewarm did not cover the actual startup read pattern for this MKV source.

Would you prefer this redirect handoff problem to be tracked here, or should I open a separate issue?

Related: #12 and #281.

[superuser404notfound]

Both of those are real, and the second one has a different cause than it looks like. Fixed in #584.

The redirect handoff. Exactly as you describe: the warm resolved the chain and threw the answer away, and #12's pin is per reader, so the session re-resolved it. Worse than once, in fact: on a harness with a resolver in front of the content origin, one 8 s session paid five resolver hops, because each fresh connection starts from the source URL before the pin is recorded. The warm now carries the URL that answered and the adoption pins it, so the fallback you asked for is the one that was already there: an expired lease drops the pin and re-resolves through the source URL on the existing ladder (401/403/404/410/5xx), nothing new to invalidate. The warm's own tail request rides the resolved target too instead of re-entering through the resolver.

The MKV tail. Your observation is right and the premise in the code was wrong. SourcePrewarmPlan excluded Matroska because matroska_read_header defers its Cues, which is true. What it missed is that the session reads near EOF regardless:

• matroska_execute_seekhead parses every non-Cues object the SeekHead names on the spot (Tags, Chapters, Attachments), and
• on the native path HLSVideoEngine seeks to the middle of the title immediately after the open so libavformat loads the index, priced in its own comment as "1-2 byte-range reads".

So a plain ffmpeg-muxed 63 MB MKV, fully warmed, still spent a request on bytes=63704296-63708626, which is its Cues element to the byte. The plan now reads the SeekHead out of the warm head and fetches from the earliest object past the head to the end of the source, capped at 1 MB, with Cluster entries ignored. On that fixture the cue prewarm seek dropped from 903.3 ms to 0.1 ms and the session issues no trailing request at all.

Two things worth having from your side, since your origin has properties no fixture here does:

1. A run with the branch, if you can build it: SourcePrewarm now logs the resolved host and the tail offset, and [AVIOReader] Cached resolved URL host= should appear once for the whole session.
2. Whether your resolver's target is stable for the length of a session. If it re-signs per request, the pin will get dropped and re-resolved on the first refusal, which is correct but costs one hop; a trace would say how often that happens in practice.

One thing your report also uncovered indirectly: aetherctl play --prewarm, the harness this feature is supposed to be measured with, deadlocked on its first call (top-level code is MainActor-isolated under the Swift 6 language mode, and the warm's Task {} enqueued on the actor the semaphore below it was blocking). Nothing had ever measured this path outside unit tests, which is how both of your findings survived. That is fixed in the same PR.

Keeping this open until there is a release you can test against.

[superuser404notfound]

Released in 7.10.0 (da3576ea, merge 993ca667).

Both halves of the round above are in that tag: the warm hands over the URL that actually answered and the adoption pins it, so a session behind a resolver stops re-resolving on every fresh connection, and Matroska now gets its tail warmed via the SeekHead instead of being excluded on a premise that only held for the Cues.

One thing worth naming from the same round, since it changes what a warm may carry rather than what it fetches: RedirectHeaderPolicy now runs at the request rather than only at the hop, because pinning the resolved target was carrying Authorization and X-Emby-Token to whatever host the chain ended at.

The issue stays open for the retest.