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
11 changes: 8 additions & 3 deletions doc/bin/gstreamer.md
Original file line number Diff line number Diff line change
Expand Up @@ -171,9 +171,14 @@ gets EOS once its track ends. A broadcast that ends or loses its publisher holds
its pads without EOS until it is announced again, so the pipeline does not end
on its own. Losing the relay connection also holds the pads: `moqsrc` redials
without a retry deadline and resumes when the broadcast returns. A first connect
that reaches no relay posts an error rather than retrying. A refused
connection, refused path or catalog, or malformed protocol input or catalog posts
an error. Properties: `url`,
that reaches no relay posts an error rather than retrying, as does a first
connection the relay refuses, or a session it closes before the connection has
stayed up for a second. Once playback has begun, a session the relay closes is
redialed, whatever its code, and a refused redial is retried like any other
failure. A refused path or catalog, malformed input or catalog, or a catalog its
publisher ended with an application code posts an error. A media track its
publisher ended with an application code logs a warning and leaves its pad idle;
it posts no error. Properties: `url`,
`broadcast`, `max-delay`, `connect-version` (comma-separated protocol versions to offer, most
preferred first; every stable version by default), `tls-disable-verify`,
`quic-idle-timeout`, `quic-keep-alive`, and `quic-keylog`.
Expand Down
14 changes: 0 additions & 14 deletions go/wrapper/types.go
Original file line number Diff line number Diff line change
Expand Up @@ -217,8 +217,6 @@ const (
ProtocolKindExpired = ffi.MoqProtocolKindExpired
// ProtocolKindProtocolViolation identifies protocol violation.
ProtocolKindProtocolViolation = ffi.MoqProtocolKindProtocolViolation
// ProtocolKindKeyValueFormatting identifies key value formatting.
ProtocolKindKeyValueFormatting = ffi.MoqProtocolKindKeyValueFormatting
// ProtocolKindGoawayTimeout identifies goaway timeout.
ProtocolKindGoawayTimeout = ffi.MoqProtocolKindGoawayTimeout
// ProtocolKindTimeout identifies timeout.
Expand Down Expand Up @@ -253,20 +251,8 @@ const (
ProtocolKindUnknown = ffi.MoqProtocolKindUnknown
// ProtocolKindTooManyRequests identifies an exceeded session request cap.
ProtocolKindTooManyRequests = ffi.MoqProtocolKindTooManyRequests
// ProtocolKindAuthTokenCacheOverflow identifies an exceeded token cache limit.
ProtocolKindAuthTokenCacheOverflow = ffi.MoqProtocolKindAuthTokenCacheOverflow
// ProtocolKindMalformedAuthToken identifies an unparseable authorization token.
ProtocolKindMalformedAuthToken = ffi.MoqProtocolKindMalformedAuthToken
// ProtocolKindUnknownAuthTokenAlias identifies an unregistered token alias.
ProtocolKindUnknownAuthTokenAlias = ffi.MoqProtocolKindUnknownAuthTokenAlias
// ProtocolKindInvalidRequestId identifies an invalid request ID.
ProtocolKindInvalidRequestId = ffi.MoqProtocolKindInvalidRequestId
// ProtocolKindInvalidPath identifies an invalid session path.
ProtocolKindInvalidPath = ffi.MoqProtocolKindInvalidPath
// ProtocolKindInvalidAuthority identifies an invalid session authority.
ProtocolKindInvalidAuthority = ffi.MoqProtocolKindInvalidAuthority
// ProtocolKindTooManyRequestUpdates identifies an exceeded request update limit.
ProtocolKindTooManyRequestUpdates = ffi.MoqProtocolKindTooManyRequestUpdates
)

// AudioSampleFormat values: the raw PCM sample layout fed to or returned from the
Expand Down
14 changes: 7 additions & 7 deletions js/net/api/index.api.md
Original file line number Diff line number Diff line change
Expand Up @@ -332,6 +332,12 @@ export namespace Error {
export class RefusedRedirect extends Error {
constructor(reason: string);
}
export const Retry: Readonly<{
readonly Never: "never";
readonly Reroute: "reroute";
readonly Same: "same";
}>;
export type Retry = typeof Error.Retry[keyof typeof Error.Retry];
export class Session extends Error {
constructor(code: SessionCode, options?: {
cause?: unknown;
Expand Down Expand Up @@ -362,6 +368,7 @@ export namespace Error {
cause?: unknown;
});
}
export function retry(err: unknown): Error.Retry;
}

export namespace Frame {
Expand Down Expand Up @@ -578,22 +585,15 @@ export namespace Path {
}

export const SessionCode: ((code: number) => SessionCode) & {
readonly AuthTokenCacheOverflow: SessionCode;
readonly Cancel: SessionCode;
readonly Expired: SessionCode;
readonly GoawayTimeout: SessionCode;
readonly Internal: SessionCode;
readonly InvalidAuthority: SessionCode;
readonly InvalidPath: SessionCode;
readonly InvalidRequestId: SessionCode;
readonly KeyValueFormatting: SessionCode;
readonly MalformedAuthToken: SessionCode;
readonly ProtocolViolation: SessionCode;
readonly Timeout: SessionCode;
readonly TooManyRequestUpdates: SessionCode;
readonly TooManyRequests: SessionCode;
readonly Unauthorized: SessionCode;
readonly UnknownAuthTokenAlias: SessionCode;
readonly Unsupported: SessionCode;
readonly Version: SessionCode;
};
Expand Down
7 changes: 4 additions & 3 deletions js/net/src/connection/handshake.ts
Original file line number Diff line number Diff line change
@@ -1,6 +1,7 @@
import { Duration } from "@moq/clock";
import { closeReason, ProtocolViolation, SessionCode, StreamError } from "../error.ts";
import { closeReason, ProtocolViolation, StreamError } from "../error.ts";
import { type Hop, randomHop } from "../hop.ts";
import { IetfSessionCode } from "../ietf/error.ts";
import * as Ietf from "../ietf/index.ts";
import * as Message from "../ietf/message.ts";
import * as Lite from "../lite/index.ts";
Expand Down Expand Up @@ -160,10 +161,10 @@ async function receiveSetup(

// A server sends neither PATH nor AUTHORITY (draft-22 sections 9.1.1 and 9.1.2).
if (client && setup.parameters.getBytes(Ietf.SetupOption.Path) !== undefined) {
throw new ProtocolViolation("server SETUP carries PATH", { code: SessionCode.InvalidPath });
throw new ProtocolViolation("server SETUP carries PATH", { code: IetfSessionCode.InvalidPath });
}
if (client && setup.parameters.getBytes(Ietf.SetupOption.Authority) !== undefined) {
throw new ProtocolViolation("server SETUP carries AUTHORITY", { code: SessionCode.InvalidAuthority });
throw new ProtocolViolation("server SETUP carries AUTHORITY", { code: IetfSessionCode.InvalidAuthority });
}
// Nothing here uses the peer's token, but one that cannot be decoded still closes the
// session (draft-22 section 8.9).
Expand Down
40 changes: 31 additions & 9 deletions js/net/src/error.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,9 @@ import {
Lagged,
NotFound,
ProtocolViolation,
Retry,
reason,
retry,
SessionCode,
SessionError,
StreamCode,
Expand Down Expand Up @@ -93,8 +95,35 @@ test("the error type names the registry the code came from", () => {
expect(Number(stream.code)).toBe(Number(session?.code));
});

test("invalid request IDs keep their session registry code", () => {
expect(fromClose({ closeCode: 0x4 })?.code).toBe(SessionCode.InvalidRequestId);
test("a code only moq-transport defines keeps its number", () => {
for (const code of [0x4, 0x6, 0x8, 0x13, 0x17, 0x19, 0x1b]) {
expect(Number(fromClose({ closeCode: code })?.code)).toBe(code);
expect(Object.values(SessionCode) as number[]).not.toContain(code);
}
});

test("retry separates a failed delivery from a verdict", () => {
for (const err of [
new SessionError(SessionCode.Unauthorized),
new SessionError(0x4 as SessionCode),
new StreamError(StreamCode.SessionClosed),
new StreamError(StreamCode.Cancel),
new StreamError(StreamCode.ControlTimeout),
Object.assign(new Error("closed"), { source: "session" }),
]) {
expect([err.message, retry(err)]).toEqual([err.message, Retry.Same]);
}
expect(retry(new StreamError(StreamCode.Unroutable))).toBe(Retry.Reroute);
for (const err of [
new NotFound("broadcast"),
new StreamError(StreamCode.Unauthorized),
new StreamError(StreamCode.MalformedTrack),
new StreamError(0x22 as StreamCode),
new Error("malformed"),
"thrown",
]) {
expect([String(err), retry(err)]).toEqual([String(err), Retry.Never]);
}
});

test("the code types reject the other registry", () => {
Expand Down Expand Up @@ -214,19 +243,12 @@ test("session codes match the draft's Session Error Codes table", () => {
Internal: 0x1,
Unauthorized: 0x2,
ProtocolViolation: 0x3,
InvalidRequestId: 0x4,
KeyValueFormatting: 0x6,
TooManyRequests: 0x7,
InvalidPath: 0x8,
GoawayTimeout: 0x10,
Timeout: 0x11,
AuthTokenCacheOverflow: 0x13,
Version: 0x15,
MalformedAuthToken: 0x16,
UnknownAuthTokenAlias: 0x17,
Expired: 0x18,
InvalidAuthority: 0x19,
TooManyRequestUpdates: 0x1b,
Unsupported: 0x30,
});
});
Expand Down
78 changes: 59 additions & 19 deletions js/net/src/error.ts
Original file line number Diff line number Diff line change
Expand Up @@ -18,12 +18,14 @@ export type SessionCode = number & { readonly [SESSION_CODE]: true };
/**
* Codes a peer sends when terminating the session, mirroring the Rust `Session`.
*
* Specified by moq-lite, which reuses moq-transport's codes unchanged. Call `SessionCode(code)`
* to construct an application code in the 64+ range. {@link StreamCode} is the other registry,
* and the two are disjoint, so the same integer means different things in each.
* moq-lite's registry, which reuses moq-transport's value for each code the two share. Call
* `SessionCode(code)` to construct an application code in the 64+ range. {@link StreamCode} is
* the other registry, and the two are disjoint, so the same integer means different things in
* each.
*
* Codes 32-47 are reserved: nothing is sent there, and the draft gives a received one no
* meaning, so treat anything not listed below as an unspecified error rather than guessing.
* meaning. A code only moq-transport defines arrives as its number too, so treat anything not
* listed below as an unspecified error rather than guessing.
*
* @public
*/
Expand All @@ -39,32 +41,18 @@ export const SessionCode = Object.freeze(
Expired: 0x18 as SessionCode,
/** A protocol rule was broken; the session is unusable. */
ProtocolViolation: 0x3 as SessionCode,
/** A request ID was reused or violated the negotiated draft’s order or parity rules. */
InvalidRequestId: 0x4 as SessionCode,
/** A key-value pair was malformed or repeated more than allowed. */
KeyValueFormatting: 0x6 as SessionCode,
/** The peer went past what the session allows: a request ID past MAX_REQUEST_ID, or too many announcements. */
TooManyRequests: 0x7 as SessionCode,
/** A PATH the peer may not send, such as a server sending one at all. */
InvalidPath: 0x8 as SessionCode,
/** The peer did not close within the GOAWAY drain deadline. */
GoawayTimeout: 0x10 as SessionCode,
/** A control message took too long. */
Timeout: 0x11 as SessionCode,
/** A token registration would exceed the advertised token cache size, which is 0 when unadvertised. */
AuthTokenCacheOverflow: 0x13 as SessionCode,
/** No version could be negotiated. */
Version: 0x15 as SessionCode,
/** The token could not be parsed. Retrying with the same token will fail again. */
MalformedAuthToken: 0x16 as SessionCode,
/** A token named an alias that was never registered. */
UnknownAuthTokenAlias: 0x17 as SessionCode,
/** An AUTHORITY the peer may not send, such as a server sending one at all. */
InvalidAuthority: 0x19 as SessionCode,
/** The peer cannot support the requested feature; moq-lite only. */
/** The peer cannot support the requested feature, token, or grant. */
Unsupported: 0x30 as SessionCode,
/** The peer left more request updates unanswered than MAX_REQUEST_UPDATES allows. */
TooManyRequestUpdates: 0x1b as SessionCode,
} as const),
);

Expand Down Expand Up @@ -405,6 +393,58 @@ function localStreamCode(err: unknown): StreamCode {
return StreamCode.Internal;
}

/**
* What a caller does after a request fails, as {@link retry} answers it. Mirrors the Rust `Retry`.
*
* @public
*/
export const Retry = Object.freeze({
/**
* The source failed to deliver rather than judging the request, so asking it again may
* succeed: its connection dropped, its session ended, or it is going away.
*/
Same: "same",
/**
* The source lost its route to the content, so only another route continues it. Asking the
* same source again can only replace the withdrawal's cause with a refusal.
*/
Reroute: "reroute",
/**
* The answer judged the request or what it carried, so it repeats on every attempt: refused,
* not found, or malformed.
*/
Never: "never",
} as const);

/** One of the {@link Retry} answers. @public */
export type Retry = (typeof Retry)[keyof typeof Retry];

// Stream codes that report the source failing to deliver rather than judging what it carried.
const DELIVERY_FAILURES: ReadonlySet<number> = new Set([
StreamCode.Internal,
StreamCode.Cancel,
StreamCode.SessionClosed,
StreamCode.GoingAway,
StreamCode.ControlTimeout,
]);

/**
* What to do after a request failed with `err`: ask the same source again, find another route,
* or give up. Mirrors the Rust `Error::retry`.
*
* A session closing, whatever its code, is the route failing to deliver: whether the session
* comes back is the connection's call, not the request's.
*
* @public
*/
export function retry(err: unknown): Retry {
if (err instanceof Stream) {
if (err.code === StreamCode.Unroutable) return Retry.Reroute;
return DELIVERY_FAILURES.has(err.code) ? Retry.Same : Retry.Never;
}
return err instanceof Session || sessionClosed(err) ? Retry.Same : Retry.Never;
}

/**
* A group was created at a sequence its track declared skipped.
*
Expand Down
4 changes: 3 additions & 1 deletion js/net/src/errors.ts
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
/**
* Session and stream error types.
* Session and stream error types, and what to do after one.
*
* @module
*/
Expand All @@ -10,6 +10,8 @@ export {
NotFound,
ProtocolViolation,
RefusedRedirect,
Retry,
retry,
Session,
Skipped,
Stream,
Expand Down
19 changes: 10 additions & 9 deletions js/net/src/ietf/connection.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,7 @@ import * as Path from "../path.ts";
import { Stream, Writer } from "../stream.ts";
import { Timescale } from "../time.ts";
import { Connection } from "./connection.ts";
import { IetfSessionCode } from "./error.ts";
import { Fetch, type FetchType } from "./fetch.ts";
import * as Message from "./message.ts";
import * as Namespace from "./namespace.ts";
Expand Down Expand Up @@ -378,11 +379,11 @@ function updateWithTokens(...tokens: (readonly number[])[]): Uint8Array {
*/
for (const [version, alpn] of [[Version.DRAFT_22, ALPN.DRAFT_22]] as const) {
for (const [name, token, code] of [
["REGISTER", [0x01, 0x07, 0x00], SessionCode.AuthTokenCacheOverflow],
["DELETE", [0x00, 0x07], SessionCode.UnknownAuthTokenAlias],
["USE_ALIAS", [0x02, 0x07], SessionCode.UnknownAuthTokenAlias],
["USE_VALUE without a type", [0x03], SessionCode.KeyValueFormatting],
["an unknown alias type", [0x04, 0x00], SessionCode.KeyValueFormatting],
["REGISTER", [0x01, 0x07, 0x00], IetfSessionCode.AuthTokenCacheOverflow],
["DELETE", [0x00, 0x07], IetfSessionCode.UnknownAuthTokenAlias],
["USE_ALIAS", [0x02, 0x07], IetfSessionCode.UnknownAuthTokenAlias],
["USE_VALUE without a type", [0x03], IetfSessionCode.KeyValueFormatting],
["an unknown alias type", [0x04, 0x00], IetfSessionCode.KeyValueFormatting],
] as const) {
test(`a request token with ${name} closes ${alpn}`, async () => {
const logged = spyOn(console, "error").mockImplementation(() => void 0);
Expand Down Expand Up @@ -416,10 +417,10 @@ for (const [version, alpn] of [[Version.DRAFT_22, ALPN.DRAFT_22]] as const) {
*/
for (const [version, alpn] of [[Version.DRAFT_22, ALPN.DRAFT_22]] as const) {
for (const [name, token, code] of [
["REGISTER", [0x01, 0x07, 0x00], SessionCode.AuthTokenCacheOverflow],
["DELETE", [0x00, 0x07], SessionCode.UnknownAuthTokenAlias],
["USE_ALIAS", [0x02, 0x07], SessionCode.UnknownAuthTokenAlias],
["USE_VALUE without a type", [0x03], SessionCode.KeyValueFormatting],
["REGISTER", [0x01, 0x07, 0x00], IetfSessionCode.AuthTokenCacheOverflow],
["DELETE", [0x00, 0x07], IetfSessionCode.UnknownAuthTokenAlias],
["USE_ALIAS", [0x02, 0x07], IetfSessionCode.UnknownAuthTokenAlias],
["USE_VALUE without a type", [0x03], IetfSessionCode.KeyValueFormatting],
] as const) {
test(`an update token with ${name} closes ${alpn}`, async () => {
const logged = spyOn(console, "error").mockImplementation(() => void 0);
Expand Down
6 changes: 3 additions & 3 deletions js/net/src/ietf/connection.ts
Original file line number Diff line number Diff line change
Expand Up @@ -7,14 +7,14 @@ import type { Goaway } from "../connection/goaway.ts";
import type { Session } from "../connection/session.ts";
import { detect, type Probe, type Stats, transportStats } from "../connection/stats.ts";
import { type Transport, transportOf } from "../connection/transport.ts";
import { error, fromClose, ProtocolViolation, SessionCode, StreamCode, StreamError, sessionClosed } from "../error.ts";
import { error, fromClose, ProtocolViolation, StreamCode, StreamError, sessionClosed } from "../error.ts";
import type { Consumer as OriginConsumer } from "../origin.ts";
import * as Path from "../path.ts";
import { type Reader, Readers, type Stream } from "../stream.ts";
import { withTimeout } from "../util/timeout.ts";
import { registerWire } from "../wire.ts";
import * as Cluster from "./cluster.ts";
import type { RequestKind } from "./error.ts";
import { IetfSessionCode, type RequestKind } from "./error.ts";
import { Fetch, FetchHeader } from "./fetch.ts";
import { GoAway } from "./goaway.ts";
import * as Message from "./message.ts";
Expand Down Expand Up @@ -578,7 +578,7 @@ export class Connection implements Session {
}
if (msg.requestId !== undefined && msg.requestId % 2n !== (this.#client ? 0n : 1n)) {
throw new ProtocolViolation("GOAWAY Request ID has the wrong parity", {
code: SessionCode.InvalidRequestId,
code: IetfSessionCode.InvalidRequestId,
});
}
// Reject bytes already behind GOAWAY before a caller can close on the drain.
Expand Down
Loading