Banyak sistem backend tumbuh dengan pola queue worker yang berbeda-beda: satu service punya retry sendiri, service lain memakai lock khusus, sebagian job mengandalkan cache, sebagian lagi mengulang tanpa batas. Hasilnya bukan sekadar variasi implementasi, tetapi variasi perilaku operasional. Saat insiden terjadi, tim harus mengingat aturan berbeda untuk setiap worker, memahami retry yang tidak konsisten, dan menebak apakah job aman dijalankan ulang atau tidak.

Cara paling efektif untuk mengurangi kompleksitas itu adalah menetapkan kontrak retry yang seragam untuk semua job asynchronous. Kontrak ini bukan berarti semua job identik, tetapi semua job tunduk pada bentuk eksekusi yang sama: ada status job yang jelas, idempotency key, kebijakan retry eksplisit, timeout, visibility timeout, locking yang konsisten, deduplication, dan metrik minimum. Dengan begitu, variasi bisnis tetap boleh ada, tetapi variasi operasional ditekan.

Artikel ini fokus pada keputusan arsitektur dan operasi: bagaimana merancang job envelope, menghindari double processing, menangani poison message, mencegah cache stampede, mengurangi lost update, dan menjaga konsistensi data antar worker tanpa menambah terlalu banyak checker, flag, dan pengecualian.

Mengapa terlalu banyak variasi queue worker menjadi masalah

Masalah utamanya bukan karena ada queue, lock, atau cache. Masalah muncul ketika tiap komponen membentuk aturan sendiri-sendiri. Satu job retry 3 kali dengan jeda tetap, job lain exponential backoff, job ketiga tidak punya timeout yang jelas, job keempat mengandalkan cache lock yang TTL-nya tidak sinkron dengan waktu proses. Dari luar terlihat masih berjalan, tetapi secara operasional sistem menjadi rapuh.

Gejala yang sering muncul

  • Double processing: job yang sama dikerjakan dua worker karena ack terlambat, lock kedaluwarsa terlalu cepat, atau dedup tidak konsisten.
  • Poison message: payload tertentu selalu gagal, tetapi terus di-retry dan memenuhi queue.
  • Cache stampede: banyak worker gagal membaca data yang sama lalu memukul database atau API upstream secara bersamaan.
  • Lost update: dua worker menulis perubahan ke entitas yang sama tanpa pengendalian versi atau idempotensi.
  • Inconsistent recovery: saat worker restart atau node mati, sebagian job dianggap gagal, sebagian menggantung, sebagian jalan ulang tanpa jejak yang seragam.

Jika setiap tim menyelesaikan masalah ini dengan cara sendiri, jumlah aturan operasional meningkat lebih cepat daripada kompleksitas bisnisnya. Itulah sebabnya satu kontrak eksekusi job yang seragam sering lebih berharga daripada menambah library atau pola baru.

Apa isi kontrak retry yang seragam

Kontrak retry yang seragam adalah seperangkat field, status, dan aturan runtime yang berlaku untuk setiap job. Implementasi teknisnya bisa berbeda menurut stack, tetapi semantik dasarnya harus tetap sama.

1. Status job yang eksplisit

Minimal, job perlu status yang bisa dipahami manusia dan sistem:

  • queued: job sudah diterima dan menunggu diproses.
  • running: worker sedang memproses job.
  • succeeded: eksekusi selesai dan efek samping dianggap final.
  • retry_scheduled: eksekusi gagal sementara dan akan dijadwalkan ulang.
  • failed: job gagal permanen atau retry habis.
  • dead_lettered: job dipindahkan ke antrian khusus untuk investigasi/manual recovery.

Status seperti ini membantu observabilitas, debugging, dan otomasi. Yang penting bukan nama persisnya, melainkan status transisinya jelas dan konsisten.

2. Idempotency key

Idempotency key menjawab pertanyaan penting: jika job yang sama diproses ulang, apakah efek sampingnya tetap aman? Untuk operasi seperti membuat invoice, mengirim email transaksi, atau menarik saldo, kunci ini wajib diperlakukan sebagai bagian inti kontrak, bukan fitur tambahan.

Prinsip praktisnya:

  • Key harus stabil untuk satu efek bisnis yang sama.
  • Key tidak boleh bergantung pada timestamp acak jika tujuan Anda adalah mencegah duplikasi.
  • Penyimpanan hasil idempotensi harus hidup lebih lama daripada rentang retry realistis.
  • Idempotensi sebaiknya dicek sebelum efek samping eksternal dilakukan.

3. Retry policy yang eksplisit

