Delivery notes

Written for people debugging a playback problem that involves this node. It documents the behaviour you can rely on, and a few behaviours you should not.

Signed paths

Every deliverable path carries an expiry and a signature. The node verifies both before it looks at the cache, so a bad signature never causes a disk read and never appears in the hit ratio. Verification failures are indistinguishable from each other on purpose: expired, malformed and forged all produce the same 403 with the same body.

# shape of a deliverable path
/v1/{asset}/{rendition}/seg-{index}.m4s?e={unix-expiry}&s={signature}

# what the node checks, in order
1. prefix is configured on this tier      -> otherwise 404
2. e is in the future                     -> otherwise 403
3. s matches over path + e                -> otherwise 403
4. cache lookup                           -> hit, or refill from shield

Clock skew

Expiry is evaluated against the node clock, which is NTP-synced with a hard alarm above 250 ms of offset. If you are issuing links with a very short window, allow at least a few seconds of slack — a link that expires in two seconds will lose the race on a slow mobile handshake.

Cache keys

The key is the path plus the query parameters that change the bytes. Today that means the rendition selector only; e and s are excluded, as is anything a player or an analytics library appends. This is why two links with different signatures hit the same cached object.

Query parameter order does not affect the key.
Unknown parameters are dropped from the key, not rejected from the request.
Accept-Encoding is part of the key for text-like objects only; media segments are stored once, uncompressed.
The key never includes a client address, cookie or user agent. There is no per-viewer variation to reason about.

Range requests

Ranges are served from whichever tier holds the object. A range that spans a gap in a partially stored object is satisfied by fetching only the missing extents from the shield, not by refetching the object. Multi-range requests are answered with a single range — the largest requested one — rather than a multipart body, because no player we serve needs multipart and the code path is a liability.

Response headers worth reading

X-Cache: HIT, MISS, PARTIAL or BYPASS. PARTIAL means some extents came from the shield during this request. Always include this value in a bug report.
X-Node: Opaque node identifier. Stable for the life of the machine. It is the fastest way for us to find your request in the logs.
Age: Seconds since the object was stored. A large Age with a playback problem points at stale content upstream, not at the node.
Accept-Ranges: Always bytes for media paths. Its absence means you did not reach a media path — check for a redirect.

There is no cache purge endpoint exposed here. Invalidation happens by changing the asset path upstream, which is safe under concurrency; a purge API is not, so we do not run one on the edge.

Refill and origin protection

A miss becomes at most one shield request, no matter how many clients ask for the same object simultaneously — the second and subsequent requests wait on the first. This collapsing is per node, so a cold fleet still produces one shield request per node, which is the reason rollouts are staged rather than fleet-wide.

When the shield is unreachable, the node prefers serving a stale object over failing: an expired but resident object is returned with a warning header for up to fifteen minutes. Past that it returns 504 rather than serving unbounded stale media.

Reporting a problem

Send the full request URL, the complete response headers, X-Node, X-Cache and a UTC timestamp to the contact in security.txt. A description of the symptom without the headers cannot be traced to a request and will come back with a request for them.