Documentation
¶
Overview ¶
Package postgres is the PostgreSQL store of vogel/idempotency, on the idempotency_key table of vogel/idempotency/migrations.
Index ¶
- Constants
- type Option
- type Store
- func (s *Store) Complete(ctx context.Context, db pgxtx.DBTX, req idempotency.Request, token uuid.UUID, ...) error
- func (s *Store) DeleteExpired(ctx context.Context, db pgxtx.DBTX, limit int) (int64, error)
- func (s *Store) Do(ctx context.Context, tx pgx.Tx, req idempotency.Request, ...) (idempotency.Response, bool, error)
- func (s *Store) Release(ctx context.Context, db pgxtx.DBTX, req idempotency.Request, token uuid.UUID) error
- func (s *Store) Reserve(ctx context.Context, db pgxtx.DBTX, req idempotency.Request, ...) (idempotency.Reservation, error)
Constants ¶
const DefaultTTL = 24 * time.Hour
DefaultTTL is how long a key protects against a retry unless WithTTL sets another duration.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Store ¶
type Store struct {
// contains filtered or unexported fields
}
Store claims idempotency keys and stores the responses of the operations they protect.
func (*Store) Complete ¶
func (s *Store) Complete(ctx context.Context, db pgxtx.DBTX, req idempotency.Request, token uuid.UUID, resp idempotency.Response) error
Complete stores resp as the response of req's key, held by the reservation token. It fails when the reservation is no longer this request's: its lease lapsed and another request took the key over, or the row expired and was reclaimed.
func (*Store) DeleteExpired ¶
DeleteExpired deletes at most limit expired rows (oldest expiry first) and returns how many it deleted. A limit <= 0 means 1000. A periodic job of the consumer calls it until it returns fewer than limit; keeping each call bounded keeps it from holding locks on a large table.
func (*Store) Do ¶
func (s *Store) Do(ctx context.Context, tx pgx.Tx, req idempotency.Request, fn func(context.Context) (idempotency.Response, error)) (idempotency.Response, bool, error)
Do runs fn exactly once per key, inside tx.
It claims (req.Scope, req.Key) in tx. When the key is new, or its earlier claim expired, it runs fn — which must do its writes on the same tx — and stores fn's Response in tx too, so the key, the mutation and the response commit or roll back together: an error from fn, or a rollback by the caller, leaves no trace of the key. It then returns fn's Response with replayed false; an error from fn is returned as is.
When the key is already claimed by a committed transaction, Do does not call fn. It returns the stored Response with replayed true when the fingerprint matches and the response is stored, ErrKeyReused when the fingerprint differs, and ErrInProgress when the key is held by an in-progress reservation of the HTTP middleware. A duplicate running while the first transaction is still open waits for it, then replays (commit) or runs fn (rollback).
An invalid req fails with ErrInvalidRequest before touching tx.
func (*Store) Release ¶
func (s *Store) Release(ctx context.Context, db pgxtx.DBTX, req idempotency.Request, token uuid.UUID) error
Release deletes req's in-progress reservation held by token, so a retry runs the operation again. It is a no-op when the reservation is no longer this request's.
func (*Store) Reserve ¶
func (s *Store) Reserve(ctx context.Context, db pgxtx.DBTX, req idempotency.Request, lease time.Duration) (idempotency.Reservation, error)
Reserve claims req's key for lease, outside any transaction of the operation: the HTTP middleware's path. The returned Reservation has Token set when this request now holds the key (new, expired, or a lapsed lease of the same request) and must run its operation, then call Complete or Release with that token; it has Replay set when the operation already finished. A key held by a live lease fails with ErrInProgress, a key claimed with another fingerprint with ErrKeyReused, an invalid req with ErrInvalidRequest. A lease <= 0 is rejected as ErrInvalidRequest: it must outlast the operation, or a retry would run it again concurrently.