@truefoundry/trueforge-core 0.0.0 → 0.1.0-rc.0

package/dist/request-reply/executor.d.ts

@@ -0,0 +1,70 @@
+import type { RedisClientType } from 'redis';
+import type { Logger } from 'winston';
+import type { RequestHandler } from './types';
+export interface RunExecutorOptions {
+    /** How often to refresh the heartbeat key (ms). */
+    heartbeatIntervalMs: number;
+    /** TTL for the reply value so abandoned keys are reclaimed (ms). */
+    replyTtlMs: number;
+}
+/** Observability hook for subscriber errors, failed SUBSCRIBEs, and malformed messages. */
+export type RequestReplyErrorHandler = (err: Error, context: {
+    executorId: string;
+    channel: string;
+}) => void;
+/**
+ * Serving side of the request-reply transport: parses and validates each
+ * published message, dispatches it to the request handler, writes the
+ * JSONReply to the request's reply key, and refreshes the heartbeat key while
+ * subscribed.
+ *
+ * Connection lifecycle stays with the caller: both clients are supplied
+ * connected and are never closed here. `subscriberClient` is the connection to
+ * SUBSCRIBE on — a `duplicate()` for standalone Redis, or the shared client
+ * for Sentinel — and must have a reconnect strategy so a failed connect
+ * self-heals (the executor re-subscribes on every `ready`).
+ */
+export declare class RequestReplyExecutor {
+    readonly executorId: string;
+    /** `rr:req:<executorId>` — the channel this executor subscribes to. */
+    readonly channel: string;
+    private readonly redis;
+    private readonly subscriberClient;
+    private readonly logger;
+    private readonly heartbeatIntervalMs;
+    private readonly heartbeatTtlMs;
+    private readonly replyTtlMs;
+    private readonly heartbeatKey;
+    private readonly requestHandler;
+    private readonly onError;
+    /** Stable reference so node-redis dedupes the listener across re-subscribes. */
+    private readonly subscribeListener;
+    private closed;
+    private initialized;
+    private runningRequests;
+    private heartbeatTimer;
+    constructor({ executorId, redis, subscriberClient, requestHandler, onError, logger, options, }: {
+        executorId: string;
+        /** Connected command client, used only for SET (reply + heartbeat). Caller owns its lifecycle. */
+        redis: RedisClientType;
+        /** Connected client to SUBSCRIBE on (duplicate or Sentinel). Caller owns its lifecycle. */
+        subscriberClient: RedisClientType;
+        requestHandler: RequestHandler;
+        onError?: RequestReplyErrorHandler | undefined;
+        logger: Logger;
+        options?: Partial<RunExecutorOptions> | undefined;
+    });
+    init(): Promise<void>;
+    private setupSubscriber;
+    private beat;
+    /** Heartbeat only while subscribed. Idempotent (restarts the timer). */
+    private startHeartbeat;
+    /** A stopped heartbeat makes callers fail fast with NoResponderError. */
+    private stopHeartbeat;
+    private processRequestFromMessage;
+    /** One raw pub/sub payload. Never throws. */
+    private onMessage;
+    close(): Promise<void>;
+    drain(): Promise<void>;
+}
+//# sourceMappingURL=executor.d.ts.map

package/dist/request-reply/executor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"executor.d.ts","sourceRoot":"","sources":["../../src/request-reply/executor.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,OAAO,CAAC;AAC7C,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,SAAS,CAAC;AAItC,OAAO,KAAK,EAAa,cAAc,EAAE,MAAM,SAAS,CAAC;AAIzD,MAAM,WAAW,kBAAkB;IACjC,mDAAmD;IACnD,mBAAmB,EAAE,MAAM,CAAC;IAC5B,oEAAoE;IACpE,UAAU,EAAE,MAAM,CAAC;CACpB;AAYD,2FAA2F;AAC3F,MAAM,MAAM,wBAAwB,GAAG,CAAC,GAAG,EAAE,KAAK,EAAE,OAAO,EAAE;IAAE,UAAU,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,KAAK,IAAI,CAAC;AAE9G;;;;;;;;;;;GAWG;AACH,qBAAa,oBAAoB;IAC/B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,uEAAuE;IACvE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAkB;IACxC,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAkB;IACnD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,mBAAmB,CAAS;IAC7C,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAS;IACxC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAS;IACtC,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAiB;IAChD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAuC;IAC/D,gFAAgF;IAChF,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAEhC;IAEF,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,WAAW,CAAS;IAC5B,OAAO,CAAC,eAAe,CAAoC;IAC3D,OAAO,CAAC,cAAc,CAA+C;IAErE,YAAY,EACV,UAAU,EACV,KAAK,EACL,gBAAgB,EAChB,cAAc,EACd,OAAO,EACP,MAAM,EACN,OAAO,GACR,EAAE;QACD,UAAU,EAAE,MAAM,CAAC;QACnB,kGAAkG;QAClG,KAAK,EAAE,eAAe,CAAC;QACvB,2FAA2F;QAC3F,gBAAgB,EAAE,eAAe,CAAC;QAClC,cAAc,EAAE,cAAc,CAAC;QAC/B,OAAO,CAAC,EAAE,wBAAwB,GAAG,SAAS,CAAC;QAC/C,MAAM,EAAE,MAAM,CAAC;QACf,OAAO,CAAC,EAAE,OAAO,CAAC,kBAAkB,CAAC,GAAG,SAAS,CAAC;KACnD,EAaA;IAEK,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CA6B1B;YAEa,eAAe;YAoBf,IAAI;IAYlB,wEAAwE;IACxE,OAAO,CAAC,cAAc;IAYtB,yEAAyE;IACzE,OAAO,CAAC,aAAa;YAQP,yBAAyB;IA8DvC,6CAA6C;IAC7C,OAAO,CAAC,SAAS;IAsBX,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAY3B;IAIK,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAG3B;CACF"}

package/dist/request-reply/executor.js

