Retry dapat menggandakan efek samping jika server sudah memproses request, tetapi responsnya hilang sebelum sampai ke klien. Untuk mencegahnya, endpoint perlu mengenali request yang sama dan mengembalikan hasil sebelumnya, bukan menjalankan operasi bisnis lagi.

Di aplikasi Rust berbasis Topcoat, perlakukan idempotensi sebagai kontrak aplikasi yang ditegakkan oleh penyimpanan bersama dan transaksi. Jangan mengandalkan Topcoat menyediakan idempotency key atau deduplikasi otomatis: periksa dokumentasi repositori untuk API routing dan handler yang sesuai dengan versi yang digunakan. Pola berikut tidak bergantung pada API khusus Topcoat.

Kontrak idempotency key

Klien mengirim key unik untuk satu operasi logis, biasanya melalui header seperti Idempotency-Key. Jika klien mengulangi operasi yang sama setelah timeout atau kegagalan koneksi, klien harus memakai key yang sama. Operasi baru harus memakai key baru.

Tetapkan kontrak yang jelas:

  • Batasi panjang dan format key, lalu tolak key kosong atau tidak valid.
  • Batasi key berdasarkan identitas pemanggil dan operasi, misalnya tenant serta nama endpoint. Jangan gunakan key global lintas pengguna.
  • Simpan hash payload yang dinormalisasi bersama key. Jika key yang sama datang dengan payload berbeda, kembalikan 409 Conflict; jangan menjalankan operasi kedua.
  • Tentukan masa berlaku yang cukup panjang untuk mencakup jendela retry klien. Setelah kedaluwarsa, key lama dapat dibersihkan, tetapi kebijakan harus menjelaskan bahwa retry setelah masa tersebut berpotensi dianggap operasi baru.
  • Simpan status HTTP dan body respons yang perlu diputar ulang. Hindari menyimpan atau memutar ulang header yang sensitif atau berubah-ubah, seperti token autentikasi.

Hash payload harus merepresentasikan makna request, bukan sekadar byte mentah jika urutan field atau representasi JSON dapat berubah tanpa mengubah makna. Normalisasi dilakukan secara konsisten sebelum hashing. Jangan memasukkan kredensial atau data rahasia ke dalam key.

Skema penyimpanan dan transaksi

Gunakan constraint unik di database sebagai penjaga konkurensi. Penyimpanan lokal proses tidak cukup: beberapa instance server harus melihat rekaman key yang sama.

CREATE TABLE idempotency_records (
    tenant_id   TEXT NOT NULL,
    operation   TEXT NOT NULL,
    key         TEXT NOT NULL,
    request_hash BYTEA NOT NULL,
    status_code INTEGER NOT NULL,
    response_body JSONB NOT NULL,
    created_at  TIMESTAMPTZ NOT NULL DEFAULT now(),
    expires_at  TIMESTAMPTZ NOT NULL,
    PRIMARY KEY (tenant_id, operation, key)
);

Contoh ini menyimpan rekaman hasil yang sudah selesai. Nama tipe dan strategi penyimpanan perlu disesuaikan dengan database serta kebutuhan respons aplikasi. Jika respons berisi data yang tidak cocok untuk JSON, simpan representasi yang sesuai.

Alur inti harus mengikat perubahan bisnis dan penyimpanan hasil idempotensi dalam transaksi database yang sama:

  1. Validasi autentikasi, otorisasi, key, dan request sebelum memulai operasi bisnis.
  2. Mulai transaksi dan coba buat rekaman untuk kombinasi tenant, operasi, dan key.
  3. Jika key sudah ada, bandingkan hash. Hash berbeda berarti 409 Conflict; hash sama berarti kembalikan hasil tersimpan.
  4. Jika key baru, jalankan perubahan bisnis, bentuk respons, lalu simpan status dan body respons pada transaksi yang sama.
  5. Commit transaksi sebelum mengirim respons.

Jika proses gagal sebelum commit, perubahan bisnis dan rekaman key sama-sama dibatalkan. Retry dapat mencoba lagi. Jika commit berhasil tetapi koneksi putus sebelum klien menerima respons, retry menemukan hasil tersimpan dan tidak mengulang mutasi.

Menangani request paralel dan integrasi Topcoat

Dua request dengan key sama dapat tiba bersamaan, bahkan di instance berbeda. Constraint unik membuat database menjadi otoritas untuk memilih satu request sebagai pemilik operasi. Request lain harus menunggu hasilnya atau membaca rekaman yang sudah selesai, bergantung pada mekanisme dan tingkat isolasi database.

