@fluojs/microservices 1.0.1 → 1.0.3

package/README.ko.md

@@ -91,6 +91,7 @@ await microservice.listen();
 - RabbitMQ 요청-응답은 기본적으로 인스턴스별 response queue를 사용합니다. 공유 reply topology를 의도적으로 운영할 때만 `responseQueue`를 명시적으로 지정하세요.
 - caller-owned broker collaborator는 shutdown 중에도 caller-owned로 유지됩니다. NATS, Kafka, RabbitMQ transport는 subscription/consumer를 분리하고 in-flight 요청을 reject하지만, 애플리케이션이 넘긴 client, producer, consumer, publisher, 외부 connection 객체를 close/disconnect하지 않습니다.
 - `AbortSignal`을 받는 요청-응답 transport는 이미 abort된 send를 publish 전에 reject하고, 나중에 abort된 in-flight send도 reject합니다. `close()`가 시작된 뒤에는 shutdown 중인 lifecycle에 새 작업을 publish하지 않고 `send()`/`emit()`을 reject합니다.
+- Root `@fluojs/microservices` barrel import와 `TcpMicroserviceTransport` 생성은 `node:net`을 load하지 않습니다. TCP는 `listen()`이 server를 시작하거나 outbound `send()`/`emit()`이 socket을 생성하는 경로에서만 Node networking을 lazy-load합니다. `close()`가 in-flight listen 시도를 기다리는 중 startup이 실패해도 microservice shutdown은 캡처한 listen error를 다시 surface하기 전에 transport cleanup을 시도합니다.
 - TCP는 테스트와 ephemeral listener를 위해 `port: 0`을 허용하고, listen 중에는 OS가 할당한 포트로 outbound `send()`/`emit()`을 라우팅합니다.
 - gRPC shutdown은 가능하면 server-level `tryShutdown()`을 사용하고, graceful shutdown을 제공하지 않는 런타임에서만 `forceShutdown()`으로 fallback합니다. Active unary/streaming call의 AbortSignal 취소는 call-level `cancel()` 또는 stream end 경로를 사용하며, stream이 end/error/early return으로 끝나면 abort listener를 제거합니다.
 - transport logger를 통해 이벤트 핸들러 실패를 기록하는 경로(`RedisPubSubMicroserviceTransport`, `RedisStreamsMicroserviceTransport`, `NatsMicroserviceTransport`, `MqttMicroserviceTransport`, gRPC event emit)는 끝까지 logger-driven observability를 유지합니다. transport logger를 주입하지 않으면 fluo는 해당 실패를 raw `console.error` fallback으로 복제하지 않습니다.
@@ -160,7 +161,7 @@ class ManualMicroserviceProvidersModule {}
 
 ### Type export
 
-Root barrel은 `Microservice`, `MicroserviceModuleOptions`, `MicroserviceModuleRegistrationOptions`, `MicroserviceTransport`, `Pattern`, `ServerStreamWriter`와 `GrpcMicroserviceTransportOptions`, `KafkaMicroserviceTransportOptions`, `MqttMicroserviceTransportOptions`, `NatsMicroserviceTransportOptions`, `RabbitMqMicroserviceTransportOptions`, `RedisPubSubMicroserviceTransportOptions`, `RedisStreamsMicroserviceTransportOptions`, `RedisStreamClientLike` 같은 transport option type을 export합니다.
+Root barrel은 `Microservice`, `MicroserviceLifecycleState`, `MicroserviceHandlerCounts`, `MicroserviceModuleOptions`, `MicroserviceModuleRegistrationOptions`, `MicroservicePlatformStatusSnapshot`, `MicroserviceStatusAdapterInput`, `MicroserviceTransport`, `MicroserviceTransportCapabilities`, `Pattern`, `ServerStreamWriter`와 `GrpcMicroserviceTransportOptions`, `KafkaMicroserviceTransportOptions`, `MqttMicroserviceTransportOptions`, `NatsMicroserviceTransportOptions`, `RabbitMqMicroserviceTransportOptions`, `RedisPubSubMicroserviceTransportOptions`, `RedisStreamsMicroserviceTransportOptions`, `RedisStreamClientLike` 같은 transport option type을 export합니다.
 
 ### 동작 계약
 

package/README.md

