postgres

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: 10 Imported by: 0

Documentation

Overview

Package postgres is the PostgreSQL store of vogel/idempotency, on the idempotency_key table of vogel/idempotency/migrations.

Index

Constants

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

type Option func(*Store)

Option configures a Store.

func WithTTL

func WithTTL(d time.Duration) Option

WithTTL sets how long a claimed key protects against a retry. A d <= 0 keeps DefaultTTL.

type Store

type Store struct {
	// contains filtered or unexported fields
}

Store claims idempotency keys and stores the responses of the operations they protect.

func NewStore

func NewStore(opts ...Option) *Store

NewStore creates a Store.

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

func (s *Store) DeleteExpired(ctx context.Context, db pgxtx.DBTX, limit int) (int64, error)

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

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

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.

Jump to

Keyboard shortcuts

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