webhookgate-sdk 1.0.0 → 1.0.2

package/README.md

@@ -0,0 +1,115 @@
+# WebhookGate
+
+WebhookGate guarantees **no duplicate webhook side effects**.
+
+https://webhookgate.com
+
+It does this by combining:
+- **durable webhook intake and de-duplication** at the gateway layer, and
+- a **consumer-side idempotency SDK** that makes duplicate side effects **structurally impossible** within the consumer.
+
+WebhookGate sits in front of webhook consumers and ensures that each `(provider, eventId)` is **accepted exactly once**, even under retries, replays, or noisy providers - and that downstream effects are never duplicated when the consumer uses the SDK.
+
+---
+
+## What WebhookGate guarantees (MVP)
+
+WebhookGate provides a durable webhook “inbox” in front of your consumer.
+
+### Gateway guarantees
+
+- **Exactly-once acceptance** per `(provider, eventId)`
+- **De-duplication at intake**: repeated deliveries of the same event are not re-accepted
+- **Durable delivery jobs + transport retries**: downstream delivery is retried on network/transport failure
+- **Deterministic Idempotency-Key propagation** on every downstream delivery
+
+The gateway delivers events **at-least-once** downstream, always with the same
+Idempotency-Key, even across retries, crashes, or restarts.
+
+---
+
+## Consumer SDK: No duplicate side effects
+
+The consumer SDK converts delivery guarantees into **hard correctness**.
+
+### What the SDK guarantees
+
+- **At-most-once execution** of the handler per Idempotency-Key
+- **Duplicate deliveries never re-run side effects**
+- **Crash-safe behavior**: if the process crashes mid-handler, the handler is never re-entered (row remains processing)
+- **Error behavior (terminal)**: if the handler throws, the idempotency row transitions to 'failed' and is never re-entered automatically
+- **Transactional DB effects** for database operations performed via the provided db client
+
+Once a key is successfully claimed, the handler will **never** be executed again — even if the process crashes, restarts, or receives the same event repeatedly.
+
+> Result: side effects are never duplicated.
+
+---
+
+## Exactly-once effects (clarified)
+
+WebhookGate guarantees that your handler runs at most once per Idempotency-Key.
+
+If your handler calls external systems (payments, email providers, APIs), those systems must respect idempotency keys to achieve end-to-end exactly-once effects across system boundaries.
+
+This design deliberately favors **safety over re-execution**:
+WebhookGate will never risk double-charging, double-emailing, or double-writing.
+
+---
+
+## Install
+
+```bash
+npm install webhookgate-sdk
+```
+
+The SDK automatically creates the required idempotency tables on first use.
+
+---
+
+## What the developer writes (locked API)
+
+```js
+import { idempotent } from "webhookgate-sdk";
+
+app.post(
+  "/webhooks/stripe",
+  idempotent(async ({ event, db }) => {
+    await chargeCustomer(event);   // never executed twice
+    await sendReceipt(event);      // never executed twice
+  })
+);
+```
+
+---
+
+## Proof: No duplicate side effects (60 seconds)
+
+1. Start Postgres
+2. Install dependencies
+   npm install
+3. Start the consumer
+   npm run consumer
+4. Start the gateway
+   npm run dev
+5. Send a replay storm
+   npm run chaos -- evt_test_1
+
+Result:
+- Gateway receives 50 duplicate events
+- Consumer executes the handler once
+- /stats shows charges = 1
+
+Crash test:
+- Start consumer with CRASH_ONCE=true
+- Re-run chaos
+- Restart consumer
+- Charges still = 1
+
+---
+
+## When you need production-grade durability
+
+WebhookGate adds durable intake, replay protection, and operational safeguards for environments where local correctness is no longer sufficient.
+
+Learn more at https://webhookgate.com

package/idempotent.js

@@ -0,0 +1,142 @@
+import { Pool } from "pg";
+
+const pool = new Pool({
+  host: process.env.PGHOST,
+  port: process.env.PGPORT ? Number(process.env.PGPORT) : undefined,
+  database: process.env.PGDATABASE,
+  user: process.env.PGUSER,
+  password: process.env.PGPASSWORD,
+  ssl: process.env.PGSSL === "true" ? { rejectUnauthorized: false } : undefined,
+});
+
+let _readyPromise = null;
+
+async function ensureTables() {
+  if (_readyPromise) return _readyPromise;
+
+  _readyPromise = (async () => {
+    await pool.query(`
+      CREATE TABLE IF NOT EXISTS webhook_idempotency (
+        idempotency_key TEXT PRIMARY KEY,
+        status TEXT NOT NULL CHECK (status IN ('processing','done','failed')),
+        created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+        completed_at TIMESTAMPTZ
+      );
+    `);
+
+    await pool.query(`
+      CREATE TABLE IF NOT EXISTS demo_charges (
+        id BIGSERIAL PRIMARY KEY,
+        idempotency_key TEXT NOT NULL UNIQUE,
+        created_at TIMESTAMPTZ NOT NULL DEFAULT now()
+      );
+    `);
+  })();
+
+  return _readyPromise;
+}
+
+function getIdempotencyKey(req) {
+  // Primary: what our gateway sends
+  const k = req.get("Idempotency-Key") || req.get("idempotency-key");
+  return k ? String(k).trim() : "";
+}
+
+/**
+ * Locked API:
+ * app.post("/webhooks/stripe", idempotent(async ({ req, event, db }) => {}))
+ *
+ * Guarantees:
+ * - first time key seen: handler runs
+ * - any repeat of same key: handler does NOT run (returns 200)
+ * - crash or error mid-handler: key transitions to 'failed' and is never re-run
+ */
+export function idempotent(handler) {
+  return async function idempotentMiddleware(req, res) {
+    await ensureTables();
+
+    const key = getIdempotencyKey(req);
+
+    if (!key) {
+      return res.status(400).json({
+        ok: false,
+        error: "Missing Idempotency-Key header",
+      });
+    }
+
+    // IMPORTANT: the SDK assumes req.body already contains the parsed event
+    const event = req.body;
+
+    const client = await pool.connect();
+    let inTxn = false;
+    try {
+      // Atomic "claim"
+      // If it inserts: we own execution.
+      // If it conflicts: someone already claimed (or finished) => skip.
+      const claimed = await client.query(
+        `
+        INSERT INTO webhook_idempotency (idempotency_key, status)
+        VALUES ($1, 'processing')
+        ON CONFLICT (idempotency_key) DO NOTHING
+        RETURNING idempotency_key
+        `,
+        [key]
+      );
+
+      if (claimed.rowCount === 0) {
+        // Already seen => do nothing (exactly-once effects)
+        return res.status(200).json({ ok: true, deduped: true });
+      }
+
+      // 2) Transaction boundary for DB effects inside handler
+      await client.query("BEGIN");
+      inTxn = true;
+
+      // Run user handler
+      await handler({ req, res, event, db: client });
+
+      // Mark done
+      await client.query(
+        `
+        UPDATE webhook_idempotency
+        SET status='done', completed_at=now()
+        WHERE idempotency_key=$1
+        `,
+        [key]
+      );
+
+      await client.query("COMMIT");
+      inTxn = false;
+
+      // If handler already wrote to res, don't double-send.
+      if (!res.headersSent) {
+        return res.status(200).json({ ok: true, deduped: false });
+      }
+    } catch (err) {
+      // best-effort rollback if handler started a txn
+      try {
+        if (inTxn) await client.query("ROLLBACK");
+      } catch (_) {}
+
+      // Optional: mark failed (still prevents reruns, which is the contract you chose)
+      try {
+        await client.query(
+          `
+          UPDATE webhook_idempotency
+          SET status='failed', completed_at=now()
+          WHERE idempotency_key=$1 AND status='processing'
+          `,
+          [key]
+        );
+      } catch (_) {
+        // ignore secondary failure
+      }
+
+      if (!res.headersSent) {
+        return res.status(500).json({ ok: false, error: err?.message || String(err) });
+      }
+    } finally {
+      client.release();
+    }
+  };
+}

package/index.js

@@ -1,2 +1,2 @@
 // packages/sdk/index.js
-export { idempotent } from "../../src/idempotent.js";
+export { idempotent } from "./idempotent.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "webhookgate-sdk",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "type": "module",
   "main": "index.js",
   "exports": {