@ebarahona/loopback-transport-core 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ed Barahona
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,297 @@
+# @ebarahona/loopback-transport-core
+
+Unified transport abstraction for LoopBack 4. Enables NestJS-style microservices with message handlers, event patterns, unified execution context, and client proxies.
+
+This package is **transport core only** -- it provides the framework abstractions, not broker-specific implementations. Kafka, RabbitMQ, gRPC, MQTT, and NATS adapters are separate packages that extend `ServerBase` and `ClientProxy`.
+
+```bash
+npm install @ebarahona/loopback-transport-core
+```
+
+## What This Provides
+
+| Export | Purpose |
+|---|---|
+| `TransportComponent` | LoopBack 4 component (registers registry + booter) |
+| `@messageHandler(pattern)` | Request/response handler decorator |
+| `@eventHandler(pattern)` | Fire-and-forget event handler decorator |
+| `@payload()` | Injects the message data (transport invocation context, not HTTP) |
+| `@transportCtx()` | Injects the broker-specific context (transport invocation context, not HTTP) |
+| `ClientProxy` | Abstract client with `send()` (cold Observable) and `emit()` (Promise) |
+| `ServerBase` | Abstract server with handler registry, dispatch, and structured results |
+| `ExecutionContext` | Unified context across HTTP, RPC, and event transports |
+| `HandlerResult` | Structured settlement result for adapter ack/nack decisions |
+| `TransportBindings` | Typed binding keys and server registration helpers |
+| `normalizePattern()` | Deterministic pattern key generation |
+| `Serializer` / `Deserializer` | Pluggable serialization (JSON default) |
+| `TransportServer` / `TransportClient` | Adapter interfaces |
+| `TransportStatus` | Connection status type (`connected`, `disconnected`, `reconnecting`, `error`) |
+| `ReadPacket` / `WritePacket` / `PacketId` | Request/response correlation types |
+
+## Usage
+
+### App Setup
+
+```typescript
+import {Application} from '@loopback/core';
+import {TransportComponent, TransportBindings} from '@ebarahona/loopback-transport-core';
+
+const app = new Application();
+app.component(TransportComponent);
+```
+
+Works with `RestApplication` for hybrid HTTP + transport apps, or plain `Application` for transport-only microservices.
+
+### Controller
+
+Patterns can be strings or objects. Object patterns are normalized (deep key sort) so `{cmd: 'get', service: 'order'}` and `{service: 'order', cmd: 'get'}` match the same handler.
+
+```typescript
+import {messageHandler, eventHandler, payload, transportCtx} from '@ebarahona/loopback-transport-core';
+
+class OrderController {
+  // String pattern -- request/response
+  @messageHandler('order.get')
+  async getOrder(@payload() data: {id: string}): Promise<Order> {
+    return this.orderService.findById(data.id);
+  }
+
+  // Object pattern -- request/response
+  @messageHandler({cmd: 'order.create', version: 2})
+  async createOrder(@payload() data: CreateOrderDto): Promise<Order> {
+    return this.orderService.create(data);
+  }
+
+  // Fire-and-forget event (multiple handlers allowed per pattern)
+  @eventHandler('order.placed')
+  async handleOrderPlaced(@payload() data: OrderDto): Promise<void> {
+    await this.notificationService.send(data);
+  }
+
+  // Access broker-specific context
+  @messageHandler('order.process')
+  async processOrder(
+    @payload() data: OrderDto,
+    @transportCtx() ctx: KafkaContext,
+  ): Promise<void> {
+    const {topic, partition, offset} = ctx;
+    // ...
+  }
+}
+```
+
+Non-JSON values in object patterns (undefined, functions, symbols, NaN, Infinity, BigInt, Date, RegExp, Map, Set, class instances) throw at decoration time.
+
+### Client (Producer)
+
+```typescript
+import {inject} from '@loopback/core';
+import {lastValueFrom} from 'rxjs';
+import {TransportBindings, TransportClient} from '@ebarahona/loopback-transport-core';
+
+class NotificationService {
+  constructor(
+    @inject(TransportBindings.client('kafka'))
+    private kafka: TransportClient,
+  ) {}
+
+  // Fire-and-forget
+  async notifyShipped(order: Order): Promise<void> {
+    await this.kafka.emit('order.shipped', order);
+  }
+
+  // Request/response (object pattern)
+  async getOrderStatus(id: string): Promise<OrderStatus> {
+    return lastValueFrom(
+      this.kafka.send<OrderStatus>({cmd: 'order.status'}, {id}),
+    );
+  }
+}
+```
+
+### Registering Transport Servers
+
+Transport adapters register with typed helpers. Class and provider registrations use singleton scope so the same instance receives handlers and gets started.
+
+```typescript
+import {TransportBindings} from '@ebarahona/loopback-transport-core';
+
+// Concrete instance (tests, simple cases)
+TransportBindings.registerServer(app, 'kafka', kafkaServer);
+
+// Class -- IoC container instantiates with full DI (recommended)
+TransportBindings.registerServerClass(app, 'kafka', KafkaServer);
+
+// Provider -- async factory with DI
+TransportBindings.registerServerProvider(app, 'kafka', KafkaServerProvider);
+```
+
+### Unified Execution Context
+
+`ExecutionContext` provides a NestJS-style context model that adapters or higher-level integrations can use across HTTP, RPC, and event transports:
+
+```typescript
+const ctx = ExecutionContext.forEvent(args, handler, controllerClass, {
+  getData: () => eventData,
+  getPattern: () => 'order.placed',
+  getContext: () => brokerContext,
+});
+
+const type = ctx.getType(); // 'http' | 'rpc' | 'event'
+const event = ctx.switchToEvent();
+const pattern = event.getPattern();
+```
+
+Constructed via immutable factory methods (`forHttp`, `forRpc`, `forEvent`). `switchToX()` validates the context type before returning.
+
+## Adapter Authors
+
+### Extending ServerBase
+
+```typescript
+import {ServerBase} from '@ebarahona/loopback-transport-core';
+
+class KafkaServer extends ServerBase {
+  constructor() {
+    super({handlerTimeoutMs: 10_000}); // default 30s
+  }
+
+  async listen(): Promise<void> {
+    await this.consumer.connect();
+    await this.consumer.subscribe({topics: this.getTopics()});
+    await this.consumer.run({
+      eachMessage: async ({topic, partition, message}) => {
+        const data = await this.deserializer.deserialize(message.value);
+        const result = await this.handleMessage(
+          {pattern: topic, data, id: message.key?.toString() ?? ''},
+          packet => this.sendResponse(packet, topic, partition),
+          {topic, partition, offset: message.offset},
+        );
+        // Use result.outcome for ack/nack
+      },
+    });
+    this.setStatus('connected');
+  }
+
+  async close(): Promise<void> {
+    await this.consumer.disconnect();
+    this.setStatus('disconnected');
+  }
+
+  unwrap<T>(): T { return this.consumer as T; }
+}
+```
+
+**What the base class handles:**
+- Handler registration and lookup via `addHandler()` / `getHandlersByPattern()`
+- `clearHandlers()` for restart/rebind safety (called by the booter)
+- Message dispatch with `handleMessage()` returning structured `HandlerResult`
+- Event fan-out with `handleEvent()` (all handlers for a pattern execute)
+- Observable handler timeout (default 30s, configurable via `handlerTimeoutMs`)
+- Status stream (`status$`) that survives restart cycles
+- `dispose()` for permanent shutdown (completes the status stream)
+
+**What adapters implement:**
+- `listen()` -- connect to broker, start consuming, call `setStatus('connected')`
+- `close()` -- disconnect from broker, call `setStatus('disconnected')`
+- `unwrap<T>()` -- expose the native client
+
+### Extending ClientProxy
+
+```typescript
+import {ClientProxy} from '@ebarahona/loopback-transport-core';
+
+class KafkaClient extends ClientProxy {
+  async connect(): Promise<void> {
+    await this.producer.connect();
+  }
+
+  protected async doClose(): Promise<void> {
+    // Called by base close() -- must handle partially opened resources
+    await this.producer.disconnect();
+  }
+
+  unwrap<T>(): T { return this.producer as T; }
+
+  protected publish(packet, callback): () => void {
+    // Send request, register correlation callback
+  }
+
+  protected async dispatchEvent(packet): Promise<void> {
+    // Fire-and-forget publish
+  }
+}
+```
+
+**What the base class handles:**
+- Lazy connection on first `send()` / `emit()`
+- Concurrent connect deduplication
+- Epoch-based stale connection detection (close during connect)
+- Close idempotency and deduplication
+- Bounded wait for pending connect during close (`closeConnectTimeoutMs`, default 5s)
+- State machine: `idle` -> `connecting` -> `connected` -> `closing` -> `idle`
+- Status stream (`status$`)
+
+**What adapters implement:**
+- `connect()` -- establish broker connection (idempotent)
+- `doClose()` -- tear down native connection (may be called with partial connect)
+- `unwrap<T>()` -- expose the native client
+- `publish(packet, callback)` -- send request, return teardown function
+- `dispatchEvent(packet)` -- fire-and-forget publish
+
+### Handler Results
+
+`handleMessage()` returns a structured `HandlerResult` for broker settlement:
+
+```typescript
+const result = await this.handleMessage(request, respond, context);
+
+switch (result.outcome) {
+  case 'success':
+    // Handler completed normally. Ack.
+    await channel.ack(msg);
+    break;
+  case 'handler-error':
+    // Application error. Error response sent to caller. Ack.
+    await channel.ack(msg);
+    break;
+  case 'infrastructure-error':
+    // No handler, respond() failure, or framework error. Nack/dead-letter.
+    await channel.nack(msg, false, false);
+    break;
+}
+```
+
+## Lifecycle Behavior
+
+- **Startup**: The `TransportBooter` lifecycle observer discovers decorated handlers from controllers, binds them to registered servers, and starts servers sequentially. If any server fails to start, all previously started servers are rolled back.
+- **Shutdown**: All servers stop in parallel (best-effort). Individual stop failures are logged but do not prevent other servers from stopping.
+- **Restart**: Handlers are cleared from servers and rebound on each start. Status streams survive `close()` -- only `dispose()` completes them permanently.
+- **Singleton scope**: `registerServerClass()` and `registerServerProvider()` bind in singleton scope so the same instance receives handlers and gets started.
+
+## Transport Modules
+
+Companion adapter packages, each implementing `TransportServer` and `TransportClient`:
+
+| Package | Transport | Native Client |
+|---|---|---|
+| `@ebarahona/loopback-transport-kafka` | Apache Kafka | `kafkajs` |
+| `@ebarahona/loopback-transport-rabbitmq` | RabbitMQ | `amqplib` |
+| `@ebarahona/loopback-transport-grpc` | gRPC | `@grpc/grpc-js` |
+| `@ebarahona/loopback-transport-mqtt` | MQTT | `mqtt` |
+| `@ebarahona/loopback-transport-nats` | NATS | `nats` |
+
+## Requirements
+
+- Node.js >= 18
+- LoopBack 4 application
+
+Peer dependencies (`@loopback/core`, `@loopback/metadata`) are satisfied by any LoopBack 4 project. Runtime dependencies (`rxjs`, `debug`) are installed automatically.
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md).
+
+## License
+
+MIT

