stratal 0.0.22 → 0.0.24

package/dist/route-registration.service-D6vSwiKP.mjs

@@ -0,0 +1,918 @@
+import { t as __exportAll } from "./chunk-BBjsoOtd.mjs";
+import { d as inject, m as getMethodInjections, r as DI_TOKENS, s as Singleton, v as ROUTER_TOKENS } from "./di-DseMn-z9.mjs";
+import { n as getMetadata, t as defineMetadata } from "./metadata-DzzprcID.mjs";
+import { n as __decorateParam, t as __decorate } from "./decorate-CuAoSZvs.mjs";
+import { LOGGER_TOKENS } from "./logger/index.mjs";
+import { d as abort, u as HttpException } from "./errors-mXYxG0XB.mjs";
+import { a as RouterContext, c as METHOD_STATUS_CODES, d as SECURITY_SCHEMES, l as ROUTER_CONTEXT_KEYS, o as DEFAULT_CONTENT_TYPE, s as HTTP_METHODS, u as ROUTE_METADATA_KEYS } from "./exception-context-kEoMFwze.mjs";
+import { o as RouterError, s as createThrottleMiddleware } from "./module-registry-Dm-pqHd3.mjs";
+import { i as zod_exports, r as z } from "./zod-eKqqhZ5_.mjs";
+import { n as getControllerOptions, r as getControllerRoute } from "./controller.decorator-C5UVeJS3.mjs";
+import "./http-method.decorator-ByWZb9DO.mjs";
+import { i as getMethodGuards, r as getControllerGuards, t as GuardExecutionService } from "./guards-DALPXy3_.mjs";
+import { n as getRateLimits } from "./rate-limit.decorator-BPAie_p3.mjs";
+import { a as getWsOnCloseMethod, o as getWsOnErrorMethod, s as getWsOnMessageMethod, t as GatewayContext, u as isGateway } from "./gateway-context-TMu_AlJt.mjs";
+import { o as toOpenAPIPath, r as generateConventionRouteName, s as toRoutingOpenAPIPath } from "./route-name-DGoBOfPg.mjs";
+//#region src/router/errors/route-not-found.error.ts
+var RouteNotFoundError = class extends HttpException {
+	path;
+	method;
+	constructor(path, method) {
+		super(404, `Route not found: ${method} ${path}`);
+		this.path = path;
+		this.method = method;
+	}
+};
+//#endregion
+//#region src/router/errors/schema-validation.error.ts
+var SchemaValidationError = class extends HttpException {
+	issues;
+	constructor(zodError) {
+		super(400, "Schema validation failed");
+		this.issues = zodError.issues.map((err) => ({
+			path: err.path.join("."),
+			message: err.message,
+			code: err.code
+		}));
+	}
+};
+//#endregion
+//#region src/router/errors/index.ts
+/**
+* Error thrown when a signed URL has an invalid or expired signature.
+*
+* HTTP Status: 403 Forbidden
+*/
+var InvalidSignatureError = class extends HttpException {
+	constructor() {
+		super(403, "Invalid or expired signature");
+	}
+};
+/**
+* ResponseValidationError
+*
+* Thrown when a controller's response body does not match the declared Zod response schema.
+* Indicates a server-side schema mismatch — the controller is returning data that
+* violates its own API contract.
+*/
+var ResponseValidationError = class extends HttpException {
+	issues;
+	constructor(zodError) {
+		super(500, "Response validation failed");
+		this.issues = zodError.issues.map((err) => ({
+			path: err.path.join("."),
+			message: err.message,
+			code: err.code
+		}));
+	}
+};
+//#endregion
+//#region src/router/middleware/domain.middleware.ts
+/**
+* Parse a domain pattern into a regex and extract parameter names.
+*
+* @example
+* parseDomainPattern('{tenant}.example.com')
+* // => { regex: /^([^.]+)\.example\.com$/, paramNames: ['tenant'] }
+*
+* parseDomainPattern('{region}.{tenant}.example.com')
+* // => { regex: /^([^.]+)\.([^.]+)\.example\.com$/, paramNames: ['region', 'tenant'] }
+*/
+function parseDomainPattern(pattern) {
+	const paramNames = [];
+	const escaped = pattern.replace(/\{([a-zA-Z_][a-zA-Z0-9_]*)\}/g, (_match, paramName) => {
+		paramNames.push(paramName);
+		return "([^.]+)";
+	}).replace(/\./g, "\\.");
+	return {
+		regex: new RegExp(`^${escaped}$`),
+		paramNames
+	};
+}
+/**
+* Strip port number from a host header value.
+* 'example.com:8787' => 'example.com'
+*/
+function stripPort(host) {
+	const colonIdx = host.lastIndexOf(":");
+	if (colonIdx === -1) return host;
+	const afterColon = host.slice(colonIdx + 1);
+	return /^\d+$/.test(afterColon) ? host.slice(0, colonIdx) : host;
+}
+/**
+* Create a Hono middleware that matches the request host against a domain pattern.
+*
+* When the host matches, domain parameters are extracted and stored in context
+* variables accessible via `ctx.domain(key)`.
+*
+* When the host does NOT match, aborts with 404.
+*
+* @param pattern - Domain pattern with `{param}` placeholders (e.g., '{tenant}.myapp.com')
+*
+* @example
+* ```typescript
+* // Applied automatically by RouteRegistrationService for controllers with domain config
+* @Controller('/dashboard', { domain: '{tenant}.myapp.com' })
+* export class DashboardController {
+*   async index(ctx: RouterContext) {
+*     const tenant = ctx.domain('tenant')
+*   }
+* }
+* ```
+*/
+function createDomainMiddleware(pattern) {
+	const { regex, paramNames } = parseDomainPattern(pattern);
+	return async (c, next) => {
+		const host = stripPort(c.req.header("host") ?? "");
+		const match = regex.exec(host);
+		if (!match) abort(404, "Domain mismatch");
+		for (let i = 0; i < paramNames.length; i++) c.set(`domain:${paramNames[i]}`, match[i + 1]);
+		await next();
+	};
+}
+//#endregion
+//#region src/router/middleware/middleware-chain.ts
+/**
+* Create a Hono middleware handler that executes a chain of Stratal middleware classes.
+*
+* Each middleware is resolved from the request-scoped container per request,
+* then executed in order (first registered = outermost in the chain).
+*
+* @param classes - Middleware classes to chain
+* @returns Hono middleware handler
+*/
+function createMiddlewareChain(classes) {
+	return async (c, next) => {
+		const requestContainer = c.get(ROUTER_CONTEXT_KEYS.REQUEST_CONTAINER);
+		const ctx = new RouterContext(c);
+		let current = next;
+		for (let i = classes.length - 1; i >= 0; i--) {
+			const prevNext = current;
+			const middlewareClass = classes[i];
+			current = () => {
+				const middleware = requestContainer.resolve(middlewareClass);
+				let called = false;
+				const guardedNext = () => {
+					if (called) return Promise.reject(new RouterError(`Middleware "${middlewareClass.name ?? "anonymous"}" called next() multiple times`));
+					called = true;
+					return prevNext();
+				};
+				return middleware.handle(ctx, guardedNext);
+			};
+		}
+		const result = await current();
+		if (result instanceof Response) return result;
+	};
+}
+//#endregion
+//#region src/router/decorators/route.decorator.ts
+/**
+* Decorator to add OpenAPI metadata to a controller method using convention-based routing.
+*
+* **Cannot be mixed with HTTP method decorators** (`@Get`, `@Post`, `@Put`, `@Patch`,
+* `@Delete`, `@All`) in the same controller. Use one pattern or the other.
+*
+* Stores route configuration (schemas, response, tags, security) in metadata.
+* HTTP method, path, and success status code are auto-derived from the method name:
+* - index() → GET /base-path → 200
+* - show() → GET /base-path/:id → 200
+* - create() → POST /base-path → 201
+* - update() → PUT /base-path/:id → 200
+* - patch() → PATCH /base-path/:id → 200
+* - destroy() → DELETE /base-path/:id → 200
+*
+* @param config - Route configuration (schemas, response, tags, security)
+*
+* @example
+* ```typescript
+* @Controller('/api/v1/notes', {
+*   tags: ['Notes'],
+*   security: ['bearerAuth']
+* })
+* export class NotesController implements Controller {
+*   @Route({
+*     body: createNoteSchema,
+*     response: noteSchema, // 201 auto-derived from 'create' method
+*     tags: ['Mutations'],
+*     description: 'Create a new note'
+*   })
+*   async create(ctx: RouterContext): Promise<Response> {
+*     // POST /api/v1/notes (auto-derived from method name)
+*     // Body schema: createNoteSchema (auto-validated)
+*     // Response: 201 → noteSchema (status auto-derived)
+*     // Tags: ['Notes', 'Mutations'] (merged with controller)
+*     // Security: ['bearerAuth'] (inherited from controller)
+*     const body = ctx.body()
+*     const note = await this.notesService.create(body)
+*     return ctx.json(note, 201)
+*   }
+*
+*   @Route({
+*     query: paginationSchema,
+*     response: z.array(noteSchema) // 200 auto-derived from 'index' method
+*   })
+*   async index(ctx: RouterContext): Promise<Response> {
+*     // GET /api/v1/notes (auto-derived)
+*     // Query params auto-validated
+*     const notes = await this.notesService.list()
+*     return ctx.json(notes)
+*   }
+*
+*   @Route({
+*     params: z.object({ id: z.string().uuid() }),
+*     response: {
+*       schema: noteSchema,
+*       description: 'Note details'
+*     },
+*     security: [] // Override to make public
+*   })
+*   async show(ctx: RouterContext): Promise<Response> {
+*     // GET /api/v1/notes/:id (auto-derived)
+*     // URL params auto-validated
+*     // Response: 200 → noteSchema (status auto-derived)
+*     // Security: [] (public route, override controller security)
+*     const id = ctx.param('id')
+*     const note = await this.notesService.findById(id)
+*     return ctx.json(note)
+*   }
+* }
+* ```
+*/
+function Route(config) {
+	return function(target, propertyKey, descriptor) {
+		const metadata = {
+			type: "convention",
+			config
+		};
+		defineMetadata(ROUTE_METADATA_KEYS.ROUTE_CONFIG, metadata, target, propertyKey);
+		const existing = getMetadata(ROUTE_METADATA_KEYS.DECORATED_METHODS, target) ?? [];
+		existing.push(propertyKey);
+		defineMetadata(ROUTE_METADATA_KEYS.DECORATED_METHODS, existing, target);
+		return descriptor;
+	};
+}
+/**
+* Get the route metadata from a controller method
+*
+* @param target - Controller instance or prototype
+* @param methodName - Name of the method
+* @returns Route metadata or undefined if not decorated
+*/
+function getRouteMetadata(target, methodName) {
+	return getMetadata(ROUTE_METADATA_KEYS.ROUTE_CONFIG, target, methodName);
+}
+/**
+* Get all methods with route decorators (@Route, @Get, @Post, etc.) from a controller
+*
+* @param ControllerClass - Controller class
+* @returns Array of method names that have route metadata
+*/
+function getRouteDecoratedMethods(ControllerClass) {
+	const methods = /* @__PURE__ */ new Set();
+	let proto = ControllerClass.prototype;
+	while (proto && proto !== Object.prototype) {
+		const own = getMetadata(ROUTE_METADATA_KEYS.DECORATED_METHODS, proto);
+		if (own) for (const m of own) methods.add(m);
+		proto = Object.getPrototypeOf(proto);
+	}
+	return [...methods];
+}
+//#endregion
+//#region src/router/schemas/common.schemas.ts
+/**
+* Common OpenAPI Schemas
+*
+* Reusable schema definitions for common API patterns:
+* - Error responses
+* - Pagination
+* - Common parameters
+*/
+/**
+* Generic error response schema
+* Used for all error responses (4xx, 5xx)
+* Matches the ErrorResponse shape produced by ExceptionHandler
+*/
+const errorResponseSchema = z.object({
+	message: z.string().describe("Human-readable error message"),
+	timestamp: z.string().datetime().describe("ISO timestamp when error occurred"),
+	stack: z.string().optional().describe("Stack trace (development only)")
+}).openapi("ErrorResponse");
+/**
+* Validation error response schema
+* Used for 400 Bad Request with validation failures
+* Matches the ErrorResponse shape produced by ExceptionHandler
+*/
+const validationErrorResponseSchema = errorResponseSchema.openapi("ValidationErrorResponse");
+/**
+* Pagination query parameters schema
+* Used for list endpoints
+*/
+const paginationQuerySchema = z.object({
+	page: z.coerce.number().int().positive().default(1).describe("Page number (1-indexed)"),
+	limit: z.coerce.number().int().positive().max(100).default(20).describe("Items per page (max 100)")
+}).openapi("PaginationQuery");
+/**
+* Paginated response wrapper schema
+* Generic wrapper for paginated list responses
+*/
+const paginatedResponseSchema = (itemSchema) => z.object({
+	data: z.array(itemSchema).describe("Array of items for current page"),
+	pagination: z.object({
+		page: z.number().int().positive().describe("Current page number"),
+		limit: z.number().int().positive().describe("Items per page"),
+		total: z.number().int().nonnegative().describe("Total number of items"),
+		totalPages: z.number().int().nonnegative().describe("Total number of pages")
+	})
+});
+/**
+* UUID parameter schema
+* Used for :id parameters in RESTful routes
+*/
+const uuidParamSchema = z.object({ id: z.string().uuid().describe("Resource UUID") }).openapi("UUIDParam");
+/**
+* Success message response schema
+* Used for operations that don't return data (e.g., DELETE)
+*/
+const successMessageSchema = z.object({
+	message: z.string().describe("Success message"),
+	data: z.record(z.string(), z.unknown()).optional().describe("Optional additional data")
+}).openapi("SuccessMessage");
+/**
+* Common HTTP status error schemas
+* Pre-configured for standard error responses
+*/
+const commonErrorSchemas = {
+	400: {
+		schema: validationErrorResponseSchema,
+		description: "Validation error"
+	},
+	401: {
+		schema: errorResponseSchema,
+		description: "Unauthorized"
+	},
+	403: {
+		schema: errorResponseSchema,
+		description: "Forbidden"
+	},
+	404: {
+		schema: errorResponseSchema,
+		description: "Not found"
+	},
+	409: {
+		schema: errorResponseSchema,
+		description: "Conflict"
+	},
+	500: {
+		schema: errorResponseSchema,
+		description: "Internal server error"
+	}
+};
+//#endregion
+//#region src/router/services/route-registration.service.ts
+var route_registration_service_exports = /* @__PURE__ */ __exportAll({ RouteRegistrationService: () => RouteRegistrationService });
+const invokeHandler = (instance, method, ...args) => {
+	try {
+		return Promise.resolve(instance[method](...args));
+	} catch (err) {
+		return Promise.reject(err);
+	}
+};
+let RouteRegistrationService = class RouteRegistrationService {
+	logger;
+	registry;
+	routerResolver;
+	localePathService;
+	app;
+	moduleRegistry;
+	controllerClasses = /* @__PURE__ */ new Map();
+	upgradeWebSocketFn = null;
+	constructor(logger, registry, routerResolver, localePathService, app, moduleRegistry) {
+		this.logger = logger;
+		this.registry = registry;
+		this.routerResolver = routerResolver;
+		this.localePathService = localePathService;
+		this.app = app;
+		this.moduleRegistry = moduleRegistry;
+	}
+	/**
+	* Configure router with controllers and global middleware.
+	* Resolves controllers from ModuleRegistry and global middleware from RouterResolver.
+	*/
+	async configure() {
+		const controllers = this.moduleRegistry.getAllControllers();
+		const globalMiddleware = this.routerResolver?.getGlobalMiddleware() ?? [];
+		this.logger.info("Registering controllers", { controllerCount: controllers.length });
+		if (globalMiddleware.length > 0) this.app.use("*", createMiddlewareChain(globalMiddleware));
+		if (controllers.some(isGateway)) {
+			const { upgradeWebSocket } = await import("hono/cloudflare-workers");
+			this.upgradeWebSocketFn = upgradeWebSocket;
+		}
+		const actions = /* @__PURE__ */ new WeakMap();
+		for (const ControllerClass of controllers) this.collectRoutes(ControllerClass, actions);
+		for (const route of this.registry.all()) actions.get(route)?.();
+		this.logger.info("Controller registration complete");
+	}
+	/**
+	* Pass 1: Collect routes from a controller into RouteRegistry and store Hono actions.
+	* Versioning and locale expansion are handled by RouteRegistry.register().
+	*/
+	collectRoutes(ControllerClass, actions) {
+		const isWsGateway = isGateway(ControllerClass);
+		const controllerRoute = getControllerRoute(ControllerClass);
+		if (!controllerRoute) throw new RouterError(`Controller "${ControllerClass.name}" registration failed: ${isWsGateway ? "Missing @Gateway decorator or route metadata" : "Missing @Controller decorator or route metadata"}`);
+		const controllerOpts = getControllerOptions(ControllerClass);
+		const controllerGuards = getControllerGuards(ControllerClass)?.guards ?? [];
+		const routerConfig = this.routerResolver?.resolveForController(ControllerClass) ?? { middleware: [] };
+		const classThrottleMiddleware = Array.from(new Set(getRateLimits(ControllerClass).map(createThrottleMiddleware)));
+		const basePath = routerConfig.prefix ? this.joinPaths(routerConfig.prefix, controllerRoute) : controllerRoute;
+		const effectiveVersion = controllerOpts?.version ?? routerConfig.version;
+		const effectiveDomain = controllerOpts?.domain ?? routerConfig.domain;
+		if (isWsGateway) {
+			const wsMiddleware = [...routerConfig.middleware, ...classThrottleMiddleware];
+			const expandedRoutes = this.registry.register({
+				method: "ws",
+				basePath,
+				version: effectiveVersion,
+				domain: effectiveDomain,
+				controller: ControllerClass.name,
+				action: "ws",
+				hidden: routerConfig.hideFromDocs ?? false,
+				middleware: wsMiddleware.map((m) => m.name)
+			});
+			for (const route of expandedRoutes) actions.set(route, () => {
+				if (wsMiddleware.length > 0) this.app.use(route.path, createMiddlewareChain(wsMiddleware));
+				if (effectiveDomain) {
+					const domainHandler = createDomainMiddleware(effectiveDomain);
+					this.app.use(route.path, domainHandler);
+					this.app.use(`${route.path}/*`, domainHandler);
+				}
+				this.registerGatewayForPath(ControllerClass, route.path, controllerGuards);
+			});
+			return;
+		}
+		const className = ControllerClass.name;
+		this.controllerClasses.set(className, ControllerClass);
+		const prototype = ControllerClass.prototype;
+		if (prototype.handle) {
+			const wildcardMiddleware = [...routerConfig.middleware, ...classThrottleMiddleware];
+			const expandedRoutes = this.registry.register({
+				method: "all",
+				basePath,
+				version: effectiveVersion,
+				domain: effectiveDomain,
+				controller: className,
+				action: "handle",
+				hidden: routerConfig.hideFromDocs ?? false,
+				middleware: wildcardMiddleware.map((m) => m.name)
+			});
+			for (const route of expandedRoutes) actions.set(route, () => {
+				if (wildcardMiddleware.length > 0) this.app.use(route.path, createMiddlewareChain(wildcardMiddleware));
+				this.registerWildcardRoute(ControllerClass, route.path);
+			});
+			return;
+		}
+		const decoratedMethods = getRouteDecoratedMethods(ControllerClass);
+		if (decoratedMethods.length === 0) throw new RouterError(`Controller "${ControllerClass.name}" registration failed: No route decorators found. Use @Route() or HTTP method decorators (@Get, @Post, etc.) on controller methods.`);
+		const methodMetadata = [];
+		let hasConvention = false;
+		let hasExplicit = false;
+		for (const m of decoratedMethods) {
+			const meta = getRouteMetadata(prototype, m);
+			if (!meta) continue;
+			methodMetadata.push({
+				method: m,
+				meta
+			});
+			if (meta.type === "convention") hasConvention = true;
+			else if (meta.type === "explicit") hasExplicit = true;
+		}
+		if (hasConvention && hasExplicit) throw new RouterError(`Controller "${ControllerClass.name}" registration failed: Cannot mix @Route() with HTTP method decorators (@Get, @Post, etc.) in the same controller. Use one pattern or the other.`);
+		const routerHidden = routerConfig.hideFromDocs;
+		const controllerHidden = controllerOpts?.hideFromDocs ?? false;
+		const routerName = routerConfig.name;
+		const controllerName = controllerOpts?.name;
+		const effectiveNamePrefix = routerName && controllerName ? `${routerName}${controllerName}` : routerName ?? controllerName;
+		for (const { method: methodName, meta } of methodMetadata) {
+			const resolved = this.resolveMethodAndPath(meta, methodName, basePath, className);
+			if (!resolved) continue;
+			const methodThrottleMiddleware = getRateLimits(prototype, methodName).map(createThrottleMiddleware);
+			const effectiveMiddleware = Array.from(new Set([
+				...routerConfig.middleware,
+				...classThrottleMiddleware,
+				...methodThrottleMiddleware
+			]));
+			const middlewareNames = effectiveMiddleware.map((m) => m.name);
+			const { httpMethod, fullPath, routeConfig: rawRouteConfig, statusCodeOverride } = resolved;
+			let mergedParams = rawRouteConfig.params;
+			if (routerConfig.params) {
+				const prefixShape = routerConfig.params.shape;
+				mergedParams = mergedParams ? mergedParams.extend(prefixShape) : routerConfig.params.extend({});
+			}
+			const routeConfig = mergedParams === rawRouteConfig.params ? rawRouteConfig : {
+				...rawRouteConfig,
+				params: mergedParams
+			};
+			const hideFromDocs = routeConfig.hideFromDocs ?? routerHidden ?? controllerHidden;
+			let routeName;
+			if (routeConfig.name) routeName = effectiveNamePrefix ? `${effectiveNamePrefix}${routeConfig.name}` : routeConfig.name;
+			else if (meta.type === "convention") {
+				const autoName = generateConventionRouteName(basePath, methodName);
+				routeName = effectiveNamePrefix ? `${effectiveNamePrefix}${autoName}` : autoName;
+			}
+			const expandedRoutes = this.registry.register({
+				name: routeName,
+				method: httpMethod,
+				basePath: fullPath,
+				version: effectiveVersion,
+				domain: effectiveDomain,
+				controller: className,
+				action: methodName,
+				hidden: hideFromDocs,
+				middleware: middlewareNames
+			});
+			const methodGuards = getMethodGuards(prototype, methodName)?.guards ?? [];
+			const allGuards = methodGuards.length > 0 ? [...controllerGuards, ...methodGuards] : controllerGuards;
+			const responseSchema = httpMethod !== "all" ? this.extractResponseSchema(routeConfig) : null;
+			const handler = this.createControllerHandler(ControllerClass, methodName, responseSchema);
+			for (const route of expandedRoutes) actions.set(route, () => {
+				if (effectiveDomain) {
+					const domainHandler = createDomainMiddleware(effectiveDomain);
+					this.app.use(route.path, domainHandler);
+					this.app.use(`${route.path}/*`, domainHandler);
+				}
+				if (allGuards.length > 0) this.logger.info(`Route guards`, {
+					controller: className,
+					method: httpMethod.toUpperCase(),
+					path: route.path,
+					methodName,
+					guardCount: allGuards.length
+				});
+				if (httpMethod === "all") {
+					this.logger.info(`Registering @All route`, {
+						controller: className,
+						path: route.path,
+						methodName
+					});
+					if (effectiveMiddleware.length > 0) this.app.use(route.path, createMiddlewareChain(effectiveMiddleware));
+					if (allGuards.length > 0) this.app.use(route.path, this.createGuardMiddleware(allGuards));
+					this.app.all(route.path, handler);
+					return;
+				}
+				const metadata = this.mergeMetadata(controllerOpts, routeConfig, ControllerClass, methodName);
+				const openApiRoute = this.buildOpenAPIRoute(httpMethod, route.path, routeConfig, metadata, meta.type === "convention" ? methodName : void 0, statusCodeOverride, route.isLocaleVariant ?? false);
+				this.logger.info(`Registering route`, {
+					controller: className,
+					method: httpMethod.toUpperCase(),
+					path: route.path,
+					methodName,
+					tags: metadata.tags,
+					hidden: route.hidden
+				});
+				const wrappedHandler = this.wrapHandlerWithChain(handler, effectiveMiddleware, allGuards);
+				this.app.openapi(openApiRoute, wrappedHandler);
+				if (!route.hidden) {
+					const { hide: _, ...specRoute } = openApiRoute;
+					this.app.openAPIRegistry.registerPath({
+						...specRoute,
+						path: toOpenAPIPath(route.path)
+					});
+				}
+			});
+		}
+	}
+	/**
+	* Register a single WebSocket gateway route
+	*/
+	registerGatewayForPath(GatewayClass, fullPath, guards) {
+		const onMsgMethod = getWsOnMessageMethod(GatewayClass);
+		const onCloseMethod = getWsOnCloseMethod(GatewayClass);
+		const onErrMethod = getWsOnErrorMethod(GatewayClass);
+		const wsHandler = this.upgradeWebSocketFn((c) => {
+			const gateway = new RouterContext(c).getContainer().resolve(GatewayClass);
+			const events = {};
+			const bindWsHandler = (method, onCatch) => {
+				return (evt, ws) => {
+					invokeHandler(gateway, method, evt, new GatewayContext(c, ws)).catch((err) => {
+						this.logger.error(`WebSocket ${method} handler error`, err, { gateway: GatewayClass.name });
+						onCatch?.(err, ws);
+					});
+				};
+			};
+			if (onMsgMethod) events.onMessage = bindWsHandler(onMsgMethod, (_err, ws) => ws.close(1011, "Internal Error"));
+			if (onCloseMethod) events.onClose = bindWsHandler(onCloseMethod);
+			else events.onClose = (_evt, ws) => {
+				ws.close();
+			};
+			if (onErrMethod) events.onError = bindWsHandler(onErrMethod);
+			return events;
+		});
+		this.nameHandler(wsHandler, GatewayClass.name, onMsgMethod ?? "[anonymous]", "ws");
+		this.logger.info("Registering WebSocket gateway", {
+			gateway: GatewayClass.name,
+			path: fullPath
+		});
+		const handlers = [];
+		if (guards.length > 0) {
+			this.logger.info("Gateway guards", {
+				gateway: GatewayClass.name,
+				path: fullPath,
+				guardCount: guards.length
+			});
+			handlers.push(this.createGuardMiddleware(guards));
+		}
+		handlers.push(wsHandler);
+		this.app.get(fullPath, ...handlers);
+	}
+	/**
+	* Create a guard execution middleware
+	*
+	* This middleware executes all guards for a route before the handler.
+	* Guards are executed in order; all must pass for the request to proceed.
+	*
+	* @param guards - Array of guards to execute
+	* @returns Hono middleware function
+	*/
+	createGuardMiddleware(guards) {
+		const guardService = new GuardExecutionService(this.logger);
+		return async (c, next) => {
+			const ctx = new RouterContext(c);
+			const container = ctx.getContainer();
+			await guardService.executeGuards(guards, ctx, container);
+			await next();
+		};
+	}
+	/**
+	* Wrap a controller handler with a `scopedMiddleware → guards → handler`
+	* chain that runs *inside* the Hono route handler — after request
+	* validators have populated `c.req.valid(...)`. This is the only place
+	* we can run user middleware after `@hono/zod-openapi`'s validators in
+	* the same pipeline.
+	*
+	* Returns a Hono handler with the same signature as the original so
+	* `app.openapi(route, wrapped)` works transparently.
+	*/
+	wrapHandlerWithChain(handler, scopedMiddleware, guards) {
+		if (scopedMiddleware.length === 0 && guards.length === 0) return handler;
+		const scopedChain = scopedMiddleware.length > 0 ? createMiddlewareChain(scopedMiddleware) : null;
+		const guardChain = guards.length > 0 ? this.createGuardMiddleware(guards) : null;
+		return async (c) => {
+			let captured;
+			const runHandler = async () => {
+				captured = await handler(c);
+			};
+			const runGuards = guardChain ? () => guardChain(c, runHandler) : runHandler;
+			const result = await (scopedChain ? () => scopedChain(c, runGuards) : runGuards)();
+			if (result instanceof Response) return result;
+			return captured;
+		};
+	}
+	/**
+	* Register wildcard route for non-RESTful controllers
+	*/
+	registerWildcardRoute(ControllerClass, route) {
+		this.logger.info(`Registering wildcard route`, {
+			controller: ControllerClass.name,
+			route: `${route}/:path{.+}`,
+			method: "ALL"
+		});
+		const handler = this.createControllerHandler(ControllerClass, "handle");
+		this.app.all(route, handler);
+		this.app.all(`${route}/:path{.+}`, handler);
+	}
+	/**
+	* Resolve HTTP method, path, route config, and status code from route metadata.
+	*/
+	resolveMethodAndPath(meta, methodName, basePath, className) {
+		if (meta.type === "convention") {
+			const derived = this.deriveHttpMethodAndPath(methodName, basePath);
+			if (!derived) throw new RouterError(`Cannot derive HTTP method/path for convention-based route "${className}.${methodName}". Ensure the method name follows the naming convention (e.g., index, create, show).`);
+			return {
+				httpMethod: derived.method,
+				fullPath: derived.path,
+				routeConfig: meta.config,
+				statusCodeOverride: meta.config.statusCode
+			};
+		}
+		return {
+			httpMethod: meta.method,
+			fullPath: this.joinPaths(basePath, meta.path),
+			routeConfig: meta.config,
+			statusCodeOverride: meta.config.statusCode
+		};
+	}
+	/**
+	* Join a base path and a route path, normalizing slashes
+	*/
+	joinPaths(basePath, routePath) {
+		if (basePath.endsWith("/")) basePath = basePath.slice(0, -1);
+		if (routePath === "/" || routePath === "") return basePath || "/";
+		if (!routePath.startsWith("/")) routePath = "/" + routePath;
+		return basePath + routePath;
+	}
+	/**
+	* Auto-derive HTTP method and path from controller method name
+	* Uses HTTP_METHODS constant for RESTful convention mapping
+	*/
+	deriveHttpMethodAndPath(methodName, basePath) {
+		if (!(methodName in HTTP_METHODS)) return null;
+		const mapping = HTTP_METHODS[methodName];
+		return {
+			method: mapping.method,
+			path: basePath + mapping.path
+		};
+	}
+	/**
+	* Merge controller-level and route-level metadata
+	* Tags are merged (appended), security is merged (union)
+	* Guards automatically add sessionCookie security if present
+	*/
+	mergeMetadata(controllerOpts, routeConfig, ControllerClass, methodName) {
+		const tags = [...controllerOpts?.tags ?? [], ...routeConfig.tags ?? []];
+		const prototype = ControllerClass.prototype;
+		const hasMethodGuards = (getMethodGuards(prototype, methodName)?.guards.length ?? 0) > 0;
+		const hasControllerGuards = (getControllerGuards(ControllerClass)?.guards.length ?? 0) > 0;
+		const requiresAuth = hasMethodGuards || hasControllerGuards;
+		let security = [];
+		if (routeConfig.security !== void 0) security = [...controllerOpts?.security ?? [], ...routeConfig.security];
+		else if (controllerOpts?.security) security = controllerOpts.security;
+		if (requiresAuth && !security.includes(SECURITY_SCHEMES.SESSION_COOKIE)) security.push(SECURITY_SCHEMES.SESSION_COOKIE);
+		return {
+			tags,
+			security: security.length > 0 ? security.map((scheme) => ({ [scheme]: [] })) : []
+		};
+	}
+	/**
+	* Build OpenAPI route configuration from metadata
+	* Creates a route definition compatible with @hono/zod-openapi.
+	*
+	* Scoped middleware and guards are NOT attached to `route.middleware`
+	* here — they're composed into a wrapped handler in `collectRoutes` so
+	* they run after Hono's request validators. See `wrapHandlerWithChain`.
+	*/
+	buildOpenAPIRoute(method, path, routeConfig, metadata, methodName, statusCodeOverride, hasLocaleParam = false) {
+		try {
+			const route = {
+				method,
+				path: toRoutingOpenAPIPath(path),
+				request: {},
+				responses: {},
+				hide: true
+			};
+			if (routeConfig.body) {
+				const bodySchema = this.isRouteBodyObject(routeConfig.body) ? routeConfig.body.schema : routeConfig.body;
+				const bodyContentType = this.isRouteBodyObject(routeConfig.body) ? routeConfig.body.contentType ?? "application/json" : DEFAULT_CONTENT_TYPE;
+				route.request = {
+					...route.request,
+					body: { content: { [bodyContentType]: { schema: bodySchema } } }
+				};
+			}
+			if (routeConfig.query) route.request = {
+				...route.request,
+				query: routeConfig.query
+			};
+			if (routeConfig.params) route.request = {
+				...route.request,
+				params: routeConfig.params
+			};
+			const localeConfig = this.localePathService.localePathConfig;
+			if (hasLocaleParam && localeConfig) {
+				const localeParam = z.object({ locale: z.enum(localeConfig.prefixedLocales).openapi({ param: {
+					name: "locale",
+					in: "path"
+				} }).optional() });
+				route.request = {
+					...route.request,
+					params: route.request.params ? route.request.params.extend(localeParam.shape) : localeParam
+				};
+			}
+			const successStatus = statusCodeOverride ?? (methodName && METHOD_STATUS_CODES[methodName]) ?? 200;
+			const responses = {};
+			const responseDef = routeConfig.response;
+			if (responseDef) if (typeof responseDef === "object" && "schema" in responseDef) responses[successStatus] = {
+				content: { [responseDef.contentType ?? "application/json"]: { schema: responseDef.schema } },
+				description: responseDef.description ?? `Response ${successStatus}`
+			};
+			else responses[successStatus] = {
+				content: { [DEFAULT_CONTENT_TYPE]: { schema: responseDef } },
+				description: `Response ${successStatus}`
+			};
+			for (const [statusStr, schema] of Object.entries(commonErrorSchemas)) {
+				const status = parseInt(statusStr);
+				responses[status] ??= schema;
+			}
+			route.responses = responses;
+			if (metadata.tags.length > 0) route.tags = metadata.tags;
+			if (metadata.security.length > 0) route.security = metadata.security;
+			if (routeConfig.description) route.description = routeConfig.description;
+			if (routeConfig.summary) route.summary = routeConfig.summary;
+			return (0, zod_exports.createRoute)(route);
+		} catch (error) {
+			throw new RouterError(`OpenAPI route registration failed for "${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
+	*
+	* @param prototype - Controller prototype
+	* @param methodName - Method name to get injections for
+	* @param container - Request-scoped container
+	* @returns Array of resolved dependencies in parameter order
+	*/
+	resolveMethodInjections(prototype, methodName, container) {
+		const injections = getMethodInjections(prototype, methodName);
+		if (!injections.length) return [];
+		return injections.map((inj) => container.resolve(inj.token));
+	}
+	/**
+	* Name a handler function so Hono's inspectRoutes() can identify it.
+	* Format: `{type}:{Controller}.{method}` (e.g. `http:UsersController.create`)
+	*/
+	nameHandler(fn, controller, method, type = "http") {
+		Object.defineProperty(fn, "name", { value: `${type}:${controller}.${method}` });
+	}
+	/**
+	* Create controller handler that resolves controller from request-scoped container
+	* This ensures each request gets a fresh controller with request-scoped context
+	*/
+	createControllerHandler(ControllerClass, methodName, responseSchema = null) {
+		const handler = async (c) => {
+			const override = c.get("validationSuccessResponse");
+			if (override) return override;
+			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(ControllerClass.prototype, methodName, requestContainer);
+				const response = await method.apply(controller, [ctx, ...injectedArgs]);
+				if (responseSchema && c.env.ENVIRONMENT !== "production") return this.validateResponse(response, responseSchema);
+				return response;
+			}
+			throw new RouterError(`Method "${methodName}" not found on controller "${ControllerClass.name}"`);
+		};
+		this.nameHandler(handler, ControllerClass.name, methodName);
+		return handler;
+	}
+	/**
+	* Extract the Zod schema from a RouteResponse definition.
+	* Returns null for non-JSON content types or when no response is defined.
+	*/
+	extractResponseSchema(routeConfig) {
+		const responseDef = routeConfig.response;
+		if (!responseDef) return null;
+		if (this.isRouteResponseObject(responseDef)) {
+			if (!(responseDef.contentType ?? "application/json").includes("application/json")) return null;
+			return responseDef.schema;
+		}
+		return responseDef;
+	}
+	/**
+	* Check if a response definition is a RouteResponseObject (has schema key) vs bare ZodType
+	*/
+	isRouteResponseObject(response) {
+		return typeof response === "object" && "schema" in response;
+	}
+	/**
+	* Validate a Response body against its declared Zod schema.
+	*
+	* Skips validation for:
+	* - Non-JSON content types
+	* - Empty bodies (204 No Content, 304 Not Modified)
+	*
+	* Clones the response to read the body without consuming the original stream.
+	*/
+	async validateResponse(response, schema) {
+		const contentType = response.headers.get("content-type");
+		if (!contentType || !contentType.includes("application/json")) return response;
+		if (response.status === 204 || response.status === 304) return response;
+		const cloned = response.clone();
+		let body;
+		try {
+			body = await cloned.json();
+		} catch {
+			return response;
+		}
+		const result = schema.safeParse(body);
+		if (!result.success) throw new ResponseValidationError(result.error);
+		return response;
+	}
+};
+RouteRegistrationService = __decorate([
+	Singleton(),
+	__decorateParam(0, inject(LOGGER_TOKENS.LoggerService)),
+	__decorateParam(1, inject(ROUTER_TOKENS.RouteRegistry)),
+	__decorateParam(2, inject(ROUTER_TOKENS.RouterResolver, { isOptional: true })),
+	__decorateParam(3, inject(ROUTER_TOKENS.LocalePathService)),
+	__decorateParam(4, inject(ROUTER_TOKENS.HonoApp)),
+	__decorateParam(5, inject(DI_TOKENS.ModuleRegistry))
+], RouteRegistrationService);
+//#endregion
+export { ResponseValidationError as _, paginatedResponseSchema as a, uuidParamSchema as c, getRouteDecoratedMethods as d, getRouteMetadata as f, InvalidSignatureError as g, parseDomainPattern as h, errorResponseSchema as i, validationErrorResponseSchema as l, createDomainMiddleware as m, route_registration_service_exports as n, paginationQuerySchema as o, createMiddlewareChain as p, commonErrorSchemas as r, successMessageSchema as s, RouteRegistrationService as t, Route as u, SchemaValidationError as v, RouteNotFoundError as y };
+
+//# sourceMappingURL=route-registration.service-D6vSwiKP.mjs.map