idempotency
Idempotency-Key store for mutating HTTP APIs, backed by std.sql. Stripe-style create-refund semantics: double-clicks do not double-pay.
ecko get github.com/ecko-lang/idempotency
import idempotency
Pure computation: it declares no capabilities, so it cannot touch the network, the filesystem or the environment.
Version 0.6.0 - source - MIT.
init(db)
Creates the idempotency_keys table if it does not already exist, and returns null. db is a std.sql connection the caller owns; call this once after opening it, before the first run.
errors: sql when the table cannot be created.
idempotency.init(db)
run(db, key, request_fingerprint, action, ttl_seconds = 86400, lock_ms = 60000, now = null)
Runs action() once per key and returns its result; a repeat call with the same key and the same request_fingerprint returns the stored result without calling action again.
A later call with the same key and a different fingerprint is refused (mismatch): the caller reused a key for a different request. A call that arrives while an earlier call for the key is still running is refused (in_progress) rather than running action a second time. If that earlier call died without finishing - the process crashed mid-action - its claim is taken over once it is lock_ms old, and action runs again; set lock_ms above the longest an action can take.
If action throws, the key is released before the error is re-thrown, so a retry with the same key runs action again; failures are not stored. The result must be plain data that JSON gives back unchanged (null, bools, ints, floats, strings, and lists and maps of those). Anything else is refused after action has run, and the key is spent: that call and every later one with the key throw not_storable and action never runs twice.
ttl_seconds is how long a key is remembered (0 never expires); now is a zero-argument function returning Unix ms, default time.now - inject a stepped clock to test expiry.
errors: idempotency/mismatch, idempotency/in_progress or idempotency/not_storable as above; bug/bad_argument for a key or fingerprint that is not a non-empty string, an action that is not a function, or a bad option; sql when the store fails; whatever action throws.
fp = idempotency.fingerprint("POST", "/v1/refunds", { amount: 500 })
result = idempotency.run(db, "refund-42", fp, fn() charge_refund(42))
fingerprint(method, path, body)
A sha256 hex digest identifying a request, for run's request_fingerprint.
body is JSON-encoded before hashing, so a map, a list, a string, bytes or null all work. Two calls with the same method, path and body produce the same digest; run uses this to tell a legitimate replay from a caller reusing a key for a different request.
errors: bug when method or path is not a string, or body holds a value JSON cannot encode (a function).
idempotency.fingerprint("POST", "/v1/refunds", { amount: 500 })
middleware(db, ttl_seconds = 86400, lock_ms = 60000, now = null)
A fn(req, next) for web.router's middleware list that applies run to requests carrying an Idempotency-Key header.
For POST/PATCH/DELETE requests with the header, it wraps next(req) with run, fingerprinting the method, path and body: a repeat request with the same key and the same request replays the stored response instead of calling next again. Requests with no key or an empty one, and GET/PUT/HEAD requests, pass straight through to next. ttl_seconds, lock_ms and now are passed to run.
The response must be plain data for replay to work - an http.json(...) or http.text(...) response qualifies; one with a bytes body or a stream is refused with not_storable, which a server turns into a 500.
errors: bug/bad_argument for a bad option, when the middleware is built; each request can throw what run throws (mismatch, in_progress, not_storable), which a server answers with a 500.
app = web.router(routes, [idempotency.middleware(db, ttl_seconds: 3600)])