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
4 changes: 2 additions & 2 deletions demo/web/src/stats.html
Original file line number Diff line number Diff line change
Expand Up @@ -116,8 +116,8 @@ <h3 class="text-xs font-semibold text-emerald-300 mb-1">Viewers <span class="tex
<div id="node-subscribers" class="overflow-x-auto text-neutral-500 text-sm">no viewers</div>
</div>
<div>
<h3 class="text-xs font-semibold text-neutral-300 mb-1">Sessions <span class="text-neutral-500 font-normal">· by auth root</span></h3>
<div id="node-session-roots" class="overflow-x-auto text-neutral-500 text-sm">no sessions</div>
<h3 class="text-xs font-semibold text-neutral-300 mb-1">Sessions <span class="text-neutral-500 font-normal">· by stats label</span></h3>
<div id="node-session-labels" class="overflow-x-auto text-neutral-500 text-sm">no sessions</div>
</div>
</div>
</section>
Expand Down
14 changes: 7 additions & 7 deletions demo/web/src/stats.ts
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,7 @@
* Per-node tracks we read:
* publisher.json egress (relay -> downstream viewers)
* subscriber.json ingress (upstream publishers -> relay)
* sessions.json sessions by auth root
* sessions.json sessions by stats label
*
* Each frame is `{ "<broadcast path>": Snapshot }`. Counters are cumulative;
* "active" = started - ended. The relay includes every entry it still holds
Expand Down Expand Up @@ -525,15 +525,15 @@ ui.run((effect) => {
};
});

