@getsoda/core 0.2.2 → 0.3.0

package/src/routing/errors.ts

@@ -3,6 +3,8 @@
  * Errors raised by the route compiler.
  */
 
+import { hideFrameworkFrames } from '../utils/errors.ts'
+
 /**
  * Reason of a `RouteError`.
  *
@@ -26,5 +28,6 @@ export class RouteError extends Error {
     message: string
   ) {
     super(message)
+    hideFrameworkFrames(this)
   }
 }

package/src/testing/index.ts

@@ -0,0 +1,73 @@
+/**
+ * @module
+ * Testing an application over HTTP, as Nest's `Test.createTestingModule()`
+ * with supertest does, on a real Bun server bound to a free port.
+ *
+ * ```ts
+ * import { createTestApp } from '@getsoda/core/testing'
+ *
+ * const app = await createTestApp(AppModule, {
+ *   overrides: [provide(UsersRepository, { useValue: new MemoryUsersRepository() })],
+ * })
+ *
+ * afterAll(() => app.close())
+ *
+ * test('creates a user', async () => {
+ *   const response = await app.request('/users', { method: 'POST', json: { name: 'Bo' } })
+ *
+ *   expect(response.status).toBe(201)
+ * })
+ * ```
+ *
+ * A single service needs no server: `createContainer(Module, { overrides })`.
+ */
+
+import { createApp } from '../app/app.ts'
+import type { App, AppOptions } from '../app/app.ts'
+import type { ModuleImport, Token } from '../di/index.ts'
+
+export interface TestRequestInit extends RequestInit {
+  /** Sent as the JSON body, with `Content-Type: application/json`. */
+  readonly json?: unknown
+}
+
+/** A started application, closed by `close()` or at the end of an `await using` block. */
+export interface TestApp extends AsyncDisposable {
+  readonly app: App
+  /** Where the application listens, on a free port of localhost. */
+  readonly url: URL
+  /** `app.container.get()`: a provider as the root module sees it. */
+  get<T>(token: Token<T>): T
+  /** Sends a request to `path`, relative to the application. */
+  request(path: string, init?: TestRequestInit): Promise<Response>
+  close(): Promise<void>
+}
+
+/**
+ * Creates `root` and serves it on a free port. Options are those of
+ * `createApp`: `overrides` replace providers; the logger is silent unless one is given.
+ */
+export const createTestApp = async (root: ModuleImport, options: AppOptions = {}): Promise<TestApp> => {
+  const app = await createApp(root, { logger: false, ...options })
+  const server = await app.listen({ port: 0, hostname: '127.0.0.1' })
+  const close = () => app.close()
+
+  return {
+    app,
+    url: server.url,
+    get: (token) => app.container.get(token),
+    request: (path, { json, ...init } = {}) => {
+      if (json === undefined) {
+        return fetch(new URL(path, server.url), init)
+      }
+
+      const headers = new Headers(init.headers)
+
+      headers.set('content-type', 'application/json')
+
+      return fetch(new URL(path, server.url), { ...init, headers, body: JSON.stringify(json) })
+    },
+    close,
+    [Symbol.asyncDispose]: close,
+  }
+}

package/src/utils/errors.ts

@@ -0,0 +1,25 @@
+/**
+ * @module
+ * Error utilities.
+ */
+
+import { fileURLToPath } from 'node:url'
+
+/** Where the framework's own files are: `src/` from sources, `dist/` once built. */
+const FRAMEWORK = fileURLToPath(new URL('../', import.meta.url))
+
+/**
+ * Removes the frames of the framework from the stack of an error about the
+ * application's code (a missing provider, an invalid route): the runtime then
+ * points at the application, not at the framework, and the message says the rest.
+ */
+export const hideFrameworkFrames = (error: Error): void => {
+  if (error.stack === undefined) {
+    return
+  }
+
+  error.stack = error.stack
+    .split('\n')
+    .filter((line) => !(line.trimStart().startsWith('at ') && line.includes(FRAMEWORK)))
+    .join('\n')
+}

package/src/utils/object.ts

