Documentation
¶
Overview ¶
Package idempotency makes a mutation safe to retry: a caller sends a key with the request, and a retry with the same key gets the first attempt's response back instead of running the mutation again.
It comes in two layers that share one store (idempotency/postgres) and one table (idempotency/migrations):
- Store.Do runs inside the mutation's own transaction. The key, the mutation and its stored response commit or roll back together, so the mutation runs exactly once per key. Services adopt it explicitly.
- The HTTP middleware (idempotency/httpx) wraps any handler. It reserves the key with a lease, runs the handler and stores the response in separate statements: if the process dies after the handler committed but before the response was stored, a retry after the lease runs the handler again. Routes that cannot afford that use Store.Do.
A key is scoped (Request.Scope): the same key from another caller, or for another operation, is a different key. A key reused with different request content (Request.Fingerprint) is rejected with ErrKeyReused rather than answered with the response of another request.
Index ¶
Constants ¶
const MaxKeyLength = 255
MaxKeyLength bounds Request.Key. Keys are opaque client strings (a UUID is the usual choice); the bound keeps a hostile client from storing large values in the key column.
Variables ¶
var ( // ErrInvalidRequest reports a Request the store cannot claim: an empty // scope, an empty key or one longer than MaxKeyLength, a key with a // character outside printable ASCII, or an empty fingerprint. ErrInvalidRequest = errors.New("idempotency: invalid request") // ErrKeyReused reports a key already claimed, in the same scope, by a // request with another fingerprint. ErrKeyReused = errors.New("idempotency: key reused with a different request") // ErrInProgress reports a key whose first request is still running. ErrInProgress = errors.New("idempotency: request with this key is still in progress") )
Functions ¶
func Fingerprint ¶
Fingerprint returns the SHA-256 of parts, each length-prefixed so that ("ab", "c") and ("a", "bc") never collide.
Types ¶
type Request ¶
type Request struct {
// Scope names whose operation it is and which one, so keys never collide
// across callers or operations (the HTTP middleware uses the principal,
// the method and the route).
Scope string
// Key is the client's idempotency key.
Key string
// Fingerprint identifies the request content (see Fingerprint): a retry
// must send the same content with the same key.
Fingerprint []byte
}
Request identifies one idempotent operation.
type Reservation ¶
Reservation is the outcome of reserving a key outside a transaction (the HTTP middleware's path; see idempotency/postgres.Store.Reserve). Exactly one field is set: Token when this request now holds the key and must run its operation, then complete or release the reservation with that token; Replay when the key's operation already finished, holding its stored response.
Directories
¶
| Path | Synopsis |
|---|---|
|
Package httpx is the HTTP layer of vogel/idempotency: a middleware that makes any mutating handler safe to retry with an Idempotency-Key header.
|
Package httpx is the HTTP layer of vogel/idempotency: a middleware that makes any mutating handler safe to retry with an Idempotency-Key header. |
|
Package migrations embeds the SQL migration(s) that create the idempotency_key table vogel/idempotency/postgres uses: one row per (scope, key) an idempotent operation claimed, holding the request's fingerprint and, once the operation finished, the response it produced.
|
Package migrations embeds the SQL migration(s) that create the idempotency_key table vogel/idempotency/postgres uses: one row per (scope, key) an idempotent operation claimed, holding the request's fingerprint and, once the operation finished, the response it produced. |
|
Package postgres is the PostgreSQL store of vogel/idempotency, on the idempotency_key table of vogel/idempotency/migrations.
|
Package postgres is the PostgreSQL store of vogel/idempotency, on the idempotency_key table of vogel/idempotency/migrations. |