@ailura/nestjs-hono-adapter 1.0.0

package/src/ws-adapter.ts

@@ -0,0 +1,329 @@
+import type { ServerType } from '@hono/node-server';
+import { createNodeWebSocket } from '@hono/node-ws';
+import type { NodeWebSocket } from '@hono/node-ws';
+import type { WsMessageHandler } from '@nestjs/common';
+import { Logger } from '@nestjs/common';
+import { AbstractWsAdapter } from '@nestjs/websockets';
+import {
+  EMPTY,
+  catchError,
+  filter,
+  first,
+  fromEvent,
+  map,
+  mergeMap,
+  share,
+  takeUntil,
+} from 'rxjs';
+import type { Observable } from 'rxjs';
+
+import type { ServerAdapter } from './server-adapter.ts';
+import {
+  CLOSE_EVENT,
+  HonoSocket,
+  MESSAGE_EVENT,
+  isReply,
+  parseFrame,
+  toReply,
+} from './ws-client.ts';
+import type { WsFrame } from './ws-client.ts';
+import { GatewayServer } from './ws-server.ts';
+
+/** The port a gateway asks for when it keeps the HTTP one. */
+const UNDERLYING_PORT = 0;
+
+/** The path a gateway listens on when it named none. */
+const ROOT_PATH = '/';
+
+/** The event Node reports a protocol upgrade on. */
+const UPGRADE_EVENT = 'upgrade';
+
+/** What Nest passes to `create()` for one gateway. */
+interface HonoGatewayOptions {
+  /** The path the gateway listens on. */
+  readonly path?: string;
+  /** The namespace the gateway asked for. */
+  readonly namespace?: string;
+}
+
+/**
+ * The part of a message event this adapter reads. It is named
+ * here rather than taken from the DOM library, which this
+ * package does not build against.
+ */
+interface WsMessageEvent {
+  /** The frame the socket delivered. */
+  readonly data: unknown;
+}
+
+/** Gives a gateway path the leading slash a route needs. */
+function normalizePath(path?: string): string {
+  if (path === undefined || path === '') {
+    return ROOT_PATH;
+  }
+  if (path.startsWith(ROOT_PATH)) {
+    return path;
+  }
+  return `/${path}`;
+}
+
+/** The handlers of one gateway, by the event each answers. */
+function indexHandlers(
+  handlers: WsMessageHandler[],
+): Map<string, WsMessageHandler> {
+  const byEvent = new Map<string, WsMessageHandler>();
+  for (const handler of handlers) {
+    byEvent.set(handler.message, handler);
+  }
+  return byEvent;
+}
+
+/**
+ * Removes the upgrade listeners `@hono/node-ws` installed on
+ * the server. Node types a listener as `Function`, which `off`
+ * does not accept, so the call goes through `Reflect.apply`,
+ * whose argument list carries no type.
+ */
+function detachUpgradeListeners(
+  server: ServerType,
+  kept: readonly unknown[],
+): void {
+  const off = server.off.bind(server);
+  for (const listener of server.listeners(UPGRADE_EVENT)) {
+    if (!kept.includes(listener)) {
+      Reflect.apply(off, undefined, [UPGRADE_EVENT, listener]);
+    }
+  }
+}
+
+/**
+ * WebSocket adapter that runs Nest's gateways on the Hono
+ * application the HTTP adapter already serves.
+ *
+ * `@hono/node-ws` upgrades a request by asking the Hono
+ * application for the gateway path, so the upgrade happens on
+ * one server rather than on a second one opened beside it. One
+ * route is registered per path a gateway named, and each route
+ * hands Nest a {@link HonoSocket} to answer on.
+ *
+ * A gateway that asked for its own port or for a namespace
+ * cannot be served this way; both are refused rather than
+ * quietly served on the HTTP server.
+ */
+class HonoWsAdapter extends AbstractWsAdapter {
+  private readonly adapter: ServerAdapter;
+  private readonly node: NodeWebSocket;
+  private readonly servers = new Map<string, GatewayServer>();
+  private readonly logger = new Logger(HonoWsAdapter.name);
+  private detach: (() => void) | undefined;
+  private injected = false;
+
+  public constructor(httpAdapter: ServerAdapter) {
+    super(httpAdapter);
+    this.adapter = httpAdapter;
+    this.node = createNodeWebSocket({
+      app: httpAdapter.getHono(),
+    });
+  }
+
+  public override create(
+    port: number,
+    options: HonoGatewayOptions = {},
+  ): GatewayServer {
+    this.ensureSupported(port, options);
+    return this.open(normalizePath(options.path));
+  }
+
+  /**
+   * Bridges the handlers Nest explored for one client onto the
+   * frames that client sends. Every subscription is tied to the
+   * socket's own close event, so a connection that goes away
+   * takes its subscriptions with it.
+   */
+  public override bindMessageHandlers(
+    client: HonoSocket,
+    handlers: WsMessageHandler[],
+    transform: (data: unknown) => Observable<unknown>,
+  ): void {
+    const byEvent = indexHandlers(handlers);
+    const closed = fromEvent(client, CLOSE_EVENT).pipe(
+      share(),
+      first(),
+    );
+    const answers = fromEvent(client, MESSAGE_EVENT).pipe(
+      mergeMap((raw: unknown) =>
+        this.answer(raw, byEvent, transform),
+      ),
+      takeUntil(closed),
+    );
+    answers.subscribe((reply) => {
+      client.sendJson(reply);
+    });
+  }
+
+  public override bindClientDisconnect(
+    client: HonoSocket,
+    callback: () => void,
+  ): void {
+    client.once(CLOSE_EVENT, callback);
+  }
+
+  /** Closes every socket a gateway path is serving. */
+  public override close(server: GatewayServer): Promise<void> {
+    server.close();
+    return Promise.resolve();
+  }
+
+  /**
+   * Releases the paths, the sockets and the WebSocket server
+   * this adapter created, and takes the upgrade listeners back
+   * off the Node server.
+   */
+  public override dispose(): Promise<void> {
+    this.release();
+    return Promise.resolve();
+  }
+
+  /**
+   * Releases the paths, the sockets, the WebSocket server and
+   * the upgrade listeners this adapter registered.
+   */
+  private release(): void {
+    const servers = [...this.servers.values()];
+    this.servers.clear();
+    for (const server of servers) {
+      server.close();
+    }
+    this.node.wss.close();
+    const { detach } = this;
+    if (detach !== undefined) {
+      detach();
+    }
+    this.detach = undefined;
+    this.injected = false;
+  }
+
+  /**
+   * Serves one path, reusing the server already serving it:
+   * Nest asks once per path, and a repeated ask must not
+   * register the route twice.
+   */
+  private open(path: string): GatewayServer {
+    const known = this.servers.get(path);
+    if (known !== undefined) {
+      return known;
+    }
+    const server = new GatewayServer();
+    this.servers.set(path, server);
+    this.serve(path, server);
+    this.inject();
+    return server;
+  }
+
+  /** Registers the upgrade route one gateway path needs. */
+  private serve(path: string, server: GatewayServer): void {
+    const upgrade = this.node.upgradeWebSocket(() => {
+      const client = new HonoSocket();
+      return {
+        onClose: (): void => {
+          client.disconnect();
+        },
+        onMessage: (event: WsMessageEvent): void => {
+          client.deliver(event.data);
+        },
+        onOpen: (_event, socket): void => {
+          client.use(socket);
+          server.accept(client);
+        },
+      };
+    });
+    this.adapter.getHono().get(path, upgrade);
+  }
+
+  /** Lets the Node server hand upgrades to the Hono app. */
+  private inject(): void {
+    if (this.injected) {
+      return;
+    }
+    const server = this.adapter.getHttpServer();
+    const before = server.listeners(UPGRADE_EVENT);
+    this.node.injectWebSocket(server);
+    this.detach = (): void => {
+      detachUpgradeListeners(server, before);
+    };
+    this.injected = true;
+  }
+
+  /** Answers one frame, when a handler claims its event. */
+  private answer(
+    raw: unknown,
+    byEvent: ReadonlyMap<string, WsMessageHandler>,
+    transform: (data: unknown) => Observable<unknown>,
+  ): Observable<unknown> {
+    const frame = parseFrame(raw);
+    if (frame === undefined) {
+      return EMPTY;
+    }
+    const handler = byEvent.get(frame.event);
+    if (handler === undefined) {
+      return EMPTY;
+    }
+    return this.invoke(handler, frame, transform);
+  }
+
+  /** Runs one handler and turns its answer into frames. */
+  private invoke(
+    handler: WsMessageHandler,
+    frame: WsFrame,
+    transform: (data: unknown) => Observable<unknown>,
+  ): Observable<unknown> {
+    try {
+      return this.replies(
+        transform(handler.callback(frame.data)),
+        frame,
+      );
+    } catch (error) {
+      return this.report(error);
+    }
+  }
+
+  /** The frames one handler's stream answers with. */
+  private replies(
+    stream: Observable<unknown>,
+    frame: WsFrame,
+  ): Observable<unknown> {
+    return stream.pipe(
+      map((value) => toReply(frame, value)),
+      filter(isReply),
+      catchError((error: unknown) => this.report(error)),
+    );
+  }
+
+  /** Reports a handler that failed and answers nothing. */
+  private report(error: unknown): Observable<never> {
+    this.logger.error(error);
+    return EMPTY;
+  }
+
+  /** Refuses the gateways this adapter cannot serve. */
+  private ensureSupported(
+    port: number,
+    options: HonoGatewayOptions,
+  ): void {
+    if (port !== UNDERLYING_PORT) {
+      throw new TypeError(
+        'HonoWsAdapter serves every gateway on the HTTP ' +
+          `adapter's server, so the gateway port ${port} ` +
+          'cannot be honoured.',
+      );
+    }
+    if (options.namespace !== undefined) {
+      throw new TypeError(
+        'HonoWsAdapter does not support WebSocket namespaces.',
+      );
+    }
+  }
+}
+
+export { HonoWsAdapter };
+export type { HonoGatewayOptions };

