# Design This file fixes the parts that are easy to get wrong. Choose the language and framework that fit the person's project; nothing here depends on them. ## The fingerprint The fingerprint says whether two requests are the same request. ``` text = method, a line feed, path with its query string, a line feed, body fingerprint = SHA-256 of text as bytes, in hexadecimal ``` The body is the raw bytes as they arrived, before any parsing. Two bodies that mean the same but are written differently are different requests. | Method | Path | Body | Fingerprint | | --- | --- | --- | --- | | `POST` | `/v1/charges` | `{"amount":1200,"currency":"USD","customer":"cus_42"}` | `4d0c10fdb00e06797b77e271a15858439b230c77bd8aa1ff6150b0fcfc60f7e3` | | `POST` | `/v1/charges` | `{"amount":1300,"currency":"USD","customer":"cus_42"}` | `907eed6f8a1eef9697f4da4e0c8a647d4e41071915d4070c9da1cefeee44370d` | ## What is stored | Field | Holds | | --- | --- | | `scope` | The caller: an API key's id or a user's id | | `key` | The header's value | | `fingerprint` | As above | | `state` | `in_progress` or `done` | | `status`, `headers`, `body` | The answer, once done | | `locked_until` | 60 seconds after the key was recorded | | `expires_at` | `key_hours` hours after the key was recorded | The primary key is `scope` and `key` together. Of the headers, store `Content-Type` and `Location` and nothing else: the rest belong to one moment. ## One request, step by step 1. Not a `POST` or `PATCH`, or no header: pass the request on. 2. Check the header's value. Work out the scope and the fingerprint. 3. Try to record the key as `in_progress`. This must be one step that fails if the key is there: | `store` | The one step | | --- | --- | | `database` | An `INSERT` that does nothing on conflict, then a check of whether a row was written | | `redis` | `SET` with `NX` and an expiry | 4. If it was recorded, run the handler, then store the answer or release the key as R6 says. 5. If the key was already there, read it: | What is there | Answer | | --- | --- | | Expired | Delete it and go back to step 3 | | Different fingerprint | 422 `idempotency_key_reused` | | `done` | The stored answer, with `Idempotent-Replayed: true` | | `in_progress`, `locked_until` passed | Take the key over with one conditional update, then step 4 | | `in_progress` | 409 `request_in_progress` | With `store` set to `database`, run steps 3 and 4 so that marking the key `done` commits together with the handler's changes: the handler uses the same transaction, or a savepoint inside it. ## Errors ```json { "error": { "code": "idempotency_key_reused", "message": "This key was used for a different request." } } ``` ## Configuration | Secret | Purpose | | --- | --- | | `DATABASE_URL` | Connection string, when `store` is `database`. | | `REDIS_URL` | Connection string, when `store` is `redis`. | ## Named here - The app says who is calling through one function, `caller(request)`. A request with no caller gets 401 with the code `unauthenticated`. - A key that breaks the rules for a key gets 400 with the code `idempotency_key_invalid`. - The method is in capitals in the fingerprint. - The row that marks a key as in progress is committed on its own, before the handler runs, so that a second request sees it at once. Marking it done commits with the handler's changes. - The note in R7 is a `note` column, and holds `answer_not_kept`. ## What this spec leaves to you Where this spec names something, use that name, so that two builds of it agree. Where it does not, the choice is yours. List what you chose in the README.