@ailura/nestjs-hono-adapter 1.0.0

package/src/hono-lifecycle.ts

@@ -0,0 +1,259 @@
+import { createServer as createHttpsServer } from 'node:https';
+import { promisify } from 'node:util';
+
+import { createAdaptorServer } from '@hono/node-server';
+import type { ServerType } from '@hono/node-server';
+import type { NestApplicationOptions } from '@nestjs/common';
+import { Hono } from 'hono';
+import { secureHeaders } from 'hono/secure-headers';
+
+import { closingBridge } from './closing.ts';
+import type { NestHono, NodeEnv } from './context.ts';
+import { corsBridge } from './cors-middleware.ts';
+import type { CorsOptions } from './cors-middleware.ts';
+import { RouteAdapter } from './route-adapter.ts';
+
+/**
+ * The shutdown options, which Nest 11 does not declare as part
+ * of the application options: `return503OnClosing` was added in
+ * Nest 12, so it is read through a type that names it and stays
+ * optional for both.
+ */
+type ClosingOptions = NestApplicationOptions & {
+  readonly return503OnClosing?: boolean;
+};
+
+/** The size a request body may reach before it is refused. */
+const DEFAULT_BODY_LIMIT = 1_048_576;
+
+/** The security headers Hono is configured with. */
+type SecureHeadersOptions = NonNullable<
+  Parameters<typeof secureHeaders>[0]
+>;
+
+/** What `@hono/node-server` accepts to build the Node server. */
+type AdaptorOptions = Parameters<typeof createAdaptorServer>[0];
+
+/** The transport options the lifecycle reads. */
+interface TransportOptions {
+  /** Largest body accepted, in bytes; `0` accepts any size. */
+  readonly bodyLimit?: number;
+  /** Whether `req.rawBody` keeps the bytes of every body. */
+  readonly rawBody?: boolean;
+  /** The security headers to send, or `false` to send none. */
+  readonly secureHeaders?: boolean | SecureHeadersOptions;
+  /** Whether `X-Forwarded-*` headers come from a proxy. */
+  readonly trustProxy?: boolean;
+}
+
+/** Destroys the connections a server is still holding open. */
+function closeConnections(server: ServerType): void {
+  if ('closeAllConnections' in server) {
+    server.closeAllConnections();
+  }
+}
+
+/** Says whether a close failure only means the server never ran. */
+function isNotRunning(error: unknown): boolean {
+  return (
+    typeof error === 'object' &&
+    error !== null &&
+    'code' in error &&
+    error.code === 'ERR_SERVER_NOT_RUNNING'
+  );
+}
+
+/**
+ * Runs Nest on Hono: this owns the Hono application, the
+ * middleware every request passes through, and the Node server
+ * the fetch handler is served on. The routes Nest registers and
+ * the answers it writes are the business of the class below.
+ *
+ * The transport options Nest passes in are honoured: requests
+ * are served over TLS when `httpsOptions` is set, connections
+ * are dropped on shutdown when `forceCloseConnections` is set,
+ * and a request that arrives while the application is closing
+ * is answered with `503` when `return503OnClosing` is set.
+ */
+abstract class HonoLifecycle extends RouteAdapter {
+  protected readonly hono: NestHono;
+  protected readonly trustProxy: boolean;
+  protected bodyLimit: number;
+  protected bodyParsingEnabled = false;
+  protected rawBodyEnabled: boolean;
+  protected corsOptions: CorsOptions | undefined;
+  private closing = false;
+  private forceCloseConnections = false;
+  private return503OnClosing = false;
+
+  protected constructor(options: TransportOptions = {}) {
+    const hono = new Hono<NodeEnv>();
+    super(hono);
+    this.hono = hono;
+    this.bodyLimit = options.bodyLimit ?? DEFAULT_BODY_LIMIT;
+    this.rawBodyEnabled = options.rawBody ?? false;
+    this.trustProxy = options.trustProxy ?? false;
+    this.installSecurityHeaders(options.secureHeaders ?? true);
+    // CORS runs first, so a 503 sent while closing is readable.
+    hono.use(
+      '*',
+      corsBridge(() => this.corsOptions),
+    );
+    hono.use(
+      '*',
+      closingBridge(
+        () => this.return503OnClosing && this.closing,
+      ),
+    );
+  }
+
+  /**
+   * Identifier ecosystem packages branch on. It is the only
+   * value Nest itself does not consume.
+   */
+  public override getType(): string {
+    return 'hono';
+  }
+
+  /**
+   * The Hono application behind the adapter, for the middleware
+   * and routes only Hono knows how to express. Registering on
+   * it before the application listens puts them ahead of Nest's
+   * routes, after the headers and CORS this adapter installs.
+   */
+  public getHono(): NestHono {
+    return this.hono;
+  }
+
+  /**
+   * Says that a Hono router scores its routes rather than
+   * matching them in the order they were added, so two routes
+   * cannot shadow each other and Nest does not have to sort
+   * them.
+   */
+  public isRouteOrderSensitive(): boolean {
+    return false;
+  }
+
+  /** Reads the shutdown options Nest hands the adapter. */
+  private readShutdownOptions(
+    options: NestApplicationOptions,
+  ): void {
+    const closing: ClosingOptions = options;
+    this.forceCloseConnections =
+      options.forceCloseConnections ?? false;
+    this.return503OnClosing =
+      closing.return503OnClosing ?? false;
+  }
+
+  /**
+   * Creates the Node server Hono's fetch handler is served
+   * through. Hono has no listener of its own, so `listen()` and
+   * `close()` operate on the value built here.
+   */
+  public override initHttpServer(
+    options: NestApplicationOptions,
+  ): void {
+    this.readShutdownOptions(options);
+    if (options.rawBody === true) {
+      this.rawBodyEnabled = true;
+    }
+    const certificate = options.httpsOptions;
+    if (certificate === undefined) {
+      this.setHttpServer(
+        createAdaptorServer({ fetch: this.hono.fetch }),
+      );
+      return;
+    }
+    const adaptorOptions: AdaptorOptions = {
+      createServer: createHttpsServer,
+      fetch: this.hono.fetch,
+      serverOptions: certificate,
+    };
+    this.setHttpServer(createAdaptorServer(adaptorOptions));
+  }
+
+  public override listen(
+    port: string | number,
+    callback?: () => void,
+  ): void;
+  public override listen(
+    port: string | number,
+    hostname: string,
+    callback?: () => void,
+  ): void;
+  public override listen(
+    port: string | number,
+    hostnameOrCallback?: string | (() => void),
+    callback?: () => void,
+  ): void {
+    if (typeof port === 'string') {
+      this.httpServer.listen(port, callback);
+      return;
+    }
+    if (typeof hostnameOrCallback === 'function') {
+      this.httpServer.listen(port, hostnameOrCallback);
+      return;
+    }
+    if (typeof hostnameOrCallback === 'string') {
+      this.httpServer.listen(
+        port,
+        hostnameOrCallback,
+        callback,
+      );
+      return;
+    }
+    this.httpServer.listen(port, callback);
+  }
+
+  /**
+   * Stops the server and, when the application asked for it,
+   * the connections it is still holding open. A server that
+   * never started listening has nothing to close, so the error
+   * it reports then is not a failure worth propagating.
+   */
+  public override async close(): Promise<void> {
+    this.closing = true;
+    const { httpServer } = this;
+    if (this.forceCloseConnections) {
+      closeConnections(httpServer);
+    }
+    try {
+      await promisify((done: () => void) => {
+        httpServer.close(done);
+      })();
+    } catch (error) {
+      if (!isNotRunning(error)) {
+        throw error;
+      }
+    }
+  }
+
+  /** Records that the payload's bytes have to be kept. */
+  protected keepRawBody(rawBody?: boolean): void {
+    if (rawBody === true) {
+      this.rawBodyEnabled = true;
+    }
+  }
+
+  /**
+   * Installs the security headers Hono sends with every answer,
+   * unless the deployment turned them off. They come from Hono
+   * rather than from Helmet, which is Express middleware: the
+   * families of headers are the same.
+   */
+  private installSecurityHeaders(
+    headers: boolean | SecureHeadersOptions,
+  ): void {
+    if (headers === true) {
+      this.hono.use('*', secureHeaders());
+      return;
+    }
+    if (headers !== false) {
+      this.hono.use('*', secureHeaders(headers));
+    }
+  }
+}
+
+export { HonoLifecycle };
+export type { TransportOptions };