Retry harus berbasis kategori kegagalan, bukan sekadar “gagal lalu coba lagi”. Bedakan setidaknya tiga jenis error:

  • Transient: timeout jaringan, upstream 503, koneksi sementara putus. Layak di-retry.
  • Permanent: payload invalid, resource tidak akan pernah ada, pelanggaran aturan bisnis tetap. Jangan di-retry tanpa perubahan data.
  • Unknown: error tak terklasifikasi. Bisa di-retry terbatas sambil dicatat sebagai anomali.

Retry policy yang seragam umumnya memuat:

  • batas percobaan maksimum,
  • strategi backoff,
  • jitter untuk menghindari lonjakan serempak,
  • daftar error yang bisa di-retry,
  • aturan pindah ke dead letter queue.

4. Timeout dan visibility timeout

Execution timeout membatasi berapa lama handler boleh berjalan. Visibility timeout menentukan berapa lama pesan dianggap sedang diproses sebelum boleh terlihat lagi oleh worker lain. Keduanya harus disetel selaras.

Kesalahan umum adalah visibility timeout lebih pendek daripada waktu proses normal. Akibatnya, job yang masih berjalan muncul lagi dan diproses worker kedua. Sebaliknya, jika visibility timeout terlalu panjang, job gagal akan lama kembali ke queue dan memperlambat pemulihan.

Aturan praktis: visibility timeout biasanya harus lebih besar dari execution timeout ditambah buffer untuk ack, commit status, dan latensi jaringan.

5. Locking dan deduplication

Locking dan deduplication menyelesaikan masalah berbeda:

  • Locking membatasi konkurensi atas resource tertentu, misalnya satu order hanya boleh diproses oleh satu worker pada satu waktu.
  • Deduplication mencegah dua pesan ekuivalen masuk atau diproses sebagai pekerjaan berbeda.

Jangan mencampur keduanya. Banyak sistem menaruh semua tanggung jawab pada lock, lalu heran ketika duplikasi tetap terjadi karena pesan sudah telanjur masuk dua kali dengan payload sedikit berbeda.

6. Metrik minimum

Tanpa metrik minimum, kontrak seragam hanya bagus di dokumen. Setidaknya ukur:

  • jumlah job masuk, sukses, gagal, dan dead-lettered,
  • latensi antrean: waktu dari enqueue sampai mulai diproses,
  • durasi eksekusi handler,
  • jumlah retry per job type,
  • jumlah timeout, lock contention, dan dedup hit,
  • umur pesan tertua di queue.

Metrik ini cukup untuk membedakan bottleneck antrean, kegagalan upstream, dan masalah desain job.

Contoh desain payload dan job envelope

Daripada membiarkan setiap producer mengirim format sendiri, gunakan job envelope yang seragam. Payload bisnis tetap bebas, tetapi metadata eksekusi harus standar.

{
  "job_id": "job_01HXYZ...",
  "job_type": "invoice.generate",
  "tenant_id": "tenant_123",
  "payload": {
    "order_id": "ord_987",
    "customer_id": "cus_456"
  },
  "idempotency_key": "invoice.generate:ord_987",
  "attempt": 1,
  "max_attempts": 5,
  "scheduled_at": "2026-08-17T10:00:00Z",
  "created_at": "2026-08-17T09:58:00Z",
  "trace_id": "trc_abcd1234",
  "timeout_seconds": 30,
  "visibility_timeout_seconds": 45,
  "lock_key": "order:ord_987",
  "dedup_key": "invoice.generate:ord_987",
  "retry_policy": {
    "backoff": "exponential",
    "base_delay_seconds": 5,
    "max_delay_seconds": 300,
    "jitter": true
  }
}

Beberapa catatan penting:

  • job_id untuk identitas teknis satu pesan.
  • idempotency_key untuk identitas efek bisnis.
  • dedup_key boleh sama dengan idempotency key, tetapi secara konsep fungsinya berbeda.
  • lock_key opsional dan hanya dipakai jika job menyentuh resource yang butuh eksklusivitas.
  • attempt perlu dikelola sistem, bukan dipercaya mentah dari producer.

Contoh pseudocode worker

func handle(job Envelope) error {
    markStatus(job.JobID, "running")

    if isDuplicate(job.DedupKey) {
        markStatus(job.JobID, "succeeded")
        return nil
    }

    lock := acquireLock(job.LockKey, job.VisibilityTimeout)
    if job.LockKey != "" && !lock.OK {
        return retryable("lock contention")
    }
    defer lock.Release()

    if alreadyCompleted(job.IdempotencyKey) {
        markStatus(job.JobID, "succeeded")
        return nil
    }

    ctx := withTimeout(job.TimeoutSeconds)
    err := processBusinessLogic(ctx, job.Payload)
    if err == nil {
        recordIdempotentResult(job.IdempotencyKey)
        markStatus(job.JobID, "succeeded")
        return nil
    }

    if isPermanent(err) {
        markStatus(job.JobID, "failed")
        return err
    }

    if job.Attempt >= job.MaxAttempts {
        moveToDeadLetter(job, err)
        markStatus(job.JobID, "dead_lettered")
        return err
    }

    rescheduleWithBackoff(job)
    markStatus(job.JobID, "retry_scheduled")
    return err
}

