Queue Worker Andal: Locking, Retry, dan Konsistensi Cache

Queue worker andal tidak cukup hanya bisa mengambil job dari antrean dan menjalankannya. Dalam sistem nyata, job bisa diproses lebih dari sekali, worker bisa crash di tengah proses, cache bisa menjadi stale, dan retry yang salah justru memperparah beban sistem. Karena itu, desain queue-worker harus mengasumsikan failure is normal, lalu membatasi dampaknya dengan idempotensi, timeout yang tepat, locking yang hati-hati, dan strategi konsistensi data yang jelas.

Artikel ini membahas pendekatan praktis untuk membangun pipeline queue-worker yang tahan terhadap at-least-once delivery, race condition, poison message, dan requeue storm. Fokusnya bukan pada framework tertentu, melainkan pola yang umum dipakai di backend modern.

Prinsip dasar: anggap queue bersifat at-least-once delivery

Banyak sistem antrean menjamin at-least-once delivery, bukan exactly-once. Artinya, satu job bisa terkirim lagi jika worker gagal meng-acknowledge sebelum batas waktu, koneksi putus, atau broker tidak yakin job sudah selesai. Implikasinya penting: handler job harus aman dijalankan lebih dari sekali.

Kesalahan umum adalah mengandalkan asumsi bahwa satu pesan pasti diproses sekali saja. Begitu asumsi ini salah, efeknya bisa serius: pembayaran tertagih dua kali, email terkirim berulang, stok berkurang ganda, atau cache berisi state yang bertentangan.

Konsekuensi desain dari at-least-once

• Idempotensi wajib pada operasi yang punya efek samping.
• Visibility timeout harus lebih besar dari waktu proses normal, tetapi tidak terlalu besar sehingga job gagal lama baru bisa diproses ulang.
• Retry policy harus membedakan error sementara dan error permanen.
• State change di database dan perubahan cache harus dirancang agar konsisten meski job dijalankan ulang.

Idempotensi: fondasi utama queue worker andal

Idempotensi berarti menjalankan operasi yang sama berkali-kali menghasilkan efek akhir yang sama. Dalam konteks queue, ini adalah perlindungan utama terhadap duplicate delivery.

Kapan idempotensi dibutuhkan

Idempotensi dibutuhkan terutama untuk job yang:

• mengubah status order atau payment,
• mengirim email atau notifikasi,
• menulis ke layanan eksternal,
• mengurangi stok, saldo, atau kuota,
• mengisi atau menghapus cache yang bergantung pada state database.

Pola implementasi idempotensi

Pola paling umum adalah memberi setiap job atau operasi bisnis sebuah idempotency key. Kunci ini disimpan di storage yang konsisten, biasanya database transaksional, bersama status prosesnya.

function processPaymentJob(job) {
  // job.idempotencyKey harus unik untuk satu intent bisnis
  beginTransaction()

  existing = findProcessedOperation(job.idempotencyKey)
  if (existing) {
    commit()
    return existing.result
  }

  order = findOrderForUpdate(job.orderId)
  if (order.paymentStatus == "paid") {
    recordProcessedOperation(job.idempotencyKey, { status: "already_paid" })
    commit()
    return
  }

  result = chargePaymentProvider({
    paymentRef: job.paymentRef,
    amount: order.amount
  })

  if (result.success) {
    markOrderPaid(order.id)
    recordProcessedOperation(job.idempotencyKey, { status: "paid" })
  } else {
    rollback()
    throw TemporaryOrPermanentError(result)
  }

  commit()
}

Mengapa pola ini bekerja:

• Jika job yang sama masuk lagi, sistem bisa mendeteksi bahwa intent bisnis tersebut sudah diproses.
• Jika worker crash setelah operasi eksternal berhasil tetapi sebelum acknowledge queue, job akan diproses ulang namun tidak menghasilkan efek ganda.
• Jika state final bisa dicek secara deterministik, duplicate execution menjadi aman.

Kesalahan umum pada idempotensi

