@fluojs/microservices 1.0.0-beta.1

package/dist/transports/mqtt-transport.js

@@ -0,0 +1,460 @@
+import { logTransportEventHandlerFailure } from './event-handler-logger.js';
+const mqttKinds = {
+  event: 'event',
+  message: 'message',
+  response: 'response'
+};
+
+/** Options for configuring the MQTT microservice transport. */
+
+/**
+ * MQTT transport for topic-based request-response messages and event delivery.
+ *
+ * The adapter can either own its MQTT client or reuse one supplied by the application while
+ * keeping Fluo's message, event, and response channels isolated by topic.
+ */
+export class MqttMicroserviceTransport {
+  client;
+  closing = false;
+  handler;
+  internallyOwnedClient;
+  logger;
+  listening = false;
+  listenPromise;
+  messageListener = (topic, payload) => {
+    void this.handleInbound(topic, payload.toString('utf8')).catch(() => undefined);
+  };
+  eventQos;
+  eventRetain;
+  eventTopic;
+  messageQos;
+  messageRetain;
+  messageTopic;
+  pending = new Map();
+  replyTopic;
+  requestTimeoutMs;
+  responseQos;
+  responseRetain;
+
+  /**
+   * Creates an MQTT transport with topic, QoS, retain, and timeout settings.
+   *
+   * @param options MQTT client/module wiring and topic behavior for the transport.
+   */
+  constructor(options) {
+    this.options = options;
+    const namespace = options.namespace ?? 'fluo.microservices';
+    this.eventTopic = options.eventTopic ?? `${namespace}.events`;
+    this.messageTopic = options.messageTopic ?? `${namespace}.messages`;
+    this.replyTopic = options.replyTopic ?? `${namespace}.responses.${crypto.randomUUID()}`;
+    this.eventQos = options.eventQos ?? 0;
+    this.messageQos = options.messageQos ?? 1;
+    this.responseQos = options.responseQos ?? 1;
+    this.eventRetain = options.eventRetain ?? false;
+    this.messageRetain = options.messageRetain ?? false;
+    this.responseRetain = options.responseRetain ?? false;
+    this.requestTimeoutMs = options.requestTimeoutMs ?? 3_000;
+    this.client = options.client;
+    this.internallyOwnedClient = !options.client;
+  }
+  setLogger(logger) {
+    this.logger = logger;
+  }
+
+  /**
+   * Subscribes to the configured MQTT event, message, and reply topics.
+   *
+   * @param handler Runtime callback invoked for inbound event and message packets.
+   * @returns A promise that resolves once all subscriptions are active.
+   */
+  async listen(handler) {
+    this.closing = false;
+    this.handler = handler;
+    if (this.listening) {
+      return;
+    }
+    if (this.listenPromise) {
+      await this.listenPromise;
+      return;
+    }
+    this.listenPromise = (async () => {
+      const client = await this.resolveClient();
+      const subscribed = [];
+      client.on('message', this.messageListener);
+      try {
+        await this.subscribeTopic(client, this.eventTopic, this.eventQos);
+        subscribed.push(this.eventTopic);
+        await this.subscribeTopic(client, this.messageTopic, this.messageQos);
+        subscribed.push(this.messageTopic);
+        await this.subscribeTopic(client, this.replyTopic, this.responseQos);
+        subscribed.push(this.replyTopic);
+      } catch (error) {
+        for (const topic of subscribed) {
+          await this.unsubscribeTopic(client, topic).catch(() => undefined);
+        }
+        client.off?.('message', this.messageListener);
+        throw error;
+      }
+      this.listening = true;
+    })();
+    try {
+      await this.listenPromise;
+    } finally {
+      this.listenPromise = undefined;
+    }
+  }
+
+  /**
+   * Sends one request-response message through MQTT.
+   *
+   * @param pattern Pattern identifying the remote message handler.
+   * @param payload Serializable request payload.
+   * @param signal Optional abort signal used to cancel the request.
+   * @returns The remote handler response payload.
+   */
+  async send(pattern, payload, signal) {
+    if (this.closing) {
+      throw new Error('MqttMicroserviceTransport is closing. Wait for close() to complete before send().');
+    }
+    if (!this.listening) {
+      throw new Error('MqttMicroserviceTransport is not listening. Call listen() before send().');
+    }
+    const requestId = crypto.randomUUID();
+    const frame = {
+      kind: mqttKinds.message,
+      pattern,
+      payload,
+      requestId,
+      replyTopic: this.replyTopic
+    };
+    return await new Promise((resolve, reject) => {
+      let abortHandler;
+      let timeout;
+      let settled = false;
+      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);
+      timeout = setTimeout(() => {
+        entry.reject(new Error(`MQTT request timed out after ${String(this.requestTimeoutMs)}ms waiting for pattern "${pattern}".`));
+      }, this.requestTimeoutMs);
+      if (signal) {
+        if (signal.aborted) {
+          entry.reject(new Error('MQTT request aborted before publish.'));
+          return;
+        }
+        abortHandler = () => {
+          entry.reject(new Error('MQTT request aborted.'));
+        };
+        signal.addEventListener('abort', abortHandler, {
+          once: true
+        });
+      }
+      void Promise.resolve().then(async () => {
+        if (this.closing) {
+          entry.reject(new Error('MQTT microservice transport closed before response.'));
+          return;
+        }
+        const client = await this.resolveClient();
+        await this.publish(client, this.messageTopic, frame, {
+          qos: this.messageQos,
+          retain: this.messageRetain
+        });
+      }).catch(error => {
+        entry.reject(error instanceof Error ? error : new Error('Failed to publish MQTT request.'));
+      });
+    });
+  }
+
+  /**
+   * Emits one fire-and-forget event through MQTT.
+   *
+   * @param pattern Pattern identifying the remote event handler.
+   * @param payload Serializable event payload.
+   * @returns A promise that resolves once the event is published.
+   */
+  async emit(pattern, payload) {
+    if (this.closing) {
+      throw new Error('MqttMicroserviceTransport is closing. Wait for close() to complete before emit().');
+    }
+    const client = await this.resolveClient();
+    const frame = {
+      kind: mqttKinds.event,
+      pattern,
+      payload
+    };
+    await this.publish(client, this.eventTopic, frame, {
+      qos: this.eventQos,
+      retain: this.eventRetain
+    });
+  }
+
+  /**
+   * Unsubscribes from MQTT topics and closes the owned client when applicable.
+   *
+   * @returns A promise that resolves once shutdown cleanup completes.
+   */
+  async close() {
+    this.closing = true;
+    let closeError;
+    if (this.listenPromise) {
+      await this.listenPromise;
+    }
+    try {
+      const client = this.client;
+      if (client && this.listening) {
+        for (const topic of [this.eventTopic, this.messageTopic, this.replyTopic]) {
+          try {
+            await this.unsubscribeTopic(client, topic);
+          } catch (error) {
+            closeError ??= error;
+          }
+        }
+      }
+      if (client) {
+        client.off?.('message', this.messageListener);
+        if (this.internallyOwnedClient) {
+          try {
+            await this.endClient(client);
+          } catch (error) {
+            closeError ??= error;
+          }
+        }
+      }
+    } finally {
+      this.handler = undefined;
+      this.listening = false;
+      if (this.internallyOwnedClient) {
+        this.client = undefined;
+      }
+      for (const pending of [...this.pending.values()]) {
+        pending.reject(new Error('MQTT microservice transport closed before response.'));
+      }
+    }
+    if (closeError) {
+      throw closeError;
+    }
+  }
+  async handleInbound(topic, rawMessage) {
+    const frame = parseEnvelope(rawMessage);
+    if (!frame) {
+      return;
+    }
+    if (topic === this.replyTopic) {
+      this.handleInboundResponse(frame);
+      return;
+    }
+    if (!this.handler) {
+      return;
+    }
+    if (topic === this.eventTopic && frame.kind === mqttKinds.event) {
+      await this.handleInboundEvent(frame);
+      return;
+    }
+    if (topic === this.messageTopic && frame.kind === mqttKinds.message && frame.requestId) {
+      await this.handleInboundRequest(frame);
+    }
+  }
+  async handleInboundEvent(frame) {
+    if (!this.handler) {
+      return;
+    }
+    try {
+      await this.handler({
+        kind: 'event',
+        pattern: frame.pattern,
+        payload: frame.payload
+      });
+    } catch (error) {
+      this.logEventHandlerFailure(error);
+    }
+  }
+  async handleInboundRequest(frame) {
+    if (!this.handler || !frame.requestId) {
+      return;
+    }
+    const client = this.client;
+    if (!client) {
+      return;
+    }
+    const replyTopic = frame.replyTopic && frame.replyTopic.length > 0 ? frame.replyTopic : this.replyTopic;
+    try {
+      const payload = await this.handler({
+        kind: 'message',
+        pattern: frame.pattern,
+        payload: frame.payload,
+        requestId: frame.requestId
+      });
+      await this.publish(client, replyTopic, {
+        kind: mqttKinds.response,
+        pattern: frame.pattern,
+        payload,
+        requestId: frame.requestId
+      }, {
+        qos: this.responseQos,
+        retain: this.responseRetain
+      });
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : 'Unhandled microservice error';
+      await this.publish(client, replyTopic, {
+        error: errorMessage,
+        kind: mqttKinds.response,
+        pattern: frame.pattern,
+        requestId: frame.requestId
+      }, {
+        qos: this.responseQos,
+        retain: this.responseRetain
+      });
+    }
+  }
+  handleInboundResponse(frame) {
+    if (frame.kind !== mqttKinds.response || !frame.requestId) {
+      return;
+    }
+    const pending = this.pending.get(frame.requestId);
+    if (!pending) {
+      return;
+    }
+    if (frame.error) {
+      pending.reject(new Error(frame.error));
+      return;
+    }
+    pending.resolve(frame.payload);
+  }
+  async resolveClient() {
+    if (this.client) {
+      return this.client;
+    }
+    const mqtt = await this.resolveMqttModule();
+    const url = this.options.url;
+    if (!url || url.length === 0) {
+      throw new Error('MqttMicroserviceTransport requires options.url when options.client is not provided.');
+    }
+    this.client = mqtt.connect(url, this.options.connectOptions);
+    return this.client;
+  }
+  async resolveMqttModule() {
+    if (this.options.mqtt) {
+      return this.options.mqtt;
+    }
+    const moduleLoader = this.options.moduleLoader ?? defaultDynamicImport;
+    try {
+      const loaded = await moduleLoader('mqtt');
+      const mqtt = loaded.default ?? loaded;
+      if (!mqtt || typeof mqtt !== 'object' || typeof mqtt.connect !== 'function') {
+        throw new Error('Failed to load mqtt runtime module.');
+      }
+      return mqtt;
+    } catch (error) {
+      throw createMissingPeerDependencyError('mqtt', error);
+    }
+  }
+  async publish(client, topic, message, options) {
+    await new Promise((resolve, reject) => {
+      client.publish(topic, JSON.stringify(message), options, error => {
+        if (error) {
+          reject(error);
+          return;
+        }
+        resolve();
+      });
+    });
+  }
+  async subscribeTopic(client, topic, qos) {
+    await new Promise((resolve, reject) => {
+      client.subscribe(topic, {
+        qos
+      }, error => {
+        if (error) {
+          reject(error);
+          return;
+        }
+        resolve();
+      });
+    });
+  }
+  async unsubscribeTopic(client, topic) {
+    await new Promise((resolve, reject) => {
+      client.unsubscribe(topic, error => {
+        if (error) {
+          reject(error);
+          return;
+        }
+        resolve();
+      });
+    });
+  }
+  async endClient(client) {
+    await new Promise((resolve, reject) => {
+      client.end(false, error => {
+        if (error) {
+          reject(error);
+          return;
+        }
+        resolve();
+      });
+    });
+  }
+  logEventHandlerFailure(error) {
+    logTransportEventHandlerFailure(this.logger, 'MqttMicroserviceTransport', error);
+  }
+}
+function parseEnvelope(rawMessage) {
+  let parsed;
+  try {
+    parsed = JSON.parse(rawMessage);
+  } catch {
+    return undefined;
+  }
+  if (!parsed || typeof parsed !== 'object') {
+    return undefined;
+  }
+  const candidate = parsed;
+  if (candidate.kind !== mqttKinds.event && candidate.kind !== mqttKinds.message && candidate.kind !== mqttKinds.response) {
+    return undefined;
+  }
+  if (typeof candidate.pattern !== 'string') {
+    return undefined;
+  }
+  if (candidate.error !== undefined && typeof candidate.error !== 'string') {
+    return undefined;
+  }
+  if (candidate.requestId !== undefined && typeof candidate.requestId !== 'string') {
+    return undefined;
+  }
+  if (candidate.replyTopic !== undefined && typeof candidate.replyTopic !== 'string') {
+    return undefined;
+  }
+  return candidate;
+}
+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 MqttMicroserviceTransport. Install it with "pnpm add ${specifier}" in your application.${details}`);
+}
+const defaultDynamicImport = async specifier => {
+  return await import(specifier);
+};

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

@@ -0,0 +1,92 @@
+import type { MicroserviceTransport, MicroserviceTransportLogger, TransportHandler } from '../types.js';
+interface NatsMessageLike {
+    readonly data: Uint8Array;
+    respond(data: Uint8Array): void;
+}
+interface NatsCodecLike {
+    decode(data: Uint8Array): string;
+    encode(value: string): Uint8Array;
+}
+interface NatsSubscriptionLike {
+    unsubscribe(): void;
+}
+interface NatsLike {
+    close?(): void;
+    publish(subject: string, payload: Uint8Array): void;
+    request(subject: string, payload: Uint8Array, options?: {
+        timeout?: number;
+    }): Promise<{
+        data: Uint8Array;
+    }>;
+    subscribe(subject: string, handler: (message: NatsMessageLike) => void): NatsSubscriptionLike;
+}
+/** Options for configuring the NATS microservice transport. */
+export interface NatsMicroserviceTransportOptions {
+    client: NatsLike;
+    codec: NatsCodecLike;
+    eventSubject?: string;
+    messageSubject?: string;
+    requestTimeoutMs?: number;
+}
+/**
+ * NATS transport for request-response messages and fire-and-forget event delivery.
+ *
+ * The adapter maps Fluo message traffic onto separate event and request subjects while
+ * preserving JSON framing and NATS request timeout behavior.
+ */
+export declare class NatsMicroserviceTransport implements MicroserviceTransport {
+    private readonly options;
+    private closing;
+    private handler;
+    private logger;
+    private listening;
+    private readonly eventSubject;
+    private readonly messageSubject;
+    private readonly pending;
+    private readonly requestTimeoutMs;
+    private subscriptions;
+    private logEventHandlerFailure;
+    private handleEventMessageSafely;
+    /**
+     * Creates a NATS transport using a client and codec supplied by the application.
+     *
+     * @param options Subject names, codec, client, and request-timeout settings.
+     */
+    constructor(options: NatsMicroserviceTransportOptions);
+    setLogger(logger: MicroserviceTransportLogger): void;
+    /**
+     * Subscribes to the configured NATS event and message subjects.
+     *
+     * @param handler Runtime callback invoked for inbound event and message packets.
+     * @returns A promise that resolves once subscriptions are active.
+     */
+    listen(handler: TransportHandler): Promise<void>;
+    /**
+     * Sends one request-response message through NATS request/reply.
+     *
+     * @param pattern Pattern identifying the remote message handler.
+     * @param payload Serializable request payload.
+     * @returns The decoded remote handler response payload.
+     */
+    send(pattern: string, payload: unknown): Promise<unknown>;
+    /**
+     * Emits one fire-and-forget event through the configured NATS event subject.
+     *
+     * @param pattern Pattern identifying the remote event handler.
+     * @param payload Serializable event payload.
+     * @returns A promise that resolves once the event is published.
+     */
+    emit(pattern: string, payload: unknown): Promise<void>;
+    /**
+     * Unsubscribes from NATS subjects and closes the client when supported.
+     *
+     * @returns A promise that resolves once shutdown cleanup completes.
+     */
+    close(): Promise<void>;
+    private handleEventMessage;
+    private handleRequestMessage;
+    private decode;
+    private encode;
+}
+export {};
+//# sourceMappingURL=nats-transport.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"nats-transport.d.ts","sourceRoot":"","sources":["../../src/transports/nats-transport.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,qBAAqB,EAAE,2BAA2B,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAGxG,UAAU,eAAe;IACvB,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;IAC1B,OAAO,CAAC,IAAI,EAAE,UAAU,GAAG,IAAI,CAAC;CACjC;AAED,UAAU,aAAa;IACrB,MAAM,CAAC,IAAI,EAAE,UAAU,GAAG,MAAM,CAAC;IACjC,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,UAAU,CAAC;CACnC;AAED,UAAU,oBAAoB;IAC5B,WAAW,IAAI,IAAI,CAAC;CACrB;AAED,UAAU,QAAQ;IAChB,KAAK,CAAC,IAAI,IAAI,CAAC;IACf,OAAO,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,UAAU,GAAG,IAAI,CAAC;IACpD,OAAO,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,UAAU,EAAE,OAAO,CAAC,EAAE;QAAE,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC;QAAE,IAAI,EAAE,UAAU,CAAA;KAAE,CAAC,CAAC;IAC7G,SAAS,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,OAAO,EAAE,eAAe,KAAK,IAAI,GAAG,oBAAoB,CAAC;CAC/F;AAED,+DAA+D;AAC/D,MAAM,WAAW,gCAAgC;IAC/C,MAAM,EAAE,QAAQ,CAAC;IACjB,KAAK,EAAE,aAAa,CAAC;IACrB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAkBD;;;;;GAKG;AACH,qBAAa,yBAA0B,YAAW,qBAAqB;IA0BzD,OAAO,CAAC,QAAQ,CAAC,OAAO;IAzBpC,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,OAAO,CAA+B;IAC9C,OAAO,CAAC,MAAM,CAA0C;IACxD,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAS;IACtC,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAS;IACxC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAqC;IAC7D,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAS;IAC1C,OAAO,CAAC,aAAa,CAA8B;IAEnD,OAAO,CAAC,sBAAsB;IAI9B,OAAO,CAAC,wBAAwB;IAMhC;;;;OAIG;gBAC0B,OAAO,EAAE,gCAAgC;IAMtE,SAAS,CAAC,MAAM,EAAE,2BAA2B,GAAG,IAAI;IAIpD;;;;;OAKG;IACG,MAAM,CAAC,OAAO,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC;IAmBtD;;;;;;OAMG;IACG,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC;IAmE/D;;;;;;OAMG;IACG,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC;IAU5D;;;;OAIG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;YA2Bd,kBAAkB;YAsBlB,oBAAoB;IAwBlC,OAAO,CAAC,MAAM;IAId,OAAO,CAAC,MAAM;CAGf"}