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: 7 additions & 7 deletions doc/bin/cli.md
Original file line number Diff line number Diff line change
Expand Up @@ -329,12 +329,12 @@ rtsp` one per RTSP session, and `import ts --program all` one per program.
A restarted process takes the name at once: viewers see the broadcast restart,
and their next subscribe reaches the new run instead of waiting for its group
numbers to catch up. Epochs cross a connection only on moq-lite 07, which is
opt-in, and order by the host's clock there, so a host whose clock runs behind
the old run's waits for it to close. Older versions and moq-transport carry no
epoch, so a restart from another session is the newest route at an equal cost,
or a better one.
opt-in, and on moq-transport draft 17 and later, and order by the host's clock
there, so a host whose clock runs behind the old run's waits for it to close.
Other versions carry no epoch, so a restart from another session is the newest
route at an equal cost, or a better one.

On moq-lite 07, two processes that pass the same `--epoch` (a UUIDv7, such as
On a version that carries epochs, two processes that pass the same `--epoch` (a UUIDv7, such as
`uuidgen -7` prints) are one publisher: relays fail over between them
mid-group, so they must produce identical tracks with aligned groups. Each
derives its catalog clock from the epoch's wall time, so fed one stream they
Expand Down Expand Up @@ -444,8 +444,8 @@ the break. `--linger` also bounds a mid-stream stitch from the replacement
announcement through its first catalog snapshot; expiry exits 1. The default
`--linger 0s` follows only a replacement whose catalog is already available.
Without `--stitch` the export stays on the old publisher while it is
up. Only lite-07 sessions carry epochs, so on the default version every return
is a replacement. An export that fails while the broadcast stays up, such as on
up. Only lite-07 and moq-transport draft 17+ sessions carry epochs, so on the
default version every return is a replacement. An export that fails while the broadcast stays up, such as on
a codec TS cannot carry, exits 1 without lingering. Only `ts` can mark a break,
so the other formats refuse `--linger`.

Expand Down
2 changes: 1 addition & 1 deletion doc/bin/gstreamer.md
Original file line number Diff line number Diff line change
Expand Up @@ -68,7 +68,7 @@ Each `sink_%u` request pad is one track. Pad properties: `track` names it
reports `failed` on an answer redialing can't change, such as a rejected token.
Each run from `READY` publishes under a fresh
[publisher epoch](/concept/moq-lite#publisher-epochs), so on moq-lite 07 (opt-in)
viewers switch to a restarted pipeline at once instead of stalling on the old
or moq-transport draft 17 and later, viewers switch to a restarted pipeline at once instead of stalling on the old
one; reconnects within a run keep it. The first catalog waits for a timed buffer
to place the shared wall clock and for every requested pad to negotiate its
rendition, including any codec config carried in its first buffers. A linked pad
Expand Down
7 changes: 4 additions & 3 deletions doc/bin/relay/cluster.md
Original file line number Diff line number Diff line change
Expand Up @@ -37,9 +37,10 @@ publishes under a new epoch, which replaces the old broadcast instead of
resuming it; the RTMP, SRT, and WHIP ingests mint one per connection. Epochs
order by creation time, so a reconnect to a different gateway assumes the two
gateways' clocks roughly agree. Seamless failover needs a publisher that
announces an epoch and moq-lite 07 on every link the route crosses. A route
without an epoch, including every route on moq-lite 06 and older or
moq-transport, keeps its subscriptions until it goes or a track fails
announces an epoch and, on every link the route crosses, moq-lite 07 or
moq-transport draft 17 or later with the [epoch extension](/draft/moq-epoch). A route
without an epoch, including every route on moq-lite 06 and older or a
moq-transport link without the extension, keeps its subscriptions until it goes or a track fails
upstream, and any other route winning it is announced as a restart. Viewers
re-request on a restart, and a relay drops its copy of the old instance,
including every path beneath a prefix claim when one of them moves to another
Expand Down
4 changes: 3 additions & 1 deletion doc/bin/relay/config.md
Original file line number Diff line number Diff line change
Expand Up @@ -37,6 +37,7 @@ allow.uid = [1001]
[listen.extensions] # moq-transport SETUP extensions to offer, each on by default.
auth = false # Decline MoQ Auth (draft 17+).
solicit = false # Decline MoQ Solicit, so peers may announce unasked.
epoch = false # Decline MoQ Epoch, so routes over moq-transport carry no epoch (draft 17+).
```