• Menggunakan timestamp sebagai kunci unik sehingga duplicate nyata tidak terdeteksi.
• Menyimpan marker idempotensi setelah efek samping tanpa transaksi yang aman.
• Mengandalkan cache untuk deduplikasi; cache cocok untuk optimasi, bukan sumber kebenaran untuk efek bisnis penting.
• Idempotensi hanya di level worker padahal layanan eksternal juga bisa menerima request ganda.

Jika integrasi ke penyedia eksternal mendukung idempotency key, gunakan juga di sana. Idempotensi paling kuat terjadi saat diterapkan di setiap boundary yang menghasilkan efek samping.

Visibility timeout, ack, dan batas waktu proses

Visibility timeout adalah jendela waktu ketika sebuah job dianggap sedang diproses dan tidak boleh diambil worker lain. Jika worker tidak menyelesaikan dan meng-acknowledge job sebelum timeout habis, job bisa muncul lagi untuk diproses ulang.

Menentukan nilai timeout

Timeout yang terlalu pendek menyebabkan duplicate processing walaupun worker sebenarnya masih sehat. Timeout yang terlalu panjang membuat job gagal tertahan lama sebelum bisa dicoba ulang. Pilih nilai berdasarkan:

• waktu proses normal pada persentil tinggi, bukan rata-rata,
• waktu terburuk untuk dependency eksternal yang masih dianggap wajar,
• ruang untuk jitter jaringan dan GC pause jika runtime mengalaminya,
• mekanisme heartbeat atau lease extension jika broker mendukungnya.

Pola aman untuk long-running job

Jika ada job yang kadang berjalan lama, pertimbangkan salah satu dari dua pendekatan:

1. Perpanjang lease/visibility secara periodik selama worker masih hidup dan membuat progres.
2. Pecah job besar menjadi job kecil agar waktu proses per unit lebih pendek dan mudah diretry.

Memecah job biasanya lebih sederhana untuk observabilitas dan failure handling. Long-running job rentan terhadap duplicate delivery, deploy interruption, dan kesulitan rollback.

Rule of thumb operasional

• Acknowledge job setelah state penting tersimpan dengan aman.
• Jangan acknowledge sebelum efek samping kritis selesai, kecuali ada mekanisme kompensasi yang jelas.
• Jika worker crash setelah commit database tetapi sebelum ack, duplicate run harus aman lewat idempotensi.

Retry, backoff, dan kapan memakai dead-letter queue

Tidak semua kegagalan layak diperlakukan sama. Retry efektif untuk error sementara seperti timeout jaringan, rate limit, atau service dependency yang sesaat tidak tersedia. Tetapi retry justru merugikan jika error bersifat permanen, misalnya payload invalid, referensi data tidak ditemukan, atau invariant bisnis dilanggar.

Bedakan error sementara dan permanen

• Temporary/transient: timeout, koneksi putus, HTTP 429, gangguan dependency, lock contention sesaat.
• Permanent: schema payload salah, ID order tidak valid, state bisnis tidak mungkin diproses, bug deterministik pada data tertentu.

Strategi retry yang lebih aman

Gunakan exponential backoff dengan jitter agar retry dari banyak worker tidak menabrak dependency pada saat yang sama. Retry instan tanpa jeda sering memicu requeue storm, yaitu ledakan job yang gagal dan masuk lagi secara agresif sampai mengantri jauh lebih cepat daripada kemampuan sistem memprosesnya.

retry delays: 10s, 30s, 2m, 5m, 15m
+ random jitter untuk menyebar beban

Kapan job dipindahkan ke dead-letter queue

Dead-letter queue (DLQ) cocok untuk job yang gagal berulang kali dan butuh inspeksi manual atau pipeline remediasi terpisah. Jangan biarkan job permanen gagal berputar tanpa akhir di antrean utama.

Pindahkan ke DLQ jika:

• sudah melewati batas retry maksimum,
• error diklasifikasikan permanen,
• payload mencurigakan atau tidak bisa diparse dengan aman,
• job berpotensi merusak sistem jika terus dicoba.

Trade-off retry vs DLQ

