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 doc/lib/js/net.md
Original file line number Diff line number Diff line change
Expand Up @@ -60,6 +60,7 @@ route.announce();
- **A subscription asks for `ranges`.** Each [range](/concept/moq-lite#subscriptions) starts and ends at an `absolute` group, one `relative` to the latest, or the group containing a `time` (a `Timestamp`), and a reader reads only its own ranges. A read whose ranges all end finishes once every group in them is handed out, dropped, or skipped, as in Rust. A time anchor needs a timed track and `moq-lite-07-wip` over a session. Passing the old `groups` key throws a `TypeError` naming `ranges`; `withRange` only narrows reads locally.
- **Hidden paths** stay out of discovery unless the announce request opts in. See [hidden broadcasts](/concept/moq-lite#hidden-broadcasts).
- **Authorization is in band.** On moq-lite 07 (opt in with `versions: ["moq-lite-07-wip", "moq-lite-06"]`, listing every fallback you still want), `auth.grant` watches what the relay lets this side publish and subscribe to, and `auth.add(token)` presents another token without reconnecting, returning its `Auth.Credential` at once; `await credential.answered` waits for the peer's AUTH verdict on moq-lite 07, resolves at once on moq-transport, and rejects with `Unsupported` on older moq-lite. Publishing outside the grant closes the connection with `SessionCode.Unauthorized`, naming the path. On moq-lite, a subscription or track listing the grant stops covering resets with `StreamCode.Unauthorized` and the session stays up. On moq-transport, `auth.add(token)` only keeps the token for the requests that name it: a route created with the `Auth.Credential` it returns (`origin.route(path, { auth })`) carries it on that announcement's `PUBLISH_NAMESPACE`; `route.setAuth(other)` renews the request. A `Connection`'s `auth` handle (a getter on a pooled connection, following its URL) outlives its sessions: a token added there is presented on every reconnect and keeps riding the announcements that name it, with no re-add or re-announce. A one-shot session's `auth` ends with it, unless `Connection.connect` was given a `new Auth.Handle()` as `auth`.
- **A reconnecting `Connection` reports the peer's verdict on its tokens.** `await connection.answered()` waits for the first answer to the tokens last set (the initial ones before any set): each is granted in band, or is the connection credential a dial carried and the peer accepted. A token the set kept, the connection credential included, counts only once the peer refuses it, and nothing is re-checked after the answer. It rejects with the peer's refusal, with `Unsupported` when the session cannot carry a token in band, or with the connection's end, or with the failure that stopped it retrying its URL while no session answered, such as a refused first dial. On a version without AUTH, a close before the peer's SETUP is its refusal. An app that re-signs its credential for each dial ends the connection on a refusal by aborting `connection.auth`, which makes the loop give up with that error.
- **A graceful close waits.** `await connection.close()` withdraws announcements and drains for up to one second. `moq-lite-05` and newer wait for the subscriber to receive finished tails; older Lite versions wait only for transport ACKs. IETF media streams are not drained. `abort()` ends immediately.

Examples:
Expand Down
1 change: 1 addition & 0 deletions js/net/api/index.api.md
Original file line number Diff line number Diff line change
Expand Up @@ -241,6 +241,7 @@ export class Connection {
static readonly accept: ({ ... }: Connection.AcceptProps) => Promise<Connection.Session>;
readonly allocator: Signals.Getter<Bandwidth.Handle | undefined>;
announced(scope?: Path.Pattern, options?: Announce.Options): Announce.Consumer;
answered(): Promise<void>;
readonly auth: Signals.Getter<Auth.Handle | undefined>;
static readonly certificateHash: (cert: string | BufferSource) => Promise<Uint8Array<ArrayBuffer>>;
static readonly checkVersions: (versions: readonly string[]) => string[];
Expand Down
50 changes: 49 additions & 1 deletion js/net/src/auth_session.ts
Original file line number Diff line number Diff line change
Expand Up @@ -164,6 +164,8 @@ export interface Pending extends Credential {
readonly answered: Promise<void>;
/** Whether any session holds a grant for it now, a draining one included. */
readonly held: boolean;
/** Whether a peer granted it in band: false for a token only a request carries, which {@link answered} also resolves for. */
readonly inband: boolean;
}

/** A token the application added to a {@link Handle}, presented on every session of it. */
Expand All @@ -175,6 +177,7 @@ class Token implements Pending {

isAnswered = false;
ended = false;
inband = false;

#state: HandleState;
#close!: (err: Error | null) => void;
Expand Down Expand Up @@ -229,6 +232,8 @@ class HandleState {
own = false;
/** Set once the handle ends. */
closed?: Error;
/** The handle's end, for a watcher that outlives its sessions. */
readonly end = new Signal<Error | undefined>(undefined);
/** Every token the application added that has not ended. */
readonly tokens = new Set<Token>();
/** Every open session built on this handle, oldest first. */
Expand Down Expand Up @@ -307,6 +312,7 @@ class HandleState {
abort(err: Error) {
if (this.closed) return;
this.closed = err;
this.end.set(err);
for (const token of [...this.tokens]) this.verdict(token, err);
if (this.acceptor instanceof RequestQueue) this.acceptor.close();
}
Expand Down Expand Up @@ -338,6 +344,15 @@ export function ended(handle: Handle): Error | undefined {
return stateOf(handle).closed;
}

/**
* When `handle` ends, with why, for a watcher that outlives its sessions.
*
* @internal
*/
export function ending(handle: Handle): Getter<Error | undefined> {
return stateOf(handle).end;
}

/**
* The tokens this side presents and the grant they earn, across every session built on it.
*
Expand Down Expand Up @@ -597,6 +612,11 @@ export interface AuthSessionProps {
handle?: Handle;
/** Whether the session is draining after a GOAWAY or a local close, which frees its handle for a successor. */
draining?: () => boolean;
/**
* Whether the peer's SETUP, still to come, is what accepts the connection credential: a
* session without AUTH that is live before its peer has checked the credential.
*/
awaiting?: boolean;
}

/**
Expand Down Expand Up @@ -631,6 +651,9 @@ export class AuthSession {
// #presented by #recount after every change to it or to an `isAnswered`.
#setupPending = new Signal(0);
#pending = new Signal(0);
// The peer's verdict on the connection credential this session presented: null once accepted,
// the refusal, or undefined while it has none.
#credential = new Signal<Error | null | undefined>(undefined);
#closed = false;

// Whoever answers the peer's tokens is decided once, after the task that established
Expand All @@ -639,14 +662,16 @@ export class AuthSession {
#decided = yieldNow();

/** Throws {@link Duplicate} while `handle` backs another active session, or the handle's end. */
constructor({ wire, requests, peerGrant, handle, draining }: AuthSessionProps) {
constructor({ wire, requests, peerGrant, handle, draining, awaiting }: AuthSessionProps) {
this.handle = handle ?? ownHandle();
this.#state = stateOf(this.handle);
this.#wire = wire;
this.#requests = requests ?? false;
this.#peerGrant = peerGrant;
this.#draining = draining ?? (() => false);
this.#state.attach(this);
// A session without AUTH has the peer's acceptance with its handshake, unless it awaits its SETUP.
if (!wire && !awaiting) this.#credential.set(null);

// Present the connection's own credential right away, so both sides learn their
// grant without waiting on the app.
Expand All @@ -659,6 +684,20 @@ export class AuthSession {
return !this.#closed && !this.#draining();
}

/**
* The peer's verdict on the connection credential this session presented: `null` once it
* accepted it, its refusal, or undefined while it has none, which the session ending leaves
* to the session's own close.
*/
get credential(): Getter<Error | null | undefined> {
return this.#credential;
}

/** The peer's SETUP arrived, so it accepted the connection credential a session without AUTH presented. */
accepted(): void {
if (!this.#wire) this.#credential.set(null);
}

/** The union of this session's grants, undefined until its peer first answers. */
get grant(): Getter<Grant | undefined> {
return this.#union;
Expand Down Expand Up @@ -917,6 +956,7 @@ export class AuthSession {
answered = granted = replied = true;
delay = undefined;
this.#replied = true;
if (presented.setup) this.#credential.set(null);
this.#answered(presented);
this.#recompute();
continue;
Expand Down Expand Up @@ -991,6 +1031,13 @@ export class AuthSession {

// Already ended by the session's close.
if (presented.ended) return;
// The peer's verdict on the credential: Unsupported is the moq-transport SETUP that
// carried it accepting it before the peer declined AUTH. Anything else leaves it to the close.
if (presented.setup && !presented.withdrawn && isVerdict(refused, granted, result)) {
this.#credential.set(
result instanceof Unsupported ? null : (result ?? new Error("the peer ended the credential")),
);
}
presented.ended = true;
presented.grant = undefined;
// A token that ends unanswered counts as answered for enforcement: its refusal is
Expand Down Expand Up @@ -1024,6 +1071,7 @@ export class AuthSession {
/** The peer granted `presented`: it counts as answered, and so does the handle's token. */
#answered(presented: Presented) {
presented.isAnswered = true;
if (presented.owner) presented.owner.inband = true;
presented.owner?.answer();
}

Expand Down
Loading