Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
17 commits
Select commit Hold shift + click to select a range
2aee55e
wip(net): prefix-route announcements in the core model
kixelated Aug 31, 2026
6ce0214
wip: migrate the rs workspace to prefix-route announcements
kixelated Aug 31, 2026
c7767ee
wip: lint-clean the rs workspace on prefix routes
kixelated Aug 31, 2026
91f6fbe
wip: migrate the ffi wrappers to prefix routes
kixelated Aug 31, 2026
efa8f14
wip(js): route-table origin with lazy materialization
kixelated Aug 31, 2026
9fa5564
wip(drafts): announcements are prefix routes; retire the epoch extension
kixelated Aug 31, 2026
3422d27
wip(doc): prefix-route announcements across the guides
kixelated Aug 31, 2026
18acfba
fix: hold announcement guards and fix two wakeup races found by the s…
kixelated Aug 31, 2026
37b0230
fix: address review, ride out route churn and pin the update prefix
kixelated Aug 31, 2026
4e0f424
fix(js): untrack generated common outputs and model the session provi…
kixelated Aug 31, 2026
7d99bc3
fix: migrate the platform- and feature-gated corners to prefix routes
kixelated Aug 31, 2026
e1da1c8
fix(py): split the aliased Route import for ruff import sorting
kixelated Aug 31, 2026
95a7ed3
feat(net)!: split Prefix from Route and make the announce halves symm…
kixelated Sep 1, 2026
a39c11b
fix(py): drop the route.prefix assertion; the prefix lives on the ann…
kixelated Sep 1, 2026
3ad515d
Merge origin/dev into claude/prefix-routing-refactor-5c22fd
kixelated Sep 1, 2026
f4c67cd
fix(net): retry a queued resolve killed by its route retracting
kixelated Sep 1, 2026
e0189ad
fix(net): classify a resolve failure by request provenance, not poll …
kixelated Sep 1, 2026
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
2 changes: 1 addition & 1 deletion demo/web/src/index.ts
Original file line number Diff line number Diff line change
Expand Up @@ -190,7 +190,7 @@ discovery.run((effect) => {
for (;;) {
const entry = await Promise.race([effect.cancel, announced.next()]);
if (!entry) break;
const path = Net.Path.join(prefix, entry.path);
const path = Net.Path.join(prefix, entry.prefix);
// Only `.hang` broadcasts are watchable streams; this skips the relay's
// `.stats` broadcast (see the stats dashboard demo for that one).
if (!path.endsWith(".hang")) continue;
Expand Down
4 changes: 2 additions & 2 deletions demo/web/src/stats.ts
Original file line number Diff line number Diff line change
Expand Up @@ -109,9 +109,9 @@ discovery.run((effect) => {
for (;;) {
const entry = await Promise.race([effect.cancel, announced.next()]);
if (!entry) break;
const node = entry.path as string;
const node = entry.prefix as string;
if (!node) continue;
const path = Net.Path.join(prefix, entry.path);
const path = Net.Path.join(prefix, entry.prefix);

if (entry.active) {
if (subs.has(node)) continue;
Expand Down
45 changes: 21 additions & 24 deletions doc/bin/cli.md
Original file line number Diff line number Diff line change
Expand Up @@ -374,36 +374,33 @@ Rules worth knowing:

### Redundant Publishers (1+1)

Relays key a broadcast's content identity on the publisher's Hop ID (the
first hop of its announcements). Two publishers of the same broadcast that
share an id are treated as interchangeable sources: relays hold both routes
and fail over between them at a group boundary, so killing one leaves viewers
running off the other.

Sharing an id is a promise: the publishers MUST produce the same broadcast,
meaning the same track names carrying the same content, with group sequences
aligned on the same boundaries. Relays may switch between same-id sources
whenever routing prefers another (not only on failure), splicing at the next
group boundary, so encoders that drift (for example segment-numbered tracks
from processes started at different times) tear down subscribers on the
switch. Independent publishers with different tracks or timelines MUST use
different Hop IDs; the newcomer then takes the broadcast over instead of
joining. Run the same command from two aligned encoders, pinning the same id
on both:
An announcement's route names the publisher's Hop ID as its first hop.
Two publishers of the same broadcast that share an id (and cost) advertise
identical routes, which relays deduplicate: the mesh sees one route while
either publisher is alive, so killing one retracts nothing and the survivor
keeps serving.

A relay never splices a live subscription from one publisher to another.
When the publisher serving a subscription goes away, that subscription ends
and the viewer re-subscribes, landing on the best remaining route; players do
this automatically when the path is (still) announced. So 1+1 buys a fast
resubscribe instead of a dead stream, not a seamless mid-group handover, and
the two encoders should still produce equivalent broadcasts (same track
names, comparable timelines) so a viewer that fails over keeps decoding. Run
the same command from two encoders, pinning the same id on both:

```bash
moq --hop 42 --connect https://relay-a.example.com/anon --broadcast event.hang import ts
moq --hop 42 --connect https://relay-b.example.com/anon --broadcast event.hang import ts
```

Leave `--hop` unset everywhere else. The default fresh id per run is what
makes a restarted encoder look like new content (ending subscriptions and
invalidating caches) instead of silently splicing mid-stream. A publisher with
a *different* id takes the broadcast over the moment it announces, ending the
incumbent rather than waiting behind it, so a reconnect is live again without
waiting for the relay's transport to time out the connection it replaced. The
last publisher to announce a path owns it, so use authorization to decide who
may publish where.
Leave `--hop` unset everywhere else. The Hop ID also feeds loop
detection: a relay drops announcements whose route already contains its own
id, so reusing one id across unrelated publishers can make their routes
invisible to each other. New subscriptions always resolve through the best
current route, newest first on a tie, so a restarted publisher serves new
viewers the moment it announces; use authorization to decide who may publish
where.

### Capture a Webcam

Expand Down
19 changes: 5 additions & 14 deletions doc/bin/relay/cluster.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@ description: Run multiple moq-relay instances across multiple hosts/regions

Relays can be joined together to proxy announcements and subscriptions between each other. A viewer talks to whichever relay is closest; if their broadcast lives somewhere else in the cluster, the local relay fetches it from a neighbor and caches it.

A broadcast carries a small hop list as it travels. Each relay it passes through adds itself to the list, which is how loops are caught and how the network picks the shortest path when there's more than one. When two paths are the same length, every relay breaks the tie the same way (a hash of the broadcast name and hop list), so the whole cluster converges on one route instead of flapping between equals.
An announcement carries a small hop list as it travels. Each relay it passes through adds itself to the list, which is how loops are caught and how the network picks the shortest path when there's more than one. When two paths are the same length, every relay breaks the tie the same way (a hash of the announced prefix and hop list), so the whole cluster converges on one route instead of flapping between equals.

Both wire protocols carry this. `moq-lite` has the hop list and route cost in its announcements natively; `moq-transport` gets them from the [MoQ Cluster extension](/draft/moq-cluster), negotiated per session on `moqt-17` and later. A peer that doesn't speak the extension still works, it just contributes no path or price of its own.

Expand Down Expand Up @@ -53,22 +53,13 @@ connect = [

Price is per direction. Pulling from a metered origin can cost far more than pushing to it, so each end declares its own and the two need not match; a relay that receives a price it disagrees with keeps its own `?cost=` for its own routing. An unpriced direction costs 1, which reproduces plain hop counting.

The cost a relay advertises is the *marginal* cost of pulling the broadcast through it. A relay actively carrying a broadcast (a subscriber is pulling it) re-announces it at cost 0: its upstream fetch is already paid for, so a sibling should pull the warm copy over a free intra-DC link instead of opening a second metered fetch. When the last subscriber leaves, the cost decays back after a short grace period. Standby publishers (e.g. a transcoder pool) can seed a large cost so they are only selected when nothing cheaper exists, and the winner's cost drops to 0 once it starts working.
The cost a relay advertises for a route is the accumulated price of the links it crossed: each relay adds the `?cost=` of the link an announcement arrived on before forwarding it. Routing prefers the most specific announced prefix, then the lowest cost, then the shortest hop list; a remaining tie breaks toward the newest announcement, so a reconnecting publisher is not outranked by the stale session it replaced.

That discount is what makes the cluster share one copy, but it also erases something. Once several relays are all carrying the broadcast they *all* advertise 0, so asking "what does this cost you?" gets the same answer everywhere and can no longer say which of them ought to be the one doing the pulling.
`moq-lite-06` announcements actually carry two prices, *warm* and *cold*: what one more subscription would cost the mesh right now, versus what the same path would cost if nothing along it were cached. The protocol lets a relay that is already carrying content discount its warm price to 0, so a cluster can consolidate onto one warm copy while the cold price still ranks the carriers (see the [moq-lite draft](/draft/moq-lite)). moq-relay does not implement that discount yet: it forwards both prices accumulated, so today they rank identically and routing runs on configured link costs alone.

So `moq-lite-06` announcements carry two prices instead of one:
Prices are not static. A publisher can re-price a live announcement, for example a standby transcoder pool that seeds a large cost so it is only selected when nothing cheaper exists and lowers it once it starts working. A relay that receives a GOAWAY from a peer re-prices every route learned from it to the maximum cost, steering new subscriptions elsewhere while existing ones finish.

- **warm**: what pulling costs right now, given which relays already have it. Zero at any relay that is carrying. This is the number routing minimizes, and it is what consolidates the fleet onto one copy.
- **cold**: what the same route would cost if no relay had it. It ignores the discounts entirely, so it does not collapse, and it keeps saying how far each relay sits from the publisher.

The first picks where a relay fetches from. The second picks which relay does the fetching: a carrying relay hands its subscribers over to another carrying relay only when that one's cold price is lower, so the relay nearest the publisher becomes the aggregation point and the rest consolidate onto it. Relays equally far from the publisher tie there and fall back to a hash of the broadcast path, which spreads ownership across the fleet instead of funneling every broadcast onto one of them.

Both matter. Without the warm price every relay opens its own fetch and the backbone carries N copies. Without the cold price the relays that are already carrying cannot be told apart, so the aggregation point lands wherever a coin flip puts it, which can leave a relay one cheap link from the publisher pulling through a relay several expensive links away.

A relay waits about half a second before moving onto another relay, and re-checks when the wait is up. Prices are reported, not observed, so a report still crossing the mesh can be cheaper than what its sender would say now, and while prices are rising a ring of relays could otherwise each defer to a stale neighbour and all let go at once, leaving nobody pulling. The wait outlasts that propagation, so the re-check runs on current prices, and it carries a small per-relay spread so a whole PoP does not reconsider on the same instant. Some moves never wait: reconnecting to the peer you were already pulling from (recognized by its declared identity, so a relay that withheld one waits like anything else), and repairs, meaning replacing a route that has vanished or stopped announcing, which would otherwise keep the relay on a dead source while a live one sits in the table. Leaving a *draining* route does wait, because a relay that received a GOAWAY keeps serving until its handover window closes, and a fleet draining together is exactly when relays re-parent off prices that have not landed. If the drain turns into a disconnection the route vanishes, and that case is immediate, so the wait is never longer than the session it is waiting on. Only trading a working upstream for a better one waits, and that includes a relay with no viewers, whose choice is simply the one it will pull down when a viewer arrives.

`moq-transport` has nowhere to carry the cold price, so those routes keep the older coin-flip behavior.
`moq-transport` has nowhere to carry the cold price, so a route learned from it ranks with an unknown (worst-case) cold cost.

## Auto-discovery

Expand Down
17 changes: 11 additions & 6 deletions doc/concept/layer/moq-lite.md
Original file line number Diff line number Diff line change
Expand Up @@ -58,21 +58,26 @@ Transports that don't carry a request URI (native QUIC, or qmux over TCP/TLS) al

### Announcements

`moq-lite` optionally supports live discovery of broadcasts.
`moq-lite` optionally supports live discovery via announcements.

Depending on the language, there's an `announced(prefix: Path)` method on the session.
This asks the peer to notify us of any existing broadcasts that match the prefix and any future updates.
An announcement is a **route**: a claim that broadcasts under a path prefix can be served.
Depending on the language, there's an `announce(prefix)` method on the publishing side and an `announced(prefix)` method on the session.
The latter asks the peer for every route that intersects the prefix, plus any future updates.

By convention a publisher announces each broadcast's exact path, so subscribers can enumerate broadcasts by iterating routes.
But a route can also cover a whole subtree: a dashboard server announces one short prefix and serves whatever broadcast is requested beneath it, with no per-broadcast announcement.
It's up to the application to decide that an announced path is a broadcast and request it.

This is extremely useful for conference rooms, as you can live discover when participants join and leave.
It's also useful for individual broadcasts as you can get notifications it comes online or goes offline (no spamming F5).
The [moq-relay clustering](/bin/relay/cluster) feature actually uses this to discover other nodes in the cluster AND what broadcasts are available on each node.

The peer first replies with the set of broadcasts that are currently live, then streams updates as they change.
The peer first replies with the set of routes that are currently advertised, then streams updates as they change.
This initial set is a discrete batch: the latest draft reports how many entries to expect up front, so a freshly connected session can wait until that snapshot has fully arrived before listing what's available, rather than racing the gossip.

Each announcement also describes the route it took: the chain of relay identities it passed through (which is how forwarding loops are caught) and what pulling the broadcast via that route would cost.
Each route also describes the path it took: the chain of relay identities it passed through (which is how forwarding loops are caught) and what pulling content via that route would cost.
The cost comes in two magnitudes, compared in order.
The *warm* cost is what one more subscription would cost the mesh right now, so it collapses to zero at any relay already carrying the broadcast; that is what lets a cluster deduplicate onto a warm copy instead of opening a second ingest.
The *warm* cost is what one more subscription would cost the mesh right now, so it collapses to zero at any relay already carrying the content; that is what lets a cluster deduplicate onto a warm copy instead of opening a second ingest.
The *cold* cost prices the same path as if nothing were cached, so when two warm relays tie at zero it still says which of them sits closer to the publisher.
Subscribers route to the lowest warm cost and break ties on cold; [moq-relay clustering](/bin/relay/cluster) covers how relays use this to pick an aggregation point.

Expand Down
9 changes: 7 additions & 2 deletions doc/lib/go/moq.md
Original file line number Diff line number Diff line change
Expand Up @@ -49,9 +49,14 @@ for ann, err := range announced.All(ctx) {
}
log.Fatal(err)
}
fmt.Println("got broadcast", ann.Path())
// An announcement is a route; its path is relative to the prefix.
fmt.Println("got route", ann.Path())

catalog, err := ann.Broadcast().Catalog(ctx)
broadcast, err := client.RequestBroadcast("demos/" + ann.Path())
if err != nil {
log.Fatal(err)
}
catalog, err := broadcast.Catalog(ctx)
if err != nil {
log.Fatal(err)
}
Expand Down
2 changes: 2 additions & 0 deletions doc/lib/js/@moq/net.md
Original file line number Diff line number Diff line change
Expand Up @@ -75,6 +75,8 @@ request.close(); // when done

Use `origin.announced(prefix)` to discover what is available rather than asking for a path you already know.

`origin.announce(prefix, provider)` is the other half: advertise that paths under a prefix can be served, handing back a broadcast from `provider.consume(path)` for whatever is requested beneath it. Publishing a broadcast announces its exact path already, so reach for this when one service covers a whole subtree. The returned dispose retracts the route.

### Broadcasts

A collection of related tracks.
Expand Down
6 changes: 4 additions & 2 deletions doc/lib/kt/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -41,9 +41,11 @@ import kotlinx.coroutines.flow.collect

Moq.connect("https://relay.example.com").use { moq ->
moq.announcements("demos/").collect { announcement ->
println("got broadcast ${announcement.path()}")
// The announced path is relative to the prefix.
println("got route ${announcement.path()}")

announcement.broadcast().subscribeCatalog().updates().collect { catalog ->
val broadcast = moq.requestBroadcast("demos/" + announcement.path())
broadcast.subscribeCatalog().updates().collect { catalog ->
println("catalog: $catalog")
}
}
Expand Down
9 changes: 6 additions & 3 deletions doc/lib/kt/moq.md
Original file line number Diff line number Diff line change
Expand Up @@ -95,8 +95,11 @@ import kotlinx.coroutines.flow.collect

Moq.connect("https://relay.example.com").use { moq ->
moq.announcements("demos/").collect { announcement ->
// An announcement is a route; resolve its path into a broadcast.
val broadcast = moq.requestBroadcast("demos/" + announcement.path())

// Convenience: subscribe and grab the current catalog.
val catalog = announcement.broadcast().catalog()
val catalog = broadcast.catalog()
println("catalog: $catalog")
}
}
Expand All @@ -105,7 +108,7 @@ Moq.connect("https://relay.example.com").use { moq ->
Raw track subscribers can query the publisher's track properties and change their own delivery preferences without resubscribing:

```kotlin
val track = announcement.broadcast().subscribeTrack(
val track = broadcast.subscribeTrack(
"events",
Subscription(priority = 10u.toUByte()),
)
Expand All @@ -116,7 +119,7 @@ track.update(Subscription(priority = 20u.toUByte()))
A catalog rendition may name a *different* broadcast: `MoqVideo.broadcast` / `MoqAudio.broadcast` is a path relative to the broadcast the catalog came from, so a transcode output at `live/hd` can describe a track that actually lives in `live/source`. `decodeAudio` and `decodeVideo` follow it for you. `subscribeMedia`, `subscribeTrack`, `fetchGroup`, and `fetchMediaGroup` take a track name rather than a rendition, so resolve first:

```kotlin
val source = announcement.broadcast().resolve(rendition.broadcast)
val source = broadcast.resolve(rendition.broadcast)
val consumer = source.subscribeMedia(name, rendition.container)
```

Expand Down
5 changes: 3 additions & 2 deletions doc/lib/py/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -54,10 +54,11 @@ import moq
async def main():
async with moq.Client("https://cdn.moq.dev/anon") as client:
async for announcement in client.announced():
catalog = await announcement.broadcast.catalog()
broadcast = await client.request_broadcast(announcement.path)
catalog = await broadcast.catalog()

for name in catalog.audio:
async for frame in announcement.broadcast.subscribe_media(name):
async for frame in broadcast.subscribe_media(name):
print(f"frame: {len(frame.payload)} bytes, ts={frame.timestamp_us}")

asyncio.run(main())
Expand Down
Loading
Loading