@asenajs/hono-adapter 1.7.0 → 2.0.0

package/README.md

@@ -1,5 +1,8 @@
 # Asena Hono Adapter
 
+[![Version](https://img.shields.io/badge/version-2.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
@@ -112,7 +115,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/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
@@ -100,31 +103,76 @@ 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;
+    /**
+     * 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: 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 +192,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 +239,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 +260,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
      */