एपीआई (एप्लिकेशन प्रोग्रामिंग इंटरफ़ेस) अनुरोध से परे इडेम्पोटेंसी (दोहराए जाने योग्य सुरक्षित लेनदेन)। (Idempotency Beyond API Requests)

इडेम्पोटेंसी एक स्टैक है, हेडर नहीं

अधिकांश टीमें निष्क्रियता को "एपीआई अनुरोध में Idempotency-Key हेडर जोड़ना" के रूप में सीखती हैं और इसे वहीं छोड़ देती हैं। यह भुगतान प्रणालियों में हिमशैल का सिर्फ एक सिरा है। एक ही प्रक्रिया आपके सिस्टम के माध्यम से कम से कम पांच अलग-अलग बिंदुओं पर "दोहराई" जा सकती है: क्लाइंट पुनः प्रयास, पीएसपी का वेबहुक पुनः प्रयास, संदेश कतार की कम से कम एक बार डिलीवरी, कार्यकर्ता की नौकरी पुनर्प्राप्ति, गाथा चरण का पुन: संचालन।```text Client retry → API idempotency key PSP retry → Gateway event id Broker retry → Inbox kaydı Worker retry → Job uniqueness Saga retry → Step marker

## पहले उल्लेख पर अवधारणाएँ```text
📦 API Idempotency Key
İstemcinin gönderdiği, aynı isteğin tekrar gönderilmesi halinde aynı sonucu garanti eden benzersiz anahtar.

📦 Gateway Event ID
PSP'nin her webhook veya bildirime verdiği benzersiz kimlik; aynı olayın birden fazla teslimatını ayırt etmeye yarar.

📦 Inbox
Gelen bir olayın işlenmeden önce kaydedildiği, tekrarları filtreleyen dayanıklı bir tablo.

📦 Job Uniqueness
Bir arka plan işinin (job) aynı iş anahtarıyla ikinci kez kuyruğa girmesini önleyen kısıt.

📦 Step Marker
Bir saga adımının tamamlandığını kalıcı olarak işaretleyen, yeniden çalışmayı önleyen kayıt.
```ये पाँच अवधारणाएँ विनिमेय नहीं हैं। एपीआई निष्क्रियता कुंजी आपके और क्लाइंट के बीच दोहराव को रोकती है; लेकिन यह आपके PSP के वेबहुक, आपकी कतार की डिलीवरी, या आपके कार्यकर्ता के काम को बिल्कुल भी प्रभावित नहीं करता है।

## परत 1: एपीआई अनुरोध

यदि क्लाइंट "पे" बटन को दो बार दबाता है (नेटवर्क विलंब, डबल क्लिक), तो क्लाइंट उसी `Idempotency-Key` के साथ अनुरोध भेजता है। यदि सर्वर ने यह कुंजी देख ली है, तो वह प्रक्रिया को दोबारा नहीं चलाएगा; पहले रन का परिणाम लौटाता है। यह परत पूरी तरह से आपके एपीआई और क्लाइंट के बीच एक अनुबंध है।```text
POST /payments  Idempotency-Key: abc123
  → ilk çağrı: işlem çalışır, sonuç kaydedilir
  → aynı key ile ikinci çağrı: kayıtlı sonuç döner, işlem tekrar çalışmaz
```## परत 2: पीएसपी से घटना

नेटवर्क समस्याओं या अपनी पुनः प्रयास नीति के कारण PSP एक ही ईवेंट (उदाहरण के लिए "सफल कैप्चर") एक से अधिक बार भेज सकता है। इनमें से प्रत्येक इवेंट में PSP द्वारा दी गई एक अद्वितीय इवेंट आईडी होती है। यदि आप यह आईडी देखते हैं, तो आपको ईवेंट को दोबारा नहीं संभालना चाहिए - लेकिन आपको पीएसपी को स्पष्ट रूप से सूचित (एसीके) करना चाहिए कि आपने ऐसा नहीं किया है।```text
Webhook #1: event_id=evt_001, type=payment.captured
Webhook #2: event_id=evt_001, type=payment.captured  (tekrar teslim)
  → aynı event_id görülmüşse, işlem atlanır, 200 OK döner
```## परत 3: संदेश कतार/इनबॉक्स

यदि ईवेंट आईडी की जांच उस कोड में की जाती है जो ईवेंट को सीधे संसाधित करता है, तो आप दौड़ की स्थिति में एक ही ईवेंट को दो अलग-अलग श्रमिकों द्वारा संसाधित किए जाने का जोखिम उठाते हैं। इसीलिए इनबॉक्स पैटर्न का उपयोग किया जाता है: ईवेंट को पहले इनबॉक्स तालिका में एक अद्वितीय बाधा के साथ लिखा जाता है; यदि यह लिखना विफल हो जाता है (यह पहले से मौजूद है), तो घटना पहले ही देखी जा चुकी है और ऑपरेशन सुरक्षित रूप से छोड़ दिया गया है।```text
INSERT INTO inbox (event_id, ...) VALUES ('evt_001', ...)
  → başarılı: ilk kez görülüyor, işlem kuyruğuna eklenir
  → unique constraint hatası: zaten görülmüş, sessizce atlanır
