# Idempotent API requests ## What this builds A way for the clients of an API to retry a request without doing the work twice. The client sends a key of its own choosing with a request. If the same request comes again with the same key, the API answers what it answered the first time and does nothing more. A dropped connection can then be retried without fear of a second charge, a second order or a second email. Read `spekkr.inputs.json` first. A key is remembered for `key_hours` hours. `store` says where keys are kept. `require_key` decides whether R8 exists. This spec sits in front of an API's routes. It needs the API to know who is calling, by an API key or a signed-in user. ## Out of scope - Making the handlers themselves safe to run twice. This keeps them from being run twice. - Retrying on the client's side. ## Requirements Each requirement has an id. Tests name the id they cover. ### R1. The header - A client sends `Idempotency-Key` with a `POST` or a `PATCH`. The value is 1 to 255 printable ASCII characters. Anything else gets status 400. - On `GET`, `HEAD`, `PUT` and `DELETE` the header is ignored: repeating those is already safe. - A key belongs to the caller who sent it. Two callers who pick the same key never meet. Accept when: an empty key, a key of 256 characters and a key with a line break each get 400, and the same key from two callers runs the handler twice. ### R2. The first request - Before the handler runs, the key is recorded as in progress, together with the request's fingerprint from `design.md`. Recording is one step, so two requests cannot both be first. - The handler runs. Its status, its body and the headers named in `design.md` are stored, and the key is marked done. Accept when: the fingerprint test vectors in `design.md` are reproduced, and after a first request the store holds the answer. ### R3. The same request again - A request with a key that is done and the same fingerprint gets the stored status, headers and body, plus the header `Idempotent-Replayed: true`. - The handler does not run. Accept when: the second answer equals the first byte for byte, and a counter in the handler shows it ran once. ### R4. The same key for something else - A request with a known key and a different fingerprint gets status 422 with the code `idempotency_key_reused`. The handler does not run and the stored answer stays. Accept when: changing one byte of the body under the same key gets 422. ### R5. Two at once - A request whose key is in progress gets status 409 with the code `request_in_progress` and `Retry-After: 1`. It does not wait. - Of 20 requests sent at the same moment with one key, one runs the handler. The others get 409 or, if they arrive after it finished, the stored answer. Accept when: the test with 20 requests shows the handler ran once and every answer is either the real one, a replay of it, or 409. ### R6. What is kept - An answer with a status from 200 to 499 is stored and replayed. That includes a refusal: retrying a request that was invalid gets the same refusal. - An answer of 500 or above is not stored. The key is released, so a retry runs the handler again. - If the process dies while a key is in progress, the key is released 60 seconds after it was recorded. - If `store` is `database`, the answer is saved in the same transaction as the handler's own changes. Either both are saved or neither is. Accept when: a handler that fails with 500 runs again on retry, a key abandoned in progress can be used after 60 seconds, and with `store` set to `database` a handler whose transaction rolls back leaves no stored answer. ### R7. Forgetting - A key is forgotten `key_hours` hours after it was first used. The same key after that is a new request. - The stored body is at most 1 MB (1,000,000 bytes). A larger answer is sent to the client but not stored, and the key is kept as done with a note; a retry gets status 409 with the code `answer_not_kept`. Accept when: a key works as new one second after it expires, and not one second before. ### R8. Keys required Only if `require_key` is on. - A `POST` without the header gets status 400 with the code `idempotency_key_missing`. Routes can be marked as exempt. Accept when: a `POST` without a key is refused and an exempt route is not. ## Definition of done - Every acceptance check above has an automated test, and all tests pass. Tests set the clock; none of them sleeps. - A README explains how to put this in front of a route, what a client should send and when to retry, and how to run the tests.