spacetimedb 2.5.0 → 2.6.0

package/src/sdk/websocket_test_adapter.ts

@@ -1,100 +1,107 @@
-import BinaryReader from '../lib/binary_reader.ts';
-import BinaryWriter from '../lib/binary_writer.ts';
-import { ClientMessage, ServerMessage } from './client_api/types';
-import type { WebSocketAdapter, WebSocketFactory } from './ws';
-import { PREFERRED_WS_PROTOCOLS, V3_WS_PROTOCOL } from './websocket_protocols';
-import {
-  decodeClientMessagesV3,
-  encodeServerMessagesV3,
-} from './websocket_v3_frames.ts';
-
-class WebsocketTestAdapter implements WebSocketAdapter {
-  protocol: string = '';
-
-  messageQueue: Uint8Array<ArrayBuffer>[];
-  outgoingMessages: ClientMessage[];
-  closed: boolean;
-  supportedProtocols: string[];
-
-  #onclose: (ev: CloseEvent) => void = () => {};
-  #onopen: () => void = () => {};
-  #onmessage: (msg: { data: Uint8Array }) => void = () => {};
-
-  constructor() {
-    this.messageQueue = [];
-    this.outgoingMessages = [];
-    this.closed = false;
-    this.supportedProtocols = [...PREFERRED_WS_PROTOCOLS];
-  }
-
-  set onclose(handler: (ev: CloseEvent) => void) {
-    this.#onclose = handler;
-  }
-
-  set onopen(handler: () => void) {
-    this.#onopen = handler;
-  }
-
-  set onmessage(handler: (msg: { data: Uint8Array }) => void) {
-    this.#onmessage = handler;
-  }
-
-  set onerror(_handler: (msg: ErrorEvent) => void) {}
-
-  send(message: Uint8Array<ArrayBuffer>): void {
-    const rawMessage = message.slice();
-    const outgoingMessages =
-      this.protocol === V3_WS_PROTOCOL
-        ? decodeClientMessagesV3(rawMessage)
-        : [rawMessage];
-
-    for (const outgoingMessage of outgoingMessages) {
-      this.outgoingMessages.push(
-        ClientMessage.deserialize(new BinaryReader(outgoingMessage))
-      );
-    }
-    this.messageQueue.push(rawMessage);
-  }
-
-  close(): void {
-    this.closed = true;
-    this.#onclose({
-      code: 1000,
-      reason: 'normal closure',
-      wasClean: true,
-    } as CloseEvent);
-  }
-
-  acceptConnection(): void {
-    this.#onopen();
-  }
-
-  sendToClient(message: ServerMessage): void {
-    const writer = new BinaryWriter(1024);
-    ServerMessage.serialize(writer, message);
-    const rawBytes = writer.getBuffer().slice();
-    // The brotli library's `compress` is somehow broken: it returns `null` for some inputs.
-    // See https://github.com/foliojs/brotli.js/issues/36, which is closed but not actually fixed.
-    // So we send the uncompressed data here, and in `spacetimedb.ts`,
-    // if compression fails, we treat the raw message as having been uncompressed all along.
-    // const data = compress(rawBytes);
-    const outboundData =
-      this.protocol === V3_WS_PROTOCOL
-        ? encodeServerMessagesV3(writer, [rawBytes]).slice()
-        : rawBytes;
-    this.#onmessage({ data: outboundData });
-  }
-
-  openWebSocket: WebSocketFactory = async ({ wsProtocol }) => {
-    const negotiatedProtocol = wsProtocol.find(protocol =>
-      this.supportedProtocols.includes(protocol)
-    );
-    if (!negotiatedProtocol) {
-      throw new Error('No compatible websocket protocol');
-    }
-    this.protocol = negotiatedProtocol;
-    return this;
-  };
-}
-
-export default WebsocketTestAdapter;
+import BinaryReader from '../lib/binary_reader.ts';
+import BinaryWriter from '../lib/binary_writer.ts';
+import { ClientMessage, ServerMessage } from './client_api/types';
+import type { WebSocketAdapter, WebSocketFactory } from './ws';
+import { PREFERRED_WS_PROTOCOLS, V3_WS_PROTOCOL } from './websocket_protocols';
+import {
+  decodeClientMessagesV3,
+  encodeServerMessagesV3,
+} from './websocket_v3_frames.ts';
+
+class WebsocketTestAdapter implements WebSocketAdapter {
+  protocol: string = '';
+
+  messageQueue: Uint8Array<ArrayBuffer>[];
+  outgoingMessages: ClientMessage[];
+  closed: boolean;
+  supportedProtocols: string[];
+
+  #onclose: (ev: CloseEvent) => void = () => {};
+  #onopen: () => void = () => {};
+  #onmessage: (msg: { data: Uint8Array }) => void = () => {};
+  #onerror: (msg: ErrorEvent) => void = () => {};
+
+  constructor() {
+    this.messageQueue = [];
+    this.outgoingMessages = [];
+    this.closed = false;
+    this.supportedProtocols = [...PREFERRED_WS_PROTOCOLS];
+  }
+
+  set onclose(handler: (ev: CloseEvent) => void) {
+    this.#onclose = handler;
+  }
+
+  set onopen(handler: () => void) {
+    this.#onopen = handler;
+  }
+
+  set onmessage(handler: (msg: { data: Uint8Array }) => void) {
+    this.#onmessage = handler;
+  }
+
+  set onerror(handler: (msg: ErrorEvent) => void) {
+    this.#onerror = handler;
+  }
+
+  error(error: Error): void {
+    this.#onerror(error as unknown as ErrorEvent);
+  }
+
+  send(message: Uint8Array<ArrayBuffer>): void {
+    const rawMessage = message.slice();
+    const outgoingMessages =
+      this.protocol === V3_WS_PROTOCOL
+        ? decodeClientMessagesV3(rawMessage)
+        : [rawMessage];
+
+    for (const outgoingMessage of outgoingMessages) {
+      this.outgoingMessages.push(
+        ClientMessage.deserialize(new BinaryReader(outgoingMessage))
+      );
+    }
+    this.messageQueue.push(rawMessage);
+  }
+
+  close(): void {
+    this.closed = true;
+    this.#onclose({
+      code: 1000,
+      reason: 'normal closure',
+      wasClean: true,
+    } as CloseEvent);
+  }
+
+  acceptConnection(): void {
+    this.#onopen();
+  }
+
+  sendToClient(message: ServerMessage): void {
+    const writer = new BinaryWriter(1024);
+    ServerMessage.serialize(writer, message);
+    const rawBytes = writer.getBuffer().slice();
+    // The brotli library's `compress` is somehow broken: it returns `null` for some inputs.
+    // See https://github.com/foliojs/brotli.js/issues/36, which is closed but not actually fixed.
+    // So we send the uncompressed data here, and in `spacetimedb.ts`,
+    // if compression fails, we treat the raw message as having been uncompressed all along.
+    // const data = compress(rawBytes);
+    const outboundData =
+      this.protocol === V3_WS_PROTOCOL
+        ? encodeServerMessagesV3(writer, [rawBytes]).slice()
+        : rawBytes;
+    this.#onmessage({ data: outboundData });
+  }
+
+  openWebSocket: WebSocketFactory = async ({ wsProtocol }) => {
+    const negotiatedProtocol = wsProtocol.find(protocol =>
+      this.supportedProtocols.includes(protocol)
+    );
+    if (!negotiatedProtocol) {
+      throw new Error('No compatible websocket protocol');
+    }
+    this.protocol = negotiatedProtocol;
+    return this;
+  };
+}
+
+export default WebsocketTestAdapter;