// Sessions connected under each auth root, counted regardless of data flow.
// Sessions connected under each stats label, counted regardless of data flow.
const sessionRows = Object.keys(stats.sessions)
.sort()
.map((root) => {
const s = stats.sessions[root] ?? {};
.map((label) => {
const s = stats.sessions[label] ?? {};
return {
key: root,
key: label,
cells: [
root || "(none)",
label || "(none)",
String(active(sessionsStarted(s), sessionsEnded(s))),
String(sessionsStarted(s)),
],
Expand All @@ -550,7 +550,7 @@ ui.run((effect) => {
["broadcast", "viewers", "tracks", "egress", "frames", "groups", "datagrams", "fetches", "announce"],
egressRows(stats.egress),
);
renderTable($("node-session-roots"), ["auth root", "connected", "total"], sessionRows);
renderTable($("node-session-labels"), ["label", "connected", "total"], sessionRows);

const sessions = countSessions(stats.sessions);
$("node-sessions").textContent = `${sessions} session${sessions === 1 ? "" : "s"}`;
Expand Down
4 changes: 2 additions & 2 deletions doc/bin/inspect.md
Original file line number Diff line number Diff line change
Expand Up @@ -76,8 +76,8 @@ curl http://localhost:4443/fetch/.stats/node/local/host/publisher.json | jq
The node name (`local/host` here) is `stats.node`. Each fetch returns the
newest snapshot of cumulative counters. `totals.json` sums each tier's traffic
and sessions, `publisher.json` is egress per broadcast path,
`subscriber.json` is ingress, and `sessions.json` counts sessions per auth
root. A subscriber may also ask for `<path>/traffic.json`, one broadcast
`subscriber.json` is ingress, and `sessions.json` counts sessions per stats
label. A subscriber may also ask for `<path>/traffic.json`, one broadcast
prefix rolled up with each child, produced only while held. Fetch twice and divide by the interval for a
rate. The `.json.z` twins carry compressed patches, which these tools print as
raw bytes. [Stats](/concept/stats) describes every field.
6 changes: 3 additions & 3 deletions doc/bin/relay/auth.md
Original file line number Diff line number Diff line change
Expand Up @@ -28,7 +28,7 @@ token, the declared role, and the verified client certificate. Nothing is
parsed on the server's behalf: the `jwt` query parameter is a convention of
`moq auth serve`, not of the relay. The grant answers with `publish` and
`subscribe` pattern unions and optionally a `root` alias, read-only `mounts`,
`expires`, a `revalidate` cadence, a stats `tier`, and `peer` / `upstream` to
`expires`, a `revalidate` cadence, a stats `tier` and `label`, and `peer` / `upstream` to
mark another relay and an [upstream link](/bin/relay/cluster#upstream-links).
The fields are documented on `moq_auth::Request` and `moq_auth::Grant`
([Rust](/lib/rs/moq-auth), [TypeScript](/lib/js/auth)).
Expand All @@ -52,8 +52,8 @@ flowing. A wider grant brings those paths back within the admitted root and
SETUP role. A one-shot HTTP `/fetch` ends on a narrower grant instead. A
changed `root`, `mounts`, `peer`, or `upstream`, or a 401 or 403, ends that
credential's grant, which closes the session unless an
[in-band](#in-band-renewal) credential still holds it. A changed `tier` keeps
the session and moves its stats from then on. Any other failure retries with backoff and the session lives
[in-band](#in-band-renewal) credential still holds it. A changed `tier` or
`label` keeps the session and moves its later stats. Any other failure retries with backoff and the session lives
until `expires`, so an outage always has the bound the server chose. A grant
with `revalidate` must set `expires` for that reason. A session that
reaches `expires` closes as `Expired` rather than `Unauthorized`, which also
Expand Down
2 changes: 1 addition & 1 deletion doc/bin/relay/config.md
Original file line number Diff line number Diff line change
Expand Up @@ -316,7 +316,7 @@ relay dials and LAN peers it admits), which is what makes billing per customer o
Each run, and each group returning after its linger, announces under a fresh
[epoch](/concept/moq-lite#publisher-epochs), so a restart is a new broadcast at
the same path. Each group's totals count everything since its epoch began, so
billing reads those; per-path traffic and per-root sessions and HTTP requests are for
billing reads those; per-path traffic and per-label sessions and HTTP requests are for
dashboards. Session counters report how close sessions come to the
per-session limits, past which one is closed with `TOO_MANY_REQUESTS`.
[Stats](/concept/stats) describes the paths, tracks, and encodings; read them
Expand Down
47 changes: 28 additions & 19 deletions doc/concept/stats.md
Original file line number Diff line number Diff line change
Expand Up @@ -51,7 +51,7 @@ generate more stats.
- `<node>` tells relays sharing a cluster apart. It may span several segments
(`sjc/1`), and is omitted along with its slash when unset: `<prefix>/node`.
- `<group>` is the first `depth` segments of each broadcast path (for traffic)
or auth root (for sessions), so a consumer can scope an announce to one
or stats label (for sessions), so a consumer can scope an announce to one
tenant. A path shorter than `depth` groups under all of its segments.
- The literal `node` segment leaves room for sibling categories under the same
prefix, so a consumer skips any path without `node` where it expects one. A
Expand Down Expand Up @@ -89,8 +89,8 @@ comes in two encodings:
| `totals.json` | tier | [Totals](#totals) for the whole group |
| `[<tier>/]publisher.json` | broadcast path | [Traffic](#traffic) this node sent (egress) |
| `[<tier>/]subscriber.json` | broadcast path | [Traffic](#traffic) this node received (ingress) |
| `[<tier>/]sessions.json` | auth root | [Sessions](#sessions) connected now |
| `[<root>/]presence.json` | tier | [Sessions](#sessions) under one auth root |
| `[<tier>/]sessions.json` | stats label | [Sessions](#sessions) connected now |
| `[<label>/]presence.json` | tier | [Sessions](#sessions) under one stats label |
| `[<path>/]traffic.json` | tier | [Prefix](#prefix) traffic under one broadcast prefix |

The default tier's per-tier tracks are unprefixed. A named tier prefixes each
Expand All @@ -104,13 +104,13 @@ them earlier: any name of the shape
`[<tier>/]{publisher,subscriber,sessions}.json[.z]` is accepted and held open
with `{}` until the tier records.

A presence track exists only while subscribed. Ask for `<root>/presence.json`
for any auth root in the group (`presence.json` for the empty root). The relay
answers with the root's current sessions and counts from there, holding a root
A presence track exists only while subscribed. Ask for `<label>/presence.json`
for any stats label in the group (`presence.json` for the empty label). The relay
answers with the label's current sessions and counts from there, holding a label
with no sessions open at `{}`, and stops producing it once the last subscriber
leaves. A prefix track works the same way for any broadcast prefix in the
group: ask for `<path>/traffic.json` (`traffic.json` for the empty prefix). A
root or prefix outside the group, or any other name, is refused.
label or prefix outside the group, or any other name, is refused.

## Frames

Expand All @@ -136,7 +136,7 @@ under the limit, keeps updating.

Each tier that recorded anything in the group's epoch, with its egress
(`publisher`) and ingress (`subscriber`) [Traffic](#traffic) and its
[Sessions](#sessions), summed over every broadcast and auth root in the group.
[Sessions](#sessions), summed over every broadcast and stats label in the group.
Unlike the per-path tracks, an entry that ends stays counted, so the next
frame always carries everything since the epoch began: a reader that misses
frames loses nothing while the group stays announced. Billing reads this
Expand Down Expand Up @@ -241,6 +241,7 @@ should prefer the canonical name and fall back to the legacy one.
"acme": {
"requests": 3, "sessions_started": 12, "sessions_ended": 10,
"sessions": 12, "sessions_closed": 10,
"sent_bytes": 1048576, "received_bytes": 524288,
"sessions_refused": { "refused": 0, "unavailable": 0, "request": 0, "forbidden": 0, "lan": 0 },
"sessions_failed": { "idle_timeout": 1, "transport": 0, "application": 0, "expired": 0 },
"announces_peak": 40, "subscriptions_peak": 900,
Expand All @@ -250,18 +251,26 @@ should prefer the canonical name and fall back to the legacy one.
```

`sessions_started` and `sessions_ended` count connects and disconnects, whether
or not any data flows: under an auth root on the tier for `sessions.json`,
under the root on each tier for `presence.json`, and under every root in the
or not any data flows: under a stats label on the tier for `sessions.json`,
under the label on each tier for `presence.json`, and under every label in the
group on the tier for `totals.json`. `sessions` and `sessions_closed` are their
legacy spellings. A session moved to a new tier ends on the old one and starts
on the new.
on the new. `sent_bytes` and `received_bytes` count the payload this node sent
to and received from those sessions and HTTP requests, the same bytes the
per-path tracks count. A changed label moves later presence and bytes; bytes
before the change remain under the old label. Older readers ignore these fields
and newer readers default missing fields to zero.

The label is the grant's `label`, a path the auth server picks to attribute
usage, independent of the root that scopes what the session may access. A grant
without a `label` counts under the empty label, never under its root.

`wire_tx` and `wire_rx` count transport bytes sent and received, separately
from `Traffic.bytes`, which counts media payload. QUIC and WebTransport count
UDP bytes, including retransmissions and transport overhead. The transport
updates a connection's counters as it sends and receives, and a stats tick reads
them without polling the session or activating its periodic sampler. Tier
changes flush the old tier first; closing a session records its final delta.
them without polling the session or activating its periodic sampler. A retag
flushes the old tier and label first; closing a session records its final delta.
An embedder creates a `transport::Wire`, registers it with `stats::Handle::wire`
or `stats::Session::wire`, records its connection's cumulative totals on it, and
holds the returned guard. Dropping the guard records the final reading.
Expand All @@ -272,9 +281,9 @@ qmux counter source; unavailable counters are never estimated from payload.
Readers default missing wire fields to zero for older relays.

`sessions_refused` counts sessions turned away before admission, by reason.
They never start a session. The relay's own refusals have no resolved root, so
they count under the empty root on the default tier; an embedder can count one
it refuses itself with `stats::Handle::refuse`, under the root and tier it
They never start a session. The relay's own refusals have no resolved label, so
they count under the empty label on the default tier; an embedder can count one
it refuses itself with `stats::Handle::refuse`, under the label and tier it
resolved.

`sessions_failed` counts admitted sessions that ended abnormally, by kind: a
Expand All @@ -283,7 +292,7 @@ either side, a drain, or a shutdown is not a failure. A grant that expires
mid-session counts as `expired`; one revoked or narrowed out from under it
counts as `application`. A reader treats a missing object as zeros.

`requests` counts admitted request/response exchanges under the token's root and
`requests` counts admitted request/response exchanges under the token's label and
tier, including HTTP `/fetch` and `/announced`. They never start or end a session.
A fetch's delivered group bytes count against the broadcast path on that tier;
`/announced` delivers no media bytes. The auth decider can give HTTP its own tier
Expand All @@ -295,9 +304,9 @@ it was admitted; later traffic follows the new tier.
the relay, and subscriptions held on it, by any one session. Compare them with
the relay's [client or peer session limits](/bin/relay/config#session-and-peer):
a session that goes past one is closed with `TOO_MANY_REQUESTS`. On
`sessions.json` a peak never goes down while the root has a session; on the
`sessions.json` a peak never goes down while the label has a session; on the
totals and presence tracks it never goes down while the track lives. Summing
nodes or roots takes the largest.
nodes or labels takes the largest.

### Counters

Expand Down
3 changes: 2 additions & 1 deletion doc/lib/js/auth.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,8 @@ The TypeScript twin of [`moq-auth`](/lib/rs/moq-auth). `RequestSchema` and
what an auth server answers, so a Worker or a Node server implements the
contract with one import. It also generates keys, signs and verifies JWTs, and
checks a connection path against a token's claims exactly as `moq auth serve`
does. Tokens are interchangeable with the Rust side. Grants and claims are
does. A grant can label its session's stats independently of its authorization
root. Tokens are interchangeable with the Rust side. Grants and claims are
[`Pattern`](https://www.npmjs.com/package/@moq/pattern) unions: `foo` is one
broadcast, `foo/**` is a subtree, `**` is everything. Parsed roles are `Access`
values with path patterns and an optional bitrate cap; authorization preserves
Expand Down
2 changes: 1 addition & 1 deletion doc/lib/rs/moq-auth.md
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,7 @@ Everything a party needs to ask for or answer an authorization on
answers the relay, in a service that mints tokens for clients, or in your own
accept loop that decides in process.

- **Request and grant.** `Request` is the JSON a relay POSTs on each session event (`connect`, `revalidate`, `end`), carrying everything it knows about the session. `Grant` is the answer: publish and subscribe [`Pattern`](https://docs.rs/moq-pattern) unions, an expiry, a revalidation cadence, and whether the session is a cluster peer or an [upstream link](/bin/relay/cluster#upstream-links). `Grant::validate` checks the grant contract; the accept loop must enforce its caps or refuse it. Expiry is exact, with no allowance for clock skew.
- **Request and grant.** `Request` is the JSON a relay POSTs on each session event (`connect`, `revalidate`, `end`), carrying everything it knows about the session. `Grant` is the answer: publish and subscribe [`Pattern`](https://docs.rs/moq-pattern) unions, an expiry, a revalidation cadence, optional stats tier and label, and whether the session is a cluster peer or an [upstream link](/bin/relay/cluster#upstream-links). `Grant::validate` checks the grant contract; the accept loop must enforce its caps or refuse it. Expiry is exact, with no allowance for clock skew.
- **Lease.** `lease::Producer` and `lease::Consumer` are the handle a session holds for its grant: read it, wait for a change, revoke it, and learn why it ended. Whoever runs the accept loop builds the producer, so an embedder can decide in process with no HTTP.
- **Client.** `Client` drives a lease against an auth server over `https://`, `unix://`, or loopback `http://`. It revalidates on cadence and retries through an outage until the grant expires, revokes on a 401, 403, or invalid grant, and reports `end` with the session's byte totals.
- **Server** (feature `serve`). `serve::Server` is the reference auth server behind `moq auth serve`: JWTs from the query or the moq-transport SETUP token, certificate grants, anonymous rules, tiers, and session caps. `Server::router` mounts it in your own axum service.
Expand Down
2 changes: 2 additions & 0 deletions js/auth/src/contract.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -109,6 +109,7 @@ test("a grant round trips and is validated", () => {
expires: 4102444800,
revalidate: 60,
tier: "websocket",
label: "project/key/123",
});
expect(grant.publish?.toJSON()).toEqual(["alice/**"]);

Expand All @@ -119,6 +120,7 @@ test("a grant round trips and is validated", () => {
expect(() => GrantSchema.parse({ publish: ["**"], expires: 4102444800, revalidate: 0.5 })).toThrow();
expect(() => GrantSchema.parse({ publish: ["**"], expires: 4102444800.5 })).toThrow();
expect(() => GrantSchema.parse({ publish: ["a/**/b/**"] })).toThrow();
expect(() => GrantSchema.parse({ publish: ["**"], label: "project/*" })).toThrow(/invalid path/);
});

test("an auth endpoint grant accepts a capped role", () => {
Expand Down
17 changes: 17 additions & 0 deletions js/auth/src/contract.ts
Original file line number Diff line number Diff line change
Expand Up @@ -7,9 +7,24 @@
* @module
*/

import { Pattern } from "@moq/pattern";
import * as z from "@zod/mini";
import { AccessSchema } from "./access.ts";

const PathSchema = z.string().check(
z.refine(
(path) => {
try {
Pattern.literal(path);
return true;
} catch {
return false;
}
},
{ message: "invalid path" },
),
);

/** How a session reached the relay; `http` is a one-shot request on the relay's web listener. */
export const TransportSchema = z.pipe(
z.string(),
Expand Down Expand Up @@ -153,6 +168,8 @@ export const GrantSchema = z
revalidate: z.optional(z.int().check(z.positive())),
/** An opaque label handed to stats, so traffic can be bucketed. */
tier: z.optional(z.string()),
/** The literal path this session's stats record under, independent of its root. Absent records under the empty label. */
label: z.optional(PathSchema),
/** The session is a cluster peer (another relay): what it announces entered the cluster elsewhere. */
peer: z.optional(z.boolean()),
/** The peer is upstream: the relay never offers it a route learned from another upstream. Requires `peer`. */
Expand Down
3 changes: 2 additions & 1 deletion js/auth/src/interop.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -261,7 +261,7 @@ describe("Rust-serialized contract", () => {
const RUST_INVALID_END =
'{"id":"00ff","event":"end","reason":"invalid","duration":1.5,"bytes":{"sent":10,"received":20},"node":"relay-1","transport":"websocket","remote":"203.0.113.9:4433","path":"/demo/room","query":"jwt=abc"}';
const RUST_GRANT =
'{"publish":["alice/**"],"subscribe":["**"],"root":"pid/room","expires":4102444800,"revalidate":60,"tier":"websocket","peer":true,"upstream":true}';
'{"publish":["alice/**"],"subscribe":["**"],"root":"pid/room","expires":4102444800,"revalidate":60,"tier":"websocket","label":"project/key/123","peer":true,"upstream":true}';

test("parse a request a Rust relay sent", () => {
const request = RequestSchema.parse(JSON.parse(RUST_REQUEST));
Expand Down Expand Up @@ -297,6 +297,7 @@ describe("Rust-serialized contract", () => {
expires: 4102444800,
revalidate: 60,
tier: "websocket",
label: "project/key/123",
peer: true,
upstream: true,
});
Expand Down
1 change: 0 additions & 1 deletion quest/m2/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -84,7 +84,6 @@ ranked just below deterministic TS legs, which it requires.
- [Dart on iOS](/quest/m2/dart-ios.md) - prove the shipped iOS native asset actually loads on a device, which no CI can
- [Mobile completion](/quest/m2/mobile-completion.md) - verify the Swift and Kotlin bindings over Rust-owned capture before closing #700
- [WebGPU HDR](/quest/m2/webgpu-hdr.md) - HDR renditions play as HDR where the browser and display can show it, and tone-map to SDR elsewhere
- [Grant stats label](/quest/m2/grant-label.md) - an auth grant's optional `label` names what its session's presence and live bytes count under in stats, apart from the path scope it may access
- [One port](/quest/m2/one-port/README.md) - one UDP port carries QUIC, SRT, and WebRTC media through an embedder hook, and one TCP port carries HTTP, RTMP, and RTMPS
- [QUIC caps](/quest/m2/rate-quic.md) - paced MAX_DATA credit in and a capped pacer out hold a QUIC session to its token's bitrate
- [WebSocket caps](/quest/m2/rate-websocket.md) - paced reads and writes over bounded socket buffers hold WebSocket to the same caps
Expand Down
Loading
Loading