stratal 0.0.11 → 0.0.13

package/dist/router/router-context.d.ts

@@ -1,8 +1,10 @@
 import type { Context } from 'hono';
-import { type ContentfulStatusCode, type RedirectStatusCode } from 'hono/utils/http-status';
+import type { SSEStreamingApi } from 'hono/streaming';
+import type { ContentfulStatusCode, RedirectStatusCode } from 'hono/utils/http-status';
+import type { StreamingApi } from 'hono/utils/stream';
 import type { Container } from '../di/container';
 import type { RouterEnv } from './types';
-type ContextQueryResult<R extends Record<string, unknown> | undefined, K extends string | undefined> = K extends string ? string : R;
+export type ContextQueryResult<R extends Record<string, unknown> | undefined, K extends string | undefined> = K extends string ? string : R extends undefined ? Record<string, unknown> : R;
 /**
  * Router context wrapper with helper methods
  *
@@ -112,6 +114,30 @@ export declare class RouterContext<T extends RouterEnv = RouterEnv> {
      * @param status - HTTP status code (default: 302)
      */
     redirect(url: string, status?: RedirectStatusCode): Response;
+    /**
+     * Return a streaming response (binary/generic)
+     *
+     * @param callback - Async function that writes to the stream
+     * @param onError - Optional error handler called if an error occurs during streaming
+     */
+    stream(callback: (stream: StreamingApi) => Promise<void>, onError?: (err: Error, stream: StreamingApi) => Promise<void>): Response;
+    /**
+     * Return a streaming text response
+     *
+     * Automatically sets `Content-Encoding: Identity` for Cloudflare Workers compatibility.
+     *
+     * @param callback - Async function that writes text to the stream
+     * @param onError - Optional error handler called if an error occurs during streaming
+     */
+    streamText(callback: (stream: StreamingApi) => Promise<void>, onError?: (err: Error, stream: StreamingApi) => Promise<void>): Response;
+    /**
+     * Return a Server-Sent Events (SSE) streaming response
+     *
+     * Automatically sets `Content-Encoding: Identity` for Cloudflare Workers compatibility.
+     *
+     * @param callback - Async function that writes SSE events to the stream
+     * @param onError - Optional error handler called if an error occurs during streaming
+     */
+    streamSSE(callback: (stream: SSEStreamingApi) => Promise<void>, onError?: (err: Error, stream: SSEStreamingApi) => Promise<void>): Response;
 }
-export {};
 //# sourceMappingURL=router-context.d.ts.map

package/dist/router/router-context.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"router-context.d.ts","sourceRoot":"","sources":["../../src/router/router-context.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,MAAM,CAAA;AACnC,OAAO,EAAE,KAAK,oBAAoB,EAAE,KAAK,kBAAkB,EAAE,MAAM,wBAAwB,CAAA;AAC3F,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAA;AAGhD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,SAAS,CAAA;AAExC,KAAK,kBAAkB,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,EAAE,CAAC,SAAS,MAAM,GAAG,SAAS,IAAI,CAAC,SAAS,MAAM,GAAG,MAAM,GAAG,CAAC,CAAA;AAEpI;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,qBAAa,aAAa,CAAC,CAAC,SAAS,SAAS,GAAG,SAAS;aAMtC,CAAC,EAAE,OAAO,CAAC,CAAC,CAAC;IAL/B;;;OAGG;gBAEe,CAAC,EAAE,OAAO,CAAC,CAAC,CAAC;IAG/B;;;;;OAKG;IACH,YAAY,IAAI,SAAS;IAQzB;;;;;OAKG;IACH,SAAS,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI;IAI/B;;;;OAIG;IACH,SAAS,IAAI,MAAM;IAKnB;;;;;OAKG;IACH,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,oBAAoB,GAAG,QAAQ;IAI3D;;;;OAIG;IACH,KAAK,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM;IAI1B;;;;OAIG;IACH,KAAK,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,GAAG,SAAS,EAAE,CAAC,SAAS,MAAM,GAAG,SAAS,GAAG,SAAS,EAAE,GAAG,CAAC,EAAE,CAAC,GAAG,kBAAkB,CAAC,CAAC,EAAE,CAAC,CAAC;IAK7I;;;;OAIG;IACH,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IAIxC;;;;;OAKG;IACH,IAAI,CAAC,CAAC,KAAK,OAAO,CAAC,CAAC,CAAC;IAMrB;;;;;OAKG;IACH,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,oBAAoB,GAAG,QAAQ;IAI3D;;;;;OAKG;IACH,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,oBAAoB,GAAG,QAAQ;IAI3D;;;;;OAKG;IACH,QAAQ,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,kBAAkB,GAAG,QAAQ;CAG7D"}
+{"version":3,"file":"router-context.d.ts","sourceRoot":"","sources":["../../src/router/router-context.ts"],"names":[],"mappings":"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"}

