@fluojs/microservices 1.0.0-beta.1

package/dist/service.js

@@ -0,0 +1,550 @@
+let _initClass;
+function _applyDecs(e, t, n, r, o, i) { var a, c, u, s, f, l, p, d = Symbol.metadata || Symbol.for("Symbol.metadata"), m = Object.defineProperty, h = Object.create, y = [h(null), h(null)], v = t.length; function g(t, n, r) { return function (o, i) { n && (i = o, o = e); for (var a = 0; a < t.length; a++) i = t[a].apply(o, r ? [i] : []); return r ? i : o; }; } function b(e, t, n, r) { if ("function" != typeof e && (r || void 0 !== e)) throw new TypeError(t + " must " + (n || "be") + " a function" + (r ? "" : " or undefined")); return e; } function applyDec(e, t, n, r, o, i, u, s, f, l, p) { function d(e) { if (!p(e)) throw new TypeError("Attempted to access private element on non-instance"); } var h = [].concat(t[0]), v = t[3], w = !u, D = 1 === o, S = 3 === o, j = 4 === o, E = 2 === o; function I(t, n, r) { return function (o, i) { return n && (i = o, o = e), r && r(o), P[t].call(o, i); }; } if (!w) { var P = {}, k = [], F = S ? "get" : j || D ? "set" : "value"; if (f ? (l || D ? P = { get: _setFunctionName(function () { return v(this); }, r, "get"), set: function (e) { t[4](this, e); } } : P[F] = v, l || _setFunctionName(P[F], r, E ? "" : F)) : l || (P = Object.getOwnPropertyDescriptor(e, r)), !l && !f) { if ((c = y[+s][r]) && 7 !== (c ^ o)) throw Error("Decorating two elements with the same name (" + P[F].name + ") is not supported yet"); y[+s][r] = o < 3 ? 1 : o; } } for (var N = e, O = h.length - 1; O >= 0; O -= n ? 2 : 1) { var T = b(h[O], "A decorator", "be", !0), z = n ? h[O - 1] : void 0, A = {}, H = { kind: ["field", "accessor", "method", "getter", "setter", "class"][o], name: r, metadata: a, addInitializer: function (e, t) { if (e.v) throw new TypeError("attempted to call addInitializer after decoration was finished"); b(t, "An initializer", "be", !0), i.push(t); }.bind(null, A) }; if (w) c = T.call(z, N, H), A.v = 1, b(c, "class decorators", "return") && (N = c);else if (H.static = s, H.private = f, c = H.access = { has: f ? p.bind() : function (e) { return r in e; } }, j || (c.get = f ? E ? function (e) { return d(e), P.value; } : I("get", 0, d) : function (e) { return e[r]; }), E || S || (c.set = f ? I("set", 0, d) : function (e, t) { e[r] = t; }), N = T.call(z, D ? { get: P.get, set: P.set } : P[F], H), A.v = 1, D) { if ("object" == typeof N && N) (c = b(N.get, "accessor.get")) && (P.get = c), (c = b(N.set, "accessor.set")) && (P.set = c), (c = b(N.init, "accessor.init")) && k.unshift(c);else if (void 0 !== N) throw new TypeError("accessor decorators must return an object with get, set, or init properties or undefined"); } else b(N, (l ? "field" : "method") + " decorators", "return") && (l ? k.unshift(N) : P[F] = N); } return o < 2 && u.push(g(k, s, 1), g(i, s, 0)), l || w || (f ? D ? u.splice(-1, 0, I("get", s), I("set", s)) : u.push(E ? P[F] : b.call.bind(P[F])) : m(e, r, P)), N; } function w(e) { return m(e, d, { configurable: !0, enumerable: !0, value: a }); } return void 0 !== i && (a = i[d]), a = h(null == a ? null : a), f = [], l = function (e) { e && f.push(g(e)); }, p = function (t, r) { for (var i = 0; i < n.length; i++) { var a = n[i], c = a[1], l = 7 & c; if ((8 & c) == t && !l == r) { var p = a[2], d = !!a[3], m = 16 & c; applyDec(t ? e : e.prototype, a, m, d ? "#" + p : _toPropertyKey(p), l, l < 2 ? [] : t ? s = s || [] : u = u || [], f, !!t, d, r, t && d ? function (t) { return _checkInRHS(t) === e; } : o); } } }, p(8, 0), p(0, 0), p(8, 1), p(0, 1), l(u), l(s), c = f, v || w(e), { e: c, get c() { var n = []; return v && [w(e = applyDec(e, [t], r, e.name, 5, n)), g(n, 1)]; } }; }
+function _toPropertyKey(t) { var i = _toPrimitive(t, "string"); return "symbol" == typeof i ? i : i + ""; }
+function _toPrimitive(t, r) { if ("object" != typeof t || !t) return t; var e = t[Symbol.toPrimitive]; if (void 0 !== e) { var i = e.call(t, r || "default"); if ("object" != typeof i) return i; throw new TypeError("@@toPrimitive must return a primitive value."); } return ("string" === r ? String : Number)(t); }
+function _setFunctionName(e, t, n) { "symbol" == typeof t && (t = (t = t.description) ? "[" + t + "]" : ""); try { Object.defineProperty(e, "name", { configurable: !0, value: n ? n + " " + t : t }); } catch (e) {} return e; }
+function _checkInRHS(e) { if (Object(e) !== e) throw TypeError("right-hand side of 'in' should be an object, got " + (null !== e ? typeof e : "null")); return e; }
+import { Inject } from '@fluojs/core';
+import { cloneWithFallback, getClassDiMetadata } from '@fluojs/core/internal';
+import { APPLICATION_LOGGER, COMPILED_MODULES, RUNTIME_CONTAINER } from '@fluojs/runtime/internal';
+import { getHandlerMetadataEntries } from './metadata.js';
+import { createMicroservicePlatformStatusSnapshot } from './status.js';
+import { MICROSERVICE_OPTIONS } from './tokens.js';
+function methodKeyToName(methodKey) {
+  return typeof methodKey === 'symbol' ? methodKey.toString() : methodKey;
+}
+function scopeFromProvider(provider) {
+  if (typeof provider === 'function') {
+    return getClassDiMetadata(provider)?.scope ?? 'singleton';
+  }
+  if ('useClass' in provider) {
+    return provider.scope ?? getClassDiMetadata(provider.useClass)?.scope ?? 'singleton';
+  }
+  return 'scope' in provider ? provider.scope ?? 'singleton' : 'singleton';
+}
+function isClassProvider(provider) {
+  return typeof provider === 'object' && provider !== null && 'useClass' in provider;
+}
+
+/**
+ * Lifecycle-managed microservice runtime that discovers pattern handlers and binds them to a transport.
+ *
+ * The service resolves singleton or request-scoped handlers, exposes programmatic
+ * send/emit/stream APIs, and delegates transport-specific I/O to the configured adapter.
+ */
+let _MicroserviceLifecycl;
+class MicroserviceLifecycleService {
+  static {
+    [_MicroserviceLifecycl, _initClass] = _applyDecs(this, [Inject(RUNTIME_CONTAINER, COMPILED_MODULES, APPLICATION_LOGGER, MICROSERVICE_OPTIONS)], []).c;
+  }
+  descriptors = [];
+  handlerInstances = new Map();
+  lifecycleState = 'created';
+  lastListenError;
+  listening = false;
+  listenPromise;
+  constructor(runtimeContainer, compiledModules, logger, moduleOptions) {
+    this.runtimeContainer = runtimeContainer;
+    this.compiledModules = compiledModules;
+    this.logger = logger;
+    this.moduleOptions = moduleOptions;
+  }
+
+  /**
+   * Starts transport listeners and discovers decorated handlers.
+   *
+   * @returns A promise that resolves once the configured transport is ready to accept traffic.
+   */
+  async listen() {
+    if (this.listening) {
+      return;
+    }
+    if (this.listenPromise) {
+      await this.listenPromise;
+      return;
+    }
+    this.listenPromise = (async () => {
+      this.lifecycleState = 'starting';
+      this.lastListenError = undefined;
+      this.descriptors.length = 0;
+      this.descriptors.push(...this.discoverHandlerDescriptors());
+      const transport = this.moduleOptions.transport;
+      transport.setLogger?.(this.logger);
+      if (transport.listenServerStreaming) {
+        transport.listenServerStreaming(async (pattern, payload, writer) => {
+          await this.dispatchServerStream(pattern, cloneWithFallback(payload), writer);
+        });
+      }
+      if (transport.listenClientStreaming) {
+        transport.listenClientStreaming(async (pattern, reader) => {
+          return await this.dispatchClientStream(pattern, reader);
+        });
+      }
+      if (transport.listenBidiStreaming) {
+        transport.listenBidiStreaming(async (pattern, reader, writer) => {
+          await this.dispatchBidiStream(pattern, reader, writer);
+        });
+      }
+      await transport.listen(async packet => this.dispatchPacket(packet));
+      this.listening = true;
+      this.lifecycleState = 'ready';
+    })();
+    try {
+      await this.listenPromise;
+    } catch (error) {
+      this.lifecycleState = 'failed';
+      this.lastListenError = error instanceof Error ? error.message : String(error);
+      throw error;
+    } finally {
+      this.listenPromise = undefined;
+    }
+  }
+
+  /**
+   * Closes the configured transport and stops accepting microservice traffic.
+   *
+   * @returns A promise that resolves once shutdown completes.
+   */
+  async close() {
+    if (this.listenPromise) {
+      await this.listenPromise;
+    }
+    this.lifecycleState = 'stopping';
+    try {
+      await this.moduleOptions.transport.close();
+      this.listening = false;
+      this.lifecycleState = 'stopped';
+    } catch (error) {
+      this.lifecycleState = 'failed';
+      this.lastListenError = error instanceof Error ? error.message : String(error);
+      throw error;
+    }
+  }
+  async onApplicationShutdown() {
+    await this.close();
+  }
+
+  /**
+   * Creates a platform status snapshot for health checks and diagnostics.
+   *
+   * @returns A structured snapshot describing handler counts, transport capabilities, and lifecycle state.
+   */
+  createPlatformStatusSnapshot() {
+    return createMicroservicePlatformStatusSnapshot({
+      handlerCounts: {
+        'bidi-stream': this.descriptors.filter(descriptor => descriptor.kind === 'bidi-stream').length,
+        'client-stream': this.descriptors.filter(descriptor => descriptor.kind === 'client-stream').length,
+        event: this.descriptors.filter(descriptor => descriptor.kind === 'event').length,
+        message: this.descriptors.filter(descriptor => descriptor.kind === 'message').length,
+        'server-stream': this.descriptors.filter(descriptor => descriptor.kind === 'server-stream').length
+      },
+      lastListenError: this.lastListenError,
+      lifecycleState: this.lifecycleState,
+      transportCapabilities: {
+        bidiStream: typeof this.moduleOptions.transport.bidiStream === 'function',
+        clientStream: typeof this.moduleOptions.transport.clientStream === 'function',
+        emit: typeof this.moduleOptions.transport.emit === 'function',
+        send: typeof this.moduleOptions.transport.send === 'function',
+        serverStream: typeof this.moduleOptions.transport.serverStream === 'function'
+      }
+    });
+  }
+
+  /**
+   * Sends one request-response message through the configured transport.
+   *
+   * @param pattern Pattern identifying the remote handler.
+   * @param payload Serializable payload forwarded to the transport.
+   * @param signal Optional abort signal passed to the transport.
+   * @returns The transport response payload.
+   */
+  async send(pattern, payload, signal) {
+    return this.moduleOptions.transport.send(pattern, cloneWithFallback(payload), signal);
+  }
+
+  /**
+   * Emits one fire-and-forget event through the configured transport.
+   *
+   * @param pattern Pattern identifying the remote event channel.
+   * @param payload Serializable payload forwarded to the transport.
+   * @returns A promise that resolves once the transport accepts the event.
+   */
+  async emit(pattern, payload) {
+    await this.moduleOptions.transport.emit(pattern, cloneWithFallback(payload));
+  }
+
+  /**
+   * Opens a server-streaming request through the configured transport.
+   *
+   * @param pattern Pattern identifying the remote server-stream handler.
+   * @param payload Serializable request payload forwarded to the transport.
+   * @param signal Optional abort signal passed to the transport.
+   * @returns An async iterable of stream messages.
+   *
+   * @throws {Error} When the configured transport does not implement `serverStream()`.
+   */
+  serverStream(pattern, payload, signal) {
+    const transport = this.moduleOptions.transport;
+    if (!transport.serverStream) {
+      throw new Error('The configured transport does not support server streaming. Use a transport that implements serverStream().');
+    }
+    return transport.serverStream(pattern, cloneWithFallback(payload), signal);
+  }
+
+  /**
+   * Opens a client-streaming request through the configured transport.
+   *
+   * @param pattern Pattern identifying the remote client-stream handler.
+   * @param signal Optional abort signal passed to the transport.
+   * @returns A writer for request chunks plus a promise for the final response.
+   *
+   * @throws {Error} When the configured transport does not implement `clientStream()`.
+   */
+  clientStream(pattern, signal) {
+    const transport = this.moduleOptions.transport;
+    if (!transport.clientStream) {
+      throw new Error('The configured transport does not support client streaming. Use a transport that implements clientStream().');
+    }
+    return transport.clientStream(pattern, signal);
+  }
+
+  /**
+   * Opens a bidirectional stream through the configured transport.
+   *
+   * @param pattern Pattern identifying the remote bidi-stream handler.
+   * @param signal Optional abort signal passed to the transport.
+   * @returns A reader for response chunks and a writer for outbound chunks.
+   *
+   * @throws {Error} When the configured transport does not implement `bidiStream()`.
+   */
+  bidiStream(pattern, signal) {
+    const transport = this.moduleOptions.transport;
+    if (!transport.bidiStream) {
+      throw new Error('The configured transport does not support bidirectional streaming. Use a transport that implements bidiStream().');
+    }
+    return transport.bidiStream(pattern, signal);
+  }
+  async dispatchPacket(packet) {
+    const matches = this.descriptors.filter(descriptor => descriptor.kind === packet.kind && this.matchesPattern(descriptor.pattern, packet.pattern));
+    if (packet.kind === 'message') {
+      if (matches.length > 1) {
+        throw new Error(`Multiple message handlers matched pattern "${packet.pattern}": ${matches.map(descriptor => `${descriptor.targetName}.${descriptor.methodName}`).join(', ')}.`);
+      }
+      const first = matches[0];
+      if (!first) {
+        throw new Error(`No message handler registered for pattern "${packet.pattern}".`);
+      }
+      return await this.invokeHandler(first, cloneWithFallback(packet.payload));
+    }
+    return await this.dispatchEventHandlers(matches, cloneWithFallback(packet.payload));
+  }
+  async dispatchServerStream(pattern, payload, writer) {
+    const matches = this.descriptors.filter(descriptor => descriptor.kind === 'server-stream' && this.matchesPattern(descriptor.pattern, pattern));
+    if (matches.length > 1) {
+      const errorMsg = `Multiple server-stream handlers matched pattern "${pattern}": ${matches.map(descriptor => `${descriptor.targetName}.${descriptor.methodName}`).join(', ')}.`;
+      writer.error(new Error(errorMsg));
+      return;
+    }
+    const first = matches[0];
+    if (!first) {
+      writer.error(new Error(`No server-stream handler registered for pattern "${pattern}".`));
+      return;
+    }
+    try {
+      await this.invokeServerStreamHandler(first, payload, writer);
+    } catch (error) {
+      this.logger.error(`Server-stream handler ${first.targetName}.${first.methodName} failed.`, error, 'MicroserviceLifecycleService');
+      writer.error(error instanceof Error ? error : new Error('Server-stream handler failed.'));
+    }
+  }
+  async invokeServerStreamHandler(descriptor, payload, writer) {
+    if (descriptor.scope === 'singleton') {
+      return await this.invokeResolvedServerStreamHandler(await this.resolveSingletonHandlerInstance(descriptor), descriptor, payload, writer);
+    }
+    const streamScope = this.runtimeContainer.createRequestScope();
+    try {
+      const instance = await streamScope.resolve(descriptor.token);
+      await this.invokeResolvedServerStreamHandler(instance, descriptor, payload, writer);
+    } finally {
+      try {
+        await streamScope.dispose();
+      } catch (error) {
+        this.logger.error(`Failed to dispose microservice server-stream scope for ${descriptor.targetName}.${descriptor.methodName}.`, error, 'MicroserviceLifecycleService');
+      }
+    }
+  }
+  async invokeResolvedServerStreamHandler(instance, descriptor, payload, writer) {
+    if (!instance) {
+      throw new Error(`Failed to resolve microservice target ${descriptor.targetName} from module ${descriptor.moduleName}.`);
+    }
+    const value = instance[descriptor.methodKey];
+    if (typeof value !== 'function') {
+      throw new Error(`Microservice handler ${descriptor.targetName}.${descriptor.methodName} must be a callable function.`);
+    }
+    await Promise.resolve(value.call(instance, payload, writer));
+  }
+  async dispatchClientStream(pattern, reader) {
+    const matches = this.descriptors.filter(descriptor => descriptor.kind === 'client-stream' && this.matchesPattern(descriptor.pattern, pattern));
+    if (matches.length > 1) {
+      throw new Error(`Multiple client-stream handlers matched pattern "${pattern}": ${matches.map(descriptor => `${descriptor.targetName}.${descriptor.methodName}`).join(', ')}.`);
+    }
+    const first = matches[0];
+    if (!first) {
+      throw new Error(`No client-stream handler registered for pattern "${pattern}".`);
+    }
+    try {
+      return await this.invokeClientStreamHandler(first, reader);
+    } catch (error) {
+      this.logger.error(`Client-stream handler ${first.targetName}.${first.methodName} failed.`, error, 'MicroserviceLifecycleService');
+      throw error;
+    }
+  }
+  async invokeClientStreamHandler(descriptor, reader) {
+    if (descriptor.scope === 'singleton') {
+      return await this.invokeResolvedClientStreamHandler(await this.resolveSingletonHandlerInstance(descriptor), descriptor, reader);
+    }
+    const streamScope = this.runtimeContainer.createRequestScope();
+    try {
+      const instance = await streamScope.resolve(descriptor.token);
+      return await this.invokeResolvedClientStreamHandler(instance, descriptor, reader);
+    } finally {
+      try {
+        await streamScope.dispose();
+      } catch (error) {
+        this.logger.error(`Failed to dispose microservice client-stream scope for ${descriptor.targetName}.${descriptor.methodName}.`, error, 'MicroserviceLifecycleService');
+      }
+    }
+  }
+  async invokeResolvedClientStreamHandler(instance, descriptor, reader) {
+    if (!instance) {
+      throw new Error(`Failed to resolve microservice target ${descriptor.targetName} from module ${descriptor.moduleName}.`);
+    }
+    const value = instance[descriptor.methodKey];
+    if (typeof value !== 'function') {
+      throw new Error(`Microservice handler ${descriptor.targetName}.${descriptor.methodName} must be a callable function.`);
+    }
+    return await Promise.resolve(value.call(instance, reader));
+  }
+  async dispatchBidiStream(pattern, reader, writer) {
+    const matches = this.descriptors.filter(descriptor => descriptor.kind === 'bidi-stream' && this.matchesPattern(descriptor.pattern, pattern));
+    if (matches.length > 1) {
+      const errorMsg = `Multiple bidi-stream handlers matched pattern "${pattern}": ${matches.map(descriptor => `${descriptor.targetName}.${descriptor.methodName}`).join(', ')}.`;
+      writer.error(new Error(errorMsg));
+      return;
+    }
+    const first = matches[0];
+    if (!first) {
+      writer.error(new Error(`No bidi-stream handler registered for pattern "${pattern}".`));
+      return;
+    }
+    try {
+      await this.invokeBidiStreamHandler(first, reader, writer);
+    } catch (error) {
+      this.logger.error(`Bidi-stream handler ${first.targetName}.${first.methodName} failed.`, error, 'MicroserviceLifecycleService');
+      writer.error(error instanceof Error ? error : new Error('Bidi-stream handler failed.'));
+    }
+  }
+  async invokeBidiStreamHandler(descriptor, reader, writer) {
+    if (descriptor.scope === 'singleton') {
+      return await this.invokeResolvedBidiStreamHandler(await this.resolveSingletonHandlerInstance(descriptor), descriptor, reader, writer);
+    }
+    const streamScope = this.runtimeContainer.createRequestScope();
+    try {
+      const instance = await streamScope.resolve(descriptor.token);
+      await this.invokeResolvedBidiStreamHandler(instance, descriptor, reader, writer);
+    } finally {
+      try {
+        await streamScope.dispose();
+      } catch (error) {
+        this.logger.error(`Failed to dispose microservice bidi-stream scope for ${descriptor.targetName}.${descriptor.methodName}.`, error, 'MicroserviceLifecycleService');
+      }
+    }
+  }
+  async invokeResolvedBidiStreamHandler(instance, descriptor, reader, writer) {
+    if (!instance) {
+      throw new Error(`Failed to resolve microservice target ${descriptor.targetName} from module ${descriptor.moduleName}.`);
+    }
+    const value = instance[descriptor.methodKey];
+    if (typeof value !== 'function') {
+      throw new Error(`Microservice handler ${descriptor.targetName}.${descriptor.methodName} must be a callable function.`);
+    }
+    await Promise.resolve(value.call(instance, reader, writer));
+  }
+  async dispatchEventHandlers(descriptors, payload) {
+    const singletonDescriptors = descriptors.filter(descriptor => descriptor.scope === 'singleton');
+    const scopedDescriptors = descriptors.filter(descriptor => descriptor.scope !== 'singleton');
+    const singletonResults = await Promise.allSettled(singletonDescriptors.map(descriptor => this.invokeHandler(descriptor, cloneWithFallback(payload))));
+    for (const result of singletonResults) {
+      if (result.status === 'rejected') {
+        this.logger.error('Event handler failed during singleton dispatch.', result.reason, 'MicroserviceLifecycleService');
+      }
+    }
+    if (scopedDescriptors.length === 0) {
+      return undefined;
+    }
+    const perEventScope = this.runtimeContainer.createRequestScope();
+    const scopeErrors = [];
+    try {
+      const scopedResults = await Promise.allSettled(scopedDescriptors.map(descriptor => this.invokeResolvedHandlerInScope(perEventScope, descriptor, cloneWithFallback(payload))));
+      for (const result of scopedResults) {
+        if (result.status === 'rejected') {
+          scopeErrors.push(result.reason instanceof Error ? result.reason : new Error(String(result.reason)));
+        }
+      }
+    } finally {
+      try {
+        await perEventScope.dispose();
+      } catch (disposeError) {
+        this.logger.error('Failed to dispose per-event scope.', disposeError, 'MicroserviceLifecycleService');
+      }
+    }
+    if (scopeErrors.length > 0) {
+      for (const error of scopeErrors) {
+        this.logger.error('Scoped event handler failed.', error, 'MicroserviceLifecycleService');
+      }
+    }
+    return undefined;
+  }
+  async invokeResolvedHandlerInScope(scope, descriptor, payload) {
+    const instance = await scope.resolve(descriptor.token);
+    return await this.invokeResolvedHandler(instance, descriptor, payload);
+  }
+  matchesPattern(pattern, input) {
+    if (pattern instanceof RegExp) {
+      pattern.lastIndex = 0;
+      return pattern.test(input);
+    }
+    return pattern === input;
+  }
+  discoverHandlerDescriptors() {
+    const seen = new WeakMap();
+    const descriptors = [];
+    for (const candidate of this.discoveryCandidates()) {
+      const entries = getHandlerMetadataEntries(candidate.targetType.prototype);
+      for (const entry of entries) {
+        const dedupeKey = this.dedupeKey(entry.metadata.kind, entry.metadata.pattern);
+        if (this.isDuplicate(seen, candidate.targetType, entry.propertyKey, dedupeKey)) {
+          this.logger.warn(`Duplicate microservice handler registration for ${dedupeKey} on ${candidate.targetType.name}.${methodKeyToName(entry.propertyKey)} was ignored.`, 'MicroserviceLifecycleService');
+          continue;
+        }
+        descriptors.push({
+          kind: entry.metadata.kind,
+          methodKey: entry.propertyKey,
+          methodName: methodKeyToName(entry.propertyKey),
+          moduleName: candidate.moduleName,
+          pattern: entry.metadata.pattern,
+          scope: candidate.scope,
+          targetName: candidate.targetType.name,
+          token: candidate.token
+        });
+      }
+    }
+    return descriptors;
+  }
+  dedupeKey(kind, pattern) {
+    if (pattern instanceof RegExp) {
+      return `${kind}:/${pattern.source}/${pattern.flags}`;
+    }
+    return `${kind}:${pattern}`;
+  }
+  isDuplicate(seen, targetType, methodKey, dedupeKey) {
+    let methodsByKey = seen.get(targetType);
+    if (!methodsByKey) {
+      methodsByKey = new Map();
+      seen.set(targetType, methodsByKey);
+    }
+    let seenPatterns = methodsByKey.get(methodKey);
+    if (!seenPatterns) {
+      seenPatterns = new Set();
+      methodsByKey.set(methodKey, seenPatterns);
+    }
+    if (seenPatterns.has(dedupeKey)) {
+      return true;
+    }
+    seenPatterns.add(dedupeKey);
+    return false;
+  }
+  discoveryCandidates() {
+    const candidates = [];
+    for (const compiledModule of this.compiledModules) {
+      for (const provider of compiledModule.definition.providers ?? []) {
+        if (typeof provider === 'function') {
+          candidates.push({
+            moduleName: compiledModule.type.name,
+            scope: scopeFromProvider(provider),
+            targetType: provider,
+            token: provider
+          });
+          continue;
+        }
+        if (isClassProvider(provider)) {
+          candidates.push({
+            moduleName: compiledModule.type.name,
+            scope: scopeFromProvider(provider),
+            targetType: provider.useClass,
+            token: provider.provide
+          });
+        }
+      }
+      for (const controller of compiledModule.definition.controllers ?? []) {
+        candidates.push({
+          moduleName: compiledModule.type.name,
+          scope: scopeFromProvider(controller),
+          targetType: controller,
+          token: controller
+        });
+      }
+    }
+    return candidates;
+  }
+  async invokeHandler(descriptor, payload) {
+    if (descriptor.scope === 'singleton') {
+      return await this.invokeResolvedHandler(await this.resolveSingletonHandlerInstance(descriptor), descriptor, payload);
+    }
+    const messageScope = this.runtimeContainer.createRequestScope();
+    try {
+      const instance = await messageScope.resolve(descriptor.token);
+      return await this.invokeResolvedHandler(instance, descriptor, payload);
+    } finally {
+      try {
+        await messageScope.dispose();
+      } catch (error) {
+        this.logger.error(`Failed to dispose microservice request scope for ${descriptor.targetName}.${descriptor.methodName}.`, error, 'MicroserviceLifecycleService');
+      }
+    }
+  }
+  async invokeResolvedHandler(instance, descriptor, payload) {
+    if (!instance) {
+      throw new Error(`Failed to resolve microservice target ${descriptor.targetName} from module ${descriptor.moduleName}.`);
+    }
+    const value = instance[descriptor.methodKey];
+    if (typeof value !== 'function') {
+      throw new Error(`Microservice handler ${descriptor.targetName}.${descriptor.methodName} must be a callable function.`);
+    }
+    try {
+      return await Promise.resolve(value.call(instance, payload));
+    } catch (error) {
+      this.logger.error(`Microservice handler ${descriptor.targetName}.${descriptor.methodName} failed.`, error, 'MicroserviceLifecycleService');
+      throw error;
+    }
+  }
+  async resolveSingletonHandlerInstance(descriptor) {
+    const cached = this.handlerInstances.get(descriptor.token);
+    if (cached) {
+      return await cached;
+    }
+    const resolving = this.runtimeContainer.resolve(descriptor.token);
+    this.handlerInstances.set(descriptor.token, resolving);
+    try {
+      return await resolving;
+    } catch (error) {
+      this.handlerInstances.delete(descriptor.token);
+      this.logger.error(`Failed to resolve microservice target ${descriptor.targetName} from module ${descriptor.moduleName}.`, error, 'MicroserviceLifecycleService');
+      throw error;
+    }
+  }
+  static {
+    _initClass();
+  }
+}
+export { _MicroserviceLifecycl as MicroserviceLifecycleService };

