Merge pull request #3 from TykTechnologies/feat/storage-binding-mocks

Mock TykStorage* bindings in harness + idempotency-guard example

Author: sedkis

README.md

@@ -20,7 +20,7 @@ That's the inner loop. **No Tyk component required to run any of it.**
 
 - **Working starter plugin** in `src/plugin.ts` — injects an `X-Trace-Id` header on every request. Replace with your logic.
 - **TypeScript types** for the Tyk plugin API via [`@tyk-technologies/tyk-plugin-types`](https://www.npmjs.com/package/@tyk-technologies/tyk-plugin-types) on npm — autocomplete in any IDE.
-- **Local test harness** in `test/_harness.ts` — mocks the goja runtime so tests run in plain Node via vitest.
+- **Local test harness** in `test/_harness.ts` — mocks the goja runtime so tests run in plain Node via vitest. Includes faithful mocks of the six shared storage bindings (`TykStorageGet/Set/SetNX/Del/TTL/Incr`), TTL and input limits included, plus a `mockStorage` helper to seed/inspect storage from tests.
 - **AGENTS.md** — the constraints brief for AI assistants. Keeps Claude/Cursor/Copilot from suggesting Node APIs like `import axios` or runtime module loading the goja runtime can't do.
 - **Webpack config** targeting ES2020 by default (run by goja v5.14+; the guaranteed floor is ES5.1) — bundles your TypeScript plus npm deps into a single self-contained JS file the gateway can run.
 - **GitHub Actions** — runs tests and builds on every push, plus an end-to-end suite that exercises every example against a real goja-enabled Tyk OSS gateway in Docker (see [e2e/](./e2e/)).

examples/README.md

@@ -12,6 +12,7 @@ Marquee plugin patterns demonstrating common Tyk plugin shapes. Copy a folder, m
 | [post-key-auth-tenant-context](./post-key-auth-tenant-context/) | `post_key_auth` | Read `session.meta_data.tenant_id`, inject `X-Tenant-Id` header for upstream. |
 | [post-correlation-id](./post-correlation-id/) | `post` | Preserve inbound `X-Correlation-Id` or generate UUID v4; uses the `uuid` npm package. |
 | [response-pii-redaction](./response-pii-redaction/) | `response` | Mask SSN-shaped patterns in response bodies before they reach the client. |
+| [idempotency-guard](./idempotency-guard/) | `pre` | Reject duplicate `Idempotency-Key` requests via the atomic `TykStorageSetNX` claim pattern (shared storage bindings). |
 
 Each example is unit-tested locally **and** runs against a real Tyk OSS gateway in CI via `e2e/` — see [e2e/README.md](../e2e/README.md).
 

examples/idempotency-guard/README.md

@@ -0,0 +1,42 @@
+# Idempotency Guard
+
+Reject duplicate requests that reuse an `Idempotency-Key` header, using the gateway's shared storage bindings (`TykStorage*`). Demonstrates the **atomic SetNX claim pattern** — the canonical way to do "first one wins" across gateway workers without a read-then-write race.
+
+## What it does
+
+On the `pre` hook:
+
+1. Reads the `Idempotency-Key` request header. **No header → pass through** (idempotency is client opt-in).
+2. Calls `TykStorageSetNX('idem:' + key, 'pending', 60)` — an atomic "set if not exists" against the gateway's Redis.
+   - **Claimed (true)** → this is the first request with that key. Pass through.
+   - **Not claimed (false)** → a request with the same key already ran within the last 60s. Return **409 Conflict**.
+3. If storage itself errors, the plugin **fails closed** with a 500 — without the guard it can't rule out a duplicate side effect, so refusing is safer than letting it through.
+
+The claim expires after 60 seconds (`CLAIM_TTL_SECONDS` in `src/plugin.ts`) — tune it to your clients' retry window.
+
+## Why SetNX and not Get-then-Set?
+
+Two concurrent requests with the same key would both `Get` (miss), then both `Set` and both proceed. `TykStorageSetNX` collapses check-and-claim into one atomic Redis operation, so exactly one request wins even under concurrency.
+
+## Caveat: atomicity scope
+
+Atomicity is **per Redis instance**. Each gateway's `TykStorage*` bindings talk to that gateway's configured Redis — in a multi-node **hybrid** deployment where data planes run separate Redis instances, each Redis enforces the guard independently. For a **global** guarantee, all gateways enforcing the guard must share the same Redis.
+
+## Try it
+
+```bash
+npm install
+npm test                # pure Node, no gateway needed
+npm run build:bundle    # dist/bundle.zip
+```
+
+```bash
+curl -X POST localhost:8080/<plugin>/post -H 'Idempotency-Key: order-123'   # 200 — claimed
+curl -X POST localhost:8080/<plugin>/post -H 'Idempotency-Key: order-123'   # 409 — duplicate
+```
+
+## Notes
+
+- `TykStorage*` bindings throw on invalid input: empty key, key > 256 bytes, value > 64KB. The test harness enforces the same limits, so violations surface in `npm test`, not in production.
+- This guard only *blocks* duplicates; it doesn't *replay* the first response (full idempotency-key semantics à la Stripe). For that you'd `TykStorageSet` the response on the `response` hook and serve it from storage on a duplicate.
+- The bindings aren't in `@tyk-technologies/tyk-plugin-types` yet — the plugin carries a local `declare function` for `TykStorageSetNX`.

examples/idempotency-guard/manifest.json

@@ -0,0 +1,15 @@
+{
+  "file_list": ["plugin.js"],
+  "custom_middleware": {
+    "pre": [
+      {
+        "name": "handler",
+        "path": "plugin.js",
+        "require_session": false,
+        "raw_body_only": false
+      }
+    ],
+    "driver": "javascript"
+  },
+  "checksum": ""
+}