package/src/index.ts

@@ -0,0 +1,27 @@
+/**
+ * The public surface of the adapter: the class a bootstrap
+ * hands to `NestFactory.create`, the options it and
+ * `enableCors` accept, and the types a handler or a middleware
+ * needs to describe what it touches.
+ */
+export { ServerAdapter } from './server-adapter.ts';
+export type { ParsedBody } from './body.ts';
+export type {
+  NestHandler,
+  NestRequest,
+  NextHandler,
+} from './bridge.ts';
+export type {
+  NestContext,
+  NestHono,
+  NodeEnv,
+} from './context.ts';
+export type { CorsOptions } from './cors-middleware.ts';
+export type { ParsedQuery } from './query.ts';
+export type { StaticAssetsOptions } from './static-assets.ts';
+export type {
+  ViewData,
+  ViewEngine,
+  ViewOptions,
+} from './views.ts';
+export type { ServerAdapterOptions } from './server-adapter.ts';

package/src/path.ts

@@ -0,0 +1,169 @@
+/**
+ * A parameter name, which both dialects write the same way. The
+ * whole match is the name, so the expression captures nothing.
+ */
+const PARAMETER = /^[A-Za-z0-9_]+/u;
+
+/** The name of a wildcard, which the v8 syntax spells `*rest`. */
+const WILDCARD = /^[A-Za-z0-9_]+/u;
+
+/** An optional segment, which the v8 syntax spells `{/:id}`. */
+const OPTIONAL_SEGMENT =
+  /^:(?<name>[A-Za-z0-9_]+)(?:\((?<constraint>[^()]*)\))?\??$/u;
+
+/** The characters this translator has no meaning for. */
+const REFUSED = new Set(['}', '(', ')']);
+
+const MISSING = -1;
+
+function unsupported(path: string): TypeError {
+  return new TypeError(
+    `The route path "${path}" is not one the Hono adapter ` +
+      'can translate. Write it the way Hono reads it: ' +
+      '`:name`, `:name?`, `:name{regex}`, `{/:name}` or `*`.',
+  );
+}
+
+function withoutLeadingSlash(content: string): string {
+  if (content.startsWith('/')) {
+    return content.slice(1);
+  }
+  return content;
+}
+
+/**
+ * Translates one optional segment. Hono can only make a single
+ * parameter optional, so a group that holds a literal or more
+ * than one segment is refused instead of quietly ignored.
+ */
+function translateGroup(content: string, path: string): string {
+  const match = OPTIONAL_SEGMENT.exec(
+    withoutLeadingSlash(content),
+  );
+  if (match === null) {
+    throw unsupported(path);
+  }
+  const { constraint, name } = match.groups ?? {
+    constraint: undefined,
+    name: '',
+  };
+  if (constraint === undefined) {
+    return `/:${name}?`;
+  }
+  return `/:${name}{${constraint}}?`;
+}
+
+/**
+ * Rewrites one route path into the dialect Hono's router reads.
+ *
+ * The two differ in three places: a constraint is written
+ * `:id(\\d+)` rather than `:id{\\d+}`, an optional segment is
+ * written `{/:id}` rather than `/:id?`, and a named wildcard is
+ * written `*rest` rather than `*`. Anything else is refused
+ * with the path that caused it, because a route that is
+ * registered but never matches is worse than one that fails at
+ * startup.
+ */
+class PathTranslator {
+  private index = 0;
+  private translated = '';
+  private readonly path: string;
+
+  public constructor(path: string) {
+    this.path = path;
+  }
+
+  public translate(): string {
+    while (this.index < this.path.length) {
+      this.step();
+    }
+    return this.translated;
+  }
+
+  private step(): void {
+    const character = this.path.charAt(this.index);
+    if (REFUSED.has(character)) {
+      throw unsupported(this.path);
+    }
+    if (this.readSpecial(character)) {
+      return;
+    }
+    this.emit(character);
+    this.index += 1;
+  }
+
+  /** Copies a character, or handles the ones that mean more. */
+  private readSpecial(character: string): boolean {
+    if (character === '{') {
+      this.readGroup();
+    } else if (character === ':') {
+      this.readParameter();
+    } else if (character === '*') {
+      this.readWildcard();
+    } else {
+      return false;
+    }
+    return true;
+  }
+
+  private emit(text: string): void {
+    this.translated += text;
+  }
+
+  private readGroup(): void {
+    const end = this.path.indexOf('}', this.index);
+    if (end === MISSING) {
+      throw unsupported(this.path);
+    }
+    const content = this.path.slice(this.index + 1, end);
+    this.emit(translateGroup(content, this.path));
+    this.index = end + 1;
+  }
+
+  private readParameter(): void {
+    const match = PARAMETER.exec(
+      this.path.slice(this.index + 1),
+    );
+    if (match === null) {
+      this.emit(':');
+      this.index += 1;
+      return;
+    }
+    const [name] = match;
+    this.index += name.length + 1;
+    this.closeParameter(name);
+  }
+
+  private closeParameter(name: string): void {
+    if (this.path.charAt(this.index) !== '(') {
+      this.emit(`:${name}`);
+      return;
+    }
+    const end = this.path.indexOf(')', this.index);
+    if (end === MISSING) {
+      throw unsupported(this.path);
+    }
+    const constraint = this.path.slice(this.index + 1, end);
+    this.emit(`:${name}{${constraint}}`);
+    this.index = end + 1;
+  }
+
+  private readWildcard(): void {
+    const match = WILDCARD.exec(
+      this.path.slice(this.index + 1),
+    );
+    this.emit('*');
+    if (match === null) {
+      this.index += 1;
+      return;
+    }
+    const [name] = match;
+    this.index += name.length + 1;
+  }
+}
+
+function toHonoPath(path: string): string {
+  return new PathTranslator(path).translate();
+}
+
+export { toHonoPath };