@ailura/nestjs-hono-adapter 1.0.0

package/src/body.ts

@@ -0,0 +1,251 @@
+import { Buffer } from 'node:buffer';
+
+import {
+  BadRequestException,
+  PayloadTooLargeException,
+} from '@nestjs/common';
+
+import type { NestContext } from './context.ts';
+import { parseQuery } from './query.ts';
+
+/** Methods that never carry a payload. */
+const BODYLESS_METHODS = new Set(['GET', 'HEAD']);
+
+/** The media types that carry a JSON document. */
+const JSON_TYPE = /^application\/(?:.+\+)?json$/u;
+
+/** How a limit may be written, in the notation Nest accepts. */
+const LIMIT =
+  /^\s*(?<amount>\d+(?:\.\d+)?)\s*(?<unit>b|kb|mb|gb|tb|pb)?\s*$/iu;
+
+/** The size a kibibyte stands for, which every unit is built on. */
+const BYTES_PER_KIB = 1024;
+
+const BYTES_PER_MIB = BYTES_PER_KIB * BYTES_PER_KIB;
+const BYTES_PER_GIB = BYTES_PER_MIB * BYTES_PER_KIB;
+const BYTES_PER_TIB = BYTES_PER_GIB * BYTES_PER_KIB;
+const BYTES_PER_PIB = BYTES_PER_TIB * BYTES_PER_KIB;
+
+/** The size each unit of a limit stands for. */
+const UNITS = new Map<string, number>([
+  ['b', 1],
+  ['gb', BYTES_PER_GIB],
+  ['kb', BYTES_PER_KIB],
+  ['mb', BYTES_PER_MIB],
+  ['pb', BYTES_PER_PIB],
+  ['tb', BYTES_PER_TIB],
+]);
+
+/**
+ * A payload as the pipeline reads it: the parsed value, the
+ * uploaded files when the request was multipart, and the bytes
+ * when the application asked to keep them.
+ */
+interface ParsedBody {
+  body: unknown;
+  files: Record<string, unknown> | undefined;
+  rawBody: Buffer | undefined;
+}
+
+interface BodyOptions {
+  readonly bodyLimit: number | undefined;
+  readonly rawBody: boolean;
+}
+
+/** A multipart payload, split into its two halves. */
+interface FormParts {
+  readonly fields: Record<string, unknown>;
+  readonly files: Record<string, unknown>;
+}
+
+/**
+ * Reads a size the way Nest's own parsers do, so a limit such
+ * as `100kb` means the same thing here as it does on Express.
+ */
+function toByteLimit(limit: number | string): number {
+  if (typeof limit === 'number') {
+    return limit;
+  }
+  const match = LIMIT.exec(limit);
+  if (match === null) {
+    throw new TypeError(
+      `The body limit "${limit}" is not a size such as ` +
+        '"100kb" or "1mb".',
+    );
+  }
+  const { amount, unit } = match.groups ?? {};
+  const bytes = Number(amount ?? '');
+  const suffix = (unit ?? 'b').toLowerCase();
+  return Math.floor(bytes * (UNITS.get(suffix) ?? 1));
+}
+
+function mediaType(context: NestContext): string {
+  const header = context.req.header('content-type') ?? '';
+  return (header.split(';')[0] ?? '').trim().toLowerCase();
+}
+
+function assertWithinLength(
+  context: NestContext,
+  limit: number | undefined,
+): void {
+  if (limit === undefined) {
+    return;
+  }
+  const declared = context.req.header('content-length');
+  if (declared === undefined) {
+    return;
+  }
+  const length = Number(declared);
+  if (Number.isFinite(length) && length > limit) {
+    throw new PayloadTooLargeException();
+  }
+}
+
+function assertWithinSize(
+  size: number,
+  limit: number | undefined,
+): void {
+  if (limit !== undefined && size > limit) {
+    throw new PayloadTooLargeException();
+  }
+}
+
+async function readBytes(
+  context: NestContext,
+  limit: number | undefined,
+): Promise<Uint8Array> {
+  const bytes = new Uint8Array(await context.req.arrayBuffer());
+  assertWithinSize(bytes.byteLength, limit);
+  return bytes;
+}
+
+function textOf(bytes: Uint8Array): string {
+  return new TextDecoder('utf-8').decode(bytes);
+}
+
+function parseJson(bytes: Uint8Array): unknown {
+  const text = textOf(bytes).trim();
+  if (text === '') {
+    return {};
+  }
+  try {
+    return JSON.parse(text);
+  } catch {
+    throw new BadRequestException('Malformed request body');
+  }
+}
+
+function parseBytes(bytes: Uint8Array, type: string): unknown {
+  if (JSON_TYPE.test(type)) {
+    return parseJson(bytes);
+  }
+  if (type === 'application/x-www-form-urlencoded') {
+    return parseQuery(textOf(bytes));
+  }
+  if (type.startsWith('text/')) {
+    return textOf(bytes);
+  }
+  if (bytes.byteLength === 0) {
+    return undefined;
+  }
+  return Buffer.from(bytes);
+}
+
+async function readForm(
+  context: NestContext,
+): Promise<Record<string, string | File>> {
+  try {
+    return await context.req.parseBody();
+  } catch {
+    throw new BadRequestException('Malformed request body');
+  }
+}
+
+function splitFields(
+  form: Record<string, string | File>,
+): FormParts {
+  const fields: Record<string, unknown> = {};
+  const files: Record<string, unknown> = {};
+  for (const [name, value] of Object.entries(form)) {
+    if (typeof value === 'string') {
+      fields[name] = value;
+    } else {
+      files[name] = value;
+    }
+  }
+  return { fields, files };
+}
+
+/**
+ * Reads a multipart request into the two halves a controller
+ * expects: the text fields in the body, the uploads in `files`.
+ * The bytes are never buffered, so `rawBody` stays empty.
+ */
+async function readMultipart(
+  context: NestContext,
+): Promise<ParsedBody> {
+  const form = await readForm(context);
+  const parts = splitFields(form);
+  const parsed: ParsedBody = {
+    body: parts.fields,
+    files: undefined,
+    rawBody: undefined,
+  };
+  if (Object.keys(parts.files).length > 0) {
+    parsed.files = parts.files;
+  }
+  return parsed;
+}
+
+function emptyBody(): ParsedBody {
+  return {
+    body: undefined,
+    files: undefined,
+    rawBody: undefined,
+  };
+}
+
+async function readPayload(
+  context: NestContext,
+  type: string,
+  options: BodyOptions,
+): Promise<ParsedBody> {
+  const bytes = await readBytes(context, options.bodyLimit);
+  const parsed: ParsedBody = {
+    body: parseBytes(bytes, type),
+    files: undefined,
+    rawBody: undefined,
+  };
+  if (options.rawBody) {
+    parsed.rawBody = Buffer.from(bytes);
+  }
+  return parsed;
+}
+
+/**
+ * Reads the payload for the pipeline.
+ *
+ * On Express and Fastify Nest installs parser middleware that
+ * fills `req.body` before the pipeline runs. Hono parses on
+ * demand, so the adapter reads the body here and hands it over
+ * in the same place. A payload that does not match its content
+ * type is refused with the exception Nest raises for a failed
+ * parse, so filters and logging see it like any other failure.
+ */
+function readBody(
+  context: NestContext,
+  options: BodyOptions,
+): Promise<ParsedBody> {
+  if (BODYLESS_METHODS.has(context.req.method)) {
+    return Promise.resolve(emptyBody());
+  }
+  const type = mediaType(context);
+  assertWithinLength(context, options.bodyLimit);
+  if (type.startsWith('multipart/form-data')) {
+    return readMultipart(context);
+  }
+  return readPayload(context, type, options);
+}
+
+export { readBody, toByteLimit };
+export type { ParsedBody };

