spacetimedb 2.3.0 → 2.4.0

package/src/server/http_handlers.ts

@@ -0,0 +1,413 @@
+import type { Identity } from '../lib/identity';
+import type {
+  HttpMethod,
+  HttpVersion,
+  MethodOrAny,
+} from '../lib/autogen/types';
+import type { UntypedSchemaDef } from '../lib/schema';
+import type { Timestamp } from '../lib/timestamp';
+import type { Uuid } from '../lib/uuid';
+import type { TransactionCtx } from './procedures';
+import type { HttpClient } from './http_internal';
+import type { Random } from './rng';
+import {
+  exportContext,
+  registerExport,
+  type ModuleExport,
+  type SchemaInner,
+} from './schema';
+import {
+  Headers,
+  makeResponse,
+  SyncResponse,
+  textDecoder,
+  textEncoder,
+  type BodyInit,
+  type HeadersInit,
+  type ResponseInit,
+} from './http_shared';
+
+export { Headers };
+export { SyncResponse };
+export type { BodyInit, HeadersInit, ResponseInit };
+export { makeResponse };
+export const httpHandlerFn = Symbol('SpacetimeDB.httpHandlerFn');
+
+export interface RequestInit {
+  body?: BodyInit | null;
+  headers?: HeadersInit;
+  method?: string;
+  version?: HttpVersion;
+}
+
+type RequestInner = {
+  headers: Headers;
+  method: string;
+  uri: string;
+  version: HttpVersion;
+};
+
+type RouteSpec = {
+  handler: HttpHandlerExport<any>;
+  method: MethodOrAny;
+  path: string;
+};
+
+const ACCEPTABLE_ROUTE_PATH_CHARS_HUMAN_DESCRIPTION =
+  'ASCII lowercase letters, digits and `-_~/`';
+
+export const makeRequest = Symbol('makeRequest');
+
+function coerceRequestBody(body?: BodyInit | null): string | Uint8Array | null {
+  if (body == null) {
+    return null;
+  }
+  if (typeof body === 'string') {
+    return body;
+  }
+  return new Uint8Array(body as any);
+}
+
+function requestBodyToBytes(body: string | Uint8Array | null): Uint8Array {
+  if (body == null) {
+    return new Uint8Array();
+  }
+  if (typeof body === 'string') {
+    return textEncoder.encode(body);
+  }
+  return body;
+}
+
+function requestBodyToText(body: string | Uint8Array | null): string {
+  if (body == null) {
+    return '';
+  }
+  if (typeof body === 'string') {
+    return body;
+  }
+  return textDecoder.decode(body);
+}
+
+function characterIsAcceptableForRoutePath(c: string) {
+  return (
+    (c >= 'a' && c <= 'z') ||
+    (c >= '0' && c <= '9') ||
+    c === '-' ||
+    c === '_' ||
+    c === '~' ||
+    c === '/'
+  );
+}
+
+function assertValidPath(path: string) {
+  if (path !== '' && !path.startsWith('/')) {
+    throw new TypeError(`Route paths must start with \`/\`: ${path}`);
+  }
+  if (![...path].every(characterIsAcceptableForRoutePath)) {
+    throw new TypeError(
+      `Route paths may contain only ${ACCEPTABLE_ROUTE_PATH_CHARS_HUMAN_DESCRIPTION}: ${path}`
+    );
+  }
+}
+
+function routesOverlap(a: RouteSpec, b: RouteSpec) {
+  const methodsMatch = (left: HttpMethod, right: HttpMethod) => {
+    if (left.tag !== right.tag) {
+      return false;
+    }
+    if (left.tag === 'Extension' && right.tag === 'Extension') {
+      return left.value === right.value;
+    }
+    return true;
+  };
+
+  return (
+    a.path === b.path &&
+    (a.method.tag === 'Any' ||
+      b.method.tag === 'Any' ||
+      (a.method.tag === 'Method' &&
+        b.method.tag === 'Method' &&
+        methodsMatch(a.method.value, b.method.value)))
+  );
+}
+
+function joinPaths(prefix: string, suffix: string) {
+  if (prefix === '/') {
+    return suffix;
+  }
+  if (suffix === '/') {
+    return prefix;
+  }
+  let prefixEnd = prefix.length;
+  while (prefixEnd > 0 && prefix[prefixEnd - 1] === '/') {
+    prefixEnd--;
+  }
+
+  let suffixStart = 0;
+  while (suffixStart < suffix.length && suffix[suffixStart] === '/') {
+    suffixStart++;
+  }
+
+  const joinedPrefix = prefix.slice(0, prefixEnd);
+  const joinedSuffix = suffix.slice(suffixStart);
+  return `${joinedPrefix}/${joinedSuffix}`;
+}
+
+export class Request {
+  #body: string | Uint8Array | null;
+  #inner: RequestInner;
+
+  constructor(url: URL | string, init: RequestInit = {}) {
+    this.#body = coerceRequestBody(init.body);
+    this.#inner = {
+      headers: new Headers(init.headers as any),
+      method: init.method ?? 'GET',
+      uri: '' + url,
+      version: init.version ?? { tag: 'Http11' },
+    };
+  }
+
+  static [makeRequest](body: BodyInit | null, inner: RequestInner) {
+    const me = new Request(inner.uri);
+    me.#body = coerceRequestBody(body);
+    me.#inner = inner;
+    return me;
+  }
+
+  get headers(): Headers {
+    return this.#inner.headers;
+  }
+
+  get method(): string {
+    return this.#inner.method;
+  }
+
+  get uri(): string {
+    return this.#inner.uri;
+  }
+
+  get url(): string {
+    return this.#inner.uri;
+  }
+
+  get version(): HttpVersion {
+    return this.#inner.version;
+  }
+
+  arrayBuffer(): ArrayBuffer {
+    return this.bytes().buffer as ArrayBuffer;
+  }
+
+  bytes(): Uint8Array {
+    return requestBodyToBytes(this.#body);
+  }
+
+  json(): any {
+    return JSON.parse(this.text());
+  }
+
+  text(): string {
+    return requestBodyToText(this.#body);
+  }
+}
+
+export interface HandlerContext<S extends UntypedSchemaDef = UntypedSchemaDef> {
+  readonly timestamp: Timestamp;
+  readonly http: HttpClient;
+  readonly identity: Identity;
+  readonly random: Random;
+  withTx<T>(body: (ctx: TransactionCtx<S>) => T): T;
+  newUuidV4(): Uuid;
+  newUuidV7(): Uuid;
+}
+
+export type HandlerFn<S extends UntypedSchemaDef = UntypedSchemaDef> = (
+  ctx: HandlerContext<S>,
+  req: Request
+) => SyncResponse;
+
+export interface HttpHandlerExport<
+  S extends UntypedSchemaDef = UntypedSchemaDef,
+> extends ModuleExport {
+  [httpHandlerFn]: HandlerFn<S>;
+}
+
+const exportedHttpHandlerObjects = new WeakSet<object>();
+
+export interface HttpHandlerOpts {
+  name: string;
+}
+
+export class Router {
+  #routes: RouteSpec[];
+
+  constructor(routes: RouteSpec[] = []) {
+    this.#routes = routes;
+  }
+
+  get(path: string, handler: HttpHandlerExport<any>) {
+    return this.addRoute(
+      { tag: 'Method', value: { tag: 'Get' } },
+      path,
+      handler
+    );
+  }
+
+  head(path: string, handler: HttpHandlerExport<any>) {
+    return this.addRoute(
+      { tag: 'Method', value: { tag: 'Head' } },
+      path,
+      handler
+    );
+  }
+
+  options(path: string, handler: HttpHandlerExport<any>) {
+    return this.addRoute(
+      { tag: 'Method', value: { tag: 'Options' } },
+      path,
+      handler
+    );
+  }
+
+  put(path: string, handler: HttpHandlerExport<any>) {
+    return this.addRoute(
+      { tag: 'Method', value: { tag: 'Put' } },
+      path,
+      handler
+    );
+  }
+
+  delete(path: string, handler: HttpHandlerExport<any>) {
+    return this.addRoute(
+      { tag: 'Method', value: { tag: 'Delete' } },
+      path,
+      handler
+    );
+  }
+
+  post(path: string, handler: HttpHandlerExport<any>) {
+    return this.addRoute(
+      { tag: 'Method', value: { tag: 'Post' } },
+      path,
+      handler
+    );
+  }
+
+  patch(path: string, handler: HttpHandlerExport<any>) {
+    return this.addRoute(
+      { tag: 'Method', value: { tag: 'Patch' } },
+      path,
+      handler
+    );
+  }
+
+  any(path: string, handler: HttpHandlerExport<any>) {
+    return this.addRoute({ tag: 'Any' }, path, handler);
+  }
+
+  nest(path: string, subRouter: Router) {
+    assertValidPath(path);
+    if (this.#routes.some(route => route.path.startsWith(path))) {
+      throw new TypeError(
+        `Cannot nest router at \`${path}\`; existing routes overlap with nested path`
+      );
+    }
+    let merged = new Router(this.#routes);
+    for (const route of subRouter.#routes) {
+      merged = merged.addRoute(
+        route.method,
+        joinPaths(path, route.path),
+        route.handler
+      );
+    }
+    return merged;
+  }
+
+  merge(otherRouter: Router) {
+    let merged = new Router(this.#routes);
+    for (const route of otherRouter.#routes) {
+      merged = merged.addRoute(route.method, route.path, route.handler);
+    }
+    return merged;
+  }
+
+  intoRoutes() {
+    return this.#routes.slice();
+  }
+
+  private addRoute(
+    method: MethodOrAny,
+    path: string,
+    handler: HttpHandlerExport<any>
+  ) {
+    assertValidPath(path);
+    const candidate = { method, path, handler };
+    if (this.#routes.some(route => routesOverlap(route, candidate))) {
+      throw new TypeError(`Route conflict for \`${path}\``);
+    }
+    return new Router([...this.#routes, candidate]);
+  }
+}
+
+export function makeHttpHandlerExport<S extends UntypedSchemaDef>(
+  ctx: SchemaInner,
+  opts: HttpHandlerOpts | undefined,
+  fn: HandlerFn<S>
+): HttpHandlerExport<S> {
+  const handlerExport = {
+    [httpHandlerFn]: fn,
+    [exportContext]: ctx,
+    [registerExport](ctx: SchemaInner, exportName: string) {
+      if (exportedHttpHandlerObjects.has(handlerExport)) {
+        throw new TypeError(
+          `HTTP handler '${exportName}' was exported more than once`
+        );
+      }
+      exportedHttpHandlerObjects.add(handlerExport);
+      registerHttpHandler(ctx, exportName, fn, opts);
+      ctx.httpHandlerExports.set(
+        handlerExport as HttpHandlerExport<UntypedSchemaDef>,
+        exportName
+      );
+    },
+  };
+  return handlerExport as HttpHandlerExport<S>;
+}
+
+export function makeHttpRouterExport(
+  ctx: SchemaInner,
+  router: Router
+): ModuleExport {
+  return {
+    [exportContext]: ctx,
+    [registerExport](ctx: SchemaInner) {
+      ctx.pendingHttpRoutes.push(...router.intoRoutes());
+    },
+  };
+}
+
+function registerHttpHandler<S extends UntypedSchemaDef>(
+  ctx: SchemaInner,
+  exportName: string,
+  fn: HandlerFn<S>,
+  opts?: HttpHandlerOpts
+) {
+  ctx.defineHttpHandler(exportName);
+  ctx.moduleDef.httpHandlers.push({ sourceName: exportName });
+
+  if (opts?.name != null) {
+    ctx.moduleDef.explicitNames.entries.push({
+      tag: 'Function',
+      value: {
+        sourceName: exportName,
+        canonicalName: opts.name,
+      },
+    });
+  }
+
+  if (!fn.name) {
+    Object.defineProperty(fn, 'name', { value: exportName, writable: false });
+  }
+
+  ctx.httpHandlers.push(fn as HandlerFn<UntypedSchemaDef>);
+}

package/src/server/http_internal.ts

@@ -1,133 +1,25 @@
-import { Headers, headersToList } from 'headers-polyfill';
-import status from 'statuses';
 import BinaryReader from '../lib/binary_reader';
 import BinaryWriter from '../lib/binary_writer';
-import {
-  HttpHeaders,
-  HttpMethod,
-  HttpRequest,
-  HttpResponse,
-} from '../lib/http_types';
+import status from 'statuses';
+import { HttpRequest, HttpResponse } from '../lib/autogen/types';
 import type { TimeDuration } from '../lib/time_duration';
 import { bsatnBaseSize } from '../lib/util';
+import {
+  type BodyInit,
+  type HeadersInit,
+  deserializeHeaders,
+  Headers,
+  makeResponse,
+  serializeHeaders,
+  serializeMethod,
+  SyncResponse,
+} from './http_shared';
 import { sys } from './runtime';
 
 export { Headers };
 
 const { freeze } = Object;
 
-export type BodyInit = ArrayBuffer | ArrayBufferView | string;
-export type HeadersInit = [string, string][] | Record<string, string> | Headers;
-export interface ResponseInit {
-  headers?: HeadersInit;
-  status?: number;
-  statusText?: string;
-}
-
-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
-interface InnerResponse {
-  type: 'basic' | 'cors' | 'default' | 'error' | 'opaque' | 'opaqueredirect';
-  url: string | null;
-  status: number;
-  statusText: string;
-  headers: Headers;
-  aborted: boolean;
-}
-
-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,
-    };
-  }
-
-  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;
-  }
-
-  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);
-    }
-  }
-}
-
 export interface RequestOptions {
   /** A BodyInit object or null to set request's body. */
   body?: BodyInit | null;
@@ -147,29 +39,9 @@ export interface HttpClient {
 
 const requestBaseSize = bsatnBaseSize({ types: [] }, HttpRequest.algebraicType);
 
-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' }],
-]);
-
 function fetch(url: URL | string, init: RequestOptions = {}) {
-  const method = methods.get(init.method?.toUpperCase() ?? 'GET') ?? {
-    tag: 'Extension',
-    value: init.method!,
-  };
-  const headers: HttpHeaders = {
-    // anys because the typings are wonky - see comment in SyncResponse.constructor
-    entries: headersToList(new Headers(init.headers as any) as any)
-      .flatMap(([k, v]) => (Array.isArray(v) ? v.map(v => [k, v]) : [[k, v]]))
-      .map(([name, value]) => ({ name, value: textEncoder.encode(value) })),
-  };
+  const method = serializeMethod(init.method);
+  const headers = serializeHeaders(new Headers(init.headers as any));
   const uri = '' + url;
   const request: HttpRequest = freeze({
     method,
@@ -198,6 +70,7 @@ function fetch(url: URL | string, init: RequestOptions = {}) {
     statusText: status(response.code),
     headers: deserializeHeaders(response.headers),
     aborted: false,
+    version: response.version,
   });
 }