idempotency

package
v0.23.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 3, 2026 License: MIT Imports: 5 Imported by: 0

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

View Source
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

View Source
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

func Fingerprint(parts ...[]byte) []byte

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.

func (Request) Validate

func (r Request) Validate() error

Validate reports whether r can be claimed, wrapping ErrInvalidRequest.

type Reservation

type Reservation struct {
	Token  uuid.UUID
	Replay *Response
}

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.

type Response

type Response struct {
	Status int
	Header map[string][]string
	Body   []byte
}

Response is what an idempotent operation produced: stored once and returned to every retry. Store.Do callers outside HTTP may leave Status zero and Header nil and carry their result in Body.

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.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL