@classytic/arc 1.0.0

package/dist/idempotency/index.js

@@ -0,0 +1,500 @@
+import fp from 'fastify-plugin';
+import { createHash } from 'crypto';
+
+// src/idempotency/idempotencyPlugin.ts
+
+// src/idempotency/stores/interface.ts
+function createIdempotencyResult(statusCode, body, headers, ttlMs) {
+  const now = /* @__PURE__ */ new Date();
+  return {
+    statusCode,
+    headers,
+    body,
+    createdAt: now,
+    expiresAt: new Date(now.getTime() + ttlMs)
+  };
+}
+
+// src/idempotency/stores/memory.ts
+var MemoryIdempotencyStore = class {
+  name = "memory";
+  results = /* @__PURE__ */ new Map();
+  locks = /* @__PURE__ */ new Map();
+  ttlMs;
+  maxEntries;
+  cleanupInterval = null;
+  constructor(options = {}) {
+    this.ttlMs = options.ttlMs ?? 864e5;
+    this.maxEntries = options.maxEntries ?? 1e4;
+    const cleanupIntervalMs = options.cleanupIntervalMs ?? 6e4;
+    this.cleanupInterval = setInterval(() => {
+      this.cleanup();
+    }, cleanupIntervalMs);
+    if (this.cleanupInterval.unref) {
+      this.cleanupInterval.unref();
+    }
+  }
+  async get(key) {
+    const result = this.results.get(key);
+    if (!result) return void 0;
+    if (/* @__PURE__ */ new Date() > result.expiresAt) {
+      this.results.delete(key);
+      return void 0;
+    }
+    return result;
+  }
+  async set(key, result) {
+    if (this.results.size >= this.maxEntries) {
+      this.evictOldest();
+    }
+    this.results.set(key, { ...result, key });
+  }
+  async tryLock(key, requestId, ttlMs) {
+    const existing = this.locks.get(key);
+    if (existing) {
+      if (/* @__PURE__ */ new Date() > existing.expiresAt) {
+        this.locks.delete(key);
+      } else {
+        return false;
+      }
+    }
+    this.locks.set(key, {
+      key,
+      requestId,
+      lockedAt: /* @__PURE__ */ new Date(),
+      expiresAt: new Date(Date.now() + ttlMs)
+    });
+    return true;
+  }
+  async unlock(key, requestId) {
+    const lock = this.locks.get(key);
+    if (lock && lock.requestId === requestId) {
+      this.locks.delete(key);
+    }
+  }
+  async isLocked(key) {
+    const lock = this.locks.get(key);
+    if (!lock) return false;
+    if (/* @__PURE__ */ new Date() > lock.expiresAt) {
+      this.locks.delete(key);
+      return false;
+    }
+    return true;
+  }
+  async delete(key) {
+    this.results.delete(key);
+    this.locks.delete(key);
+  }
+  async close() {
+    if (this.cleanupInterval) {
+      clearInterval(this.cleanupInterval);
+      this.cleanupInterval = null;
+    }
+    this.results.clear();
+    this.locks.clear();
+  }
+  /**
+   * Get current stats (for debugging/monitoring)
+   */
+  getStats() {
+    return {
+      results: this.results.size,
+      locks: this.locks.size
+    };
+  }
+  /**
+   * Remove expired entries
+   */
+  cleanup() {
+    const now = /* @__PURE__ */ new Date();
+    for (const [key, result] of this.results) {
+      if (now > result.expiresAt) {
+        this.results.delete(key);
+      }
+    }
+    for (const [key, lock] of this.locks) {
+      if (now > lock.expiresAt) {
+        this.locks.delete(key);
+      }
+    }
+  }
+  /**
+   * Evict oldest entries when at capacity
+   */
+  evictOldest() {
+    const entries = Array.from(this.results.entries()).sort((a, b) => a[1].createdAt.getTime() - b[1].createdAt.getTime());
+    const toRemove = Math.max(1, Math.floor(entries.length * 0.1));
+    for (let i = 0; i < toRemove; i++) {
+      const entry = entries[i];
+      if (entry) {
+        this.results.delete(entry[0]);
+      }
+    }
+  }
+};
+
+// src/idempotency/idempotencyPlugin.ts
+var HEADER_IDEMPOTENCY_REPLAYED = "x-idempotency-replayed";
+var HEADER_IDEMPOTENCY_KEY = "x-idempotency-key";
+var idempotencyPlugin = async (fastify, opts = {}) => {
+  const {
+    enabled = false,
+    headerName = "idempotency-key",
+    ttlMs = 864e5,
+    // 24 hours
+    lockTimeoutMs = 3e4,
+    // 30 seconds
+    methods = ["POST", "PUT", "PATCH"],
+    include,
+    exclude,
+    store = new MemoryIdempotencyStore({ ttlMs }),
+    retryAfterSeconds = 1
+  } = opts;
+  if (!enabled) {
+    fastify.decorate("idempotency", {
+      invalidate: async () => {
+      },
+      has: async () => false
+    });
+    fastify.decorateRequest("idempotencyKey", void 0);
+    fastify.decorateRequest("idempotencyReplayed", false);
+    fastify.log?.debug?.("Idempotency plugin disabled");
+    return;
+  }
+  const methodSet = new Set(methods.map((m) => m.toUpperCase()));
+  fastify.decorate("idempotency", {
+    invalidate: async (key) => {
+      await store.delete(key);
+    },
+    has: async (key) => {
+      const result = await store.get(key);
+      return !!result;
+    }
+  });
+  fastify.decorateRequest("idempotencyKey", void 0);
+  fastify.decorateRequest("idempotencyReplayed", false);
+  function shouldApplyIdempotency(request) {
+    if (!methodSet.has(request.method)) {
+      return false;
+    }
+    const url = request.url;
+    if (exclude?.some((pattern) => pattern.test(url))) {
+      return false;
+    }
+    if (include && !include.some((pattern) => pattern.test(url))) {
+      return false;
+    }
+    return true;
+  }
+  function normalizeBody(obj) {
+    if (obj === null || typeof obj !== "object") {
+      return obj;
+    }
+    if (Array.isArray(obj)) {
+      return obj.map(normalizeBody);
+    }
+    const sorted = {};
+    const keys = Object.keys(obj).sort();
+    for (const key of keys) {
+      sorted[key] = normalizeBody(obj[key]);
+    }
+    return sorted;
+  }
+  function getRequestFingerprint(request) {
+    let bodyHash = "nobody";
+    if (request.body && typeof request.body === "object") {
+      const normalized = normalizeBody(request.body);
+      const bodyString = JSON.stringify(normalized);
+      bodyHash = createHash("sha256").update(bodyString).digest("hex").substring(0, 16);
+      if (request.log && request.log.debug) {
+        request.log.debug({ bodyHash }, "Generated body hash");
+      }
+    }
+    const fingerprint = `${request.method}:${request.url}:${bodyHash}`;
+    return fingerprint;
+  }
+  fastify.addHook("preHandler", async (request, reply) => {
+    if (!shouldApplyIdempotency(request)) {
+      return;
+    }
+    const keyHeader = request.headers[headerName.toLowerCase()];
+    const idempotencyKey = typeof keyHeader === "string" ? keyHeader.trim() : void 0;
+    if (!idempotencyKey) {
+      return;
+    }
+    request.idempotencyKey = idempotencyKey;
+    const fullKey = `${idempotencyKey}:${getRequestFingerprint(request)}`;
+    const cached = await store.get(fullKey);
+    if (cached) {
+      request.idempotencyReplayed = true;
+      reply.header(HEADER_IDEMPOTENCY_REPLAYED, "true");
+      reply.header(HEADER_IDEMPOTENCY_KEY, idempotencyKey);
+      for (const [key, value] of Object.entries(cached.headers)) {
+        if (!key.startsWith("x-idempotency")) {
+          reply.header(key, value);
+        }
+      }
+      reply.code(cached.statusCode).send(cached.body);
+      return;
+    }
+    const lockAcquired = await store.tryLock(fullKey, request.id, lockTimeoutMs);
+    if (!lockAcquired) {
+      reply.code(409).header("Retry-After", retryAfterSeconds.toString()).send({
+        error: "Request with this idempotency key is already in progress",
+        code: "IDEMPOTENCY_CONFLICT",
+        retryAfter: retryAfterSeconds
+      });
+      return;
+    }
+    request._idempotencyFullKey = fullKey;
+  });
+  fastify.addHook("onSend", async (request, reply, payload) => {
+    if (request.idempotencyReplayed) {
+      return payload;
+    }
+    const fullKey = request._idempotencyFullKey;
+    if (!fullKey) {
+      return payload;
+    }
+    const statusCode = reply.statusCode;
+    if (statusCode < 200 || statusCode >= 300) {
+      await store.unlock(fullKey, request.id);
+      return payload;
+    }
+    const headersToCache = {};
+    const excludeHeaders = /* @__PURE__ */ new Set([
+      "content-length",
+      "transfer-encoding",
+      "connection",
+      "keep-alive",
+      "date",
+      "set-cookie"
+    ]);
+    const rawHeaders = reply.getHeaders();
+    for (const [key, value] of Object.entries(rawHeaders)) {
+      if (!excludeHeaders.has(key.toLowerCase()) && typeof value === "string") {
+        headersToCache[key] = value;
+      }
+    }
+    let body;
+    try {
+      body = typeof payload === "string" ? JSON.parse(payload) : payload;
+    } catch {
+      body = payload;
+    }
+    const result = createIdempotencyResult(statusCode, body, headersToCache, ttlMs);
+    await store.set(fullKey, result);
+    await store.unlock(fullKey, request.id);
+    reply.header(HEADER_IDEMPOTENCY_KEY, request.idempotencyKey);
+    return payload;
+  });
+  fastify.addHook("onError", async (request) => {
+    const fullKey = request._idempotencyFullKey;
+    if (fullKey) {
+      await store.unlock(fullKey, request.id);
+    }
+  });
+  fastify.addHook("onClose", async () => {
+    await store.close?.();
+  });
+  fastify.log?.info?.({ headerName, ttlMs, methods }, "Idempotency plugin enabled");
+};
+var idempotencyPlugin_default = fp(idempotencyPlugin, {
+  name: "arc-idempotency",
+  fastify: "5.x"
+});
+
+// src/idempotency/stores/redis.ts
+var RedisIdempotencyStore = class {
+  name = "redis";
+  client;
+  prefix;
+  lockPrefix;
+  ttlMs;
+  constructor(options) {
+    this.client = options.client;
+    this.prefix = options.prefix ?? "idem:";
+    this.lockPrefix = options.lockPrefix ?? "idem:lock:";
+    this.ttlMs = options.ttlMs ?? 864e5;
+  }
+  resultKey(key) {
+    return `${this.prefix}${key}`;
+  }
+  lockKey(key) {
+    return `${this.lockPrefix}${key}`;
+  }
+  async get(key) {
+    const data = await this.client.get(this.resultKey(key));
+    if (!data) return void 0;
+    try {
+      const result = JSON.parse(data);
+      if (new Date(result.expiresAt) < /* @__PURE__ */ new Date()) {
+        await this.delete(key);
+        return void 0;
+      }
+      return {
+        ...result,
+        createdAt: new Date(result.createdAt),
+        expiresAt: new Date(result.expiresAt)
+      };
+    } catch {
+      return void 0;
+    }
+  }
+  async set(key, result) {
+    const data = { key, ...result };
+    const ttlSeconds = Math.ceil(
+      (new Date(result.expiresAt).getTime() - Date.now()) / 1e3
+    );
+    if (ttlSeconds > 0) {
+      await this.client.set(this.resultKey(key), JSON.stringify(data), {
+        EX: ttlSeconds
+      });
+    }
+  }
+  async tryLock(key, requestId, ttlMs) {
+    const ttlSeconds = Math.ceil(ttlMs / 1e3);
+    const result = await this.client.set(
+      this.lockKey(key),
+      requestId,
+      { EX: ttlSeconds, NX: true }
+    );
+    return result === "OK";
+  }
+  async unlock(key, requestId) {
+    const currentHolder = await this.client.get(this.lockKey(key));
+    if (currentHolder === requestId) {
+      await this.client.del(this.lockKey(key));
+    }
+  }
+  async isLocked(key) {
+    const exists = await this.client.exists(this.lockKey(key));
+    return exists > 0;
+  }
+  async delete(key) {
+    await this.client.del([this.resultKey(key), this.lockKey(key)]);
+  }
+  async close() {
+  }
+};
+
+// src/idempotency/stores/mongodb.ts
+var MongoIdempotencyStore = class {
+  name = "mongodb";
+  connection;
+  collectionName;
+  ttlMs;
+  indexCreated = false;
+  constructor(options) {
+    this.connection = options.connection;
+    this.collectionName = options.collection ?? "arc_idempotency";
+    this.ttlMs = options.ttlMs ?? 864e5;
+    if (options.createIndex !== false) {
+      this.ensureIndex().catch((err) => {
+        console.warn("[MongoIdempotencyStore] Failed to create index:", err);
+      });
+    }
+  }
+  get collection() {
+    return this.connection.db.collection(this.collectionName);
+  }
+  async ensureIndex() {
+    if (this.indexCreated) return;
+    try {
+      await this.collection.createIndex(
+        { expiresAt: 1 },
+        { expireAfterSeconds: 0 }
+      );
+      this.indexCreated = true;
+    } catch {
+      this.indexCreated = true;
+    }
+  }
+  async get(key) {
+    const doc = await this.collection.findOne({ _id: key });
+    if (!doc || !doc.result) return void 0;
+    if (new Date(doc.expiresAt) < /* @__PURE__ */ new Date()) {
+      return void 0;
+    }
+    return {
+      key,
+      statusCode: doc.result.statusCode,
+      headers: doc.result.headers,
+      body: doc.result.body,
+      createdAt: new Date(doc.createdAt),
+      expiresAt: new Date(doc.expiresAt)
+    };
+  }
+  async set(key, result) {
+    await this.collection.updateOne(
+      { _id: key },
+      {
+        $set: {
+          result: {
+            statusCode: result.statusCode,
+            headers: result.headers,
+            body: result.body
+          },
+          createdAt: result.createdAt,
+          expiresAt: result.expiresAt
+        },
+        $unset: { lock: "" }
+      },
+      { upsert: true }
+    );
+  }
+  async tryLock(key, requestId, ttlMs) {
+    const now = /* @__PURE__ */ new Date();
+    const expiresAt = new Date(now.getTime() + ttlMs);
+    try {
+      const existingDoc = await this.collection.findOne({ _id: key });
+      if (existingDoc) {
+        if (existingDoc.lock && new Date(existingDoc.lock.expiresAt) > now) {
+          return false;
+        }
+        const updateResult = await this.collection.updateOne(
+          {
+            _id: key,
+            $or: [
+              { lock: { $exists: false } },
+              { "lock.expiresAt": { $lt: now } }
+            ]
+          },
+          {
+            $set: {
+              lock: { requestId, expiresAt }
+            }
+          }
+        );
+        return updateResult.acknowledged;
+      }
+      const insertResult = await this.collection.insertOne({
+        _id: key,
+        lock: { requestId, expiresAt },
+        createdAt: now,
+        expiresAt: new Date(now.getTime() + this.ttlMs)
+      });
+      return insertResult.acknowledged;
+    } catch {
+      return false;
+    }
+  }
+  async unlock(key, requestId) {
+    await this.collection.updateOne(
+      { _id: key, "lock.requestId": requestId },
+      { $unset: { lock: "" } }
+    );
+  }
+  async isLocked(key) {
+    const doc = await this.collection.findOne({ _id: key });
+    if (!doc || !doc.lock) return false;
+    return new Date(doc.lock.expiresAt) > /* @__PURE__ */ new Date();
+  }
+  async delete(key) {
+    await this.collection.deleteOne({ _id: key });
+  }
+  async close() {
+  }
+};
+
+export { MemoryIdempotencyStore, MongoIdempotencyStore, RedisIdempotencyStore, createIdempotencyResult, idempotencyPlugin_default as idempotencyPlugin, idempotencyPlugin as idempotencyPluginFn };