package/dist/client/client-proxy.d.ts

@@ -0,0 +1,147 @@
+import { Observable, ReplaySubject } from 'rxjs';
+import { TransportClient, TransportStatus, WritePacket, ReadPacket, PacketId } from '../interfaces';
+/**
+ * Abstract base class for transport clients.
+ *
+ * ## Lifecycle contract
+ *
+ * - `send()`/`emit()` lazily connect on first use.
+ * - Concurrent send/emit calls share one connect().
+ * - `close()` transitions to 'closing', waits for any pending connect
+ *   (bounded by `closeConnectTimeoutMs`, default 5s), calls doClose(),
+ *   then transitions to 'idle'.
+ * - If the pending connect does not settle within the timeout, close
+ *   proceeds anyway. The adapter's doClose() must safely tear down
+ *   partially opened native resources in this case.
+ * - `send()`/`emit()` during 'closing' fail fast.
+ * - After close, the next send/emit reconnects.
+ * - A stale connect that resolves after close always rejects for its
+ *   original caller, even if a newer connection is already healthy.
+ * - State is always reset in finally -- failed doClose() does not
+ *   leave the client stuck.
+ *
+ * ## Stale async detection
+ *
+ * A monotonic `epoch` counter increments on each close(). The
+ * connect callback only transitions to 'connected' if the epoch
+ * has not changed, preventing a late-resolving connect from
+ * overriding a close that happened while it was pending.
+ *
+ * The connectionPromise is only cleared by its own .finally()
+ * callback if it is still the current promise, preventing a stale
+ * promise from clobbering a newer one.
+ */
+export declare abstract class ClientProxy implements TransportClient {
+    protected readonly statusSubject: ReplaySubject<TransportStatus>;
+    private state;
+    private connectionPromise?;
+    private connectionEpoch?;
+    private closePromise?;
+    private epoch;
+    private readonly closeConnectTimeoutMs;
+    readonly status$: Observable<TransportStatus>;
+    constructor(options?: {
+        closeConnectTimeoutMs?: number;
+    });
+    /**
+     * Establish connection to the broker.
+     * Implementations should be idempotent (safe to call multiple times).
+     */
+    abstract connect(): Promise<void>;
+    /**
+     * Close the native connection. Implemented by transport adapters.
+     * Called by the base close() template method after waiting for any
+     * pending connect (bounded by closeConnectTimeoutMs). If the timeout
+     * fires before connect settles, doClose() is still called -- adapters
+     * must handle partially opened native resources in that case.
+     */
+    protected abstract doClose(): Promise<void>;
+    /**
+     * Close the connection and reset state.
+     *
+     * - If idle with no pending connect, returns immediately (no-op).
+     * - If already closing, returns the existing close promise (dedupe).
+     * - Otherwise:
+     *   1. Increments epoch to invalidate any in-flight connect().
+     *   2. Transitions to 'closing' so new send/emit fails fast.
+     *   3. Waits for pending connect (bounded by closeConnectTimeoutMs).
+     *   4. Calls doClose() for adapter-specific teardown.
+     *   5. Resets to 'idle' in finally (even if doClose throws).
+     *
+     * After close, the client is reusable: the next send/emit
+     * will trigger a fresh connect().
+     */
+    close(): Promise<void>;
+    private doCloseInternal;
+    /**
+     * Wait for a pending connect to settle, bounded by timeout.
+     * If connect does not settle in time, proceed anyway -- the epoch
+     * invalidation ensures the stale connect result is ignored.
+     */
+    private waitForPendingConnect;
+    /**
+     * Access the underlying native client.
+     */
+    abstract unwrap<T>(): T;
+    /**
+     * Send a message and register a callback for the correlated response.
+     * Returns a teardown function to cancel the pending response.
+     */
+    protected abstract publish(packet: ReadPacket & PacketId, callback: (packet: WritePacket) => void): () => void;
+    /**
+     * Dispatch a fire-and-forget event.
+     */
+    protected abstract dispatchEvent(packet: ReadPacket): Promise<void>;
+    /**
+     * Send a request and receive a response (request/response pattern).
+     *
+     * Returns a cold Observable: the message is sent only when subscribed.
+     * The connection is established lazily on first subscription.
+     */
+    send<TResult = unknown, TInput = unknown>(pattern: string | Record<string, unknown>, data: TInput): Observable<TResult>;
+    /**
+     * Emit an event with no response expected (fire-and-forget pattern).
+     *
+     * Returns a Promise that resolves when the event is dispatched.
+     * The connection is established lazily if not already connected.
+     */
+    emit<TInput = unknown>(pattern: string | Record<string, unknown>, data: TInput): Promise<void>;
+    /**
+     * Assign a unique correlation ID to a packet.
+     * Uses crypto.randomUUID() for distributed-system-safe IDs.
+     */
+    protected assignPacketId(packet: ReadPacket): ReadPacket & PacketId;
+    /**
+     * Create an Observer callback that maps WritePacket to Observable emissions.
+     */
+    protected createObserver<T>(observer: {
+        next: (value: T) => void;
+        error: (err: unknown) => void;
+        complete: () => void;
+    }): (packet: WritePacket) => void;
+    /**
+     * Verify the client is in connected state.
+     * Throws if a concurrent close() prevented the transition.
+     */
+    private assertConnected;
+    /**
+     * Ensure the client is connected. Concurrent calls share the same
+     * connection promise to prevent duplicate connections.
+     *
+     * - 'closing': reject immediately.
+     * - 'connected': return immediately.
+     * - 'connecting': await the shared promise.
+     * - 'idle': start connect, capture epoch, only transition to
+     *   'connected' if epoch hasn't changed.
+     *
+     * After await, the caller validates that the epoch it waited on
+     * still matches. A stale connect that was invalidated by close()
+     * always rejects for its original caller, even if a newer
+     * connection is already healthy.
+     *
+     * The connectionPromise/connectionEpoch are only cleared in
+     * .finally() if the finishing promise is still the current one,
+     * preventing a stale promise from clobbering a newer one.
+     */
+    private ensureConnected;
+}

