@ebarahona/loopback-transport-core 1.0.0 → 1.2.0

package/dist/registry/handler-registry.d.ts

@@ -1,48 +1,119 @@
-import { Application } from '@loopback/core';
-import { MessageHandler } from '../interfaces';
+import { Application, type Constructor } from '@loopback/core';
+import type { HandlerKind } from '../discovery';
+import type { HandlerOptions } from '../decorators';
+import type { MessageHandler } from '../interfaces';
 /**
- * Discovers @messageHandler and @eventHandler decorated methods
- * from controllers and registers them with the appropriate transport server.
+ * Internal registry entry tracking both the runtime handler function
+ * and the metadata required to construct a {@link RegisteredHandler}
+ * view for cross-cutting wrappers and the {@link DiscoveryService}.
+ *
+ * @internal
+ */
+export interface RegistryEntry {
+    /** Original (unnormalized) pattern as supplied by the discoverer. */
+    readonly pattern: string | Record<string, unknown>;
+    /** Transport server tag (`'*'` for wildcard). */
+    readonly transport: string;
+    /** Handler kind. */
+    readonly kind: HandlerKind;
+    /** Controller class that declared this handler. */
+    readonly controllerClass: Constructor<unknown>;
+    /** Method name on the controller prototype. */
+    readonly methodName: string;
+    /** Id of the discoverer that produced this entry. */
+    readonly discovererId: string;
+    /** Discoverer-specific handler options. */
+    readonly options?: HandlerOptions;
+    /**
+     * Live handler function. Mutable so the lifecycle observer can swap
+     * in the wrapped version between discovery and server-binding.
+     */
+    handler: MessageHandler;
+}
+/**
+ * Discovers transport handlers from controllers via every bound
+ * {@link HandlerDiscoverer} and registers them with the appropriate
+ * transport server.
+ *
+ * The two built-in vocabularies (`@messageHandler` and `@eventHandler`)
+ * are implemented as default discoverers bound by `TransportComponent`.
+ * Plugins (gRPC, cron, WebSocket, etc.) contribute additional decorator
+ * vocabularies by binding their own `HandlerDiscoverer` implementations
+ * under `TransportBindings.tags.HANDLER_DISCOVERER`.
  *
  * This class does NOT run in the constructor. It is invoked by
- * TransportBooter after all controllers are registered.
+ * `TransportBooter` after all controllers are registered.
  *
  * Handler invocations use per-message child contexts for concurrency
  * safety. The application context is never mutated per-message.
  *
- * Context lifetime extends until the handler result (including Observable
- * streams) fully completes, errors, or times out.
+ * Context lifetime extends until the handler result (including
+ * Observable streams) fully completes, errors, or times out.
+ *
+ * @public
  */
 export declare class HandlerRegistry {
     /**
      * Registry keyed by `transport::pattern` to support the same pattern
-     * on different transports without collision.
+     * on different transports without collision. Each value is the chain
+     * of entries for that pattern (multiple allowed for event fan-out).
      */
-    private readonly handlers;
+    private readonly entries;
     private discovered;
     /**
      * Scan all controllers in the application for transport decorators
      * and register the handlers.
      *
+     * Discovers handlers by consulting every `HandlerDiscoverer` bound
+     * under `TransportBindings.tags.HANDLER_DISCOVERER`, including the
+     * built-in `MessageHandlerDiscoverer` and `EventHandlerDiscoverer`
+     * registered by `TransportComponent`, plus any plugin-contributed
+     * discoverers.
+     *
      * Idempotent: clears previously discovered handlers before scanning.
+     *
+     * @public
+     * @param app - The LoopBack application instance.
+     * @returns Resolves once every controller has been scanned.
+     * @throws TransportConfigError When the same pattern is targeted by
+     *   both `@messageHandler` and `@eventHandler`, or by two
+     *   `@messageHandler` declarations.
      */
     discoverHandlers(app: Application): Promise<void>;
     /**
      * Bind discovered handlers to the registered transport servers.
-     * Throws if discovery has not been run.
      *
-     * Handles precedence: transport-specific handlers override wildcard
-     * handlers for the same pattern on that transport's server.
+     * Precedence rules:
+     *
+     * - Request handlers: transport-specific overrides wildcard (only one
+     *   per pattern survives).
+     * - Event handlers: both specific and wildcard run (fan-out).
+     *
+     * @public
+     * @param app - The LoopBack application instance.
+     * @returns Resolves once every handler has been bound.
+     * @throws TransportConfigError When `discoverHandlers()` has not been
+     *   called first, or when a transport server binding is missing the
+     *   `TRANSPORT_NAME_TAG` tag.
      */
     bindToServers(app: Application): Promise<void>;
     /**
-     * Get all discovered handlers.
+     * Get all discovered handlers. The returned map is a defensive copy.
+     *
+     * @public
+     * @returns A read-only snapshot of every registered pattern and its
+     *   handler chain.
      */
     getHandlers(): ReadonlyMap<string, readonly MessageHandler[]>;
     /**
-     * Whether discovery has been run.
+     * Whether {@link discoverHandlers} has been run.
+     *
+     * @public
      */
     isDiscovered(): boolean;
+    /** @internal Package-scoped accessor used by TransportObserver to build the DiscoveryService snapshot. */
+    _getEntries(): IterableIterator<RegistryEntry>;
+    private iterateEntries;
     /**
      * Build the registry key from transport and raw pattern.
      * Normalizes the pattern (sorts object keys) before keying.
@@ -53,21 +124,20 @@ export declare class HandlerRegistry {
      * Extract the pattern portion from a registry key.
      */
     private extractPattern;
-    private scanMessageHandlers;
-    private scanEventHandlers;
     /**
-     * Shared scanner for both @messageHandler and @eventHandler metadata.
-     * The isEvent flag controls duplicate/chaining rules.
+     * Convert a `DiscoveredHandler` into a runtime `MessageHandler`,
+     * applying validation rules (no mixed kinds per pattern, no duplicate
+     * request handlers) before inserting into the registry.
      */
-    private scanHandlers;
+    private registerDiscovered;
     /**
-     * Create a handler function that invokes the controller method through
-     * LoopBack's native invocation pipeline.
+     * Create a handler function that invokes the controller method
+     * through LoopBack's native invocation pipeline.
      *
      * Each invocation creates a uniquely named child Context from the
-     * application context. Per-message bindings (payload, transport context)
-     * are scoped to the child context and cannot collide with concurrent
-     * messages.
+     * application context. Per-message bindings (payload, transport
+     * context) are scoped to the child context and cannot collide with
+     * concurrent messages.
      *
      * The child context lifetime extends until the handler result fully
      * resolves. For Observable results, the context stays open until the

package/dist/registry/handler-registry.js

@@ -5,13 +5,17 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
     else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
     return c > 3 && r && Object.defineProperty(target, key, r), r;
 };
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.HandlerRegistry = void 0;
 const core_1 = require("@loopback/core");
 const crypto_1 = require("crypto");
-const debug_1 = require("debug");
+const debug_1 = __importDefault(require("debug"));
 const rxjs_1 = require("rxjs");
-const decorators_1 = require("../decorators");
+const discovery_1 = require("../discovery");
+const errors_1 = require("../helpers/errors");
 const keys_1 = require("../keys");
 const utils_1 = require("../utils");
 const debug = (0, debug_1.default)('loopback:transport:registry');
@@ -21,77 +25,220 @@ const debug = (0, debug_1.default)('loopback:transport:registry');
  */
 const KEY_SEPARATOR = '::';
 /**
- * Discovers @messageHandler and @eventHandler decorated methods
- * from controllers and registers them with the appropriate transport server.
+ * Discovers transport handlers from controllers via every bound
+ * {@link HandlerDiscoverer} and registers them with the appropriate
+ * transport server.
+ *
+ * The two built-in vocabularies (`@messageHandler` and `@eventHandler`)
+ * are implemented as default discoverers bound by `TransportComponent`.
+ * Plugins (gRPC, cron, WebSocket, etc.) contribute additional decorator
+ * vocabularies by binding their own `HandlerDiscoverer` implementations
+ * under `TransportBindings.tags.HANDLER_DISCOVERER`.
  *
  * This class does NOT run in the constructor. It is invoked by
- * TransportBooter after all controllers are registered.
+ * `TransportBooter` after all controllers are registered.
  *
  * Handler invocations use per-message child contexts for concurrency
  * safety. The application context is never mutated per-message.
  *
- * Context lifetime extends until the handler result (including Observable
- * streams) fully completes, errors, or times out.
+ * Context lifetime extends until the handler result (including
+ * Observable streams) fully completes, errors, or times out.
+ *
+ * @public
  */
 let HandlerRegistry = class HandlerRegistry {
-    constructor() {
-        /**
-         * Registry keyed by `transport::pattern` to support the same pattern
-         * on different transports without collision.
-         */
-        this.handlers = new Map();
-        this.discovered = false;
-    }
+    /**
+     * Registry keyed by `transport::pattern` to support the same pattern
+     * on different transports without collision. Each value is the chain
+     * of entries for that pattern (multiple allowed for event fan-out).
+     */
+    entries = new Map();
+    discovered = false;
     /**
      * Scan all controllers in the application for transport decorators
      * and register the handlers.
      *
+     * Discovers handlers by consulting every `HandlerDiscoverer` bound
+     * under `TransportBindings.tags.HANDLER_DISCOVERER`, including the
+     * built-in `MessageHandlerDiscoverer` and `EventHandlerDiscoverer`
+     * registered by `TransportComponent`, plus any plugin-contributed
+     * discoverers.
+     *
      * Idempotent: clears previously discovered handlers before scanning.
+     *
+     * @public
+     * @param app - The LoopBack application instance.
+     * @returns Resolves once every controller has been scanned.
+     * @throws TransportConfigError When the same pattern is targeted by
+     *   both `@messageHandler` and `@eventHandler`, or by two
+     *   `@messageHandler` declarations.
      */
     async discoverHandlers(app) {
-        this.handlers.clear();
+        this.entries.clear();
         this.discovered = false;
+        const discovererBindings = app.findByTag(keys_1.HANDLER_DISCOVERER_TAG);
+        const discoverers = [];
+        for (const binding of discovererBindings) {
+            discoverers.push(await app.get(binding.key));
+        }
         const controllerBindings = app.findByTag('controller');
-        debug('scanning %d controllers for transport handlers', controllerBindings.length);
+        debug('scanning %d controllers with %d discoverers', controllerBindings.length, discoverers.length);
+        const perDiscovererCounts = new Map();
         for (const binding of controllerBindings) {
             const controllerClass = binding.valueConstructor;
             if (!controllerClass)
                 continue;
             const bindingKey = binding.key;
-            this.scanMessageHandlers(controllerClass, bindingKey, app);
-            this.scanEventHandlers(controllerClass, bindingKey, app);
+            for (const discoverer of discoverers) {
+                const found = await discoverer.discover(controllerClass);
+                if (found.length === 0)
+                    continue;
+                perDiscovererCounts.set(discoverer.id, (perDiscovererCounts.get(discoverer.id) ?? 0) + found.length);
+                for (const item of found) {
+                    this.registerDiscovered(item, controllerClass, bindingKey, app, discoverer.id);
+                }
+            }
         }
         this.discovered = true;
-        debug('discovered %d transport handlers', this.handlers.size);
+        if (debug.enabled) {
+            for (const [id, count] of perDiscovererCounts) {
+                debug('discoverer [%s] contributed %d handlers', id, count);
+            }
+            debug('discovered %d transport handlers total', this.entries.size);
+        }
     }
     /**
      * Bind discovered handlers to the registered transport servers.
-     * Throws if discovery has not been run.
      *
-     * Handles precedence: transport-specific handlers override wildcard
-     * handlers for the same pattern on that transport's server.
+     * Precedence rules:
+     *
+     * - Request handlers: transport-specific overrides wildcard (only one
+     *   per pattern survives).
+     * - Event handlers: both specific and wildcard run (fan-out).
+     *
+     * @public
+     * @param app - The LoopBack application instance.
+     * @returns Resolves once every handler has been bound.
+     * @throws TransportConfigError When `discoverHandlers()` has not been
+     *   called first, or when a transport server binding is missing the
+     *   `TRANSPORT_NAME_TAG` tag.
      */
     async bindToServers(app) {
         if (!this.discovered) {
-            throw new Error('Cannot bind handlers to servers: discoverHandlers() has not been called.');
+            throw new errors_1.TransportConfigError('Cannot bind handlers to servers: discoverHandlers() has not been called.');
         }
         const serverBindings = app.findByTag(keys_1.TRANSPORT_SERVER_TAG);
+        // Boot-time validation: surface misconfigurations loudly before any
+        // handler is bound to a server. Four guards run here:
+        //   1. Handlers referencing unknown transports.
+        //   2. Handlers exist but no transport servers registered.
+        //   3. Duplicate NAME tags across TransportServer bindings.
+        //   4. TransportServer binding without a NAME tag.
+        let strictBinding = true;
+        if (app.isBound(keys_1.TransportBindings.STRICT_BINDING)) {
+            strictBinding = await app.get(keys_1.TransportBindings.STRICT_BINDING);
+        }
+        // Build the set of known transport names and detect duplicate NAME
+        // tags (Guard 3) and missing NAME tags (Guard 4) in a single pass.
+        const knownTransports = new Set();
+        const nameToBindingKeys = new Map();
         for (const serverBinding of serverBindings) {
+            const tag = serverBinding.tagMap?.[keys_1.TRANSPORT_NAME_TAG];
+            if (typeof tag !== 'string' || tag.length === 0) {
+                debug('%s is registered as a TransportServer but has no NAME tag; the server is skipped during binding and will not receive handlers (the lifecycle observer also skips it during startup)', String(serverBinding.key));
+                continue;
+            }
+            knownTransports.add(tag);
+            const list = nameToBindingKeys.get(tag) ?? [];
+            list.push(String(serverBinding.key));
+            nameToBindingKeys.set(tag, list);
+        }
+        // Guard 3: duplicate NAME tags. Always throws regardless of strict mode.
+        for (const [name, keys] of nameToBindingKeys) {
+            if (keys.length > 1) {
+                throw new errors_1.TransportConfigError(`duplicate transport name "${name}": multiple TransportServer ` +
+                    `bindings tagged with the same NAME (${keys.join(', ')}). ` +
+                    'Each transport must have a unique name.');
+            }
+        }
+        // Guard 2: no transport servers but handlers exist. Always warns.
+        if (serverBindings.length === 0 && this.entries.size > 0) {
+            let handlerCount = 0;
+            for (const chain of this.entries.values())
+                handlerCount += chain.length;
+            debug('no transport servers registered but %d handlers are bound; handlers will not receive events', handlerCount);
+        }
+        // Guard 1: handlers referencing unknown transports.
+        // Group orphaned entries by transport name for the error/log message.
+        const orphansByTransport = new Map();
+        for (const chain of this.entries.values()) {
+            for (const entry of chain) {
+                if (entry.transport === undefined || entry.transport === '*')
+                    continue;
+                if (knownTransports.has(entry.transport))
+                    continue;
+                const list = orphansByTransport.get(entry.transport) ?? [];
+                list.push({
+                    controllerName: entry.controllerClass.name,
+                    methodName: entry.methodName,
+                    pattern: (0, utils_1.normalizePattern)(entry.pattern),
+                    discovererId: entry.discovererId,
+                });
+                orphansByTransport.set(entry.transport, list);
+            }
+        }
+        if (orphansByTransport.size > 0) {
+            const knownList = knownTransports.size === 0
+                ? '(none)'
+                : Array.from(knownTransports).join(', ');
+            const summaryParts = [];
+            for (const [name, list] of orphansByTransport) {
+                summaryParts.push(`${name} (${list.length} handlers)`);
+            }
+            const detailLines = [];
+            for (const [, list] of orphansByTransport) {
+                for (const o of list) {
+                    detailLines.push(`    - ${o.controllerName}.${o.methodName} on pattern "${o.pattern}" (discoverer "${o.discovererId}")`);
+                }
+            }
+            const message = `handlers reference unknown transport(s): ${summaryParts.join(', ')}.\n` +
+                `  Known transports: ${knownList}\n` +
+                `  Orphaned handlers:\n${detailLines.join('\n')}`;
+            if (strictBinding) {
+                throw new errors_1.TransportConfigError(message);
+            }
+            for (const [name, list] of orphansByTransport) {
+                const perTransportDetails = list
+                    .map(o => `    - ${o.controllerName}.${o.methodName} on pattern "${o.pattern}" (discoverer "${o.discovererId}")`)
+                    .join('\n');
+                debug('handlers reference unknown transport "%s" (%d handlers).\n  Known transports: %s\n  Orphaned handlers:\n%s', name, list.length, knownList, perTransportDetails);
+            }
+        }
+        for (const serverBinding of serverBindings) {
+            const tag = serverBinding.tagMap?.[keys_1.TRANSPORT_NAME_TAG];
+            if (typeof tag !== 'string' || tag.length === 0) {
+                // Guard 4 already emitted a debug warning above; only wildcard
+                // handlers can ever reach this server, so skip the routing loop.
+                continue;
+            }
+            const transportName = tag;
             const server = await app.get(serverBinding.key);
-            const transportName = serverBinding.tagMap?.[keys_1.TRANSPORT_NAME_TAG];
             // Collect handlers for this server.
             // Precedence rules differ by handler type:
             // - Request handlers: specific overrides wildcard (only one per pattern)
             // - Event handlers: both specific and wildcard run (fan-out)
             const boundRequestPatterns = new Set();
             // First pass: transport-specific handlers
-            for (const [registryKey, handlers] of this.handlers) {
-                if (handlers[0].transport && handlers[0].transport === transportName) {
+            for (const [registryKey, entryChain] of this.entries) {
+                const first = entryChain[0];
+                if (!first)
+                    continue;
+                if (first.transport !== '*' && first.transport === transportName) {
                     const pattern = this.extractPattern(registryKey);
-                    for (const handler of handlers) {
-                        server.addHandler(pattern, handler);
+                    for (const entry of entryChain) {
+                        server.addHandler(pattern, entry.handler);
                     }
-                    if (!handlers[0].isEventHandler) {
+                    if (first.kind !== discovery_1.HANDLER_KIND_EVENT) {
                         boundRequestPatterns.add(pattern);
                     }
                     debug('bound handler [%s] to transport [%s] (specific)', pattern, transportName);
@@ -100,35 +247,56 @@ let HandlerRegistry = class HandlerRegistry {
             // Second pass: wildcard handlers
             // - Request handlers: skip if transport-specific already bound
             // - Event handlers: always bind (fan-out semantics)
-            for (const [registryKey, handlers] of this.handlers) {
-                if (!handlers[0].transport) {
+            for (const [registryKey, entryChain] of this.entries) {
+                const first = entryChain[0];
+                if (!first)
+                    continue;
+                if (first.transport === '*') {
                     const pattern = this.extractPattern(registryKey);
-                    if (handlers[0].isEventHandler || !boundRequestPatterns.has(pattern)) {
-                        for (const handler of handlers) {
-                            server.addHandler(pattern, handler);
+                    if (first.kind === discovery_1.HANDLER_KIND_EVENT ||
+                        !boundRequestPatterns.has(pattern)) {
+                        for (const entry of entryChain) {
+                            server.addHandler(pattern, entry.handler);
                         }
-                        debug('bound handler [%s] to transport [%s] (wildcard)', pattern, transportName ?? 'default');
+                        debug('bound handler [%s] to transport [%s] (wildcard)', pattern, transportName);
                     }
                 }
             }
         }
     }
     /**
-     * Get all discovered handlers.
+     * Get all discovered handlers. The returned map is a defensive copy.
+     *
+     * @public
+     * @returns A read-only snapshot of every registered pattern and its
+     *   handler chain.
      */
     getHandlers() {
         const copy = new Map();
-        for (const [key, handlers] of this.handlers) {
-            copy.set(key, [...handlers]);
+        for (const [key, entries] of this.entries) {
+            copy.set(key, entries.map(e => e.handler));
         }
         return copy;
     }
     /**
-     * Whether discovery has been run.
+     * Whether {@link discoverHandlers} has been run.
+     *
+     * @public
      */
     isDiscovered() {
         return this.discovered;
     }
+    /** @internal Package-scoped accessor used by TransportObserver to build the DiscoveryService snapshot. */
+    _getEntries() {
+        return this.iterateEntries();
+    }
+    *iterateEntries() {
+        for (const chain of this.entries.values()) {
+            for (const entry of chain) {
+                yield entry;
+            }
+        }
+    }
     /**
      * Build the registry key from transport and raw pattern.
      * Normalizes the pattern (sorts object keys) before keying.
@@ -146,56 +314,77 @@ let HandlerRegistry = class HandlerRegistry {
             ? key.slice(separatorIndex + KEY_SEPARATOR.length)
             : key;
     }
-    scanMessageHandlers(controllerClass, controllerBindingKey, app) {
-        this.scanHandlers(controllerClass, controllerBindingKey, app, decorators_1.MESSAGE_HANDLER_METADATA.key, false);
-    }
-    scanEventHandlers(controllerClass, controllerBindingKey, app) {
-        this.scanHandlers(controllerClass, controllerBindingKey, app, decorators_1.EVENT_HANDLER_METADATA.key, true);
-    }
     /**
-     * Shared scanner for both @messageHandler and @eventHandler metadata.
-     * The isEvent flag controls duplicate/chaining rules.
+     * Convert a `DiscoveredHandler` into a runtime `MessageHandler`,
+     * applying validation rules (no mixed kinds per pattern, no duplicate
+     * request handlers) before inserting into the registry.
      */
-    scanHandlers(controllerClass, controllerBindingKey, app, metadataKey, isEvent) {
-        const methods = core_1.MetadataInspector.getAllMethodMetadata(metadataKey, controllerClass.prototype);
-        if (!methods)
-            return;
-        const decoratorName = isEvent ? '@eventHandler' : '@messageHandler';
-        for (const [methodName, metadata] of Object.entries(methods)) {
-            const key = this.buildKey(metadata.transport, metadata.pattern);
-            const existing = this.handlers.get(key);
-            // Reject mixed handler types on the same pattern
-            if (existing && existing[0].isEventHandler !== isEvent) {
-                throw new Error(`Cannot mix @messageHandler and @eventHandler for pattern: ${(0, utils_1.normalizePattern)(metadata.pattern)}. ` +
-                    'A pattern must be exclusively request/response or event.');
-            }
-            // Reject duplicate request/response handlers
-            if (existing && !isEvent) {
-                throw new Error(`Duplicate @messageHandler for pattern: ${(0, utils_1.normalizePattern)(metadata.pattern)}. ` +
-                    'Only one request/response handler per pattern is allowed.');
-            }
-            const handler = this.createHandler(controllerBindingKey, methodName, app);
-            handler.isEventHandler = isEvent;
-            handler.transport = metadata.transport;
-            handler.extras = metadata.extras;
-            if (existing) {
-                existing.push(handler);
-                debug('chained %s [%s] on %s.%s', decoratorName, (0, utils_1.normalizePattern)(metadata.pattern), controllerClass.name, methodName);
-            }
-            else {
-                this.handlers.set(key, [handler]);
-                debug('discovered %s [%s] on %s.%s', decoratorName, (0, utils_1.normalizePattern)(metadata.pattern), controllerClass.name, methodName);
+    registerDiscovered(discovered, controllerClass, controllerBindingKey, app, discovererId) {
+        const isEvent = discovered.kind === discovery_1.HANDLER_KIND_EVENT;
+        const rawTransport = discovered.transport;
+        const transportForKey = rawTransport === '*' ? undefined : rawTransport;
+        const key = this.buildKey(transportForKey, discovered.pattern);
+        const keyOrPattern = (0, utils_1.normalizePattern)(discovered.pattern);
+        const existing = this.entries.get(key);
+        const firstExisting = existing?.[0];
+        // Reject mixed handler types on the same pattern.
+        if (firstExisting && firstExisting.kind !== discovered.kind) {
+            throw new errors_1.TransportConfigError(`Cannot mix handler kinds for pattern "${keyOrPattern}" on transport "${rawTransport}": ` +
+                `existing kind "${firstExisting.kind}" from ` +
+                `${firstExisting.controllerClass.name}.${firstExisting.methodName} ` +
+                `(discoverer "${firstExisting.discovererId}") conflicts with ` +
+                `new kind "${discovered.kind}" from ` +
+                `${controllerClass.name}.${discovered.methodName} ` +
+                `(discoverer "${discovererId}").`);
+        }
+        // Reject duplicate request/response handlers.
+        if (firstExisting && !isEvent) {
+            throw new errors_1.TransportConfigError(`Duplicate request handler for pattern "${keyOrPattern}" on transport "${rawTransport}": ` +
+                `pattern is already bound to ` +
+                `${firstExisting.controllerClass.name}.${firstExisting.methodName} ` +
+                `contributed by discoverer "${firstExisting.discovererId}".`);
+        }
+        const handler = this.createHandler(controllerBindingKey, discovered.methodName, app);
+        handler.isEventHandler = isEvent;
+        if (transportForKey !== undefined) {
+            handler.transport = transportForKey;
+        }
+        if (discovered.options?.extras !== undefined) {
+            handler.extras = discovered.options.extras;
+        }
+        const entry = {
+            pattern: discovered.pattern,
+            transport: rawTransport,
+            kind: discovered.kind,
+            controllerClass,
+            methodName: discovered.methodName,
+            discovererId,
+            ...(discovered.options !== undefined
+                ? { options: discovered.options }
+                : {}),
+            handler,
+        };
+        const decoratorLabel = `@${discovererId}Handler`;
+        if (existing) {
+            if (firstExisting && firstExisting.discovererId !== entry.discovererId) {
+                debug('event handler chain on pattern %s (transport %s) now spans discoverers: %s + %s', keyOrPattern, rawTransport, firstExisting.discovererId, entry.discovererId);
             }
+            existing.push(entry);
+            debug('chained %s [%s] on %s.%s', decoratorLabel, keyOrPattern, controllerClass.name, discovered.methodName);
+        }
+        else {
+            this.entries.set(key, [entry]);
+            debug('discovered %s [%s] on %s.%s', decoratorLabel, (0, utils_1.normalizePattern)(discovered.pattern), controllerClass.name, discovered.methodName);
         }
     }
     /**
-     * Create a handler function that invokes the controller method through
-     * LoopBack's native invocation pipeline.
+     * Create a handler function that invokes the controller method
+     * through LoopBack's native invocation pipeline.
      *
      * Each invocation creates a uniquely named child Context from the
-     * application context. Per-message bindings (payload, transport context)
-     * are scoped to the child context and cannot collide with concurrent
-     * messages.
+     * application context. Per-message bindings (payload, transport
+     * context) are scoped to the child context and cannot collide with
+     * concurrent messages.
      *
      * The child context lifetime extends until the handler result fully
      * resolves. For Observable results, the context stays open until the
@@ -205,7 +394,8 @@ let HandlerRegistry = class HandlerRegistry {
         const handler = async (data, context) => {
             const invocationCtx = new core_1.Context(app, `transport-invocation-${(0, crypto_1.randomUUID)()}`);
             // Idempotent cleanup guard: Context.close() is synchronous but
-            // may be reached from multiple paths (error + teardown) for Observables
+            // may be reached from multiple paths (error + teardown) for
+            // Observables.
             let closed = false;
             const cleanup = () => {
                 if (!closed) {
@@ -219,13 +409,13 @@ let HandlerRegistry = class HandlerRegistry {
                 const controller = await invocationCtx.get(controllerBindingKey);
                 const method = controller[methodName];
                 if (typeof method !== 'function') {
-                    throw new Error(`Transport handler method "${methodName}" not found on controller "${controllerBindingKey}"`);
+                    throw new errors_1.TransportConfigError(`Transport handler method "${methodName}" not found on controller "${controllerBindingKey}"`);
                 }
-                // Invoke through LoopBack's method invocation pipeline
-                // This honors parameter injection, interceptors, and other
-                // framework invocation semantics
+                // Invoke through LoopBack's method invocation pipeline so we
+                // honour parameter injection, interceptors, and other framework
+                // invocation semantics.
                 const result = await (0, core_1.invokeMethod)(controller, methodName, invocationCtx, [data, context]);
-                // For Observable results, defer context cleanup until stream completes
+                // For Observable results, defer context cleanup until stream completes.
                 if ((0, rxjs_1.isObservable)(result)) {
                     const obs = result;
                     return new rxjs_1.Observable(subscriber => {
@@ -246,7 +436,7 @@ let HandlerRegistry = class HandlerRegistry {
                         };
                     });
                 }
-                // For non-Observable results, close context immediately
+                // For non-Observable results, close context immediately.
                 cleanup();
                 return result;
             }