package/src/bridge.ts

@@ -0,0 +1,308 @@
+import type { IncomingMessage } from 'node:http';
+import { Readable } from 'node:stream';
+
+import { HttpStatus, StreamableFile } from '@nestjs/common';
+
+import type { NestContext } from './context.ts';
+import { parseQuery } from './query.ts';
+import type { ParsedQuery } from './query.ts';
+
+const JSON_CONTENT_TYPE = 'application/json; charset=UTF-8';
+const TEXT_CONTENT_TYPE = 'text/plain; charset=UTF-8';
+
+/** The header a proxy sets with the protocol it received. */
+const FORWARDED_PROTO = 'x-forwarded-proto';
+
+/** The header a proxy sets with the host it received. */
+const FORWARDED_HOST = 'x-forwarded-host';
+
+/** The header a proxy sets with the address it received from. */
+const FORWARDED_FOR = 'x-forwarded-for';
+
+/**
+ * The request properties Nest's core reads. Every property is
+ * declared, and the ones that can legitimately be absent are
+ * written as `| undefined`, so `exactOptionalPropertyTypes`
+ * cannot hide a field that was never populated.
+ */
+interface NestRequest {
+  method: string;
+  url: string;
+  originalUrl: string;
+  path: string;
+  hostname: string;
+  protocol: string;
+  secure: boolean;
+  ip: string | undefined;
+  ips: string[];
+  headers: Record<string, string>;
+  query: ParsedQuery;
+  params: Record<string, string>;
+  hosts: Record<string, string>;
+  socket: IncomingMessage['socket'];
+  raw: IncomingMessage;
+  body: unknown;
+  rawBody: Buffer | undefined;
+  session: unknown;
+  files: Record<string, unknown> | undefined;
+}
+
+/**
+ * Continues to whatever handles the request next. The adapter
+ * contract types it as returning `void` while Hono returns a
+ * promise, so it is kept as `unknown` and the result ignored.
+ */
+type NextHandler = () => unknown;
+
+/**
+ * A handler as Nest registers it: the route proxy, a middleware
+ * or the not-found proxy all share this shape.
+ */
+type NestHandler = (
+  request: NestRequest,
+  response: NestContext,
+  next: NextHandler,
+) => unknown;
+
+/** How much of a proxy's word the deployment believes. */
+interface RequestOptions {
+  readonly trustProxy: boolean;
+}
+
+/** What the forwarded headers of one request said. */
+interface Forwarded {
+  readonly addresses: string[];
+  readonly hosts: string[];
+  readonly protocols: string[];
+}
+
+function isPrimitive(
+  body: unknown,
+): body is string | number | boolean | bigint {
+  const kind = typeof body;
+  return (
+    kind === 'string' ||
+    kind === 'number' ||
+    kind === 'boolean' ||
+    kind === 'bigint'
+  );
+}
+
+function isBinaryBody(
+  body: unknown,
+): body is Uint8Array | ArrayBuffer | ReadableStream {
+  return (
+    body instanceof Uint8Array ||
+    body instanceof ArrayBuffer ||
+    body instanceof ReadableStream
+  );
+}
+
+/**
+ * Reads one forwarded header as the list it is: a proxy may
+ * append to it, and the first entry is the one closest to the
+ * client.
+ */
+function forwarded(
+  context: NestContext,
+  name: string,
+): string[] {
+  const header = context.req.header(name);
+  if (header === undefined) {
+    return [];
+  }
+  return header
+    .split(',')
+    .map((value) => value.trim())
+    .filter((value) => value !== '');
+}
+
+/**
+ * Reads a forwarded header only when the deployment says a
+ * proxy sets it: a client that can write it can claim any
+ * address it likes.
+ */
+function trustedValues(
+  context: NestContext,
+  name: string,
+  trustProxy: boolean,
+): string[] {
+  if (!trustProxy) {
+    return [];
+  }
+  return forwarded(context, name);
+}
+
+function forwardedValues(
+  context: NestContext,
+  options: RequestOptions,
+): Forwarded {
+  const { trustProxy } = options;
+  return {
+    addresses: trustedValues(
+      context,
+      FORWARDED_FOR,
+      trustProxy,
+    ),
+    hosts: trustedValues(context, FORWARDED_HOST, trustProxy),
+    protocols: trustedValues(
+      context,
+      FORWARDED_PROTO,
+      trustProxy,
+    ),
+  };
+}
+
+/**
+ * Maps a Hono context onto the request object Nest expects.
+ *
+ * Nest reads the request as a bag of properties rather than
+ * through an interface, so this is the single place where the
+ * Web request is translated into that bag.
+ */
+function toNestRequest(
+  context: NestContext,
+  options: RequestOptions,
+): NestRequest {
+  const target = new URL(context.req.url);
+  const route = `${target.pathname}${target.search}`;
+  const { incoming } = context.env;
+  const values = forwardedValues(context, options);
+  const [forwardedProtocol] = values.protocols;
+  const scheme =
+    forwardedProtocol ?? target.protocol.replace(':', '');
+  const [host] = values.hosts;
+  const [address] = values.addresses;
+  return {
+    body: undefined,
+    files: undefined,
+    headers: context.req.header(),
+    hostname: host ?? target.hostname,
+    hosts: {},
+    ip: address ?? incoming.socket.remoteAddress,
+    ips: values.addresses,
+    method: context.req.method,
+    originalUrl: route,
+    params: context.req.param(),
+    path: target.pathname,
+    protocol: scheme,
+    query: parseQuery(target.search),
+    raw: incoming,
+    rawBody: undefined,
+    secure: scheme === 'https',
+    session: undefined,
+    socket: incoming.socket,
+    url: route,
+  };
+}
+
+function toTextResponse(
+  body: string | number | boolean | bigint,
+  status: number,
+  headers: Headers,
+): Response {
+  if (!headers.has('content-type')) {
+    headers.set('content-type', TEXT_CONTENT_TYPE);
+  }
+  return new Response(String(body), { headers, status });
+}
+
+function toList(
+  value: string | readonly string[],
+): readonly string[] {
+  if (typeof value === 'string') {
+    return [value];
+  }
+  return value;
+}
+
+/**
+ * Writes the disposition a file declares. Nest accepts a list,
+ * which Node treats as one header line per entry, so each entry
+ * is appended rather than overwritten.
+ */
+function setDisposition(
+  headers: Headers,
+  disposition: string | readonly string[],
+): void {
+  for (const value of toList(disposition)) {
+    headers.append('content-disposition', value);
+  }
+}
+
+/**
+ * Streams a file Nest built, keeping the headers it declares.
+ * `StreamableFile` is the one response type that reaches the
+ * adapter as a Node stream, so it is converted here rather than
+ * buffered.
+ */
+function toFileResponse(
+  file: StreamableFile,
+  status: number,
+  headers: Headers,
+): Response {
+  const { type, disposition, length } = file.getHeaders();
+  if (type !== '') {
+    headers.set('content-type', type);
+  }
+  if (disposition !== undefined) {
+    setDisposition(headers, disposition);
+  }
+  if (length !== undefined) {
+    headers.set('content-length', String(length));
+  }
+  return new Response(Readable.toWeb(file.getStream()), {
+    headers,
+    status,
+  });
+}
+
+function toResponse(
+  body: unknown,
+  status: number,
+  headers: Headers,
+): Response {
+  if (body === undefined || body === null) {
+    return new Response(undefined, { headers, status });
+  }
+  if (body instanceof StreamableFile) {
+    return toFileResponse(body, status, headers);
+  }
+  if (isBinaryBody(body)) {
+    return new Response(body, { headers, status });
+  }
+  if (isPrimitive(body)) {
+    return toTextResponse(body, status, headers);
+  }
+  headers.set('content-type', JSON_CONTENT_TYPE);
+  return Response.json(body, { headers, status });
+}
+
+/**
+ * Builds the Web response for a value Nest returned.
+ *
+ * The headers already recorded on the context are copied first:
+ * `@Header()` reaches the adapter through `setHeader()`, which
+ * stores them on the context, and replacing the response would
+ * otherwise drop them.
+ */
+function buildResponse(
+  context: NestContext,
+  body: unknown,
+  status: number = HttpStatus.OK,
+): Response {
+  return toResponse(
+    body,
+    status,
+    new Headers(context.res.headers),
+  );
+}
+
+export {
+  buildResponse,
+  toNestRequest,
+  type NestHandler,
+  type NestRequest,
+  type NextHandler,
+  type RequestOptions,
+};