Pseudocode ini menunjukkan urutan penting: cek dedup, ambil lock bila perlu, cek idempotensi, jalankan bisnis, klasifikasikan error, lalu transisikan status secara konsisten.

Masalah nyata yang harus ditangani kontrak ini

Double processing

Double processing biasanya muncul dari kombinasi ack yang terlambat, worker crash setelah efek samping dilakukan, atau visibility timeout yang terlalu pendek. Kontrak seragam menguranginya dengan tiga lapis:

  1. idempotency key untuk menjamin efek akhir tetap satu,
  2. visibility timeout yang selaras dengan durasi kerja,
  3. lock key bila ada resource yang tidak aman diproses paralel.

Penting dipahami: queue dengan at-least-once delivery tidak menjanjikan pesan hanya dikirim sekali. Karena itu, asumsi dasar worker harus selalu “pesan bisa datang ulang”.

Poison message

Pesan beracun adalah job yang secara konsisten gagal karena data rusak, bug handler, atau ketergantungan yang tidak cocok dengan payload tertentu. Jika job seperti ini terus di-retry, ia bisa menghabiskan kapasitas worker dan menunda job sehat.

Solusi praktis:

  • klasifikasikan error permanen seawal mungkin,
  • batasi jumlah retry,
  • pindahkan ke dead letter queue,
  • simpan konteks minimum: error terakhir, attempt terakhir, timestamp, trace id, dan ringkasan payload.

Kesalahan umum adalah memperlakukan semua exception sebagai transient.

Cache stampede

Saat banyak worker membutuhkan data yang sama, kegagalan cache atau cache miss bisa membuat semuanya menyerbu database atau API upstream. Ini tidak selalu masalah queue, tetapi sering dipicu oleh fan-out worker.

Kontrak seragam membantu dengan:

  • lock per kunci data saat melakukan refill cache,
  • jitter pada retry agar worker tidak memukul upstream secara serempak,
  • membatasi konkurensi job type tertentu,
  • menghindari retry agresif untuk kegagalan yang sama.

Jika cache dipakai untuk lock, berhati-hatilah. Cache TTL yang terlalu pendek bisa membuat lock lenyap sebelum handler selesai.

Lost update dan konsistensi data antar worker

Dua worker bisa membaca versi data yang sama lalu menulis hasil berbeda; penulisan terakhir menang dan perubahan sebelumnya hilang. Lock bisa membantu, tetapi tidak cukup untuk semua kasus, terutama bila update melintasi database dan layanan eksternal.

Pendekatan yang lebih aman biasanya menggabungkan:

  • optimistic concurrency atau version check di database,
  • idempotent write untuk operasi keluar,
  • outbox/inbox pattern bila perlu sinkronisasi antar batas layanan,
  • lock key hanya untuk resource yang benar-benar butuh serialisasi.

Intinya, queue worker bukan pengganti kontrol konkurensi data.

Langkah implementasi standardisasi

1. Mulai dari kontrak, bukan dari framework

Tentukan dulu semantik yang wajib: status, idempotency, retry, timeout, lock, dedup, metrik. Setelah itu baru petakan ke kemampuan broker queue, cache, database, dan runtime worker yang Anda pakai.

2. Pisahkan policy global dan override yang dibenarkan

Buat default yang seragam, misalnya semua job punya max attempts, timeout, dan backoff standar. Lalu izinkan override hanya untuk alasan jelas, misalnya:

  • job memanggil API pihak ketiga yang memang lambat,
  • job CPU-bound yang tidak aman diparalelkan tinggi,
  • job near-real-time yang perlu retry lebih agresif namun singkat.

Jika override dibiarkan bebas, kontrak seragam akan kembali pecah.

3. Sediakan library internal atau middleware worker

Implementasi paling efektif biasanya bukan wiki, tetapi library bersama atau middleware yang memaksa perilaku dasar:

  • validasi envelope,
  • setup timeout context,
  • status transition,
  • pengambilan dan pelepasan lock,
  • klasifikasi retryable/non-retryable error,
  • publikasi metrik dan log terstruktur.

