@managani/cache 0.1.0

package/LICENSE

@@ -0,0 +1,9 @@
+MIT License
+
+Copyright (c) Managani
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,35 @@
+# @managani/cache
+
+Shared CommonJS Memcached cache and MongoDB coordination primitives for Managani applications.
+
+```js
+const { createCache } = require("@managani/cache");
+
+const cache = createCache({
+  servers: [
+    "cache-memcached-1:11211",
+    "cache-memcached-2:11211",
+    "cache-memcached-3:11211",
+  ],
+  namespace: "product:v3",
+  l1: { maxBytes: 16 * 1024 * 1024, maxTtlMs: 2000 },
+});
+
+await cache.set("key", { value: true }, { ttlMs: 300000 });
+const value = await cache.get("key");
+```
+
+Values use a versioned JSON envelope. Objects, arrays, dates, buffers, `null`,
+primitives, and bigints retain their types. Values above 64 KiB use fast
+compression when it saves at least 10%; values above 3.5 MiB on wire are skipped.
+
+The cache exposes `get`, `getMany`, `set`, `setMany`, `delete`,
+`invalidateScope`, `getOrLoad`, atomic `add`, `increment`, `decrement`,
+`consumeOnce`, advisory `acquireLease`, `health`, and `close`.
+
+Ordinary backend failures return misses or unsuccessful writes. `consumeOnce`
+probes the whole cluster and fails closed while any node is degraded.
+
+Use `createMongoCoordinator({ db })` for token-checked locks, bounded
+semaphores, and cooldowns whose loss could affect correctness. It uses primary
+reads, atomic writes, and a TTL index.

package/index.js