package/src/sdk/websocket_v3_frames.ts

@@ -1,126 +1,126 @@
-import BinaryReader from '../lib/binary_reader.ts';
-import BinaryWriter from '../lib/binary_writer.ts';
-import { ClientMessage, ServerMessage } from './client_api/types';
-
-// v3 is only a transport framing convention. The payload is one or more
-// already-encoded v2 websocket messages concatenated back-to-back, so these
-// helpers intentionally operate on raw bytes.
-const EMPTY_V3_PAYLOAD_ERR =
-  'v3 websocket payloads must contain at least one message';
-
-function ensureMessages(messages: readonly Uint8Array[]): void {
-  if (messages.length === 0) {
-    throw new RangeError(EMPTY_V3_PAYLOAD_ERR);
-  }
-}
-
-function ensureMessageCount(
-  messages: readonly Uint8Array[],
-  messageCount: number
-): void {
-  ensureMessages(messages);
-  if (messageCount < 1 || messageCount > messages.length) {
-    throw new RangeError(
-      `v3 websocket payload requested ${messageCount} messages from ${messages.length}`
-    );
-  }
-}
-
-function concatenateMessagesV3(
-  writer: BinaryWriter,
-  messages: readonly Uint8Array<ArrayBuffer>[],
-  messageCount: number = messages.length
-): Uint8Array<ArrayBuffer> {
-  ensureMessageCount(messages, messageCount);
-  writer.clear();
-  for (let i = 0; i < messageCount; i++) {
-    writer.writeBytes(messages[i]!);
-  }
-  return writer.getBuffer();
-}
-
-function splitMessagesV3(
-  reader: BinaryReader,
-  data: Uint8Array<ArrayBuffer>,
-  deserialize: (reader: BinaryReader) => unknown
-): Uint8Array<ArrayBuffer>[] {
-  reader.reset(data);
-  if (reader.remaining === 0) {
-    throw new RangeError(EMPTY_V3_PAYLOAD_ERR);
-  }
-
-  const messages: Uint8Array<ArrayBuffer>[] = [];
-  while (reader.remaining > 0) {
-    const startOffset = reader.offset;
-    deserialize(reader);
-    messages.push(data.subarray(startOffset, reader.offset));
-  }
-
-  return messages;
-}
-
-export function countClientMessagesForV3Frame(
-  messages: readonly Uint8Array<ArrayBuffer>[],
-  maxFrameBytes: number
-): number {
-  ensureMessages(messages);
-
-  const firstMessage = messages[0]!;
-  if (firstMessage.length > maxFrameBytes) {
-    return 1;
-  }
-
-  let count = 1;
-  let frameSize = firstMessage.length;
-  while (count < messages.length) {
-    const nextMessage = messages[count]!;
-    const nextFrameSize = frameSize + nextMessage.length;
-    if (nextFrameSize > maxFrameBytes) {
-      break;
-    }
-    frameSize = nextFrameSize;
-    count += 1;
-  }
-  return count;
-}
-
-export function encodeClientMessagesV3(
-  writer: BinaryWriter,
-  messages: readonly Uint8Array<ArrayBuffer>[],
-  messageCount: number = messages.length
-): Uint8Array<ArrayBuffer> {
-  return concatenateMessagesV3(writer, messages, messageCount);
-}
-
-export function decodeClientMessagesV3(
-  data: Uint8Array<ArrayBuffer>
-): Uint8Array<ArrayBuffer>[] {
-  return splitMessagesV3(new BinaryReader(data), data, reader =>
-    ClientMessage.deserialize(reader)
-  );
-}
-
-export function encodeServerMessagesV3(
-  writer: BinaryWriter,
-  messages: readonly Uint8Array<ArrayBuffer>[]
-): Uint8Array<ArrayBuffer> {
-  return concatenateMessagesV3(writer, messages);
-}
-
-export function forEachServerMessageV3(
-  reader: BinaryReader,
-  data: Uint8Array,
-  visit: (message: ServerMessage) => void
-): number {
-  reader.reset(data);
-  if (reader.remaining === 0) {
-    throw new RangeError(EMPTY_V3_PAYLOAD_ERR);
-  }
-
-  let count = 0;
-  while (reader.remaining > 0) {
-    visit(ServerMessage.deserialize(reader));
-    count += 1;
-  }
-  return count;
-}
+import BinaryReader from '../lib/binary_reader.ts';
+import BinaryWriter from '../lib/binary_writer.ts';
+import { ClientMessage, ServerMessage } from './client_api/types';
+
+// v3 is only a transport framing convention. The payload is one or more
+// already-encoded v2 websocket messages concatenated back-to-back, so these
+// helpers intentionally operate on raw bytes.
+const EMPTY_V3_PAYLOAD_ERR =
+  'v3 websocket payloads must contain at least one message';
+
+function ensureMessages(messages: readonly Uint8Array[]): void {
+  if (messages.length === 0) {
+    throw new RangeError(EMPTY_V3_PAYLOAD_ERR);
+  }
+}
+
+function ensureMessageCount(
+  messages: readonly Uint8Array[],
+  messageCount: number
+): void {
+  ensureMessages(messages);
+  if (messageCount < 1 || messageCount > messages.length) {
+    throw new RangeError(
+      `v3 websocket payload requested ${messageCount} messages from ${messages.length}`
+    );
+  }
+}
+
+function concatenateMessagesV3(
+  writer: BinaryWriter,
+  messages: readonly Uint8Array<ArrayBuffer>[],
+  messageCount: number = messages.length
+): Uint8Array<ArrayBuffer> {
+  ensureMessageCount(messages, messageCount);
+  writer.clear();
+  for (let i = 0; i < messageCount; i++) {
+    writer.writeBytes(messages[i]!);
+  }
+  return writer.getBuffer();
+}
+
+function splitMessagesV3(
+  reader: BinaryReader,
+  data: Uint8Array<ArrayBuffer>,
+  deserialize: (reader: BinaryReader) => unknown
+): Uint8Array<ArrayBuffer>[] {
+  reader.reset(data);
+  if (reader.remaining === 0) {
+    throw new RangeError(EMPTY_V3_PAYLOAD_ERR);
+  }
+
+  const messages: Uint8Array<ArrayBuffer>[] = [];
+  while (reader.remaining > 0) {
+    const startOffset = reader.offset;
+    deserialize(reader);
+    messages.push(data.subarray(startOffset, reader.offset));
+  }
+
+  return messages;
+}
+
+export function countClientMessagesForV3Frame(
+  messages: readonly Uint8Array<ArrayBuffer>[],
+  maxFrameBytes: number
+): number {
+  ensureMessages(messages);
+
+  const firstMessage = messages[0]!;
+  if (firstMessage.length > maxFrameBytes) {
+    return 1;
+  }
+
+  let count = 1;
+  let frameSize = firstMessage.length;
+  while (count < messages.length) {
+    const nextMessage = messages[count]!;
+    const nextFrameSize = frameSize + nextMessage.length;
+    if (nextFrameSize > maxFrameBytes) {
+      break;
+    }
+    frameSize = nextFrameSize;
+    count += 1;
+  }
+  return count;
+}
+
+export function encodeClientMessagesV3(
+  writer: BinaryWriter,
+  messages: readonly Uint8Array<ArrayBuffer>[],
+  messageCount: number = messages.length
+): Uint8Array<ArrayBuffer> {
+  return concatenateMessagesV3(writer, messages, messageCount);
+}
+
+export function decodeClientMessagesV3(
+  data: Uint8Array<ArrayBuffer>
+): Uint8Array<ArrayBuffer>[] {
+  return splitMessagesV3(new BinaryReader(data), data, reader =>
+    ClientMessage.deserialize(reader)
+  );
+}
+
+export function encodeServerMessagesV3(
+  writer: BinaryWriter,
+  messages: readonly Uint8Array<ArrayBuffer>[]
+): Uint8Array<ArrayBuffer> {
+  return concatenateMessagesV3(writer, messages);
+}
+
+export function forEachServerMessageV3(
+  reader: BinaryReader,
+  data: Uint8Array,
+  visit: (message: ServerMessage) => void
+): number {
+  reader.reset(data);
+  if (reader.remaining === 0) {
+    throw new RangeError(EMPTY_V3_PAYLOAD_ERR);
+  }
+
+  let count = 0;
+  while (reader.remaining > 0) {
+    visit(ServerMessage.deserialize(reader));
+    count += 1;
+  }
+  return count;
+}

