@voltkit-rtc/client 0.6.1 → 0.7.1

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';
+  }
+}