@@ -0,0 +1,571 @@
+const crypto = require("node:crypto");
+const { Memcache } = require("memcache");
+const L1Cache = require("./lib/l1_cache");
+const MongoCoordinator = require("./lib/mongo_coordinator");
+const MemcachedRateLimitStore = require("./lib/rate_limit_store");
+const { decodeEntry, encodeEntry } = require("./lib/serialization");
+
+const DEFAULT_TTL_MS = 5 * 60 * 1000;
+const DEFAULT_MAX_VALUE_BYTES = Math.floor(3.5 * 1024 * 1024);
+
+class CacheUnavailableError extends Error {
+  constructor(message = "Cache unavailable") {
+    super(message);
+    this.name = "CacheUnavailableError";
+    this.code = "CACHE_UNAVAILABLE";
+  }
+}
+
+class DistributedCache {
+  constructor(options = {}) {
+    this.namespace = String(options.namespace || "app");
+    this.logger = options.logger || null;
+    this.metrics = options.metrics || null;
+    this.timeoutMs = Math.max(10, Number(options.timeoutMs) || 100);
+    this.maxValueBytes = Math.max(
+      1024,
+      Number(options.maxValueBytes) || DEFAULT_MAX_VALUE_BYTES,
+    );
+    this.compressionThreshold = Math.max(
+      0,
+      Number(options.compressionThreshold) || 64 * 1024,
+    );
+    this.servers = [
+      ...new Set(
+        (options.servers || [])
+          .map(String)
+          .map((value) => value.trim())
+          .filter(Boolean),
+      ),
+    ];
+    this.l1 = new L1Cache(options.l1 || {});
+    this.inflight = new Map();
+    this.scopeGenerations = new Map();
+    this.scopeGenerationTtlMs = Math.max(
+      100,
+      Number(options.scopeGenerationTtlMs) || 2000,
+    );
+    this.errorLogTimes = new Map();
+    this.errorLogIntervalMs = Math.max(
+      1000,
+      Number(options.errorLogIntervalMs) || 60000,
+    );
+    this.client = options.client || this._createClient(this.servers);
+    this.probes = new Map();
+    this.nodeState = new Map();
+    this._reconcilePromise = Promise.resolve();
+    this._closed = false;
+    this._customClient = !!options.client;
+    if (!this._customClient) this._initializeHealth(options.healthIntervalMs);
+  }
+
+  async get(key, options = {}) {
+    const entry = await this._getEntry(key, options);
+    return entry ? entry.value : null;
+  }
+
+  async getMany(keys, options = {}) {
+    return Promise.all((keys || []).map((key) => this.get(key, options)));
+  }
+
+  async set(key, value, options = {}) {
+    const ttlMs = Math.max(1, Number(options.ttlMs) || DEFAULT_TTL_MS);
+    const staleTtlMs = Math.max(0, Number(options.staleTtlMs) || 0);
+    const generation = await this._scopeGeneration(options.scope);
+    const wireKey = this._wireKey("value", key, options.scope, generation);
+    const entry = { version: 1, value, freshUntil: Date.now() + ttlMs };
+    return this._storeEncoded(wireKey, entry, {
+      ttlMs: ttlMs + staleTtlMs,
+      scope: options.scope || "",
+    });
+  }
+
+  async setMany(entries, options = {}) {
+    return Promise.all(
+      (entries || []).map((entry) =>
+        this.set(entry.key, entry.value, {
+          ...options,
+          ...(entry.options || {}),
+          ttlMs: entry.ttlMs || entry.options?.ttlMs || options.ttlMs,
+        }),
+      ),
+    );
+  }
+
+  async add(key, value, options = {}) {
+    const ttlMs = Math.max(1, Number(options.ttlMs) || DEFAULT_TTL_MS);
+    const generation = await this._scopeGeneration(options.scope);
+    const wireKey = this._wireKey("value", key, options.scope, generation);
+    const entry = { version: 1, value, freshUntil: Date.now() + ttlMs };
+    const encoded = await encodeEntry(entry, {
+      compressionThreshold: this.compressionThreshold,
+    });
+    if (encoded.bytes > this.maxValueBytes) {
+      this._metric("cache_oversize", { bytes: encoded.bytes });
+      return false;
+    }
+    try {
+      const stored = await this.client.add(
+        wireKey,
+        encoded.encoded,
+        this._ttlSeconds(ttlMs),
+      );
+      if (stored)
+        this.l1.set(wireKey, entry, {
+          size: encoded.bytes,
+          ttlMs,
+          scope: options.scope || "",
+        });
+      this._metric("cache_add", { stored: !!stored });
+      return !!stored;
+    } catch (error) {
+      this._cacheError("add", error);
+      return false;
+    }
+  }
+
+  async increment(key, options = {}) {
+    const amount = Math.max(1, Number(options.amount) || 1);
+    const initial = Math.max(0, Number(options.initial) || 0);
+    const wireKey = this._wireKey("counter", key);
+    try {
+      let value = await this.client.incr(wireKey, amount);
+      if (Number.isFinite(value)) return Number(value);
+      if (
+        await this.client.add(
+          wireKey,
+          String(initial + amount),
+          this._ttlSeconds(options.ttlMs || DEFAULT_TTL_MS),
+        )
+      )
+        return initial + amount;
+      value = await this.client.incr(wireKey, amount);
+      return Number.isFinite(value) ? Number(value) : null;
+    } catch (error) {
+      this._cacheError("increment", error);
+      return null;
+    }
+  }
+
+  async decrement(key, options = {}) {
+    const wireKey = this._wireKey("counter", key);
+    try {
+      const value = await this.client.decr(
+        wireKey,
+        Math.max(1, Number(options.amount) || 1),
+      );
+      return Number.isFinite(value) ? Number(value) : null;
+    } catch (error) {
+      this._cacheError("decrement", error);
+      return null;
+    }
+  }
+
+  async getCounter(key) {
+    const wireKey = this._wireKey("counter", key);
+    try {
+      const value = await this.client.get(wireKey);
+      return value === undefined || value === null ? 0 : Number(value) || 0;
+    } catch (error) {
+      this._cacheError("get_counter", error);
+      return null;
+    }
+  }
+
+  async delete(key, options = {}) {
+    const generation = await this._scopeGeneration(options.scope, false);
+    const wireKey = this._wireKey(
+      options.kind || "value",
+      key,
+      options.scope,
+      generation,
+    );
+    this.l1.delete(wireKey);
+    try {
+      return !!(await this.client.delete(wireKey));
+    } catch (error) {
+      this._cacheError("delete", error);
+      return false;
+    }
+  }
+
+  async invalidateScope(scope) {
+    if (!scope) return false;
+    const generation = crypto.randomUUID();
+    const key = this._scopeKey(scope);
+    try {
+      const stored = await this.client.set(key, generation, 0);
+      if (!stored) return false;
+      this.scopeGenerations.set(scope, {
+        value: generation,
+        expiresAt: Date.now() + this.scopeGenerationTtlMs,
+      });
+      this.l1.invalidateScope(scope);
+      this._metric("cache_scope_invalidated", {});
+      return true;
+    } catch (error) {
+      this._cacheError("invalidate_scope", error);
+      return false;
+    }
+  }
+
+  async getOrLoad(key, loader, options = {}) {
+    if (typeof loader !== "function")
+      throw new TypeError("getOrLoad requires loader");
+    const entry = await this._getEntry(key, options);
+    const inflightKey = this._wireKey(
+      "inflight",
+      key,
+      options.scope,
+      await this._scopeGeneration(options.scope),
+    );
+    if (entry && entry.freshUntil > Date.now()) return entry.value;
+    if (entry && Number(options.staleTtlMs) > 0) {
+      this._loadOnce(inflightKey, key, loader, options).catch((error) =>
+        this._log("warn", "Cache background refresh failed", error),
+      );
+      return entry.value;
+    }
+    return this._loadOnce(inflightKey, key, loader, options);
+  }
+
+  async acquireLease(key, options = {}) {
+    const token = crypto.randomUUID();
+    const ttlMs = Math.max(1, Number(options.ttlMs) || 60000);
+    const acquired = await this.add(
+      `lease:${key}`,
+      { token },
+      { ttlMs, scope: options.scope },
+    );
+    return acquired
+      ? { key, token, expiresAt: new Date(Date.now() + ttlMs) }
+      : null;
+  }
+
+  async consumeOnce(key, options = {}) {
+    const status = await this.health();
+    if (!status.healthy || status.degraded)
+      throw new CacheUnavailableError(
+        "Cache degraded during one-time value consumption",
+      );
+    const value = await this.get(key, options);
+    if (value === null) return null;
+    const markerTtlMs = Math.max(1000, Number(options.ttlMs) || DEFAULT_TTL_MS);
+    const marked = await this.add(`consumed:${key}`, true, {
+      ttlMs: markerTtlMs,
+      scope: options.scope,
+    });
+    if (!marked) return null;
+    await this.delete(key, options);
+    return value;
+  }
+
+  isDegraded() {
+    if (this._customClient) return false;
+    return (
+      !this.servers.length ||
+      [...this.nodeState.values()].some(
+        (state) => state.ejected || state.healthy === false,
+      )
+    );
+  }
+
+  async health() {
+    if (this._customClient)
+      return { healthy: true, degraded: false, nodes: [] };
+    await Promise.all(this.servers.map((server) => this._probe(server)));
+    const nodes = this.servers.map((server) => ({
+      server,
+      ...this.nodeState.get(server),
+    }));
+    return {
+      healthy: nodes.some((node) => !node.ejected && node.healthy),
+      degraded: nodes.some((node) => node.ejected || !node.healthy),
+      nodes,
+    };
+  }
+
+  async close() {
+    this._closed = true;
+    if (this._healthTimer) clearInterval(this._healthTimer);
+    this.l1.clear();
+    await Promise.allSettled([
+      this.client?.quit?.(),
+      ...[...this.probes.values()].map((probe) => probe.quit?.()),
+    ]);
+  }
+
+  async _getEntry(key, options = {}) {
+    const generation = await this._scopeGeneration(options.scope);
+    const wireKey = this._wireKey("value", key, options.scope, generation);
+    const l1 = options.l1 === false ? null : this.l1.get(wireKey);
+    if (l1) {
+      this._metric("cache_get", { layer: "l1", hit: true });
+      return l1;
+    }
+    try {
+      const encoded = await this.client.get(wireKey);
+      if (encoded === undefined || encoded === null) {
+        this._metric("cache_get", { layer: "l2", hit: false });
+        return null;
+      }
+      const entry = await decodeEntry(encoded);
+      if (!entry) return null;
+      if (options.l1 !== false)
+        this.l1.set(wireKey, entry, {
+          size: Buffer.byteLength(encoded),
+          ttlMs: Math.max(1, entry.freshUntil - Date.now()),
+          scope: options.scope || "",
+        });
+      this._metric("cache_get", { layer: "l2", hit: true });
+      return entry;
+    } catch (error) {
+      this._cacheError("get", error);
+      return null;
+    }
+  }
+
+  async _storeEncoded(wireKey, entry, options) {
+    const encoded = await encodeEntry(entry, {
+      compressionThreshold: this.compressionThreshold,
+    });
+    if (encoded.bytes > this.maxValueBytes) {
+      this._metric("cache_oversize", { bytes: encoded.bytes });
+      return false;
+    }
+    try {
+      const stored = await this.client.set(
+        wireKey,
+        encoded.encoded,
+        this._ttlSeconds(options.ttlMs),
+      );
+      if (stored)
+        this.l1.set(wireKey, entry, {
+          size: encoded.bytes,
+          ttlMs: options.ttlMs,
+          scope: options.scope,
+        });
+      this._metric("cache_set", {
+        stored: !!stored,
+        bytes: encoded.bytes,
+        compressed: encoded.compressed,
+      });
+      return !!stored;
+    } catch (error) {
+      this._cacheError("set", error);
+      return false;
+    }
+  }
+
+  async _loadOnce(inflightKey, key, loader, options) {
+    if (this.inflight.has(inflightKey)) return this.inflight.get(inflightKey);
+    const promise = Promise.resolve()
+      .then(loader)
+      .then(async (value) => {
+        await this.set(key, value, options);
+        return value;
+      })
+      .finally(() => this.inflight.delete(inflightKey));
+    this.inflight.set(inflightKey, promise);
+    return promise;
+  }
+
+  async _scopeGeneration(scope, create = true) {
+    if (!scope) return "";
+    const cached = this.scopeGenerations.get(scope);
+    if (cached && cached.expiresAt > Date.now()) return cached.value;
+    const key = this._scopeKey(scope);
+    try {
+      let generation = await this.client.get(key);
+      if (!generation && create) {
+        const candidate = crypto.randomUUID();
+        if (await this.client.add(key, candidate, 0)) generation = candidate;
+        else generation = await this.client.get(key);
+      }
+      generation = generation || "";
+      this.scopeGenerations.set(scope, {
+        value: generation,
+        expiresAt: Date.now() + this.scopeGenerationTtlMs,
+      });
+      return generation;
+    } catch (error) {
+      this._cacheError("scope_generation", error);
+      return "";
+    }
+  }
+
+  _scopeKey(scope) {
+    return this._wireKey("scope", scope);
+  }
+
+  _wireKey(kind, key, scope = "", generation = "") {
+    return `mc:${crypto
+      .createHash("sha256")
+      .update(
+        `${this.namespace}\0${kind}\0${scope || ""}\0${generation || ""}\0${String(key)}`,
+      )
+      .digest("hex")}`;
+  }
+
+  _ttlSeconds(ttlMs) {
+    return Math.max(
+      1,
+      Math.ceil(
+        Math.min(Number(ttlMs) || DEFAULT_TTL_MS, 30 * 24 * 60 * 60 * 1000) /
+          1000,
+      ),
+    );
+  }
+
+  _createClient(servers) {
+    return new Memcache({
+      nodes: servers,
+      timeout: this.timeoutMs,
+      keepAlive: true,
+      retries: 0,
+      retryOnlyIdempotent: true,
+      lazyConnect: true,
+      maxValueSize: 4 * 1024 * 1024,
+    });
+  }
+
+  _initializeHealth(intervalMs) {
+    for (const server of this.servers) {
+      this.nodeState.set(server, {
+        healthy: true,
+        ejected: false,
+        failures: 0,
+        successes: 0,
+      });
+      this.probes.set(server, this._createClient([server]));
+    }
+    this._attachNodeHandlers();
+    this._healthTimer = setInterval(
+      () => {
+        Promise.all(this.servers.map((server) => this._probe(server))).catch(
+          () => {},
+        );
+      },
+      Math.max(1000, Number(intervalMs) || 5000),
+    );
+    if (typeof this._healthTimer.unref === "function")
+      this._healthTimer.unref();
+  }
+
+  _attachNodeHandlers() {
+    for (const node of this.client.getNodes()) {
+      if (node._managaniCacheHandlersAttached) continue;
+      node._managaniCacheHandlersAttached = true;
+      node.on("error", (error) => this._recordFailure(node.id, error));
+      node.on("timeout", (error) => this._recordFailure(node.id, error));
+    }
+  }
+
+  _recordFailure(server, error) {
+    const state = this.nodeState.get(server);
+    if (!state) return;
+    state.failures++;
+    state.successes = 0;
+    state.healthy = false;
+    this._metric("cache_node_failure", { server, failures: state.failures });
+    if (state.failures >= 2 && !state.ejected)
+      this._queueReconcile(() => this._eject(server, error));
+  }
+
+  async _probe(server) {
+    if (this._closed) return;
+    const state = this.nodeState.get(server);
+    const probe = this.probes.get(server);
+    try {
+      const versions = await probe.version();
+      if (!versions?.size)
+        throw new Error("Memcached version probe returned no node");
+      state.healthy = true;
+      state.failures = 0;
+      state.successes++;
+      if (state.ejected && state.successes >= 2)
+        await this._queueReconcile(() => this._rejoin(server));
+    } catch (error) {
+      this._recordFailure(server, error);
+    }
+  }
+
+  _queueReconcile(operation) {
+    this._reconcilePromise = this._reconcilePromise
+      .then(operation)
+      .catch((error) =>
+        this._log("warn", "Memcached ring reconciliation failed", error),
+      );
+    return this._reconcilePromise;
+  }
+
+  async _eject(server, error) {
+    const state = this.nodeState.get(server);
+    if (!state || state.ejected) return;
+    await this.client.removeNode(server);
+    state.ejected = true;
+    state.healthy = false;
+    state.successes = 0;
+    this._log("warn", `Memcached node ejected '${server}'`, error);
+    this._metric("cache_node_ejected", { server });
+  }
+
+  async _rejoin(server) {
+    const state = this.nodeState.get(server);
+    if (!state?.ejected) return;
+    const flushed = await this.probes.get(server).flush();
+    if (!flushed) throw new Error(`Memcached node flush failed before rejoin '${server}'`);
+    await this.client.addNode(server);
+    state.ejected = false;
+    state.healthy = true;
+    state.failures = 0;
+    state.successes = 0;
+    this._attachNodeHandlers();
+    this._log("info", `Memcached node rejoined '${server}'`);
+    this._metric("cache_node_rejoined", { server });
+  }
+
+  _cacheError(operation, error) {
+    this._metric("cache_error", { operation });
+    const now = Date.now();
+    const lastLogAt = this.errorLogTimes.get(operation) || 0;
+    if (now - lastLogAt < this.errorLogIntervalMs) return;
+    this.errorLogTimes.set(operation, now);
+    this._log("warn", `Memcached ${operation} failed`, error);
+  }
+
+  _metric(name, fields) {
+    if (typeof this.metrics === "function") this.metrics(name, fields);
+    else if (typeof this.metrics?.increment === "function")
+      this.metrics.increment(name, fields);
+  }
+
+  _log(level, message, error) {
+    const logger = this.logger;
+    if (!logger || typeof logger[level] !== "function") return;
+    if (error) logger[level]({ err: error }, message);
+    else logger[level](message);
+  }
+}
+
+function createCache(options) {
+  return new DistributedCache(options);
+}
+
+function createMongoCoordinator(options) {
+  return new MongoCoordinator(options);
+}
+
+function createRateLimitStore(options) {
+  return new MemcachedRateLimitStore(options);
+}
+
+module.exports = {
+  CacheUnavailableError,
+  DistributedCache,
+  MemcachedRateLimitStore,
+  MongoCoordinator,
+  createCache,
+  createMongoCoordinator,
+  createRateLimitStore,
+};

