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
1 change: 1 addition & 0 deletions Cargo.lock

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

7 changes: 1 addition & 6 deletions doc/bin/relay/config.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@ description: TOML reference for moq-relay
`moq-relay relay.toml`. Every key is also a CLI flag and environment variable
that joins the section and key: `listen.tls.cert` is `--listen-tls-cert` /
`MOQ_LISTEN_TLS_CERT`. The exceptions: `listen.bind` is spelled `--listen` /
`MOQ_LISTEN`, and `listen.extensions` and `connect.extensions` are TOML only.
`MOQ_LISTEN`.
Precedence is CLI, then env, then file, then defaults.
`moq-relay --help` lists every flag.

Expand Down Expand Up @@ -45,10 +45,6 @@ bind = "127.0.0.1:4444"
[listen.unix] # Plaintext qmux over a Unix socket, gated by peer credentials.
bind = "/run/moq/internal.sock"
allow.uid = [1001]

[listen.extensions] # moq-transport SETUP extensions to offer, each on by default.
# The relay always offers ietf, for moq-lite-07 relay links.
solicit = false # Decline MoQ Solicit, so peers may announce unasked.
```

`timeout` bounds the whole handshake, transport through MoQ SETUP and auth
Expand Down Expand Up @@ -305,7 +301,6 @@ tls.cert = "relay.pem" # Present a client certificate (mTLS to pee
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.solicit = false # Decline MoQ Solicit on outbound moq-transport sessions, as in [listen.extensions].
```