package/src/ws-client.ts

@@ -0,0 +1,190 @@
+import { EventEmitter } from 'node:events';
+
+import type { WSContext } from 'hono/ws';
+
+/** The event a frame from the client arrives on. */
+const MESSAGE_EVENT = 'message';
+
+/** The event that says the socket has gone away. */
+const CLOSE_EVENT = 'close';
+
+/** The state a socket is in once it accepts a send. */
+const OPEN_STATE = 1;
+
+/**
+ * One frame from a client: the event it names, the payload it
+ * carries, and the correlation it asked to have repeated.
+ */
+interface WsFrame {
+  /** The event the gateway answers. */
+  readonly event: string;
+  /** What the handler is given. */
+  readonly data?: unknown;
+  /** The correlation the answer repeats, when there is one. */
+  readonly id?: string | number;
+}
+
+/** What a gateway answers with. */
+interface WsReply {
+  /** The event being answered. */
+  readonly event: string;
+  /** What the handler returned, when it returned anything. */
+  readonly data?: unknown;
+  /** The correlation the client asked to have repeated. */
+  readonly id?: string | number;
+}
+
+/** Says whether a value is a frame, by the event it names. */
+function isFrame(value: unknown): value is WsFrame {
+  if (typeof value !== 'object' || value === null) {
+    return false;
+  }
+  return 'event' in value && typeof value.event === 'string';
+}
+
+/**
+ * Reads the frame a parsed payload carries. A payload that is
+ * only a string names the event and carries no data, which is
+ * how a gateway is called without arguments.
+ */
+function frameFrom(value: unknown): WsFrame | undefined {
+  if (isFrame(value)) {
+    return value;
+  }
+  if (typeof value === 'string') {
+    return { event: value };
+  }
+  return undefined;
+}
+
+/**
+ * Reads a frame from text. Text that is not JSON is taken as
+ * the event name itself, so a client may send `ping` as well as
+ * `{"event":"ping"}`.
+ */
+function parseText(text: string): WsFrame | undefined {
+  try {
+    return frameFrom(JSON.parse(text) as unknown);
+  } catch {
+    return { event: text };
+  }
+}
+
+/**
+ * Reads a frame from what the socket delivered. Text frames
+ * arrive as text, binary frames as bytes, and a socket may hand
+ * over an already parsed frame when one is replayed.
+ */
+function parseFrame(raw: unknown): WsFrame | undefined {
+  if (typeof raw === 'string') {
+    return parseText(raw);
+  }
+  if (raw instanceof Uint8Array) {
+    return parseText(new TextDecoder().decode(raw));
+  }
+  return frameFrom(raw);
+}
+
+/** Repeats the correlation the client asked for, when it did. */
+function withCorrelation(
+  answer: WsReply,
+  frame: WsFrame,
+): WsReply {
+  if (frame.id === undefined) {
+    return answer;
+  }
+  return {
+    data: answer.data,
+    event: answer.event,
+    id: frame.id,
+  };
+}
+
+/**
+ * The frame that answers one, or nothing when the handler
+ * answered with nothing and the client asked for no
+ * acknowledgement.
+ *
+ * A handler that answered with its own `{ event, data }` keeps
+ * that shape, which is what the `ws` platform sends; anything
+ * else is wrapped in the event being answered.
+ */
+function toReply(
+  frame: WsFrame,
+  value: unknown,
+): WsReply | undefined {
+  if (value === undefined || value === null) {
+    if (frame.id === undefined) {
+      return undefined;
+    }
+    return { event: frame.event, id: frame.id };
+  }
+  if (isFrame(value)) {
+    return withCorrelation(value, frame);
+  }
+  const answer: WsReply = { data: value, event: frame.event };
+  return withCorrelation(answer, frame);
+}
+
+/** Says whether an answer is worth sending. */
+function isReply(value: WsReply | undefined): value is WsReply {
+  return value !== undefined;
+}
+
+/**
+ * One client connection, in the shape Nest's WebSocket layer
+ * reads: a `message` event for every frame the client sends, a
+ * `close` event once, and `send()` for the answers. Nest
+ * subscribes with `on` and `once`, so this follows the Node
+ * emitter its own adapters use rather than an `EventTarget`.
+ */
+class HonoSocket extends EventEmitter {
+  private socket: WSContext | undefined;
+
+  /** Binds this client to the socket the upgrade produced. */
+  public use(socket: WSContext): void {
+    this.socket = socket;
+  }
+
+  /** Emits the frame the client sent. */
+  public deliver(data: unknown): void {
+    this.emit(MESSAGE_EVENT, data);
+  }
+
+  /** Says the socket is gone, and only ever once. */
+  public disconnect(): void {
+    this.socket = undefined;
+    this.emit(CLOSE_EVENT);
+  }
+
+  /** Sends one answer, unless the socket is no longer open. */
+  public sendJson(reply: unknown): void {
+    const { socket } = this;
+    if (socket === undefined) {
+      return;
+    }
+    if (socket.readyState !== OPEN_STATE) {
+      return;
+    }
+    socket.send(JSON.stringify(reply));
+  }
+
+  /** Closes the socket from this side. */
+  public close(): void {
+    const { socket } = this;
+    if (socket === undefined) {
+      return;
+    }
+    socket.close();
+  }
+}
+
+export {
+  CLOSE_EVENT,
+  MESSAGE_EVENT,
+  HonoSocket,
+  isReply,
+  parseFrame,
+  toReply,
+};
+export type { WsFrame, WsReply };