package/lib/l1_cache.js

@@ -0,0 +1,66 @@
+class L1Cache {
+  constructor(options = {}) {
+    this.maxBytes = Math.max(0, Number(options.maxBytes) || 0);
+    this.maxTtlMs = Math.max(0, Number(options.maxTtlMs) || 2000);
+    this.entries = new Map();
+    this.bytes = 0;
+  }
+
+  get(key, now = Date.now()) {
+    const entry = this.entries.get(key);
+    if (!entry) return null;
+    if (entry.expiresAt <= now) {
+      this.delete(key);
+      return null;
+    }
+    this.entries.delete(key);
+    this.entries.set(key, entry);
+    return entry.value;
+  }
+
+  set(key, value, options = {}) {
+    if (!this.maxBytes) return;
+    const size = Math.max(1, Number(options.size) || 1);
+    if (size > this.maxBytes) return;
+    const ttlMs = Math.min(
+      Math.max(1, Number(options.ttlMs) || this.maxTtlMs),
+      this.maxTtlMs,
+    );
+    this.delete(key);
+    this.entries.set(key, {
+      value,
+      size,
+      scope: options.scope || "",
+      expiresAt: Date.now() + ttlMs,
+    });
+    this.bytes += size;
+    this._trim();
+  }
+
+  delete(key) {
+    const entry = this.entries.get(key);
+    if (!entry) return false;
+    this.entries.delete(key);
+    this.bytes = Math.max(0, this.bytes - entry.size);
+    return true;
+  }
+
+  invalidateScope(scope) {
+    for (const [key, entry] of this.entries.entries()) {
+      if (entry.scope === scope) this.delete(key);
+    }
+  }
+
+  clear() {
+    this.entries.clear();
+    this.bytes = 0;
+  }
+
+  _trim() {
+    while (this.bytes > this.maxBytes && this.entries.size) {
+      this.delete(this.entries.keys().next().value);
+    }
+  }
+}
+
+module.exports = L1Cache;