package/src/sdk/ws.ts

@@ -1,105 +1,105 @@
-import { stdbLogger } from './logger';
-
-async function resolveWS(): Promise<typeof WebSocket> {
-  // Browser or Node >= 22 (or any env that exposes global WebSocket)
-  if (typeof WebSocket !== 'undefined') {
-    return WebSocket;
-  }
-
-  // Node without a global WebSocket: lazily load undici's polyfill.
-  // Use an unstatable dynamic import so bundlers don't prebundle it.
-  const dynamicImport = new Function('m', 'return import(m)') as (
-    m: string
-  ) => Promise<any>;
-
-  try {
-    const { WebSocket: UndiciWS } = await dynamicImport('undici');
-    return UndiciWS as unknown as typeof WebSocket;
-  } catch (err) {
-    stdbLogger(
-      'warn',
-      '[spacetimedb-sdk] No global WebSocket found. ' +
-        'On Node 18–21, please install `undici` (npm install undici) ' +
-        'to enable WebSocket support.'
-    );
-    throw err;
-  }
-}
-
-export interface WebSocketAdapter {
-  readonly protocol: string;
-  send(msg: Uint8Array<ArrayBuffer>): void;
-  close(): void;
-
-  set onclose(handler: (ev: CloseEvent) => void);
-  set onopen(handler: () => void);
-  set onmessage(handler: (msg: { data: Uint8Array }) => void);
-  set onerror(handler: (msg: ErrorEvent) => void);
-}
-
-export interface WebSocketArgs {
-  url: URL;
-  wsProtocol: string[];
-  nameOrAddress: string;
-  authToken?: string;
-  compression: 'gzip' | 'brotli' | 'none';
-  lightMode: boolean;
-  confirmedReads?: boolean;
-}
-export type WebSocketFactory = (
-  args: WebSocketArgs
-) => Promise<WebSocketAdapter>;
-
-/**
- * Open a WebSocket to the database specified by the given `WebSocketArgs`.
- * @returns a WebSocket with `binaryType` set to `arraybuffer`.
- */
-export async function openWebSocket({
-  url,
-  nameOrAddress,
-  wsProtocol,
-  authToken,
-  compression,
-  lightMode,
-  confirmedReads,
-}: WebSocketArgs): Promise<WebSocket> {
-  const headers = new Headers();
-
-  const WS = await resolveWS();
-
-  // We swap our original token to a shorter-lived token
-  // to avoid sending the original via query params.
-  let temporaryAuthToken: string | undefined;
-  if (authToken) {
-    headers.set('Authorization', `Bearer ${authToken}`);
-    const tokenUrl = new URL('v1/identity/websocket-token', url);
-    tokenUrl.protocol = url.protocol === 'wss:' ? 'https:' : 'http:';
-
-    const response = await fetch(tokenUrl, { method: 'POST', headers });
-    if (response.ok) {
-      const { token } = await response.json();
-      temporaryAuthToken = token;
-    } else {
-      throw new Error(`Failed to verify token: ${response.statusText}`);
-    }
-  }
-
-  const databaseUrl = new URL(`v1/database/${nameOrAddress}/subscribe`, url);
-  if (temporaryAuthToken) {
-    databaseUrl.searchParams.set('token', temporaryAuthToken);
-  }
-  databaseUrl.searchParams.set(
-    'compression',
-    { gzip: 'Gzip', brotli: 'Brotli', none: 'None' }[compression] ?? 'None'
-  );
-  if (lightMode) {
-    databaseUrl.searchParams.set('light', 'true');
-  }
-  if (confirmedReads !== undefined) {
-    databaseUrl.searchParams.set('confirmed', confirmedReads.toString());
-  }
-
-  const ws = new WS(databaseUrl.toString(), wsProtocol);
-  ws.binaryType = 'arraybuffer';
-  return ws;
-}
+import { stdbLogger } from './logger';
+
+async function resolveWS(): Promise<typeof WebSocket> {
+  // Browser or Node >= 22 (or any env that exposes global WebSocket)
+  if (typeof WebSocket !== 'undefined') {
+    return WebSocket;
+  }
+
+  // Node without a global WebSocket: lazily load undici's polyfill.
+  // Use an unstatable dynamic import so bundlers don't prebundle it.
+  const dynamicImport = new Function('m', 'return import(m)') as (
+    m: string
+  ) => Promise<any>;
+
+  try {
+    const { WebSocket: UndiciWS } = await dynamicImport('undici');
+    return UndiciWS as unknown as typeof WebSocket;
+  } catch (err) {
+    stdbLogger(
+      'warn',
+      '[spacetimedb-sdk] No global WebSocket found. ' +
+        'On Node 18–21, please install `undici` (npm install undici) ' +
+        'to enable WebSocket support.'
+    );
+    throw err;
+  }
+}
+
+export interface WebSocketAdapter {
+  readonly protocol: string;
+  send(msg: Uint8Array<ArrayBuffer>): void;
+  close(): void;
+
+  set onclose(handler: (ev: CloseEvent) => void);
+  set onopen(handler: () => void);
+  set onmessage(handler: (msg: { data: Uint8Array }) => void);
+  set onerror(handler: (msg: ErrorEvent) => void);
+}
+
+export interface WebSocketArgs {
+  url: URL;
+  wsProtocol: string[];
+  nameOrAddress: string;
+  authToken?: string;
+  compression: 'gzip' | 'brotli' | 'none';
+  lightMode: boolean;
+  confirmedReads?: boolean;
+}
+export type WebSocketFactory = (
+  args: WebSocketArgs
+) => Promise<WebSocketAdapter>;
+
+/**
+ * Open a WebSocket to the database specified by the given `WebSocketArgs`.
+ * @returns a WebSocket with `binaryType` set to `arraybuffer`.
+ */
+export async function openWebSocket({
+  url,
+  nameOrAddress,
+  wsProtocol,
+  authToken,
+  compression,
+  lightMode,
+  confirmedReads,
+}: WebSocketArgs): Promise<WebSocket> {
+  const headers = new Headers();
+
+  const WS = await resolveWS();
+
+  // We swap our original token to a shorter-lived token
+  // to avoid sending the original via query params.
+  let temporaryAuthToken: string | undefined;
+  if (authToken) {
+    headers.set('Authorization', `Bearer ${authToken}`);
+    const tokenUrl = new URL('v1/identity/websocket-token', url);
+    tokenUrl.protocol = url.protocol === 'wss:' ? 'https:' : 'http:';
+
+    const response = await fetch(tokenUrl, { method: 'POST', headers });
+    if (response.ok) {
+      const { token } = await response.json();
+      temporaryAuthToken = token;
+    } else {
+      throw new Error(`Failed to verify token: ${response.statusText}`);
+    }
+  }
+
+  const databaseUrl = new URL(`v1/database/${nameOrAddress}/subscribe`, url);
+  if (temporaryAuthToken) {
+    databaseUrl.searchParams.set('token', temporaryAuthToken);
+  }
+  databaseUrl.searchParams.set(
+    'compression',
+    { gzip: 'Gzip', brotli: 'Brotli', none: 'None' }[compression] ?? 'None'
+  );
+  if (lightMode) {
+    databaseUrl.searchParams.set('light', 'true');
+  }
+  if (confirmedReads !== undefined) {
+    databaseUrl.searchParams.set('confirmed', confirmedReads.toString());
+  }
+
+  const ws = new WS(databaseUrl.toString(), wsProtocol);
+  ws.binaryType = 'arraybuffer';
+  return ws;
+}