A draining upstream may name a replacement URI. `same-host` follows it only
Expand Down
9 changes: 5 additions & 4 deletions doc/concept/standard.md
Original file line number Diff line number Diff line change
Expand Up @@ -55,8 +55,7 @@ ignores unknown parameters: [cluster](/draft/moq-cluster) routing hop lists,
[hidden](/draft/moq-hidden) to keep `.`-named namespaces out of discovery, and
[active-count](/draft/moq-active-count) to count the `NAMESPACE` messages
before a `SUBSCRIBE_NAMESPACE` is synced.
Both libraries offer solicit unless a side's `extensions` setting declines it,
which connects it as a peer that does not speak that extension. The pooled JavaScript `Connection` has no such setting yet.
Both libraries always offer solicit.
moq-transport carries no [publisher instance](/concept/moq-lite#publisher-instances),
so the receiving session mints one per announcement.

Expand All @@ -71,8 +70,10 @@ does and a browser session does not yet.
[ietf](/draft/moq-ietf) goes the other way: it extends moq-lite-07 to carry this
object state between relays. moq-lite-07 is still a work in progress
(`moq-lite-07-wip`), negotiated only when both sides enable it, so a peer that
does not offer it does not carry this state. Only Rust offers the extension, when
`extensions.ietf` is set, and `moq-relay` always does on moq-lite-07.
does not offer it does not carry this state. Only `moq-relay` offers the extension,
always, on moq-lite-07. It costs a moq-lite track nothing: only a track a moq-transport
publisher made carries the state, so the groups of any other cross the hop byte for
byte as they would without the extension.
[moq-e2ee](/draft/moq-e2ee), published and experimental, is not a transport extension. It encrypts
application payloads, so relays still forward named tracks they cannot read.
See [Encryption](/concept/hang#encryption).
Expand Down
61 changes: 12 additions & 49 deletions drafts/draft-lcurley-moq-ietf.md
Original file line number Diff line number Diff line change
Expand Up @@ -26,6 +26,7 @@ informative:

This document defines an extension for moq-lite {{moql}} that carries the object state of MoQ Transport {{moqt}} across a moq-lite session between two relays.
A track a MoQ Transport publisher sends through relay A, then over moq-lite to relay B, reaches a MoQ Transport subscriber of relay B as it would through one relay: with its Object IDs, gaps, properties, and END_OF_GROUP status.
A datagram track keeps only what moq-lite carries.

--- note_Note_to_Readers

Expand All @@ -37,7 +38,7 @@ Submit an [issue](https://github.com/moq-dev/moq/issues) or [PR](https://github.
# Conventions and Definitions
{::boilerplate bcp14-tagged}

A **relayed** group or datagram arrived from a MoQ Transport publisher, so it has object state that moq-lite cannot express.
A **relayed** group arrived from a MoQ Transport publisher, so it has object state that moq-lite cannot express.
A **plain** one has none: its Object IDs are its frame indices, it has no properties, and its group ends where its last frame does.
A track's **Version** is the {{moqt}} version its original publisher spoke, which serialized every property it carries, or none for a track published over moq-lite ([Track Stream](#track)).

Expand All @@ -62,14 +63,15 @@ An endpoint offers the extension with the following Setup Parameter ({{moql}} SE

The value MUST be empty; a receiver MUST close the session with a PROTOCOL_VIOLATION otherwise.
The extension is negotiated only when both endpoints offer it, and only on moq-lite-07 and later.
An endpoint MUST NOT send any field this document defines unless the extension is negotiated, and MUST NOT parse a Group Stream, FETCH response, Track Stream, or datagram from the peer until it has the peer's SETUP and so knows whether it was.
An endpoint MAY drop a datagram that arrives before then.
A Group Stream, FETCH response, or datagram is read with the Version of its track, which the Track Stream carries before any subscription or fetch opens.
An endpoint MUST NOT send any field this document defines unless the extension is negotiated, and MUST NOT parse a Group Stream, FETCH response, or Track Stream from the peer until it has the peer's SETUP and so knows whether it was.
A Group Stream or FETCH response is read with the Version of its track, which the Track Stream carries before any subscription or fetch opens.


# Group Streams {#group}
When the extension is negotiated, a Group Stream carries a Group State after the GROUP message, and an Object Record before each FRAME.
A FETCH response carries the same, with the Group State first.
When the extension is negotiated, a Group Stream of a track with a Version carries a Group State after the GROUP message, and an Object Record before each FRAME.
A FETCH response for such a track carries the same, with the Group State first.
A Group Stream or FETCH response of a track without a Version is exactly as {{moql}} defines it, so the extension costs a track published over moq-lite nothing.
Datagrams are unchanged too: a datagram track ({{moql}}) has no Track Stream and so no Version.
Comment thread
coderabbitai[bot] marked this conversation as resolved.
Resolved

~~~
Group Stream {
Expand All @@ -93,7 +95,6 @@ A bit field describing the group's relay state, or 0 for a plain group:
- `0x8` **END_OF_GROUP**: The stream's end ends the group, as a {{moqt}} subgroup that contains the end of its group.

A receiver MUST reset the stream with a PROTOCOL_VIOLATION on any other bit, a bit without RELAYED, or a record with Properties when EXTENSIONS is clear.
A track without a Version has no {{moqt}} state, so a receiver MUST reset the stream with a PROTOCOL_VIOLATION on any Group State but 0 for one.
A publisher MUST clear FIRST_OBJECT when the stream starts after the first frame it holds, and END_OF_GROUP when the stream may stop before the end of the group, such as at a subscription's end frame.
A stream that stops at an end frame carries no END_OF_GROUP record, even when that frame is the group's last.

Expand Down Expand Up @@ -134,11 +135,10 @@ A relay forwards the block to a peer of that encoding unchanged, so the block ne
Every property of the object, serialized as the track's Version serializes an object's properties, in ascending ID order.
Immutable Properties (0x0b) are in the same encoding, as the publisher sent them.
It MUST NOT be empty or longer than 65,536 bytes.
A track without a Version carries no properties: a Property Block on one is malformed.
On a timed track an object with a FRAME, or a datagram without a Status, MUST NOT carry one longer than 65,526 bytes, leaving room for the largest Timestamp a relay restates ([Timestamps](#timestamps)): a one-byte key and a value of up to nine bytes.
On a timed track an object with a FRAME MUST NOT carry one longer than 65,526 bytes, leaving room for the largest Timestamp a relay restates ([Timestamps](#timestamps)): a one-byte key and a value of up to nine bytes.
A relay MUST refuse a {{moqt}} object whose properties, less its mutable Timestamp, exceed that, so every object it forwards fits.
A receiver MUST treat a block the track's Version would refuse as malformed, as it MUST a block on an object that Version could not send with properties.
Only draft 14 lets a status object carry them, so a block on the END_OF_GROUP record needs a Version of draft 14, and a datagram with a block MUST have fields an OBJECT_DATAGRAM Type of its Version carries ([Datagrams](#datagrams)).
Only draft 14 lets a status object carry them, so a block on the END_OF_GROUP record needs a Version of draft 14.
The Version also gives each property its meaning: drafts 18 and 19 serialize a block alike, but only drafts 19 and later assign property 0x06 to SUBGROUP_DELIVERY_TIMEOUT, so a relay knows not to forward a 0x06 to a draft that would read it differently.
Other properties are opaque to this extension.

Expand All @@ -148,13 +148,13 @@ A nonzero Version identifies timestamps from MoQ Transport, which may be arrival
The receiver MUST NOT apply moq-lite's group-start rewind check to such a track; a Version of zero retains that check.
Without this extension, or in a listing ({{track}}), the receiver may check them like native moq-lite timestamps and refuse a Group that rewinds.

On a timed track, the FRAME's Timestamp, or the datagram's for a datagram, is the object's time, and nothing else carries it.
On a timed track, the FRAME's Timestamp is the object's time, and nothing else carries it.
The Property Block MUST NOT contain a mutable Timestamp (0x10) there; a receiver MUST treat one as malformed.
A relay forwarding the object to {{moqt}} restates the time as the mutable Timestamp, unless a Timestamp inside the Immutable Properties already says it.
A sealed Timestamp is in the track's Timescale ({{moql}} TRACK_INFO), and a relay MUST NOT forward one to a peer of other units, which would change its meaning.

On an untimed track there is no FRAME Timestamp, so a mutable Timestamp stays in the Property Block as an opaque property.
Likewise, an object without a FRAME, such as the END_OF_GROUP record or a datagram with a non-zero Status, has no time of its own beside the block, so its mutable Timestamp stays there on any track.
Likewise, the END_OF_GROUP record has no FRAME and so no time of its own beside the block, so its mutable Timestamp stays there on any track.


# Track Stream {#track}
Expand Down Expand Up @@ -203,43 +203,6 @@ A TRACKS_ADD ({{moql}} Tracks Stream) embeds TRACK_INFO without TRACK_PROPERTIES
Lacking the Version, a TRACKS_ADD cannot mark a {{moqt}} track's timestamps as unchecked ({{timestamps}}).


# Datagrams {#datagrams}
When the extension is negotiated, a DATAGRAM carries a Datagram State after its Group Sequence.

~~~
DATAGRAM Body {
Subscribe ID (i)
Group Sequence (i)
Datagram State (i)
[Object ID (i)]
[Publisher Priority (8)]
[Status (i)]
[Properties Length (i), Properties (..)]
[Timestamp (i)]
[Inflated Size (i)]
Payload (b)
}
~~~

**Datagram State**:
A bit field, or 0 for a plain datagram, which has none of the optional fields before the Timestamp:

- `0x1` **RELAYED**: The datagram is relayed, so its Properties follow. Every other bit requires it.
- `0x2` **OBJECT_ID**: The Object ID follows.
- `0x4` **PRIORITY**: The {{moqt}} Publisher Priority follows.
- `0x8` **END_OF_GROUP**: The object ends its group.
- `0x10` **STATUS**: The {{moqt}} Object Status follows.

A receiver MUST drop a datagram with any other bit, a bit without RELAYED, or any bit on a track without a Version.

A datagram with a Status MUST have an empty Payload, as {{moqt}} sends no payload beside one; a Normal (0) Status is an empty object.
It has no Inflated Size ({{moql}} DATAGRAM), even on a compressed track, as there is no payload to inflate.
A non-zero Status carries no object: it has no Timestamp, even on a timed track.
A receiver MUST drop a datagram whose Status no {{moqt}} draft defines: only 0 (Normal), 1 (DOES_NOT_EXIST, drafts 14 and 15), 3 (END_OF_GROUP), and 4 (END_OF_TRACK) are relayed.
It MUST also drop one its track's Version could not send: whose fields no OBJECT_DATAGRAM Type of that Version carries, such as STATUS with END_OF_GROUP, or whose Status it does not define.
From draft 17 on a non-zero Status carries no properties, and only drafts 14 and 15 define DOES_NOT_EXIST.


# Security Considerations
A peer sets how much state a receiver holds for each object, up to a 65,536-byte Property Block.
A receiver SHOULD hold the block as received, not decoded, and charge it to the group's cache budget like a payload.
Expand Down
11 changes: 0 additions & 11 deletions js/net/src/connection/accept.ts
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,6 @@ import type { Consumer as OriginConsumer, Producer as OriginProducer } from "../
import { Stream } from "../stream.ts";
import { untilAborted } from "../util/abort.ts";
import { after } from "../util/timer.ts";
import * as Extensions from "./extensions.ts";
import { DISCOVERY_REMOVED, forwardAnnounced } from "./forward.ts";
import { DEFAULT_TIMEOUT, exchangeSetup, handsOff } from "./handshake.ts";
import type { Session } from "./session.ts";
Expand Down Expand Up @@ -40,13 +39,6 @@ export interface AcceptProps {
*/
consume?: OriginProducer;

/**
* The moq-transport extensions to offer, each on unless set to `false`.
*
* @internal Tests only; nothing outside the package consumes it.
*/
extensions?: Extensions.Extensions;

/** The implementation this side advertises in SETUP; see the `implementation` connect option. */
implementation?: string;
}
Expand All @@ -56,8 +48,6 @@ type SessionProps = {
publish?: OriginConsumer;
/** Whether this side dialed; only the dialing side aborts on a publication its grant does not cover. */
client: boolean;
/** The moq-transport extensions this side offers. */
extensions: Extensions.Offered;
/** The implementation this side advertises in SETUP; empty sends nothing. */
implementation: string;
};
Expand Down Expand Up @@ -115,7 +105,6 @@ async function acceptInner(
const wiring: SessionProps = {
publish: props.publish,
client: false,
extensions: Extensions.offered(props.extensions),
implementation: props.implementation ?? IMPLEMENTATION,
};

Expand Down
11 changes: 0 additions & 11 deletions js/net/src/connection/connect.ts
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,6 @@ import * as Hex from "../util/hex.ts";
import { after } from "../util/timer.ts";
import { isWebTransportSupported } from "./browser.ts";
import { parse, show } from "./endpoint.ts";
import * as Extensions from "./extensions.ts";
import { DISCOVERY_REMOVED, forwardAnnounced } from "./forward.ts";
import { DEFAULT_TIMEOUT, exchangeSetup, handsOff } from "./handshake.ts";
import type { Session } from "./session.ts";
Expand Down Expand Up @@ -251,13 +250,6 @@ export interface ConnectProps {
*/
consume?: OriginProducer;

/**
* The moq-transport extensions to offer, each on unless set to `false`.
*
* @internal Tests only; nothing outside the package consumes it.
*/
extensions?: Extensions.Extensions;

/**
* Credentials to present, kept apart from the URL.
*
Expand Down Expand Up @@ -313,8 +305,6 @@ type SessionProps = {
handle?: Auth.Handle;
/** Whether this side dialed; only the dialing side aborts on a publication its grant does not cover. */
client: boolean;
/** The moq-transport extensions this side offers. */
extensions: Extensions.Offered;
/** The connection credential SETUP presents, on versions that carry one. */
token?: Uint8Array;
/** The implementation this side advertises in SETUP; empty sends nothing. */
Expand Down Expand Up @@ -475,7 +465,6 @@ async function connectInner(
publish: props.publish,
handle: props.auth,
client: true,
extensions: Extensions.offered(props.extensions),
token: presented.setup === undefined ? undefined : new TextEncoder().encode(presented.setup),
implementation: props.implementation ?? IMPLEMENTATION,
probeTarget: props.viewers?.target,
Expand Down
72 changes: 0 additions & 72 deletions js/net/src/connection/extensions.test.ts

This file was deleted.

26 changes: 0 additions & 26 deletions js/net/src/connection/extensions.ts

This file was deleted.

Loading