@ebarahona/loopback-transport-core 1.0.0

package/dist/registry/handler-registry.js

@@ -0,0 +1,265 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    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;
+};
+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 rxjs_1 = require("rxjs");
+const decorators_1 = require("../decorators");
+const keys_1 = require("../keys");
+const utils_1 = require("../utils");
+const debug = (0, debug_1.default)('loopback:transport:registry');
+/**
+ * Separator for registry keys. Uses double colon to avoid collision
+ * with colons that may appear inside JSON-stringified object patterns.
+ */
+const KEY_SEPARATOR = '::';
+/**
+ * Discovers @messageHandler and @eventHandler decorated methods
+ * from controllers and registers them with the appropriate transport server.
+ *
+ * This class does NOT run in the constructor. It is invoked by
+ * 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.
+ */
+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;
+    }
+    /**
+     * Scan all controllers in the application for transport decorators
+     * and register the handlers.
+     *
+     * Idempotent: clears previously discovered handlers before scanning.
+     */
+    async discoverHandlers(app) {
+        this.handlers.clear();
+        this.discovered = false;
+        const controllerBindings = app.findByTag('controller');
+        debug('scanning %d controllers for transport handlers', controllerBindings.length);
+        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);
+        }
+        this.discovered = true;
+        debug('discovered %d transport handlers', this.handlers.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.
+     */
+    async bindToServers(app) {
+        if (!this.discovered) {
+            throw new Error('Cannot bind handlers to servers: discoverHandlers() has not been called.');
+        }
+        const serverBindings = app.findByTag(keys_1.TRANSPORT_SERVER_TAG);
+        for (const serverBinding of serverBindings) {
+            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) {
+                    const pattern = this.extractPattern(registryKey);
+                    for (const handler of handlers) {
+                        server.addHandler(pattern, handler);
+                    }
+                    if (!handlers[0].isEventHandler) {
+                        boundRequestPatterns.add(pattern);
+                    }
+                    debug('bound handler [%s] to transport [%s] (specific)', pattern, transportName);
+                }
+            }
+            // 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) {
+                    const pattern = this.extractPattern(registryKey);
+                    if (handlers[0].isEventHandler || !boundRequestPatterns.has(pattern)) {
+                        for (const handler of handlers) {
+                            server.addHandler(pattern, handler);
+                        }
+                        debug('bound handler [%s] to transport [%s] (wildcard)', pattern, transportName ?? 'default');
+                    }
+                }
+            }
+        }
+    }
+    /**
+     * Get all discovered handlers.
+     */
+    getHandlers() {
+        const copy = new Map();
+        for (const [key, handlers] of this.handlers) {
+            copy.set(key, [...handlers]);
+        }
+        return copy;
+    }
+    /**
+     * Whether discovery has been run.
+     */
+    isDiscovered() {
+        return this.discovered;
+    }
+    /**
+     * Build the registry key from transport and raw pattern.
+     * Normalizes the pattern (sorts object keys) before keying.
+     * Format: `transport::normalizedPattern` or `*::normalizedPattern`.
+     */
+    buildKey(transport, pattern) {
+        return `${transport ?? '*'}${KEY_SEPARATOR}${(0, utils_1.normalizePattern)(pattern)}`;
+    }
+    /**
+     * Extract the pattern portion from a registry key.
+     */
+    extractPattern(key) {
+        const separatorIndex = key.indexOf(KEY_SEPARATOR);
+        return separatorIndex >= 0
+            ? 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.
+     */
+    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);
+            }
+        }
+    }
+    /**
+     * 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.
+     *
+     * The child context lifetime extends until the handler result fully
+     * resolves. For Observable results, the context stays open until the
+     * Observable completes, errors, or times out.
+     */
+    createHandler(controllerBindingKey, methodName, app) {
+        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
+            let closed = false;
+            const cleanup = () => {
+                if (!closed) {
+                    closed = true;
+                    invocationCtx.close();
+                }
+            };
+            try {
+                invocationCtx.bind(keys_1.TransportBindings.CURRENT_PAYLOAD).to(data);
+                invocationCtx.bind(keys_1.TransportBindings.CURRENT_CONTEXT).to(context);
+                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}"`);
+                }
+                // Invoke through LoopBack's method invocation pipeline
+                // This honors 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
+                if ((0, rxjs_1.isObservable)(result)) {
+                    const obs = result;
+                    return new rxjs_1.Observable(subscriber => {
+                        const subscription = obs.subscribe({
+                            next: value => subscriber.next(value),
+                            error: err => {
+                                subscriber.error(err);
+                                cleanup();
+                            },
+                            complete: () => {
+                                subscriber.complete();
+                                cleanup();
+                            },
+                        });
+                        return () => {
+                            subscription.unsubscribe();
+                            cleanup();
+                        };
+                    });
+                }
+                // For non-Observable results, close context immediately
+                cleanup();
+                return result;
+            }
+            catch (err) {
+                cleanup();
+                throw err;
+            }
+        };
+        return handler;
+    }
+};
+exports.HandlerRegistry = HandlerRegistry;
+exports.HandlerRegistry = HandlerRegistry = __decorate([
+    (0, core_1.injectable)({ scope: core_1.BindingScope.SINGLETON })
+], HandlerRegistry);
+//# sourceMappingURL=handler-registry.js.map

