awcms-idempotency

name	awcms-idempotency
description	Terapkan idempotency pada mutation high-risk AWCMS agar aman dari double-submit. Gunakan saat implementasi posting transaksi, cancel/return, transfer approve/ship/receive, cycle count, adjustment, VAT generate, Coretax batch, receipt send, sync push, atau workflow decision. Sesuai doc 10.

AWCMS — Idempotent High-Risk Mutation

Ikuti docs/awcms/10_template_kode_coding_standard.md.

Alur

flowchart TD
  A[Baca Idempotency-Key header] --> B{Key ada di awcms_idempotency_keys?}
  B -- Tidak --> C[Hitung request hash stabil] --> D[Jalankan mutation dalam transaction] --> E[Simpan key + hash + response/resource] --> F[Return response]
  B -- Ya --> G{hash sama?}
  G -- Ya --> H[Return response tersimpan]
  G -- Tidak --> I[409 IDEMPOTENCY_CONFLICT]

Aturan

1. Header Idempotency-Key wajib; jika kosong → 400 IDEMPOTENCY_REQUIRED.
2. Request hash stabil dari body ternormalisasi (urutan field konsisten).
3. Key sama + hash sama → replay response tersimpan (aman).
4. Key sama + hash beda → 409 IDEMPOTENCY_CONFLICT.
5. Simpan status/resource hasil mutation di awcms_idempotency_keys.
6. Kombinasikan dengan stock lock (SELECT ... FOR UPDATE) & transaction wrapper.
7. Deadlock retry harus aman karena idempotency.
8. Retention key: 7–30 hari.
9. Hash WAJIB terikat ke identitas resource — lihat §"Bind hash ke resource id" di bawah, ini bukan opsional dan sudah menyebabkan bug nyata berulang kali.