package/src/closing.ts

@@ -0,0 +1,38 @@
+import { HttpStatus } from '@nestjs/common';
+import type { MiddlewareHandler } from 'hono';
+
+import type { NodeEnv } from './context.ts';
+
+/** The answer Nest's own adapters give while shutting down. */
+const CLOSING_BODY = {
+  message: 'Service Unavailable',
+  statusCode: HttpStatus.SERVICE_UNAVAILABLE,
+} as const;
+
+/** The answer a request that arrives while closing receives. */
+function closingResponse(): Response {
+  return Response.json(CLOSING_BODY, {
+    status: HttpStatus.SERVICE_UNAVAILABLE,
+  });
+}
+
+/**
+ * Answers the requests that arrive while the server is closing.
+ *
+ * A request already in flight has passed this step and is left
+ * to finish; one that arrives afterwards is refused instead of
+ * being accepted and then dropped when the socket goes away.
+ * The step does nothing unless the application asked for it.
+ */
+function closingBridge(
+  isClosing: () => boolean,
+): MiddlewareHandler<NodeEnv> {
+  return (_context, next) => {
+    if (isClosing()) {
+      return Promise.resolve(closingResponse());
+    }
+    return next();
+  };
+}
+
+export { closingBridge };

package/src/context.ts

@@ -0,0 +1,25 @@
+import type { HttpBindings } from '@hono/node-server';
+import type { Context, Hono } from 'hono';
+
+/**
+ * Environment `@hono/node-server` attaches to every request. It
+ * carries the raw Node request and response, which is how the
+ * adapter reaches the client socket without depending on them
+ * anywhere else.
+ */
+interface NodeEnv {
+  Bindings: HttpBindings;
+}
+
+/** The Hono application, typed with its Node bindings. */
+type NestHono = Hono<NodeEnv>;
+
+/**
+ * A Hono context. It doubles as the response object Nest writes
+ * to: keeping the transport in a Web `Response` is what makes
+ * the adapter independent of the platform the request arrived
+ * on.
+ */
+type NestContext = Context<NodeEnv>;
+
+export type { NestContext, NestHono, NodeEnv };