package/dist/router/router-context.js

@@ -1,3 +1,4 @@
+import { stream as honoStream, streamSSE as honoStreamSSE, streamText as honoStreamText } from 'hono/streaming';
 import { RequestContainerNotInitializedError } from '../errors';
 import { ROUTER_CONTEXT_KEYS } from './constants';
 /**
@@ -141,5 +142,38 @@ export class RouterContext {
     redirect(url, status) {
         return this.c.redirect(url, status);
     }
+    /**
+     * Return a streaming response (binary/generic)
+     *
+     * @param callback - Async function that writes to the stream
+     * @param onError - Optional error handler called if an error occurs during streaming
+     */
+    stream(callback, onError) {
+        return honoStream(this.c, callback, onError);
+    }
+    /**
+     * Return a streaming text response
+     *
+     * Automatically sets `Content-Encoding: Identity` for Cloudflare Workers compatibility.
+     *
+     * @param callback - Async function that writes text to the stream
+     * @param onError - Optional error handler called if an error occurs during streaming
+     */
+    streamText(callback, onError) {
+        this.c.header('Content-Encoding', 'Identity');
+        return honoStreamText(this.c, callback, onError);
+    }
+    /**
+     * Return a Server-Sent Events (SSE) streaming response
+     *
+     * Automatically sets `Content-Encoding: Identity` for Cloudflare Workers compatibility.
+     *
+     * @param callback - Async function that writes SSE events to the stream
+     * @param onError - Optional error handler called if an error occurs during streaming
+     */
+    streamSSE(callback, onError) {
+        this.c.header('Content-Encoding', 'Identity');
+        return honoStreamSSE(this.c, callback, onError);
+    }
 }
 //# sourceMappingURL=router-context.js.map

package/dist/router/router-context.js.map

