@frontmcp/utils 1.10.16 → 1.11.0-rc.2

package/browser/storage/adapters/redis.mjs

@@ -0,0 +1,497 @@
+var __frontmcpModule = typeof process !== "undefined" && typeof process.getBuiltinModule === "function" ? process.getBuiltinModule("module") : undefined;
+const require = __frontmcpModule ? __frontmcpModule.createRequire(import.meta.url || 'file:///') : undefined;
+// __frontmcpCreateRequire
+var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require : typeof Proxy !== "undefined" ? new Proxy(x, {
+  get: (a, b) => (typeof require !== "undefined" ? require : a)[b]
+}) : x)(function(x) {
+  if (typeof require !== "undefined") return require.apply(this, arguments);
+  throw Error('Dynamic require of "' + x + '" is not supported');
+});
+
+// libs/utils/src/storage/adapters/redis.ts
+import { StorageConfigError, StorageConnectionError } from "../errors.mjs";
+import { attachRedisErrorListener } from "../redis-error-listener.mjs";
+import {
+  describeRedisUrlConflicts,
+  mergeRedisUrlFields
+} from "../redis-url.mjs";
+import { validateTTL } from "../utils/index.mjs";
+import {
+  COMPARE_AND_DELETE_SCRIPT,
+  COMPARE_AND_EXPIRE_SCRIPT,
+  COMPARE_AND_SET_SCRIPT
+} from "../utils/compare-and-delete.mjs";
+import { BaseStorageAdapter } from "./base.mjs";
+function getRedisClass() {
+  try {
+    return __require("ioredis").default || __require("ioredis");
+  } catch (error) {
+    const msg = error instanceof Error ? error.message : String(error);
+    if (msg.includes("Dynamic require") || msg.includes("require is not defined")) {
+      throw new Error(
+        `Failed to load ioredis: ${msg}. This typically happens with ESM bundlers (esbuild, Vite). Ensure your bundler externalizes ioredis or use CJS mode.`,
+        { cause: error }
+      );
+    }
+    throw new Error("ioredis is required for Redis storage adapter. Install it with: npm install ioredis", {
+      cause: error
+    });
+  }
+}
+var RedisStorageAdapter = class extends BaseStorageAdapter {
+  backendName = "redis";
+  client;
+  subscriber;
+  options;
+  ownsClient;
+  detachErrorListener;
+  connecting;
+  keyPrefix;
+  subscriptionHandlers = /* @__PURE__ */ new Map();
+  reconnectListeners = /* @__PURE__ */ new Set();
+  connectionUrl;
+  /** The connection options of a URL this adapter reads itself; undefined for one only ioredis reads. */
+  urlOptions;
+  constructor(options = {}) {
+    super();
+    const hasClient = options.client !== void 0;
+    const hasConfig = options.config !== void 0 || options.url !== void 0;
+    if (hasClient && hasConfig) {
+      throw new StorageConfigError("redis", 'Cannot specify both "client" and "config"/"url". Use one or the other.');
+    }
+    if (!hasClient && !hasConfig) {
+      const envUrl = process.env["REDIS_URL"] || process.env["REDIS_HOST"];
+      if (envUrl) {
+        options = { ...options, url: envUrl };
+      } else {
+        throw new StorageConfigError(
+          "redis",
+          'Either "client", "config", "url", or REDIS_URL environment variable must be provided.'
+        );
+      }
+    }
+    this.options = options;
+    this.ownsClient = !hasClient;
+    this.keyPrefix = options.keyPrefix ?? "";
+    const configUrl = options.config?.url;
+    this.connectionUrl = options.url ?? (typeof configUrl === "string" ? configUrl : void 0);
+    this.urlOptions = this.connectionUrl ? resolveUrlOptions(this.connectionUrl, options) : void 0;
+  }
+  // ============================================
+  // Connection Lifecycle
+  // ============================================
+  async connect() {
+    if (this.connected) return;
+    this.connecting ??= this.openConnection().finally(() => {
+      this.connecting = void 0;
+    });
+    return this.connecting;
+  }
+  async openConnection() {
+    let socketError;
+    const recordSocketError = (error) => {
+      socketError = error;
+    };
+    let client;
+    try {
+      if (this.options.client) {
+        client = this.options.client;
+      } else {
+        client = this.newClient();
+        client.on("error", recordSocketError);
+      }
+      await client.ping();
+      this.client = client;
+      this.connected = true;
+      if (this.ownsClient) {
+        client.removeListener("error", recordSocketError);
+        this.detachErrorListener = attachRedisErrorListener(client, { label: "RedisStorage" });
+      }
+    } catch (e) {
+      if (this.ownsClient && client) {
+        try {
+          client.disconnect();
+        } catch {
+        }
+      }
+      const cause = socketError ?? (e instanceof Error ? e : void 0);
+      throw new StorageConnectionError("Failed to connect to Redis", cause, "redis");
+    }
+  }
+  async disconnect() {
+    if (!this.connected) return;
+    if (this.subscriber) {
+      await this.subscriber.quit();
+      this.subscriber = void 0;
+    }
+    if (this.ownsClient && this.client) {
+      await this.client.quit();
+    }
+    this.detachErrorListener?.();
+    this.detachErrorListener = void 0;
+    this.client = void 0;
+    this.connected = false;
+    this.subscriptionHandlers.clear();
+  }
+  async ping() {
+    if (!this.client) return false;
+    try {
+      const result = await this.client.ping();
+      return result === "PONG";
+    } catch {
+      return false;
+    }
+  }
+  // ============================================
+  // Connection Helpers
+  // ============================================
+  /**
+   * Get the connected Redis client, throwing if not connected.
+   */
+  getConnectedClient() {
+    this.ensureConnected();
+    if (!this.client) {
+      throw new StorageConnectionError("Redis client not connected", void 0, "redis");
+    }
+    return this.client;
+  }
+  /**
+   * Get the connected Redis subscriber, throwing if not created.
+   */
+  getConnectedSubscriber() {
+    if (!this.subscriber) {
+      throw new StorageConnectionError("Redis subscriber not created", void 0, "redis");
+    }
+    return this.subscriber;
+  }
+  // ============================================
+  // Core Operations
+  // ============================================
+  async get(key) {
+    return this.getConnectedClient().get(this.prefixKey(key));
+  }
+  async doSet(key, value, options) {
+    const client = this.getConnectedClient();
+    const prefixedKey = this.prefixKey(key);
+    if (options?.ttlSeconds) {
+      if (options.ifNotExists) {
+        await client.set(prefixedKey, value, "EX", options.ttlSeconds, "NX");
+      } else if (options.ifExists) {
+        await client.set(prefixedKey, value, "EX", options.ttlSeconds, "XX");
+      } else {
+        await client.set(prefixedKey, value, "EX", options.ttlSeconds);
+      }
+    } else if (options?.ifNotExists) {
+      await client.set(prefixedKey, value, "NX");
+    } else if (options?.ifExists) {
+      await client.set(prefixedKey, value, "XX");
+    } else {
+      await client.set(prefixedKey, value);
+    }
+  }
+  async delete(key) {
+    const result = await this.getConnectedClient().del(this.prefixKey(key));
+    return result > 0;
+  }
+  async deleteIfEquals(key, expectedValue) {
+    const deleted = await this.getConnectedClient().eval(
+      COMPARE_AND_DELETE_SCRIPT,
+      1,
+      this.prefixKey(key),
+      expectedValue
+    );
+    return deleted === 1;
+  }
+  async expireIfEquals(key, expectedValue, ttlSeconds) {
+    validateTTL(ttlSeconds);
+    const extended = await this.getConnectedClient().eval(
+      COMPARE_AND_EXPIRE_SCRIPT,
+      1,
+      this.prefixKey(key),
+      expectedValue,
+      String(ttlSeconds)
+    );
+    return extended === 1;
+  }
+  async setIfEquals(key, expectedValue, value) {
+    const stored = await this.getConnectedClient().eval(
+      COMPARE_AND_SET_SCRIPT,
+      1,
+      this.prefixKey(key),
+      expectedValue,
+      value
+    );
+    return stored === 1;
+  }
+  async exists(key) {
+    const result = await this.getConnectedClient().exists(this.prefixKey(key));
+    return result > 0;
+  }
+  // ============================================
+  // Batch Operations (pipelined)
+  // ============================================
+  async mget(keys) {
+    if (keys.length === 0) return [];
+    const prefixedKeys = keys.map((k) => this.prefixKey(k));
+    return this.getConnectedClient().mget(...prefixedKeys);
+  }
+  async mset(entries) {
+    if (entries.length === 0) return;
+    for (const entry of entries) {
+      this.validateSetOptions(entry.options);
+    }
+    const pipeline = this.getConnectedClient().pipeline();
+    for (const entry of entries) {
+      const prefixedKey = this.prefixKey(entry.key);
+      if (entry.options?.ttlSeconds) {
+        if (entry.options.ifNotExists) {
+          pipeline.set(prefixedKey, entry.value, "EX", entry.options.ttlSeconds, "NX");
+        } else if (entry.options.ifExists) {
+          pipeline.set(prefixedKey, entry.value, "EX", entry.options.ttlSeconds, "XX");
+        } else {
+          pipeline.set(prefixedKey, entry.value, "EX", entry.options.ttlSeconds);
+        }
+      } else if (entry.options?.ifNotExists) {
+        pipeline.set(prefixedKey, entry.value, "NX");
+      } else if (entry.options?.ifExists) {
+        pipeline.set(prefixedKey, entry.value, "XX");
+      } else {
+        pipeline.set(prefixedKey, entry.value);
+      }
+    }
+    await pipeline.exec();
+  }
+  async mdelete(keys) {
+    if (keys.length === 0) return 0;
+    const prefixedKeys = keys.map((k) => this.prefixKey(k));
+    return this.getConnectedClient().del(...prefixedKeys);
+  }
+  // ============================================
+  // TTL Operations
+  // ============================================
+  async expire(key, ttlSeconds) {
+    validateTTL(ttlSeconds);
+    const result = await this.getConnectedClient().expire(this.prefixKey(key), ttlSeconds);
+    return result === 1;
+  }
+  async ttl(key) {
+    const result = await this.getConnectedClient().ttl(this.prefixKey(key));
+    if (result === -2) return null;
+    return result;
+  }
+  // ============================================
+  // Key Enumeration (SCAN)
+  // ============================================
+  async keys(pattern = "*") {
+    const client = this.getConnectedClient();
+    const prefixedPattern = this.prefixKey(pattern);
+    const result = [];
+    let cursor = "0";
+    do {
+      const [nextCursor, keys] = await client.scan(cursor, "MATCH", prefixedPattern, "COUNT", 100);
+      cursor = nextCursor;
+      for (const key of keys) {
+        result.push(this.unprefixKey(key));
+      }
+    } while (cursor !== "0");
+    return result;
+  }
+  // ============================================
+  // Atomic Operations
+  // ============================================
+  async incr(key) {
+    return this.getConnectedClient().incr(this.prefixKey(key));
+  }
+  async decr(key) {
+    return this.getConnectedClient().decr(this.prefixKey(key));
+  }
+  async incrBy(key, amount) {
+    return this.getConnectedClient().incrby(this.prefixKey(key), amount);
+  }
+  // ============================================
+  // Pub/Sub
+  // ============================================
+  supportsPubSub() {
+    return true;
+  }
+  async publish(channel, message) {
+    const prefixedChannel = this.prefixKey(channel);
+    return this.getConnectedClient().publish(prefixedChannel, message);
+  }
+  async subscribe(channel, handler) {
+    this.ensureConnected();
+    const prefixedChannel = this.prefixKey(channel);
+    if (!this.subscriber) {
+      await this.createSubscriber();
+    }
+    const subscriber = this.getConnectedSubscriber();
+    if (!this.subscriptionHandlers.has(prefixedChannel)) {
+      this.subscriptionHandlers.set(prefixedChannel, /* @__PURE__ */ new Set());
+      await subscriber.subscribe(prefixedChannel);
+    }
+    const handlers = this.subscriptionHandlers.get(prefixedChannel);
+    if (handlers) {
+      handlers.add(handler);
+    }
+    return async () => {
+      const handlers2 = this.subscriptionHandlers.get(prefixedChannel);
+      if (handlers2) {
+        handlers2.delete(handler);
+        if (handlers2.size === 0) {
+          this.subscriptionHandlers.delete(prefixedChannel);
+          await this.subscriber?.unsubscribe(prefixedChannel);
+        }
+      }
+    };
+  }
+  onPubSubReconnect(listener) {
+    this.reconnectListeners.add(listener);
+    return () => {
+      this.reconnectListeners.delete(listener);
+    };
+  }
+  // ============================================
+  // Internal Helpers
+  // ============================================
+  /**
+   * Build Redis options from config.
+   */
+  buildRedisOptions() {
+    if (this.connectionUrl) {
+      return { lazyConnect: false, maxRetriesPerRequest: 3, ...this.urlOptions };
+    }
+    const config = this.options.config;
+    if (!config || typeof config.url === "string" || config.host === void 0) {
+      throw new StorageConfigError("redis", "Redis config is required when URL is not provided");
+    }
+    return {
+      host: config.host,
+      port: config.port ?? 6379,
+      password: config.password,
+      db: config.db ?? 0,
+      tls: config.tls ? {} : void 0,
+      lazyConnect: false,
+      maxRetriesPerRequest: 3
+    };
+  }
+  /**
+   * Create a client this adapter owns. A URL only ioredis reads goes to it as is.
+   */
+  newClient() {
+    const RedisClass = getRedisClass();
+    if (this.connectionUrl && !this.urlOptions) {
+      return new RedisClass(this.connectionUrl, this.buildRedisOptions());
+    }
+    return new RedisClass(this.buildRedisOptions());
+  }
+  /**
+   * Create subscriber connection.
+   */
+  async createSubscriber() {
+    let subscriber;
+    if (this.connectionUrl || this.options.config) {
+      subscriber = this.newClient();
+    } else if (this.options.client) {
+      subscriber = this.options.client.duplicate();
+    } else {
+      throw new StorageConfigError("redis", "Cannot create subscriber without url, config, or client");
+    }
+    attachRedisErrorListener(subscriber, { label: "RedisStorage:subscriber" });
+    subscriber.on("message", (channel, message) => {
+      const handlers = this.subscriptionHandlers.get(channel);
+      if (handlers) {
+        const unprefixedChannel = this.unprefixKey(channel);
+        for (const handler of handlers) {
+          try {
+            handler(message, unprefixedChannel);
+          } catch {
+          }
+        }
+      }
+    });
+    let readyBefore = false;
+    subscriber.on("ready", () => {
+      if (readyBefore) {
+        for (const listener of [...this.reconnectListeners]) {
+          try {
+            listener();
+          } catch {
+          }
+        }
+      }
+      readyBefore = true;
+    });
+    this.subscriber = subscriber;
+  }
+  /**
+   * Add prefix to a key.
+   */
+  prefixKey(key) {
+    return this.keyPrefix + key;
+  }
+  /**
+   * Remove prefix from a key.
+   */
+  unprefixKey(key) {
+    if (this.keyPrefix && key.startsWith(this.keyPrefix)) {
+      return key.slice(this.keyPrefix.length);
+    }
+    return key;
+  }
+  /**
+   * Get the underlying Redis client (for advanced use).
+   */
+  getClient() {
+    return this.client;
+  }
+};
+function resolveUrlOptions(connectionUrl, options) {
+  const { url: configUrl, ...siblingFields } = { url: void 0, ...options.config };
+  if (options.url && configUrl && configUrl !== options.url) {
+    throw new StorageConfigError("redis", "redis.url and redis.config.url name different servers; set one of them.");
+  }
+  return urlConnectionOptions(connectionUrl, siblingFields);
+}
+function urlConnectionOptions(url, fields) {
+  const merge = mergeRedisUrlFields(url, fields);
+  if (!merge) return void 0;
+  if (merge.conflicts.length > 0) {
+    throw new StorageConfigError("redis", describeRedisUrlConflicts(merge.conflicts));
+  }
+  const { queryOptions, tls, ...stated } = merge.connection;
+  return { ...queryOptions, ...stated, ...toFillInOptions(merge.fillIns), ...tls ? { tls: {} } : {} };
+}
+function toFillInOptions({ port, password, db, tls }) {
+  return {
+    ...port !== void 0 ? { port } : {},
+    ...password !== void 0 ? { password } : {},
+    ...db !== void 0 ? { db } : {},
+    ...tls ? { tls: {} } : {}
+  };
+}
+function createRedisClient(options) {
+  const urlOptions = options.url ? urlConnectionOptions(options.url, options) : void 0;
+  const RedisClass = getRedisClass();
+  const baseOptions = { lazyConnect: false, maxRetriesPerRequest: 3 };
+  let client;
+  if (urlOptions) {
+    client = new RedisClass({ ...baseOptions, ...urlOptions });
+  } else if (options.url) {
+    client = new RedisClass(options.url, baseOptions);
+  } else {
+    client = new RedisClass({
+      ...baseOptions,
+      host: options.host ?? "localhost",
+      port: options.port ?? 6379,
+      password: options.password,
+      db: options.db ?? 0,
+      tls: options.tls ? {} : void 0
+    });
+  }
+  attachRedisErrorListener(client, { label: options.label ?? "redis", logger: options.logger });
+  return client;
+}
+export {
+  RedisStorageAdapter,
+  createRedisClient
+};