Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
14 changes: 11 additions & 3 deletions doc/bin/relay/config.md
Original file line number Diff line number Diff line change
Expand Up @@ -359,9 +359,17 @@ explicitly, it also caps how long a superseded group stays fresh, whatever max
age the publisher declared; unset, each track keeps its own max age. The latest
group of every track, and any group still being read, is kept past `capacity` but
sheds its oldest frames instead. Whatever the capacity, a group holds at most its
newest 32 MB. A reader of a track's newest group that reaches a shed frame asks
for a new group on tracks that opt into refresh. Any other reader of a shed
frame sees `Evicted`.
newest 32 MB. A reader that reaches a shed frame, such as a late joiner of a long
group, replays it through a flight: a separate copy fetched from the upstream hop
from that frame, paced by its fastest reader and held to its own 32 MB. Readers
within 16 MB of a flight's fastest reader share it, and a reader leaves its
flight for the live copy once that copy holds its frame within 16 MB of the live
reader, which stops the flight. Each hop serves a flight from its own flights in
turn, up to the publisher, which replays only if it serves past groups. A
moq-transport hop streams a FETCH's objects after answering it, so it replays a
finished group, but it refuses a FETCH of a live group that reaches past what
the group holds, so a live group's replay stops there. When nothing replays it, a reader of a track's newest group asks for a
new group on tracks that opt into refresh, and any other reader sees `Evicted`.

While a group has readers, the relay receives at most 16 MB of it past the
fastest one, then stops reading its stream until that reader catches up, so
Expand Down
29 changes: 25 additions & 4 deletions quest/m1/unbounded-groups/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -23,6 +23,25 @@ holds (a tail join).

## Plan