@@ -88,6 +88,7 @@ Microservice handlers fully support fluo's DI scopes. Request-scoped providers a
 - RabbitMQ request/reply uses an instance-scoped response queue by default. Pass `responseQueue` explicitly only when you intentionally own and coordinate a shared reply topology.
 - Caller-owned broker collaborators stay caller-owned during shutdown. NATS, Kafka, and RabbitMQ transports detach their subscriptions/consumers and reject in-flight requests, but they do not close or disconnect the client, producer, consumer, publisher, or external connection objects supplied by the application.
 - Request-response transports that accept `AbortSignal` reject already-aborted sends before publishing and reject in-flight sends on later abort. Once `close()` starts, transports reject new `send()`/`emit()` calls instead of publishing work into a shutting-down lifecycle.
+- Importing the root `@fluojs/microservices` barrel and constructing `TcpMicroserviceTransport` do not load `node:net`; TCP loads Node networking only when `listen()` starts a server or an outbound `send()`/`emit()` constructs a socket. If startup fails while `close()` is waiting on an in-flight listen attempt, microservice shutdown still attempts transport cleanup before surfacing the captured listen error.
 - TCP accepts `port: 0` for tests and ephemeral listeners, then routes outbound `send()`/`emit()` calls through the OS-assigned port while the transport is listening.
 - gRPC shutdown uses server-level `tryShutdown()` when available and falls back to `forceShutdown()` only for runtimes without graceful shutdown support. AbortSignal cancellation for active unary or streaming calls uses the call-level `cancel()`/stream end path and removes abort listeners when streams end, error, or are returned early.
 - Event-handler failures that flow through the transport logger (`RedisPubSubMicroserviceTransport`, `RedisStreamsMicroserviceTransport`, `NatsMicroserviceTransport`, `MqttMicroserviceTransport`, and gRPC event emits) remain logger-driven. If you do not inject a transport logger, fluo does not mirror those failures through a raw `console.error` fallback.
@@ -157,7 +158,7 @@ class ManualMicroserviceProvidersModule {}
 
 ### Type exports
 
-The root barrel exports `Microservice`, `MicroserviceModuleOptions`, `MicroserviceModuleRegistrationOptions`, `MicroserviceTransport`, `Pattern`, `ServerStreamWriter`, and transport option types such as `GrpcMicroserviceTransportOptions`, `KafkaMicroserviceTransportOptions`, `MqttMicroserviceTransportOptions`, `NatsMicroserviceTransportOptions`, `RabbitMqMicroserviceTransportOptions`, `RedisPubSubMicroserviceTransportOptions`, `RedisStreamsMicroserviceTransportOptions`, and `RedisStreamClientLike`.
+The root barrel exports `Microservice`, `MicroserviceLifecycleState`, `MicroserviceHandlerCounts`, `MicroserviceModuleOptions`, `MicroserviceModuleRegistrationOptions`, `MicroservicePlatformStatusSnapshot`, `MicroserviceStatusAdapterInput`, `MicroserviceTransport`, `MicroserviceTransportCapabilities`, `Pattern`, `ServerStreamWriter`, and transport option types such as `GrpcMicroserviceTransportOptions`, `KafkaMicroserviceTransportOptions`, `MqttMicroserviceTransportOptions`, `NatsMicroserviceTransportOptions`, `RabbitMqMicroserviceTransportOptions`, `RedisPubSubMicroserviceTransportOptions`, `RedisStreamsMicroserviceTransportOptions`, and `RedisStreamClientLike`.
 
 ### Behavioral contracts
 

package/dist/service.d.ts

@@ -1,5 +1,5 @@
 import type { Container } from '@fluojs/di';