package/lib/mongo_coordinator.js

@@ -0,0 +1,163 @@
+const crypto = require("node:crypto");
+
+function hashKey(namespace, kind, key) {
+  return crypto
+    .createHash("sha256")
+    .update(`${namespace}\0${kind}\0${key}`)
+    .digest("hex");
+}
+
+function returnedDocument(result) {
+  if (!result) return null;
+  return Object.prototype.hasOwnProperty.call(result, "value")
+    ? result.value
+    : result;
+}
+
+class MongoCoordinator {
+  constructor(options = {}) {
+    if (!options.db || typeof options.db.collection !== "function")
+      throw new Error("MongoCoordinator requires a connected MongoDB Db");
+    this.namespace = String(options.namespace || "app");
+    this.collection = options.db.collection(
+      options.collectionName || "cache_coordination",
+    );
+    this.logger = options.logger || null;
+    this.metrics = options.metrics || null;
+    this._indexes = null;
+  }
+
+  async acquireLock(key, options = {}) {
+    await this._ensureIndexes();
+    const ttlMs = Math.max(1, Number(options.ttlMs) || 60000);
+    const token = options.token || crypto.randomUUID();
+    const now = new Date();
+    const expiresAt = new Date(now.getTime() + ttlMs);
+    const _id = hashKey(this.namespace, "lock", key);
+    const update = {
+      $set: {
+        namespace: this.namespace,
+        kind: "lock",
+        key_hash: _id,
+        token,
+        expires_at: expiresAt,
+        updated_at: now,
+      },
+    };
+    let document = returnedDocument(
+      await this.collection.findOneAndUpdate(
+        {
+          _id,
+          $or: [
+            { expires_at: { $lte: now } },
+            { expires_at: { $exists: false } },
+          ],
+        },
+        update,
+        { returnDocument: "after" },
+      ),
+    );
+    if (!document) {
+      try {
+        await this.collection.insertOne({
+          _id,
+          namespace: this.namespace,
+          kind: "lock",
+          key_hash: _id,
+          token,
+          expires_at: expiresAt,
+          updated_at: now,
+        });
+        document = { token };
+      } catch (error) {
+        if (error?.code !== 11000) throw error;
+      }
+    }
+    const acquired = document?.token === token;
+    this._metric("mongo_lock", { acquired });
+    return acquired ? { key, token, expiresAt } : null;
+  }
+
+  async releaseLock(lock) {
+    if (!lock?.key || !lock?.token) return false;
+    await this._ensureIndexes();
+    const _id = hashKey(this.namespace, "lock", lock.key);
+    const result = await this.collection.deleteOne({ _id, token: lock.token });
+    return result.deletedCount === 1;
+  }
+
+  async acquireSemaphore(key, limit, options = {}) {
+    const max = Math.max(1, Number(limit) || 1);
+    const start = Math.floor(Math.random() * max);
+    for (let offset = 0; offset < max; offset++) {
+      const slot = (start + offset) % max;
+      const lock = await this.acquireLock(`semaphore:${key}:${slot}`, options);
+      if (lock) return { ...lock, semaphoreKey: key, slot };
+    }
+    return null;
+  }
+
+  async releaseSemaphore(lease) {
+    if (!lease || lease.slot === undefined) return false;
+    return this.releaseLock({
+      key: `semaphore:${lease.semaphoreKey}:${lease.slot}`,
+      token: lease.token,
+    });
+  }
+
+  async setCooldown(key, until) {
+    await this._ensureIndexes();
+    const untilDate = new Date(until);
+    const _id = hashKey(this.namespace, "cooldown", key);
+    await this.collection.updateOne(
+      { _id },
+      {
+        $setOnInsert: {
+          namespace: this.namespace,
+          kind: "cooldown",
+          key_hash: _id,
+        },
+        $max: { until: untilDate, expires_at: untilDate },
+        $set: { updated_at: new Date() },
+      },
+      { upsert: true },
+    );
+    return untilDate;
+  }
+
+  async getCooldown(key) {
+    await this._ensureIndexes();
+    const _id = hashKey(this.namespace, "cooldown", key);
+    const document = await this.collection.findOne(
+      { _id, until: { $gt: new Date() } },
+      { readPreference: "primary" },
+    );
+    return document?.until || null;
+  }
+
+  async _ensureIndexes() {
+    if (!this._indexes)
+      this._indexes = Promise.all([
+        this.collection.createIndex(
+          { expires_at: 1 },
+          { expireAfterSeconds: 0, name: "expires_at_ttl" },
+        ),
+        this.collection.createIndex(
+          { namespace: 1, kind: 1 },
+          { name: "namespace_kind" },
+        ),
+      ]).catch((error) => {
+        this._indexes = null;
+        throw error;
+      });
+    return this._indexes;
+  }
+
+  _metric(name, fields) {
+    if (typeof this.metrics === "function") this.metrics(name, fields);
+    else if (typeof this.metrics?.increment === "function")
+      this.metrics.increment(name, fields);
+  }
+}
+
+module.exports = MongoCoordinator;