package/dist/client/client-proxy.js

@@ -0,0 +1,225 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ClientProxy = void 0;
+const crypto_1 = require("crypto");
+const rxjs_1 = require("rxjs");
+const utils_1 = require("../utils");
+/**
+ * Abstract base class for transport clients.
+ *
+ * ## Lifecycle contract
+ *
+ * - `send()`/`emit()` lazily connect on first use.
+ * - Concurrent send/emit calls share one connect().
+ * - `close()` transitions to 'closing', waits for any pending connect
+ *   (bounded by `closeConnectTimeoutMs`, default 5s), calls doClose(),
+ *   then transitions to 'idle'.
+ * - If the pending connect does not settle within the timeout, close
+ *   proceeds anyway. The adapter's doClose() must safely tear down
+ *   partially opened native resources in this case.
+ * - `send()`/`emit()` during 'closing' fail fast.
+ * - After close, the next send/emit reconnects.
+ * - A stale connect that resolves after close always rejects for its
+ *   original caller, even if a newer connection is already healthy.
+ * - State is always reset in finally -- failed doClose() does not
+ *   leave the client stuck.
+ *
+ * ## Stale async detection
+ *
+ * A monotonic `epoch` counter increments on each close(). The
+ * connect callback only transitions to 'connected' if the epoch
+ * has not changed, preventing a late-resolving connect from
+ * overriding a close that happened while it was pending.
+ *
+ * The connectionPromise is only cleared by its own .finally()
+ * callback if it is still the current promise, preventing a stale
+ * promise from clobbering a newer one.
+ */
+class ClientProxy {
+    constructor(options) {
+        this.statusSubject = new rxjs_1.ReplaySubject(1);
+        this.state = 'idle';
+        this.epoch = 0;
+        this.status$ = this.statusSubject.asObservable();
+        this.closeConnectTimeoutMs = options?.closeConnectTimeoutMs ?? 5000;
+    }
+    /**
+     * Close the connection and reset state.
+     *
+     * - If idle with no pending connect, returns immediately (no-op).
+     * - If already closing, returns the existing close promise (dedupe).
+     * - Otherwise:
+     *   1. Increments epoch to invalidate any in-flight connect().
+     *   2. Transitions to 'closing' so new send/emit fails fast.
+     *   3. Waits for pending connect (bounded by closeConnectTimeoutMs).
+     *   4. Calls doClose() for adapter-specific teardown.
+     *   5. Resets to 'idle' in finally (even if doClose throws).
+     *
+     * After close, the client is reusable: the next send/emit
+     * will trigger a fresh connect().
+     */
+    async close() {
+        if (this.state === 'idle' && !this.connectionPromise)
+            return;
+        if (this.closePromise)
+            return this.closePromise;
+        this.closePromise = this.doCloseInternal().finally(() => {
+            this.closePromise = undefined;
+        });
+        return this.closePromise;
+    }
+    async doCloseInternal() {
+        this.epoch++;
+        this.state = 'closing';
+        // Wait for pending connect with timeout so close never hangs
+        await this.waitForPendingConnect();
+        try {
+            await this.doClose();
+        }
+        finally {
+            this.state = 'idle';
+            this.connectionPromise = undefined;
+            this.connectionEpoch = undefined;
+            this.statusSubject.next('disconnected');
+        }
+    }
+    /**
+     * Wait for a pending connect to settle, bounded by timeout.
+     * If connect does not settle in time, proceed anyway -- the epoch
+     * invalidation ensures the stale connect result is ignored.
+     */
+    async waitForPendingConnect() {
+        const pending = this.connectionPromise;
+        if (!pending)
+            return;
+        await Promise.race([
+            pending.catch(() => undefined),
+            new Promise(resolve => setTimeout(resolve, this.closeConnectTimeoutMs)),
+        ]);
+    }
+    /**
+     * Send a request and receive a response (request/response pattern).
+     *
+     * Returns a cold Observable: the message is sent only when subscribed.
+     * The connection is established lazily on first subscription.
+     */
+    send(pattern, data) {
+        const normalizedPattern = (0, utils_1.normalizePattern)(pattern);
+        return (0, rxjs_1.defer)(async () => this.ensureConnected()).pipe((0, rxjs_1.mergeMap)(() => new rxjs_1.Observable(observer => {
+            const packet = this.assignPacketId({
+                pattern: normalizedPattern,
+                data,
+            });
+            const callback = this.createObserver(observer);
+            return this.publish(packet, callback);
+        })));
+    }
+    /**
+     * Emit an event with no response expected (fire-and-forget pattern).
+     *
+     * Returns a Promise that resolves when the event is dispatched.
+     * The connection is established lazily if not already connected.
+     */
+    async emit(pattern, data) {
+        const normalizedPattern = (0, utils_1.normalizePattern)(pattern);
+        await this.ensureConnected();
+        await this.dispatchEvent({ pattern: normalizedPattern, data });
+    }
+    /**
+     * Assign a unique correlation ID to a packet.
+     * Uses crypto.randomUUID() for distributed-system-safe IDs.
+     */
+    assignPacketId(packet) {
+        return { ...packet, id: (0, crypto_1.randomUUID)() };
+    }
+    /**
+     * Create an Observer callback that maps WritePacket to Observable emissions.
+     */
+    createObserver(observer) {
+        return (packet) => {
+            if ('err' in packet && packet.err !== undefined) {
+                return observer.error(packet.err);
+            }
+            if ('response' in packet) {
+                observer.next(packet.response);
+            }
+            if (packet.isDisposed) {
+                return observer.complete();
+            }
+        };
+    }
+    /**
+     * Verify the client is in connected state.
+     * Throws if a concurrent close() prevented the transition.
+     */
+    assertConnected() {
+        if (this.state !== 'connected') {
+            throw new Error('Client was closed during connection');
+        }
+    }
+    /**
+     * Ensure the client is connected. Concurrent calls share the same
+     * connection promise to prevent duplicate connections.
+     *
+     * - 'closing': reject immediately.
+     * - 'connected': return immediately.
+     * - 'connecting': await the shared promise.
+     * - 'idle': start connect, capture epoch, only transition to
+     *   'connected' if epoch hasn't changed.
+     *
+     * After await, the caller validates that the epoch it waited on
+     * still matches. A stale connect that was invalidated by close()
+     * always rejects for its original caller, even if a newer
+     * connection is already healthy.
+     *
+     * The connectionPromise/connectionEpoch are only cleared in
+     * .finally() if the finishing promise is still the current one,
+     * preventing a stale promise from clobbering a newer one.
+     */
+    async ensureConnected() {
+        if (this.state === 'closing') {
+            throw new Error('Client is closing');
+        }
+        if (this.state === 'connected')
+            return;
+        // Capture the epoch this caller will wait on
+        const awaitedEpoch = this.connectionEpoch ?? this.epoch;
+        if (!this.connectionPromise) {
+            const ep = this.epoch;
+            this.connectionEpoch = ep;
+            this.state = 'connecting';
+            const promise = this.connect()
+                .then(() => {
+                if (this.epoch === ep) {
+                    this.state = 'connected';
+                    this.statusSubject.next('connected');
+                }
+                else {
+                    throw new Error('Client was closed during connection');
+                }
+            })
+                .catch(err => {
+                if (this.epoch === ep) {
+                    this.state = 'idle';
+                }
+                throw err;
+            })
+                .finally(() => {
+                if (this.connectionPromise === promise) {
+                    this.connectionPromise = undefined;
+                    this.connectionEpoch = undefined;
+                }
+            });
+            this.connectionPromise = promise;
+        }
+        await this.connectionPromise;
+        // Validate that this caller's epoch is still current.
+        // A stale caller whose connect was invalidated must not proceed.
+        if (this.epoch !== awaitedEpoch) {
+            throw new Error('Client was closed during connection');
+        }
+        this.assertConnected();
+    }
+}
+exports.ClientProxy = ClientProxy;
+//# sourceMappingURL=client-proxy.js.map