package/dist/status.d.ts

@@ -0,0 +1,30 @@
+import type { PlatformHealthReport, PlatformReadinessReport, PlatformSnapshot } from '@fluojs/runtime';
+export type MicroserviceLifecycleState = 'created' | 'starting' | 'ready' | 'stopping' | 'stopped' | 'failed';
+export interface MicroserviceHandlerCounts {
+    'bidi-stream': number;
+    'client-stream': number;
+    event: number;
+    message: number;
+    'server-stream': number;
+}
+export interface MicroserviceTransportCapabilities {
+    bidiStream: boolean;
+    clientStream: boolean;
+    emit: boolean;
+    send: boolean;
+    serverStream: boolean;
+}
+export interface MicroserviceStatusAdapterInput {
+    handlerCounts: MicroserviceHandlerCounts;
+    lastListenError?: string;
+    lifecycleState: MicroserviceLifecycleState;
+    transportCapabilities: MicroserviceTransportCapabilities;
+}
+export interface MicroservicePlatformStatusSnapshot {
+    readiness: PlatformReadinessReport;
+    health: PlatformHealthReport;
+    ownership: PlatformSnapshot['ownership'];
+    details: Record<string, unknown>;
+}
+export declare function createMicroservicePlatformStatusSnapshot(input: MicroserviceStatusAdapterInput): MicroservicePlatformStatusSnapshot;
+//# sourceMappingURL=status.d.ts.map