package/src/ws-server.ts

@@ -0,0 +1,40 @@
+import { EventEmitter } from 'node:events';
+
+import { CLOSE_EVENT } from './ws-client.ts';
+import type { HonoSocket } from './ws-client.ts';
+
+/** The event Nest listens on for every new socket. */
+const CONNECTION_EVENT = 'connection';
+
+/**
+ * The sockets of one gateway path.
+ *
+ * Nest binds a connection handler to the server `create()`
+ * returns and then, per socket, its message handlers and its
+ * disconnect hook. This is the emitter those bindings need: it
+ * emits `connection` with each socket and holds that socket
+ * until the path is closed, so no listener outlives the
+ * connection it was bound to.
+ */
+class GatewayServer extends EventEmitter {
+  private readonly sockets = new Set<HonoSocket>();
+
+  /** Tracks a socket and hands it to Nest. */
+  public accept(socket: HonoSocket): void {
+    this.sockets.add(socket);
+    socket.once(CLOSE_EVENT, () => {
+      this.sockets.delete(socket);
+    });
+    this.emit(CONNECTION_EVENT, socket);
+  }
+
+  /** Closes every socket on the path. */
+  public close(): void {
+    for (const socket of this.sockets) {
+      socket.close();
+    }
+    this.sockets.clear();
+  }
+}
+
+export { CONNECTION_EVENT, GatewayServer };

package/src/ws.ts

@@ -0,0 +1,13 @@
+/**
+ * The WebSocket entry point, kept out of the root module so a
+ * deployment that only serves HTTP never resolves
+ * `@nestjs/websockets` or `@hono/node-ws`: both are optional
+ * peers, and neither is needed to run the HTTP adapter.
+ *
+ * It is published as the `@ailura/nestjs-hono-adapter/ws`
+ * subpath rather than re-exported from `index.ts`, because an
+ * ESM re-export resolves eagerly and would load them anyway.
+ */
+export { HonoWsAdapter } from './ws-adapter.ts';
+export type { HonoGatewayOptions } from './ws-adapter.ts';
+export type { HonoSocket } from './ws-client.ts';