Make Square webhook dedup restart-safe via database

The in-memory dedup is now only a fast path; the square_webhook_events INSERT ... ON CONFLICT DO NOTHING is the source of truth, so replays across restarts and after FIFO eviction are skipped. A DB failure fails closed with 503 so Square retries. Empty event_ids are rejected with 400 (no dispatch, no dedup row). Ordering trade-off (insert-before-dispatch) documented for when handlers mutate state.
2026-08-22 00:34:49 +01:00
parent c9d55817f6
commit 5ea89da2ad
3 changed files with 311 additions and 16 deletions
@@ -13,8 +13,12 @@ import (
 	"log"
 	"net/http"
 	"net/http/httptest"
+	"os"
 	"strings"
 	"testing"
+
+	"crussell/db"
+	"github.com/jackc/pgx/v5/pgxpool"
 )

 // =============================================================================
@@ -126,6 +130,31 @@ func webhookTestEnv(t *testing.T, body []byte) (signature string) {
 	return base64.StdEncoding.EncodeToString(mac.Sum(nil))
 }

+// countWebhookEvents returns how many dedup rows exist for an event_id. The
+// handler commits its dedup insert to the pool (no per-test transaction), so a
+// fresh query sees it.
+func countWebhookEvents(t *testing.T, eventID string) int {
+	t.Helper()
+	var n int
+	if err := db.Conn.QueryRow(context.Background(),
+		"SELECT COUNT(*) FROM square_webhook_events WHERE event_id = $1", eventID).Scan(&n); err != nil {
+		t.Fatalf("failed to count square_webhook_events rows: %v", err)
+	}
+	return n
+}
+
+// testDBHost mirrors testdb.dbHost so the broken-pool test can reach the same
+// Postgres instance without importing testdb internals.
+func testDBHost() string {
+	if h := os.Getenv("TEST_DB_HOST"); h != "" {
+		return h
+	}
+	if h := os.Getenv("POSTGRES_HOST"); h != "" {
+		return h
+	}
+	return "localhost"
+}
+
 func TestHandleSquareWebhook_PaymentUpdated(t *testing.T) {
 	event := SquareWebhookEvent{
 		Type:      "payment.updated",
@@ -198,6 +227,38 @@ func TestHandleSquareWebhook_InvalidJSON(t *testing.T) {
 	}
 }

+// TestHandleSquareWebhook_EmptyEventID_Rejected verifies a signed event with an
+// empty event_id is rejected with 400 — fail-safe: no dispatch, no dedup row.
+// Square's retry policy treats 4xx as non-retryable, so the malformed event is
+// dropped without side effects.
+func TestHandleSquareWebhook_EmptyEventID_Rejected(t *testing.T) {
+	body := []byte(`{"type":"payment.updated","event_id":"","data":{"id":"payment_empty_id"}}`)
+	sig := webhookTestEnv(t, body)
+
+	var buf bytes.Buffer
+	oldOutput := log.Writer()
+	log.SetOutput(&buf)
+	defer log.SetOutput(oldOutput)
+
+	w := makeWebhookRequest(body, sig, context.Background())
+	if w.Code != http.StatusBadRequest {
+		t.Fatalf("expected 400 for empty event_id, got %d. body: %s", w.Code, w.Body.String())
+	}
+
+	out := buf.String()
+	if !strings.Contains(out, "Rejecting event with empty event_id (400)") {
+		t.Errorf("expected empty event_id rejection log, got:\n%s", out)
+	}
+	if strings.Contains(out, "Received event: payment.updated") {
+		t.Errorf("expected empty event_id to skip dispatch, got:\n%s", out)
+	}
+
+	// No dedup row may be written for an empty event_id.
+	if n := countWebhookEvents(t, ""); n != 0 {
+		t.Errorf("expected no dedup row for empty event_id, got %d", n)
+	}
+}
+
 func TestHandleSquareWebhook_BodyTooLarge(t *testing.T) {
 	// 600KB body exceeds the 512KB limit
 	largeBody := []byte(strings.Repeat("a", 600*1024))
@@ -328,6 +389,11 @@ func TestHandleSquareWebhook_DuplicateEventID(t *testing.T) {
 	if w2.Body.String() != "ok" {
 		t.Errorf("expected replay body 'ok', got %q", w2.Body.String())
 	}
+
+	// The persistent dedup row is written exactly once despite both deliveries.
+	if n := countWebhookEvents(t, event.EventID); n != 1 {
+		t.Errorf("expected exactly 1 persisted dedup row, got %d", n)
+	}
 }

 func TestHandleSquareWebhook_DistinctEventIDs(t *testing.T) {
@@ -379,3 +445,144 @@ func TestSquareWebhookDedup_CapEvictsOldest(t *testing.T) {
 		t.Errorf("expected evt_cap_0 to be evicted and treated as new")
 	}
 }
+
+func TestSquareWebhookDedup_HasDoesNotRecord(t *testing.T) {
+	d := newSquareWebhookDedup(3)
+	if d.has("evt_has_1") {
+		t.Error("expected has() on empty set to return false")
+	}
+	if d.register("evt_has_1") {
+		t.Error("expected first register to report new")
+	}
+	if !d.has("evt_has_1") {
+		t.Error("expected has() to observe a registered id")
+	}
+}
+
+// TestHandleSquareWebhook_DedupDispatchOnce verifies the handler body runs
+// exactly once across a delivery + replay, with a single persisted dedup row.
+func TestHandleSquareWebhook_DedupDispatchOnce(t *testing.T) {
+	event := SquareWebhookEvent{
+		Type:      "payment.updated",
+		EventID:   "evt_dispatch_once_1",
+		CreatedAt: "2025-01-01T00:00:00Z",
+		Data:      json.RawMessage(`{"id":"payment_dispatch_once_1"}`),
+	}
+	body, _ := json.Marshal(event)
+	sig := webhookTestEnv(t, body)
+
+	var buf bytes.Buffer
+	oldOutput := log.Writer()
+	log.SetOutput(&buf)
+	defer log.SetOutput(oldOutput)
+
+	w1 := makeWebhookRequest(body, sig, context.Background())
+	if w1.Code != http.StatusOK {
+		t.Fatalf("expected first delivery 200, got %d. body: %s", w1.Code, w1.Body.String())
+	}
+	w2 := makeWebhookRequest(body, sig, context.Background())
+	if w2.Code != http.StatusOK {
+		t.Fatalf("expected replay 200, got %d. body: %s", w2.Code, w2.Body.String())
+	}
+	if w2.Body.String() != "ok" {
+		t.Errorf("expected replay body 'ok', got %q", w2.Body.String())
+	}
+
+	out := buf.String()
+	if got := strings.Count(out, "Received event: payment.updated"); got != 1 {
+		t.Errorf("expected dispatch to run exactly once, saw %d 'Received event' log lines:\n%s", got, out)
+	}
+	if n := countWebhookEvents(t, event.EventID); n != 1 {
+		t.Errorf("expected exactly 1 persisted dedup row, got %d", n)
+	}
+}
+
+// TestHandleSquareWebhook_DedupPersistsAcrossRestart simulates a restart: the
+// event was handled by a previous process whose in-memory cache is gone, but
+// the dedup row survived in the DB — the replayed delivery must be skipped.
+func TestHandleSquareWebhook_DedupPersistsAcrossRestart(t *testing.T) {
+	event := SquareWebhookEvent{
+		Type:      "payment.updated",
+		EventID:   "evt_restart_1",
+		CreatedAt: "2025-01-01T00:00:00Z",
+		Data:      json.RawMessage(`{"id":"payment_restart_1"}`),
+	}
+	body, _ := json.Marshal(event)
+	sig := webhookTestEnv(t, body)
+
+	if _, err := db.Conn.Exec(context.Background(),
+		"INSERT INTO square_webhook_events (event_id) VALUES ($1) ON CONFLICT (event_id) DO NOTHING", event.EventID); err != nil {
+		t.Fatalf("failed to seed dedup row: %v", err)
+	}
+
+	var buf bytes.Buffer
+	oldOutput := log.Writer()
+	log.SetOutput(&buf)
+	defer log.SetOutput(oldOutput)
+
+	w := makeWebhookRequest(body, sig, context.Background())
+	if w.Code != http.StatusOK {
+		t.Fatalf("expected 200 for replayed event, got %d. body: %s", w.Code, w.Body.String())
+	}
+	if w.Body.String() != "ok" {
+		t.Errorf("expected body 'ok', got %q", w.Body.String())
+	}
+	if out := buf.String(); strings.Contains(out, "Received event: payment.updated") {
+		t.Errorf("expected replayed event to skip dispatch, got:\n%s", out)
+	}
+	if n := countWebhookEvents(t, event.EventID); n != 1 {
+		t.Errorf("expected still exactly 1 dedup row, got %d", n)
+	}
+}
+
+// TestHandleSquareWebhook_DedupInsertFails_FailsClosed verifies the handler
+// rejects (503) when the dedup INSERT cannot be persisted, so Square retries.
+func TestHandleSquareWebhook_DedupInsertFails_FailsClosed(t *testing.T) {
+	event := SquareWebhookEvent{
+		Type:      "payment.updated",
+		EventID:   "evt_db_down_1",
+		CreatedAt: "2025-01-01T00:00:00Z",
+		Data:      json.RawMessage(`{"id":"payment_db_down_1"}`),
+	}
+	body, _ := json.Marshal(event)
+	sig := webhookTestEnv(t, body)
+
+	orig := db.Conn
+	defer func() { db.Conn = orig }()
+	// A pool whose database does not exist fails every Exec — simulating a DB
+	// that is unreachable or down.
+	badDSN := fmt.Sprintf("postgres://myuser:mypassword@%s:5432/crussell_test_webhooks_nonexistent?sslmode=disable", testDBHost())
+	badPool, err := pgxpool.New(context.Background(), badDSN)
+	if err != nil {
+		t.Fatalf("failed to create broken pool: %v", err)
+	}
+	defer badPool.Close()
+	db.Conn = db.NewPoolProxy(badPool)
+
+	w := makeWebhookRequest(body, sig, context.Background())
+	if w.Code != http.StatusServiceUnavailable {
+		t.Fatalf("expected 503 when dedup write fails, got %d. body: %s", w.Code, w.Body.String())
+	}
+}
+
+// TestHandleSquareWebhook_DedupNilConn_FailsClosed verifies the handler also
+// rejects (503) when the DB was never wired at all (defensive fail-closed).
+func TestHandleSquareWebhook_DedupNilConn_FailsClosed(t *testing.T) {
+	event := SquareWebhookEvent{
+		Type:      "payment.updated",
+		EventID:   "evt_nil_conn_1",
+		CreatedAt: "2025-01-01T00:00:00Z",
+		Data:      json.RawMessage(`{"id":"payment_nil_conn_1"}`),
+	}
+	body, _ := json.Marshal(event)
+	sig := webhookTestEnv(t, body)
+
+	orig := db.Conn
+	db.Conn = nil
+	defer func() { db.Conn = orig }()
+
+	w := makeWebhookRequest(body, sig, context.Background())
+	if w.Code != http.StatusServiceUnavailable {
+		t.Fatalf("expected 503 when DB is not wired, got %d. body: %s", w.Code, w.Body.String())
+	}
+}