@voltkit-rtc/client 0.6.0 → 0.7.0

package/src/chat.ts

@@ -7,7 +7,9 @@
  * nothing else -- for an audience that is watching a broadcast over a CDN and
  * has no reason to be on an SFU.
  */
+import { isTerminalError } from './errors.js';
 import type { Role } from './index.js';
+import { socketUrl } from './token.js';
 
 export interface ChatMessage {
   /** Monotonic within a channel, so the oldest id held is a paging cursor. */
@@ -95,16 +97,6 @@ interface Pending {
 
 const RPC_TIMEOUT_MS = 15_000;
 const MAX_RECONNECT_ATTEMPTS = 8;
-/** A token that is wrong will be wrong next time too; retrying only adds noise. */
-const TERMINAL_JOIN_ERRORS = new Set([
-  'bad-token',
-  'no-token',
-  // The account cannot use the service until it is topped up or restored.
-  'quota-exhausted',
-  'daily-limit-reached',
-  'monthly-limit-reached',
-  'tenant-suspended',
-]);
 
 const sleep = (ms: number) => new Promise((r) => setTimeout(r, ms));
 
@@ -179,9 +171,7 @@ export class ChatClient {
   private openSocket(): Promise<void> {
     this.detachSocket();
     return new Promise((resolve, reject) => {
-      const url = new URL(this.wsUrl);
-      url.searchParams.set('token', this.token);
-      const ws = new WebSocket(url.toString());
+      const ws = new WebSocket(socketUrl(this.wsUrl, this.token));
       this.ws = ws;
 
       const onError = () => reject(new Error('websocket failed to open'));
@@ -246,7 +236,10 @@ export class ChatClient {
           return;
         } catch (err) {
           this.emit('error', err as Error);
-          if (err instanceof ChatRpcError && TERMINAL_JOIN_ERRORS.has(err.code)) {
+          // A token that is wrong will be wrong next time too, and an account
+          // that ran out stays out until topped up: the registry's terminal
+          // codes, shared with StreamClient. Retrying only adds noise.
+          if (err instanceof ChatRpcError && isTerminalError(err.code)) {
             this.closedByUs = true;
             this.emit('closed', 'gave-up');
             return;

package/src/errors.ts

@@ -0,0 +1,162 @@
+/**
+ * One error registry for every VoltKit SDK (docs/sdk-contract.json): the codes
+ * the controller and the media nodes answer with, passed through unchanged, and
+ * the ones the SDKs raise themselves. Switch on `error.code`, never on the
+ * message.
+ *
+ * Kept as a literal here, since the package cannot read the repository's docs
+ * at runtime, and checked against the contract by
+ * scripts/test/sdk-contract-browser.sh and test/contract.test.mjs. One code per
+ * line, so that check can read it.
+ */
+
+/** Who raises a code: the server (controller or media node) or the SDK itself. */
+export type ErrorOrigin = 'server' | 'sdk';
+
+export interface ErrorInfo {
+  origin: ErrorOrigin;
+  /** A join (or reconnect) refused with it must not be retried with the same token. */
+  terminal: boolean;
+  /** Trying the same call again later can succeed. */
+  retryable: boolean;
+}
+
+export const ERROR_CODES = {
+  'bad-json': { origin: 'server', terminal: false, retryable: false },
+  'bad-params': { origin: 'server', terminal: false, retryable: false },
+  'unknown-method': { origin: 'server', terminal: false, retryable: false },
+  'too-many-requests': { origin: 'server', terminal: false, retryable: true },
+  'not-joined': { origin: 'server', terminal: false, retryable: false },
+  'already-joined': { origin: 'server', terminal: false, retryable: false },
+  'internal': { origin: 'server', terminal: false, retryable: true },
+  'node-error': { origin: 'server', terminal: false, retryable: true },
+  'no-token': { origin: 'server', terminal: true, retryable: false },
+  'bad-token': { origin: 'server', terminal: true, retryable: false },
+  'wrong-tenant': { origin: 'server', terminal: true, retryable: false },
+  'token-mismatch': { origin: 'server', terminal: false, retryable: false },
+  'no-room': { origin: 'server', terminal: true, retryable: false },
+  'room-ended': { origin: 'server', terminal: true, retryable: false },
+  'kicked': { origin: 'server', terminal: true, retryable: false },
+  'no-node': { origin: 'server', terminal: false, retryable: true },
+  'no-capacity': { origin: 'server', terminal: false, retryable: true },
+  'stage-full': { origin: 'server', terminal: false, retryable: true },
+  'participant-quota': { origin: 'server', terminal: false, retryable: true },
+  'viewer-quota': { origin: 'server', terminal: false, retryable: true },
+  'quota-exhausted': { origin: 'server', terminal: true, retryable: false },
+  'daily-limit-reached': { origin: 'server', terminal: true, retryable: false },
+  'monthly-limit-reached': { origin: 'server', terminal: true, retryable: false },
+  'tenant-suspended': { origin: 'server', terminal: true, retryable: false },
+  'billing-unavailable': { origin: 'server', terminal: true, retryable: false },
+  'forbidden': { origin: 'server', terminal: true, retryable: false },
+  'not-in-room': { origin: 'server', terminal: false, retryable: false },
+  'no-participant': { origin: 'server', terminal: false, retryable: false },
+  'bad-transport': { origin: 'server', terminal: false, retryable: false },
+  'no-transport': { origin: 'server', terminal: false, retryable: false },
+  'no-producer': { origin: 'server', terminal: false, retryable: false },
+  'no-consumer': { origin: 'server', terminal: false, retryable: false },
+  'cannot-consume': { origin: 'server', terminal: false, retryable: false },
+  'consumer-cap': { origin: 'server', terminal: false, retryable: true },
+  'producer-cap': { origin: 'server', terminal: false, retryable: true },
+  'room-cap': { origin: 'server', terminal: false, retryable: true },
+  'draining': { origin: 'server', terminal: false, retryable: true },
+  'bad-request': { origin: 'server', terminal: false, retryable: false },
+  'source-already-published': { origin: 'server', terminal: false, retryable: false },
+  'force-muted': { origin: 'server', terminal: false, retryable: false },
+  'media-disabled': { origin: 'server', terminal: false, retryable: false },
+  'frame-rate-not-allowed': { origin: 'server', terminal: false, retryable: false },
+  'video-quality-not-allowed': { origin: 'server', terminal: false, retryable: false },
+  'audio-quality-not-allowed': { origin: 'server', terminal: false, retryable: false },
+  'video-not-allowed': { origin: 'server', terminal: false, retryable: false },
+  'audio-not-allowed': { origin: 'server', terminal: false, retryable: false },
+  'video-subscription-limit': { origin: 'server', terminal: false, retryable: false },
+  'slot-taken': { origin: 'server', terminal: false, retryable: false },
+  'slot-blocked': { origin: 'server', terminal: false, retryable: false },
+  'slot-occupied': { origin: 'server', terminal: false, retryable: false },
+  'chat-muted': { origin: 'server', terminal: false, retryable: false },
+  'rate-limited': { origin: 'server', terminal: false, retryable: true },
+  'no-message': { origin: 'server', terminal: false, retryable: false },
+  'chat-unavailable': { origin: 'server', terminal: false, retryable: false },
+  'closed': { origin: 'server', terminal: false, retryable: true },
+  'unauthorized': { origin: 'server', terminal: false, retryable: false },
+  'bad-signature': { origin: 'server', terminal: false, retryable: false },
+  'operator-only': { origin: 'server', terminal: false, retryable: false },
+  'bad-role': { origin: 'server', terminal: false, retryable: false },
+  'room-exists': { origin: 'server', terminal: false, retryable: false },
+  'room-quota': { origin: 'server', terminal: false, retryable: true },
+  'no-nodes': { origin: 'server', terminal: false, retryable: true },
+  'capacity-exhausted': { origin: 'server', terminal: false, retryable: true },
+  'unavailable': { origin: 'server', terminal: false, retryable: true },
+  'not-found': { origin: 'server', terminal: false, retryable: false },
+  'broadcast-disabled': { origin: 'server', terminal: false, retryable: false },
+  'chat-disabled': { origin: 'server', terminal: false, retryable: false },
+  'no-stream': { origin: 'server', terminal: false, retryable: false },
+  'stream-exists': { origin: 'server', terminal: false, retryable: false },
+  'stream-quota': { origin: 'server', terminal: false, retryable: true },
+  'network': { origin: 'sdk', terminal: false, retryable: true },
+  'rates-unconfigured': { origin: 'sdk', terminal: false, retryable: false },
+  'redirected': { origin: 'sdk', terminal: false, retryable: false },
+  'not-connected': { origin: 'sdk', terminal: false, retryable: true },
+  'timeout': { origin: 'sdk', terminal: false, retryable: true },
+  'connect-failed': { origin: 'sdk', terminal: false, retryable: true },
+  'replaced': { origin: 'sdk', terminal: true, retryable: false },
+  'reconnect-gave-up': { origin: 'sdk', terminal: true, retryable: false },
+  'devices-gone': { origin: 'sdk', terminal: false, retryable: false },
+  'unpublished': { origin: 'sdk', terminal: false, retryable: false },
+  'frame-rate-fallback': { origin: 'sdk', terminal: false, retryable: false },
+  'codec-fallback': { origin: 'sdk', terminal: false, retryable: false },
+  'quality-unavailable': { origin: 'sdk', terminal: false, retryable: false },
+  'screen-share-active': { origin: 'sdk', terminal: false, retryable: false },
+  'screen-share-unsupported': { origin: 'sdk', terminal: false, retryable: false },
+  'screen-share-no-video': { origin: 'sdk', terminal: false, retryable: false },
+  'disconnected': { origin: 'sdk', terminal: false, retryable: true },
+  'produce-failed': { origin: 'sdk', terminal: false, retryable: true },
+  'consume-failed': { origin: 'sdk', terminal: false, retryable: true },
+  'media-unavailable': { origin: 'sdk', terminal: false, retryable: false },
+  'music-unavailable': { origin: 'sdk', terminal: false, retryable: false },
+  'no-camera': { origin: 'sdk', terminal: false, retryable: false },
+  'camera-failed': { origin: 'sdk', terminal: false, retryable: true },
+  'unknown-producer': { origin: 'sdk', terminal: false, retryable: false },
+  'screen-share-denied': { origin: 'sdk', terminal: false, retryable: true },
+  'screen-share-service-required': { origin: 'sdk', terminal: false, retryable: false },
+  'screen-share-source-required': { origin: 'sdk', terminal: false, retryable: false },
+  'screen-share-setup-required': { origin: 'sdk', terminal: false, retryable: false },
+  'screen-share-start-timeout': { origin: 'sdk', terminal: false, retryable: true },
+  'screen-share-ended': { origin: 'sdk', terminal: false, retryable: true },
+  'screen-share-failed': { origin: 'sdk', terminal: false, retryable: true },
+  'screen-share-size-unavailable': { origin: 'sdk', terminal: false, retryable: true },
+  'screen-audio-unavailable': { origin: 'sdk', terminal: false, retryable: false },
+  'screen-stop-failed': { origin: 'sdk', terminal: false, retryable: false },
+  'degradation-preference-failed': { origin: 'sdk', terminal: false, retryable: false },
+} as const satisfies Record<string, ErrorInfo>;
+
+/** Every code in the registry. A newer server may still send one this SDK predates. */
+export type ErrorCode = keyof typeof ERROR_CODES;
+
+/** The registry entry for a code, or undefined for one this SDK does not know. */
+export function errorInfo(code: string): ErrorInfo | undefined {
+  return Object.prototype.hasOwnProperty.call(ERROR_CODES, code) ? ERROR_CODES[code as ErrorCode] : undefined;
+}
+
+/**
+ * Whether reconnecting cannot fix a join refused with this code: a room that
+ * has ended is not coming back, and a token that is wrong will be wrong next
+ * time too. Unknown codes are not terminal, so a newer server's code never
+ * stops a reconnect that could succeed.
+ */
+export function isTerminalError(code: string): boolean {
+  return errorInfo(code)?.terminal === true;
+}
+
+/**
+ * An error with a machine-readable code: returned by the server (its code
+ * passed through unchanged, known to this SDK or not) or raised by the SDK
+ * itself with a registry code. `data` is what the server attached so the app
+ * can act on a refusal rather than merely report it: `{ slots }` for
+ * `slot-occupied`, for instance.
+ */
+export class RpcError extends Error {
+  constructor(readonly code: ErrorCode | (string & {}), message: string, readonly data?: unknown) {
+    super(`${code}: ${message}`);
+    this.name = 'RpcError';
+  }
+}