• Retry agresif meningkatkan peluang pulih otomatis, tetapi bisa menambah beban dan memperlambat job sehat.
• DLQ cepat mengurangi gangguan ke antrean utama, tetapi menambah beban operasional karena butuh investigasi dan replay.

Pendekatan yang baik adalah retry terbatas untuk error sementara, lalu kirim ke DLQ jika problem belum selesai.

Distributed locking dan race condition: gunakan secukupnya

Distributed locking berguna saat dua worker atau lebih berpotensi memproses resource yang sama pada waktu bersamaan. Contoh: dua job untuk order yang sama, sinkronisasi saldo akun, atau refresh cache yang mahal.

Namun lock bukan pengganti idempotensi. Lock mengurangi konkurensi, sementara idempotensi melindungi dari duplicate execution dan retry. Keduanya menyelesaikan masalah yang berbeda.

Kapan lock diperlukan

• Ketika dua job pada resource yang sama tidak boleh overlap.
• Ketika operasi tidak bisa dibuat sepenuhnya idempoten di level bisnis.
• Ketika ada update berurutan yang harus mempertahankan ordering tertentu.

Pilihan implementasi lock

• Database row lock cocok jika semua state penting ada di database yang sama dan transaksi singkat.
• Lease berbasis key-value store cocok untuk koordinasi lintas worker/proses, selama ada TTL dan token kepemilikan lock.
• Partitioning by key sering lebih sederhana: semua job dengan kunci yang sama diarahkan ke shard/consumer yang sama, sehingga konkurensi berkurang tanpa lock eksplisit.

Masalah umum pada distributed lock

• Lock tanpa TTL bisa macet permanen ketika worker crash.
• Melepas lock yang bukan miliknya jika implementasi tidak memakai token/fencing.
• Durasi lock terlalu pendek sehingga lock habis saat job masih berjalan dan worker lain masuk.
• Mengunci terlalu luas, misalnya satu lock global untuk semua order, yang justru membunuh throughput.

Jika satu transaksi database dengan row-level locking sudah cukup, itu biasanya lebih mudah dipahami daripada menambah distributed lock eksternal.

Konsistensi cache setelah job sukses atau gagal

Cache invalidation sering menjadi sumber bug yang lebih sulit dilacak daripada queue itu sendiri. Setelah job sukses, data utama mungkin benar di database tetapi cache tetap menampilkan state lama. Setelah job gagal di tengah jalan, cache bahkan bisa memuat state yang tidak pernah benar-benar committed.

Prinsip utama: database adalah source of truth

Untuk state bisnis penting, commit ke database dulu. Setelah itu, baru lakukan salah satu strategi cache berikut:

• Invalidate on write: hapus cache terkait setelah commit, sehingga pembacaan berikutnya mengisi ulang dari database.
• Write-through/update cache: perbarui cache setelah commit, cocok jika pola akses membutuhkan latensi baca rendah dan format cache jelas.
• Versioned cache key: simpan versi atau updated_at untuk mencegah pembaca melihat campuran state lama dan baru.

Mengapa invalidasi sering lebih aman

Invalidasi umumnya lebih sederhana daripada menulis ulang seluruh representasi cache. Jika struktur cache diturunkan dari banyak tabel atau agregasi, memperbaruinya secara parsial rentan salah. Menghapus cache setelah commit membiarkan pembacaan berikutnya membangun state yang konsisten.

Urutan yang aman

1. Mulai transaksi.
2. Validasi bahwa job masih relevan.
3. Ubah state database.
4. Commit transaksi.
5. Invalidate atau update cache.
6. Acknowledge job.

Urutan ini penting. Jika cache diubah sebelum commit, lalu transaksi gagal, cache menjadi bohong. Jika job di-ack terlalu awal, sistem kehilangan kesempatan untuk memulihkan kegagalan setelah commit parsial.

Bagaimana jika cache invalidation gagal

Kegagalan invalidasi cache sebaiknya diperlakukan sebagai masalah operasional yang terlihat jelas, bukan disembunyikan. Beberapa opsi:

