Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
31 commits
Select commit Hold shift + click to select a range
ed24869
chore(quest): claim quest/m1/socket/rust.md
kixelated Nov 3, 2026
f1f1525
feat(net): dial and accept sockets over an origin
kixelated Nov 3, 2026
26db1ce
doc: specify sockets on a concept page and finish the Rust quest
kixelated Nov 3, 2026
90147b4
test(net): let socket discovery follow its own watches
kixelated Nov 3, 2026
9b72bb3
fix(net): bound socket stream queues, register bi opens first, close …
kixelated Nov 3, 2026
f57d270
fix(net): hand out only the socket streams the peer still lists
kixelated Nov 3, 2026
dec0c23
fix(net): end socket opens on local close, guard bi reopens
kixelated Nov 3, 2026
775653c
fix(net): number socket streams so a track carries one stream
kixelated Nov 3, 2026
0e0e62f
feat(net)!: unnamed socket streams, with a token-auth example and rel…
kixelated Nov 3, 2026
d6bd0f2
Merge remote-tracking branch 'origin/main' into t3/6b95c913
kixelated Nov 3, 2026
2fd0dc2
fix(net): a bi open resolves on the peer's subscription too
kixelated Nov 3, 2026
1378093
fix(net): an accepted bi stream reads the opener's half as its answer
kixelated Nov 4, 2026
c78dd6f
Merge remote-tracking branch 'origin/main' into t3/5e39b12c
kixelated Nov 4, 2026
c5e1854
fix(net): release a socket's accept reads on close, ordered against r…
kixelated Nov 4, 2026
2cc7b30
Merge branch 'main' into quest/m1/socket/rust
kixelated Nov 4, 2026
0ec5fd9
feat(net)!: replace socket listeners with .tcp endpoints, one pipe pe…
kixelated Nov 4, 2026
58fc5be
fix(net): reset and accept socket requests outside the endpoint lock
kixelated Nov 4, 2026
2cc97ed
fix(net): read socket messages in sequence, reset handshakes explicitly
kixelated Nov 4, 2026
5c76a1b
docs(net): say who ends each half of a socket session
kixelated Nov 4, 2026
a48eea0
Merge branch 'main' into quest/m1/socket/rust
kixelated Nov 4, 2026
274d411
feat(net)!: socket endpoints at .socket/<id> with tcp and track proto…
kixelated Nov 4, 2026
90262b5
fix(net): pace tcp sessions without stalling, and fix the socket tests
kixelated Nov 4, 2026
af5e40a
Merge remote-tracking branch 'origin/main' into socket-single-group
kixelated Nov 4, 2026
28e52a0
test(relay): run the socket auth test on tokio after the simulator move
kixelated Nov 4, 2026
d5e854b
fix(net): refuse a second tcp group after the first finished
kixelated Nov 4, 2026
3fd88d8
fix(net): wake socket dials outside every lock, and pass on a peer re…
kixelated Nov 4, 2026
3983339
fix(net): poll a socket endpoint's handler with no lock held
kixelated Nov 4, 2026
6a0e513
Merge remote-tracking branch 'origin/main' into socket-bind-acceptor
kixelated Nov 4, 2026
babc0aa
feat(net): bind socket sessions to both ends, and wait on the dialer'…
kixelated Nov 4, 2026
f861bf8
style: cargo fmt
kixelated Nov 4, 2026
0161d5b
fix(net): drop queued socket dials whose dialer gave up
kixelated Nov 4, 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
1 change: 1 addition & 0 deletions doc/.vitepress/config.ts
Original file line number Diff line number Diff line change
Expand Up @@ -118,6 +118,7 @@ export default defineConfig({
{ text: "Transport", link: "/concept/transport" },
{ text: "moq-lite", link: "/concept/moq-lite" },
{ text: "Identity and recovery", link: "/concept/identity" },
{ text: "Sockets", link: "/concept/socket" },
{ text: "hang", link: "/concept/hang" },
{ text: "Archives", link: "/concept/archives" },
{ text: "Audio jitter", link: "/concept/audio-jitter" },
Expand Down
1 change: 1 addition & 0 deletions doc/concept/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -38,6 +38,7 @@ watched at 100 ms by one viewer and 10 s by another.
- [Transport](/concept/transport): why QUIC, and the WebTransport, WebSocket, and raw QUIC paths onto it.
- [moq-lite](/concept/moq-lite): the pub/sub protocol, discovery, path patterns, subscriptions, and congestion behavior.
- [Identity and recovery](/concept/identity): choosing stream instances, following restarts, and answering work on demand without mixing streams.
- [Sockets](/concept/socket): dial and accept point-to-point sessions through relays, as reliable byte pipes or as tracks of messages.
- [hang](/concept/hang): the media catalog, containers, encryption, and how to extend both.
- [Archives](/concept/archives): record listed tracks into object storage and serve them back from a host.
- [Audio jitter](/concept/audio-jitter): how a receiver sizes its audio playout target from arrival timing.
Expand Down
223 changes: 223 additions & 0 deletions doc/concept/socket.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,223 @@
---
title: Sockets
description: Dial and accept point-to-point sessions over MoQ, as reliable byte pipes or as tracks of messages
---

# Sockets

A socket connects two endpoints through relays, the way a TCP connection
connects two hosts. Each endpoint announces one hidden broadcast, dials other
endpoints, and accepts their dials. Each connection is a session that only the
two ends can read while its id stays secret (see [Hidden names](#hidden-names)),
in one of two protocols: `tcp`, a reliable, ordered byte
pipe each way, or `track`, a track each way whose groups are messages. Use a
socket for per-client state that only the two ends need, such as a viewer's
commands and the replies to them, while whatever every client needs stays in an
ordinary broadcast.

A socket is a convention over announcements, broadcasts, and track
subscriptions, not a wire extension. It uses no instances and no track
listings, and relays carry it unchanged. It needs moq-lite-07 or
moq-transport on every hop: an endpoint's broadcast is
[hidden](/concept/moq-lite#hidden-broadcasts), and an older moq-lite hop
never carries hidden broadcasts, so a dial across one never finds its peer. This page is the convention, enough to implement it in any
language.
[`moq_net::socket`](https://docs.rs/moq-net/latest/moq_net/socket/) implements
it in Rust.

## Endpoints

An endpoint with id `<id>` announces one broadcast, once:

```text
<prefix>/.socket/<id>
```

The id is one path segment: a well-known name for a server, such as a game, or
a random id for a client. The prefix is shared by every endpoint that talks to
each other. The `.socket` segment starts with `.`, so endpoints are
[hidden](/concept/moq-lite#hidden-broadcasts) from anyone listing the prefix.

The announcement is used only for routing: it is how a relay finds an
endpoint. Connections are never announced. An endpoint's broadcast holds only
session tracks, served on request, whatever their protocol.

## Sessions

A session between a dialer `A` and an acceptor `B` is named by its protocol `P`,
both ends, and a session id `S` that `A` picks: random and unguessable, at
least 128 bits, such as 32 hex digits. Both halves of the session are tracks
with the same name, `<protocol>/<dialer>/<acceptor>/<session>`, one in each
endpoint's broadcast:

| Track | In broadcast | Written by | Read by |
| --- | --- | --- | --- |
| `P/A/B/S` | `<prefix>/.socket/A` | `A` | `B` |
| `P/A/B/S` | `<prefix>/.socket/B` | `B` | `A` |

The protocol is `tcp` or `track`; see [Protocols](#protocols). An endpoint
resets a request whose protocol it doesn't speak, or isn't accepting, as
unsupported.

The dialer's id follows the protocol in both broadcasts, so an endpoint tells a
dial from an answer by the name alone: a request with another endpoint as the
dialer and itself as the acceptor is that endpoint dialing, and a request with
itself as the dialer answers one of its own dials. An endpoint resets any other
request, such as one naming another acceptor, as not found. Since `S` is random
per dial, every session is distinct, and one endpoint can dial and accept any
number of sessions at once, with the same peer or others.

### Dial

1. `A` picks `S` and holds its own half, `P/A/B/S` in its broadcast,
unanswered.
2. `A` subscribes to `<prefix>/.socket/B` for the track `P/A/B/S`, waiting for
`B`'s endpoint to be announced if it is not yet.
3. `B` receives that subscription as a request for a track it does not have:
an incoming dial in protocol `P`, claiming to be from `A`, with session `S`.

### Accept

1. `B` subscribes to `<prefix>/.socket/A` for the track `P/A/B/S`, and holds
`A`'s subscription unanswered. A relay can deliver the dial before `A`'s
announcement, so `B` waits for `A`'s endpoint to be announced for as long as
`A`'s subscription stays open, and gives up once it closes.
2. `A` answers that subscription only if it dialed `S` to `B` and is still
waiting, and resets any other. That makes the exchange a return-routability
check: a dial forged in `A`'s name, by anyone who can subscribe to `B`,
reaches an `A` that never dialed it, so `A` resets `B`'s subscription and `B`
resets the forger's.
3. Once `A` answers, `B` answers `A`'s subscription, and the session is open
for both. `B` writes nothing before `A` answers.

### Reject

`B` resets `A`'s subscription, with not found, as for a session that does not
exist. An endpoint resets a dial in a protocol it is not accepting as
unsupported, and one that accepts nothing at all answers not found, as for any
track nobody serves. A dial that gives up resets `B`'s subscription in turn.

## Protocols

Each side writes its own half and reads the peer's. A reader subscribes
reliably and in order: oldest group first, with no delay budget, so it waits
for a late group rather than skipping it. The protocol decides what a half
holds.

### `tcp`

Each half is exactly one group, sequence 0. In MoQ a group travels as one QUIC
stream on every hop, so it is reliable, strictly ordered, and flow controlled,
exactly like one direction of a TCP connection:

- A frame is a write. The reader reads the frames in the order they were
written, with nothing skipped.
- Finishing the group is FIN: the reader reads to the end, then sees the end.
- Resetting the group, or its track, is RST: the reader fails with the error.
- A second group on a session track is a protocol error: the reader resets the
session, both halves.

There are no track-level settings: no priority between messages, no delay
budget, no order, since the newest group is never stale.

A session can last indefinitely: a group has no size cap, and each copy keeps
only a bounded tail of it. A writer that waits for room before each write (in
Rust, `group::Producer::ready`) runs at most a window ahead of the reader on
every hop, so a slow reader slows the writer, as TCP backpressure does, and
nothing is lost. A writer that doesn't wait sheds the front of its half, and a
reader that falls behind it fails with an eviction error instead of skipping
data. Pacing reaches across native QUIC and qmux hops; see
[unbounded groups](https://github.com/moq-dev/moq/tree/main/quest/m1/unbounded-groups)
for what remains, such as browsers, which read without pacing.

Use `tcp` for a byte stream or a log of records that must all arrive in order,
such as a proxied TCP connection, a file transfer, or a request and its reply.

### `track`

Each half is a whole track, and a message is one group. A slow message never
holds up the next, and each group can carry its own priority. Messages are
ordered by group sequence. A half has no max age unless its writer sets one, so
a newer message never makes an older one stale. A reader that keeps up gets
every message, but each
hop's cache reclaims a message nobody read within its idle window (30 s by
default), or under memory pressure, except the newest, so a reader that stalls
longer can miss messages.

The reader's subscription starts reliable and in order, like `tcp`. An
application may make it lossy for messages that go stale, such as positions or
controls, by updating the subscription with a finite delay budget: a message
that is late past the budget is skipped rather than holding up later ones. It
may also read newest first.

Finishing a half closes the session that way. Resetting it is an error.

Use `track` for independent messages, where a late one should not block the
next: commands, controls, acknowledgements, or telemetry.

## Closing

An endpoint closing, or its broadcast ending, resets every session it holds,
and stops reading them. A side that sees the peer's half reset treats the
session as closed and resets its own half, so both halves end.

There is no multiplexing within a session: another channel is another session.
Several sessions between the same two endpoints are independent, and a
restarted endpoint starts new sessions. A channel that every client reads, such
as a game's status, stays an ordinary broadcast.

## Hidden names

The session id is the secret that keeps a session to its two ends: the token
grants below let any endpoint subscribe to any other, so whoever learns a
session's track name can read it, or answer it before its peer.

The acceptor learns the name too, but cannot replay it to a third endpoint
`C`: the name binds both ends. `C` resets `P/A/B/S` as a session for another
acceptor, and `A` never dialed `P/A/C/S`, so it resets `C`'s accept of that.
The peer id of an accepted session is the endpoint that dialed it to this one.

A session track therefore never appears where a third party can read it:

- It is never announced.
- It is never listed: an endpoint serves its session tracks only on request,
so a moq-lite 07 track listing (`TRACKS`) of an endpoint's broadcast names
none of them, even to a reader allowed everything.
- Logs and metrics that a third party can read must not carry it.

## Authorization

Sockets need nothing beyond ordinary
[token grants](/bin/relay/auth#path-matching). With the token's root at the
socket prefix, each grant is a prefix:

```jsonc
// The endpoint <id>: publishes its own endpoint, reads every endpoint.
{ "root": "<prefix>", "publish": [".socket/<id>"], "subscribe": [".socket/**"] }
```

The publish grant pins the id, so no endpoint can announce as another. The
subscribe grant lets it reach any endpoint, which is what dialing and accepting
need; the session id keeps it out of other endpoints' sessions. A narrower
subscribe grant, such as a client allowed only `.socket/<server>`, also works:
it can then dial only that server and accept only its dials.

`moq auth sign` writes this as, for example:

```bash
moq auth sign --key key.jwk --root "$PREFIX" --publish ".socket/$ID" --subscribe '.socket/**' > endpoint.jwt
```

Each client then connects to the relay at the prefix with its token, and its
endpoint's prefix is the session root.

Signing and encryption are not part of the convention: an endpoint id is a
name the token pins, not a key, and relays are trusted with session names. A
planned mesh layer makes ids public keys.

## Later

Later protocols are other prefixes on the same endpoint, with no new
announcement. A multiplexed `quic` mode, with many streams per session like
QUIC, would name its sessions `quic/<dialer>/<acceptor>/<session>` and bring back several
groups or streams per session.
1 change: 1 addition & 0 deletions doc/lib/rs/moq-net.md
Original file line number Diff line number Diff line change
Expand Up @@ -20,6 +20,7 @@ What you use it for, beyond what the concept page already describes:
- **Rank several CDNs.** Dial each with its own subscribe handle, `origin.clone().with_preference(origin::Preference::new(rank))` (higher wins; 0 is neutral and a negative rank demotes), all on one origin. Requests use the preferred link that has a route and fail over to the next; see [multiple CDNs](/concept/moq-lite#multiple-cdns).
- **Request one instance, or follow them all.** `consumer.request(path, None)` resolves the instance serving a path now, and fails `Unroutable` only once discovery has synced with no route for it. `consumer.follow(path, None)` hands out each publisher instance serving a path from `available()`: the first once announced, then each one that takes over or returns after an end, like JS `follow(path)`. A broadcast already resolved stays on the old instance until dropped or its route goes. See [identity and recovery](/concept/identity) to choose between following and holding one instance.
- **Discovery follows what you watch.** A client session asks the relay for announcements only under the prefixes its subscribe origin's readers watch, with `announced()`, `request`, or `follow`, stops asking about a prefix 2s after nothing at or beneath it is watched, and asks again on reconnect. A broadcast resolved through a discovered route keeps its path watched until dropped. `request` owns discovery of its path, so no separate watch is needed. A server session, or a client fed into an origin handle marked `with_link(origin::Link::Peer)` or `Link::Upstream`, asks for everything it may, so a relay discovers everything. An HTTP gateway (the moq-hls `Server`, the moq-rtc WHEP router) watches its whole scope while it lives, so the paths its callers name never open a request each. moq-lite-03/04 sessions, whose announcements mark no initial set, still ask for everything.
- **Dial and accept sockets.** `socket::Endpoint::new(&origin, prefix, id)` announces a hidden endpoint at `<prefix>/.socket/<id>`, used only to route dials. A session speaks one of two protocols, each with its own dial and accept. `accept_tcp()` and `accept_track()` yield an `Incoming` dial to `accept` or `reject` (dropping it rejects). `dial_tcp(peer)` and an accepted `tcp` dial yield a `socket::TcpStream`, a `group::Producer` and `group::Consumer` pair carrying one reliable, ordered byte pipe each way (finish is FIN, abort is RST, and `ready` paces the writer to the reader); `dial_track(peer, info)` and an accepted `track` dial yield a `socket::TrackStream`, this side's `track::Producer` and a `track::Subscriber` of the peer's half, subscribed reliably and in order until the application updates it, one message per group. A dial resolves once the peer accepts, and an accept checks that the claimed dialer really dialed this endpoint, waiting for its endpoint while the dial stays open. Session tracks are never announced or listed. See [Sockets](/concept/socket).
- **One track per name.** Concurrent subscriptions share one request and producer. The application owns sequence numbers: the broadcast keeps nothing of an ended track, so a producer that replaces it starts at 0. A name always means the same content, so the replacement continues past its predecessor's groups with `create_group` at an explicit sequence. Readers of an aborted track resume onto the replacement when they read through an origin request, whose route always names an instance; otherwise their subscription ends with the error.
- **Authored tracks default to a zero `max_age`.** `track::Info::default()` sets `max_age` to `Some(Duration::ZERO)`, the live edge only; a publisher that wants readers to reach history sets a longer bound, or `with_max_age(None)` for no publisher limit. Media tracks from `hang::container::track_info` declare `hang::container::MAX_AGE` (30 seconds). `max_age` is how long a superseded group stays fresh, never the newest group; it frees no bytes, which the cache pool's expiry reclaims. Received metadata keeps absence as no limit, and an origin's `cache_duration` can only cap it lower.
- **End content by finishing tracks.** A broadcast has no finished state. When the input ends, finish each track; the broadcast stays announced and keeps serving them until you close it or drop its last producer. How long to keep it up for late readers is yours to decide: `moq_mux::Linger` holds a hang broadcast for a fixed window.
Expand Down
Loading
Loading