@@ -1 +1 @@
-{"version":3,"file":"router-context.js","sourceRoot":"","sources":["../../src/router/router-context.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,mCAAmC,EAAE,MAAM,WAAW,CAAA;AAC/D,OAAO,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAA;AAKjD;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,MAAM,OAAO,aAAa;IAMN;IALlB;;;OAGG;IACH,YACkB,CAAa;QAAb,MAAC,GAAD,CAAC,CAAY;IAC3B,CAAC;IAEL;;;;;OAKG;IACH,YAAY;QACV,MAAM,SAAS,GAAG,IAAI,CAAC,CAAC,CAAC,GAAG,CAAC,mBAAmB,CAAC,iBAAiB,CAAC,CAAA;QACnE,IAAI,CAAC,SAAS,EAAE,CAAC;YACf,MAAM,IAAI,mCAAmC,EAAE,CAAA;QACjD,CAAC;QACD,OAAO,SAAsB,CAAA;IAC/B,CAAC;IAED;;;;;OAKG;IACH,SAAS,CAAC,MAAc;QACtB,IAAI,CAAC,CAAC,CAAC,GAAG,CAAC,mBAAmB,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IAChD,CAAC;IAED;;;;OAIG;IACH,SAAS;QACP,MAAM,MAAM,GAAG,IAAI,CAAC,CAAC,CAAC,GAAG,CAAC,mBAAmB,CAAC,MAAM,CAAC,CAAA;QACrD,OAAQ,MAAiB,IAAI,IAAI,CAAA;IACnC,CAAC;IAED;;;;;OAKG;IACH,IAAI,CAAC,IAAY,EAAE,MAA6B;QAC9C,OAAO,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,EAAE,MAAM,CAAC,CAAA;IAClC,CAAC;IAED;;;;OAIG;IACH,KAAK,CAAC,GAAW;QACf,OAAQ,IAAI,CAAC,CAAC,CAAC,GAAqE,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,GAAG,CAAC,CAAA;IAC1G,CAAC;IAED;;;;OAIG;IACH,KAAK,CAAsG,GAAO;QAChH,MAAM,SAAS,GAAI,IAAI,CAAC,CAAC,CAAC,GAAsE,CAAC,KAAK,CAAC,OAAO,CAAC,CAAA;QAC/G,OAAO,GAAG,CAAC,CAAC,CAAC,SAAS,CAAC,GAAG,CAA6B,CAAC,CAAC,CAAC,SAAqC,CAAA;IACjG,CAAC;IAED;;;;OAIG;IACH,MAAM,CAAC,IAAY;QACjB,OAAO,IAAI,CAAC,CAAC,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,CAAA;IAChC,CAAC;IAED;;;;;OAKG;IACH,IAAI;QACF,mEAAmE;QACnE,mEAAmE;QACnE,OAAQ,IAAI,CAAC,CAAC,CAAC,GAAwD,CAAC,KAAK,CAAC,MAAM,CAAC,CAAA;IACvF,CAAC;IAED;;;;;OAKG;IACH,IAAI,CAAC,IAAY,EAAE,MAA6B;QAC9C,OAAO,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,EAAE,MAAM,CAAC,CAAA;IAClC,CAAC;IAED;;;;;OAKG;IACH,IAAI,CAAC,IAAY,EAAE,MAA6B;QAC9C,OAAO,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,EAAE,MAAM,CAAC,CAAA;IAClC,CAAC;IAED;;;;;OAKG;IACH,QAAQ,CAAC,GAAW,EAAE,MAA2B;QAC/C,OAAO,IAAI,CAAC,CAAC,CAAC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC,CAAA;IACrC,CAAC;CACF"}
+{"version":3,"file":"router-context.js","sourceRoot":"","sources":["../../src/router/router-context.ts"],"names":[],"mappings":"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"}

package/dist/router/services/route-registration.service.d.ts

@@ -2,7 +2,7 @@ import type { OpenAPIHono } from '../../i18n/validation';
 import { type LoggerService } from '../../logger';
 import type { Constructor } from '../../types';
 import type { IController } from '../controller';
-import type { RouterEnv } from '../types';
+import type { RouterEnv, VersioningOptions } from '../types';
 /**
  * Route registration service
  * Manages controller and route registration with OpenAPI support
@@ -16,20 +16,42 @@ import type { RouterEnv } from '../types';
  */
 export declare class RouteRegistrationService {
     private logger;
+    private versioningOptions;
     private controllerClasses;
-    constructor(logger: LoggerService);
+    constructor(logger: LoggerService, versioningOptions?: VersioningOptions | null);
     /**
      * Configure router with controllers
      *
      * @param app - OpenAPIHono application instance
      * @param controllers - Array of controller classes from modules
      */
-    configure(app: OpenAPIHono<RouterEnv>, controllers: Constructor<IController>[]): void;
+    configure(app: OpenAPIHono<RouterEnv>, controllers: Constructor<IController>[]): Promise<void>;
+    /**
+     * Register a WebSocket gateway
+     * Applies versioning and guards, then registers an upgradeWebSocket handler
+     */
+    private registerGateway;
+    /**
+     * Register a single WebSocket gateway route
+     */
+    private registerGatewayRoute;
     /**
      * Register a single controller with all its routes
      * Validates that controller has access decorator (strict mode)
      */
     private registerController;
+    /**
+     * Dispatch route registration based on decorator type
+     */
+    private dispatchRoutes;
+    /**
+     * Resolve versioned paths for a controller based on versioning configuration.
+     *
+     * @param basePath - The base path from @Controller decorator
+     * @param controllerOpts - Controller options (may contain version)
+     * @returns Array of resolved paths (with version prefix if applicable)
+     */
+    private resolveVersionedPaths;
     /**
      * Create a guard execution middleware
      *
@@ -48,6 +70,15 @@ export declare class RouteRegistrationService {
      * Register OpenAPI routes with metadata
      */
     private registerOpenAPIRoutes;
+    /**
+     * Register routes using HTTP method decorators (@Get, @Post, etc.)
+     * These use explicit method + path instead of convention-based derivation
+     */
+    private registerHttpRoutes;
+    /**
+     * Join a base path and a route path, normalizing slashes
+     */
+    private joinPaths;
     /**
      * Register route without OpenAPI metadata (for hidden routes)
      * Route is functional but won't appear in documentation
@@ -76,6 +107,10 @@ export declare class RouteRegistrationService {
      * Execution order: Global middlewares → Guards → Handler
      */
     private buildOpenAPIRoute;
+    /**
+     * Check if a body definition is a RouteBodyObject (has schema key) vs bare ZodType
+     */
+    private isRouteBodyObject;
     /**
      * Resolve method parameter injections from the container
      *

package/dist/router/services/route-registration.service.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"route-registration.service.d.ts","sourceRoot":"","sources":["../../../src/router/services/route-registration.service.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAA;AAExD,OAAO,EAAE,KAAK,aAAa,EAAE,MAAM,cAAc,CAAA;AACjD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAA;AAE9C,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,eAAe,CAAA;AAchD,OAAO,KAAK,EAKV,SAAS,EAEV,MAAM,UAAU,CAAA;AAEjB;;;;;;;;;;GAUG;AACH,qBAAa,wBAAwB;IAIjC,OAAO,CAAC,MAAM;IAHhB,OAAO,CAAC,iBAAiB,CAA8C;gBAG7D,MAAM,EAAE,aAAa;IAG/B;;;;;OAKG;IACH,SAAS,CACP,GAAG,EAAE,WAAW,CAAC,SAAS,CAAC,EAC3B,WAAW,EAAE,WAAW,CAAC,WAAW,CAAC,EAAE,GACtC,IAAI;IAwBP;;;OAGG;IACH,OAAO,CAAC,kBAAkB;IAkC1B;;;;;;;;OAQG;IACH,OAAO,CAAC,qBAAqB;IAe7B;;OAEG;IACH,OAAO,CAAC,qBAAqB;IAkB7B;;OAEG;IACH,OAAO,CAAC,qBAAqB;IA6F7B;;;OAGG;IACH,OAAO,CAAC,2BAA2B;IA+CnC;;OAEG;IACH,OAAO,CAAC,qBAAqB;IA0B7B;;;OAGG;IACH,OAAO,CAAC,uBAAuB;IAU/B;;;;OAIG;IACH,OAAO,CAAC,aAAa;IAuCrB;;;;;;OAMG;IACH,OAAO,CAAC,iBAAiB;IAiHzB;;;;;;;OAOG;IACH,OAAO,CAAC,uBAAuB;IAW/B;;;OAGG;IACH,OAAO,CAAC,uBAAuB;CAsChC"}
+{"version":3,"file":"route-registration.service.d.ts","sourceRoot":"","sources":["../../../src/router/services/route-registration.service.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAA;AAExD,OAAO,EAAE,KAAK,aAAa,EAAE,MAAM,cAAc,CAAA;AACjD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAA;AAI9C,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,eAAe,CAAA;AAgBhD,OAAO,KAAK,EAMV,SAAS,EAET,iBAAiB,EAClB,MAAM,UAAU,CAAA;AAUjB;;;;;;;;;;GAUG;AACH,qBAAa,wBAAwB;IAIjC,OAAO,CAAC,MAAM;IACd,OAAO,CAAC,iBAAiB;IAJ3B,OAAO,CAAC,iBAAiB,CAA8C;gBAG7D,MAAM,EAAE,aAAa,EACrB,iBAAiB,GAAE,iBAAiB,GAAG,IAAW;IAG5D;;;;;OAKG;IACG,SAAS,CACb,GAAG,EAAE,WAAW,CAAC,SAAS,CAAC,EAC3B,WAAW,EAAE,WAAW,CAAC,WAAW,CAAC,EAAE,GACtC,OAAO,CAAC,IAAI,CAAC;IAyChB;;;OAGG;YACW,eAAe;IAoB7B;;OAEG;YACW,oBAAoB;IA4ElC;;;OAGG;IACH,OAAO,CAAC,kBAAkB;IAoD1B;;OAEG;IACH,OAAO,CAAC,cAAc;IAkBtB;;;;;;OAMG;IACH,OAAO,CAAC,qBAAqB;IAiC7B;;;;;;;;OAQG;IACH,OAAO,CAAC,qBAAqB;IAe7B;;OAEG;IACH,OAAO,CAAC,qBAAqB;IAkB7B;;OAEG;IACH,OAAO,CAAC,qBAAqB;IA6F7B;;;OAGG;IACH,OAAO,CAAC,kBAAkB;IAsF1B;;OAEG;IACH,OAAO,CAAC,SAAS;IAKjB;;;OAGG;IACH,OAAO,CAAC,2BAA2B;IAkDnC;;OAEG;IACH,OAAO,CAAC,qBAAqB;IA0B7B;;;OAGG;IACH,OAAO,CAAC,uBAAuB;IAU/B;;;;OAIG;IACH,OAAO,CAAC,aAAa;IAuCrB;;;;;;OAMG;IACH,OAAO,CAAC,iBAAiB;IAuHzB;;OAEG;IACH,OAAO,CAAC,iBAAiB;IAIzB;;;;;;;OAOG;IACH,OAAO,CAAC,uBAAuB;IAW/B;;;OAGG;IACH,OAAO,CAAC,uBAAuB;CAsChC"}

package/dist/router/services/route-registration.service.js

@@ -1,11 +1,21 @@
 import { getMethodInjections } from '../../di';
 import { getControllerGuards, getMethodGuards, GuardExecutionService, } from '../../guards';
 import { createRoute } from '../../i18n/validation';
-import { HTTP_METHODS, METHOD_STATUS_CODES, SECURITY_SCHEMES } from '../constants';
-import { getControllerOptions, getControllerRoute, getDecoratedMethods, getRouteConfig } from '../decorators';
+import { getWsOnCloseMethod, getWsOnErrorMethod, getWsOnMessageMethod, isGateway } from '../../websocket/decorators';
+import { GatewayContext } from '../../websocket/gateway-context';
+import { DEFAULT_CONTENT_TYPE, HTTP_METHODS, METHOD_STATUS_CODES, SECURITY_SCHEMES, VERSION_NEUTRAL } from '../constants';
+import { getControllerOptions, getControllerRoute, getDecoratedMethods, getHttpDecoratedMethods, getHttpRouteMetadata, getRouteConfig, } from '../decorators';
 import { ControllerMethodNotFoundError, ControllerRegistrationError, OpenAPIRouteRegistrationError, } from '../errors';
 import { RouterContext } from '../router-context';
 import { commonErrorSchemas } from '../schemas/common.schemas';
+const invokeHandler = (instance, method, ...args) => {
+    try {
+        return Promise.resolve(instance[method](...args));
+    }
+    catch (err) {
+        return Promise.reject(err);
+    }
+};
 /**
  * Route registration service
  * Manages controller and route registration with OpenAPI support
@@ -19,9 +29,11 @@ import { commonErrorSchemas } from '../schemas/common.schemas';
  */
 export class RouteRegistrationService {
     logger;
+    versioningOptions;
     controllerClasses = new Map();
-    constructor(logger) {
+    constructor(logger, versioningOptions = null) {
         this.logger = logger;
+        this.versioningOptions = versioningOptions;
     }
     /**
      * Configure router with controllers
@@ -29,7 +41,7 @@ export class RouteRegistrationService {
      * @param app - OpenAPIHono application instance
      * @param controllers - Array of controller classes from modules
      */
-    configure(app, controllers) {
+    async configure(app, controllers) {
         this.logger.info('Registering controllers', {
             controllerCount: controllers.length,
         });
@@ -45,12 +57,101 @@ export class RouteRegistrationService {
                 return -1; // a goes before b
             return 0; // maintain relative order
         });
+        // Single-pass partition: gateways vs regular controllers
+        const gateways = [];
+        const regulars = [];
+        for (const c of sortedControllers) {
+            if (isGateway(c)) {
+                gateways.push(c);
+            }
+            else {
+                regulars.push(c);
+            }
+        }
+        // Register WebSocket gateways
+        for (const GatewayClass of gateways) {
+            await this.registerGateway(app, GatewayClass);
+        }
         // Register controllers
-        for (const ControllerClass of sortedControllers) {
+        for (const ControllerClass of regulars) {
             this.registerController(app, ControllerClass);
         }
         this.logger.info('Controller registration complete');
     }
+    /**
+     * Register a WebSocket gateway
+     * Applies versioning and guards, then registers an upgradeWebSocket handler
+     */
+    async registerGateway(app, GatewayClass) {
+        const route = getControllerRoute(GatewayClass);
+        if (!route) {
+            throw new ControllerRegistrationError(GatewayClass.name, 'Missing @Gateway decorator or route metadata');
+        }
+        const controllerOpts = getControllerOptions(GatewayClass);
+        const paths = this.versioningOptions
+            ? this.resolveVersionedPaths(route, controllerOpts)
+            : [route];
+        for (const fullPath of paths) {
+            await this.registerGatewayRoute(app, GatewayClass, fullPath);
+        }
+    }
+    /**
+     * Register a single WebSocket gateway route
+     */
+    async registerGatewayRoute(app, GatewayClass, fullPath) {
+        // Collect class-level guards
+        const controllerGuards = getControllerGuards(GatewayClass)?.guards ?? [];
+        // Dynamic import: only load hono/cloudflare-workers when gateways exist
+        const { upgradeWebSocket } = await import('hono/cloudflare-workers');
+        // Cache WS metadata once at registration time (not per-connection)
+        const onMsgMethod = getWsOnMessageMethod(GatewayClass);
+        const onCloseMethod = getWsOnCloseMethod(GatewayClass);
+        const onErrMethod = getWsOnErrorMethod(GatewayClass);
+        const wsHandler = upgradeWebSocket((c) => {
+            const routerCtx = new RouterContext(c);
+            const container = routerCtx.getContainer();
+            const gateway = container.resolve(GatewayClass);
+            // Cloudflare Workers doesn't support the `onOpen` WebSocket event;
+            // the upgrade callback itself serves as the open context.
+            const events = {};
+            const bindWsHandler = (method, onCatch) => {
+                return (evt, ws) => {
+                    const ctx = new GatewayContext(c, ws);
+                    c.executionCtx.waitUntil(invokeHandler(gateway, method, evt, ctx).catch((err) => {
+                        this.logger.error(`WebSocket ${method} handler error`, { gateway: GatewayClass.name, error: err instanceof Error ? err.message : String(err) });
+                        onCatch?.(err, ws);
+                    }));
+                };
+            };
+            if (onMsgMethod) {
+                events.onMessage = bindWsHandler(onMsgMethod, (_err, ws) => ws.close(1011, 'Internal Error'));
+            }
+            if (onCloseMethod) {
+                events.onClose = bindWsHandler(onCloseMethod);
+            }
+            if (onErrMethod) {
+                events.onError = bindWsHandler(onErrMethod);
+            }
+            return events;
+        });
+        this.logger.info('Registering WebSocket gateway', {
+            gateway: GatewayClass.name,
+            path: fullPath,
+        });
+        const handlers = [];
+        if (controllerGuards.length > 0) {
+            this.logger.info('Gateway guards', {
+                gateway: GatewayClass.name,
+                path: fullPath,
+                guardCount: controllerGuards.length,
+            });
+            handlers.push(this.createGuardMiddleware(controllerGuards));
+        }
+        handlers.push(wsHandler);
+        // Type assertion needed because Hono's overloaded .get() signatures
+        // don't accept a spread of MiddlewareHandler[] alongside upgradeWebSocket's output type
+        app.get(fullPath, ...handlers);
+    }
     /**
      * Register a single controller with all its routes
      * Validates that controller has access decorator (strict mode)
@@ -64,21 +165,81 @@ export class RouteRegistrationService {
         this.controllerClasses.set(className, ControllerClass);
         const prototype = ControllerClass.prototype;
         const controllerOpts = getControllerOptions(ControllerClass);
-        // Handle wildcard routes (non-RESTful controllers)
+        // Handle wildcard routes (non-RESTful controllers) — check once, not per version
         if (prototype.handle) {
-            this.registerWildcardRoute(app, ControllerClass, route);
+            if (!this.versioningOptions) {
+                this.registerWildcardRoute(app, ControllerClass, route);
+            }
+            else {
+                for (const versionedRoute of this.resolveVersionedPaths(route, controllerOpts)) {
+                    this.registerWildcardRoute(app, ControllerClass, versionedRoute);
+                }
+            }
             return;
         }
-        // Check for OpenAPI decorated methods
+        // Compute decorated methods once (loop-invariant)
         const decoratedMethods = getDecoratedMethods(ControllerClass);
-        if (decoratedMethods.length > 0) {
-            // Register OpenAPI routes
-            this.registerOpenAPIRoutes(app, ControllerClass, route, decoratedMethods, controllerOpts);
+        const httpDecoratedMethods = getHttpDecoratedMethods(ControllerClass);
+        // Enforce mutual exclusivity once
+        if (decoratedMethods.length > 0 && httpDecoratedMethods.length > 0) {
+            throw new ControllerRegistrationError(ControllerClass.name, 'Cannot mix @Route() with HTTP method decorators (@Get, @Post, etc.) in the same controller. Use one pattern or the other.');
+        }
+        // Fast path: no versioning — inline dispatch, no array allocation, no loop
+        if (!this.versioningOptions) {
+            this.dispatchRoutes(app, ControllerClass, route, decoratedMethods, httpDecoratedMethods, controllerOpts, prototype);
+            return;
+        }
+        // Versioning path: resolve versioned paths and register each
+        for (const versionedRoute of this.resolveVersionedPaths(route, controllerOpts)) {
+            this.dispatchRoutes(app, ControllerClass, versionedRoute, decoratedMethods, httpDecoratedMethods, controllerOpts, prototype);
+        }
+    }
+    /**
+     * Dispatch route registration based on decorator type
+     */
+    dispatchRoutes(app, ControllerClass, path, decoratedMethods, httpDecoratedMethods, controllerOpts, prototype) {
+        if (httpDecoratedMethods.length > 0) {
+            this.registerHttpRoutes(app, ControllerClass, path, httpDecoratedMethods, controllerOpts);
+        }
+        else if (decoratedMethods.length > 0) {
+            this.registerOpenAPIRoutes(app, ControllerClass, path, decoratedMethods, controllerOpts);
         }
         else {
-            // Fallback to traditional RESTful method registration (no OpenAPI)
-            this.registerRESTfulRoutes(app, ControllerClass, route, prototype);
+            this.registerRESTfulRoutes(app, ControllerClass, path, prototype);
+        }
+    }
+    /**
+     * Resolve versioned paths for a controller based on versioning configuration.
+     *
+     * @param basePath - The base path from @Controller decorator
+     * @param controllerOpts - Controller options (may contain version)
+     * @returns Array of resolved paths (with version prefix if applicable)
+     */
+    resolveVersionedPaths(basePath, controllerOpts) {
+        // Versioning disabled — always return base path
+        if (!this.versioningOptions) {
+            return [basePath];
+        }
+        const version = controllerOpts?.version;
+        // VERSION_NEUTRAL — explicitly opt out of versioning
+        if (version === VERSION_NEUTRAL) {
+            return [basePath];
+        }
+        const prefix = this.versioningOptions.prefix ?? 'v';
+        // Explicit version(s) on the controller
+        if (version !== undefined) {
+            const versions = Array.isArray(version) ? version : [version];
+            return versions.map(v => `/${prefix}${v}${basePath}`);
         }
+        // No explicit version — apply defaultVersion if set
+        if (this.versioningOptions.defaultVersion !== undefined) {
+            const defaults = Array.isArray(this.versioningOptions.defaultVersion)
+                ? this.versioningOptions.defaultVersion
+                : [this.versioningOptions.defaultVersion];
+            return defaults.map(v => `/${prefix}${v}${basePath}`);
+        }
+        // Versioning enabled but no version and no default — no prefix
+        return [basePath];
     }
     /**
      * Create a guard execution middleware
@@ -185,6 +346,80 @@ export class RouteRegistrationService {
             });
         }
     }
+    /**
+     * Register routes using HTTP method decorators (@Get, @Post, etc.)
+     * These use explicit method + path instead of convention-based derivation
+     */
+    registerHttpRoutes(app, ControllerClass, basePath, httpDecoratedMethods, controllerOpts) {
+        const className = ControllerClass.name;
+        const prototype = ControllerClass.prototype;
+        const controllerHidden = controllerOpts?.hideFromDocs ?? false;
+        const controllerGuards = getControllerGuards(ControllerClass)?.guards ?? [];
+        for (const methodName of httpDecoratedMethods) {
+            const httpMeta = getHttpRouteMetadata(prototype, methodName);
+            if (!httpMeta)
+                continue;
+            const fullPath = this.joinPaths(basePath, httpMeta.path);
+            const routeConfig = httpMeta.config;
+            const hideFromDocs = routeConfig.hideFromDocs ?? controllerHidden;
+            // @All routes or hidden routes are registered without OpenAPI
+            if (httpMeta.method === 'all' || hideFromDocs) {
+                this.logger.info(`Registering route (no OpenAPI)`, {
+                    controller: className,
+                    method: httpMeta.method.toUpperCase(),
+                    path: fullPath,
+                    methodName,
+                });
+                this.registerRouteWithoutOpenAPI(app, ControllerClass, methodName, {
+                    method: httpMeta.method,
+                    path: fullPath,
+                });
+                continue;
+            }
+            // Collect method-level guards
+            const methodGuards = getMethodGuards(prototype, methodName)?.guards ?? [];
+            const allGuards = [...controllerGuards, ...methodGuards];
+            if (allGuards.length > 0) {
+                this.logger.info(`Route guards`, {
+                    controller: className,
+                    method: httpMeta.method.toUpperCase(),
+                    path: fullPath,
+                    methodName,
+                    guardCount: allGuards.length,
+                });
+            }
+            // Build and register OpenAPI route
+            const metadata = this.mergeMetadata(controllerOpts, routeConfig, ControllerClass, methodName);
+            const statusCode = routeConfig.statusCode ?? 200;
+            const openApiRoute = this.buildOpenAPIRoute(httpMeta.method, fullPath, routeConfig, metadata, allGuards, undefined, statusCode);
+            this.logger.info(`Registering OpenAPI route`, {
+                controller: className,
+                method: httpMeta.method.toUpperCase(),
+                path: fullPath,
+                methodName,
+                tags: metadata.tags,
+            });
+            app.openapi(openApiRoute, async (c) => {
+                const ctx = new RouterContext(c);
+                const requestContainer = ctx.getContainer();
+                const controller = requestContainer.resolve(ControllerClass);
+                const method = controller[methodName];
+                if (typeof method === 'function') {
+                    const injectedArgs = this.resolveMethodInjections(prototype, methodName, requestContainer);
+                    return await method.call(controller, ctx, ...injectedArgs);
+                }
+                throw new ControllerMethodNotFoundError(methodName, className);
+            });
+        }
+    }
+    /**
+     * Join a base path and a route path, normalizing slashes
+     */
+    joinPaths(basePath, routePath) {
+        if (routePath === '/')
+            return basePath;
+        return basePath + routePath;
+    }
     /**
      * Register route without OpenAPI metadata (for hidden routes)
      * Route is functional but won't appear in documentation
@@ -222,6 +457,9 @@ export class RouteRegistrationService {
             case 'delete':
                 app.delete(derived.path, handler);
                 break;
+            case 'all':
+                app.all(derived.path, handler);
+                break;
             default:
                 // For head, options, trace, or any other method, use all()
                 app.all(derived.path, handler);
@@ -304,7 +542,7 @@ export class RouteRegistrationService {
      *
      * Execution order: Global middlewares → Guards → Handler
      */
-    buildOpenAPIRoute(method, path, routeConfig, metadata, guards, methodName) {
+    buildOpenAPIRoute(method, path, routeConfig, metadata, guards, methodName, statusCodeOverride) {
         try {
             const route = {
                 method,
@@ -318,12 +556,14 @@ export class RouteRegistrationService {
             }
             // Add request body if defined
             if (routeConfig.body) {
+                const bodySchema = this.isRouteBodyObject(routeConfig.body) ? routeConfig.body.schema : routeConfig.body;
+                const bodyContentType = this.isRouteBodyObject(routeConfig.body) ? routeConfig.body.contentType ?? DEFAULT_CONTENT_TYPE : DEFAULT_CONTENT_TYPE;
                 route.request = {
                     ...route.request,
                     body: {
                         content: {
-                            'application/json': {
-                                schema: routeConfig.body,
+                            [bodyContentType]: {
+                                schema: bodySchema,
                             },
                         },
                     },
@@ -343,8 +583,10 @@ export class RouteRegistrationService {
                     params: routeConfig.params,
                 };
             }
-            // Derive success status code from method name
-            const successStatus = (methodName && METHOD_STATUS_CODES[methodName]) ?? 200;
+            // Derive success status code from method name or use override
+            const successStatus = statusCodeOverride
+                ?? (methodName && METHOD_STATUS_CODES[methodName])
+                ?? 200;
             // Build responses object with auto-derived status
             const responses = {};
             // Add success response with derived status code
@@ -352,9 +594,10 @@ export class RouteRegistrationService {
             // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition -- response may be undefined at runtime
             if (responseDef) {
                 if (typeof responseDef === 'object' && 'schema' in responseDef) {
+                    const responseContentType = responseDef.contentType ?? DEFAULT_CONTENT_TYPE;
                     responses[successStatus] = {
                         content: {
-                            'application/json': { schema: responseDef.schema },
+                            [responseContentType]: { schema: responseDef.schema },
                         },
                         description: responseDef.description ?? `Response ${successStatus}`,
                     };
@@ -362,7 +605,7 @@ export class RouteRegistrationService {
                 else {
                     responses[successStatus] = {
                         content: {
-                            'application/json': { schema: responseDef },
+                            [DEFAULT_CONTENT_TYPE]: { schema: responseDef },
                         },
                         description: `Response ${successStatus}`,
                     };
@@ -397,6 +640,12 @@ export class RouteRegistrationService {
             throw new OpenAPIRouteRegistrationError(path, error instanceof Error ? error.message : String(error));
         }
     }
+    /**
+     * Check if a body definition is a RouteBodyObject (has schema key) vs bare ZodType
+     */
+    isRouteBodyObject(body) {
+        return typeof body === 'object' && 'schema' in body;
+    }
     /**
      * Resolve method parameter injections from the container
      *