package/dist/status.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"status.d.ts","sourceRoot":"","sources":["../src/status.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,oBAAoB,EAAE,uBAAuB,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AAEvG,MAAM,MAAM,0BAA0B,GAAG,SAAS,GAAG,UAAU,GAAG,OAAO,GAAG,UAAU,GAAG,SAAS,GAAG,QAAQ,CAAC;AAE9G,MAAM,WAAW,yBAAyB;IACxC,aAAa,EAAE,MAAM,CAAC;IACtB,eAAe,EAAE,MAAM,CAAC;IACxB,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,eAAe,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,iCAAiC;IAChD,UAAU,EAAE,OAAO,CAAC;IACpB,YAAY,EAAE,OAAO,CAAC;IACtB,IAAI,EAAE,OAAO,CAAC;IACd,IAAI,EAAE,OAAO,CAAC;IACd,YAAY,EAAE,OAAO,CAAC;CACvB;AAED,MAAM,WAAW,8BAA8B;IAC7C,aAAa,EAAE,yBAAyB,CAAC;IACzC,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,cAAc,EAAE,0BAA0B,CAAC;IAC3C,qBAAqB,EAAE,iCAAiC,CAAC;CAC1D;AAED,MAAM,WAAW,kCAAkC;IACjD,SAAS,EAAE,uBAAuB,CAAC;IACnC,MAAM,EAAE,oBAAoB,CAAC;IAC7B,SAAS,EAAE,gBAAgB,CAAC,WAAW,CAAC,CAAC;IACzC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAClC;AAqED,wBAAgB,wCAAwC,CACtD,KAAK,EAAE,8BAA8B,GACpC,kCAAkC,CAoBpC"}