```## परत 4: नौकरी ही

इनबॉक्स के बाद, कार्य पृष्ठभूमि कार्य को सौंप दिया जाता है। यह कार्य अपने आप एक से अधिक बार भी कतारबद्ध हो सकता है (उदाहरण के लिए, पुनः प्रयास तंत्र या पुनः तैनाती के दौरान)। कार्य कतार को उसी कार्य कुंजी के साथ दूसरे कार्य को अस्वीकार करना होगा (उदाहरण के लिए `payment_id + step_name`)।```text
Job key: payment_id=pay_42, step=finalize_stock
  → aynı key ile ikinci job denemesi: kuyruk seviyesinde reddedilir
```## परत 5: सागा चरण ही

यहां तक कि जब नौकरी चल रही हो, तब भी कदम निष्क्रिय होना चाहिए - क्योंकि दुर्घटना के बाद नौकरी खुद ही फिर से शुरू हो सकती है। यह अंतिम परत चरण मार्कर हैं, जिन्हें हमने अध्याय तीन में पेश किया है: प्रत्येक चरण स्थायी रूप से इसके पूरा होने का प्रतीक है, और यदि चरण फिर से चलाया जाता है तो यह उस चिह्न की जांच करता है ताकि यह वास्तविक कार्य (इन्वेंट्री में कटौती करना, वित्त रिकॉर्ड खोलना) फिर से न करे।```text
Step marker: finalize_stock=DONE (payment_id=pay_42)
  → adım tekrar çağrılırsa, marker kontrol edilir, iş tekrar yapılmaz
```## इन पांच परतों की अलग-अलग आवश्यकता क्यों है

प्रत्येक परत एक अलग "कौन पुनः भेजता है" प्रश्न का उत्तर देती है: ग्राहक, पीएसपी, कतार, कार्यकर्ता, या स्वयं कार्य। यदि आप केवल एपीआई परत पर निष्क्रियता स्थापित करते हैं और अन्य चार को छोड़ देते हैं, तो आपके सिस्टम में "एपीआई में एक बार, लेकिन पृष्ठभूमि में तीन बार" चलने वाली अंतिम गाथा हो सकती है - और आप केवल उत्पादन में इस बग को देखेंगे, आमतौर पर ग्राहक की शिकायत के साथ।

## इस एपिसोड में सबसे भ्रमित करने वाला मैचअप```text
❌ Idempotency-Key header'ı eklemek, idempotency problemini çözer
✓ Bu header sadece istemci-API katmanındaki tekrarı çözer

❌ PSP event id kontrolü tek başına yeterlidir
✓ Event id kontrolü, race condition'a karşı bir inbox/unique constraint ile desteklenmelidir

❌ Job kuyruğu at-least-once teslimat yaparsa, iş otomatik olarak idempotent olur
✓ At-least-once teslimat + idempotent olmayan iş = güvenli değil; iş kendi başına idempotent olmalıdır

❌ Bir saga adımı başarıyla tamamlandıysa tekrar çağrılması zararsızdır
✓ Adım işaretçisi yoksa tekrar çağrı, yan etkiyi (stok düşme, ödeme) ikinci kez tetikler

अपने इडेम्पोटेंसी स्टैक को चेकलिस्ट करें

1. क्या आपके एपीआई में एक निष्क्रियता कुंजी है? यदि हां, तो आप परिणाम को कब तक रखेंगे?
2. क्या आप अपने पीएसपी वेबहुक पर इवेंट आईडी की जांच करते हैं, या क्या आप प्रत्येक वेबहुक को सीधे संसाधित करते हैं?
3. क्या आपके इनबॉक्स तालिका में ईवेंट आईडी के लिए एक अद्वितीय बाधा है, या क्या आप एप्लिकेशन कोड (दौड़ की स्थिति का जोखिम) में जांच करते हैं?
4. क्या आपकी नौकरी कतार उसी नौकरी कुंजी के साथ दूसरी नौकरी को अस्वीकार करती है?
5. क्या प्रत्येक गाथा चरण एक मार्कर की जांच करता है जो अपने स्वयं के पूरा होने की जांच करता है, या क्या यह हर बार चलने पर कार्य को फिर से करता है?

यदि इन पांच परतों में से दो गायब हैं, तो आपके सिस्टम में "दुर्लभ लेकिन आवर्ती" दोहरी प्रतिबद्धता त्रुटियां होने की संभावना है।

इस अनुभाग से याद रखने योग्य बातें

1. निष्क्रियता एक एकल हेडर या एक नियंत्रण नहीं है; यह एक स्टैक है जिसे कम से कम पांच स्वतंत्र परतों में अलग से स्थापित किया जाना चाहिए।
2. प्रत्येक परत एक अलग रीप्ले स्रोत (क्लाइंट, पीएसपी, कतार, कार्यकर्ता, सागा चरण) पर प्रतिक्रिया करती है; एक में दूसरा शामिल नहीं है.
3. इनबॉक्स पैटर्न एक संरचनात्मक समाधान है जो इवेंट आईडी जांच को दौड़ की स्थिति के खिलाफ सुरक्षित बनाता है, यह सिर्फ "अगर" जांच नहीं है।
4. कम से कम एक बार डिलीवरी मॉडल में, एक गैर-निष्क्रिय कार्य चरण देर-सबेर दो बार चलेगा।

हेडर में निष्क्रियता को कम करना पांच मंजिला इमारत में एक दरवाजा लगाने और अन्य चार मंजिलों की खिड़कियां खुली छोड़ने जैसा है।