@asenajs/hono-adapter 1.7.0 → 3.0.0

package/README.md

@@ -1,5 +1,8 @@
 # Asena Hono Adapter
 
+[![Version](https://img.shields.io/badge/version-3.0.0-blue.svg)](https://github.com/AsenaJs/hono-adapter)
+[![Bun Version](https://img.shields.io/badge/Bun-1.3.12%2B-blueviolet)](https://bun.sh)
+
 HTTP and WebSocket adapter implementation based on Hono web framework for Asena.js.
 
 ## Features
@@ -15,15 +18,28 @@ HTTP and WebSocket adapter implementation based on Hono web framework for Asena.
 ## Requirements
 
 - [Bun](https://bun.sh) v1.3.12 or higher
+- [@asenajs/asena](https://github.com/AsenaJs/Asena) v0.10.0 or higher (peer dependency)
+- [Hono](https://hono.dev) v4.12.9 or higher (peer dependency)
+- [Zod](https://zod.dev) v4.3.6 or higher (peer dependency)
 - TypeScript v5.8.2 or above
 
 ## Installation
 
-1. Install with NPM package manager:
 ```bash
-bun add @asenajs/hono-adapter
+bun add @asenajs/hono-adapter hono zod
 ```
 
+`hono` and `zod` are **peer dependencies** - this adapter offers the wrapper, your project owns the
+libraries it wraps. That is what keeps your code and the adapter on a single copy of `hono`; two
+copies mean two `HTTPException` classes, and a deliberate 403 thrown from the wrong one is answered
+500.
+
+| Package manager | Command |
+|:--|:--|
+| bun, npm 7+, pnpm 8+ | `bun add hono zod` — peers auto-install, but declare them anyway so they survive a clean install |
+| yarn 1 | `yarn add hono zod` — **required**, yarn 1 does not install peers for you |
+
+
 ## Usage
 
 ### Server Setup (index.ts)
@@ -112,7 +128,11 @@ describe("YourController", () => {
   let baseUrl;
   
   beforeEach(async () => {
-    const port = Math.floor(Math.random() * 55000) + 10000;
+    // 10000-31999: below the kernel's ephemeral floor (net.ipv4.ip_local_port_range,
+    // 32768-60999). A server port drawn from that range collides with the outbound
+    // sockets the suite itself holds open - TIME_WAIT included - and Bun.serve then
+    // fails with EADDRINUSE, randomly, in whichever test happened to draw it.
+    const port = 10000 + Math.floor(Math.random() * 22000);
     const [adapter, logger] = createHonoAdapter(new DefaultLogger());
     const app = new AsenaServer(adapter).logger(logger).port(port);
     

package/dist/index.d.ts

@@ -4,4 +4,19 @@ export * from './lib/types';
 export * from './lib/defaults';
 export * from './lib/utils/createHonoAdapter';
 export * from './lib/errors';
+/**
+ * Hono's own `HTTPException`, re-exported so applications and middlewares stay on the copy of
+ * `hono` this adapter resolved - importing it from `hono/http-exception` directly is what lets a
+ * project end up with two `HTTPException` classes that `instanceof` disagrees about.
+ *
+ * This is *not* the class to throw for an ordinary HTTP error. That is `HttpException` from
+ * `@asenajs/asena/adapter`, which is the same class on every adapter, so the same `throw`
+ * compiles and behaves identically on ergenecore and here. It is deliberately not re-exported
+ * from this package: two throwable, branded classes whose names differ by the case of two letters
+ * is a trap for autocomplete, and only one of them is the portable one.
+ *
+ * Both are recognised by `isHttpException()` and both are answered from their own status, so
+ * anything hono's ecosystem raises - `hono/basic-auth`, `hono/bearer-auth`, `hono/jwt`, hono's
+ * validator - keeps working exactly as before.
+ */
 export { HTTPException } from 'hono/http-exception';

package/dist/index.js

@@ -4,6 +4,20 @@ export * from './lib/types';
 export * from './lib/defaults';
 export * from './lib/utils/createHonoAdapter';
 export * from './lib/errors';
-// Re-export Hono's HTTPException for user convenience in middlewares
+/**
+ * Hono's own `HTTPException`, re-exported so applications and middlewares stay on the copy of
+ * `hono` this adapter resolved - importing it from `hono/http-exception` directly is what lets a
+ * project end up with two `HTTPException` classes that `instanceof` disagrees about.
+ *
+ * This is *not* the class to throw for an ordinary HTTP error. That is `HttpException` from
+ * `@asenajs/asena/adapter`, which is the same class on every adapter, so the same `throw`
+ * compiles and behaves identically on ergenecore and here. It is deliberately not re-exported
+ * from this package: two throwable, branded classes whose names differ by the case of two letters
+ * is a trap for autocomplete, and only one of them is the portable one.
+ *
+ * Both are recognised by `isHttpException()` and both are answered from their own status, so
+ * anything hono's ecosystem raises - `hono/basic-auth`, `hono/bearer-auth`, `hono/jwt`, hono's
+ * validator - keeps working exactly as before.
+ */
 export { HTTPException } from 'hono/http-exception';
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":"AAAA,cAAc,mBAAmB,CAAC;AAClC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,aAAa,CAAC;AAC5B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,+BAA+B,CAAC;AAC9C,cAAc,cAAc,CAAC;AAE7B,qEAAqE;AACrE,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":"AAAA,cAAc,mBAAmB,CAAC;AAClC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,aAAa,CAAC;AAC5B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,+BAA+B,CAAC;AAC9C,cAAc,cAAc,CAAC;AAE7B;;;;;;;;;;;;;;GAcG;AACH,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC"}

package/dist/lib/HonoAdapter.d.ts

@@ -3,7 +3,7 @@ import type { Server } from 'bun';
 import type { WebsocketRouteParams } from '@asenajs/asena/adapter';
 import { AsenaAdapter, type AsenaServeOptions, type AsenaStartOptions, type BaseMiddleware, type RouteParams } from '@asenajs/asena/adapter';
 import type { GlobalMiddlewareRouteConfig } from '@asenajs/asena/server/config';
-import type { HonoAdapterOptions, HonoErrorHandler, StaticServeExtras } from './types';
+import type { HonoAdapterOptions, HonoErrorHandler, HonoNotFoundHandler, StaticServeExtras } from './types';
 import { type ServerLogger } from '@asenajs/asena/logger';
 import type { ValidationSchema } from './defaults';
 import type { Context as HonoAdapterContext } from './defaults/Context';
@@ -13,14 +13,17 @@ export declare class HonoAdapter extends AsenaAdapter<HonoAdapterContext, Valida
     name: string;
     app: Hono;
     private readonly _strict;
+    private readonly logErrors;
     private server;
     private options;
     /**
-     * Whether the application registered an error handler. Validation failures are only
-     * worth throwing when something is there to catch them - otherwise Hono answers 500
-     * and the adapter's 400 envelope is the better response.
+     * Whether the *application* registered an error handler. Read only by `start()`, to decide
+     * whether the framework's own default needs registering - Hono keeps a single `onError`, so
+     * registering both would replace the application's.
      */
     private hasErrorHandler;
+    /** Whether the application registered an onNotFound hook (see start()) */
+    private hasNotFoundHandler;
     /**
      * Normalizes a route path for Hono compatibility.
      * Strips trailing slash (except root '/') because Hono's strict:false
@@ -28,6 +31,21 @@ export declare class HonoAdapter extends AsenaAdapter<HonoAdapterContext, Valida
      * Registered routes must match this normalized form.
      */
     private normalizePath;
+    /**
+     * Stops the HTTP surface and releases everything the adapter owns.
+     *
+     * The socket goes down first and the WebSocket adapter is torn down after it, for the same
+     * reason the core stops the adapter before running `@OnStop`: a transport has to outlive the
+     * things that publish through it. Destroying it while a message handler is still running would
+     * only turn a shutdown into an error in the log.
+     *
+     * `finally`, so the two failure directions are both covered - a `server.stop()` that rejects
+     * still releases the WebSocket resources, and a WebSocket teardown that fails cannot leave the
+     * port bound. A port that survives `stop()` is how a test suite starts failing with
+     * EADDRINUSE and how a rolling deploy keeps taking traffic it can no longer serve.
+     *
+     * @param closeActiveConnections - Whether to drop in-flight connections instead of draining them
+     */
     stop(closeActiveConnections?: boolean): Promise<void>;
     private routeQueue;
     /**
@@ -100,31 +118,86 @@ export declare class HonoAdapter extends AsenaAdapter<HonoAdapterContext, Valida
     registerWebsocketRoute(params: WebsocketRouteParams<HonoAdapterContext>): Promise<void> | void;
     start(options?: AsenaStartOptions): Promise<Server<WebSocketData<any>>>;
     /**
-     * Registers global error handler with enhanced error handling capabilities
+     * Registers the handler for requests that match no route.
      *
-     * Supports Hono's HTTPException for proper status code handling:
-     * - HTTPException instances are passed to user handler for custom handling
-     * - If user handler returns a response, it's used
-     * - Otherwise, HTTPException's default response is returned
-     * - Other errors follow normal error handling flow
+     * Separate from {@link onError}: an unmatched route is a routing outcome, not a thrown error,
+     * so the application's error handler never sees one and never has to discriminate.
      *
-     * @param errorHandler - Custom error handler function
+     * @param notFoundHandler - Handler that produces the 404 response
+     */
+    onNotFound(notFoundHandler: HonoNotFoundHandler): void;
+    /**
+     * The 404 both adapters answer when no `onNotFound` is registered, and the log line that goes
+     * with it.
+     *
+     * Hono's own default is `text/plain`, so the same application used to produce a different
+     * body depending on which adapter it ran under - the specific complaint that started this
+     * work. Registered unconditionally in `start()` so the default holds even for an app with
+     * no config at all.
+     *
+     * `info`, not `warn`: a scanner walking /wp-admin, /.env and /phpmyadmin must not be able to
+     * fill the warning stream. Not `debug` either - a 404 nobody can see is how a mistyped route
+     * survives to production. Only reached when the framework is the one answering, so an
+     * application that shaped its own 404 gets no line from here.
+     */
+    private defaultNotFoundResponse;
+    /**
+     * Registers the application's global error handler.
+     *
+     * Every error the application throws is offered to it first, `HTTPException` included, so an
+     * application can reshape its own 401/403/429 envelopes rather than only the 500s. Returning
+     * nothing means "not mine, use the default" - the framework then answers, and logs.
+     *
+     * @param errorHandler - Handler that produces the response for a thrown error
      *
      * @example
      * ```typescript
      * adapter.onError((error, context) => {
-     *   // HTTPException handling (optional custom behavior)
-     *   if (error instanceof HTTPException) {
-     *     // Add custom logging or return custom response
-     *     return context.send({ custom: 'response' }, error.status);
+     *   if (isHttpException(error)) {
+     *     return context.send({ error: error.message }, error.status);
      *   }
      *
-     *   // Other errors
      *   return context.send({ error: 'Internal error' }, 500);
      * });
      * ```
      */
     onError(errorHandler: HonoErrorHandler): void;
+    /**
+     * The response the framework itself answers with, and the log line that goes with it.
+     *
+     * Reached when the application declared no `onError`, when its handler declined by returning
+     * nothing, or when the handler threw. All three mean the framework is producing the response,
+     * so it is the framework that has to record what happened - otherwise an `onError` that
+     * returns `undefined` swallows a 500 with no trace anywhere.
+     *
+     * The body is the same one `@asenajs/ergenecore` answers. It used to be `text/plain` for an
+     * application with no config and `{error, message, timestamp}` for one whose handler declined,
+     * so the same failure produced three different envelopes across the two adapters.
+     */
+    private defaultErrorResponse;
+    /**
+     * The status the caller will be answered with, for anything thrown.
+     *
+     * Shared by `defaultErrorResponse` and `logHandledError` so the response and the log line cannot
+     * disagree. They used to: the response was chosen by `instanceof HTTPException` while the log
+     * level was chosen by duck-typing a numeric `status` off the error. A plain `Error` carrying a
+     * stray `.status = 401` was therefore answered 500 and logged at debug as a 4xx, and a branded
+     * exception from a second copy was answered 500 and logged as whatever status it carried.
+     */
+    private resolveErrorStatus;
+    /**
+     * Logs an error that is about to be handed to the application's error handler.
+     *
+     * The level is derived from the status the client will actually see - via the same
+     * `resolveErrorStatus` the response uses, so the two cannot drift. A 4xx is the caller's
+     * mistake and the auth/validation layer doing its job, so it must not flood the ERROR stream
+     * with stack traces - an unauthenticated request would otherwise be an attacker-controlled log
+     * amplifier. Only 5xx carries a stack, because that is the class of failure nobody predicted.
+     *
+     * `ServerLogger.debug` is optional, so fall back to `info` when an implementation does
+     * not provide it.
+     */
+    private logHandledError;
     serveOptions(options: () => Promise<AsenaServeOptions> | AsenaServeOptions): Promise<void>;
     setPort(port: number): void;
     private prepareMiddlewares;
@@ -144,15 +217,16 @@ export declare class HonoAdapter extends AsenaAdapter<HonoAdapterContext, Valida
     /**
      * @description Answer a failed validation.
      *
-     * Throws a `ValidationError` so the failure travels the same path as every other
-     * error and reaches `ConfigService.onError`, which is what the documentation has
-     * always described. When the application defines no error handler Hono would turn
-     * a thrown error into a bare 500, so the adapter's own 400 envelope stays as the
-     * fallback and those applications see no change at all.
+     * Throws a `ValidationError` so the failure travels the same path as every other error and
+     * reaches `ConfigService.onError`, which is what the documentation has always described.
+     *
+     * The adapter used to answer its own 400 here when no error handler was configured, which made
+     * a validation failure the one 4xx that reached neither `onError` nor the log. That envelope
+     * did not disappear with the branch - it moved onto `ValidationError.getResponse()`, which
+     * `defaultErrorResponse` falls back to.
      * @param {ZodError} error - The Zod failure
      * @param {string} target - Which part of the request failed
-     * @param {Context} context - The Hono context
-     * @returns {Response} The fallback response, when no error handler is configured
+     * @returns {never} Always throws
      */
     private handleValidationFailure;
     /**
@@ -190,27 +264,16 @@ export declare class HonoAdapter extends AsenaAdapter<HonoAdapterContext, Valida
      */
     private getGlobalMiddlewaresForPath;
     /**
-     * Extracts base path from a route path
-     * Examples:
-     * - "/api/users/:id" -> "/api/users"
-     * - "/users" -> "/users"
-     * - "/" -> "/"
-     */
-    private extractBasePath;
-    /**
-     * Groups routes by their base path
-     * Returns a map of base path -> routes with that base path
-     */
-    private groupRoutesByBasePath;
-    /**
-     * Finds common middlewares across all routes in a group
-     * Returns middlewares that appear in ALL routes
-     */
-    private extractCommonMiddlewares;
-    /**
-     * Registers routes to Hono app with optimization
-     * Groups routes by base path and applies common middlewares at group level
-     * Also registers WebSocket routes
+     * Sorts the queued routes and registers each one with its own middlewares.
+     *
+     * There used to be a "common middleware" optimisation here: routes sharing a base path were
+     * mounted on a sub-app and the middlewares they had in common were hoisted to `group.use('*')`.
+     * It compared middlewares with `mw.constructor.name`, but by this point a middleware is the
+     * plain `{ handle, override }` literal PrepareMiddlewareService builds - so the name was
+     * `"Object"` for every one of them and the comparison was always true. Every route in a group
+     * got the *first* route's middlewares and had its own filtered away, which silently swapped
+     * authorisation guards between sibling routes. Measured at 100 routes it bought nothing, so
+     * it is gone rather than repaired.
      */
     private optimizeAndRegisterRoutes;
     /**
@@ -222,10 +285,6 @@ export declare class HonoAdapter extends AsenaAdapter<HonoAdapterContext, Valida
      * Converts HTTP GET route to WebSocket upgrade endpoint
      */
     private registerWebsocketRouteDirect;
-    /**
-     * Registers a group of routes with common middlewares at base path level
-     */
-    private registerRouteGroup;
     /**
      * Registers a single route directly without grouping
      */