Idempotency Key بالعربي: امنع سحب الفلوس مرتين لما العميل يضغط "ادفع" تاني

الشكل غير الآمن (قبل Idempotency)

لو العميل بعت الطلب ده مرتين، السيرفر هيعمل charge مرتين. ده bug إنتاج حقيقي.

الشكل الآمن

العميل بيولّد الـ UUID مرة واحدة قبل الطلب. أي retry بيبعت نفس المفتاح. السيرفر بيستخدمه كبصمة.

تنفيذ Middleware كامل بـ Node.js و Redis

الكود ده بيعمل 3 حاجات: بيقرا الـ header، بيشيك Redis، بيحط lock قصير عشان طلبين متوازيين بنفس المفتاح ما يتنفذوش مع بعض (race condition). التخزين بيحصل بعد ما الـ handler يخلّص ويرجّع response.

قياس فعلي

سيناريو: نظام دفع بـ 100,000 طلب يومياً، 2% retry rate بسبب شبكة ضعيفة (= 2,000 طلب مكرر).

الأرقام دي مبنية على معدلات إعادة المحاولة اللي نشرتها Stripe في مدونتها الرسمية عن Idempotency، بتطبيقها على حجم transactions متوسط لمتجر e-commerce عربي.

Trade-offs اللي لازم تعرفها

بتكسب: أمان كامل من duplicates، retry آمن من طرف العميل حتى لو network flaky، تجربة مستخدم أحسن لأن العميل يقدر يضغط تاني بدون خوف.

بتخسر:

• Redis memory (كل key + response cached، TTL لازم يتحط).
• Latency صغيرة (+2–4ms لكل طلب بسبب الـ lookup).
• تعقيد زيادة في error handling — لو الطلب فشل في نص التنفيذ، لازم قرار واضح: تحفظ الـ failed response ولا تسيب العميل يعيد؟

التوصية: احفظ الـ failed response لو الفشل نهائي (validation error، insufficient funds). ماتحفظش لو الفشل مؤقت (timeout على Stripe) علشان retry يكون ممكن.

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

• GET requests: idempotent بطبعها، مش محتاجة مفتاح.
• Counters و increments: أحياناً التكرار هو الصح (POST /views). هنا الـ idempotency هتكسرلك المنطق.
• Keys بدون TTL: الذاكرة بتنفجر بعد أسابيع. دايماً حط TTL بين 24 ساعة و 7 أيام حسب الـ domain.
• Multi-tenant بدون namespace: لو شركتين بيستخدموا نفس الـ key بالصدفة، الثانية هتاخد response الأولى. خلي الـ cache key {tenant_id}:{key}.

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

افتح أقرب POST endpoint عندك بيعمل شغل مالي أو يرسل email أو ينشئ طلب. ضيف middleware بيقرا Idempotency-Key من الـ headers ويخزّن الـ response في Redis لمدة 24 ساعة. اختبره بـ curl بنفس المفتاح مرتين — المفروض الرد يكون 100% متطابق والـ charge يحصل مرة واحدة بس.

مصادر

• Stripe — Idempotent Requests (documentation)
• Stripe Engineering — Designing robust and predictable APIs with idempotency
• IETF — draft-ietf-httpapi-idempotency-key-header
• RFC 9110 — Idempotent Methods
• AWS Builder's Library — Making retries safe with idempotent APIs
• MDN — Idempotent (Glossary)