package/dist/registry/handler-registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"handler-registry.js","sourceRoot":"","sources":["../../src/registry/handler-registry.ts"],"names":[],"mappings":"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"}

package/dist/registry/index.d.ts

@@ -0,0 +1 @@
+export * from './handler-registry';

package/dist/registry/index.js

@@ -0,0 +1,18 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./handler-registry"), exports);
+//# sourceMappingURL=index.js.map

package/dist/registry/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/registry/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,qDAAmC"}

package/dist/serializers/index.d.ts

@@ -0,0 +1 @@
+export * from './serializer.interface';

package/dist/serializers/index.js

@@ -0,0 +1,18 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./serializer.interface"), exports);
+//# sourceMappingURL=index.js.map

package/dist/serializers/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/serializers/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,yDAAuC"}

package/dist/serializers/serializer.interface.d.ts

@@ -0,0 +1,62 @@
+/// <reference types="node" />
+/// <reference types="node" />
+/**
+ * Serializes outgoing messages before sending to the broker.
+ *
+ * Supports both sync and async implementations to allow for
+ * compression, encryption, schema registry lookup, protobuf/avro
+ * encoding, and streaming codecs.
+ */
+export interface Serializer<TInput = unknown, TOutput = unknown> {
+    serialize(value: TInput): TOutput | Promise<TOutput>;
+}
+/**
+ * Deserializes incoming messages received from the broker.
+ *
+ * Supports async implementations for decompression, decryption,
+ * schema registry lookup, and streaming codecs.
+ */
+export interface Deserializer<TInput = unknown, TOutput = unknown> {
+    deserialize(value: TInput): TOutput | Promise<TOutput>;
+}
+/**
+ * Transport message envelope with metadata for tracing,
+ * correlation, retries, and distributed context propagation.
+ *
+ * Transport adapters should serialize/deserialize this envelope
+ * rather than raw payloads when full transport metadata is needed.
+ */
+export interface TransportPacket<T = unknown> {
+    readonly pattern: string | Record<string, unknown>;
+    readonly data: T;
+    readonly headers?: Readonly<Record<string, string | Buffer | number | boolean>>;
+    readonly correlationId?: string;
+    readonly traceId?: string;
+}
+/**
+ * Default JSON serializer. Converts objects to JSON strings.
+ *
+ * Wraps JSON.stringify errors into deterministic transport errors
+ * instead of exposing raw runtime exceptions (circular refs, BigInt, etc.).
+ *
+ * Input: any JSON-serializable value.
+ * Output: JSON string (compatible with all text-based transports).
+ *
+ * Note: Buffer/Uint8Array output for binary transports requires
+ * a custom serializer implementation.
+ */
+export declare class JsonSerializer implements Serializer<unknown, string> {
+    serialize(value: unknown): string;
+}
+/**
+ * Default JSON deserializer. Parses JSON strings or Buffers to objects.
+ *
+ * Wraps JSON.parse errors into deterministic transport errors
+ * instead of exposing raw SyntaxError from corrupted broker payloads.
+ *
+ * Input: string or Buffer (Node.js). For browser/WebSocket transports,
+ * use string or Uint8Array with a custom deserializer.
+ */
+export declare class JsonDeserializer implements Deserializer<string | Buffer, unknown> {
+    deserialize(value: string | Buffer): unknown;
+}

package/dist/serializers/serializer.interface.js

