مفاتيح التكرار (Idempotency Keys): أعِد المحاولة على الدفع بأمان بلا خصم مزدوج

CREATE TABLE idempotency_keys (
  key         TEXT PRIMARY KEY,
  response    JSONB       NOT NULL,
  status_code INT         NOT NULL,
  created_at  TIMESTAMPTZ NOT NULL DEFAULT now()
);

والمنطق في الـ endpoint (Flask + psycopg). لاحظ الـ FOR UPDATE اللي بيقفل الصف علشان يتعامل مع طلبين متزامنين بنفس المفتاح:

خطوة مهمة للإنتاج: اربط المفتاح بهوية العميل (user_id + key) علشان مفتاح حد ما يصطدمش بمفتاح حد تاني، وارفض أي طلب بيعيد استخدام مفتاح قديم بجسم مختلف.

الأرقام والـ trade-off

في نظام مدفوعات بـ 200 ألف عملية في اليوم، كان معدل الخصم المزدوج حوالي 0.3% (قرب 600 عملية يوميًا) بسبب إعادة المحاولة والشبكة. بعد تفعيل مفاتيح التكرار نزل المعدل لصفر تقريبًا. تكلفة البحث عن المفتاح في جدول مفهرس أقل من 1 مللي ثانية لكل طلب (الأرقام تقديرية للتوضيح، بس الترتيب واقعي).

الـ trade-off هنا: بتكسب أثر "مرة واحدة بالظبط" (exactly-once effect) وأمان كامل لإعادة المحاولة. بتخسر تخزين إضافي (صف لكل عملية)، زمن بحث بسيط، وتعقيد في التعامل مع الطلبات المتزامنة (محتاج قفل أو قيد فريد). الافتراض إن العملية ليها side effect حقيقي؛ من غير كده الكلام ده مالوش لازمة.

خزّن المفتاح مع مدة صلاحية (TTL) زي 24 ساعة، وامسح القديم بمهمة مجدولة. Stripe مثلًا بيحتفظ بمفاتيح التكرار لمدة 24 ساعة.

متى لا تستخدم هذه الطريقة

لو العملية قرائية بحتة (GET) فهي idempotent أصلاً ومش محتاجة مفتاح. لو العملية آمنة للتكرار بطبيعتها (زي "خلّي القيمة = X" اللي تكرارها مايغيّرش حاجة)، مفيش داعي. للأدوات الداخلية الصغيرة اللي تكرارها مش بيكلّف، مفاتيح التكرار ممكن تبقى تعقيد زيادة. ركّز الحماية على العمليات اللي تكرارها بيكلّف فلوس أو بيبعت حاجة للعميل.

الخطوة التالية

افتح أهم endpoint فيه POST بيعمل side effect (دفع، إنشاء طلب، إرسال إيميل)، ضيف جدول idempotency_keys بقيد فريد، وخلّي العميل يبعت هيدر Idempotency-Key. بعد كده ابعت نفس الطلب مرتين ورا بعض بنفس المفتاح، وأكّد إن الـ side effect حصل مرة واحدة والرد اترجّع نفسه في المرتين.

المصادر

• Stripe API Docs — Idempotent requests: https://docs.stripe.com/api/idempotent_requests
• IETF Draft — The Idempotency-Key HTTP Header Field: https://datatracker.ietf.org/doc/draft-ietf-httpapi-idempotency-key-header/
• RFC 9110 — HTTP Semantics (Idempotent Methods): https://www.rfc-editor.org/rfc/rfc9110#name-idempotent-methods
• MDN Web Docs — Idempotent: https://developer.mozilla.org/en-US/docs/Glossary/Idempotent