@@ -0,0 +1,267 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/request-reply/executor.ts
+var executor_exports = {};
+__export(executor_exports, {
+  RequestReplyExecutor: () => RequestReplyExecutor
+});
+module.exports = __toCommonJS(executor_exports);
+var import_node_crypto = require("crypto");
+var import_zod = __toESM(require("zod"), 1);
+var import_errorLogFields = require("../core/util/errorLogFields.js");
+var import_errors = require("./errors.js");
+var import_types = require("./types.js");
+var import_utils = require("./utils.js");
+var DEFAULT_HEARTBEAT_INTERVAL_MS = 5e3;
+var DEFAULT_REPLY_TTL_MS = 12e4;
+function resolveRunExecutorOptions(options) {
+  return {
+    heartbeatIntervalMs: options?.heartbeatIntervalMs ?? DEFAULT_HEARTBEAT_INTERVAL_MS,
+    replyTtlMs: options?.replyTtlMs ?? DEFAULT_REPLY_TTL_MS
+  };
+}
+var RequestReplyExecutor = class {
+  executorId;
+  /** `rr:req:<executorId>` — the channel this executor subscribes to. */
+  channel;
+  redis;
+  subscriberClient;
+  logger;
+  heartbeatIntervalMs;
+  heartbeatTtlMs;
+  replyTtlMs;
+  heartbeatKey;
+  requestHandler;
+  onError;
+  /** Stable reference so node-redis dedupes the listener across re-subscribes. */
+  subscribeListener = (message) => {
+    this.onMessage(message);
+  };
+  closed = false;
+  initialized = false;
+  runningRequests = /* @__PURE__ */ new Map();
+  heartbeatTimer = null;
+  constructor({
+    executorId,
+    redis,
+    subscriberClient,
+    requestHandler,
+    onError,
+    logger,
+    options
+  }) {
+    const { heartbeatIntervalMs, replyTtlMs } = resolveRunExecutorOptions(options);
+    this.executorId = executorId;
+    this.redis = redis;
+    this.subscriberClient = subscriberClient;
+    this.logger = logger;
+    this.replyTtlMs = replyTtlMs;
+    this.requestHandler = requestHandler;
+    this.onError = onError;
+    this.channel = (0, import_utils.requestChannel)(executorId);
+    this.heartbeatKey = (0, import_utils.heartbeatKey)(executorId);
+    this.heartbeatIntervalMs = heartbeatIntervalMs;
+    this.heartbeatTtlMs = Math.ceil(this.heartbeatIntervalMs * 1.5);
+  }
+  async init() {
+    if (this.closed || this.initialized) {
+      return;
+    }
+    this.initialized = true;
+    this.subscriberClient.on("error", (err) => {
+      this.logger.error("[RequestReplyExecutor] Subscriber error", {
+        executorId: this.executorId,
+        ...(0, import_errorLogFields.extractErrorLogFields)(err)
+      });
+      this.onError?.(err, { executorId: this.executorId, channel: this.channel });
+      this.stopHeartbeat();
+    });
+    this.subscriberClient.on("end", () => {
+      this.logger.warn("[RequestReplyExecutor] Subscriber connection ended", { executorId: this.executorId });
+      this.stopHeartbeat();
+    });
+    this.subscriberClient.on("ready", () => {
+      void this.setupSubscriber();
+    });
+    if (this.subscriberClient.isReady) {
+      await this.setupSubscriber();
+    }
+  }
+  async setupSubscriber() {
+    if (this.closed) {
+      return;
+    }
+    try {
+      await this.subscriberClient.subscribe(this.channel, this.subscribeListener);
+      this.logger.info("[RequestReplyExecutor] Subscribed to request channel", { executorId: this.executorId });
+      this.stopHeartbeat();
+      this.startHeartbeat();
+    } catch (err) {
+      const error = err instanceof Error ? err : new Error(String(err), { cause: err });
+      this.logger.error("[RequestReplyExecutor] Error subscribing to request channel", {
+        executorId: this.executorId,
+        ...(0, import_errorLogFields.extractErrorLogFields)(error)
+      });
+      this.onError?.(error, { executorId: this.executorId, channel: this.channel });
+      this.stopHeartbeat();
+    }
+  }
+  async beat() {
+    this.logger.debug("[RequestReplyExecutor] Beating heartbeat", { executorId: this.executorId });
+    try {
+      await this.redis.set(this.heartbeatKey, "1", { PX: this.heartbeatTtlMs });
+    } catch (err) {
+      this.logger.error("[RequestReplyExecutor] Heartbeat error", {
+        executorId: this.executorId,
+        ...(0, import_errorLogFields.extractErrorLogFields)(err)
+      });
+    }
+  }
+  /** Heartbeat only while subscribed. Idempotent (restarts the timer). */
+  startHeartbeat() {
+    if (this.closed) {
+      return;
+    }
+    this.logger.info("[RequestReplyExecutor] Starting heartbeat", { executorId: this.executorId });
+    this.stopHeartbeat();
+    void this.beat();
+    this.heartbeatTimer = setInterval(() => {
+      void this.beat();
+    }, this.heartbeatIntervalMs);
+  }
+  /** A stopped heartbeat makes callers fail fast with NoResponderError. */
+  stopHeartbeat() {
+    if (this.heartbeatTimer) {
+      this.logger.info("[RequestReplyExecutor] Stopping heartbeat", { executorId: this.executorId });
+      clearInterval(this.heartbeatTimer);
+      this.heartbeatTimer = null;
+    }
+  }
+  async processRequestFromMessage(message) {
+    let raw;
+    try {
+      raw = JSON.parse(message);
+    } catch (err) {
+      this.logger.warn("[RequestReplyExecutor] Request message is not valid JSON", { executorId: this.executorId });
+      this.onError?.(
+        new Error(`Request message is not valid JSON for executorId: ${this.executorId}`, {
+          cause: err
+        }),
+        {
+          executorId: this.executorId,
+          channel: this.channel
+        }
+      );
+      return;
+    }
+    const parsedRequest = import_types.publishedRequestSchema.safeParse(raw);
+    if (!parsedRequest.success) {
+      const zodError = import_zod.default.treeifyError(parsedRequest.error);
+      this.logger.warn("[RequestReplyExecutor] Invalid request message shape", {
+        executorId: this.executorId,
+        zod: zodError
+      });
+      this.onError?.(
+        new Error(
+          `Invalid request message shape for executorId: ${this.executorId}, error: ${JSON.stringify(zodError)}`,
+          { cause: parsedRequest.error }
+        ),
+        { executorId: this.executorId, channel: this.channel }
+      );
+      return;
+    }
+    const { replyKey, path, body, headers } = parsedRequest.data;
+    let replyPayload;
+    try {
+      replyPayload = await this.requestHandler(path, { body, headers });
+    } catch (err) {
+      if (err instanceof import_errors.ReplyError) {
+        replyPayload = { status: err.status, headers: {}, body: { message: err.message } };
+      } else {
+        const message2 = err instanceof Error ? err.message : String(err);
+        replyPayload = { status: 500, headers: {}, body: { message: message2 } };
+      }
+    }
+    try {
+      await this.redis.set(replyKey, JSON.stringify(replyPayload), { PX: this.replyTtlMs });
+    } catch (err) {
+      this.logger.error("[RequestReplyExecutor] Request processing failed", {
+        executorId: this.executorId,
+        replyKey,
+        ...(0, import_errorLogFields.extractErrorLogFields)(err)
+      });
+    }
+  }
+  /** One raw pub/sub payload. Never throws. */
+  onMessage(message) {
+    this.logger.debug("[RequestReplyExecutor] Received message", { executorId: this.executorId, message });
+    if (!message) {
+      return;
+    }
+    if (this.closed) {
+      this.logger.warn("[RequestReplyExecutor] Received message after executor is closed", {
+        executorId: this.executorId,
+        message
+      });
+      return;
+    }
+    const pid = (0, import_node_crypto.randomUUID)();
+    const requestPromise = this.processRequestFromMessage(message).finally(() => {
+      this.runningRequests.delete(pid);
+    });
+    this.runningRequests.set(pid, requestPromise);
+  }
+  // This function should never throw!
+  // Stops intake: unsubscribe from the channel and stop the heartbeat. Never
+  // closes the clients — the caller owns their lifecycle.
+  async close() {
+    if (this.closed) {
+      return;
+    }
+    this.logger.info("[RequestReplyExecutor] Closing", { executorId: this.executorId });
+    this.closed = true;
+    try {
+      await this.subscriberClient.unsubscribe(this.channel);
+    } catch {
+    }
+    this.stopHeartbeat();
+  }
+  // This function should never throw!
+  // This is called during graceful shutdown
+  async drain() {
+    await this.close();
+    await Promise.allSettled(Array.from(this.runningRequests.values()));
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  RequestReplyExecutor
+});
+//# sourceMappingURL=executor.js.map