@@ -0,0 +1,52 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.JsonDeserializer = exports.JsonSerializer = void 0;
+/**
+ * Default JSON serializer. Converts objects to JSON strings.
+ *
+ * Wraps JSON.stringify errors into deterministic transport errors
+ * instead of exposing raw runtime exceptions (circular refs, BigInt, etc.).
+ *
+ * Input: any JSON-serializable value.
+ * Output: JSON string (compatible with all text-based transports).
+ *
+ * Note: Buffer/Uint8Array output for binary transports requires
+ * a custom serializer implementation.
+ */
+class JsonSerializer {
+    serialize(value) {
+        try {
+            const serialized = JSON.stringify(value);
+            if (serialized === undefined) {
+                throw new Error('value is not JSON-serializable');
+            }
+            return serialized;
+        }
+        catch (err) {
+            throw new Error(`Failed to serialize outgoing message: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+}
+exports.JsonSerializer = JsonSerializer;
+/**
+ * Default JSON deserializer. Parses JSON strings or Buffers to objects.
+ *
+ * Wraps JSON.parse errors into deterministic transport errors
+ * instead of exposing raw SyntaxError from corrupted broker payloads.
+ *
+ * Input: string or Buffer (Node.js). For browser/WebSocket transports,
+ * use string or Uint8Array with a custom deserializer.
+ */
+class JsonDeserializer {
+    deserialize(value) {
+        try {
+            const str = typeof value === 'string' ? value : value.toString('utf-8');
+            return JSON.parse(str);
+        }
+        catch (err) {
+            throw new Error(`Failed to deserialize incoming message: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+}
+exports.JsonDeserializer = JsonDeserializer;
+//# sourceMappingURL=serializer.interface.js.map

package/dist/serializers/serializer.interface.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"serializer.interface.js","sourceRoot":"","sources":["../../src/serializers/serializer.interface.ts"],"names":[],"mappings":";;;AAoCA;;;;;;;;;;;GAWG;AACH,MAAa,cAAc;IACzB,SAAS,CAAC,KAAc;QACtB,IAAI;YACF,MAAM,UAAU,GAAG,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;YACzC,IAAI,UAAU,KAAK,SAAS,EAAE;gBAC5B,MAAM,IAAI,KAAK,CAAC,gCAAgC,CAAC,CAAC;aACnD;YACD,OAAO,UAAU,CAAC;SACnB;QAAC,OAAO,GAAG,EAAE;YACZ,MAAM,IAAI,KAAK,CACb,yCACE,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CACjD,EAAE,CACH,CAAC;SACH;IACH,CAAC;CACF;AAhBD,wCAgBC;AAED;;;;;;;;GAQG;AACH,MAAa,gBAAgB;IAG3B,WAAW,CAAC,KAAsB;QAChC,IAAI;YACF,MAAM,GAAG,GACP,OAAO,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC;YAC9D,OAAO,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;SACxB;QAAC,OAAO,GAAG,EAAE;YACZ,MAAM,IAAI,KAAK,CACb,2CACE,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CACjD,EAAE,CACH,CAAC;SACH;IACH,CAAC;CACF;AAhBD,4CAgBC"}

package/dist/server/index.d.ts

@@ -0,0 +1 @@
+export * from './server-base';

package/dist/server/index.js

@@ -0,0 +1,18 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./server-base"), exports);
+//# sourceMappingURL=index.js.map

package/dist/server/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/server/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,gDAA8B"}

package/dist/server/server-base.d.ts

@@ -0,0 +1,154 @@
+import { Observable } from 'rxjs';
+import { TransportServer, TransportStatus, MessageHandler, WritePacket, IncomingRequest, IncomingEvent } from '../interfaces';
+import { Serializer, Deserializer } from '../serializers';
+/**
+ * Result of handling a message. Separates "what was sent to the caller"
+ * from "should the broker ack or nack this message."
+ *
+ * - `success`: Handler completed. Response was sent. Adapter should ack.
+ * - `handler-error`: Handler threw or Observable errored. Error response
+ *   was sent to the caller. Adapter should ack (the error was handled).
+ * - `infrastructure-error`: No handler found, serialization failure, or
+ *   other framework-level failure. Adapter should nack/dead-letter.
+ */
+export interface HandlerResult {
+    readonly outcome: 'success' | 'handler-error' | 'infrastructure-error';
+    readonly error?: unknown;
+}
+/**
+ * Abstract base class for transport servers.
+ *
+ * Manages the handler registry, message dispatching, and serialization.
+ * Each transport (Kafka, RabbitMQ, gRPC, MQTT, NATS) extends this
+ * class and implements listen/close/unwrap.
+ *
+ * Subclasses should:
+ * - Call deserializer.deserialize() on raw broker messages before
+ *   passing them to handleMessage()/handleEvent()
+ * - Call serializer.serialize() on outbound responses
+ * - Call setStatus('connected') in listen() when ready
+ * - Call setStatus('disconnected') in close() when stopped
+ * - Call dispose() only when the server will never be restarted
+ */
+export declare abstract class ServerBase implements TransportServer {
+    protected readonly messageHandlers: Map<string, MessageHandler<unknown, unknown, unknown>[]>;
+    private readonly statusSubject;
+    protected serializer: Serializer;
+    protected deserializer: Deserializer;
+    protected handlerTimeoutMs: number;
+    readonly status$: Observable<TransportStatus>;
+    constructor(options?: {
+        serializer?: Serializer;
+        deserializer?: Deserializer;
+        handlerTimeoutMs?: number;
+    });
+    /**
+     * Start listening for messages from the broker.
+     * Subclasses should call setStatus('connected') when ready.
+     */
+    abstract listen(): Promise<void>;
+    /**
+     * Stop listening and close connections.
+     * Subclasses should call setStatus('disconnected') when stopped.
+     * Call dispose() only when the server will never be restarted.
+     */
+    abstract close(): Promise<void>;
+    /**
+     * Access the underlying native server/consumer.
+     */
+    abstract unwrap<T>(): T;
+    /**
+     * Emit a status change. Called by transport adapters in listen() and close().
+     */
+    protected setStatus(status: TransportStatus): void;
+    /**
+     * Permanently complete the status stream. After this call, no further
+     * status emissions are possible and the server instance cannot restart.
+     * Existing subscribers receive the complete notification.
+     *
+     * Call only when the server is being permanently disposed.
+     * Normal close() should call setStatus('disconnected'), NOT dispose().
+     */
+    protected dispose(): void;
+    /**
+     * Register a handler for a message pattern.
+     *
+     * For request/response handlers (@messageHandler): duplicate patterns
+     * throw an error. Only one handler per pattern is allowed.
+     *
+     * For event handlers (@eventHandler): multiple handlers on the same
+     * pattern are stored in an array and all execute.
+     *
+     * Mixing @messageHandler and @eventHandler on the same pattern throws.
+     *
+     * Handlers are never mutated. Each server owns its own handler array,
+     * so the same handler object can be safely shared across servers.
+     */
+    addHandler(pattern: string, handler: MessageHandler): void;
+    /**
+     * Get all registered handlers. Returns a defensive copy.
+     */
+    getHandlers(): ReadonlyMap<string, readonly MessageHandler[]>;
+    /**
+     * Remove all registered handlers.
+     * Called before rebinding on restart to prevent duplicate registration.
+     */
+    clearHandlers(): void;
+    /**
+     * Get handlers by pattern. Normalizes the pattern before lookup.
+     * Returns a defensive copy for external consumers.
+     */
+    getHandlersByPattern(pattern: string | Record<string, unknown>): readonly MessageHandler[] | undefined;
+    /**
+     * Internal handler lookup. Returns the live array for dispatch performance.
+     */
+    private lookupHandlers;
+    /**
+     * Handle a request/response message.
+     *
+     * Invokes the handler and calls respond() with each result value.
+     * Observable subscriptions are tracked and cleaned up on completion,
+     * error, or timeout.
+     *
+     * Returns a HandlerResult that separates response semantics from
+     * broker settlement semantics:
+     *
+     * - `success`: Handler completed normally. Ack the message.
+     * - `handler-error`: Handler threw or Observable errored. The error
+     *   response was already sent to the caller. Ack the message --
+     *   the error was handled as an application-level response.
+     * - `infrastructure-error`: No handler found or framework failure.
+     *   Nack/dead-letter the message.
+     *
+     * Observable handlers that do not complete within handlerTimeoutMs
+     * are terminated with a timeout error (handler-error).
+     *
+     * If respond() throws (adapter publication failure), the error is
+     * caught and returned as infrastructure-error.
+     */
+    protected handleMessage(request: IncomingRequest, respond: (packet: WritePacket) => void, context?: unknown): Promise<HandlerResult>;
+    /**
+     * Core handler execution. Separated from handleMessage so that
+     * respond() failures bubble up and are caught by the outer wrapper.
+     */
+    private executeHandler;
+    /**
+     * Handle a fire-and-forget event.
+     *
+     * Invokes all chained handlers for the pattern.
+     * Errors are logged but not propagated (fire-and-forget semantics).
+     *
+     * Observable event handlers that do not complete within handlerTimeoutMs
+     * are terminated and logged.
+     */
+    protected handleEvent(event: IncomingEvent, context?: unknown): Promise<void>;
+    /**
+     * Normalize a pattern to a consistent string key.
+     * Delegates to the shared normalizePattern utility.
+     */
+    protected normalizePattern(pattern: string | Record<string, unknown>): string;
+    /**
+     * Serialize an error to a string for transport.
+     */
+    private serializeError;
+}