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 ¶
- Variables
- func Do[R any](ctx context.Context, i *Idempotency, key any, ...) (R, error)
- func Handler[T, R any](i *Idempotency, h func(context.Context, T) (R, error), ...) func(context.Context, T) (R, error)
- type AlreadyExistsError
- type HandlerOption
- type Idempotency
- type MemoryStore
- type Option
- type Record
- type Status
- type Store
Examples ¶
Constants ¶
This section is empty.
Variables ¶
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.
type Option ¶
type Option func(*Idempotency)
Option configures an Idempotency.
func WithExpiry ¶
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 ¶
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 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. |