Bùa Vẽ API Cản Đúp Trong Go (Idempotent API Design) — Chìa Khóa Cản Đúp & Lưới Lọc Redis SetNX

{
  "idempotency_key": "550e8400-e29b-41d4-a716-446655440000",
  "payload_hash": "băm_vụn_sha256_đầu_cổ_xác_request_body_bytes",
  "status": "completed",
  "response_code": 201,
  "response_headers": {
    "Content-Type": ["application/json"],
    "X-Transaction-Id": ["tx_987654"]
  },
  "response_body": "{\"transaction_id\":\"tx_987654\",\"status\":\"success\"}",
  "created_at": "2026-06-18T09:00:00Z",
  "expires_at": "2026-06-19T09:00:00Z"
}

CREATE TABLE idempotency_keys (
    idemp_key        VARCHAR(255) NOT NULL,
    payload_hash     CHAR(64)     NOT NULL,         -- Đập móp băm nát SHA256 cái xác request body
    status           VARCHAR(50)  NOT NULL,          -- Rặn mãi: 'in-progress', 'completed', 'failed'
    response_code    INT,
    response_headers JSONB,
    response_body    TEXT,
    created_at       TIMESTAMPTZ  NOT NULL DEFAULT NOW(),
    expires_at       TIMESTAMPTZ  NOT NULL,

    PRIMARY KEY (idemp_key)
);

-- Soi mục lục hẹp (Partial index): chọc đúng ổ mấy cái khóa đang bốc cháy (active keys - tỉa gọt cắt xén cho mâm index thon gọn index size cho ba cái bảng thô kệch)
CREATE UNIQUE INDEX idx_idemp_active ON idempotency_keys (idemp_key)
    WHERE expires_at > NOW();

package middleware

import (
    "bytes"
    "context"
    "crypto/sha256"
    "encoding/hex"
    "encoding/json"
    "fmt"
    "io"
    "net/http"
    "time"

    "github.com/redis/go-redis/v9"
)

// IdempotencyRecord ngâm dấm nhồi lổm chổm JSON ở bãi Redis
type IdempotencyRecord struct {
    Status       string              `json:"status"`       // "in-progress" | "completed"
    ResponseCode int                 `json:"response_code"`
    Headers      map[string][]string `json:"headers"`
    Body         string              `json:"body"`
    PayloadHash  string              `json:"payload_hash"`
}

// responseRecorder bọc vỏ nhộng bao lấy http.ResponseWriter đặng túm mớ ọc rác (capture the response)
type responseRecorder struct {
    http.ResponseWriter
    code int
    body *bytes.Buffer
}

func newResponseRecorder(w http.ResponseWriter) *responseRecorder {
    return &responseRecorder{ResponseWriter: w, code: http.StatusOK, body: new(bytes.Buffer)}
}

func (r *responseRecorder) WriteHeader(statusCode int) {
    r.code = statusCode
    r.ResponseWriter.WriteHeader(statusCode)
}

func (r *responseRecorder) Write(b []byte) (int, error) {
    r.body.Write(b)
    return r.ResponseWriter.Write(b)
}

// IdempotencyMiddleware vác lề luật bóp cổ đám cản đúp giương ngạnh xài Redis SetNX
type IdempotencyMiddleware struct {
    rdb    *redis.Client
    keyTTL time.Duration
}

func NewIdempotencyMiddleware(rdb *redis.Client, keyTTL time.Duration) *IdempotencyMiddleware {
    return &IdempotencyMiddleware{rdb: rdb, keyTTL: keyTTL}
}

func (im *IdempotencyMiddleware) Handle(next http.Handler) http.Handler {
    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        idempKey := r.Header.Get("Idempotency-Key")
        if idempKey == "" {
            next.ServeHTTP(w, r) // chẳng vác thẻ bài (No key) → mời quan anh lách (pass through)
            return
        }

        ctx := r.Context()
        redisKey := fmt.Sprintf("idemp:%s", idempKey)

        // Quay cối băm chả cục mìn (Compute payload hash) rình rập soi trò tráo trở xài lại thẻ vớ xác khác (key reuse with different body)
        body, _ := io.ReadAll(r.Body)
        r.Body = io.NopCloser(bytes.NewBuffer(body))
        hash := sha256.Sum256(body)
        payloadHash := hex.EncodeToString(hash[:])

        // Chặng 1 (Step 1): Dòm ngó thử thẻ này nát lỗ chưa (Check if key already exists)
        existingData, err := im.rdb.Get(ctx, redisKey).Result()
        if err == nil {
            var existing IdempotencyRecord
            if json.Unmarshal([]byte(existingData), &existing) == nil {
                // Tát sưng mỏ trò lén lút tuồn mìn mớ rác tráo xác (Reject key reuse with different payload)
                if existing.PayloadHash != "" && existing.PayloadHash != payloadHash {
                    http.Error(w,
                        `{"error":"idempotency_key_reuse","message":"Cầm chìa cũ ném rác mới (Key used with a different request body)"}`,
                        http.StatusUnprocessableEntity)
                    return
                }

                if existing.Status == "in-progress" {
                    // Cùng một lò goroutine/pod ất ơ nào đó đang è cổ nấu cơm với cái chìa khóa này
                    http.Error(w,
                        `{"error":"request_in_progress","message":"Trò chọc lố đang bị nhồi (Duplicate request is already being processed)"}`,
                        http.StatusConflict)
                    return
                }

                // Luộc lóng ngóng mớ phèo phổi (Already completed) — ọi trả cục rác (replay the cached response)
                for name, vals := range existing.Headers {
                    for _, val := range vals {
                        w.Header().Add(name, val)
                    }
                }
                w.Header().Set("X-Idempotent-Replayed", "true")
                w.WriteHeader(existing.ResponseCode)
                w.Write([]byte(existing.Body))
                return
            }
        }

        // Chặng 2 (Step 2): Nhắm mắt chém phát lụm luôn (Atomically claim) xài ngón đòn SetNX (SET if Not eXists)
        // DUY NHẤT MỘT THẰNG (ONE) lính goroutine/pod đớp được hũ vàng (succeed) — đám bậu xậu ra rìa húp cháo (false)
        inProgress := IdempotencyRecord{Status: "in-progress", PayloadHash: payloadHash}
        inProgressJSON, _ := json.Marshal(inProgress)

        set, setErr := im.rdb.SetNX(ctx, redisKey, inProgressJSON, im.keyTTL).Result()
        if setErr != nil || !set {
            http.Error(w,
                `{"error":"conflict","message":"Bị thằng ôn nhảy lầu chặn mẹ họng (Request already in progress)"}`,
                http.StatusConflict)
            return
        }

        // Chặng 3 (Step 3): Lăn xả nhào vô nấu rác (Execute the actual handler), hốt ổ trọn gói bãi mửa của nó
        recorder := newResponseRecorder(w)
        next.ServeHTTP(recorder, r)

        // Chặng 4 (Step 4): Nhồi rác vùi lấp (Save the completed response) chôn xuống Redis
        finalRecord := IdempotencyRecord{
            Status:       "completed",
            ResponseCode: recorder.code,
            Headers:      map[string][]string(w.Header()),
            Body:         recorder.body.String(),
            PayloadHash:  payloadHash,
        }
        finalJSON, _ := json.Marshal(finalRecord)
        im.rdb.Set(ctx, redisKey, finalJSON, im.keyTTL)
    })
}