`timeout` bounds the whole handshake, transport through MoQ SETUP, so a peer
Expand Down Expand Up @@ -275,7 +276,8 @@ tls.key = "relay.key"
goaway.redirect = "same-host" # How far to trust a draining peer's redirect URI.
goaway.handover = "10s" # Cap on how long the drained upstream keeps serving.
extensions.auth = false # Decline MoQ Auth on outbound moq-transport sessions.
extensions.solicit = false # Decline MoQ Solicit. Both default to on, as in [listen.extensions].
extensions.solicit = false # Decline MoQ Solicit.
extensions.epoch = false # Decline MoQ Epoch. All default to on, as in [listen.extensions].
```

A draining upstream may name a replacement URI. `same-host` follows it only
Expand Down
19 changes: 12 additions & 7 deletions doc/concept/moq-lite.md
Original file line number Diff line number Diff line change
Expand Up @@ -107,10 +107,15 @@ authorization and hidden names work exactly as without one.
of the old instance, so a new subscriber never sees its cached groups.

The epoch and the restart message travel on moq-lite 07, which is opt-in.
Older moq-lite versions and moq-transport carry neither, so their routes have
no epoch and a restart reaches them as an end then a start of the path. Without
an epoch, any other route winning is a restart, even a reconnect over the same
path, since nothing says it serves the same bytes.
moq-transport carries the epoch from draft 17 when both sides offer the [epoch
extension](/draft/moq-epoch), on by default. A restart onto another epoch is
advertised before the old one is withdrawn, so the path is never absent, and one
that gains or loses an epoch is an end then a start. Older moq-lite versions,
older moq-transport drafts, and a side that declines the extension carry no
epoch. Without an epoch, any other route winning is a restart, even a reconnect
over the same path, since nothing says it serves the same bytes. A peer that
ignores the end and start may keep cached objects of the old run under the same
names, so an end and a start is not a cache flush.

`moq` and `moqsink` mint a fresh epoch per run, kept across reconnects, and the
RTMP, SRT, and WHIP ingests mint one per connection. Replicas share one by
Expand All @@ -127,9 +132,9 @@ compared. A subscription uses the preferred link that has a route and moves to t
next when that route goes; a publisher pushes the same broadcast to every CDN.

The move resumes without a seam only between routes with the same epoch, which
needs moq-lite 07 on both links. A CDN speaking moq-transport carries no epoch, so
moving onto it, or back off it, is a restart and the player requests the path
again.
needs moq-lite 07, or moq-transport draft 17 or later with the epoch extension,
on both links. A CDN link that carries no epoch makes moving onto it, or back
off it, a restart, and the player requests the path again.

### Hidden broadcasts

Expand Down
6 changes: 4 additions & 2 deletions doc/concept/standard.md
Original file line number Diff line number Diff line change
Expand Up @@ -42,11 +42,13 @@ ignores unknown parameters: [cluster](/draft/moq-cluster) routing hop lists,
[hidden](/draft/moq-hidden) to keep `.`-named namespaces out of discovery,
[auth](/draft/moq-auth) to tell each peer what it may publish and subscribe to,
[active-count](/draft/moq-active-count) to count the `NAMESPACE` messages
before a `SUBSCRIBE_NAMESPACE` is synced, and
before a `SUBSCRIBE_NAMESPACE` is synced,
[epoch](/draft/moq-epoch) to carry [publisher epochs](/concept/moq-lite#publisher-epochs)
without changing a path, and
[probe](/draft/moq-probe) for bandwidth estimation. Rust sessions request PROBE
only while an owned `recv_bandwidth()` consumer is held. Read estimates through
its `peek()` or `changed()` methods; session statistics do not request PROBE.
Both libraries offer solicit and auth (draft 17 and later) unless a side's
Both libraries offer solicit, auth, and epoch (draft 17 and later) unless a side's
`extensions` setting declines one, which connects it as a peer that does not
speak that extension. The pooled JavaScript `Connection` has no such setting yet.
[moq-e2ee](/draft/moq-e2ee) is not a transport extension. It encrypts
Expand Down
5 changes: 3 additions & 2 deletions doc/concept/stats.md
Original file line number Diff line number Diff line change
Expand Up @@ -61,8 +61,9 @@ Each announcement carries a fresh [publisher epoch](/concept/moq-lite#publisher-
on its route, so a restarted node or a group returning from idle is a new
broadcast at the same path: it replaces the old one, and no relay serves it
groups cached under the old epoch. A reader treats each epoch as its own set of
counters. The epoch rides moq-lite 07 announcements; over older versions and
moq-transport a reader sees the same change as an end and a start at the path.
counters. The epoch rides moq-lite 07 announcements, and moq-transport draft 17
and later with the [epoch extension](/draft/moq-epoch); over anything else a
reader sees the same change as an end and a start at the path.
An aggregating reader pins each node's subscription to its epoch, and when one
publisher is reached through both kinds of link (with and without an epoch), it
carries only that path's outgoing counters across the change.
Expand Down
5 changes: 3 additions & 2 deletions doc/setup/upgrade.md
Original file line number Diff line number Diff line change
Expand Up @@ -50,8 +50,9 @@ These land with the next breaking release.
their readers upgraded together.
- **Announce restarts.** moq-lite 07 adds `ANNOUNCE_RESTART` (0x3): another
publisher instance now serves the prefix. lite-06's `ANNOUNCE_RESTART` is
named `ANNOUNCE_UPDATE`, as it always meant. On moq-lite 06 and older and
moq-transport, a restart is still an end then a start.
named `ANNOUNCE_UPDATE`, as it always meant. moq-transport draft 17 and later
with the epoch extension advertise another epoch before withdrawing the old
one. Elsewhere, a restart is still an end then a start.
- **Publisher epochs ride the route** (#4942). moq-lite 07 carries the epoch
after the path in `ANNOUNCE_START`, `TRACK`, `SUBSCRIBE`, and `FETCH`.
Routes without an epoch no longer resume across routes, so default lite-06
Expand Down
10 changes: 8 additions & 2 deletions drafts/draft-lcurley-moq-cluster.md
Original file line number Diff line number Diff line change
Expand Up @@ -144,8 +144,9 @@ NAMESPACE Message (Cluster) {
~~~

The added fields are encoded exactly as in PUBLISH_NAMESPACE.
Negotiating this extension enables the block on every NAMESPACE, with a parameter count of 0 when it is empty; when another extension defines the same block an endpoint appends one block holding the parameters of both, not two blocks.
An endpoint MUST NOT append the block when nothing negotiated it, and MUST NOT include HOP_PATH or ROUTE_COST unless this extension is.
Other extensions, such as MoQ Epoch (draft-lcurley-moq-epoch), carry their NAMESPACE parameters in the same block.
A session appends exactly one block to every NAMESPACE when it negotiated any extension that uses the block, holding the parameters of all of them in any order, with a count of 0 when none applies; it appends none when it negotiated none.
An endpoint MUST NOT include HOP_PATH or ROUTE_COST unless this extension is negotiated.

NAMESPACE_DONE ({{moqt}} Section 10.17) carries no state from this extension.

Expand Down Expand Up @@ -226,6 +227,7 @@ An advertisement lives as long as its stream, so an update on a new stream would
An endpoint MUST NOT open a second stream for an advertisement it already maintains on the session.

An update replaces the old parameters atomically, so a receiver MUST NOT tear down subscriptions or drop cached state because one arrived, even when the first HOP_PATH entry changed: the namespace still names the same content ({{publishers}}).
An update never changes an advertisement's instance; under MoQ Epoch another instance is a new advertisement.

The expected update is a ROUTE_COST change, which is how a relay signals that it started or stopped carrying the namespace.

Expand Down Expand Up @@ -261,6 +263,9 @@ Under this extension an advertisement is a path, so a session advertises a names

A namespace names one broadcast whichever publisher serves it, so several publishers of it are redundant copies: their groups are one sequence, and a subscription moves between them without a gap.
A publisher MUST NOT reuse a namespace for different content, and publishes a new instance under a new namespace instead.

A session that negotiated MoQ Epoch names the instance instead: the namespace and EPOCH together name the content, so only advertisements with the same EPOCH are redundant copies, and a publisher MAY reuse the namespace for a new instance under a new EPOCH.
A receiver MUST NOT move a subscription between advertisements with different EPOCHs, or between advertisements without one.
A refusal never moves to another publisher ({{selection}}).
A relay that moves to another publisher MUST update its advertisement to the new path ({{updating}}).

Expand Down Expand Up @@ -311,6 +316,7 @@ The Key-Value-Pair parity is load-bearing: HOP_PATH is odd, so its value is a le
# Appendix A: Changelog

## moq-cluster-02
- Exactly one NAMESPACE parameter block is appended when any extension that uses it is negotiated, holding the parameters of all of them. Under MoQ Epoch, only advertisements with the same EPOCH are redundant copies, and an update never changes the instance.
- A namespace names one broadcast whichever publisher serves it, and a publisher MUST NOT reuse one for different content. A receiver MAY fail a subscription over between any of its advertisements, continuing from the first object the subscriber lacks instead of at a group boundary. Replaces the first-Hop-ID publisher identity.
- Defined request resolution against the longest covering prefix; every refusal is terminal, including between several publishers of one namespace, and capacity is signaled only by withdrawing or re-pricing the advertisement.
- A relay does not advertise a namespace because it resolved it; the publisher advertises the concrete namespace once producing.
Expand Down
Loading
Loading