package/lib/rate_limit_store.js

@@ -0,0 +1,67 @@
+class MemcachedRateLimitStore {
+  constructor(options = {}) {
+    if (!options.cache)
+      throw new Error("MemcachedRateLimitStore requires cache");
+    this.cache = options.cache;
+    this.prefix = String(options.prefix || "rl:");
+    this.windowMs = Math.max(1, Number(options.windowMs) || 60000);
+    this.localKeys = false;
+    this.memory = new Map();
+  }
+
+  init(options = {}) {
+    if (options.windowMs) this.windowMs = Math.max(1, Number(options.windowMs));
+  }
+
+  async increment(key) {
+    const bucket = this._bucket();
+    const cacheKey = `${this.prefix}${bucket.start}:${key}`;
+    let totalHits = await this.cache.increment(cacheKey, {
+      ttlMs: this.windowMs * 2,
+    });
+    if (!Number.isFinite(totalHits))
+      totalHits = this._memoryIncrement(cacheKey, bucket.end);
+    return { totalHits, resetTime: new Date(bucket.end) };
+  }
+
+  async decrement(key) {
+    const bucket = this._bucket();
+    const cacheKey = `${this.prefix}${bucket.start}:${key}`;
+    const value = await this.cache.decrement(cacheKey);
+    if (!Number.isFinite(value)) this._memoryDecrement(cacheKey);
+  }
+
+  async resetKey(key) {
+    const bucket = this._bucket();
+    const cacheKey = `${this.prefix}${bucket.start}:${key}`;
+    this.memory.delete(cacheKey);
+    await this.cache.delete(cacheKey, {
+      kind: "counter",
+    });
+  }
+
+  async resetAll() {
+    this.memory.clear();
+  }
+
+  _bucket(now = Date.now()) {
+    const start = Math.floor(now / this.windowMs) * this.windowMs;
+    return { start, end: start + this.windowMs };
+  }
+
+  _memoryIncrement(key, resetAt) {
+    const current = this.memory.get(key);
+    const count =
+      !current || current.resetAt <= Date.now() ? 1 : current.count + 1;
+    this.memory.set(key, { count, resetAt });
+    return count;
+  }
+
+  _memoryDecrement(key) {
+    const current = this.memory.get(key);
+    if (!current) return;
+    current.count = Math.max(0, current.count - 1);
+  }
+}
+
+module.exports = MemcachedRateLimitStore;