package/dist/status.js

@@ -0,0 +1,79 @@
+function createReadiness(input) {
+  if (input.lifecycleState === 'ready') {
+    return {
+      critical: true,
+      status: 'ready'
+    };
+  }
+  if (input.lifecycleState === 'starting') {
+    return {
+      critical: true,
+      reason: 'Microservice transport listener is still starting.',
+      status: 'degraded'
+    };
+  }
+  if (input.lifecycleState === 'failed') {
+    return {
+      critical: true,
+      reason: input.lastListenError ?? 'Microservice transport listener failed to start.',
+      status: 'not-ready'
+    };
+  }
+  if (input.lifecycleState === 'stopping') {
+    return {
+      critical: true,
+      reason: 'Microservice transport listener is shutting down.',
+      status: 'not-ready'
+    };
+  }
+  if (input.lifecycleState === 'stopped') {
+    return {
+      critical: true,
+      reason: 'Microservice transport listener is stopped.',
+      status: 'not-ready'
+    };
+  }
+  return {
+    critical: true,
+    reason: 'Microservice transport listener has not started yet.',
+    status: 'not-ready'
+  };
+}
+function createHealth(input) {
+  if (input.lifecycleState === 'failed' || input.lifecycleState === 'stopped') {
+    return {
+      reason: input.lastListenError ?? 'Microservice transport listener is unavailable.',
+      status: 'unhealthy'
+    };
+  }
+  if (input.lifecycleState === 'starting' || input.lifecycleState === 'stopping') {
+    return {
+      reason: 'Microservice transport listener is transitioning lifecycle state.',
+      status: 'degraded'
+    };
+  }
+  return {
+    status: 'healthy'
+  };
+}
+export function createMicroservicePlatformStatusSnapshot(input) {
+  return {
+    details: {
+      dependencies: ['transport.external'],
+      handlerCounts: {
+        ...input.handlerCounts
+      },
+      lastListenError: input.lastListenError,
+      lifecycleState: input.lifecycleState,
+      transportCapabilities: {
+        ...input.transportCapabilities
+      }
+    },
+    health: createHealth(input),
+    ownership: {
+      externallyManaged: true,
+      ownsResources: false
+    },
+    readiness: createReadiness(input)
+  };
+}

package/dist/tokens.d.ts

@@ -0,0 +1,7 @@
+import type { Token } from '@fluojs/core';
+import type { Microservice, MicroserviceModuleOptions } from './types.js';
+/** Compatibility injection token for the programmatic microservice facade. */
+export declare const MICROSERVICE: Token<Microservice>;
+/** Injection token for the configured transport and runtime module options. */
+export declare const MICROSERVICE_OPTIONS: Token<MicroserviceModuleOptions>;
+//# sourceMappingURL=tokens.d.ts.map

package/dist/tokens.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tokens.d.ts","sourceRoot":"","sources":["../src/tokens.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,cAAc,CAAC;AAE1C,OAAO,KAAK,EAAE,YAAY,EAAE,yBAAyB,EAAE,MAAM,YAAY,CAAC;AAE1E,8EAA8E;AAC9E,eAAO,MAAM,YAAY,EAAE,KAAK,CAAC,YAAY,CAA4C,CAAC;AAC1F,+EAA+E;AAC/E,eAAO,MAAM,oBAAoB,EAAE,KAAK,CAAC,yBAAyB,CAA4C,CAAC"}