Documentation
¶
Overview ¶
Package idempotent standardizes HTTP contracts for idempotent API workflows.
The package is stable core API. It does not store idempotency keys or replay responses; middleware/idempotency or application code owns reservation, persistence, locking, TTLs, and response replay. idempotent provides the shared HTTP pieces that handlers, route contracts, and tests can agree on.
Start with RequireKey to extract the Idempotency-Key header and RequestHash to compare method, target, and body bytes. Use ConflictProblem, ReplayProblem, WriteConflict, WriteAcceptedReplay, and OperationExtensions to keep conflict, replay, accepted-operation, and OpenAPI behavior consistent across create, update, patch, and asynchronous workflows.
Keep keys scoped to tenant and principal in storage, reject reused keys with mismatched hashes, and avoid using this package alone as a replay store. For examples, see docs/cookbook.md.
Purpose: See the package summary above. Import: `github.com/aatuh/api-toolkit/v4/idempotent`. Example: See docs/api-reference.md for package example links and docs/cookbook.md for task recipes. Errors: Constructors, parsers, and handlers return or write documented errors according to their signatures; packages with plain data types do not add hidden error channels. Concurrency: Treat configured middleware and helpers as immutable after construction; request and response values remain request-scoped unless a type documents stronger guarantees. Stability: Stable core API under VERSIONING.md and scripts/apicheck.sh. When not to use: Prefer net/http, application-owned types, or narrower helpers when this package contract is not needed.
Index ¶
- func ConflictProblem(detail string) httpx.Problem
- func OperationExtensions(required bool) map[string]any
- func ReplayProblem(detail string) httpx.Problem
- func RequestHash(r *http.Request, body []byte) string
- func RequireKey(r *http.Request, headerName string) (string, error)
- func WriteAcceptedReplay(w http.ResponseWriter, config AsyncConfig)
- func WriteConflict(w http.ResponseWriter, detail string)
- type AsyncConfig
- type CreateConfig
- type UpdateConfig
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func ConflictProblem ¶
ConflictProblem returns the standard idempotency conflict problem.
func OperationExtensions ¶
OperationExtensions returns OpenAPI extensions for idempotent operation contracts.
func ReplayProblem ¶
ReplayProblem returns the standard idempotency replay problem.
func RequestHash ¶
RequestHash returns a deterministic SHA-256 hash for method, target, and body bytes.
func RequireKey ¶
RequireKey extracts a required idempotency key from the request.
Example ¶
package main
import (
"context"
"fmt"
"net/http"
"net/http/httptest"
"github.com/aatuh/api-toolkit/v4/idempotent"
)
func main() {
req := httptest.NewRequestWithContext(context.Background(), http.MethodPost, "/charges", nil)
req.Header.Set("Idempotency-Key", "charge-123")
key, err := idempotent.RequireKey(req, "Idempotency-Key")
if err != nil {
panic(err)
}
fmt.Println(key)
}
Output: charge-123
func WriteAcceptedReplay ¶
func WriteAcceptedReplay(w http.ResponseWriter, config AsyncConfig)
WriteAcceptedReplay writes a replayed 202 Accepted operation response.
func WriteConflict ¶
func WriteConflict(w http.ResponseWriter, detail string)
WriteConflict writes a 409 idempotency conflict Problem Details response.
Types ¶
type AsyncConfig ¶
AsyncConfig describes an idempotent async replay response.
type CreateConfig ¶
CreateConfig describes idempotency requirements for create workflows.
type UpdateConfig ¶
UpdateConfig describes idempotency requirements for update workflows.
Source Files