-import { type ApplicationLogger, type CompiledModule, type MicroserviceRuntime, type OnApplicationShutdown } from '@fluojs/runtime';
+import type { ApplicationLogger, CompiledModule, MicroserviceRuntime, OnApplicationShutdown } from '@fluojs/runtime';
 import type { Microservice, MicroserviceModuleOptions, ServerStreamWriter } from './types.js';
 /**
  * Lifecycle-managed microservice runtime that discovers pattern handlers and binds them to a transport.

package/dist/service.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"service.d.ts","sourceRoot":"","sources":["../src/service.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,SAAS,EAAY,MAAM,YAAY,CAAC;AACtD,OAAO,EACL,KAAK,iBAAiB,EACtB,KAAK,cAAc,EACnB,KAAK,mBAAmB,EACxB,KAAK,qBAAqB,EAC3B,MAAM,iBAAiB,CAAC;AAMzB,OAAO,KAAK,EAGV,YAAY,EACZ,yBAAyB,EAEzB,kBAAkB,EAEnB,MAAM,YAAY,CAAC;AA6BpB;;;;;GAKG;AACH,qBACa,4BAA6B,YAAW,YAAY,EAAE,mBAAmB,EAAE,qBAAqB;IASzG,OAAO,CAAC,QAAQ,CAAC,gBAAgB;IACjC,OAAO,CAAC,QAAQ,CAAC,eAAe;IAChC,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,aAAa;IAXhC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAA2B;IACvD,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAsC;IACvE,OAAO,CAAC,cAAc,CAAmF;IACzG,OAAO,CAAC,eAAe,CAAqB;IAC5C,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,aAAa,CAA4B;gBAG9B,gBAAgB,EAAE,SAAS,EAC3B,eAAe,EAAE,SAAS,cAAc,EAAE,EAC1C,MAAM,EAAE,iBAAiB,EACzB,aAAa,EAAE,yBAAyB;IAG3D;;;;OAIG;IACG,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC;IA2D7B;;;;OAIG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAkBtB,qBAAqB,IAAI,OAAO,CAAC,IAAI,CAAC;IAI5C;;;;OAIG;IACH,4BAA4B;IAqB5B;;;;;;;OAOG;IACG,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,OAAO,CAAC;IAIrF;;;;;;OAMG;IACG,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC;IAI5D;;;;;;;;;OASG;IACH,YAAY,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,aAAa,CAAC,OAAO,CAAC;IAU7F;;;;;;;;OAQG;IACH,YAAY,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG;QAAE,MAAM,EAAE,kBAAkB,CAAC;QAAC,MAAM,EAAE,OAAO,CAAC,OAAO,CAAC,CAAA;KAAE;IAU7G;;;;;;;;OAQG;IACH,UAAU,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG;QAAE,MAAM,EAAE,aAAa,CAAC,OAAO,CAAC,CAAC;QAAC,MAAM,EAAE,kBAAkB,CAAA;KAAE;YAUnG,cAAc;YAyBd,oBAAoB;YA+BpB,yBAAyB;YAiCzB,iCAAiC;YAuBjC,oBAAoB;YA4BpB,yBAAyB;YA+BzB,iCAAiC;YAsBjC,kBAAkB;YA+BlB,uBAAuB;YAiCvB,+BAA+B;YAuB/B,qBAAqB;YA8DrB,4BAA4B;IAK1C,OAAO,CAAC,cAAc;IAStB,OAAO,CAAC,0BAA0B;IAkClC,OAAO,CAAC,SAAS;IAQjB,OAAO,CAAC,WAAW;IA4BnB,OAAO,CAAC,mBAAmB;YAsCb,aAAa;YAuBb,qBAAqB;YA2BrB,+BAA+B;CAsB9C"}
+{"version":3,"file":"service.d.ts","sourceRoot":"","sources":["../src/service.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,SAAS,EAAY,MAAM,YAAY,CAAC;AACtD,OAAO,KAAK,EAAE,iBAAiB,EAAE,cAAc,EAAE,mBAAmB,EAAE,qBAAqB,EAAE,MAAM,iBAAiB,CAAC;AAMrH,OAAO,KAAK,EAGV,YAAY,EACZ,yBAAyB,EAEzB,kBAAkB,EAEnB,MAAM,YAAY,CAAC;AA6BpB;;;;;GAKG;AACH,qBACa,4BAA6B,YAAW,YAAY,EAAE,mBAAmB,EAAE,qBAAqB;IASzG,OAAO,CAAC,QAAQ,CAAC,gBAAgB;IACjC,OAAO,CAAC,QAAQ,CAAC,eAAe;IAChC,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,aAAa;IAXhC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAA2B;IACvD,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAsC;IACvE,OAAO,CAAC,cAAc,CAAmF;IACzG,OAAO,CAAC,eAAe,CAAqB;IAC5C,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,aAAa,CAA4B;gBAG9B,gBAAgB,EAAE,SAAS,EAC3B,eAAe,EAAE,SAAS,cAAc,EAAE,EAC1C,MAAM,EAAE,iBAAiB,EACzB,aAAa,EAAE,yBAAyB;IAG3D;;;;OAIG;IACG,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC;IA2D7B;;;;OAIG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IA+BtB,qBAAqB,IAAI,OAAO,CAAC,IAAI,CAAC;IAI5C;;;;OAIG;IACH,4BAA4B;IAqB5B;;;;;;;OAOG;IACG,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,OAAO,CAAC;IAIrF;;;;;;OAMG;IACG,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC;IAI5D;;;;;;;;;OASG;IACH,YAAY,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,aAAa,CAAC,OAAO,CAAC;IAU7F;;;;;;;;OAQG;IACH,YAAY,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG;QAAE,MAAM,EAAE,kBAAkB,CAAC;QAAC,MAAM,EAAE,OAAO,CAAC,OAAO,CAAC,CAAA;KAAE;IAU7G;;;;;;;;OAQG;IACH,UAAU,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG;QAAE,MAAM,EAAE,aAAa,CAAC,OAAO,CAAC,CAAC;QAAC,MAAM,EAAE,kBAAkB,CAAA;KAAE;YAUnG,cAAc;YAyBd,oBAAoB;YA+BpB,yBAAyB;YAiCzB,iCAAiC;YAuBjC,oBAAoB;YA4BpB,yBAAyB;YA+BzB,iCAAiC;YAsBjC,kBAAkB;YA+BlB,uBAAuB;YAiCvB,+BAA+B;YAuB/B,qBAAqB;YA8DrB,4BAA4B;IAK1C,OAAO,CAAC,cAAc;IAStB,OAAO,CAAC,0BAA0B;IAkClC,OAAO,CAAC,SAAS;IAQjB,OAAO,CAAC,WAAW;IA4BnB,OAAO,CAAC,mBAAmB;YAsCb,aAAa;YAuBb,qBAAqB;YA2BrB,+BAA+B;CAsB9C"}

package/dist/service.js

@@ -106,13 +106,23 @@ class MicroserviceLifecycleService {
    * @returns A promise that resolves once shutdown completes.
    */
   async close() {
+    let listenError;
     if (this.listenPromise) {
-      await this.listenPromise;
+      try {
+        await this.listenPromise;
+      } catch (error) {
+        listenError = error;
+      }
     }
     this.lifecycleState = 'stopping';
     try {
       await this.moduleOptions.transport.close();
       this.listening = false;
+      if (listenError) {
+        this.lifecycleState = 'failed';
+        this.lastListenError = listenError instanceof Error ? listenError.message : String(listenError);
+        throw listenError;
+      }
       this.lifecycleState = 'stopped';
     } catch (error) {
       this.lifecycleState = 'failed';

package/dist/transports/tcp-transport.d.ts

@@ -17,11 +17,12 @@ export declare class TcpMicroserviceTransport implements MicroserviceTransport {
     private closing;
     private handler;
     private listenPromise;
+    private server;
+    private serverPromise;
     private readonly sockets;
     private readonly host;
     private readonly maxFrameBytes;
     private readonly requestTimeoutMs;
-    private readonly server;
     /**
      * Creates a TCP transport bound to one host/port pair.
      *
@@ -35,6 +36,7 @@ export declare class TcpMicroserviceTransport implements MicroserviceTransport {
      * @returns A promise that resolves once the TCP server is listening.
      */
     listen(handler: TransportHandler): Promise<void>;
+    private startListening;
     /**
      * Emits one fire-and-forget event over the TCP transport.
      *
@@ -63,6 +65,7 @@ export declare class TcpMicroserviceTransport implements MicroserviceTransport {
     private assertAcceptingOutbound;
     private resolveConnectPort;
     private resolveBoundPort;
+    private ensureServer;
     private bindSocketParser;
     private writeLine;
     private serializeFrame;

package/dist/transports/tcp-transport.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tcp-transport.d.ts","sourceRoot":"","sources":["../../src/transports/tcp-transport.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,qBAAqB,EAAE,gBAAgB,EAAmB,MAAM,aAAa,CAAC;AAQ5F,UAAU,+BAA+B;IACvC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAID;;;;;GAKG;AACH,qBAAa,wBAAyB,YAAW,qBAAqB;IAoBxD,OAAO,CAAC,QAAQ,CAAC,OAAO;IAnBpC,OAAO,CAAC,SAAS,CAAqB;IACtC,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,OAAO,CAA+B;IAC9C,OAAO,CAAC,aAAa,CAA4B;IACjD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAqB;IAC7C,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAS;IAC9B,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAS;IACvC,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAS;IAC1C,OAAO,CAAC,QAAQ,CAAC,MAAM,CAIpB;IAEH;;;;OAIG;gBAC0B,OAAO,EAAE,+BAA+B;IAMrE;;;;;OAKG;IACG,MAAM,CAAC,OAAO,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC;IAgCtD;;;;;;OAMG;IACG,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC;IAK5D;;;;;;;OAOG;IACG,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,OAAO,CAAC;IAMrF;;;;OAIG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;YAgCd,mBAAmB;YA8BnB,cAAc;IA0G5B,OAAO,CAAC,uBAAuB;IAU/B,OAAO,CAAC,kBAAkB;IAQ1B,OAAO,CAAC,gBAAgB;IAUxB,OAAO,CAAC,gBAAgB;IAyCxB,OAAO,CAAC,SAAS;IAIjB,OAAO,CAAC,cAAc;CASvB"}
+{"version":3,"file":"tcp-transport.d.ts","sourceRoot":"","sources":["../../src/transports/tcp-transport.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,qBAAqB,EAAE,gBAAgB,EAAmB,MAAM,aAAa,CAAC;AAQ5F,UAAU,+BAA+B;IACvC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAID;;;;;GAKG;AACH,qBAAa,wBAAyB,YAAW,qBAAqB;IAiBxD,OAAO,CAAC,QAAQ,CAAC,OAAO;IAhBpC,OAAO,CAAC,SAAS,CAAqB;IACtC,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,OAAO,CAA+B;IAC9C,OAAO,CAAC,aAAa,CAA4B;IACjD,OAAO,CAAC,MAAM,CAAqB;IACnC,OAAO,CAAC,aAAa,CAA8B;IACnD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAqB;IAC7C,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAS;IAC9B,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAS;IACvC,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAS;IAE1C;;;;OAIG;gBAC0B,OAAO,EAAE,+BAA+B;IAMrE;;;;;OAKG;IACG,MAAM,CAAC,OAAO,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC;YAqBxC,cAAc;IAyB5B;;;;;;OAMG;IACG,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC;IAK5D;;;;;;;OAOG;IACG,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,OAAO,CAAC;IAMrF;;;;OAIG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;YA6Cd,mBAAmB;YA8BnB,cAAc;IA2G5B,OAAO,CAAC,uBAAuB;IAU/B,OAAO,CAAC,kBAAkB;IAQ1B,OAAO,CAAC,gBAAgB;YAUV,YAAY;IAyB1B,OAAO,CAAC,gBAAgB;IAyCxB,OAAO,CAAC,SAAS;IAIjB,OAAO,CAAC,cAAc;CASvB"}

package/dist/transports/tcp-transport.js

@@ -1,4 +1,3 @@
-import { createServer, Socket } from 'node:net';
 const DEFAULT_MAX_FRAME_BYTES = 1_048_576;
 
 /**
@@ -12,15 +11,12 @@ export class TcpMicroserviceTransport {
   closing = false;
   handler;
   listenPromise;
+  server;
+  serverPromise;
   sockets = new Set();
   host;
   maxFrameBytes;
   requestTimeoutMs;
-  server = createServer(socket => {
-    this.sockets.add(socket);
-    this.bindSocketParser(socket, async packet => this.handleInboundPacket(socket, packet));
-    socket.once('close', () => this.sockets.delete(socket));
-  });
 
   /**
    * Creates a TCP transport bound to one host/port pair.
@@ -45,25 +41,35 @@ export class TcpMicroserviceTransport {
       throw new Error('TcpMicroserviceTransport is closing. Wait for close() to complete before listen().');
     }
     this.handler = handler;
-    if (this.server.listening) {
+    if (this.listenPromise) {
+      await this.listenPromise;
       return;
     }
-    if (this.listenPromise) {
+    this.listenPromise = this.startListening();
+    try {
       await this.listenPromise;
+    } finally {
+      this.listenPromise = undefined;
+    }
+  }
+  async startListening() {
+    const server = await this.ensureServer();
+    if (this.closing) {
+      throw new Error('TcpMicroserviceTransport is closing. Wait for close() to complete before listen().');
+    }
+    if (server.listening) {
       return;
     }
-    this.listenPromise = new Promise((resolve, reject) => {
-      this.server.once('error', reject);
-      this.server.listen(this.options.port, this.host, () => {
-        this.server.off('error', reject);
+    await new Promise((resolve, reject) => {
+      server.once('error', reject);
+      server.listen(this.options.port, this.host, () => {
+        server.off('error', reject);
         this.boundPort = this.resolveBoundPort();
         resolve();
       });
     });
-    try {
-      await this.listenPromise;
-    } finally {
-      this.listenPromise = undefined;
+    if (this.closing) {
+      throw new Error('TcpMicroserviceTransport is closing. Wait for close() to complete before listen().');
     }
   }
 
@@ -109,19 +115,27 @@ export class TcpMicroserviceTransport {
    */
   async close() {
     this.closing = true;
+    let listenError;
     if (this.listenPromise) {
-      await this.listenPromise;
+      try {
+        await this.listenPromise;
+      } catch (error) {
+        listenError = error;
+      }
     }
     for (const socket of this.sockets) {
       socket.destroy();
     }
     this.sockets.clear();
-    if (!this.server.listening) {
+    if (!this.server?.listening) {
       this.boundPort = undefined;
+      if (listenError) {
+        throw listenError;
+      }
       return;
     }
     await new Promise((resolve, reject) => {
-      this.server.close(error => {
+      this.server?.close(error => {
         if (error) {
           reject(error);
           return;
@@ -130,6 +144,9 @@ export class TcpMicroserviceTransport {
       });
     });
     this.boundPort = undefined;
+    if (listenError) {
+      throw listenError;
+    }
   }
   async handleInboundPacket(socket, packet) {
     if (!this.handler) {
@@ -163,6 +180,9 @@ export class TcpMicroserviceTransport {
   }
   async sendWirePacket(packet, signal) {
     const serializedPacket = this.serializeFrame(packet);
+    const {
+      Socket
+    } = await import('node:net');
     return await new Promise((resolve, reject) => {
       const socket = new Socket();
       let settled = false;
@@ -255,7 +275,7 @@ export class TcpMicroserviceTransport {
     if (this.closing) {
       throw new Error(`TcpMicroserviceTransport is closing. Wait for close() to complete before ${operation}().`);
     }
-    if (!this.server.listening || typeof this.boundPort !== 'number') {
+    if (!this.server?.listening || typeof this.boundPort !== 'number') {
       throw new Error(`TcpMicroserviceTransport is not listening. Call listen() before ${operation}().`);
     }
   }
@@ -266,12 +286,35 @@ export class TcpMicroserviceTransport {
     return this.options.port;
   }
   resolveBoundPort() {
-    const address = this.server.address();
+    const address = this.server?.address();
     if (address && typeof address === 'object') {
       return address.port;
     }
     return this.options.port;
   }
+  async ensureServer() {
+    if (this.server) {
+      return this.server;
+    }
+    this.serverPromise ??= (async () => {
+      const {
+        createServer
+      } = await import('node:net');
+      const server = createServer(socket => {
+        this.sockets.add(socket);
+        this.bindSocketParser(socket, async packet => this.handleInboundPacket(socket, packet));
+        socket.once('close', () => this.sockets.delete(socket));
+      });
+      this.server = server;
+      return server;
+    })();
+    try {
+      return await this.serverPromise;
+    } catch (error) {
+      this.serverPromise = undefined;
+      throw error;
+    }
+  }
   bindSocketParser(socket, onPacket) {
     let buffer = '';
     let bufferBytes = 0;

package/package.json

@@ -13,7 +13,7 @@
     "grpc",
     "mqtt"
   ],
-  "version": "1.0.1",
+  "version": "1.0.3",
   "private": false,
   "license": "MIT",
   "repository": {
@@ -68,9 +68,9 @@
     "dist"
   ],
   "dependencies": {
-    "@fluojs/di": "^1.0.1",
-    "@fluojs/core": "^1.0.1",
-    "@fluojs/runtime": "^1.0.1"
+    "@fluojs/core": "^1.0.3",
+    "@fluojs/di": "^1.1.0",
+    "@fluojs/runtime": "^1.1.7"
   },
   "peerDependencies": {
     "@grpc/grpc-js": "^1.0.0",