• retry invalidasi secara terpisah,
• gunakan TTL pendek pada key kritis sebagai pagar tambahan,
• simpan event post-commit ke outbox untuk diproses worker khusus invalidasi cache,
• pasang metrik untuk mendeteksi mismatch antara database dan cache.

Untuk arsitektur yang lebih kompleks, pola transactional outbox sering membantu. State database di-commit bersama record event lokal, lalu publisher/worker lain mengirim event dan melakukan invalidasi secara andal tanpa bergantung pada keberhasilan jaringan di dalam transaksi utama.

Contoh alur praktis: order dan payment processing

Skenario

Pengguna menyelesaikan checkout. Sistem membuat order dengan status pending_payment, lalu menerbitkan job CapturePayment. Tantangannya:

• job bisa diproses lebih dari sekali,
• provider payment bisa timeout padahal charge sebenarnya berhasil,
• dua worker bisa mengambil job yang sama jika visibility timeout habis,
• cache order summary harus konsisten setelah payment sukses atau gagal.

Alur yang disarankan

1. API membuat order dan menyimpan payment_intent_id atau idempotency key bisnis.
2. Job CapturePayment(orderId, idempotencyKey) masuk ke queue.
3. Worker mengambil job, lalu memuat order dengan proteksi konkurensi yang sesuai.
4. Jika order sudah paid, worker selesai tanpa efek tambahan.
5. Jika belum, worker memanggil provider payment dengan idempotency key yang sama.
6. Jika provider mengembalikan sukses, worker commit status order menjadi paid.
7. Setelah commit, worker invalidate cache order, cache cart, atau agregat terkait.
8. Baru setelah itu worker acknowledge job.

Kasus timeout ke provider

Jika request ke provider timeout, jangan langsung menganggap charge gagal permanen. Bisa jadi provider menerima dan memproses request, tetapi responsnya hilang. Dalam kasus seperti ini:

• jangan menandai order langsung gagal final tanpa verifikasi,
• retry dengan idempotency key yang sama, atau
• jalankan job rekonsiliasi yang menanyakan status transaksi ke provider.

Ini contoh klasik mengapa idempotensi dan rekonsiliasi lebih penting daripada sekadar retry membabi buta.

Contoh pseudo-code yang lebih lengkap

function handleCapturePayment(job) {
  lock = acquireLease("order:" + job.orderId, ttl=60s)
  if (!lock) {
    retryWithBackoff(job)
    return
  }

  try {
    beginTransaction()

    order = findOrderForUpdate(job.orderId)
    if (!order) {
      commit()
      moveToDLQ(job, "order_not_found")
      return
    }

    if (order.status == "paid") {
      commit()
      return
    }

    processed = findProcessedOperation(job.idempotencyKey)
    if (processed) {
      commit()
      return
    }

    commit()

    result = paymentProvider.capture({
      paymentIntentId: order.paymentIntentId,
      idempotencyKey: job.idempotencyKey
    })

    beginTransaction()
    order = findOrderForUpdate(job.orderId)

    if (result.success) {
      markOrderPaid(order.id)
      recordProcessedOperation(job.idempotencyKey, { status: "success" })
      commit()
      invalidateCache("order:" + order.id)
      invalidateCache("order_summary:user:" + order.userId)
      ack(job)
      return
    }

    rollback()

    if (result.temporaryFailure) {
      retryWithBackoff(job)
    } else {
      moveToDLQ(job, result.errorCode)
    }
  } finally {
    releaseLease(lock)
  }
}

Contoh di atas bukan template universal, tetapi menunjukkan prinsip penting:

• cek state final sebelum melakukan efek samping,
• pisahkan error sementara dan permanen,
• jangan ubah cache sebelum commit,
• anggap duplicate execution sebagai hal normal.

Tabel gejala, penyebab, dan mitigasi

Checklist operasional untuk queue worker andal

Metrik yang wajib dipantau

