Apa Itu Idempotency? Retry Aman dan Idempotency Key

• Key baru di setiap percobaan

  Membuat key di dalam loop retry menjadikan setiap retry sebuah request baru, dan perlindungannya hilang. Buat key sekali per operasi, simpan bersama operasi yang belum selesai, lalu pakai ulang di setiap retry, restart proses, dan reload halaman. Panduan Stripe memperingatkan bahwa key baru bisa memulai operasi kedua.

• Cek key lalu simpan, dalam dua langkah terpisah

  Dua duplikat yang tiba bersamaan sama-sama tidak menemukan catatan untuk key itu, sama-sama mengerjakan tugasnya, dan pelanggan ditagih dua kali. Klaim key lebih dulu dalam satu langkah atomik yang diputuskan oleh unique constraint, tandai sebagai sedang diproses, dan hanya request yang memenangkan klaim yang mengerjakan tugasnya. Yang lain mendapat 409.

• Penanda selesai yang ditulis sebelum pekerjaan selesai

  Lewati-jika-sudah-ada hanya idempotent jika penandanya berarti seluruh job sudah selesai. Jika langkah berikutnya gagal, run ulang akan selamanya melewati job yang setengah jadi, seperti yang pernah terjadi pada merge script repo ini. Tulis penandanya dalam transaksi yang sama dengan pekerjaannya, atau putuskan semua yang bisa gagal sebelum write pertama.

• Menganggap 500 sebagai izin untuk mencoba dari awal

  Status 500 itu tidak pasti: operasinya mungkin sudah menimbulkan efek. Panduan Stripe menyarankan untuk tidak me-retry dengan key baru sampai hasil request awal jelas, dan berhenti me-retry operasi yang belum jelas setelah jendela 24 jam lalu merekonsiliasinya.

• Yang akan saya ubah di sini: satu key per pesan kontak

  Form-nya bisa membuat crypto.randomUUID() sekali per pesan yang sudah diisi, mengirimnya bersama POST, dan menghapusnya hanya setelah sukses. Route-nya lalu meneruskan key itu ke emails.send sebagai idempotencyKey, yang disimpan Resend selama 24 jam, sehingga tekan tombol kedua setelah balasan hilang mengembalikan hasil pertama, bukan email kedua. Teks error-nya juga sebaiknya menyebut bahwa pesannya mungkin sudah terkirim.

1. 1

   Simpan server ini sebagai server.mjs dan jalankan dengan node server.mjs di terminal tersendiri. Server mencetak jumlah charge setiap kali ada charge baru.

   // server.mjs: a toy payments API. Each charge takes 1.5 s. With an
   // Idempotency-Key header, the first result is stored and replayed.
   import { createHash } from "node:crypto";
   import http from "node:http";
   
   const charges = [];
   const keys = new Map(); // key -> { fingerprint, done, status, body }
   const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
   
   function reply(res, status, body, headers = {}) {
     res.writeHead(status, { "Content-Type": "application/json", ...headers });
     res.end(JSON.stringify(body) + "\n");
   }
   
   http
     .createServer(async (req, res) => {
       if (req.method === "GET") return reply(res, 200, { charges: charges.length });
       let raw = "";
       for await (const chunk of req) raw += chunk;
       const key = req.headers["idempotency-key"];
       const fingerprint = createHash("sha256").update(raw).digest("hex");
       if (key) {
         const seen = keys.get(key);
         if (seen && seen.fingerprint !== fingerprint)
           return reply(res, 422, { error: "key reused with a different body" });
         if (seen && !seen.done)
           return reply(res, 409, { error: "a request with this key is in progress" });
         if (seen) return reply(res, seen.status, seen.body, { "Idempotent-Replayed": "true" });
         keys.set(key, { fingerprint, done: false }); // claim the key BEFORE the work
       }
       await sleep(1500); // the slow part, like a call to a card network
       const charge = { id: `ch_${charges.length + 1}`, body: raw };
       charges.push(charge);
       if (key) keys.set(key, { fingerprint, done: true, status: 201, body: charge });
       console.log("charges so far:", charges.length);
       reply(res, 201, charge);
     })
     .listen(4242, "127.0.0.1", () => console.log("listening on 127.0.0.1:4242"));

   Salin
2. 2

   Hilangkan sebuah balasan dengan sengaja. curl -m 1 menyerah setelah satu detik, sebelum charge 1,5 detik itu menjawab, jadi curl mencetak timeout (error 28) padahal server sudah menagih. Retry POST yang sama lalu baca hitungannya: 2 charge untuk satu order.

   curl -sS -m 1 -X POST http://127.0.0.1:4242/charges -d 'order=A-1'
   curl -sS -X POST http://127.0.0.1:4242/charges -d 'order=A-1'
   curl -sS http://127.0.0.1:4242/charges

   Salin
