Build an API Idempotency Layer

npm install hono @hono/node-server ioredis
npm install -D typescript @types/node

// src/idempotency/middleware.ts — Idempotency-Key handling for Hono on Redis
import type { Context, MiddlewareHandler } from "hono";
import { Redis } from "ioredis";
import { createHash, randomUUID } from "node:crypto";

const redis = new Redis(process.env.REDIS_URL!);

type Record_ =
  | { state: "processing"; fp: string; token: string }
  | { state: "done"; fp: string; token: string; status: number; contentType: string; body: string };

const LOCK_MS = 60_000;           // how long an in-flight request may hold the key
const DEFAULT_TTL = 24 * 60 * 60; // how long a finished response can be replayed

// Atomically: if the key still holds OUR token, replace it (or delete it when ARGV[2] is empty).
const FINISH = `
local v = redis.call('GET', KEYS[1])
if not v or cjson.decode(v).token ~= ARGV[1] then return 0 end
if ARGV[2] == '' then return redis.call('DEL', KEYS[1]) end
redis.call('SET', KEYS[1], ARGV[2], 'EX', tonumber(ARGV[3]))
return 1`;

const replay = (r: Extract<Record_, { state: "done" }>) =>
  new Response(r.body, { status: r.status, headers: { "Content-Type": r.contentType, "Idempotent-Replayed": "true" } });

export function idempotency(opts: {
  scope: (c: Context) => string;   // e.g. the authenticated account id: keys are per caller, never global
  requiredOn?: string[];           // path prefixes where a missing key is a 400
  ttl?: number;
}): MiddlewareHandler {
  return async (c, next) => {
    if (["GET", "HEAD", "OPTIONS"].includes(c.req.method)) return next();
    const header = c.req.header("Idempotency-Key");
    if (!header) {
      if (opts.requiredOn?.some((p) => c.req.path.startsWith(p))) return c.json({ error: "Idempotency-Key header required" }, 400);
      return next();
    }
    if (header.length > 255) return c.json({ error: "Idempotency-Key too long" }, 400);

    // Same key + different request is a client bug: reject it instead of replaying the wrong response.
    const fp = createHash("sha256").update(`${c.req.method}\n${c.req.path}\n${await c.req.text()}`).digest("hex");
    const key = `idem:${opts.scope(c)}:${createHash("sha256").update(header).digest("hex")}`;
    const token = randomUUID();

    // One atomic step both checks and claims the key; there is no window between "look" and "lock".
    const claimed = await redis.set(key, JSON.stringify({ state: "processing", fp, token }), "PX", LOCK_MS, "NX");
    if (!claimed) {
      const raw = await redis.get(key);
      if (!raw) return c.json({ error: "Retry the request" }, 409); // expired between SET and GET
      const rec: Record_ = JSON.parse(raw);
      if (rec.fp !== fp) return c.json({ error: "Idempotency-Key reused with a different request" }, 422);
      if (rec.state === "processing") return c.json({ error: "A request with this key is still in progress" }, 409, { "Retry-After": "1" });
      return replay(rec);
    }

    try {
      await next();
    } catch (err) {
      await redis.eval(FINISH, 1, key, token, "", 0); // let the client retry
      throw err;
    }
    // Hono turns handler exceptions into a 500 response; never replay those.
    if (c.res.status >= 500) {
      await redis.eval(FINISH, 1, key, token, "", 0);
      return;
    }
    const done: Record_ = {
      state: "done", fp, token, status: c.res.status,
      contentType: c.res.headers.get("content-type") ?? "application/json",
      body: await c.res.clone().text(),
    };
    await redis.eval(FINISH, 1, key, token, JSON.stringify(done), opts.ttl ?? DEFAULT_TTL);
  };
}

import { Hono } from "hono";
import { idempotency } from "./idempotency/middleware.ts";

// declare the variable your auth middleware sets, or c.get("accountId") does not type-check
const app = new Hono<{ Variables: { accountId: string } }>();
app.use("/payments/*", idempotency({ scope: (c) => c.get("accountId"), requiredOn: ["/payments"] }));
app.post("/payments", async (c) => { /* charge once */ });