CRITICAL — bind request hash ke resource id (Issue #750, #795 — recurring 4x)

computeRequestHash(payload: unknown) (src/modules/_shared/idempotency.ts:36) tidak menegakkan apa pun sendiri — ia cuma SHA-256 dari JSON body yang key-nya sudah diurutkan. Ia TIDAK tahu resource mana yang sedang dimutasi. Store key di awcms_idempotency_keys adalah (tenant_id, request_scope, idempotency_key), dan request_scope itu dibagi rata di seluruh resource bertipe sama dalam satu tenant (bukan per-resource) — jadi kalau computeRequestHash hanya di-hash dari body mentah (atau body kosong {} untuk endpoint restore/cancel/commit yang tidak punya field lain), maka Idempotency-Key yang sama dipakai ulang klien untuk DUA resource berbeda dengan tipe endpoint sama akan mereplay respons resource pertama untuk request yang seharusnya memutasi resource kedua — silent no-op yang terlihat seperti sukses (200 dengan body resource A), padahal resource B tidak pernah termutasi.

Bug class ini muncul 4 kali di repo ini: Issue #750 (reference-data, PR #783, 3 ronde perbaikan), lalu Issue #795 menemukan pola yang sama BELUM diperbaiki di modul lain (document-infrastructure PR #798, business-scope/organization-structure PR #801, identity-access/data-lifecycle/reports PR lain) lewat grep -rn "computeRequestHash(" src/pages/api/ menyeluruh — audit pertama yang hanya menyasar endpoint yang "kelihatan jelas" (body kosong) melewatkan endpoint PATCH/action lain yang body-nya ADA tapi tidak menyertakan id dari path param.

Pola BENAR

Selalu sertakan identitas resource (biasanya id/[key]/relationId dari path param) DAN literal action string eksplisit di payload yang di-hash — jangan hash body mentah begitu saja, dan jangan hash {} untuk endpoint yang path-nya sudah membawa id:

// src/pages/api/v1/tenant/domains/[id]/set-primary.ts:68 — body kosong, id dari path
const requestHash = computeRequestHash({ domainId, action: "set_primary" });

// src/pages/api/v1/data-lifecycle/legal-holds/[id]/release.ts:69-73 — body ADA tapi
// tidak membawa id sendiri, jadi id dari path harus ditambahkan manual
const requestHash = computeRequestHash({
  ...body,
  id: holdId,
  action: "release"
});

Aturan praktis: kalau endpoint punya path param [id]/[key]/[relationId], path param itu wajib masuk ke object yang di-hash (spread body dulu lalu override/tambahkan id, supaya field id di body — kalau ada — tidak diam-diam menang). action literal wajib ada supaya dua endpoint berbeda pada resource yang sama (mis. restore vs delete) tidak collide walau kebetulan body-nya identik ({}).

Checklist verifikasi sebelum PR

• Grep seluruh tree yang di-assign, bukan cuma daftar endpoint yang "kelihatan mencurigakan": grep -rn "computeRequestHash(" src/pages/api/v1/<module>/. Jangan percaya daftar endpoint bernama sebagai lengkap — Issue #795 sendiri butuh re-grep independen karena pass pertama hanya menyasar 7 dari 11 endpoint yang rentan.
• Untuk tiap hit: apakah payload yang di-hash sudah menyertakan resource id dari path DAN literal action? Endpoint create murni (tidak ada resource pra-eksisting untuk diikat, mis. POST /documents) TIDAK rentan — tidak perlu id.
• Endpoint index-level yang mengidentifikasi resource lewat kombinasi field yang SUDAH ada di body mentah (mis. scopeType+scopeId+sequenceKey pada sequences/revise) tidak perlu perubahan — tapi verifikasi ini secara eksplisit per endpoint, jangan asumsikan.
• Test adversarial: dua resource berbeda, Idempotency-Key yang SAMA dipakai ulang pada keduanya secara berurutan → request kedua harus benar-benar memutasi resource kedua (bukan replay respons resource pertama). Contoh nyata: tests/integration/document-infrastructure.integration.test.ts.

Lihat src/modules/document-infrastructure/README.md §"Catatan idempotency-key resource binding" untuk worked example lengkap lintas 11 endpoint satu modul.

Endpoint wajib idempotency

POS posting, cancel/return, profiles/resolve|links|merge-requests, warehouse transfer approve/ship/receive, cycle-count, stock-adjustment, VAT invoice generate, Coretax batch, receipt send, sync push, workflow decision, blog post lifecycle actions (blog_post_publish/_schedule/_archive/_restore/_purge, blog_revision_restore — Issue #538/#541), POST /api/v1/email/announcements (Issue #497). Daftar ini tumbuh per modul baru — cek skill modul terkait (mis. awcms-blog-content, awcms-email) untuk endpoint idempotency-gated terbaru, jangan asumsikan daftar di atas lengkap.

Verifikasi (test)

• Same key + same request → satu resource, response konsisten.
• Same key + different request → 409.
• Double submit paralel → tidak dobel.
• Rollback saat error → tidak ada partial state.
• Double submit paralel dengan Idempotency-Key sama persis + payload sama (retry jaringan client) → kedua request 200 dengan response identik (replay), bukan salah satunya 409 — aturan 3 di atas ("hash sama → replay") tetap tegak walau kalah race. Double submit paralel dengan key sama tapi payload beda → satu pemenang (200), satu 409 IDEMPOTENCY_CONFLICT bersih (bukan raw constraint error/500), sesuai aturan 4. Ditegakkan sekali di helper bersama, bukan per-endpoint: saveIdempotencyRecord (src/modules/_shared/idempotency.ts) INSERT ... ON CONFLICT DO NOTHING RETURNING id; kalau kalah, SELECT ulang row pemenang (dijamin sudah committed — ON CONFLICT hanya trigger melawan row yang sudah commit) dan bandingkan request_hash-nya dengan punya kita sebelum melempar IdempotencyRaceLostError (bawa replay kalau hash sama, null kalau beda). withTenant (src/lib/database/tenant-context.ts) menangkapnya di satu titik, rollback transaksi loser, log idempotency.race_lost (key di-hash SHA-256, bukan raw — doc 10 masking), lalu replay response pemenang atau 409 — otomatis berlaku untuk semua konsumen tabel awcms_idempotency_keys tanpa ubah route masing-masing. Contoh test: tests/integration/tenant-domain-api.integration.test.ts's "set-primary under concurrent SAME Idempotency-Key + SAME payload" (replay, tepat satu audit event + satu row idempotency key) dan "verify under concurrent SAME Idempotency-Key + DIFFERENT payload" (409 bersih, domain berbeda dipakai justru untuk menghindari race index primary-dedup set-primary sendiri yang tidak terkait).