package/dist/request-reply/executor.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/request-reply/executor.ts"],"sourcesContent":["import { randomUUID } from 'node:crypto';\nimport type { RedisClientType } from 'redis';\nimport type { Logger } from 'winston';\nimport z from 'zod';\nimport { extractErrorLogFields } from '../core/util/errorLogFields';\nimport { ReplyError } from './errors';\nimport type { JSONReply, RequestHandler } from './types';\nimport { publishedRequestSchema } from './types';\nimport { heartbeatKey, requestChannel } from './utils';\n\nexport interface RunExecutorOptions {\n  /** How often to refresh the heartbeat key (ms). */\n  heartbeatIntervalMs: number;\n  /** TTL for the reply value so abandoned keys are reclaimed (ms). */\n  replyTtlMs: number;\n}\n\nconst DEFAULT_HEARTBEAT_INTERVAL_MS = 5_000;\nconst DEFAULT_REPLY_TTL_MS = 120_000;\n\nfunction resolveRunExecutorOptions(options: Partial<RunExecutorOptions> | undefined): RunExecutorOptions {\n  return {\n    heartbeatIntervalMs: options?.heartbeatIntervalMs ?? DEFAULT_HEARTBEAT_INTERVAL_MS,\n    replyTtlMs: options?.replyTtlMs ?? DEFAULT_REPLY_TTL_MS,\n  };\n}\n\n/** Observability hook for subscriber errors, failed SUBSCRIBEs, and malformed messages. */\nexport type RequestReplyErrorHandler = (err: Error, context: { executorId: string; channel: string }) => void;\n\n/**\n * Serving side of the request-reply transport: parses and validates each\n * published message, dispatches it to the request handler, writes the\n * JSONReply to the request's reply key, and refreshes the heartbeat key while\n * subscribed.\n *\n * Connection lifecycle stays with the caller: both clients are supplied\n * connected and are never closed here. `subscriberClient` is the connection to\n * SUBSCRIBE on — a `duplicate()` for standalone Redis, or the shared client\n * for Sentinel — and must have a reconnect strategy so a failed connect\n * self-heals (the executor re-subscribes on every `ready`).\n */\nexport class RequestReplyExecutor {\n  readonly executorId: string;\n  /** `rr:req:<executorId>` — the channel this executor subscribes to. */\n  readonly channel: string;\n  private readonly redis: RedisClientType;\n  private readonly subscriberClient: RedisClientType;\n  private readonly logger: Logger;\n  private readonly heartbeatIntervalMs: number;\n  private readonly heartbeatTtlMs: number;\n  private readonly replyTtlMs: number;\n  private readonly heartbeatKey: string;\n  private readonly requestHandler: RequestHandler;\n  private readonly onError: RequestReplyErrorHandler | undefined;\n  /** Stable reference so node-redis dedupes the listener across re-subscribes. */\n  private readonly subscribeListener = (message: string): void => {\n    this.onMessage(message);\n  };\n\n  private closed = false;\n  private initialized = false;\n  private runningRequests = new Map<string, Promise<void>>();\n  private heartbeatTimer: ReturnType<typeof setInterval> | null = null;\n\n  constructor({\n    executorId,\n    redis,\n    subscriberClient,\n    requestHandler,\n    onError,\n    logger,\n    options,\n  }: {\n    executorId: string;\n    /** Connected command client, used only for SET (reply + heartbeat). Caller owns its lifecycle. */\n    redis: RedisClientType;\n    /** Connected client to SUBSCRIBE on (duplicate or Sentinel). Caller owns its lifecycle. */\n    subscriberClient: RedisClientType;\n    requestHandler: RequestHandler;\n    onError?: RequestReplyErrorHandler | undefined;\n    logger: Logger;\n    options?: Partial<RunExecutorOptions> | undefined;\n  }) {\n    const { heartbeatIntervalMs, replyTtlMs } = resolveRunExecutorOptions(options);\n    this.executorId = executorId;\n    this.redis = redis;\n    this.subscriberClient = subscriberClient;\n    this.logger = logger;\n    this.replyTtlMs = replyTtlMs;\n    this.requestHandler = requestHandler;\n    this.onError = onError;\n    this.channel = requestChannel(executorId);\n    this.heartbeatKey = heartbeatKey(executorId);\n    this.heartbeatIntervalMs = heartbeatIntervalMs;\n    this.heartbeatTtlMs = Math.ceil(this.heartbeatIntervalMs * 1.5);\n  }\n\n  async init(): Promise<void> {\n    if (this.closed || this.initialized) {\n      return;\n    }\n    this.initialized = true;\n\n    this.subscriberClient.on('error', (err: Error) => {\n      this.logger.error('[RequestReplyExecutor] Subscriber error', {\n        executorId: this.executorId,\n        ...extractErrorLogFields(err),\n      });\n      this.onError?.(err, { executorId: this.executorId, channel: this.channel });\n      this.stopHeartbeat();\n    });\n    this.subscriberClient.on('end', () => {\n      this.logger.warn('[RequestReplyExecutor] Subscriber connection ended', { executorId: this.executorId });\n      this.stopHeartbeat();\n    });\n    // ready fires on the first connect and every reconnect; re-subscribing is\n    // safe because node-redis dedupes the stable listener.\n    this.subscriberClient.on('ready', () => {\n      void this.setupSubscriber();\n    });\n\n    // On stable connections we won't get another ready event — if the caller\n    // already connected the client, subscribe now.\n    if (this.subscriberClient.isReady) {\n      await this.setupSubscriber();\n    }\n  }\n\n  private async setupSubscriber(): Promise<void> {\n    if (this.closed) {\n      return;\n    }\n    try {\n      await this.subscriberClient.subscribe(this.channel, this.subscribeListener);\n      this.logger.info('[RequestReplyExecutor] Subscribed to request channel', { executorId: this.executorId });\n      this.stopHeartbeat();\n      this.startHeartbeat();\n    } catch (err) {\n      const error = err instanceof Error ? err : new Error(String(err), { cause: err });\n      this.logger.error('[RequestReplyExecutor] Error subscribing to request channel', {\n        executorId: this.executorId,\n        ...extractErrorLogFields(error),\n      });\n      this.onError?.(error, { executorId: this.executorId, channel: this.channel });\n      this.stopHeartbeat();\n    }\n  }\n\n  private async beat(): Promise<void> {\n    this.logger.debug('[RequestReplyExecutor] Beating heartbeat', { executorId: this.executorId });\n    try {\n      await this.redis.set(this.heartbeatKey, '1', { PX: this.heartbeatTtlMs });\n    } catch (err) {\n      this.logger.error('[RequestReplyExecutor] Heartbeat error', {\n        executorId: this.executorId,\n        ...extractErrorLogFields(err),\n      });\n    }\n  }\n\n  /** Heartbeat only while subscribed. Idempotent (restarts the timer). */\n  private startHeartbeat(): void {\n    if (this.closed) {\n      return;\n    }\n    this.logger.info('[RequestReplyExecutor] Starting heartbeat', { executorId: this.executorId });\n    this.stopHeartbeat();\n    void this.beat();\n    this.heartbeatTimer = setInterval(() => {\n      void this.beat();\n    }, this.heartbeatIntervalMs);\n  }\n\n  /** A stopped heartbeat makes callers fail fast with NoResponderError. */\n  private stopHeartbeat(): void {\n    if (this.heartbeatTimer) {\n      this.logger.info('[RequestReplyExecutor] Stopping heartbeat', { executorId: this.executorId });\n      clearInterval(this.heartbeatTimer);\n      this.heartbeatTimer = null;\n    }\n  }\n\n  private async processRequestFromMessage(message: string): Promise<void> {\n    let raw: unknown;\n    try {\n      raw = JSON.parse(message);\n    } catch (err) {\n      // Drop the request, this should never happen\n      this.logger.warn('[RequestReplyExecutor] Request message is not valid JSON', { executorId: this.executorId });\n      this.onError?.(\n        new Error(`Request message is not valid JSON for executorId: ${this.executorId}`, {\n          cause: err,\n        }),\n        {\n          executorId: this.executorId,\n          channel: this.channel,\n        },\n      );\n      return;\n    }\n\n    const parsedRequest = publishedRequestSchema.safeParse(raw);\n    if (!parsedRequest.success) {\n      // Drop the request, this should never happen\n      const zodError = z.treeifyError(parsedRequest.error);\n      this.logger.warn('[RequestReplyExecutor] Invalid request message shape', {\n        executorId: this.executorId,\n        zod: zodError,\n      });\n      this.onError?.(\n        new Error(\n          `Invalid request message shape for executorId: ${this.executorId}, error: ${JSON.stringify(zodError)}`,\n          { cause: parsedRequest.error },\n        ),\n        { executorId: this.executorId, channel: this.channel },\n      );\n      return;\n    }\n\n    const { replyKey, path, body, headers } = parsedRequest.data;\n    let replyPayload: JSONReply;\n    try {\n      replyPayload = await this.requestHandler(path, { body, headers });\n    } catch (err) {\n      // ReplyError lets handlers choose the reply status; any other throw is an unexpected 500.\n      if (err instanceof ReplyError) {\n        replyPayload = { status: err.status, headers: {}, body: { message: err.message } };\n      } else {\n        const message = err instanceof Error ? err.message : String(err);\n        replyPayload = { status: 500, headers: {}, body: { message } };\n      }\n    }\n\n    try {\n      await this.redis.set(replyKey, JSON.stringify(replyPayload), { PX: this.replyTtlMs });\n    } catch (err) {\n      this.logger.error('[RequestReplyExecutor] Request processing failed', {\n        executorId: this.executorId,\n        replyKey,\n        ...extractErrorLogFields(err),\n      });\n    }\n  }\n\n  /** One raw pub/sub payload. Never throws. */\n  private onMessage(message: string): void {\n    this.logger.debug('[RequestReplyExecutor] Received message', { executorId: this.executorId, message });\n    if (!message) {\n      return;\n    }\n    if (this.closed) {\n      this.logger.warn('[RequestReplyExecutor] Received message after executor is closed', {\n        executorId: this.executorId,\n        message,\n      });\n      return;\n    }\n    const pid = randomUUID();\n    const requestPromise = this.processRequestFromMessage(message).finally(() => {\n      this.runningRequests.delete(pid);\n    });\n    this.runningRequests.set(pid, requestPromise);\n  }\n\n  // This function should never throw!\n  // Stops intake: unsubscribe from the channel and stop the heartbeat. Never\n  // closes the clients — the caller owns their lifecycle.\n  async close(): Promise<void> {\n    if (this.closed) {\n      return;\n    }\n    this.logger.info('[RequestReplyExecutor] Closing', { executorId: this.executorId });\n    this.closed = true;\n    try {\n      await this.subscriberClient.unsubscribe(this.channel);\n    } catch {\n      // ignore: connection may already be closed\n    }\n    this.stopHeartbeat();\n  }\n\n  // This function should never throw!\n  // This is called during graceful shutdown\n  async drain(): Promise<void> {\n    await this.close();\n    await Promise.allSettled(Array.from(this.runningRequests.values()));\n  }\n}\n"],"mappings":"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","names":["z","message"]}

package/dist/request-reply/executor.mjs

@@ -0,0 +1,232 @@
+// src/request-reply/executor.ts
+import { randomUUID } from "crypto";
+import z from "zod";
+import { extractErrorLogFields } from "../core/util/errorLogFields.mjs";
+import { ReplyError } from "./errors.mjs";
+import { publishedRequestSchema } from "./types.mjs";
+import { heartbeatKey, requestChannel } from "./utils.mjs";
+var DEFAULT_HEARTBEAT_INTERVAL_MS = 5e3;
+var DEFAULT_REPLY_TTL_MS = 12e4;
+function resolveRunExecutorOptions(options) {
+  return {
+    heartbeatIntervalMs: options?.heartbeatIntervalMs ?? DEFAULT_HEARTBEAT_INTERVAL_MS,
+    replyTtlMs: options?.replyTtlMs ?? DEFAULT_REPLY_TTL_MS
+  };
+}
+var RequestReplyExecutor = class {
+  executorId;
+  /** `rr:req:<executorId>` — the channel this executor subscribes to. */
+  channel;
+  redis;
+  subscriberClient;
+  logger;
+  heartbeatIntervalMs;
+  heartbeatTtlMs;
+  replyTtlMs;
+  heartbeatKey;
+  requestHandler;
+  onError;
+  /** Stable reference so node-redis dedupes the listener across re-subscribes. */
+  subscribeListener = (message) => {
+    this.onMessage(message);
+  };
+  closed = false;
+  initialized = false;
+  runningRequests = /* @__PURE__ */ new Map();
+  heartbeatTimer = null;
+  constructor({
+    executorId,
+    redis,
+    subscriberClient,
+    requestHandler,
+    onError,
+    logger,
+    options
+  }) {
+    const { heartbeatIntervalMs, replyTtlMs } = resolveRunExecutorOptions(options);
+    this.executorId = executorId;
+    this.redis = redis;
+    this.subscriberClient = subscriberClient;
+    this.logger = logger;
+    this.replyTtlMs = replyTtlMs;
+    this.requestHandler = requestHandler;
+    this.onError = onError;
+    this.channel = requestChannel(executorId);
+    this.heartbeatKey = heartbeatKey(executorId);
+    this.heartbeatIntervalMs = heartbeatIntervalMs;
+    this.heartbeatTtlMs = Math.ceil(this.heartbeatIntervalMs * 1.5);
+  }
+  async init() {
+    if (this.closed || this.initialized) {
+      return;
+    }
+    this.initialized = true;
+    this.subscriberClient.on("error", (err) => {
+      this.logger.error("[RequestReplyExecutor] Subscriber error", {
+        executorId: this.executorId,
+        ...extractErrorLogFields(err)
+      });
+      this.onError?.(err, { executorId: this.executorId, channel: this.channel });
+      this.stopHeartbeat();
+    });
+    this.subscriberClient.on("end", () => {
+      this.logger.warn("[RequestReplyExecutor] Subscriber connection ended", { executorId: this.executorId });
+      this.stopHeartbeat();
+    });
+    this.subscriberClient.on("ready", () => {
+      void this.setupSubscriber();
+    });
+    if (this.subscriberClient.isReady) {
+      await this.setupSubscriber();
+    }
+  }
+  async setupSubscriber() {
+    if (this.closed) {
+      return;
+    }
+    try {
+      await this.subscriberClient.subscribe(this.channel, this.subscribeListener);
+      this.logger.info("[RequestReplyExecutor] Subscribed to request channel", { executorId: this.executorId });
+      this.stopHeartbeat();
+      this.startHeartbeat();
+    } catch (err) {
+      const error = err instanceof Error ? err : new Error(String(err), { cause: err });
+      this.logger.error("[RequestReplyExecutor] Error subscribing to request channel", {
+        executorId: this.executorId,
+        ...extractErrorLogFields(error)
+      });
+      this.onError?.(error, { executorId: this.executorId, channel: this.channel });
+      this.stopHeartbeat();
+    }
+  }
+  async beat() {
+    this.logger.debug("[RequestReplyExecutor] Beating heartbeat", { executorId: this.executorId });
+    try {
+      await this.redis.set(this.heartbeatKey, "1", { PX: this.heartbeatTtlMs });
+    } catch (err) {
+      this.logger.error("[RequestReplyExecutor] Heartbeat error", {
+        executorId: this.executorId,
+        ...extractErrorLogFields(err)
+      });
+    }
+  }
+  /** Heartbeat only while subscribed. Idempotent (restarts the timer). */
+  startHeartbeat() {
+    if (this.closed) {
+      return;
+    }
+    this.logger.info("[RequestReplyExecutor] Starting heartbeat", { executorId: this.executorId });
+    this.stopHeartbeat();
+    void this.beat();
+    this.heartbeatTimer = setInterval(() => {
+      void this.beat();
+    }, this.heartbeatIntervalMs);
+  }
+  /** A stopped heartbeat makes callers fail fast with NoResponderError. */
+  stopHeartbeat() {
+    if (this.heartbeatTimer) {
+      this.logger.info("[RequestReplyExecutor] Stopping heartbeat", { executorId: this.executorId });
+      clearInterval(this.heartbeatTimer);
+      this.heartbeatTimer = null;
+    }
+  }
+  async processRequestFromMessage(message) {
+    let raw;
+    try {
+      raw = JSON.parse(message);
+    } catch (err) {
+      this.logger.warn("[RequestReplyExecutor] Request message is not valid JSON", { executorId: this.executorId });
+      this.onError?.(
+        new Error(`Request message is not valid JSON for executorId: ${this.executorId}`, {
+          cause: err
+        }),
+        {
+          executorId: this.executorId,
+          channel: this.channel
+        }
+      );
+      return;
+    }
+    const parsedRequest = publishedRequestSchema.safeParse(raw);
+    if (!parsedRequest.success) {
+      const zodError = z.treeifyError(parsedRequest.error);
+      this.logger.warn("[RequestReplyExecutor] Invalid request message shape", {
+        executorId: this.executorId,
+        zod: zodError
+      });
+      this.onError?.(
+        new Error(
+          `Invalid request message shape for executorId: ${this.executorId}, error: ${JSON.stringify(zodError)}`,
+          { cause: parsedRequest.error }
+        ),
+        { executorId: this.executorId, channel: this.channel }
+      );
+      return;
+    }
+    const { replyKey, path, body, headers } = parsedRequest.data;
+    let replyPayload;
+    try {
+      replyPayload = await this.requestHandler(path, { body, headers });
+    } catch (err) {
+      if (err instanceof ReplyError) {
+        replyPayload = { status: err.status, headers: {}, body: { message: err.message } };
+      } else {
+        const message2 = err instanceof Error ? err.message : String(err);
+        replyPayload = { status: 500, headers: {}, body: { message: message2 } };
+      }
+    }
+    try {
+      await this.redis.set(replyKey, JSON.stringify(replyPayload), { PX: this.replyTtlMs });
+    } catch (err) {
+      this.logger.error("[RequestReplyExecutor] Request processing failed", {
+        executorId: this.executorId,
+        replyKey,
+        ...extractErrorLogFields(err)
+      });
+    }
+  }
+  /** One raw pub/sub payload. Never throws. */
+  onMessage(message) {
+    this.logger.debug("[RequestReplyExecutor] Received message", { executorId: this.executorId, message });
+    if (!message) {
+      return;
+    }
+    if (this.closed) {
+      this.logger.warn("[RequestReplyExecutor] Received message after executor is closed", {
+        executorId: this.executorId,
+        message
+      });
+      return;
+    }
+    const pid = randomUUID();
+    const requestPromise = this.processRequestFromMessage(message).finally(() => {
+      this.runningRequests.delete(pid);
+    });
+    this.runningRequests.set(pid, requestPromise);
+  }
+  // This function should never throw!
+  // Stops intake: unsubscribe from the channel and stop the heartbeat. Never
+  // closes the clients — the caller owns their lifecycle.
+  async close() {
+    if (this.closed) {
+      return;
+    }
+    this.logger.info("[RequestReplyExecutor] Closing", { executorId: this.executorId });
+    this.closed = true;
+    try {
+      await this.subscriberClient.unsubscribe(this.channel);
+    } catch {
+    }
+    this.stopHeartbeat();
+  }
+  // This function should never throw!
+  // This is called during graceful shutdown
+  async drain() {
+    await this.close();
+    await Promise.allSettled(Array.from(this.runningRequests.values()));
+  }
+};
+export {
+  RequestReplyExecutor
+};
+//# sourceMappingURL=executor.mjs.map

package/dist/request-reply/executor.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/request-reply/executor.ts"],"sourcesContent":["import { randomUUID } from 'node:crypto';\nimport type { RedisClientType } from 'redis';\nimport type { Logger } from 'winston';\nimport z from 'zod';\nimport { extractErrorLogFields } from '../core/util/errorLogFields';\nimport { ReplyError } from './errors';\nimport type { JSONReply, RequestHandler } from './types';\nimport { publishedRequestSchema } from './types';\nimport { heartbeatKey, requestChannel } from './utils';\n\nexport interface RunExecutorOptions {\n  /** How often to refresh the heartbeat key (ms). */\n  heartbeatIntervalMs: number;\n  /** TTL for the reply value so abandoned keys are reclaimed (ms). */\n  replyTtlMs: number;\n}\n\nconst DEFAULT_HEARTBEAT_INTERVAL_MS = 5_000;\nconst DEFAULT_REPLY_TTL_MS = 120_000;\n\nfunction resolveRunExecutorOptions(options: Partial<RunExecutorOptions> | undefined): RunExecutorOptions {\n  return {\n    heartbeatIntervalMs: options?.heartbeatIntervalMs ?? DEFAULT_HEARTBEAT_INTERVAL_MS,\n    replyTtlMs: options?.replyTtlMs ?? DEFAULT_REPLY_TTL_MS,\n  };\n}\n\n/** Observability hook for subscriber errors, failed SUBSCRIBEs, and malformed messages. */\nexport type RequestReplyErrorHandler = (err: Error, context: { executorId: string; channel: string }) => void;\n\n/**\n * Serving side of the request-reply transport: parses and validates each\n * published message, dispatches it to the request handler, writes the\n * JSONReply to the request's reply key, and refreshes the heartbeat key while\n * subscribed.\n *\n * Connection lifecycle stays with the caller: both clients are supplied\n * connected and are never closed here. `subscriberClient` is the connection to\n * SUBSCRIBE on — a `duplicate()` for standalone Redis, or the shared client\n * for Sentinel — and must have a reconnect strategy so a failed connect\n * self-heals (the executor re-subscribes on every `ready`).\n */\nexport class RequestReplyExecutor {\n  readonly executorId: string;\n  /** `rr:req:<executorId>` — the channel this executor subscribes to. */\n  readonly channel: string;\n  private readonly redis: RedisClientType;\n  private readonly subscriberClient: RedisClientType;\n  private readonly logger: Logger;\n  private readonly heartbeatIntervalMs: number;\n  private readonly heartbeatTtlMs: number;\n  private readonly replyTtlMs: number;\n  private readonly heartbeatKey: string;\n  private readonly requestHandler: RequestHandler;\n  private readonly onError: RequestReplyErrorHandler | undefined;\n  /** Stable reference so node-redis dedupes the listener across re-subscribes. */\n  private readonly subscribeListener = (message: string): void => {\n    this.onMessage(message);\n  };\n\n  private closed = false;\n  private initialized = false;\n  private runningRequests = new Map<string, Promise<void>>();\n  private heartbeatTimer: ReturnType<typeof setInterval> | null = null;\n\n  constructor({\n    executorId,\n    redis,\n    subscriberClient,\n    requestHandler,\n    onError,\n    logger,\n    options,\n  }: {\n    executorId: string;\n    /** Connected command client, used only for SET (reply + heartbeat). Caller owns its lifecycle. */\n    redis: RedisClientType;\n    /** Connected client to SUBSCRIBE on (duplicate or Sentinel). Caller owns its lifecycle. */\n    subscriberClient: RedisClientType;\n    requestHandler: RequestHandler;\n    onError?: RequestReplyErrorHandler | undefined;\n    logger: Logger;\n    options?: Partial<RunExecutorOptions> | undefined;\n  }) {\n    const { heartbeatIntervalMs, replyTtlMs } = resolveRunExecutorOptions(options);\n    this.executorId = executorId;\n    this.redis = redis;\n    this.subscriberClient = subscriberClient;\n    this.logger = logger;\n    this.replyTtlMs = replyTtlMs;\n    this.requestHandler = requestHandler;\n    this.onError = onError;\n    this.channel = requestChannel(executorId);\n    this.heartbeatKey = heartbeatKey(executorId);\n    this.heartbeatIntervalMs = heartbeatIntervalMs;\n    this.heartbeatTtlMs = Math.ceil(this.heartbeatIntervalMs * 1.5);\n  }\n\n  async init(): Promise<void> {\n    if (this.closed || this.initialized) {\n      return;\n    }\n    this.initialized = true;\n\n    this.subscriberClient.on('error', (err: Error) => {\n      this.logger.error('[RequestReplyExecutor] Subscriber error', {\n        executorId: this.executorId,\n        ...extractErrorLogFields(err),\n      });\n      this.onError?.(err, { executorId: this.executorId, channel: this.channel });\n      this.stopHeartbeat();\n    });\n    this.subscriberClient.on('end', () => {\n      this.logger.warn('[RequestReplyExecutor] Subscriber connection ended', { executorId: this.executorId });\n      this.stopHeartbeat();\n    });\n    // ready fires on the first connect and every reconnect; re-subscribing is\n    // safe because node-redis dedupes the stable listener.\n    this.subscriberClient.on('ready', () => {\n      void this.setupSubscriber();\n    });\n\n    // On stable connections we won't get another ready event — if the caller\n    // already connected the client, subscribe now.\n    if (this.subscriberClient.isReady) {\n      await this.setupSubscriber();\n    }\n  }\n\n  private async setupSubscriber(): Promise<void> {\n    if (this.closed) {\n      return;\n    }\n    try {\n      await this.subscriberClient.subscribe(this.channel, this.subscribeListener);\n      this.logger.info('[RequestReplyExecutor] Subscribed to request channel', { executorId: this.executorId });\n      this.stopHeartbeat();\n      this.startHeartbeat();\n    } catch (err) {\n      const error = err instanceof Error ? err : new Error(String(err), { cause: err });\n      this.logger.error('[RequestReplyExecutor] Error subscribing to request channel', {\n        executorId: this.executorId,\n        ...extractErrorLogFields(error),\n      });\n      this.onError?.(error, { executorId: this.executorId, channel: this.channel });\n      this.stopHeartbeat();\n    }\n  }\n\n  private async beat(): Promise<void> {\n    this.logger.debug('[RequestReplyExecutor] Beating heartbeat', { executorId: this.executorId });\n    try {\n      await this.redis.set(this.heartbeatKey, '1', { PX: this.heartbeatTtlMs });\n    } catch (err) {\n      this.logger.error('[RequestReplyExecutor] Heartbeat error', {\n        executorId: this.executorId,\n        ...extractErrorLogFields(err),\n      });\n    }\n  }\n\n  /** Heartbeat only while subscribed. Idempotent (restarts the timer). */\n  private startHeartbeat(): void {\n    if (this.closed) {\n      return;\n    }\n    this.logger.info('[RequestReplyExecutor] Starting heartbeat', { executorId: this.executorId });\n    this.stopHeartbeat();\n    void this.beat();\n    this.heartbeatTimer = setInterval(() => {\n      void this.beat();\n    }, this.heartbeatIntervalMs);\n  }\n\n  /** A stopped heartbeat makes callers fail fast with NoResponderError. */\n  private stopHeartbeat(): void {\n    if (this.heartbeatTimer) {\n      this.logger.info('[RequestReplyExecutor] Stopping heartbeat', { executorId: this.executorId });\n      clearInterval(this.heartbeatTimer);\n      this.heartbeatTimer = null;\n    }\n  }\n\n  private async processRequestFromMessage(message: string): Promise<void> {\n    let raw: unknown;\n    try {\n      raw = JSON.parse(message);\n    } catch (err) {\n      // Drop the request, this should never happen\n      this.logger.warn('[RequestReplyExecutor] Request message is not valid JSON', { executorId: this.executorId });\n      this.onError?.(\n        new Error(`Request message is not valid JSON for executorId: ${this.executorId}`, {\n          cause: err,\n        }),\n        {\n          executorId: this.executorId,\n          channel: this.channel,\n        },\n      );\n      return;\n    }\n\n    const parsedRequest = publishedRequestSchema.safeParse(raw);\n    if (!parsedRequest.success) {\n      // Drop the request, this should never happen\n      const zodError = z.treeifyError(parsedRequest.error);\n      this.logger.warn('[RequestReplyExecutor] Invalid request message shape', {\n        executorId: this.executorId,\n        zod: zodError,\n      });\n      this.onError?.(\n        new Error(\n          `Invalid request message shape for executorId: ${this.executorId}, error: ${JSON.stringify(zodError)}`,\n          { cause: parsedRequest.error },\n        ),\n        { executorId: this.executorId, channel: this.channel },\n      );\n      return;\n    }\n\n    const { replyKey, path, body, headers } = parsedRequest.data;\n    let replyPayload: JSONReply;\n    try {\n      replyPayload = await this.requestHandler(path, { body, headers });\n    } catch (err) {\n      // ReplyError lets handlers choose the reply status; any other throw is an unexpected 500.\n      if (err instanceof ReplyError) {\n        replyPayload = { status: err.status, headers: {}, body: { message: err.message } };\n      } else {\n        const message = err instanceof Error ? err.message : String(err);\n        replyPayload = { status: 500, headers: {}, body: { message } };\n      }\n    }\n\n    try {\n      await this.redis.set(replyKey, JSON.stringify(replyPayload), { PX: this.replyTtlMs });\n    } catch (err) {\n      this.logger.error('[RequestReplyExecutor] Request processing failed', {\n        executorId: this.executorId,\n        replyKey,\n        ...extractErrorLogFields(err),\n      });\n    }\n  }\n\n  /** One raw pub/sub payload. Never throws. */\n  private onMessage(message: string): void {\n    this.logger.debug('[RequestReplyExecutor] Received message', { executorId: this.executorId, message });\n    if (!message) {\n      return;\n    }\n    if (this.closed) {\n      this.logger.warn('[RequestReplyExecutor] Received message after executor is closed', {\n        executorId: this.executorId,\n        message,\n      });\n      return;\n    }\n    const pid = randomUUID();\n    const requestPromise = this.processRequestFromMessage(message).finally(() => {\n      this.runningRequests.delete(pid);\n    });\n    this.runningRequests.set(pid, requestPromise);\n  }\n\n  // This function should never throw!\n  // Stops intake: unsubscribe from the channel and stop the heartbeat. Never\n  // closes the clients — the caller owns their lifecycle.\n  async close(): Promise<void> {\n    if (this.closed) {\n      return;\n    }\n    this.logger.info('[RequestReplyExecutor] Closing', { executorId: this.executorId });\n    this.closed = true;\n    try {\n      await this.subscriberClient.unsubscribe(this.channel);\n    } catch {\n      // ignore: connection may already be closed\n    }\n    this.stopHeartbeat();\n  }\n\n  // This function should never throw!\n  // This is called during graceful shutdown\n  async drain(): Promise<void> {\n    await this.close();\n    await Promise.allSettled(Array.from(this.runningRequests.values()));\n  }\n}\n"],"mappings":"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","names":["message"]}

package/dist/request-reply/index.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Redis request-reply transport for executor peering: route a command to the
+ * replica addressed by a plain `executorId`. Hosts own the Redis connection
+ * (inject the node-redis client) and their own id grammar — how an executor
+ * id is embedded in / parsed out of resource ids never enters this module.
+ */
+export { redisRequest } from './client';
+export type { SendRequestOptions } from './client';
+export { NoResponderError, ReplyError, RequestTimeoutError } from './errors';
+export { RequestReplyExecutor } from './executor';
+export type { RequestReplyErrorHandler, RunExecutorOptions } from './executor';
+export { RequestReplyRouter } from './router';
+export type { RouteHandler } from './router';
+export { jsonReplySchema } from './types';
+export type { JSONReply, JSONValue, RequestEnvelope, RequestHandler } from './types';
+//# sourceMappingURL=index.d.ts.map

package/dist/request-reply/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/request-reply/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AACxC,YAAY,EAAE,kBAAkB,EAAE,MAAM,UAAU,CAAC;AACnD,OAAO,EAAE,gBAAgB,EAAE,UAAU,EAAE,mBAAmB,EAAE,MAAM,UAAU,CAAC;AAC7E,OAAO,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC;AAClD,YAAY,EAAE,wBAAwB,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAC/E,OAAO,EAAE,kBAAkB,EAAE,MAAM,UAAU,CAAC;AAC9C,YAAY,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AAC7C,OAAO,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAC1C,YAAY,EAAE,SAAS,EAAE,SAAS,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC"}