spacetimedb 2.3.0 → 2.4.1

package/src/server/http_shared.ts

@@ -0,0 +1,186 @@
+import { Headers, headersToList } from 'headers-polyfill';
+import type {
+  HttpHeaders,
+  HttpMethod,
+  HttpVersion,
+} from '../lib/autogen/types';
+
+export { Headers };
+
+export type BodyInit = ArrayBuffer | ArrayBufferView | string;
+export type HeadersInit = [string, string][] | Record<string, string> | Headers;
+
+export const textEncoder = new TextEncoder();
+export const textDecoder = new TextDecoder('utf-8');
+
+export function deserializeMethod(method: HttpMethod): string {
+  switch (method.tag) {
+    case 'Get':
+      return 'GET';
+    case 'Head':
+      return 'HEAD';
+    case 'Post':
+      return 'POST';
+    case 'Put':
+      return 'PUT';
+    case 'Delete':
+      return 'DELETE';
+    case 'Connect':
+      return 'CONNECT';
+    case 'Options':
+      return 'OPTIONS';
+    case 'Trace':
+      return 'TRACE';
+    case 'Patch':
+      return 'PATCH';
+    case 'Extension':
+      return method.value;
+  }
+}
+
+const methods = new Map<string, HttpMethod>([
+  ['GET', { tag: 'Get' }],
+  ['HEAD', { tag: 'Head' }],
+  ['POST', { tag: 'Post' }],
+  ['PUT', { tag: 'Put' }],
+  ['DELETE', { tag: 'Delete' }],
+  ['CONNECT', { tag: 'Connect' }],
+  ['OPTIONS', { tag: 'Options' }],
+  ['TRACE', { tag: 'Trace' }],
+  ['PATCH', { tag: 'Patch' }],
+]);
+
+export function serializeMethod(method?: string): HttpMethod {
+  return (
+    methods.get(method?.toUpperCase() ?? 'GET') ?? {
+      tag: 'Extension',
+      value: method!,
+    }
+  );
+}
+
+export function serializeHeaders(headers: Headers): HttpHeaders {
+  return {
+    entries: headersToList(headers as any)
+      .flatMap(([k, v]) => (Array.isArray(v) ? v.map(v => [k, v]) : [[k, v]]))
+      .map(([name, value]) => ({ name, value: textEncoder.encode(value) })),
+  };
+}
+
+export function deserializeHeaders(headers: HttpHeaders): Headers {
+  return new Headers(
+    headers.entries.map(({ name, value }): [string, string] => [
+      name,
+      textDecoder.decode(value),
+    ])
+  );
+}
+
+export interface ResponseInit {
+  headers?: HeadersInit;
+  status?: number;
+  statusText?: string;
+  version?: HttpVersion;
+}
+
+export interface InnerResponse {
+  type: 'basic' | 'cors' | 'default' | 'error' | 'opaque' | 'opaqueredirect';
+  url: string | null;
+  status: number;
+  statusText: string;
+  headers: Headers;
+  aborted: boolean;
+  version: HttpVersion;
+}
+
+export const makeResponse = Symbol('makeResponse');
+
+export class SyncResponse {
+  #body: string | ArrayBuffer | null;
+  #inner: InnerResponse;
+
+  constructor(body?: BodyInit | null, init?: ResponseInit) {
+    if (body == null) {
+      this.#body = null;
+    } else if (typeof body === 'string') {
+      this.#body = body;
+    } else {
+      // this call is fine, the typings are just weird
+      this.#body = new Uint8Array<ArrayBuffer>(body as any).buffer;
+    }
+
+    // there's a type mismatch - headers-polyfill's typing doesn't expect its
+    // own `Headers` type, even though the actual code handles it correctly.
+    this.#inner = {
+      headers: new Headers(init?.headers as any),
+      status: init?.status ?? 200,
+      statusText: init?.statusText ?? '',
+      type: 'default',
+      url: null,
+      aborted: false,
+      version: init?.version ?? { tag: 'Http11' },
+    };
+  }
+
+  static [makeResponse](body: BodyInit | null, inner: InnerResponse) {
+    const me = new SyncResponse(body);
+    me.#inner = inner;
+    return me;
+  }
+
+  get headers(): Headers {
+    return this.#inner.headers;
+  }
+
+  get status(): number {
+    return this.#inner.status;
+  }
+
+  get statusText() {
+    return this.#inner.statusText;
+  }
+
+  get ok(): boolean {
+    return 200 <= this.#inner.status && this.#inner.status <= 299;
+  }
+
+  get url(): string {
+    return this.#inner.url ?? '';
+  }
+
+  get type() {
+    return this.#inner.type;
+  }
+
+  get version(): HttpVersion {
+    return this.#inner.version;
+  }
+
+  arrayBuffer(): ArrayBuffer {
+    return this.bytes().buffer;
+  }
+
+  bytes(): Uint8Array<ArrayBuffer> {
+    if (this.#body == null) {
+      return new Uint8Array();
+    } else if (typeof this.#body === 'string') {
+      return textEncoder.encode(this.#body);
+    } else {
+      return new Uint8Array(this.#body);
+    }
+  }
+
+  json(): any {
+    return JSON.parse(this.text());
+  }
+
+  text(): string {
+    if (this.#body == null) {
+      return '';
+    } else if (typeof this.#body === 'string') {
+      return this.#body;
+    } else {
+      return textDecoder.decode(this.#body);
+    }
+  }
+}

package/src/server/index.ts

@@ -22,5 +22,16 @@ export type { Uuid } from '../lib/uuid';
 export type { Random } from './rng';
 export type { ViewExport, ViewCtx, AnonymousViewCtx } from './views';
 export { Range, type Bound } from './range';
+export {
+  Headers,
+  Request,
+  SyncResponse,
+  Router,
+  type BodyInit,
+  type HeadersInit,
+  type RequestInit,
+  type ResponseInit,
+} from './http';
+export type { HandlerContext, HttpHandlerExport } from './http';
 
 import './polyfills'; // Ensure polyfills are loaded

package/src/server/procedures.ts

@@ -22,7 +22,7 @@ import { Uuid } from '../lib/uuid';
 import { httpClient, type HttpClient } from './http_internal';
 import type { DbView } from './db_view';
 import { makeRandom, type Random } from './rng';
-import { callUserFunction, ReducerCtxImpl, sys } from './runtime';
+import { callUserFunction, ReducerCtxImpl, runWithTx, sys } from './runtime';
 import {
   exportContext,
   registerExport,
@@ -214,38 +214,16 @@ const ProcedureCtxImpl = class ProcedureCtx<S extends UntypedSchemaDef>
   }
 
   withTx<T>(body: (ctx: TransactionCtx<S>) => T): T {
-    const run = () => {
-      const timestamp = sys.procedure_start_mut_tx();
-
-      try {
-        const ctx: TransactionCtx<S> = new TransactionCtxImpl(
+    return runWithTx(
+      timestamp =>
+        new TransactionCtxImpl(
           this.sender,
-          new Timestamp(timestamp),
+          timestamp,
           this.connectionId,
           this.#dbView()
-        );
-        return body(ctx);
-      } catch (e) {
-        sys.procedure_abort_mut_tx();
-        throw e;
-      }
-    };
-
-    let res = run();
-    try {
-      sys.procedure_commit_mut_tx();
-      return res;
-    } catch {
-      // ignore the commit error
-    }
-    console.warn('committing anonymous transaction failed');
-    res = run();
-    try {
-      sys.procedure_commit_mut_tx();
-      return res;
-    } catch (e) {
-      throw new Error('transaction retry failed again', { cause: e });
-    }
+        ) as TransactionCtx<S>,
+      body
+    );
   }
 
   newUuidV4(): Uuid {

package/src/server/runtime.ts

@@ -27,6 +27,18 @@ import {
   type UniqueIndex,
 } from '../lib/indexes';
 import { callProcedure } from './procedures';
+import {
+  type HandlerContext,
+  Request,
+  SyncResponse,
+  makeRequest,
+} from './http_handlers';
+import { httpClient } from './http_internal';
+import {
+  deserializeHeaders,
+  deserializeMethod,
+  serializeHeaders,
+} from './http_shared';
 import {
   type AuthCtx,
   type JsonObject,
@@ -35,7 +47,7 @@ import {
 } from '../lib/reducers';
 import { type UntypedSchemaDef } from '../lib/schema';
 import { type RowType, type Table, type TableMethods } from '../lib/table';
-import { hasOwn } from '../lib/util';
+import { bsatnBaseSize, hasOwn } from '../lib/util';
 import { type AnonymousViewCtx, type ViewCtx } from './views';
 import { isRowTypedQuery, makeQueryBuilder, toSql } from './query';
 import type { DbView } from './db_view';
@@ -43,11 +55,32 @@ import { getErrorConstructor, SenderError } from './errors';
 import { Range, type Bound } from './range';
 import { makeRandom, type Random } from './rng';
 import type { SchemaInner } from './schema';
+import { HttpRequest, HttpResponse } from '../lib/autogen/types';
 
 const { freeze } = Object;
 
 export const sys = { ..._syscalls2_0, ..._syscalls2_1 };
 
+function requestFromWire(request: HttpRequest, body: Uint8Array): Request {
+  return Request[makeRequest](body, {
+    headers: deserializeHeaders(request.headers),
+    method: deserializeMethod(request.method),
+    uri: request.uri,
+    version: request.version,
+  });
+}
+
+function responseIntoWire(response: SyncResponse): [HttpResponse, Uint8Array] {
+  return [
+    {
+      headers: serializeHeaders(response.headers),
+      version: response.version,
+      code: response.status,
+    },
+    response.bytes(),
+  ];
+}
+
 export function parseJsonObject(json: string): JsonObject {
   let value: unknown;
 
@@ -272,6 +305,38 @@ export const callUserFunction = function __spacetimedb_end_short_backtrace<
   return fn(...args);
 };
 
+export function runWithTx<T, Ctx>(
+  makeCtx: (timestamp: Timestamp) => Ctx,
+  body: (ctx: Ctx) => T
+): T {
+  const run = () => {
+    const timestamp = sys.procedure_start_mut_tx();
+
+    try {
+      return body(makeCtx(new Timestamp(timestamp)));
+    } catch (e) {
+      sys.procedure_abort_mut_tx();
+      throw e;
+    }
+  };
+
+  let res = run();
+  try {
+    sys.procedure_commit_mut_tx();
+    return res;
+  } catch {
+    // ignore the commit error
+  }
+  console.warn('committing anonymous transaction failed');
+  res = run();
+  try {
+    sys.procedure_commit_mut_tx();
+    return res;
+  } catch (e) {
+    throw new Error('transaction retry failed again', { cause: e });
+  }
+}
+
 export const makeHooks = (schema: SchemaInner): ModuleHooks =>
   new ModuleHooksImpl(schema);
 
@@ -418,11 +483,82 @@ class ModuleHooksImpl implements ModuleHooks {
       () => this.#dbView
     );
   }
+
+  __call_http_handler__(
+    id: u32,
+    timestamp: bigint,
+    request: Uint8Array,
+    body: Uint8Array
+  ): [response: Uint8Array, body: Uint8Array] {
+    const moduleCtx = this.#schema;
+    const handler = moduleCtx.httpHandlers[id];
+    const ctx = new HandlerContextImpl(
+      new Timestamp(timestamp),
+      () => this.#dbView
+    );
+    const requestMetadata = HttpRequest.deserialize(new BinaryReader(request));
+    const response = callUserFunction(
+      handler,
+      ctx,
+      requestFromWire(requestMetadata, body)
+    );
+    const [responseMetadata, responseBody] = responseIntoWire(response);
+    const responseBuf = new BinaryWriter(
+      bsatnBaseSize(moduleCtx.typespace, HttpResponse.algebraicType)
+    );
+    HttpResponse.serialize(responseBuf, responseMetadata);
+    return [responseBuf.getBuffer(), responseBody];
+  }
 }
 
 const BINARY_WRITER = new BinaryWriter(0);
 const BINARY_READER = new BinaryReader(new Uint8Array());
 
+class HandlerContextImpl<S extends UntypedSchemaDef = UntypedSchemaDef>
+  implements HandlerContext<S>
+{
+  #identity: Identity | undefined;
+  #uuidCounter: { value: number } | undefined;
+  #random: Random | undefined;
+  #dbView: () => DbView<any>;
+
+  readonly http = httpClient;
+
+  constructor(
+    readonly timestamp: Timestamp,
+    dbView: () => DbView<any>
+  ) {
+    this.#dbView = dbView;
+  }
+
+  get identity() {
+    return (this.#identity ??= new Identity(sys.identity()));
+  }
+
+  get random() {
+    return (this.#random ??= makeRandom(this.timestamp));
+  }
+
+  withTx<T>(body: (ctx: any) => T): T {
+    return runWithTx(
+      timestamp =>
+        new ReducerCtxImpl(Identity.zero(), timestamp, null, this.#dbView()),
+      body
+    );
+  }
+
+  newUuidV4(): Uuid {
+    const bytes = this.random.fill(new Uint8Array(16));
+    return Uuid.fromRandomBytesV4(bytes);
+  }
+
+  newUuidV7(): Uuid {
+    const bytes = this.random.fill(new Uint8Array(4));
+    const counter = (this.#uuidCounter ??= { value: 0 });
+    return Uuid.fromCounterV7(counter, this.timestamp, bytes);
+  }
+}
+
 function makeTableView(
   typespace: Typespace,
   table: RawTableDefV10

package/src/server/schema.ts

@@ -1,5 +1,9 @@
 import { moduleHooks, type ModuleDefaultExport } from 'spacetime:sys@2.0';
-import { CaseConversionPolicy, Lifecycle } from '../lib/autogen/types';
+import {
+  CaseConversionPolicy,
+  Lifecycle,
+  type MethodOrAny,
+} from '../lib/autogen/types';
 import {
   type ParamsAsObject,
   type ParamsObj,
@@ -14,6 +18,14 @@ import {
 } from '../lib/schema';
 import type { UntypedTableSchema } from '../lib/table_schema';
 import { ColumnBuilder, TypeBuilder } from '../lib/type_builders';
+import {
+  Router,
+  type HandlerFn,
+  type HttpHandlerExport,
+  type HttpHandlerOpts,
+  makeHttpHandlerExport,
+  makeHttpRouterExport,
+} from './http_handlers';
 import {
   makeProcedureExport,
   type ProcedureExport,
@@ -38,6 +50,7 @@ import {
   type ViewFn,
   type ViewOpts,
   type ViewReturnTypeBuilder,
+  type ValidateViewPrimaryKey,
   type Views,
 } from './views';
 import type { UntypedTableDef } from '../lib/table';
@@ -47,10 +60,12 @@ export class SchemaInner<
 > extends ModuleContext {
   schemaType: S;
   existingFunctions = new Set<string>();
+  existingHttpHandlers = new Set<string>();
   reducers: Reducers = [];
   procedures: Procedures = [];
   views: Views = [];
   anonViews: AnonViews = [];
+  httpHandlers: HandlerFn[] = [];
   /**
    * Maps ReducerExport objects to the name of the reducer.
    * Used for resolving the reducers of scheduled tables.
@@ -60,7 +75,10 @@ export class SchemaInner<
     | ProcedureExport<UntypedSchemaDef, any, any>,
     string
   > = new Map();
+  httpHandlerExports: Map<HttpHandlerExport<UntypedSchemaDef>, string> =
+    new Map();
   pendingSchedules: PendingSchedule[] = [];
+  pendingHttpRoutes: PendingHttpRoute[] = [];
 
   constructor(getSchemaType: (ctx: SchemaInner<S>) => S) {
     super();
@@ -70,12 +88,21 @@ export class SchemaInner<
   defineFunction(name: string) {
     if (this.existingFunctions.has(name)) {
       throw new TypeError(
-        `There is already a reducer or procedure with the name '${name}'`
+        `There is already a reducer, procedure, or view with the name '${name}'`
       );
     }
     this.existingFunctions.add(name);
   }
 
+  defineHttpHandler(name: string) {
+    if (this.existingHttpHandlers.has(name)) {
+      throw new TypeError(
+        `There is already an HTTP handler with the name '${name}'`
+      );
+    }
+    this.existingHttpHandlers.add(name);
+  }
+
   resolveSchedules() {
     for (const { reducer, scheduleAtCol, tableName } of this.pendingSchedules) {
       const functionName = this.functionExports.get(reducer());
@@ -91,9 +118,30 @@ export class SchemaInner<
       });
     }
   }
+
+  resolveHttpRoutes() {
+    for (const route of this.pendingHttpRoutes) {
+      const handlerFunction = this.httpHandlerExports.get(route.handler);
+      if (handlerFunction === undefined) {
+        throw new TypeError(
+          `HTTP route for path '${route.path}' refers to a handler that was not exported.`
+        );
+      }
+      this.moduleDef.httpRoutes.push({
+        handlerFunction,
+        method: route.method,
+        path: route.path,
+      });
+    }
+  }
 }
 
 type PendingSchedule = UntypedTableSchema['schedule'] & { tableName: string };
+type PendingHttpRoute = {
+  handler: HttpHandlerExport<UntypedSchemaDef>;
+  method: MethodOrAny;
+  path: string;
+};
 
 /**
  * The Schema class represents the database schema for a SpacetimeDB application.
@@ -153,6 +201,7 @@ export class Schema<S extends UntypedSchemaDef> implements ModuleDefaultExport {
       moduleExport[registerExport](registeredSchema, name);
     }
     registeredSchema.resolveSchedules();
+    registeredSchema.resolveHttpRoutes();
     return makeHooks(registeredSchema);
   }
 
@@ -347,7 +396,11 @@ export class Schema<S extends UntypedSchemaDef> implements ModuleDefaultExport {
   view<Ret extends ViewReturnTypeBuilder, F extends ViewFn<S, {}, Ret>>(
     opts: ViewOpts,
     ret: Ret,
-    fn: F
+    fn: F,
+    // Compile-time-only guard: this rest parameter is `[]` for valid return
+    // builders, but becomes a required error tuple when a returned row builder
+    // marks more than one column with `.primaryKey()`.
+    ..._: ValidateViewPrimaryKey<Ret>
   ): ViewExport<F> {
     return makeViewExport<S, {}, Ret, F>(this.#ctx, opts, {}, ret, fn);
   }
@@ -380,7 +433,15 @@ export class Schema<S extends UntypedSchemaDef> implements ModuleDefaultExport {
   anonymousView<
     Ret extends ViewReturnTypeBuilder,
     F extends AnonymousViewFn<S, {}, Ret>,
-  >(opts: ViewOpts, ret: Ret, fn: F): ViewExport<F> {
+  >(
+    opts: ViewOpts,
+    ret: Ret,
+    fn: F,
+    // Compile-time-only guard: this rest parameter is `[]` for valid return
+    // builders, but becomes a required error tuple when a returned row builder
+    // marks more than one column with `.primaryKey()`.
+    ..._: ValidateViewPrimaryKey<Ret>
+  ): ViewExport<F> {
     return makeAnonViewExport<S, {}, Ret, F>(this.#ctx, opts, {}, ret, fn);
   }
 
@@ -458,6 +519,27 @@ export class Schema<S extends UntypedSchemaDef> implements ModuleDefaultExport {
     return makeProcedureExport(this.#ctx, opts, params, ret, fn);
   }
 
+  httpHandler(fn: HandlerFn<S>): HttpHandlerExport<S>;
+  httpHandler(opts: HttpHandlerOpts, fn: HandlerFn<S>): HttpHandlerExport<S>;
+  httpHandler(
+    ...args: [HandlerFn<S>] | [HttpHandlerOpts, HandlerFn<S>]
+  ): HttpHandlerExport<S> {
+    let opts: HttpHandlerOpts | undefined, fn: HandlerFn<S>;
+    switch (args.length) {
+      case 1:
+        [fn] = args;
+        break;
+      case 2:
+        [opts, fn] = args;
+        break;
+    }
+    return makeHttpHandlerExport(this.#ctx, opts, fn);
+  }
+
+  httpRouter(router: Router): ModuleExport {
+    return makeHttpRouterExport(this.#ctx, router);
+  }
+
   /**
    * Bundle multiple reducers, procedures, etc into one value to export.
    * The name they will be exported with is their corresponding key in the `exports` argument.

package/src/server/sys.d.ts

@@ -37,6 +37,13 @@ declare module 'spacetime:sys@2.0' {
       timestamp: bigint,
       args: Uint8Array
     ): Uint8Array;
+
+    __call_http_handler__(
+      id: u32,
+      timestamp: bigint,
+      request: Uint8Array,
+      body: Uint8Array
+    ): [response: Uint8Array, body: Uint8Array];
   }
 
   export function register_hooks(hooks: ModuleHooks);

package/src/server/view.test-d.ts

@@ -73,11 +73,33 @@ const spacetime = schema({
 
 const arrayRetValue = t.array(person.rowType);
 const optionalPerson = t.option(person.rowType);
+const multiplePrimaryKeyRows = t.array(
+  t.row('MultiplePrimaryKeyRows', {
+    id: t.u32().primaryKey(),
+    name: t.string().primaryKey(),
+  })
+);
 
 spacetime.anonymousView({ name: 'v1', public: true }, arrayRetValue, ctx => {
   return ctx.from.person.build();
 });
 
+// @ts-expect-error views can have at most one primaryKey column on the returned row type.
+spacetime.anonymousView(
+  { name: 'multiplePrimaryRows', public: true },
+  multiplePrimaryKeyRows,
+  () => []
+);
+
+// @ts-expect-error the same multiple-primary-key check also applies to query-builder views.
+spacetime.anonymousView(
+  { name: 'multiplePrimaryRowsQuery', public: true },
+  multiplePrimaryKeyRows,
+  ctx => {
+    return ctx.from.person;
+  }
+);
+
 spacetime.anonymousView(
   { name: 'optionalPerson', public: true },
   optionalPerson,