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.
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
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.
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