• Queue depth: jumlah job menunggu.
• Job age / lag: umur job tertua atau waktu tunggu sebelum diproses.
• Processing time: distribusi durasi proses, bukan hanya rata-rata.
• Success rate dan failure rate.
• Retry count per jenis job dan per error class.
• DLQ inflow: jumlah job masuk ke dead-letter queue.
• Duplicate detection rate: seberapa sering idempotency key terpakai ulang.
• Lock contention: frekuensi gagal memperoleh lock.
• Cache invalidation failure atau mismatch rate jika ada verifikasi.

Alert yang berguna

• queue lag melewati SLO,
• retry rate melonjak tiba-tiba,
• DLQ bertambah terus,
• rasio timeout dependency eksternal naik,
• jumlah duplicate processing meningkat,
• backlog bertambah meski worker count tetap tinggi, menandakan worker macet atau dependency bottleneck.

Backpressure dan pengendalian beban

Worker yang andal tidak selalu berarti memproses secepat mungkin. Saat dependency lambat, sistem perlu backpressure agar tidak menghancurkan dirinya sendiri.

• Batasi concurrency per jenis job.
• Gunakan rate limit untuk panggilan ke layanan eksternal.
• Terapkan circuit breaker agar error berulang tidak memicu retry berantai.
• Pisahkan antrean cepat dan lambat agar job berat tidak memblokir job ringan.
• Jika perlu, turunkan throughput sengaja untuk menjaga latensi dan error rate tetap terkendali.

Poison message dan requeue storm

Poison message adalah job yang akan gagal terus karena payload atau state-nya rusak. Jika job semacam ini terus diretry tanpa batas, antrean utama ikut rusak. Karena itu:

• beri batas retry yang ketat,
• log context yang cukup untuk investigasi,
• sediakan tooling untuk inspect, replay, atau discard dari DLQ,
• validasi payload sedini mungkin sebelum job mahal dijalankan.

Requeue storm sering muncul saat banyak worker melakukan retry serentak ke dependency yang sedang down. Gejalanya adalah CPU dan I/O tinggi, antrean tidak berkurang, dan log error membanjir. Mitigasinya: backoff + jitter, global rate limiting, dan penghentian sementara konsumsi job tertentu jika dependency kritis gagal total.

Rollout worker yang aman

• Drain in-flight jobs saat deploy jika memungkinkan.
• Pastikan shutdown worker bersifat graceful: berhenti mengambil job baru, selesaikan atau lepaskan lease job aktif dengan aman.
• Gunakan deployment bertahap agar bug pada handler baru tidak merusak seluruh antrean.
• Jika format payload berubah, jaga kompatibilitas maju dan mundur selama masa transisi.
• Version-kan handler atau event schema bila perubahan tidak kompatibel tak bisa dihindari.

Pitfall yang paling sering terjadi

• Mencampur retry teknis dan retry bisnis. Retry teknis untuk timeout tidak sama dengan keputusan bisnis seperti mencoba charge ulang kartu di lain waktu.
• Menaruh seluruh logika dalam satu job raksasa. Job besar sulit diobservasi, sulit diretry, dan rawan timeout.
• Menganggap lock menyelesaikan semuanya. Lock tidak menggantikan idempotensi.
• Menggunakan cache sebagai sumber kebenaran untuk status payment atau order.
• Tidak memiliki jalur rekonsiliasi untuk dependency eksternal yang bisa sukses tanpa respons yang jelas.

Penutup

Membangun queue worker andal berarti menerima bahwa duplicate delivery, timeout, race condition, dan kegagalan parsial akan terjadi. Solusi yang paling efektif bukan satu fitur tunggal, melainkan kombinasi disiplin desain: idempotensi untuk efek samping, visibility timeout yang realistis, retry dengan backoff, DLQ untuk kegagalan permanen, locking secukupnya, dan strategi cache yang tunduk pada source of truth di database.

Jika harus memulai dari yang paling penting, prioritaskan tiga hal ini terlebih dahulu: buat handler idempoten, klasifikasikan retry dengan benar, dan ubah cache hanya setelah commit data utama. Tiga keputusan itu biasanya menghilangkan sebagian besar bug queue yang paling mahal dalam produksi.