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.

25 changes: 24 additions & 1 deletion doc/bin/cli.md
Original file line number Diff line number Diff line change
Expand Up @@ -23,7 +23,8 @@ or Docker; see [Install](/setup/install).
| `export` | `rtmp`, `srt`, `rtc` | Serve plays (`--listen`) or push to a remote (`--connect`). |
| `play` | | Decode and play in a native window with sound. |
| `transcode` | | Publish a just-in-time rendition ladder next to a broadcast. |
| `token` | | Generate, sign, and verify relay JWTs. |
| `fetch` | `<track>` | Write one group of a track to stdout. |
| `auth` | | Generate, sign, and verify relay JWTs. |
| `devices` | | List capture sources and their ids. |

## Grammar
Expand All @@ -32,6 +33,7 @@ or Docker; see [Install](/setup/install).
moq <MoQ side> import <source> [options]
moq <MoQ side> export <sink> [options]
moq <MoQ side> play [options]
moq <MoQ side> fetch <track> [options]
```

The **MoQ side** goes first and attaches the process to the network:
Expand Down Expand Up @@ -155,6 +157,27 @@ heights and bitrates must then increase strictly together. Duplicate heights or
bitrates, inverted rankings, and zero-sized or zero-bitrate rungs are rejected
before connecting.

## Fetch

```bash
moq --connect https://relay.example.com/anon --broadcast my-stream.hang fetch catalog.json | jq
moq ... fetch video/hd --group 42 --json
```

Writes one group of a track to stdout over MoQ, with the session's own auth:
the counterpart of the relay's HTTP `/fetch/<broadcast>/<track>?group=N`. Without
`--group` it reads the newest group. By default stdout carries the frame
payloads back to back, byte for byte what `curl` gets from `/fetch`. `--json`
prints one line per frame instead:
`{"group": 42, "frame": 0, "size": 1234, "payload": "<base64>"}`, with a
zero-based `frame` and padded standard base64.

`<track>` is the literal track name. `/fetch` splits its path on the last `/`,
so the two agree only for names without one. Fetch only dials `--connect`, and
refuses a listener or cluster flag. It gives up after 30 seconds, as `/fetch`
does, and exits non-zero when the broadcast or group is not found, the relay
refuses, or the deadline passes.

## Multiple stages

Separate stages with `--` to bridge several broadcasts, or both directions,
Expand Down
1 change: 0 additions & 1 deletion quest/m1/cli-inspect/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -22,4 +22,3 @@ This README owns the guide, written once both verbs land: a new

- [Caught up](/quest/m1/cli-inspect/caught-up.md) - moq-net's announce consumer yields a `Live` marker once the initial set has landed, and shell completion drops its settle timer
- [ls](/quest/m1/cli-inspect/ls.md) - `moq ls` prints the live set and exits, or follows changes, as paths or JSON lines
- [Fetch](/quest/m1/cli-inspect/fetch.md) - `moq fetch` writes one group of a track to stdout, raw or as JSON lines
31 changes: 0 additions & 31 deletions quest/m1/cli-inspect/fetch.md

This file was deleted.

3 changes: 3 additions & 0 deletions rs/moq-cli/Cargo.toml
Original file line number Diff line number Diff line change
Expand Up @@ -89,6 +89,7 @@ pulseaudio = ["moq-audio?/pulseaudio"]
anyhow = { workspace = true, features = ["backtrace"] }
axum = { workspace = true }
axum-server = { workspace = true }
base64 = { workspace = true }
bytes = { workspace = true }
hang = { workspace = true }
humantime = { workspace = true }
Expand Down Expand Up @@ -127,6 +128,8 @@ sd-notify = { workspace = true }
# the wrong catalog track apart from one reading the right one: `moq-mux`'s producer
# publishes hang and MSF from the same source, so both answer for an ordinary broadcast.
moq-msf = { path = "../moq-msf" }
# `test_relay` stands up a real relay for the `fetch` tests to read through.
moq-relay = { path = "../moq-relay", default-features = false, features = ["test-support"] }
tempfile = { workspace = true }
# `test-util` enables `tokio::time::pause` so the TS round-trip test simulates the
# exporter drain timeouts instantly instead of waiting on the wall clock.
Expand Down
72 changes: 49 additions & 23 deletions rs/moq-cli/src/args.rs
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@
//!
//! Grammar: `moq <MoQ side> <stage> [-- <stage>]...`, where a stage is
//! `<import|export> <endpoint> [endpoint opts]`, plus `moq <MoQ side> play` for
//! native playback.
//! native playback and `moq <MoQ side> fetch <track>` to read one group.
//!
//! - The MoQ side (`--connect`, the `--listen*` transport binds, `--cluster-lan`,
//! and `--cluster-connect` / `--cluster-connect-api`; all optional, at least
Expand Down Expand Up @@ -181,6 +181,12 @@ impl Invocation {
self.typed.reject(command)
}

/// Refuse every MoQ-side flag but `--connect` and `--broadcast`, on a verb that
/// only reads from a relay. Answered from the command line, like [`Self::reject`].
pub fn dial_only(&self, command: &str) -> anyhow::Result<()> {
self.typed.dial_only(command)
}

/// Split `argv` on `--` and run each chunk through a real parser.
pub fn try_parse_from<I, T>(argv: I) -> Result<Self, ParseError>
where
Expand Down Expand Up @@ -248,8 +254,8 @@ impl Invocation {
}

// Only `import` and `export` share an Origin. The rest own the process: `play`
// drives a window on the main thread, `transcode` builds its own Origin, and
// `token` / `devices` never touch the network at all.
// drives a window on the main thread, `transcode` builds its own Origin, `fetch`
// opens its own session, and `auth` / `devices` never touch the network at all.
if let Some(command) = self.stages.iter().find(|command| !command.is_stageable()) {
anyhow::bail!(
"`{}` must be the only verb; it can't share a process with another `--` stage",
Expand Down Expand Up @@ -505,6 +511,25 @@ impl MoqSide {
/// the same reason it used to be out of it -- an ambient `MOQ_HOP` no longer
/// reaches here, so a typed one can be refused like the rest.
fn reject(&self, command: &str) -> anyhow::Result<()> {
if let Some(flag) = self.given().next() {
anyhow::bail!("`{command}` runs locally and takes no MoQ side; drop {flag}");
}
Ok(())
}

/// Refuse every MoQ-side flag except the dial, on a verb that only reads from a
/// relay: a listener or cluster it would never serve is not silently ignored.
/// Private for the same reason as [`Self::reject`], and reached through
/// [`Invocation::dial_only`].
fn dial_only(&self, command: &str) -> anyhow::Result<()> {
if let Some(flag) = self.given().find(|flag| !matches!(*flag, "--connect" | "--broadcast")) {

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Reject every ignored listener option for fetch

When fetch is invoked with --connect plus an accept-only option such as --listen-tls-generate, --listen-version, --listen-preferred-v4, or a QUIC-LB setting, parsing succeeds and this check misses it because given() enumerates only listener bind fields. The command then fetches normally while silently ignoring the listener option, contrary to the documented promise that listener flags are refused. Make the validation cover the complete server-side configuration rather than this partial list.

AGENTS.md reference: AGENTS.md:L17-L17

Useful? React with 👍 / 👎.

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Declining in this PR: given() is the shared MoQ-side flag list that reject (auth/completion/devices) also leans on, so the accept-only options it misses are a pre-existing gap for every verb, not something fetch introduced. Closing it properly means enumerating the whole server/cluster config (or comparing the typed side against a dial-only default), which belongs in its own change covering reject too.

(written by Claude Opus 5.5)

anyhow::bail!("`{command}` only dials a relay with --connect; drop {flag}");
}
Ok(())
}

/// The MoQ-side flags this side was given.
fn given(&self) -> impl Iterator<Item = &'static str> {
#[cfg(feature = "cluster-lan")]
let cluster_secret = self.cluster.lan.secret.is_some();
#[cfg(not(feature = "cluster-lan"))]
Expand All @@ -516,7 +541,7 @@ impl MoqSide {

// A legacy `--client-connect` must be rejected here too; the fold has already
// landed it in `url`.
let ignored = [
let flags = [
("--connect", self.client.url.is_some()),
("--listen", self.server.bind.is_some()),
("--listen-tcp-bind", self.server.tcp.bind.is_some()),
Expand All @@ -535,26 +560,24 @@ impl MoqSide {
("--broadcast", self.broadcast.is_some()),
("--hop", self.hop.is_some()),
];
let ignored = ignored.into_iter().find(|(_, given)| *given).map(|(flag, _)| flag);
#[cfg(unix)]
let ignored = ignored
.or_else(|| self.server.unix.bind.is_some().then_some("--listen-unix-bind"))
.or_else(|| {
let allow = &self.server.unix.allow;
[
("--listen-unix-allow-uid", !allow.uid.is_empty()),
("--listen-unix-allow-gid", !allow.gid.is_empty()),
("--listen-unix-allow-pid", !allow.pid.is_empty()),
]
.into_iter()
.find_map(|(flag, given)| given.then_some(flag))
});

if let Some(flag) = ignored {
anyhow::bail!("`{command}` runs locally and takes no MoQ side; drop {flag}");
}

Ok(())
let unix = {
let allow = &self.server.unix.allow;
[
("--listen-unix-bind", self.server.unix.bind.is_some()),
("--listen-unix-allow-uid", !allow.uid.is_empty()),
("--listen-unix-allow-gid", !allow.gid.is_empty()),
("--listen-unix-allow-pid", !allow.pid.is_empty()),
]
};
#[cfg(not(unix))]
let unix = [];

flags
.into_iter()
.chain(unix)
.filter(|(_, given)| *given)
.map(|(flag, _)| flag)
}
}

Expand All @@ -572,6 +595,8 @@ pub enum Command {
/// The released spelling of [`Self::Export`].
#[usage(hide = true)]
Subscribe(Export),
/// Write one group of a track to stdout.
Fetch(crate::fetch::Args),
/// Play a broadcast in a native window and speaker.
#[cfg(feature = "play")]
Play(crate::play::Args),
Expand Down Expand Up @@ -629,6 +654,7 @@ impl Command {
match self {
Self::Import(_) | Self::Publish(_) => "import",
Self::Export(_) | Self::Subscribe(_) => "export",
Self::Fetch(_) => "fetch",
#[cfg(feature = "play")]
Self::Play(_) => "play",
#[cfg(feature = "transcode")]
Expand Down
Loading
Loading