idempotency

package
v0.1.0 Latest Latest
Warning

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

Go to latest
Published: Nov 21, 2026 License: MIT Imports: 11 Imported by: 0

Documentation

Overview

Package idempotency makes AWS Lambda handlers, and other functions, safe to retry.

The first call for a key runs the function and saves its JSON-encoded result. Later calls with the same key, until the record expires, return the saved result without running the function. A call that arrives while the first one is still running gets ErrInProgress. When the function returns an error, the record is deleted so a retry can run it again.

Records live in a Store. Use NewMemoryStore for tests and the dynamodbstore subpackage in production.

Index

Examples

Constants

This section is empty.

Variables

View Source
var (
	// ErrInProgress is returned when another invocation with the same key is
	// still running.
	ErrInProgress = errors.New("idempotency: invocation already in progress")

	// ErrPayloadMismatch is returned when a request reuses a key with a
	// different payload than the one saved, when payload validation is on.
	ErrPayloadMismatch = errors.New("idempotency: payload does not match saved record")

	// ErrMissingKey is returned when the key data is empty: JSON null, "",
	// {} or [].
	ErrMissingKey = errors.New("idempotency: key data is empty")

	// ErrResponseNotSaved is returned, together with the result, when the
	// function succeeded but its response could not be saved. The side effect
	// has happened. Returning this error to Lambda makes it retry, and the
	// retry runs the function again once the in-progress record expires; a
	// caller that prefers no retry can check for it and return a nil error.
	ErrResponseNotSaved = errors.New("idempotency: function succeeded but its response was not saved")

	// ErrNotOwner is returned by [Store.Update] and [Store.Delete] when the
	// record belongs to another invocation.
	ErrNotOwner = errors.New("idempotency: record is owned by another invocation")
)

Functions

func Do

func Do[R any](
	ctx context.Context,
	i *Idempotency,
	key any,
	fn func(context.Context) (R, error),
) (R, error)

Do runs fn at most once per key until the record expires. key is JSON-encoded and hashed. Repeated calls return the saved result.

The result type R must survive a JSON round trip: unexported fields are not saved.

Example
package main

import (
	"context"
	"fmt"

	"github.com/nixmaldonado/lambda-kit-go/idempotency"
)

func main() {
	idem := idempotency.New(idempotency.NewMemoryStore(), idempotency.WithKeyPrefix("send-email"))
	ctx := context.Background()

	for range 2 {
		id, _ := idempotency.Do(ctx, idem, "welcome:user-7", func(context.Context) (string, error) {
			fmt.Println("sending")

			return "msg-123", nil
		})
		fmt.Println(id)
	}
}
Output:
sending
msg-123
msg-123

func Handler

func Handler[T, R any](
	i *Idempotency,
	h func(context.Context, T) (R, error),
	opts ...HandlerOption[T],
) func(context.Context, T) (R, error)

Handler wraps a Lambda handler so that repeated events return the saved response instead of running h again.

Use KeyFrom with AWS event types. Without it the whole event is the key, and API Gateway, SQS and EventBridge events carry fields that change on every delivery (request ID, receipt handle, receive count, timestamps), so a retried event never matches and the handler runs again.

If h succeeds but its response cannot be saved, the wrapper returns the result together with an error matching ErrResponseNotSaved. Passing that error to Lambda causes a retry; check for it to decide otherwise.

The response type R must survive a JSON round trip: unexported fields are not saved.

Example
package main

import (
	"context"
	"fmt"

	"github.com/nixmaldonado/lambda-kit-go/idempotency"
)

type Order struct {
	ID     string `json:"id"`
	Amount int    `json:"amount"`
}

type Receipt struct {
	OrderID string `json:"orderId"`
	Charged int    `json:"charged"`
}

func main() {
	// In production, use dynamodbstore.New instead.
	idem := idempotency.New(idempotency.NewMemoryStore())

	charge := func(_ context.Context, o Order) (Receipt, error) {
		fmt.Println("charging", o.ID)

		return Receipt{OrderID: o.ID, Charged: o.Amount}, nil
	}

	handler := idempotency.Handler(
		idem,
		charge,
		idempotency.KeyFrom(func(o Order) any { return o.ID }),
	)
	// In main: lambda.Start(handler)

	ctx := context.Background()
	first, _ := handler(ctx, Order{ID: "o-1", Amount: 42})
	second, _ := handler(ctx, Order{ID: "o-1", Amount: 42}) // replayed, not charged again

	fmt.Println(first == second)
}
Output:
charging o-1
true

Types

type AlreadyExistsError

type AlreadyExistsError struct {
	Record Record
}

