spacetimedb 2.1.0 → 2.2.0

package/src/sdk/decompress.ts

@@ -1,12 +1,11 @@
 export async function decompress(
-  buffer: Uint8Array,
-  // Leaving it here to expand to brotli when it lands in the browsers and NodeJS
-  type: 'gzip',
+  buffer: Uint8Array<ArrayBuffer>,
+  type: CompressionFormat,
   chunkSize: number = 128 * 1024 // 128KB
 ): Promise<Uint8Array> {
   // Create a single ReadableStream to handle chunks
   let offset = 0;
-  const readableStream = new ReadableStream({
+  const readableStream = new ReadableStream<BufferSource>({
     pull(controller) {
       if (offset < buffer.length) {
         // Slice a chunk of the buffer and enqueue it
@@ -29,24 +28,9 @@ export async function decompress(
   const decompressedStream = readableStream.pipeThrough(decompressionStream);
 
   // Collect the decompressed chunks efficiently
-  const reader = decompressedStream.getReader();
-  const chunks: Uint8Array[] = [];
-  let totalLength = 0;
-  let result: any;
-
-  while (!(result = await reader.read()).done) {
-    chunks.push(result.value);
-    totalLength += result.value.length;
+  const chunks = [];
+  for await (const chunk of decompressedStream) {
+    chunks.push(chunk);
   }
-
-  // Allocate a single Uint8Array for the decompressed data
-  const decompressedArray = new Uint8Array(totalLength);
-  let chunkOffset = 0;
-
-  for (const chunk of chunks) {
-    decompressedArray.set(chunk, chunkOffset);
-    chunkOffset += chunk.length;
-  }
-
-  return decompressedArray;
+  return new Blob(chunks).bytes();
 }

package/src/sdk/table_cache.ts

@@ -66,6 +66,7 @@ export class TableCacheImpl<
   TableName extends TableNamesOf<RemoteModule>,
 > implements ClientTableCoreImplementable<RemoteModule, TableName>
 {
+  private readonly hasPrimaryKey: boolean;
   private rows: Map<
     ComparablePrimitive,
     [RowType<TableDefForTableName<RemoteModule, TableName>>, number]
@@ -83,6 +84,9 @@ export class TableCacheImpl<
     this.tableDef = tableDef;
     this.rows = new Map();
     this.emitter = new EventEmitter();
+    this.hasPrimaryKey = Object.values(this.tableDef.columns).some(
+      col => col.columnMetadata.isPrimaryKey === true
+    );
     // Build index views from the resolved runtime index metadata.
     //
     // We intentionally use `resolvedIndexes` rather than `indexes`:
@@ -281,11 +285,7 @@ export class TableCacheImpl<
       return pendingCallbacks;
     }
 
-    // TODO: performance
-    const hasPrimaryKey = Object.values(this.tableDef.columns).some(
-      col => col.columnMetadata.isPrimaryKey === true
-    );
-    if (hasPrimaryKey) {
+    if (this.hasPrimaryKey) {
       const insertMap = new Map<
         ComparablePrimitive,
         [

package/src/sdk/type_utils.ts

@@ -1,5 +1,6 @@
-import type { InferTypeOfRow } from '.';
+import type { Infer, InferTypeOfRow } from '.';
 import type { Prettify } from '../lib/type_util';
+import type { UntypedProcedureDef } from './procedures';
 import type { UntypedReducerDef } from './reducers';
 
 export type IsEmptyObject<T> = [keyof T] extends [never] ? true : false;
@@ -8,3 +9,11 @@ export type MaybeParams<T> = IsEmptyObject<T> extends true ? [] : [params: T];
 export type ParamsType<R extends UntypedReducerDef> = MaybeParams<
   Prettify<InferTypeOfRow<R['params']>>
 >;
+
+export type ProcedureParamsType<P extends UntypedProcedureDef> = MaybeParams<
+  Prettify<InferTypeOfRow<P['params']>>
+>;
+
+export type ProcedureReturnType<P extends UntypedProcedureDef> = Infer<
+  P['returnType']
+>;

package/src/sdk/websocket_decompress_adapter.ts

@@ -1,17 +1,10 @@
 import { decompress } from './decompress';
-import { resolveWS } from './ws';
+import { openWebSocket, type WebSocketAdapter, type WebSocketArgs } from './ws';
 
-export interface WebsocketAdapter {
-  send(msg: Uint8Array): 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 class WebsocketDecompressAdapter implements WebsocketAdapter {
+export class WebsocketDecompressAdapter implements WebSocketAdapter {
+  get protocol(): string {
+    return this.#ws.protocol;
+  }
   set onclose(handler: (ev: CloseEvent) => void) {
     this.#ws.onclose = handler;
   }
@@ -30,16 +23,17 @@ export class WebsocketDecompressAdapter implements WebsocketAdapter {
 
   #ws: WebSocket;
 
-  async #decompress(buffer: Uint8Array): Promise<Uint8Array> {
+  async #decompress(buffer: Uint8Array<ArrayBuffer>): Promise<Uint8Array> {
     const tag = buffer[0];
     const data = buffer.subarray(1);
     switch (tag) {
       case 0:
         return data;
       case 1:
-        throw new Error(
-          'Brotli Compression not supported. Please use gzip or none compression in withCompression method on DbConnection.'
-        );
+        // Some runtimes support brotli, but it's not yet defined in `lib.dom.d.ts`.
+        // We assert runtime support in `DbConnectionBuilder.withCompression`, so
+        // this cast is safe.
+        return await decompress(data, 'brotli' as CompressionFormat);
       case 2:
         return await decompress(data, 'gzip');
       default:
@@ -49,7 +43,7 @@ export class WebsocketDecompressAdapter implements WebsocketAdapter {
     }
   }
 
-  send(msg: Uint8Array): void {
+  send(msg: Uint8Array<ArrayBuffer>): void {
     this.#ws.send(msg);
   }
 
@@ -58,68 +52,12 @@ export class WebsocketDecompressAdapter implements WebsocketAdapter {
   }
 
   constructor(ws: WebSocket) {
-    ws.binaryType = 'arraybuffer';
-
     this.#ws = ws;
   }
 
-  static async createWebSocketFn({
-    url,
-    nameOrAddress,
-    wsProtocol,
-    authToken,
-    compression,
-    lightMode,
-    confirmedReads,
-  }: {
-    url: URL;
-    wsProtocol: string;
-    nameOrAddress: string;
-    authToken?: string;
-    compression: 'gzip' | 'none';
-    lightMode: boolean;
-    confirmedReads?: boolean;
-  }): Promise<WebsocketDecompressAdapter> {
-    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 = 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 {
-        return Promise.reject(
-          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',
-      compression === 'gzip' ? 'Gzip' : 'None'
-    );
-    if (lightMode) {
-      databaseUrl.searchParams.set('light', 'true');
-    }
-    if (confirmedReads !== undefined) {
-      databaseUrl.searchParams.set('confirmed', confirmedReads.toString());
-    }
-
-    const ws = new WS(databaseUrl.toString(), wsProtocol);
-
-    return new WebsocketDecompressAdapter(ws);
+  static async openWebSocket(
+    args: WebSocketArgs
+  ): Promise<WebsocketDecompressAdapter> {
+    return new WebsocketDecompressAdapter(await openWebSocket(args));
   }
 }

package/src/sdk/websocket_protocols.ts

@@ -0,0 +1,25 @@
+import { stdbLogger } from './logger.ts';
+
+export const V2_WS_PROTOCOL = 'v2.bsatn.spacetimedb';
+export const V3_WS_PROTOCOL = 'v3.bsatn.spacetimedb';
+export const PREFERRED_WS_PROTOCOLS = [V3_WS_PROTOCOL, V2_WS_PROTOCOL] as const;
+
+export type NegotiatedWsProtocol =
+  | typeof V2_WS_PROTOCOL
+  | typeof V3_WS_PROTOCOL;
+
+export function normalizeWsProtocol(protocol: string): NegotiatedWsProtocol {
+  if (protocol === V3_WS_PROTOCOL) {
+    return V3_WS_PROTOCOL;
+  }
+  // We treat an empty negotiated subprotocol as legacy v2 for compatibility.
+  if (protocol === '' || protocol === V2_WS_PROTOCOL) {
+    return V2_WS_PROTOCOL;
+  }
+
+  stdbLogger(
+    'warn',
+    `Unexpected websocket subprotocol "${protocol}", falling back to ${V2_WS_PROTOCOL}.`
+  );
+  return V2_WS_PROTOCOL;
+}

package/src/sdk/websocket_test_adapter.ts

@@ -1,64 +1,100 @@
-import { BinaryReader, BinaryWriter } from '../';
+import BinaryReader from '../lib/binary_reader.ts';
+import BinaryWriter from '../lib/binary_writer.ts';
 import { ClientMessage, ServerMessage } from './client_api/types';
-import type { WebsocketAdapter } from './websocket_decompress_adapter';
+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 {
-  onclose: any;
-  // eslint-disable-next-line @typescript-eslint/no-unsafe-function-type
-  onopen!: () => void;
-  onmessage: any;
-  onerror: any;
+class WebsocketTestAdapter implements WebSocketAdapter {
+  protocol: string = '';
 
-  messageQueue: any[];
+  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;
   }
 
-  send(message: any): void {
-    const parsedMessage = ClientMessage.deserialize(new BinaryReader(message));
-    this.outgoingMessages.push(parsedMessage);
-    // console.ClientMessageSerde.deserialize(message);
-    this.messageQueue.push(message);
+  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 });
+    this.#onclose({
+      code: 1000,
+      reason: 'normal closure',
+      wasClean: true,
+    } as CloseEvent);
   }
 
   acceptConnection(): void {
-    this.onopen();
+    this.#onopen();
   }
 
   sendToClient(message: ServerMessage): void {
     const writer = new BinaryWriter(1024);
     ServerMessage.serialize(writer, message);
-    const rawBytes = writer.getBuffer();
+    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);
-    this.onmessage({ data: rawBytes });
+    const outboundData =
+      this.protocol === V3_WS_PROTOCOL
+        ? encodeServerMessagesV3(writer, [rawBytes]).slice()
+        : rawBytes;
+    this.#onmessage({ data: outboundData });
   }
 
-  async createWebSocketFn(_args: {
-    url: URL;
-    wsProtocol: string;
-    nameOrAddress: string;
-    authToken?: string;
-    compression: 'gzip' | 'none';
-    lightMode: boolean;
-    confirmedReads?: boolean;
-  }): Promise<WebsocketTestAdapter> {
+  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 type { WebsocketTestAdapter };
 export default WebsocketTestAdapter;

package/src/sdk/websocket_v3_frames.ts

@@ -0,0 +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;
+}

package/src/sdk/ws.ts

@@ -1,9 +1,9 @@
 import { stdbLogger } from './logger';
 
-export async function resolveWS(): Promise<typeof WebSocket> {
+async function resolveWS(): Promise<typeof WebSocket> {
   // Browser or Node >= 22 (or any env that exposes global WebSocket)
-  if (typeof (globalThis as any).WebSocket !== 'undefined') {
-    return (globalThis as any).WebSocket as typeof WebSocket;
+  if (typeof WebSocket !== 'undefined') {
+    return WebSocket;
   }
 
   // Node without a global WebSocket: lazily load undici's polyfill.
@@ -25,3 +25,81 @@ export async function resolveWS(): Promise<typeof WebSocket> {
     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;
+}

package/src/server/http_internal.ts

@@ -27,6 +27,15 @@ export interface ResponseInit {
 const textEncoder = new TextEncoder();
 const textDecoder = new TextDecoder('utf-8' /* { fatal: true } */);
 
+function deserializeHeaders(headers: HttpHeaders): Headers {
+  return new Headers(
+    headers.entries.map(({ name, value }): [string, string] => [
+      name,
+      textDecoder.decode(value),
+    ])
+  );
+}
+
 const makeResponse = Symbol('makeResponse');
 
 // based on deno's type of the same name
@@ -187,7 +196,7 @@ function fetch(url: URL | string, init: RequestOptions = {}) {
     url: uri,
     status: response.code,
     statusText: status(response.code),
-    headers: new Headers(),
+    headers: deserializeHeaders(response.headers),
     aborted: false,
   });
 }

package/src/server/index.ts

@@ -8,7 +8,7 @@ export {
 export { CaseConversionPolicy } from '../lib/autogen/types';
 export { table } from '../lib/table';
 export { SenderError, SpacetimeHostError, errors } from './errors';
-export type { Reducer, ReducerCtx } from '../lib/reducers';
+export type { Reducer, ReducerCtx, JwtClaims, AuthCtx } from '../lib/reducers';
 export type { ReducerExport } from './reducers';
 export { type DbView } from './db_view';
 export * from './query';