@webpieces/http-routing 0.4.400 → 0.4.401

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@webpieces/http-routing",
-  "version": "0.4.400",
+  "version": "0.4.401",
   "description": "Decorator-based routing with auto-wiring for WebPieces",
   "type": "commonjs",
   "main": "./src/index.js",
@@ -22,9 +22,9 @@
   },
   "dependencies": {
     "@inversifyjs/binding-decorators": "1.1.5",
-    "@webpieces/core-context": "0.4.400",
-    "@webpieces/core-util": "0.4.400",
-    "@webpieces/gcp-identity": "0.4.400",
+    "@webpieces/core-context": "0.4.401",
+    "@webpieces/core-util": "0.4.401",
+    "@webpieces/gcp-identity": "0.4.401",
     "inversify": "7.10.4",
     "jsonwebtoken": "9.0.2",
     "minimatch": "10.0.1"

package/src/RouteBuilderImpl.js

@@ -207,7 +207,7 @@ let RouteBuilderImpl = class RouteBuilderImpl {
     createRouteHandler(routeWithMeta) {
         const route = routeWithMeta.definition;
         const routeMeta = route.routeMeta;
-        log.info(`[RouteBuilder] Setting up route: ${routeMeta.httpMethod} ${routeMeta.path}`);
+        log.info(`Setting up route: ${routeMeta.httpMethod} ${routeMeta.path}`);
         // ONE chain for both HTTP and in-process — no transport tier. The fixed framework
         // filters (ErrorLogFilter, AuthFilter) are auto-installed and read the transport-neutral
         // HttpRequest, so they run identically in both.

package/src/RouteBuilderImpl.js.map

@@ -1 +1 @@
-{"version":3,"file":"RouteBuilderImpl.js","sourceRoot":"","sources":["../../../../../packages/http/http-routing/src/RouteBuilderImpl.ts"],"names":[],"mappings":"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","sourcesContent":["import { Container } from 'inversify';\nimport { RouteBuilder, RouteDefinition, FilterDefinition } from './WebAppMeta';\nimport { provideFrameworkSingleton } from '@webpieces/core-context';\nimport { RouteHandler } from './RouteHandler';\nimport { MethodMeta } from './MethodMeta';\nimport { RouteMetadata, DocumentDesign } from '@webpieces/core-util';\nimport { WpResponse, Service } from './Filter';\nimport { FilterMatcher, HttpFilter } from './FilterMatcher';\nimport { LogManager } from '@webpieces/core-util';\n\nconst log = LogManager.getLogger('RouteBuilder');\n\n/**\n * FilterWithMeta - Pairs a resolved filter instance with its definition.\n * Stores both the DI-resolved filter and the metadata needed for matching.\n */\nexport class FilterWithMeta {\n    constructor(\n        public filter: HttpFilter,\n        public definition: FilterDefinition,\n    ) {}\n}\n\n/**\n * RouteHandlerImpl - Concrete implementation of RouteHandler.\n * Wraps a resolved controller and method to invoke on each request.\n */\nexport class RouteHandlerImpl<TResult> implements RouteHandler<TResult> {\n    constructor(\n        private controller: Record<string, unknown>,\n        private method: (this: unknown, requestDto?: unknown) => Promise<TResult>,\n    ) {}\n\n    async execute(meta: MethodMeta): Promise<TResult> {\n        // Invoke the method with requestDto from meta\n        // The controller is already resolved - no DI lookup on every request!\n        const result: TResult = await this.method.call(this.controller, meta.requestDto);\n        return result;\n    }\n}\n/**\n * RouteHandlerWithMeta - Pairs a route handler with its definition.\n * Stores both the handler (which wraps the DI-resolved controller) and the route metadata.\n *\n * We use unknown for the generic type since we store different TResult types in the same Map.\n * Type safety is maintained through the generic on RouteDefinition at registration time.\n */\nexport class RouteHandlerWithMeta {\n    constructor(\n        public invokeControllerHandler: RouteHandler<unknown>,\n        public definition: RouteDefinition,\n    ) {}\n}\n\n/**\n * RouteBuilderImpl - Concrete implementation of RouteBuilder interface.\n *\n * Similar to Java WebPieces RouteBuilder, this class is responsible for:\n * 1. Registering routes with their handlers\n * 2. Registering filters with priority\n *\n * This class is explicit (not anonymous) to:\n * - Improve traceability and debugging\n * - Make the code easier to understand\n * - Enable better IDE navigation (Cmd+Click on addRoute works!)\n *\n * DI Pattern: This class is registered in webpiecesContainer via @provideFrameworkSingleton()\n * but needs appContainer to resolve filters/controllers. The container is set via\n * setContainer() after appContainer is created (late binding pattern).\n */\n@provideFrameworkSingleton()\nexport class RouteBuilderImpl implements RouteBuilder {\n    private routes: RouteHandlerWithMeta[] = [];\n    private filterRegistry: Array<FilterWithMeta> = [];\n    private container?: Container;\n\n    /**\n     * Map for O(1) route lookup by method:path.\n     * Used by both addRoute() and createRouteInvoker() for fast route access.\n     */\n    private routeMap: Map<string, RouteHandlerWithMeta> = new Map();\n\n    /**\n     * Create route key for consistent lookup.\n     * Key format: \"${METHOD}:${path}\" (e.g., \"POST:/search/item\")\n     */\n    private createRouteKey(method: string, path: string): string {\n        return `${method.toUpperCase()}:${path}`;\n    }\n\n    /**\n     * Set the DI container used for resolving filters and controllers.\n     * Called by WebpiecesCoreServer after appContainer is created.\n     *\n     * @param container - The application DI container (appContainer)\n     */\n    setContainer(container: Container): void {\n        this.container = container;\n    }\n\n    /**\n     * Register a route with the router.\n     *\n     * Uses createRouteHandlerWithMeta() to create the handler, then stores it\n     * in both the routes array and the routeMap for O(1) lookup.\n     *\n     * @param route - Route definition with controller class and method name\n     */\n    addRoute(route: RouteDefinition): void {\n        const routeWithMeta = this.createRouteHandlerWithMeta(route);\n        this.routes.push(routeWithMeta);\n\n        // Also add to map for O(1) lookup by method:path\n        const key = this.createRouteKey(\n            route.routeMeta.httpMethod,\n            route.routeMeta.path\n        );\n        this.routeMap.set(key, routeWithMeta);\n    }\n\n    /**\n     * Create RouteHandlerWithMeta from a RouteDefinition.\n     *\n     * Resolves controller from DI container ONCE and creates a handler that\n     * invokes the controller method with the request DTO.\n     *\n     * This method is used by:\n     * - addRoute() for production route registration\n     * - createRouteInvoker() for test clients (via createApiClient)\n     *\n     * @param route - Route definition with controller class and method name\n     * @returns RouteHandlerWithMeta containing the handler and route definition\n     */\n    private createRouteHandlerWithMeta<TResult = unknown>(\n        route: RouteDefinition,\n    ): RouteHandlerWithMeta {\n        if (!this.container) {\n            throw new Error('Container not set. Call setContainer() before registering routes.');\n        }\n\n        const routeMeta = route.routeMeta;\n\n        // Resolve controller instance from DI container ONCE (not on every request!)\n        const controller = this.container.get(route.controllerClass) as Record<string, unknown>;\n\n        // Get the controller method\n        const method = controller[routeMeta.methodName];\n        if (typeof method !== 'function') {\n            const controllerName = (route.controllerClass as { name?: string }).name || 'Unknown';\n            throw new Error(\n                `Method ${routeMeta.methodName} not found on controller ${controllerName}`,\n            );\n        }\n\n        const handler = new RouteHandlerImpl<TResult>(\n            controller,\n            method as (this: unknown, requestDto?: unknown) => Promise<TResult>\n        );\n\n        // Return handler with route definition\n        return new RouteHandlerWithMeta(\n            handler as RouteHandler<unknown>,\n            route,\n        );\n    }\n\n    /**\n     * Register a filter with the filter chain.\n     *\n     * Resolves the filter from DI container and pairs it with the filter definition.\n     * The definition includes pattern information used for route-specific filtering.\n     *\n     * @param filterDef - Filter definition with priority, filter class, and optional filepath pattern\n     */\n    addFilter(filterDef: FilterDefinition): void {\n        if (!this.container) {\n            throw new Error('Container not set. Call setContainer() before registering filters.');\n        }\n\n        // Resolve filter instance from DI container\n        const filter = this.container.get<HttpFilter>(filterDef.filterClass);\n\n        // Store filter with its definition\n        const filterWithMeta = new FilterWithMeta(filter, filterDef);\n        this.filterRegistry.push(filterWithMeta);\n    }\n\n    /**\n     * Get all registered routes.\n     *\n     * @returns Map of routes with handlers and definitions, keyed by \"METHOD:path\"\n     */\n    getRoutes(): RouteHandlerWithMeta[] {\n        return this.routes;\n    }\n\n    /**\n     * Get all filters sorted by priority (highest priority first).\n     *\n     * @returns Array of FilterWithMeta sorted by priority\n     */\n    getSortedFilters(): Array<FilterWithMeta> {\n        return [...this.filterRegistry].sort(\n            (a, b) => b.definition.priority - a.definition.priority,\n        );\n    }\n\n    /**\n     * Cached filter definitions for lazy route setup.\n     */\n    private cachedFilterDefinitions?: FilterDefinition[];\n\n    /**\n     * Get filter definitions, computing once and caching.\n     */\n    private getFilterDefinitions(): FilterDefinition[] {\n        if (!this.cachedFilterDefinitions) {\n            const sortedFilters = this.getSortedFilters();\n            this.cachedFilterDefinitions = sortedFilters.map((fwm) => {\n                const def = fwm.definition;\n                def.filter = fwm.filter;\n                return def;\n            });\n        }\n        return this.cachedFilterDefinitions;\n    }\n\n    /**\n     * Setup a single route by creating its filter chain.\n     * This is called lazily by createHandler() and getRouteService().\n     *\n     * Creates a Service that wraps the filter chain and controller invocation.\n     * The service is DTO-only and has no Express dependency.\n     *\n     * @param key - Route key in format \"METHOD:path\"\n     * @param routeWithMeta - Route handler with metadata\n     * @returns The service for this route\n     */\n    public createRouteHandler(\n        routeWithMeta: RouteHandlerWithMeta,\n    ): Service<MethodMeta, WpResponse<unknown>> {\n        const route = routeWithMeta.definition;\n        const routeMeta = route.routeMeta;\n\n        log.info(`[RouteBuilder] Setting up route: ${routeMeta.httpMethod} ${routeMeta.path}`);\n\n        // ONE chain for both HTTP and in-process — no transport tier. The fixed framework\n        // filters (ErrorLogFilter, AuthFilter) are auto-installed and read the transport-neutral\n        // HttpRequest, so they run identically in both.\n        const filterDefinitions = this.getFilterDefinitions();\n\n        // Find matching filters for this route\n        const matchingFilters = FilterMatcher.findMatchingFilters(\n            route.controllerFilepath,\n            filterDefinitions,\n        );\n\n        // Create service that wraps the controller execution\n        const controllerService: Service<MethodMeta, WpResponse<unknown>> = {\n            invoke: async (meta: MethodMeta): Promise<WpResponse<unknown>> => {\n                const result = await routeWithMeta.invokeControllerHandler.execute(meta);\n                // A void endpoint (e.g. a @PubSub cloud-task handler returning Promise<void>)\n                // yields undefined; coerce to {} so the response is a non-null JSON body\n                // (downstream LogApiCall/serialization require one), mirroring `result ?? {}`.\n                return new WpResponse(result ?? {});\n            },\n        };\n\n        if (matchingFilters.length === 0) {\n            throw new Error(\"No filters found for route — the framework auto-installs ErrorLogFilter + AuthFilter, so this indicates a wiring problem.\");\n        }\n\n        // Chain filters: highest priority (first in array) should run first (be outermost)\n        // Build from innermost (lowest priority) to outermost (highest priority)\n        // Start with controller, then wrap with filters in reverse priority order\n        let service: Service<MethodMeta, WpResponse<unknown>> = controllerService;\n        for (let i = matchingFilters.length - 1; i >= 0; i--) {\n            service = matchingFilters[i].chainService(service);\n        }\n\n        return service;\n    }\n\n    /**\n     * Create an invoker function for a route (for testing via createApiClient).\n     * Uses routeMap for O(1) lookup, sets up the filter chain ONCE,\n     * and returns a Service that can be called multiple times without\n     * recreating the filter chain.\n     *\n     * This method is called by WebpiecesServer.createApiClient() during proxy setup.\n     * The returned Service is stored as the proxy method and invoked on each call.\n     *\n     * @param method - HTTP method (GET, POST, etc.)\n     * @param path - URL path\n     * @returns A Service that invokes the route\n     */\n    createRouteInvoker(method: string, path: string): Service<MethodMeta, WpResponse<unknown>> {\n        // Use routeMap for O(1) lookup (not linear search!)\n        const key = this.createRouteKey(method, path);\n        const routeWithMeta = this.routeMap.get(key);\n\n        if (!routeWithMeta) {\n            throw new Error(`Route not found: ${method} ${path}`);\n        }\n\n        // Setup filter chain ONCE (not on every invocation!). Same chain as HTTP — auth included.\n        return this.createRouteHandler(routeWithMeta);\n    }\n\n    /**\n     * Look up the RouteMetadata (incl. authMeta) for a registered route by method+path.\n     * Used to build a MethodMeta for an in-process dispatch (e.g. a delivered cloud\n     * task) so the filter chain sees the same routeMeta production HTTP would.\n     *\n     * @returns the route's RouteMetadata, or undefined if no route is registered.\n     */\n    getRouteMeta(method: string, path: string): RouteMetadata | undefined {\n        const key = this.createRouteKey(method, path);\n        return this.routeMap.get(key)?.definition.routeMeta;\n    }\n}\n"]}
+{"version":3,"file":"RouteBuilderImpl.js","sourceRoot":"","sources":["../../../../../packages/http/http-routing/src/RouteBuilderImpl.ts"],"names":[],"mappings":"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","sourcesContent":["import { Container } from 'inversify';\nimport { RouteBuilder, RouteDefinition, FilterDefinition } from './WebAppMeta';\nimport { provideFrameworkSingleton } from '@webpieces/core-context';\nimport { RouteHandler } from './RouteHandler';\nimport { MethodMeta } from './MethodMeta';\nimport { RouteMetadata, DocumentDesign } from '@webpieces/core-util';\nimport { WpResponse, Service } from './Filter';\nimport { FilterMatcher, HttpFilter } from './FilterMatcher';\nimport { LogManager } from '@webpieces/core-util';\n\nconst log = LogManager.getLogger('RouteBuilder');\n\n/**\n * FilterWithMeta - Pairs a resolved filter instance with its definition.\n * Stores both the DI-resolved filter and the metadata needed for matching.\n */\nexport class FilterWithMeta {\n    constructor(\n        public filter: HttpFilter,\n        public definition: FilterDefinition,\n    ) {}\n}\n\n/**\n * RouteHandlerImpl - Concrete implementation of RouteHandler.\n * Wraps a resolved controller and method to invoke on each request.\n */\nexport class RouteHandlerImpl<TResult> implements RouteHandler<TResult> {\n    constructor(\n        private controller: Record<string, unknown>,\n        private method: (this: unknown, requestDto?: unknown) => Promise<TResult>,\n    ) {}\n\n    async execute(meta: MethodMeta): Promise<TResult> {\n        // Invoke the method with requestDto from meta\n        // The controller is already resolved - no DI lookup on every request!\n        const result: TResult = await this.method.call(this.controller, meta.requestDto);\n        return result;\n    }\n}\n/**\n * RouteHandlerWithMeta - Pairs a route handler with its definition.\n * Stores both the handler (which wraps the DI-resolved controller) and the route metadata.\n *\n * We use unknown for the generic type since we store different TResult types in the same Map.\n * Type safety is maintained through the generic on RouteDefinition at registration time.\n */\nexport class RouteHandlerWithMeta {\n    constructor(\n        public invokeControllerHandler: RouteHandler<unknown>,\n        public definition: RouteDefinition,\n    ) {}\n}\n\n/**\n * RouteBuilderImpl - Concrete implementation of RouteBuilder interface.\n *\n * Similar to Java WebPieces RouteBuilder, this class is responsible for:\n * 1. Registering routes with their handlers\n * 2. Registering filters with priority\n *\n * This class is explicit (not anonymous) to:\n * - Improve traceability and debugging\n * - Make the code easier to understand\n * - Enable better IDE navigation (Cmd+Click on addRoute works!)\n *\n * DI Pattern: This class is registered in webpiecesContainer via @provideFrameworkSingleton()\n * but needs appContainer to resolve filters/controllers. The container is set via\n * setContainer() after appContainer is created (late binding pattern).\n */\n@provideFrameworkSingleton()\nexport class RouteBuilderImpl implements RouteBuilder {\n    private routes: RouteHandlerWithMeta[] = [];\n    private filterRegistry: Array<FilterWithMeta> = [];\n    private container?: Container;\n\n    /**\n     * Map for O(1) route lookup by method:path.\n     * Used by both addRoute() and createRouteInvoker() for fast route access.\n     */\n    private routeMap: Map<string, RouteHandlerWithMeta> = new Map();\n\n    /**\n     * Create route key for consistent lookup.\n     * Key format: \"${METHOD}:${path}\" (e.g., \"POST:/search/item\")\n     */\n    private createRouteKey(method: string, path: string): string {\n        return `${method.toUpperCase()}:${path}`;\n    }\n\n    /**\n     * Set the DI container used for resolving filters and controllers.\n     * Called by WebpiecesCoreServer after appContainer is created.\n     *\n     * @param container - The application DI container (appContainer)\n     */\n    setContainer(container: Container): void {\n        this.container = container;\n    }\n\n    /**\n     * Register a route with the router.\n     *\n     * Uses createRouteHandlerWithMeta() to create the handler, then stores it\n     * in both the routes array and the routeMap for O(1) lookup.\n     *\n     * @param route - Route definition with controller class and method name\n     */\n    addRoute(route: RouteDefinition): void {\n        const routeWithMeta = this.createRouteHandlerWithMeta(route);\n        this.routes.push(routeWithMeta);\n\n        // Also add to map for O(1) lookup by method:path\n        const key = this.createRouteKey(\n            route.routeMeta.httpMethod,\n            route.routeMeta.path\n        );\n        this.routeMap.set(key, routeWithMeta);\n    }\n\n    /**\n     * Create RouteHandlerWithMeta from a RouteDefinition.\n     *\n     * Resolves controller from DI container ONCE and creates a handler that\n     * invokes the controller method with the request DTO.\n     *\n     * This method is used by:\n     * - addRoute() for production route registration\n     * - createRouteInvoker() for test clients (via createApiClient)\n     *\n     * @param route - Route definition with controller class and method name\n     * @returns RouteHandlerWithMeta containing the handler and route definition\n     */\n    private createRouteHandlerWithMeta<TResult = unknown>(\n        route: RouteDefinition,\n    ): RouteHandlerWithMeta {\n        if (!this.container) {\n            throw new Error('Container not set. Call setContainer() before registering routes.');\n        }\n\n        const routeMeta = route.routeMeta;\n\n        // Resolve controller instance from DI container ONCE (not on every request!)\n        const controller = this.container.get(route.controllerClass) as Record<string, unknown>;\n\n        // Get the controller method\n        const method = controller[routeMeta.methodName];\n        if (typeof method !== 'function') {\n            const controllerName = (route.controllerClass as { name?: string }).name || 'Unknown';\n            throw new Error(\n                `Method ${routeMeta.methodName} not found on controller ${controllerName}`,\n            );\n        }\n\n        const handler = new RouteHandlerImpl<TResult>(\n            controller,\n            method as (this: unknown, requestDto?: unknown) => Promise<TResult>\n        );\n\n        // Return handler with route definition\n        return new RouteHandlerWithMeta(\n            handler as RouteHandler<unknown>,\n            route,\n        );\n    }\n\n    /**\n     * Register a filter with the filter chain.\n     *\n     * Resolves the filter from DI container and pairs it with the filter definition.\n     * The definition includes pattern information used for route-specific filtering.\n     *\n     * @param filterDef - Filter definition with priority, filter class, and optional filepath pattern\n     */\n    addFilter(filterDef: FilterDefinition): void {\n        if (!this.container) {\n            throw new Error('Container not set. Call setContainer() before registering filters.');\n        }\n\n        // Resolve filter instance from DI container\n        const filter = this.container.get<HttpFilter>(filterDef.filterClass);\n\n        // Store filter with its definition\n        const filterWithMeta = new FilterWithMeta(filter, filterDef);\n        this.filterRegistry.push(filterWithMeta);\n    }\n\n    /**\n     * Get all registered routes.\n     *\n     * @returns Map of routes with handlers and definitions, keyed by \"METHOD:path\"\n     */\n    getRoutes(): RouteHandlerWithMeta[] {\n        return this.routes;\n    }\n\n    /**\n     * Get all filters sorted by priority (highest priority first).\n     *\n     * @returns Array of FilterWithMeta sorted by priority\n     */\n    getSortedFilters(): Array<FilterWithMeta> {\n        return [...this.filterRegistry].sort(\n            (a, b) => b.definition.priority - a.definition.priority,\n        );\n    }\n\n    /**\n     * Cached filter definitions for lazy route setup.\n     */\n    private cachedFilterDefinitions?: FilterDefinition[];\n\n    /**\n     * Get filter definitions, computing once and caching.\n     */\n    private getFilterDefinitions(): FilterDefinition[] {\n        if (!this.cachedFilterDefinitions) {\n            const sortedFilters = this.getSortedFilters();\n            this.cachedFilterDefinitions = sortedFilters.map((fwm) => {\n                const def = fwm.definition;\n                def.filter = fwm.filter;\n                return def;\n            });\n        }\n        return this.cachedFilterDefinitions;\n    }\n\n    /**\n     * Setup a single route by creating its filter chain.\n     * This is called lazily by createHandler() and getRouteService().\n     *\n     * Creates a Service that wraps the filter chain and controller invocation.\n     * The service is DTO-only and has no Express dependency.\n     *\n     * @param key - Route key in format \"METHOD:path\"\n     * @param routeWithMeta - Route handler with metadata\n     * @returns The service for this route\n     */\n    public createRouteHandler(\n        routeWithMeta: RouteHandlerWithMeta,\n    ): Service<MethodMeta, WpResponse<unknown>> {\n        const route = routeWithMeta.definition;\n        const routeMeta = route.routeMeta;\n\n        log.info(`Setting up route: ${routeMeta.httpMethod} ${routeMeta.path}`);\n\n        // ONE chain for both HTTP and in-process — no transport tier. The fixed framework\n        // filters (ErrorLogFilter, AuthFilter) are auto-installed and read the transport-neutral\n        // HttpRequest, so they run identically in both.\n        const filterDefinitions = this.getFilterDefinitions();\n\n        // Find matching filters for this route\n        const matchingFilters = FilterMatcher.findMatchingFilters(\n            route.controllerFilepath,\n            filterDefinitions,\n        );\n\n        // Create service that wraps the controller execution\n        const controllerService: Service<MethodMeta, WpResponse<unknown>> = {\n            invoke: async (meta: MethodMeta): Promise<WpResponse<unknown>> => {\n                const result = await routeWithMeta.invokeControllerHandler.execute(meta);\n                // A void endpoint (e.g. a @PubSub cloud-task handler returning Promise<void>)\n                // yields undefined; coerce to {} so the response is a non-null JSON body\n                // (downstream LogApiCall/serialization require one), mirroring `result ?? {}`.\n                return new WpResponse(result ?? {});\n            },\n        };\n\n        if (matchingFilters.length === 0) {\n            throw new Error(\"No filters found for route — the framework auto-installs ErrorLogFilter + AuthFilter, so this indicates a wiring problem.\");\n        }\n\n        // Chain filters: highest priority (first in array) should run first (be outermost)\n        // Build from innermost (lowest priority) to outermost (highest priority)\n        // Start with controller, then wrap with filters in reverse priority order\n        let service: Service<MethodMeta, WpResponse<unknown>> = controllerService;\n        for (let i = matchingFilters.length - 1; i >= 0; i--) {\n            service = matchingFilters[i].chainService(service);\n        }\n\n        return service;\n    }\n\n    /**\n     * Create an invoker function for a route (for testing via createApiClient).\n     * Uses routeMap for O(1) lookup, sets up the filter chain ONCE,\n     * and returns a Service that can be called multiple times without\n     * recreating the filter chain.\n     *\n     * This method is called by WebpiecesServer.createApiClient() during proxy setup.\n     * The returned Service is stored as the proxy method and invoked on each call.\n     *\n     * @param method - HTTP method (GET, POST, etc.)\n     * @param path - URL path\n     * @returns A Service that invokes the route\n     */\n    createRouteInvoker(method: string, path: string): Service<MethodMeta, WpResponse<unknown>> {\n        // Use routeMap for O(1) lookup (not linear search!)\n        const key = this.createRouteKey(method, path);\n        const routeWithMeta = this.routeMap.get(key);\n\n        if (!routeWithMeta) {\n            throw new Error(`Route not found: ${method} ${path}`);\n        }\n\n        // Setup filter chain ONCE (not on every invocation!). Same chain as HTTP — auth included.\n        return this.createRouteHandler(routeWithMeta);\n    }\n\n    /**\n     * Look up the RouteMetadata (incl. authMeta) for a registered route by method+path.\n     * Used to build a MethodMeta for an in-process dispatch (e.g. a delivered cloud\n     * task) so the filter chain sees the same routeMeta production HTTP would.\n     *\n     * @returns the route's RouteMetadata, or undefined if no route is registered.\n     */\n    getRouteMeta(method: string, path: string): RouteMetadata | undefined {\n        const key = this.createRouteKey(method, path);\n        return this.routeMap.get(key)?.definition.routeMeta;\n    }\n}\n"]}