3. 3

   Ulangi dengan idempotency key yang dibuat sekali, sebelum percobaan pertama. Panggilan pertama timeout lagi; retry-nya mendapat 201 yang tersimpan dengan Idempotent-Replayed: true, dan hitungannya naik satu, bukan dua.

   KEY=$(node -p "crypto.randomUUID()")
   curl -sS -m 1 -X POST http://127.0.0.1:4242/charges -H "Idempotency-Key: $KEY" -d 'order=B-1'
   sleep 1
   curl -sS -i -X POST http://127.0.0.1:4242/charges -H "Idempotency-Key: $KEY" -d 'order=B-1'
   curl -sS http://127.0.0.1:4242/charges

   Salin
4. 4

   Kirim duplikat saat request pertama masih berjalan. Duplikatnya langsung mencetak 409; request aslinya mencetak 201 saat selesai.

   KEY=$(node -p "crypto.randomUUID()")
   curl -sS -w '%{http_code}\n' -X POST http://127.0.0.1:4242/charges -H "Idempotency-Key: $KEY" -d 'order=C-1' &
   sleep 0.2
   curl -sS -w '%{http_code}\n' -X POST http://127.0.0.1:4242/charges -H "Idempotency-Key: $KEY" -d 'order=C-1'
   wait

   Salin
5. 5

   Di terminal yang sama, pakai lagi key tadi dengan body berbeda. Server menolak dengan 422, sesuai saran draft IETF, alih-alih memutar ulang jawaban untuk request yang berbeda.

   curl -sS -w '%{http_code}\n' -X POST http://127.0.0.1:4242/charges -H "Idempotency-Key: $KEY" -d 'order=C-2'

   Salin
6. 6

   Sekarang idempotency alami di SQLite. Upsert menyisipkan sekali (changes 1) dan tidak melakukan apa-apa di kali kedua (changes 0). Mengurangi dua kali menyisakan 10; menyetel 11 dua kali tetap 11.

   sqlite3 :memory: <<'SQL'
   CREATE TABLE processed (message_id TEXT PRIMARY KEY);
   CREATE TABLE stock (sku TEXT PRIMARY KEY, qty INTEGER);
   INSERT INTO stock VALUES ('mug', 12);
   -- a redelivered message, handled twice
   INSERT INTO processed VALUES ('msg-42') ON CONFLICT (message_id) DO NOTHING;
   SELECT changes();
   INSERT INTO processed VALUES ('msg-42') ON CONFLICT (message_id) DO NOTHING;
   SELECT changes();
   -- add-by-amount twice, then set-a-value twice
   UPDATE stock SET qty = qty - 1 WHERE sku = 'mug';
   UPDATE stock SET qty = qty - 1 WHERE sku = 'mug';
   SELECT qty FROM stock;
   UPDATE stock SET qty = 11 WHERE sku = 'mug';
   UPDATE stock SET qty = 11 WHERE sku = 'mug';
   SELECT qty FROM stock;
   SQL

   Salin
7. 7

   Hentikan server dengan Ctrl+C di terminalnya. Semua datanya hanya di memori, jadi tidak ada yang tertinggal.

Dari: 9. Belajar WebSocket dan SSE untuk Pemula, Termasuk Long Polling · 7. Contoh Studi Kasus System Design: Merancang Situs Ini

1. 1.Kenapa DELETE idempotent walaupun panggilan kedua bisa menjawab berbeda?Lihat jawabannya

   Jawaban:Idempotency berbicara tentang efek yang dimaksud di server, bukan responsnya. Setelah satu atau dua kali DELETE, resource-nya tetap hilang; RFC 9110 menyebut respons untuk pengulangan bisa berbeda.

2. 2.Apa yang disimpan server untuk setiap idempotency key, dan kapan?Lihat jawabannya

   Jawaban:Fingerprint dari body, status pekerjaannya, serta status dan body yang dijawabnya. Server mengklaim key sebagai sedang diproses sebelum mengerjakan tugasnya, sehingga duplikat yang masih jalan mendapat 409, lalu menyimpan hasilnya saat pekerjaan selesai.

3. 3.Script deploy menambahkan isi ke .env dengan >>. Apa yang terjadi saat deploy dijalankan lagi, dan bagaimana perbaikannya?Lihat jawabannya

   Jawaban:Setiap baris muncul dua kali, dan file-nya membesar di setiap run. Tulis ulang seluruh file dengan >, seperti yang dilakukan deploy situs ini dengan cat > .env, sehingga setiap run menghasilkan file yang sama.

4. 4.Kapan idempotency alami sudah cukup, dan kapan Anda butuh key?Lihat jawabannya

   Jawaban:Jika request menyebut resource-nya dan membawa state lengkapnya, seperti PUT, operasi set, atau upsert pada unique key alami, pengulangan akan berakhir di hasil yang sama. Jika setiap request membuat sesuatu yang baru, misalnya charge atau email, hanya key pilihan klien yang bisa membedakan retry dari request baru.

• desain idempotency key untuk API
• pola idempotent consumer untuk message queue
• desain pengiriman webhook yang andal