AlreadyExistsError is returned by Store.Create when a live record exists.

func (*AlreadyExistsError) Error

func (e *AlreadyExistsError) Error() string

type HandlerOption

type HandlerOption[T any] func(*handlerConfig[T])

HandlerOption configures Handler.

func KeyFrom

func KeyFrom[T any](fn func(event T) any) HandlerOption[T]

KeyFrom selects the part of the event that identifies a request, such as an order ID or an Idempotency-Key header. The value is JSON-encoded and hashed. Without KeyFrom, the whole event is the key; see Handler for why that is rarely what you want.

func ValidateWith

func ValidateWith[T any](fn func(event T) any) HandlerOption[T]

ValidateWith selects the part of the event that must match on repeated requests. A request that reuses a key with a different payload gets ErrPayloadMismatch instead of the saved response.

type Idempotency

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

Idempotency holds the settings shared by Handler and Do. Use a separate Idempotency, or a different WithKeyPrefix, for each operation that should have its own keys.

func New

func New(store Store, opts ...Option) *Idempotency

New returns an Idempotency that saves records in store. It panics if store is nil.

type MemoryStore

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

MemoryStore is a Store that keeps records in process memory. It is meant for tests and local runs: records are lost when the process exits and are not shared between Lambda execution environments.

func NewMemoryStore

func NewMemoryStore() *MemoryStore

NewMemoryStore returns an empty MemoryStore.

func (*MemoryStore) Create

func (s *MemoryStore) Create(_ context.Context, r Record, now time.Time) error

Create implements Store.

func (*MemoryStore) Delete

func (s *MemoryStore) Delete(_ context.Context, r Record) error

Delete implements Store.

func (*MemoryStore) Update

func (s *MemoryStore) Update(_ context.Context, r Record) error

Update implements Store.

type Option

type Option func(*Idempotency)

Option configures an Idempotency.

func WithExpiry

func WithExpiry(d time.Duration) Option

WithExpiry sets how long a completed record protects its key. The default is one hour. It panics if d is not positive, since a zero expiry would silently disable idempotency.

func WithKeyPrefix

func WithKeyPrefix(prefix string) Option

WithKeyPrefix sets the namespace prepended to every key. The default is the AWS_LAMBDA_FUNCTION_NAME environment variable, or "lambda-kit" outside Lambda.

type Record

type Record struct {
	// Key is the idempotency key: the key prefix plus a hash of the key data.
	Key string
	// Status is the state of the invocation.
	Status Status
	// ExpiresAt is when the record stops protecting the key.
	ExpiresAt time.Time
	// InProgressExpiresAt is when an in-progress record is considered
	// abandoned (for example, after a Lambda timeout) and may be taken over.
	// Zero for completed records.
	InProgressExpiresAt time.Time
	// Response is the JSON-encoded result of a completed invocation.
	Response []byte
	// PayloadHash is the hash of the validated payload, or empty when payload
	// validation is not configured.
	PayloadHash string
	// Token identifies the invocation that created the record. Update and
	// Delete only act on a record whose token matches, so a slow invocation
	// cannot clobber the record of one that took over its key.
	Token string
}

Record is what a Store persists for one idempotency key.

type Status

type Status string

Status is the state of an idempotency record.

const (
	// StatusInProgress means an invocation is currently running for the key.
	StatusInProgress Status = "INPROGRESS"
	// StatusCompleted means an invocation finished and its response is saved.
	StatusCompleted Status = "COMPLETED"
)

type Store

type Store interface {
	// Create saves r unless a live record with the same key already exists.
	//
	// A record is live when now is before its ExpiresAt and, for an
	// in-progress record, before its InProgressExpiresAt. Expired and
	// abandoned records must be overwritten.
	//
	// The check and the write must be atomic. When a live record exists,
	// Create returns an *[AlreadyExistsError] holding that record.
	Create(ctx context.Context, r Record, now time.Time) error

	// Update overwrites the record with r.Key, but only if the stored record
	// has the same Token. Otherwise, including when no record exists, it
	// returns [ErrNotOwner].
	Update(ctx context.Context, r Record) error

	// Delete removes the record with r.Key, but only if the stored record has
	// the same Token. Deleting a missing record is not an error; a record with
	// another token returns [ErrNotOwner].
	Delete(ctx context.Context, r Record) error
}

Store persists idempotency records. Implementations must be safe for concurrent use.

Directories

Path Synopsis
Package dynamodbstore implements idempotency.Store on Amazon DynamoDB.
Package dynamodbstore implements idempotency.Store on Amazon DynamoDB.

Jump to

Keyboard shortcuts

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