package middleware

import (
    "net/http"
    "net/http/httptest"
    "sync"
    "sync/atomic"
    "testing"
    "time"
)

func TestIdempotencyMutualExclusion(t *testing.T) {
    var executionCount atomic.Int64

    handler := http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        executionCount.Add(1)
        w.WriteHeader(http.StatusCreated)
        w.Write([]byte(`{"transaction_id":"tx_001","status":"success"}`))
    })

    rdb := setupTestRedis() // cắn hàng rởm miniredis test ngáo 
    mw := NewIdempotencyMiddleware(rdb, 24*time.Hour)
    wrapped := mw.Handle(handler)

    const concurrency = 100
    var wg sync.WaitGroup
    wg.Add(concurrency)

    codes := make([]int, concurrency)
    for i := 0; i < concurrency; i++ {
        go func(index int) {
            defer wg.Done()
            req := httptest.NewRequest("POST", "/payments",
                strings.NewReader(`{"amount":100}`))
            req.Header.Set("Idempotency-Key", "same-uuid-for-all") // Cùng 1 mẹ đẻ ra! (Same key!)
            req.Header.Set("Content-Type", "application/json")

            rec := httptest.NewRecorder()
            wrapped.ServeHTTP(rec, req)
            codes[index] = rec.Code
        }(i)
    }
    wg.Wait()

    // Bọn thợ đụng cắn răng nhai phải chạy ĐÚNG DÀNH ĐÉT 1 PHÁT (exactly ONCE) mạc xác ngập mồm 100 cú chọt
    if count := executionCount.Load(); count != 1 {
        t.Errorf("Ngáo vãi đòi 1 cú, lòi mồm %d", count)
    }

    created, conflict := 0, 0
    for _, code := range codes {
        switch code {
        case http.StatusCreated:
            created++
        case http.StatusConflict:
            conflict++
        }
    }
    t.Logf("Lụm thóc: %d Trái (Created), %d Thọt Đè Nhau (Conflict) (đúc ở lò %d concurrent requests)",
        created, conflict, concurrency)
    // Sổ ghi: 1 con hốt bạc (Created), 99 đứa chui hầm mếu máo (Conflict)
}

package retry

import (
    "fmt"
    "math"
    "math/rand"
    "time"
)

type ExponentialBackoff struct {
    BaseDelay  time.Duration
    MaxDelay   time.Duration
    JitterCap  time.Duration
    MaxRetries int
}

func (b *ExponentialBackoff) NextDelay(attempt int) (time.Duration, bool) {
    if attempt >= b.MaxRetries {
        return 0, false
    }
    exp := math.Pow(2, float64(attempt))
    delay := time.Duration(float64(b.BaseDelay)*exp) +
        time.Duration(rand.Int63n(int64(b.JitterCap)))
    if delay > b.MaxDelay {
        delay = b.MaxDelay
    }
    return delay, true
}

// RetryWithIdempotency gồng mình đập cửa thử đâm lại (retries) CÙNG MỘT PHÔI THẺ cản đúp (SAME idempotency key) nhồi trên từng phát nã
func RetryWithIdempotency(
    key string,
    backoff ExponentialBackoff,
    fn func(idempKey string) (int, error),
) error {
    for attempt := 0; attempt < backoff.MaxRetries; attempt++ {
        statusCode, err := fn(key) // Chày cối 1 thẻ ở mỗi hiệp húc đụng (Same key on every retry — safe)

        if err == nil && statusCode < 500 {
            return nil // Êm chim (Success) quặc dính mìn client (4xx) — cuốn xéo về chẳng húc đập nữa (don't retry)
        }

        delay, more := backoff.NextDelay(attempt)
        if !more {
            return fmt.Errorf("cắn rứt nổ sọ hết trơn mẹ mìn đập cửa %d phát (exhausted retries)", attempt+1)
        }
        time.Sleep(delay)
    }
    return nil
}