From 2b3eef2059382c62d565863a6c9364ad41cc3ae2 Mon Sep 17 00:00:00 2001 From: Nikola-Tee Date: Fri, 28 Aug 2026 20:14:25 +0100 Subject: [PATCH] docs: add idempotency key entry to glossary MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Add an API Terms section to docs/glossary.md documenting the idempotency key feature, its {endpoint}:{invoice_id}:{key} scoping convention, and TTL-based eviction in the Rust/Axum backend. Closes #475 🤖 Generated with Codebuff Co-Authored-By: Codebuff --- docs/glossary.md | 26 ++++++++++++++++++++++++++ 1 file changed, 26 insertions(+) diff --git a/docs/glossary.md b/docs/glossary.md index 72aebd8..0b55975 100644 --- a/docs/glossary.md +++ b/docs/glossary.md @@ -152,6 +152,32 @@ See _Token Allowlist_ under Settlement Terms. --- +## API Terms + +**Idempotency Key** +A client-supplied token that ensures a request is processed at most once. +The key is passed in the `Idempotency-Key` header. The backend stores the +response against a namespaced key and returns the cached result on +subsequent requests with the same idempotency key, preventing duplicate +side-effects from retries or network glitches. + +**Idempotency Key Scoping** +Keys are scoped as `{endpoint}:{invoice_id}:{idempotency_key}`. This means +the same `Idempotency-Key` header value used on two different endpoints +(or for two different invoice IDs) never collides. Each (endpoint, invoice, +key) triple is an independent entry in the idempotency store. + +**Idempotency TTL** +Cached idempotency entries expire after a configurable time-to-live (default: +24 hours in production). Expired entries are evicted both lazily on lookup +and periodically by a background sweeper, so memory usage stays bounded. + +> **Source:** `backend/src/idempotency.rs` (Rust/Axum backend). +> The TypeScript backend (`comebackhere-backend`) does not currently +> implement idempotency keys. + +--- + ## Cross-Contract Workflow Summary ```