Idempotency

Documentation Index

Fetch the complete documentation index at: https://docs.go-mizu.dev/llms.txt

Use this file to discover all available pages before exploring further.

​

Overview

• Safe payment processing retries
• Duplicate request prevention
• Reliable webhook handling

​

Installation

import "github.com/go-mizu/mizu/middlewares/idempotency"

​

Quick Start

app := mizu.New()

// Enable idempotency
app.Use(idempotency.New())

app.Post("/payments", func(c *mizu.Ctx) error {
    // This will only execute once per idempotency key
    result := processPayment()
    return c.JSON(200, result)
})

POST /payments
Idempotency-Key: unique-key-123

​

Configuration

​

Options

​

Examples

​

Basic Usage

app.Use(idempotency.New())

​

Custom Header

app.Use(idempotency.WithOptions(idempotency.Options{
    KeyHeader: "X-Request-Id",
}))

​

Specific Methods Only

app.Use(idempotency.WithOptions(idempotency.Options{
    Methods: []string{http.MethodPost}, // Only POST
}))

​

User-Scoped Keys

app.Use(idempotency.WithOptions(idempotency.Options{
    KeyGenerator: func(key string, c *mizu.Ctx) string {
        userID := c.Request().Header.Get("X-User-ID")
        return userID + ":" + key
    },
}))

​

Custom Store

store := idempotency.NewMemoryStore()
defer store.Close()

app.Use(idempotency.WithStore(store, idempotency.Options{}))

​

How It Works

1. Client sends request with Idempotency-Key header
2. Middleware checks if key exists in store
3. If exists: returns cached response with Idempotent-Replayed: true
4. If not: executes handler, caches response, returns normally
5. Subsequent requests with same key get cached response

​

API Reference

​

Functions

// New creates idempotency middleware
func New() mizu.Middleware

// WithOptions creates middleware with configuration
func WithOptions(opts Options) mizu.Middleware

// WithStore creates middleware with custom store
func WithStore(store Store, opts Options) mizu.Middleware

// NewMemoryStore creates in-memory response store
func NewMemoryStore() *MemoryStore

​

Store Interface

type Store interface {
    Get(key string) (*Response, error)
    Set(key string, resp *Response) error
    Delete(key string) error
}

type Response struct {
    StatusCode int
    Headers    http.Header
    Body       []byte
    ExpiresAt  time.Time
}

​

Response Headers

​

Technical Details

​

Cache Key Generation

• The idempotency key from the header
• The HTTP method (POST, PUT, etc.)
• The request URL path

​

Response Capture

1. Captures the response status code (defaults to 200 OK)
2. Clones all response headers
3. Buffers the response body in memory
4. Writes everything to both the buffer and the underlying ResponseWriter

​

Memory Store Implementation

• Uses sync.RWMutex for thread-safe concurrent access
• Runs a background cleanup goroutine that removes expired entries every 10 minutes
• Stores responses with their expiration timestamps
• Returns nil for expired entries automatically

​

Request Flow

1. Method Check: Verifies the HTTP method is in the configured Methods list
2. Key Extraction: Retrieves the idempotency key from the specified header
3. Cache Lookup: Checks if a response exists for the generated cache key
4. Cache Hit: If found and not expired, replays the cached response with Idempotent-Replayed: true header
5. Cache Miss: Wraps the ResponseWriter, executes the handler, captures the response, and stores it in the cache
6. Expiration: Responses are stored with a TTL and automatically cleaned up

​

Best Practices

• Always use idempotency keys for payment operations
• Generate unique keys client-side (UUIDs work well)
• Include user context in key generation for multi-tenant apps
• Set appropriate TTL based on your use case
• Use distributed store (Redis) for multi-instance deployments

​

Testing

​

Test Coverage

​

Client Example

// JavaScript client
const response = await fetch('/api/payments', {
    method: 'POST',
    headers: {
        'Content-Type': 'application/json',
        'Idempotency-Key': crypto.randomUUID()
    },
    body: JSON.stringify({ amount: 100 })
});

​

Related Middlewares

• requestid - Request ID generation
• retry - Automatic retries
• ratelimit - Rate limiting