Implementasikan urutan insert, konflik unik, dan pembacaan ulang sesuai database yang dipakai. Tangani konflik unik sebagai jalur kontrol, bukan sebagai kesalahan server yang langsung dipulangkan ke klien. Jika transaksi pertama rollback, request yang menunggu harus dapat mencoba memperoleh key dan menjalankan operasi. Uji perilaku ini pada database nyata yang digunakan; jangan menyimpulkannya hanya dari mock atau SQLite jika produksi memakai database lain.

Pada lapisan Topcoat, handler cukup menghubungkan ekstraksi request dan konteks autentikasi dengan layanan aplikasi yang menjalankan alur transaksi. Karena API spesifik Topcoat bergantung pada dokumentasi dan versi proyek, gunakan tipe request, respons, dan mekanisme routing yang benar-benar tersedia di repositori. Jangan menambahkan middleware idempotensi seolah-olah fitur tersebut bawaan Topcoat.

Gunakan timeout dan batas waktu tunggu yang masuk akal. Jika request duplikat tidak dapat menunggu transaksi pertama, balas dengan respons sementara yang dapat dicoba ulang, misalnya 503 Service Unavailable dengan kebijakan retry yang terdokumentasi. Jangan mengklaim operasi berhasil sebelum transaksi pertama commit.

Efek samping di luar database

Transaksi database tidak dapat membuat pengiriman email, panggilan API eksternal, atau publikasi pesan menjadi atomik. Jika operasi bisnis memicu efek samping eksternal, tulis catatan outbox dalam transaksi yang sama dengan perubahan bisnis dan hasil idempotensi. Worker mengirimkan catatan tersebut secara terpisah, dengan deduplikasi pada penerima atau sistem tujuan bila tersedia.

Tanpa outbox atau idempotensi pada sistem tujuan, kegagalan setelah sistem eksternal menerima permintaan tetapi sebelum aplikasi mencatat keberhasilan tetap dapat menggandakan efek samping. Jelaskan batas jaminan ini kepada pemanggil dan desain kompensasi bila operasi tidak dapat dideduplikasi.

Masa berlaku, respons, dan debugging

Simpan waktu kedaluwarsa dan bersihkan rekaman lama secara berkala. Penghapusan harus mempertimbangkan jendela retry yang dijanjikan. Jangan menghapus rekaman yang masih dibutuhkan untuk menyelesaikan request paralel atau audit. Jika hasil lama harus tetap dapat dikenali setelah payload respons dibuang, pertahankan tombstone berisi scope, key, hash, dan waktu kedaluwarsa.

Untuk key yang sama dan payload sama, putar ulang status serta body hasil operasi pertama. Untuk key sama dengan payload berbeda, gunakan respons konflik yang konsisten dan jangan mengungkap detail payload tersimpan. Catat metrik untuk key baru, replay, konflik hash, konflik unik, timeout, dan kegagalan transaksi; hindari mencatat key mentah jika berisiko mengandung informasi sensitif.

Uji kegagalan jaringan dan konkurensi

Uji alur dengan database yang sama jenisnya dengan lingkungan produksi. Skenario minimum:

  • Request berhasil dan diulang dengan key serta payload sama: mutasi hanya terjadi sekali dan respons diputar ulang.
  • Request memakai key sama dengan payload berbeda: server mengembalikan konflik dan tidak menjalankan mutasi kedua.
  • Koneksi klien diputus setelah server commit tetapi sebelum respons diterima: retry mengembalikan hasil tersimpan.
  • Transaksi gagal sebelum commit: tidak ada perubahan bisnis atau rekaman hasil yang tertinggal; retry dapat berhasil.
  • Dua request paralel memakai key sama: hanya satu mutasi terjadi dan keduanya memperoleh hasil yang konsisten.
  • Key kedaluwarsa: perilaku mengikuti kebijakan retensi yang didokumentasikan.

Simulasikan putusnya koneksi pada batas waktu yang berbeda. Memutus klien saja tidak selalu membatalkan transaksi server; pastikan aplikasi tetap menyelesaikan atau membatalkan transaksi dengan benar. Periksa jumlah baris bisnis, rekaman idempotensi, dan catatan outbox setelah setiap skenario.

Intinya, Topcoat menangani lapisan HTTP sesuai kemampuan yang didokumentasikan, sedangkan jaminan retry berasal dari kontrak key, constraint unik, dan transaksi yang mencakup mutasi bisnis serta hasil. Inilah yang mencegah retry jaringan mengubah satu operasi logis menjadi beberapa efek samping.