feat: option to persist and replay selected non-2xx responses

[paveg]

Summary

The middleware deletes the idempotency record whenever the handler returns a non-2xx response, so a client that retries after receiving, say, a 409 re-runs the handler instead of getting the same 409 replayed. For some APIs that is exactly right. For others the non-2xx is the durable outcome of the request, and re-running the handler is the thing idempotency was supposed to prevent. An opt-in to persist selected non-2xx responses would cover the second case.

Where this happens

dist/index.js (v0.9.1), after next() resolves:

const res = c.res;
if (!res.ok) {
  await store.delete(storeKey);
  return;
}

and the store contract in types.d.ts documents the same intent:

complete() — Called after the handler returns a 2xx response.
delete() — Called when the handler throws or returns non-2xx. Allows the client to retry with the same key.

Why it matters

Consider a booking endpoint where the handler runs a single-statement conditional INSERT that returns 0 rows when a slot has just been taken by someone else, and the route answers 409. The request was well-formed; the 409 is the final answer for that key. With the current behaviour:

1. Client A sends POST /bookings with key K, loses the race, gets 409. The record for K is deleted.
2. A's connection times out before the 409 arrives, so A retries with K.
3. lock() succeeds (K no longer exists), the handler runs the guard again, and — if the slot has since freed up — A now holds a booking it believes failed.

The middleware's own README frames the goal as "the same request produces the same result", and this is the one path where it does not.

I want to be clear that this is a design choice, not a bug: treating 4xx/5xx as "client, please fix and retry" is the common convention and the right default. The ask is narrower.

Proposal

An option — name is bikesheddable — that tells the middleware which non-2xx statuses are terminal for a key:

idempotency({
  store,
  // Persist and replay these statuses instead of deleting the key.
  persistStatuses: [409, 422],
})

or a predicate, persistResponse: (res: Response) => boolean, which generalises the same thing.

Semantics I would expect:

• Statuses in the list go through complete() exactly like a 2xx, and are replayed on the next request with the same key and fingerprint.
• Statuses not in the list keep today's behaviour (delete()).
• Default stays [], so nothing changes for existing users.

Alternatives I considered

• Handle it in the route: return the 409 as a 200 { ok: false } envelope. This works but forces a non-RESTful response shape onto every consumer just to satisfy the middleware, and it is what I would like to avoid.
• A custom store that ignores delete(): this breaks the "throw → delete → allow retry" path that should stay retriable, so it is not a clean workaround.

Happy to send a PR if the direction is acceptable. Thanks for the library — the d1Store INSERT OR IGNORE lock is exactly the primitive I needed.

[paveg]

Analysis

Surveyed all five paveg middleware repos for an open, unblocked, mechanical issue. hono-cf-access and hono-dpop have zero open issues. hono-webhook-verify has one open issue (#163), already linked to an open PR (#164) — out of scope. hono-problem-details has three open issues: #177 and #103 each already carry an unanswered analysis comment from a prior run, so both are out of scope per policy; #185 is a new, undecided API-design proposal (JSON-Schema-vs-Standard-Schema OpenAPI helpers) with no clear winner yet either.

That leaves this issue and #185 as the two "fresh" candidates, and this one is more valuable to resolve first: #185 is developer ergonomics for a stack combination (Valibot + hono-openapi) nobody has hit yet, while #178 describes a real correctness gap — a retried request can silently succeed after the client already observed the terminal failure for that key. So I picked this one, but it isn't mechanical either: it's an API-design decision (option name and shape), not a defined bug fix, so per policy I'm posting analysis instead of code.

Where the change would land

src/middleware.ts, right after next() resolves:

const res = c.res;
if (!res.ok) {
	// Non-2xx: delete key (Stripe pattern) so client can retry
	await store.delete(storeKey);
	return;
}

No store-interface change is needed — IdempotencyStore.complete(key, response: StoredResponse) already accepts any status; only its doc comment ("Called after the handler returns a 2xx response") would need updating. The gate is purely in middleware.ts: decide whether to call complete() or delete() for a given non-2xx res.

Options

1. persistStatuses: number[] — allowlist of exact status codes to persist ([409, 422]). Simplest surface, directly matches the issue's primary example, trivially serializable/testable.
2. persistResponse: (res: Response) => boolean — general predicate over the full Response (status, headers, even a cloned body). Covers cases persistStatuses can't (e.g. "persist 409 only when X-Conflict-Reason: slot-taken"), at the cost of callers needing to clone the body if they want to inspect it, and of being harder to reason about (a careless predicate that reads res.body would consume it before the middleware does).
3. Both, persistStatuses as the ergonomic default path and persistResponse as the escape hatch (mirrors the errorKey/formatErrors precedent already recommended in hono-problem-details#103) — persistResponse, if provided, wins over persistStatuses.
4. Do nothing — document the "wrap 409 as 200 { ok: false }" workaround in the README and close as won't-fix. The issue author already considered and rejected this (forces a non-RESTful shape onto every consumer).

Recommendation

Option 1 (persistStatuses: number[]) alone, default [] (today's behavior, byte-for-byte unchanged). Reasoning:

• It matches every example in the issue and the concrete failure scenario (booking 409) without needing body/header inspection.
• A predicate option is easy to add later in a non-breaking way if a real need for it shows up; shipping it speculatively now adds an API surface (and a body-consumption footgun) with no known caller.
• persistResponse name matches the issue's own alternative naming, so if a predicate is wanted this — not persistCondition or similar — is the name to use for consistency with existing terminology in this thread.

Decision needed before implementation

1. Confirm persistStatuses: number[], default [], is the right first cut — vs. shipping the predicate (persistResponse) from the start because it's known to be needed soon.
2. Confirm precedence/behavior when a status in persistStatuses is hit: goes through complete() exactly like 2xx (replayed verbatim on retry, including the same status code) — same as the issue's proposal.
3. Confirm this ships as a minor with a changeset (non-breaking, opt-in) per the repo's semver conventions.

Once confirmed, implementation is small and test-first per CLAUDE.md: a new test in the middleware suite asserting a persistStatuses-listed status is replayed via Idempotency-Replayed: true on retry (mirroring the existing 2xx replay test), and one asserting non-listed non-2xx statuses keep today's delete-and-retry behavior.

---

Generated by Claude Code