@fluojs/microservices 1.0.0-beta.1

package/dist/transports/grpc-transport.js

@@ -0,0 +1,1035 @@
+import { logTransportEventHandlerFailure } from './event-handler-logger.js';
+const DEFAULT_KIND_METADATA_KEY = 'x-fluo-kind';
+const DEFAULT_MESSAGE_KIND_VALUE = 'message';
+const DEFAULT_EVENT_KIND_VALUE = 'event';
+const grpcKinds = {
+  event: 'event',
+  message: 'message'
+};
+
+/** Options for configuring the gRPC microservice transport. */
+
+/**
+ * gRPC transport for unary, event-style unary, and all streaming microservice patterns.
+ *
+ * The adapter loads protobuf definitions at runtime, registers service implementations on a gRPC server,
+ * and exposes matching unary/server-stream/client-stream/bidi-stream client calls through one transport surface.
+ */
+export class GrpcMicroserviceTransport {
+  bidiStreamHandler;
+  clientStreamHandler;
+  closing = false;
+  clients = new Map();
+  grpc;
+  handler;
+  logger;
+  listening = false;
+  listenPromise;
+  pending = new Map();
+  packageRoot;
+  requestTimeoutMs;
+  server;
+  resolvedServer;
+  serverStreamHandler;
+
+  /**
+   * Creates a gRPC transport bound to one protobuf package and server endpoint.
+   *
+   * @param options Protobuf loading, server binding, and client-call settings for the transport.
+   */
+  constructor(options) {
+    this.options = options;
+    this.requestTimeoutMs = options.requestTimeoutMs ?? 3_000;
+    this.server = options.server;
+  }
+  setLogger(logger) {
+    this.logger = logger;
+  }
+
+  /**
+   * Loads protobuf services, registers handlers, and binds the gRPC server.
+   *
+   * @param handler Runtime callback invoked for inbound unary message and event packets.
+   * @returns A promise that resolves once the gRPC server is bound and ready.
+   */
+  async listen(handler) {
+    this.closing = false;
+    this.handler = handler;
+    if (this.listening) {
+      return;
+    }
+    if (this.listenPromise) {
+      await this.listenPromise;
+      return;
+    }
+    this.listenPromise = (async () => {
+      const grpc = await this.resolveGrpc();
+      const protoLoader = await this.resolveProtoLoader();
+      const packageDefinition = protoLoader.loadSync(this.options.protoPath, this.options.loaderOptions);
+      const loadedDefinition = grpc.loadPackageDefinition(packageDefinition);
+      const packageRoot = this.resolvePackageRoot(loadedDefinition);
+      const targetServices = this.resolveTargetServices(packageRoot);
+      const server = this.server ?? new grpc.Server();
+      let hasRegisteredMethod = false;
+      try {
+        for (const [serviceName, serviceConstructor] of targetServices) {
+          const implementation = this.buildServiceImplementation(serviceName, serviceConstructor);
+          if (Object.keys(implementation).length === 0) {
+            continue;
+          }
+          hasRegisteredMethod = true;
+          server.addService(serviceConstructor.service, implementation);
+        }
+        if (!hasRegisteredMethod) {
+          throw new Error('GrpcMicroserviceTransport could not register any RPC handlers. At least one unary, server-streaming, client-streaming, or bidirectional-streaming method is required.');
+        }
+        await this.bindServer(server, grpc);
+      } catch (error) {
+        await this.shutdownServer(server);
+        throw error;
+      }
+      this.grpc = grpc;
+      this.packageRoot = packageRoot;
+      this.resolvedServer = server;
+      this.listening = true;
+    })();
+    try {
+      await this.listenPromise;
+    } finally {
+      this.listenPromise = undefined;
+    }
+  }
+
+  /**
+   * Sends one unary request-response message through gRPC.
+   *
+   * @param pattern `<Service>.<Method>` pattern identifying the remote unary RPC.
+   * @param payload Serializable request payload.
+   * @param signal Optional abort signal used to cancel the call.
+   * @returns The decoded unary RPC response.
+   */
+  async send(pattern, payload, signal) {
+    if (this.closing) {
+      throw new Error('GrpcMicroserviceTransport is closing. Wait for close() to complete before send().');
+    }
+    if (!this.listening) {
+      throw new Error('GrpcMicroserviceTransport is not listening. Call listen() before send().');
+    }
+    const parsed = parseGrpcPattern(pattern);
+    return await this.callUnary(parsed, payload, grpcKinds.message, signal);
+  }
+
+  /**
+   * Emits one event-style unary call through gRPC.
+   *
+   * @param pattern `<Service>.<Method>` pattern identifying the remote RPC.
+   * @param payload Serializable event payload.
+   * @returns A promise that resolves once the remote RPC acknowledges the call.
+   */
+  async emit(pattern, payload) {
+    if (this.closing) {
+      throw new Error('GrpcMicroserviceTransport is closing. Wait for close() to complete before emit().');
+    }
+    if (!this.listening) {
+      throw new Error('GrpcMicroserviceTransport is not listening. Call listen() before emit().');
+    }
+    const parsed = parseGrpcPattern(pattern);
+    await this.callUnary(parsed, payload, grpcKinds.event, undefined);
+  }
+
+  /**
+   * Registers the runtime callback used for inbound server-streaming RPCs.
+   *
+   * @param handler Runtime callback invoked for inbound server-stream requests.
+   */
+  listenServerStreaming(handler) {
+    this.serverStreamHandler = handler;
+  }
+
+  /**
+   * Registers the runtime callback used for inbound client-streaming RPCs.
+   *
+   * @param handler Runtime callback invoked for inbound client-stream requests.
+   */
+  listenClientStreaming(handler) {
+    this.clientStreamHandler = handler;
+  }
+
+  /**
+   * Registers the runtime callback used for inbound bidirectional-streaming RPCs.
+   *
+   * @param handler Runtime callback invoked for inbound bidi-stream requests.
+   */
+  listenBidiStreaming(handler) {
+    this.bidiStreamHandler = handler;
+  }
+
+  /**
+   * Opens an outbound server-streaming call.
+   *
+   * @param pattern `<Service>.<Method>` pattern identifying the remote server-stream RPC.
+   * @param payload Serializable request payload.
+   * @param signal Optional abort signal used to cancel the stream.
+   * @returns An async iterable of streamed response messages.
+   */
+  serverStream(pattern, payload, signal) {
+    if (this.closing) {
+      throw new Error('GrpcMicroserviceTransport is closing. Wait for close() to complete before serverStream().');
+    }
+    if (!this.listening) {
+      throw new Error('GrpcMicroserviceTransport is not listening. Call listen() before serverStream().');
+    }
+    const parsed = parseGrpcPattern(pattern);
+    return this.callServerStream(parsed, payload, signal);
+  }
+
+  /**
+   * Opens an outbound client-streaming call.
+   *
+   * @param pattern `<Service>.<Method>` pattern identifying the remote client-stream RPC.
+   * @param signal Optional abort signal used to cancel the stream.
+   * @returns A writer for request messages and a promise for the final response payload.
+   */
+  clientStream(pattern, signal) {
+    if (this.closing) {
+      throw new Error('GrpcMicroserviceTransport is closing. Wait for close() to complete before clientStream().');
+    }
+    if (!this.listening) {
+      throw new Error('GrpcMicroserviceTransport is not listening. Call listen() before clientStream().');
+    }
+    const parsed = parseGrpcPattern(pattern);
+    return this.callClientStream(parsed, signal);
+  }
+
+  /**
+   * Opens an outbound bidirectional-streaming call.
+   *
+   * @param pattern `<Service>.<Method>` pattern identifying the remote bidi-stream RPC.
+   * @param signal Optional abort signal used to cancel the stream.
+   * @returns A response reader paired with a request writer.
+   */
+  bidiStream(pattern, signal) {
+    if (this.closing) {
+      throw new Error('GrpcMicroserviceTransport is closing. Wait for close() to complete before bidiStream().');
+    }
+    if (!this.listening) {
+      throw new Error('GrpcMicroserviceTransport is not listening. Call listen() before bidiStream().');
+    }
+    const parsed = parseGrpcPattern(pattern);
+    return this.callBidiStream(parsed, signal);
+  }
+
+  /**
+   * Shuts down the gRPC server and closes any cached service clients.
+   *
+   * @returns A promise that resolves once shutdown cleanup completes.
+   */
+  async close() {
+    this.closing = true;
+    let closeError;
+    if (this.listenPromise) {
+      await this.listenPromise;
+    }
+    try {
+      if (this.resolvedServer) {
+        await this.shutdownServer(this.resolvedServer);
+      }
+      for (const service of this.clients.values()) {
+        try {
+          service.client.close?.();
+        } catch (error) {
+          closeError ??= error;
+        }
+      }
+    } catch (error) {
+      closeError ??= error;
+    } finally {
+      this.handler = undefined;
+      this.serverStreamHandler = undefined;
+      this.clientStreamHandler = undefined;
+      this.bidiStreamHandler = undefined;
+      this.listening = false;
+      this.resolvedServer = undefined;
+      this.clients.clear();
+      this.packageRoot = undefined;
+      for (const pending of [...this.pending.values()]) {
+        pending.reject(new Error('gRPC microservice transport closed before response.'));
+      }
+    }
+    if (closeError) {
+      throw closeError;
+    }
+  }
+  buildServiceImplementation(serviceName, serviceConstructor) {
+    const implementation = {};
+    for (const [methodName, methodDefinition] of Object.entries(serviceConstructor.service)) {
+      if (methodDefinition.requestStream && methodDefinition.responseStream) {
+        implementation[methodName] = call => {
+          void this.handleInboundBidiStream(serviceName, methodName, call).catch(error => {
+            try {
+              const grpcError = this.mapGrpcHandlerError(error);
+              const mapped = Object.assign(new Error(grpcError.message), {
+                code: grpcError.code
+              });
+              if (call.destroy) {
+                call.destroy(mapped);
+              } else {
+                call.end();
+              }
+            } catch {
+              call.end();
+            }
+          });
+        };
+        continue;
+      }
+      if (methodDefinition.requestStream) {
+        implementation[methodName] = (call, callback) => {
+          void this.handleInboundClientStream(serviceName, methodName, call).then(response => {
+            callback(null, response);
+          }).catch(error => {
+            callback(this.mapGrpcHandlerError(error));
+          });
+        };
+        continue;
+      }
+      if (methodDefinition.responseStream) {
+        implementation[methodName] = call => {
+          void this.handleInboundServerStream(serviceName, methodName, call).catch(error => {
+            try {
+              const grpcError = this.mapGrpcHandlerError(error);
+              const mapped = Object.assign(new Error(grpcError.message), {
+                code: grpcError.code
+              });
+              if (call.destroy) {
+                call.destroy(mapped);
+              } else {
+                call.end();
+              }
+            } catch {
+              call.end();
+            }
+          });
+        };
+        continue;
+      }
+      implementation[methodName] = (call, callback) => {
+        void this.handleInboundUnary(serviceName, methodName, call).then(response => {
+          callback(null, response);
+        }).catch(error => {
+          callback(this.mapGrpcHandlerError(error));
+        });
+      };
+    }
+    return implementation;
+  }
+  async handleInboundUnary(serviceName, methodName, call) {
+    const handler = this.handler;
+    if (!handler) {
+      throw this.createGrpcError(this.resolveGrpcStatusCode('UNIMPLEMENTED', 12), 'No message handler registered for pattern.');
+    }
+    const pattern = `${serviceName}.${methodName}`;
+    const kind = this.resolveInboundKind(call.metadata);
+    if (kind === grpcKinds.event) {
+      try {
+        await handler({
+          kind: 'event',
+          pattern,
+          payload: call.request
+        });
+      } catch (error) {
+        this.logEventHandlerFailure(error);
+      }
+      return {};
+    }
+    return await handler({
+      kind: 'message',
+      pattern,
+      payload: call.request
+    });
+  }
+  async handleInboundServerStream(serviceName, methodName, call) {
+    const handler = this.serverStreamHandler;
+    if (!handler) {
+      throw this.createGrpcError(this.resolveGrpcStatusCode('UNIMPLEMENTED', 12), 'No server-stream handler registered for pattern.');
+    }
+    const pattern = `${serviceName}.${methodName}`;
+    const mapHandlerError = error => {
+      const grpcError = this.mapGrpcHandlerError(error);
+      return Object.assign(new Error(grpcError.message), {
+        code: grpcError.code
+      });
+    };
+    const writer = {
+      write(data) {
+        call.write(data);
+      },
+      end() {
+        call.end();
+      },
+      error(err) {
+        const mapped = mapHandlerError(err);
+        if (call.destroy) {
+          call.destroy(mapped);
+        } else {
+          call.end();
+        }
+      }
+    };
+    await handler(pattern, call.request, writer);
+  }
+  async handleInboundClientStream(serviceName, methodName, call) {
+    const handler = this.clientStreamHandler;
+    if (!handler) {
+      throw this.createGrpcError(this.resolveGrpcStatusCode('UNIMPLEMENTED', 12), 'No client-stream handler registered for pattern.');
+    }
+    const pattern = `${serviceName}.${methodName}`;
+    const reader = grpcReadableToAsyncIterable(call);
+    return await handler(pattern, reader);
+  }
+  async handleInboundBidiStream(serviceName, methodName, call) {
+    const handler = this.bidiStreamHandler;
+    if (!handler) {
+      throw this.createGrpcError(this.resolveGrpcStatusCode('UNIMPLEMENTED', 12), 'No bidi-stream handler registered for pattern.');
+    }
+    const pattern = `${serviceName}.${methodName}`;
+    const reader = grpcReadableToAsyncIterable(call);
+    const writer = {
+      write(data) {
+        call.write(data);
+      },
+      end() {
+        call.end();
+      },
+      error(err) {
+        if (call.destroy) {
+          call.destroy(err);
+        } else {
+          call.end();
+        }
+      }
+    };
+    await handler(pattern, reader, writer);
+  }
+  async callUnary(parsedPattern, payload, kind, signal) {
+    const runtime = this.getServiceRuntime(parsedPattern.serviceName);
+    const method = runtime.client[parsedPattern.methodName];
+    if (typeof method !== 'function') {
+      throw new Error(`GrpcMicroserviceTransport could not resolve unary method "${parsedPattern.serviceName}.${parsedPattern.methodName}".`);
+    }
+    const requestId = crypto.randomUUID();
+    return await new Promise((resolve, reject) => {
+      let abortHandler;
+      let settled = false;
+      let timeout;
+      let activeCall;
+      const cleanup = () => {
+        if (timeout) {
+          clearTimeout(timeout);
+        }
+        if (signal && abortHandler) {
+          signal.removeEventListener('abort', abortHandler);
+        }
+        this.pending.delete(requestId);
+      };
+      const entry = {
+        resolve: value => {
+          if (settled) {
+            return;
+          }
+          settled = true;
+          cleanup();
+          resolve(value);
+        },
+        reject: error => {
+          if (settled) {
+            return;
+          }
+          settled = true;
+          cleanup();
+          reject(error);
+        }
+      };
+      this.pending.set(requestId, entry);
+      const metadata = this.createMetadata(kind);
+      const deadline = new Date(Date.now() + this.requestTimeoutMs);
+      timeout = setTimeout(() => {
+        entry.reject(new Error(`gRPC request timed out after ${String(this.requestTimeoutMs)}ms waiting for pattern "${parsedPattern.serviceName}.${parsedPattern.methodName}".`));
+        activeCall?.cancel?.();
+      }, this.requestTimeoutMs);
+      if (signal) {
+        if (signal.aborted) {
+          entry.reject(new Error('gRPC request aborted before dispatch.'));
+          return;
+        }
+        abortHandler = () => {
+          activeCall?.cancel?.();
+          entry.reject(new Error('gRPC request aborted.'));
+        };
+        signal.addEventListener('abort', abortHandler, {
+          once: true
+        });
+      }
+      void Promise.resolve().then(() => {
+        if (this.closing) {
+          entry.reject(new Error('gRPC microservice transport closed before response.'));
+          return;
+        }
+        activeCall = method.call(runtime.client, payload, metadata, {
+          deadline
+        }, (error, response) => {
+          if (error) {
+            if (signal?.aborted) {
+              entry.reject(new Error('gRPC request aborted.'));
+              return;
+            }
+            if (isGrpcStatus(error, this.resolveGrpcStatusCode('DEADLINE_EXCEEDED', 4))) {
+              entry.reject(new Error(`gRPC request timed out after ${String(this.requestTimeoutMs)}ms waiting for pattern "${parsedPattern.serviceName}.${parsedPattern.methodName}".`));
+              return;
+            }
+            const message = typeof error.message === 'string' && error.message.length > 0 ? error.message : 'Unhandled gRPC transport error';
+            entry.reject(new Error(message));
+            return;
+          }
+          entry.resolve(response);
+        });
+      }).catch(error => {
+        entry.reject(error instanceof Error ? error : new Error('Failed to send gRPC request.'));
+      });
+    });
+  }
+  callServerStream(parsedPattern, payload, signal) {
+    const runtime = this.getServiceRuntime(parsedPattern.serviceName);
+    const method = runtime.client[parsedPattern.methodName];
+    if (typeof method !== 'function') {
+      throw new Error(`GrpcMicroserviceTransport could not resolve server-streaming method "${parsedPattern.serviceName}.${parsedPattern.methodName}".`);
+    }
+    const metadata = this.createMetadata(grpcKinds.message);
+    const transport = this;
+    return {
+      [Symbol.asyncIterator]() {
+        const buffer = [];
+        let done = false;
+        let error;
+        let waiting;
+        let stream;
+        const startStream = () => {
+          if (stream) {
+            return;
+          }
+          stream = method.call(runtime.client, payload, metadata);
+          stream.on('data', data => {
+            if (waiting) {
+              const w = waiting;
+              waiting = undefined;
+              w.resolve({
+                value: data,
+                done: false
+              });
+            } else {
+              buffer.push(data);
+            }
+          });
+          stream.on('end', () => {
+            done = true;
+            if (waiting) {
+              const w = waiting;
+              waiting = undefined;
+              w.resolve({
+                value: undefined,
+                done: true
+              });
+            }
+          });
+          stream.on('error', err => {
+            done = true;
+            if (signal?.aborted) {
+              error = new Error('gRPC server stream aborted.');
+            } else {
+              error = err instanceof Error ? err : new Error('gRPC server stream error.');
+            }
+            if (waiting) {
+              const w = waiting;
+              waiting = undefined;
+              w.reject(error);
+            }
+          });
+          if (signal) {
+            if (signal.aborted) {
+              done = true;
+              error = new Error('gRPC server stream aborted.');
+              stream.cancel?.();
+              return;
+            }
+            const onAbort = () => {
+              done = true;
+              error = new Error('gRPC server stream aborted.');
+              stream?.cancel?.();
+              if (waiting) {
+                const w = waiting;
+                waiting = undefined;
+                w.reject(error);
+              }
+            };
+            signal.addEventListener('abort', onAbort, {
+              once: true
+            });
+          }
+        };
+        void transport;
+        return {
+          next() {
+            startStream();
+            if (buffer.length > 0) {
+              return Promise.resolve({
+                value: buffer.shift(),
+                done: false
+              });
+            }
+            if (error) {
+              return Promise.reject(error);
+            }
+            if (done) {
+              return Promise.resolve({
+                value: undefined,
+                done: true
+              });
+            }
+            return new Promise((resolve, reject) => {
+              waiting = {
+                resolve,
+                reject
+              };
+            });
+          },
+          return() {
+            done = true;
+            stream?.cancel?.();
+            return Promise.resolve({
+              value: undefined,
+              done: true
+            });
+          }
+        };
+      }
+    };
+  }
+  callClientStream(parsedPattern, signal) {
+    const runtime = this.getServiceRuntime(parsedPattern.serviceName);
+    const method = runtime.client[parsedPattern.methodName];
+    if (typeof method !== 'function') {
+      throw new Error(`GrpcMicroserviceTransport could not resolve client-streaming method "${parsedPattern.serviceName}.${parsedPattern.methodName}".`);
+    }
+    const metadata = this.createMetadata(grpcKinds.message);
+    let callStream;
+    let ended = false;
+    const result = new Promise((resolve, reject) => {
+      if (signal?.aborted) {
+        reject(new Error('gRPC client stream aborted before dispatch.'));
+        return;
+      }
+      callStream = method.call(runtime.client, metadata, (error, response) => {
+        if (error) {
+          if (signal?.aborted) {
+            reject(new Error('gRPC client stream aborted.'));
+            return;
+          }
+          const message = typeof error.message === 'string' && error.message.length > 0 ? error.message : 'Unhandled gRPC client stream error';
+          reject(new Error(message));
+          return;
+        }
+        resolve(response);
+      });
+      if (signal) {
+        const onAbort = () => {
+          if (!ended) {
+            ended = true;
+            callStream?.end();
+          }
+          reject(new Error('gRPC client stream aborted.'));
+        };
+        signal.addEventListener('abort', onAbort, {
+          once: true
+        });
+      }
+    });
+    const writer = {
+      write(data) {
+        if (!ended) {
+          callStream?.write(data);
+        }
+      },
+      end() {
+        if (!ended) {
+          ended = true;
+          callStream?.end();
+        }
+      },
+      error(err) {
+        void err;
+        if (!ended) {
+          ended = true;
+          callStream?.end();
+        }
+      }
+    };
+    return {
+      writer,
+      result
+    };
+  }
+  callBidiStream(parsedPattern, signal) {
+    const runtime = this.getServiceRuntime(parsedPattern.serviceName);
+    const method = runtime.client[parsedPattern.methodName];
+    if (typeof method !== 'function') {
+      throw new Error(`GrpcMicroserviceTransport could not resolve bidirectional-streaming method "${parsedPattern.serviceName}.${parsedPattern.methodName}".`);
+    }
+    const metadata = this.createMetadata(grpcKinds.message);
+    const duplexStream = method.call(runtime.client, metadata);
+    let writerEnded = false;
+    if (signal) {
+      if (signal.aborted) {
+        duplexStream.cancel?.();
+      } else {
+        const onAbort = () => {
+          if (!writerEnded) {
+            writerEnded = true;
+            duplexStream.end();
+          }
+          duplexStream.cancel?.();
+        };
+        signal.addEventListener('abort', onAbort, {
+          once: true
+        });
+      }
+    }
+    const reader = grpcReadableToAsyncIterable(duplexStream, signal);
+    const writer = {
+      write(data) {
+        if (!writerEnded) {
+          duplexStream.write(data);
+        }
+      },
+      end() {
+        if (!writerEnded) {
+          writerEnded = true;
+          duplexStream.end();
+        }
+      },
+      error(err) {
+        void err;
+        if (!writerEnded) {
+          writerEnded = true;
+          duplexStream.end();
+        }
+      }
+    };
+    return {
+      reader,
+      writer
+    };
+  }
+  getServiceRuntime(serviceName) {
+    const cached = this.clients.get(serviceName);
+    if (cached) {
+      return cached;
+    }
+    const grpc = this.grpc;
+    if (!grpc || !this.packageRoot) {
+      throw new Error('GrpcMicroserviceTransport is not initialized. Call listen() before send() or emit().');
+    }
+    const serviceConstructor = this.resolveServiceConstructor(this.packageRoot, serviceName);
+    const credentials = this.options.credentials ?? grpc.credentials.createInsecure();
+    const ClientConstructor = grpc.makeGenericClientConstructor(serviceConstructor.service, serviceName, {});
+    const client = new ClientConstructor(this.options.url, credentials, this.options.channelOptions);
+    const runtime = {
+      client,
+      serviceDefinition: serviceConstructor.service
+    };
+    this.clients.set(serviceName, runtime);
+    return runtime;
+  }
+  resolvePackageRoot(loadedDefinition) {
+    const packageName = this.options.packageName.trim();
+    if (packageName.length === 0) {
+      throw new Error('GrpcMicroserviceTransport requires packageName to resolve proto services.');
+    }
+    const path = packageName.split('.').filter(segment => segment.length > 0);
+    if (path.length === 0) {
+      throw new Error('GrpcMicroserviceTransport requires packageName to resolve proto services.');
+    }
+    let current = loadedDefinition;
+    for (const segment of path) {
+      if (!current || typeof current !== 'object') {
+        throw new Error(`GrpcMicroserviceTransport could not resolve proto package "${packageName}".`);
+      }
+      const next = current[segment];
+      if (!next) {
+        throw new Error(`GrpcMicroserviceTransport could not resolve proto package "${packageName}".`);
+      }
+      current = next;
+    }
+    if (!current || typeof current !== 'object') {
+      throw new Error(`GrpcMicroserviceTransport could not resolve proto package "${packageName}".`);
+    }
+    return current;
+  }
+  resolveTargetServices(packageRoot) {
+    const names = this.options.services && this.options.services.length > 0 ? [...this.options.services] : Object.keys(packageRoot).filter(name => this.isServiceConstructor(packageRoot[name]));
+    if (names.length === 0) {
+      throw new Error(`GrpcMicroserviceTransport found no services under proto package "${this.options.packageName}".`);
+    }
+    return names.map(name => [name, this.resolveServiceConstructor(packageRoot, name)]);
+  }
+  resolveServiceConstructor(packageRoot, serviceName) {
+    const candidate = packageRoot[serviceName];
+    if (!this.isServiceConstructor(candidate)) {
+      throw new Error(`GrpcMicroserviceTransport could not resolve service "${serviceName}" in package "${this.options.packageName}".`);
+    }
+    return candidate;
+  }
+  isServiceConstructor(value) {
+    if (!value || typeof value !== 'function') {
+      return false;
+    }
+    const service = value.service;
+    return !!service && typeof service === 'object';
+  }
+  async bindServer(server, grpc) {
+    const credentials = this.options.credentials ?? grpc.credentials.createInsecure();
+    await new Promise((resolve, reject) => {
+      server.bindAsync(this.options.url, credentials, error => {
+        if (error) {
+          reject(error);
+          return;
+        }
+        resolve();
+      });
+    });
+    server.start();
+  }
+  async shutdownServer(server) {
+    if (server.tryShutdown) {
+      await new Promise((resolve, reject) => {
+        server.tryShutdown?.(error => {
+          if (error) {
+            reject(error);
+            return;
+          }
+          resolve();
+        });
+      });
+      return;
+    }
+    server.forceShutdown?.();
+  }
+  async resolveGrpc() {
+    if (this.options.grpc) {
+      return this.options.grpc;
+    }
+    const loaded = await this.loadPeerModule('@grpc/grpc-js');
+    const grpc = loaded.default ?? loaded;
+    if (!grpc || typeof grpc !== 'object' || typeof grpc.loadPackageDefinition !== 'function') {
+      throw new Error('Failed to load @grpc/grpc-js runtime module.');
+    }
+    return grpc;
+  }
+  async resolveProtoLoader() {
+    if (this.options.protoLoader) {
+      return this.options.protoLoader;
+    }
+    const loaded = await this.loadPeerModule('@grpc/proto-loader');
+    const protoLoader = loaded.default ?? loaded;
+    if (!protoLoader || typeof protoLoader !== 'object' || typeof protoLoader.loadSync !== 'function') {
+      throw new Error('Failed to load @grpc/proto-loader runtime module.');
+    }
+    return protoLoader;
+  }
+  async loadPeerModule(specifier) {
+    const moduleLoader = this.options.moduleLoader ?? defaultDynamicImport;
+    try {
+      return await moduleLoader(specifier);
+    } catch (error) {
+      throw createMissingPeerDependencyError(specifier, error);
+    }
+  }
+  createMetadata(kind) {
+    const grpc = this.grpc;
+    if (!grpc) {
+      throw new Error('GrpcMicroserviceTransport is not initialized. Call listen() before send() or emit().');
+    }
+    const metadata = new grpc.Metadata();
+    metadata.set(this.options.kindMetadataKey ?? DEFAULT_KIND_METADATA_KEY, this.kindMetadataValue(kind));
+    return metadata;
+  }
+  resolveInboundKind(metadata) {
+    if (!metadata || typeof metadata.get !== 'function') {
+      return grpcKinds.message;
+    }
+    const values = metadata.get(this.options.kindMetadataKey ?? DEFAULT_KIND_METADATA_KEY);
+    const first = Array.isArray(values) ? values[0] : values;
+    const value = typeof first === 'string' ? first : String(first ?? '');
+    if (value === (this.options.eventKindMetadataValue ?? DEFAULT_EVENT_KIND_VALUE)) {
+      return grpcKinds.event;
+    }
+    return grpcKinds.message;
+  }
+  kindMetadataValue(kind) {
+    if (kind === grpcKinds.event) {
+      return this.options.eventKindMetadataValue ?? DEFAULT_EVENT_KIND_VALUE;
+    }
+    return this.options.messageKindMetadataValue ?? DEFAULT_MESSAGE_KIND_VALUE;
+  }
+  mapGrpcHandlerError(error) {
+    if (error && typeof error === 'object' && 'code' in error && 'message' in error) {
+      const candidate = error;
+      const message = typeof candidate.message === 'string' && candidate.message.length > 0 ? candidate.message : 'Unhandled microservice error';
+      return {
+        code: typeof candidate.code === 'number' ? candidate.code : this.resolveGrpcStatusCode('INTERNAL', 13),
+        message
+      };
+    }
+    const message = error instanceof Error ? error.message : 'Unhandled microservice error';
+    if (message.includes('No message handler registered for pattern') || message.includes('No server-stream handler registered for pattern')) {
+      return this.createGrpcError(this.resolveGrpcStatusCode('UNIMPLEMENTED', 12), message);
+    }
+    if (message.includes('Invalid gRPC pattern')) {
+      return this.createGrpcError(this.resolveGrpcStatusCode('INVALID_ARGUMENT', 3), message);
+    }
+    return this.createGrpcError(this.resolveGrpcStatusCode('INTERNAL', 13), message);
+  }
+  createGrpcError(code, message) {
+    return {
+      code,
+      message
+    };
+  }
+  resolveGrpcStatusCode(name, fallback) {
+    const status = this.grpc?.status;
+    const code = status?.[name];
+    return typeof code === 'number' ? code : fallback;
+  }
+  logEventHandlerFailure(error) {
+    logTransportEventHandlerFailure(this.logger, 'GrpcMicroserviceTransport', error);
+  }
+}
+function grpcReadableToAsyncIterable(stream, signal) {
+  return {
+    [Symbol.asyncIterator]() {
+      const buffer = [];
+      let done = false;
+      let error;
+      let waiting;
+      stream.on('data', data => {
+        if (waiting) {
+          const w = waiting;
+          waiting = undefined;
+          w.resolve({
+            value: data,
+            done: false
+          });
+        } else {
+          buffer.push(data);
+        }
+      });
+      stream.on('end', () => {
+        done = true;
+        if (waiting) {
+          const w = waiting;
+          waiting = undefined;
+          w.resolve({
+            value: undefined,
+            done: true
+          });
+        }
+      });
+      stream.on('error', err => {
+        done = true;
+        if (signal?.aborted) {
+          error = new Error('gRPC stream aborted.');
+        } else {
+          error = err instanceof Error ? err : new Error('gRPC stream error.');
+        }
+        if (waiting) {
+          const w = waiting;
+          waiting = undefined;
+          w.reject(error);
+        }
+      });
+      if (signal) {
+        if (signal.aborted) {
+          done = true;
+          error = new Error('gRPC stream aborted.');
+          stream.cancel?.();
+        } else {
+          const onAbort = () => {
+            done = true;
+            error = new Error('gRPC stream aborted.');
+            stream.cancel?.();
+            if (waiting) {
+              const w = waiting;
+              waiting = undefined;
+              w.reject(error);
+            }
+          };
+          signal.addEventListener('abort', onAbort, {
+            once: true
+          });
+        }
+      }
+      return {
+        next() {
+          if (buffer.length > 0) {
+            return Promise.resolve({
+              value: buffer.shift(),
+              done: false
+            });
+          }
+          if (error) {
+            return Promise.reject(error);
+          }
+          if (done) {
+            return Promise.resolve({
+              value: undefined,
+              done: true
+            });
+          }
+          return new Promise((resolve, reject) => {
+            waiting = {
+              resolve,
+              reject
+            };
+          });
+        },
+        return() {
+          done = true;
+          stream.cancel?.();
+          return Promise.resolve({
+            value: undefined,
+            done: true
+          });
+        }
+      };
+    }
+  };
+}
+function parseGrpcPattern(pattern) {
+  const segments = pattern.split('.');
+  if (segments.length !== 2 || segments[0]?.length === 0 || segments[1]?.length === 0) {
+    throw new Error(`Invalid gRPC pattern "${pattern}". Expected "<Service>.<Method>" matching proto service and method names.`);
+  }
+  return {
+    serviceName: segments[0],
+    methodName: segments[1]
+  };
+}
+function isGrpcStatus(error, code) {
+  return typeof error?.code === 'number' && error.code === code;
+}
+function createMissingPeerDependencyError(specifier, originalError) {
+  const details = originalError instanceof Error && typeof originalError.message === 'string' ? ` (${originalError.message})` : '';
+  return new Error(`Missing optional peer dependency "${specifier}" required by GrpcMicroserviceTransport. Install it with "pnpm add ${specifier}" in your application.${details}`);
+}
+const defaultDynamicImport = async specifier => {
+  return await import(specifier);
+};