Dengan cara ini, handler bisnis fokus pada logika domain, bukan pada plumbing retry dan observabilitas.

4. Definisikan storage untuk status dan idempotensi

Anda tidak selalu perlu database baru. Namun Anda perlu jawaban jelas untuk:

  • di mana status job disimpan,
  • berapa lama status dipertahankan,
  • di mana idempotency key dicatat,
  • bagaimana dedup key dievaluasi,
  • apa yang terjadi saat storage sementara tidak tersedia.

Pilihan implementasinya bisa berbeda, tetapi keputusan ini tidak boleh implisit.

5. Standarkan log dan tracing

Setiap log worker minimal harus membawa job_id, job_type, attempt, trace_id, dan bila relevan idempotency_key. Tanpa itu, investigasi insiden akan berubah menjadi pencarian manual lintas service.

Checklist standardisasi queue worker

  • Setiap job memiliki envelope standar dengan metadata eksekusi.
  • Status transisi job terdefinisi dan dapat diobservasi.
  • Setiap job yang punya efek samping eksternal memiliki idempotency key.
  • Retry hanya dilakukan untuk error yang diklasifikasikan retryable.
  • Execution timeout dan visibility timeout disetel secara konsisten.
  • Locking dipakai hanya untuk resource yang perlu eksklusivitas.
  • Deduplication dibedakan dari idempotensi.
  • Poison message dipindahkan ke DLQ setelah batas retry.
  • Metrics minimum tersedia per job type.
  • Log terstruktur membawa job_id, attempt, dan trace_id.
  • Default policy ada, override harus terdokumentasi.
  • Ada prosedur replay job dan recovery dari DLQ.

Trade-off dan keterbatasan

Kontrak retry yang seragam bukan berarti sistem menjadi sederhana secara mutlak. Ia justru memindahkan kompleksitas ke tempat yang lebih terkendali. Ada beberapa trade-off yang perlu diterima:

  • Lebih banyak metadata: payload menjadi lebih besar dan butuh disiplin producer-consumer.
  • Storage tambahan: status dan idempotency key perlu tempat simpan yang andal.
  • Latency ekstra: cek dedup, lock, atau idempotensi menambah satu-dua operasi I/O.
  • Policy bisa terasa kaku: beberapa job khusus mungkin tidak cocok dengan default.

Namun dibanding membiarkan setiap worker punya aturan sendiri, trade-off ini biasanya lebih murah secara operasional.

Kapan variasi memang diperlukan

Standardisasi bukan tujuan absolut. Variasi tetap layak jika perbedaannya berakar pada karakteristik beban kerja, bukan preferensi implementasi. Contohnya:

  • Job CPU-bound mungkin butuh model konkurensi dan timeout berbeda dari job I/O-bound.
  • Workflow panjang yang terdiri dari banyak langkah mungkin lebih cocok memakai state machine atau orchestrator, bukan satu retry policy sederhana.
  • Exactly-once effect pada domain sensitif seperti pembayaran mungkin membutuhkan kontrol transaksi dan pencatatan lebih ketat.
  • High-throughput fire-and-forget dengan efek samping minim mungkin tidak butuh lock sama sekali.

Prinsipnya: variasi boleh terjadi pada parameter atau kelas workload, tetapi jangan biarkan variasi liar pada semantik dasar. Jika job A dan job B sama-sama asynchronous dan sama-sama menghasilkan efek samping, operator seharusnya tidak perlu mempelajari dua model kegagalan yang sepenuhnya berbeda.

Panduan keputusan praktis

Jika sistem Anda mulai dipenuhi checker, wrapper, dan pengecualian untuk worker yang berbeda-beda, jangan buru-buru menambah alat baru. Langkah pertama yang paling berguna sering justru menyederhanakan kontrak eksekusi job.

Gunakan pendekatan berikut:

  1. inventarisasi semua job type dan perilaku retry-nya saat ini,
  2. kelompokkan masalah yang berulang: duplikasi, timeout, lock contention, poison message, inconsistency,
  3. tetapkan envelope dan status standar,
  4. buat default retry policy dan klasifikasi error,
  5. tambahkan idempotency key pada job yang punya efek samping,
  6. ukur metrik minimum,
  7. baru izinkan variasi jika ada alasan teknis yang bisa dijelaskan.

Dengan kontrak retry yang seragam, Anda tidak menghilangkan seluruh kompleksitas backend. Tetapi Anda mengurangi variasi yang tidak perlu, membuat perilaku worker lebih mudah diprediksi, dan mempercepat debugging ketika insiden benar-benar terjadi. Di sistem asynchronous, prediktabilitas operasional sering lebih berharga daripada fleksibilitas lokal yang tidak terkendali.