package/lib/serialization.js

@@ -0,0 +1,122 @@
+const { promisify } = require("node:util");
+const zlib = require("node:zlib");
+
+const deflateRaw = promisify(zlib.deflateRaw);
+const inflateRaw = promisify(zlib.inflateRaw);
+
+const RAW_PREFIX = "mc1:r:";
+const COMPRESSED_PREFIX = "mc1:z:";
+
+function encodeValue(value) {
+  if (value === null) return ["null"];
+  if (value === undefined) return ["undefined"];
+  if (Buffer.isBuffer(value)) return ["buffer", value.toString("base64")];
+  if (value instanceof Date) return ["date", value.toISOString()];
+  if (Array.isArray(value)) return ["array", Array.from(value, encodeValue)];
+
+  switch (typeof value) {
+    case "string":
+      return ["string", value];
+    case "boolean":
+      return ["boolean", value];
+    case "bigint":
+      return ["bigint", value.toString()];
+    case "number":
+      if (Number.isNaN(value)) return ["number", "NaN"];
+      if (value === Infinity) return ["number", "Infinity"];
+      if (value === -Infinity) return ["number", "-Infinity"];
+      if (Object.is(value, -0)) return ["number", "-0"];
+      return ["number", value];
+    case "object": {
+      if (typeof value.toJSON === "function") return encodeValue(value.toJSON());
+      return [
+        "object",
+        Object.keys(value).map((key) => [key, encodeValue(value[key])]),
+      ];
+    }
+    default:
+      throw new TypeError(`Unsupported cache value type '${typeof value}'`);
+  }
+}
+
+function decodeValue(encoded) {
+  if (!Array.isArray(encoded) || typeof encoded[0] !== "string")
+    throw new TypeError("Invalid cache value envelope");
+  const [type, value] = encoded;
+  switch (type) {
+    case "null":
+      return null;
+    case "undefined":
+      return undefined;
+    case "buffer":
+      return Buffer.from(value, "base64");
+    case "date":
+      return new Date(value);
+    case "array":
+      return value.map(decodeValue);
+    case "string":
+    case "boolean":
+      return value;
+    case "bigint":
+      return BigInt(value);
+    case "number":
+      if (value === "NaN") return NaN;
+      if (value === "Infinity") return Infinity;
+      if (value === "-Infinity") return -Infinity;
+      if (value === "-0") return -0;
+      return value;
+    case "object":
+      return Object.fromEntries(
+        value.map(([key, item]) => [key, decodeValue(item)]),
+      );
+    default:
+      throw new TypeError(`Unsupported cache value envelope '${type}'`);
+  }
+}
+
+async function encodeEntry(entry, options = {}) {
+  const compressionThreshold = Math.max(
+    0,
+    Number(options.compressionThreshold) || 64 * 1024,
+  );
+  const raw = Buffer.from(
+    JSON.stringify({ version: 1, entry: encodeValue(entry) }),
+  );
+  let prefix = RAW_PREFIX;
+  let payload = raw;
+  if (raw.length >= compressionThreshold) {
+    const compressed = await deflateRaw(raw, {
+      level: zlib.constants.Z_BEST_SPEED,
+    });
+    if (compressed.length <= raw.length * 0.9) {
+      prefix = COMPRESSED_PREFIX;
+      payload = compressed;
+    }
+  }
+  const encoded = `${prefix}${payload.toString("base64")}`;
+  return {
+    encoded,
+    bytes: Buffer.byteLength(encoded),
+    compressed: prefix === COMPRESSED_PREFIX,
+  };
+}
+
+async function decodeEntry(encoded) {
+  if (typeof encoded !== "string") return null;
+  let payload;
+  if (encoded.startsWith(RAW_PREFIX)) {
+    payload = Buffer.from(encoded.slice(RAW_PREFIX.length), "base64");
+  } else if (encoded.startsWith(COMPRESSED_PREFIX)) {
+    payload = await inflateRaw(
+      Buffer.from(encoded.slice(COMPRESSED_PREFIX.length), "base64"),
+    );
+  } else {
+    return null;
+  }
+  const envelope = JSON.parse(payload.toString("utf8"));
+  if (!envelope || envelope.version !== 1) return null;
+  const entry = decodeValue(envelope.entry);
+  return entry && entry.version === 1 ? entry : null;
+}
+
+module.exports = { decodeEntry, decodeValue, encodeEntry, encodeValue };

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@managani/cache",
+  "version": "0.1.0",
+  "description": "Shared Memcached cache and MongoDB coordination primitives",
+  "main": "index.js",
+  "type": "commonjs",
+  "license": "MIT",
+  "files": [
+    "index.js",
+    "lib",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "node --test test/cache.test.js test/mongo_coordinator.test.js",
+    "test:integration": "node --test test/memcached.integration.test.js",
+    "test:cluster": "node test/cluster_chaos.js"
+  },
+  "keywords": [
+    "cache",
+    "memcached",
+    "mongodb",
+    "distributed-cache"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/streamient/managani.git",
+    "directory": "packages/cache"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=24"
+  },
+  "dependencies": {
+    "memcache": "1.10.0"
+  }
+}