Decided 2026-11-05 (maintainer, /quest-plan), on the open questions of
[moq-dev/moq#7944](https://github.com/moq-dev/moq/pull/7944), which landed
flights:

- A compressed group's flight starts at frame 0, since every later frame
builds on the ones before it, and its riders skip ahead to their frame. The
prefix is transferred once per flight. Carrying the inflater's state from the
cached copy, and keeping refresh or `Evicted` for compressed groups, were
rejected.
- Paced batch fills are [their own quest](/quest/m1/unbounded-groups/paced-batch-fills.md).
- No cap on concurrent flights per group: memory is bounded by each flight's
tail and pool debt, and the cost of more flights is upstream transfer.
Revisit with relay evidence.
- A moq-transport FETCH is answered from metadata: FETCH_OK follows once the
publisher learns the group's live edge, and its objects stream after it,
riding flights, with no whole-group buffer. A FETCH of a live group is
refused unless its range ends below the live edge, and a failure after
FETCH_OK resets the stream. FETCH stays single-group.

Decided 2026-10-28 (maintainer, after an audit of the plan and
[moq-dev/moq#6993](https://github.com/moq-dev/moq/pull/6993)):

Expand All @@ -39,7 +58,7 @@ Decided 2026-10-28 (maintainer, after an audit of the plan and
window is at most 16 MB, so a reader within the behind half of the
fastest one keeps up and a slower one falls off.
- A reader at a shed frame, a late joiner or one that fell off, is served by
a [flight](/quest/m1/unbounded-groups/flights.md) when the publisher has a
a flight ([moq-dev/moq#7944](https://github.com/moq-dev/moq/pull/7944)) when the publisher has a
refill handler: a separate copy with its own upstream fill and 32 MB tail,
paced by its fastest rider. A reader joins a flight only within 16 MB of
its fastest rider, and hands over to the copy ahead at the same frame once
Expand Down Expand Up @@ -147,15 +166,17 @@ origin can regenerate data from disk or an archive.

This epic owns the end-to-end test: a relay chain carries one live group well
past the old caps. A late joiner gets its head through a flight and hands
over to the live copy, and a live reader keeps the tail, over lite and
moq-transport, with memory held near 32 MB per copy. It also carries a long
over to the live copy, and a live reader keeps the tail, over lite, with
memory held near 32 MB per copy; over moq-transport, the live group's replay
is refused and a finished group's replays
([moq-dev/moq#7944](https://github.com/moq-dev/moq/pull/7944)). It also carries a long
compressed group through a small cache pool with a plain reader on a legacy
wire, which [moq-dev/moq#6993](https://github.com/moq-dev/moq/pull/6993)
covered only at the model layer (maintainer, 2026-10-30).

## Required

- [Flights](/quest/m1/unbounded-groups/flights.md) - a reader at a shed frame replays through a separate paced copy that hands over to the copy ahead
- [Paced batch fills](/quest/m1/unbounded-groups/paced-batch-fills.md) - fills that write a batch of groups stop evicting their own earlier groups before the reader takes them
- [Byte holes](/quest/m1/unbounded-groups/byte-holes.md) - segments inside a frame shed like front frames and flights start at `(frame, byte)` on the current lite wip; the frame cap goes
- [JS byte holes](/quest/m1/unbounded-groups/js-byte-holes.md) - `@moq/net` mirrors the byte-offset wire and continues a frame cut off mid-way
- [Compressed frames have no size cap and inflate as a bounded stream](/quest/m1/unbounded-groups/compressed-stream.md) - A compressed frame of any size publishes and is received in Rust and `@moq/net`, like a plain one
8 changes: 2 additions & 6 deletions quest/m1/unbounded-groups/byte-holes.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,8 +4,8 @@

A frame of any size, such as a file delivered as one frame, passes through a
relay holding only a group's 32 MB tail. Sealed segments inside the frame
are shed like front frames, and a [flight](/quest/m1/unbounded-groups/flights.md)
can start at a `(frame, byte)` position on the current lite wip version.
are shed like front frames, and a flight
([moq-dev/moq#7944](https://github.com/moq-dev/moq/pull/7944)) can start at a `(frame, byte)` position on the current lite wip version.
`MAX_CACHE_BYTES` stops capping a frame; it still bounds a group's tail.

## Plan
Expand Down Expand Up @@ -59,7 +59,3 @@ by flights, so this waits on Flights and stays in m1.
Public API: `Position` gains a byte field, frames gain a chunked read, and
`MAX_CACHE_BYTES` stops capping a frame.
Wire: a byte offset on the current lite wip's range ends and group header.

## Required

- [Flights](/quest/m1/unbounded-groups/flights.md) - the paced copies a mid-frame start serves
80 changes: 0 additions & 80 deletions quest/m1/unbounded-groups/flights.md

This file was deleted.

26 changes: 26 additions & 0 deletions quest/m1/unbounded-groups/paced-batch-fills.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,26 @@
# [M] Paced batch fills

## Goal

A `track::Requests` fill that writes a whole batch of groups at once no longer
evicts its own earlier groups before the reader takes them. A reader of a
batch fill reads every group it asked for, at its own pace, without the cache
holding the whole batch.

## Plan

Decided 2026-11-05 (maintainer, /quest-plan): split from
[moq-dev/moq#7944](https://github.com/moq-dev/moq/pull/7944), which landed
flights, into a quest of its own. The failure crosses groups, while a flight
paces one group copy by its riders, and pacing the batch changes what
`Fill::wanted` promises every handler.

The follow-up from [moq-dev/moq#7339](https://github.com/moq-dev/moq/pull/7339),
moved to flights from
[fastest-reader pacing](https://github.com/moq-dev/moq/pull/7664) on
2026-11-02 (maintainer). Recommendation from #7944: `Fill::wanted` yields the
next group only once the readers took the one before, so a handler serving a
batch writes it a group at a time.

Public API: `Fill::wanted`'s contract for handlers, with a `MIGRATE.md` note.
Wire: none.
6 changes: 3 additions & 3 deletions quest/m2/ietf-fill-refill.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,8 @@
## Goal

A moq-transport fill (draft 22) or joining FETCH (draft 18) serves a group's
missing head as a [flight](/quest/m1/unbounded-groups/flights.md): a separate
missing head as a flight
([moq-dev/moq#7944](https://github.com/moq-dev/moq/pull/7944)): a separate
copy whose readers hand over to the subscription's tail copy at the first
object the tail holds, instead of the 7-state `Fill` claim, park, and install
handoff between two producers.
Expand All @@ -30,7 +31,7 @@ Search by those names if the lines have moved again.

Decided 2026-10-28 (maintainer): nothing is written into a group copy below
its live log, so the head no longer fills the tail's group in place. Once
[Flights](/quest/m1/unbounded-groups/flights.md) lands, the head is a flight
[Flights](https://github.com/moq-dev/moq/pull/7944) lands, the head is a flight
from object 0 that hands over to the tail copy, which also keeps a tail
whose head never arrives, as the headless group quest decided. Joining at the next group instead was considered and
rejected: it costs a GOP of startup and drops objects already received.
Expand All @@ -39,5 +40,4 @@ Public API: none. Wire: none.

## Required

- [Flights](/quest/m1/unbounded-groups/flights.md) - separate paced copies and the handover between them
- [moq-transport requests end through one lease](/quest/m2/ietf-request-lease.md) - restructures the same files first
3 changes: 1 addition & 2 deletions quest/m2/resume-redesign.md
Original file line number Diff line number Diff line change
Expand Up @@ -64,7 +64,7 @@ paths diverged.
`Retain`, `Candidate`, and per-reader `learn_end`.
4. `Recover` attaches to the slot, not a handed-out group: continuing a
group whose copy failed is a
[flight](/quest/m1/unbounded-groups/flights.md) from the reader's frame on
[flight](https://github.com/moq-dev/moq/pull/7944) from the reader's frame on
the new route, which hands over like any other flight.

Hard constraint from the splice era: two caches sharing one group handle
Expand All @@ -90,7 +90,6 @@ serving copy's upstream closed, followed by a read.

## Required

- [Flights](/quest/m1/unbounded-groups/flights.md) - the paced copy and handover `Recover` folds into
- [Release cut](/quest/m2/release/cut.md) - wait for the release in flight to ship

## Related
Expand Down
3 changes: 3 additions & 0 deletions rs/kio/src/log.rs
Original file line number Diff line number Diff line change
Expand Up @@ -268,6 +268,9 @@ impl<T: Send + Sync + 'static> Writer<T> {
/// first segment.
pub const HEAP: usize = Self::SHARED + Segment::<T>::heap(FIRST_SEGMENT);

/// Bytes the largest segment occupies: the most one eviction frees at once.
pub const SEGMENT_HEAP: usize = Segment::<T>::heap(MAX_SEGMENT);

/// An empty log whose first entry gets index `start`.
pub fn new(start: u64) -> Self {
Self {
Expand Down
6 changes: 6 additions & 0 deletions rs/moq-net/MIGRATE.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,12 @@ How to update your code for each breaking change, newest first.

## Unreleased

### Readers at a shed frame ask a `track::Requests` handler for a flight ([#7944](https://github.com/moq-dev/moq/pull/7944))

A reader that reaches a frame its group copy shed no longer gets `Error::Evicted` when the track has a live `track::Requests` handle: the handler receives a `Fill` of that one group from that frame (`Fill::start`), or from frame 0 on a compressed track, even though the group is still cached and live.
Accept it as usual and write from that frame, waiting on `group::Producer::ready` so its readers pace it, and stop once `Fill::is_wanted` is false and the group's `demand()` has no reader: they left it for the live copy.
A handler that cannot serve old frames refuses the fill (`Fill::refuse_groups` or dropping it), and the reader falls back to refresh or `Evicted` as before. A track without a handler is unchanged.

### The `async` feature is opt-in ([#7607](https://github.com/moq-dev/moq/pull/7607))

`async` is no longer a default feature. Enable it to keep the sessions (`Client`, `Server`, `Session`), `time::run`, the announcement `Stream` adapter, and every async wrapper such as `next_group`, `read_frame`, or `closed`:
Expand Down
Loading
Loading