@@ -12,3 +12,26 @@
  * ```
  */
 export const createNullObject = <T extends object>(): T => Object.create(null) as T
+
+/**
+ * Public method names along the prototype chain, most derived first, without duplicates.
+ */
+export const methodNames = (instance: object): string[] => {
+  const names: string[] = []
+  const seen = new Set<string>(['constructor'])
+
+  for (
+    let prototype: object | null = Object.getPrototypeOf(instance);
+    prototype !== null && prototype !== Object.prototype;
+    prototype = Object.getPrototypeOf(prototype)
+  ) {
+    for (const name of Object.getOwnPropertyNames(prototype)) {
+      if (!seen.has(name)) {
+        seen.add(name)
+        names.push(name)
+      }
+    }
+  }
+
+  return names
+}

package/src/websocket/decorators.ts

@@ -0,0 +1,55 @@
+/**
+ * @module
+ * Decorators of WebSocket gateways, as in `@nestjs/websockets`.
+ */
+
+import type { Constructor } from '../di/index.ts'
+import { ControllerError } from '../http/errors.ts'
+
+const gateways = new WeakMap<Constructor<unknown>, string>()
+const events = new WeakMap<object, string>()
+
+/**
+ * Declares a gateway: WebSocket connections upgraded from `GET path`. List it
+ * in the `controllers` of its module: like a controller, it is an entry point
+ * the framework creates, and its guards run on the handshake.
+ *
+ * ```ts
+ * @WebSocketGateway('/chat')
+ * @UseGuards(JwtGuard)
+ * class ChatGateway {
+ *   @SubscribeMessage('message')
+ *   message(data: unknown, socket: GatewaySocket) {
+ *     return { event: 'message', data }
+ *   }
+ * }
+ * ```
+ */
+export const WebSocketGateway =
+  (path: string) =>
+  (target: Constructor<unknown>, _context: ClassDecoratorContext<Constructor<unknown>>): void => {
+    if (!path.startsWith('/') || /[:*?]/.test(path)) {
+      throw new ControllerError('INVALID_PATH', `@WebSocketGateway('${path}'): a gateway path is static and starts with "/"`)
+    }
+
+    gateways.set(target, path)
+  }
+
+/**
+ * Handles the frames `{ "event": event, "data": ... }` of a gateway. The
+ * method receives `(data, socket)`; what it returns, unless `undefined`, is
+ * sent back as JSON.
+ */
+export const SubscribeMessage =
+  (event: string) =>
+  <This, M extends (this: This, ...args: any[]) => unknown>(method: M, context: ClassMethodDecoratorContext<This, M>): void => {
+    if (context.static || context.private) {
+      throw new ControllerError('INVALID_HANDLER', `@SubscribeMessage('${event}') must decorate a public instance method`)
+    }
+
+    events.set(method, event)
+  }
+
+export const getGatewayPath = (target: Constructor<unknown>): string | undefined => gateways.get(target)
+
+export const getSubscribedEvent = (method: object): string | undefined => events.get(method)

package/src/websocket/gateway.ts

@@ -0,0 +1,213 @@
+/**
+ * @module
+ * Serving a gateway: the handshake goes through the route pipeline (guards
+ * and exception filters of the gateway), then frames are dispatched to its
+ * `@SubscribeMessage()` methods.
+ *
+ * The protocol is the one of Nest's `WsAdapter`: text frames holding
+ * `{ "event": string, "data": any }`. Frames that are not JSON, not such an
+ * object, or name no handled event are dropped silently, as anyone can send
+ * them; errors of the gateway's own code are reported.
+ */
+
+import type { ControllerEntry } from '../di/index.ts'
+import { parseJson } from '../http/body.ts'
+import type { Context, RouteInfo } from '../http/context.ts'
+import { createPipeline } from '../http/pipeline.ts'
+import type { FilterStep, GuardStep } from '../http/pipeline.ts'
+import { methodNames } from '../utils/object.ts'
+import { isThenable } from '../utils/promise.ts'
+import { getSubscribedEvent } from './decorators.ts'
+
+/** What a gateway socket carries. */
+export interface GatewaySocketData {
+  /** Context of the handshake request: what its guards set is read with `context.get(key)`. */
+  readonly context: Context
+  /** @internal */
+  readonly gateway: GatewayRuntime
+}
+
+/** A connection of a gateway: Bun's `ServerWebSocket`, with `subscribe()`, `publish()`... */
+export type GatewaySocket = Bun.ServerWebSocket<GatewaySocketData>
+
+/** `handleConnection(socket)`: called when a client is connected. */
+export interface OnGatewayConnection {
+  handleConnection(socket: GatewaySocket): unknown
+}
+
+/** `handleDisconnect(socket, code, reason)`: called when a connection is closed. */
+export interface OnGatewayDisconnect {
+  handleDisconnect(socket: GatewaySocket, code: number, reason: string): unknown
+}
+
+/** Code of the close frame sent when the application shuts down. */
+const GOING_AWAY = 1001
+
+/** Runs `fn`, reporting a synchronous or asynchronous failure. */
+const settle = (fn: () => unknown, report: (error: unknown) => void, then?: (value: unknown) => void): void => {
+  try {
+    const result = fn()
+
+    if (isThenable(result)) {
+      Promise.resolve(result).then(then, report)
+    } else {
+      then?.(result)
+    }
+  } catch (error) {
+    report(error)
+  }
+}
+
+/** The live part of a gateway: its sockets and handlers. */
+export class GatewayRuntime {
+  readonly #instance: Record<string, unknown>
+  readonly #handlers = new Map<string, (data: unknown, socket: GatewaySocket) => unknown>()
+  readonly #sockets = new Set<GatewaySocket>()
+  readonly #onError: (error: unknown, req: Request) => void
+
+  constructor(instance: object, onError: (error: unknown, req: Request) => void) {
+    this.#instance = instance as Record<string, unknown>
+    this.#onError = onError
+
+    for (const name of methodNames(instance)) {
+      const method = this.#instance[name] as (data: unknown, socket: GatewaySocket) => unknown
+      const event = getSubscribedEvent(method)
+
+      if (event !== undefined) {
+        this.#handlers.set(event, method)
+      }
+    }
+  }
+
+  get events(): readonly string[] {
+    return [...this.#handlers.keys()]
+  }
+
+  open(socket: GatewaySocket): void {
+    this.#sockets.add(socket)
+    this.#call('handleConnection', socket, [socket])
+  }
+
+  message(socket: GatewaySocket, message: string | Buffer): void {
+    const frame = typeof message === 'string' ? parseFrame(message) : undefined
+    const handler = frame === undefined ? undefined : this.#handlers.get(frame.event)
+
+    if (handler === undefined) {
+      return
+    }
+
+    settle(
+      () => handler.call(this.#instance, frame!.data, socket),
+      (error) => this.#onError(error, socket.data.context.req),
+      (result) => {
+        if (result !== undefined) {
+          this.#send(socket, result)
+        }
+      }
+    )
+  }
+
+  close(socket: GatewaySocket, code: number, reason: string): void {
+    this.#sockets.delete(socket)
+    this.#call('handleDisconnect', socket, [socket, code, reason])
+  }
+
+  /** Closes every connection, as the application shuts down. */
+  closeAll(): void {
+    for (const socket of this.#sockets) {
+      socket.close(GOING_AWAY, 'Server shutting down')
+    }
+  }
+
+  #call(hook: string, socket: GatewaySocket, args: readonly unknown[]): void {
+    const fn = this.#instance[hook]
+
+    if (typeof fn === 'function') {
+      settle(
+        () => fn.apply(this.#instance, args),
+        (error) => this.#onError(error, socket.data.context.req)
+      )
+    }
+  }
+
+  #send(socket: GatewaySocket, value: unknown): void {
+    try {
+      // JSON.stringify throws on cycles and bigints: an application error, reported.
+      socket.send(JSON.stringify(value))
+    } catch (error) {
+      this.#onError(error, socket.data.context.req)
+    }
+  }
+}
+
+const parseFrame = (message: string): { event: string; data: unknown } | undefined => {
+  let frame: unknown
+
+  try {
+    frame = parseJson(message)
+  } catch {
+    return undefined
+  }
+
+  if (typeof frame !== 'object' || frame === null || typeof (frame as { event?: unknown }).event !== 'string') {
+    return undefined
+  }
+
+  return frame as { event: string; data: unknown }
+}
+
+/** Bun's handlers for every gateway of a server: each socket knows its gateway. */
+export const websocketHandler: Bun.WebSocketHandler<GatewaySocketData> = {
+  open: (socket) => socket.data.gateway.open(socket),
+  message: (socket, message) => socket.data.gateway.message(socket, message),
+  close: (socket, code, reason) => socket.data.gateway.close(socket, code, reason),
+}
+
+/** Result of the handshake once the connection is upgraded: Bun wants no response then. */
+const UPGRADED = Symbol('upgraded')
+
+export interface GatewayParts {
+  readonly entry: ControllerEntry
+  readonly path: string
+  readonly guards: readonly GuardStep[]
+  readonly filters: readonly FilterStep[]
+  readonly metadata: ReadonlyMap<symbol, unknown>
+  readonly onError: (error: unknown, req: Request) => void
+}
+
+/** A gateway ready to serve: its native route and its runtime. */
+export interface BuiltGateway {
+  readonly path: string
+  readonly runtime: GatewayRuntime
+  /** The native route of the handshake, for `Bun.serve({ routes })`. */
+  readonly handle: (req: Bun.BunRequest, server: Bun.Server<GatewaySocketData>) => Response | undefined | Promise<Response | undefined>
+}
+
+export const buildGateway = (parts: GatewayParts): BuiltGateway => {
+  const runtime = new GatewayRuntime(parts.entry.instance as object, parts.onError)
+  const route: RouteInfo = { controller: parts.entry.controller, handler: 'handshake', method: 'GET', path: parts.path, metadata: parts.metadata }
+  // The pipeline is built once; the server of each request is found here.
+  const servers = new WeakMap<Request, Bun.Server<GatewaySocketData>>()
+  const pipeline = createPipeline({
+    route,
+    guards: parts.guards,
+    interceptors: [],
+    filters: parts.filters,
+    invoke: (ctx) =>
+      servers.get(ctx.req)!.upgrade(ctx.req, { data: { context: ctx, gateway: runtime } })
+        ? UPGRADED
+        : new Response('Expected a WebSocket upgrade', { status: 426, headers: { upgrade: 'websocket' } }),
+    respond: (value) => (value === UPGRADED ? (undefined as unknown as Response) : (value as Response)),
+    onError: parts.onError,
+  })
+
+  return {
+    path: parts.path,
+    runtime,
+    handle: (req, server) => {
+      servers.set(req, server)
+
+      return pipeline(req, {})
+    },
+  }
+}

package/src/websocket/index.ts

@@ -0,0 +1,7 @@
+/**
+ * @module
+ * WebSocket gateways, as in `@nestjs/websockets`.
+ */
+
+export { SubscribeMessage, WebSocketGateway } from './decorators.ts'
+export type { GatewaySocket, GatewaySocketData, OnGatewayConnection, OnGatewayDisconnect } from './gateway.ts'