Env Konsolidasi Antrean (asynq)

A. Ringkasan & Definition of Done

Konsolidasi antrean memindahkan public.queue_jobs dari tabel yang dibaca empat service dengan empat semantik berbeda menjadi outbox dengan satu pembaca: container relay (biner ./relay milik integration-service) yang meneruskan tiap baris ke asynq/Redis, lalu tiap service mengonsumsinya sebagai asynq.Handler.

queue_jobs tidak dihapus. Penulis terbesarnya adalah trigger PL/pgSQL di dalam Postgres dan Camunda sisi Java — keduanya tidak punya jalan ke Redis, jadi tabelnya tetap ada dan turun pangkat jadi outbox.

Halaman ini adalah registry env-nya: apa yang harus ada di .env, service mana yang membacanya, dan mana yang hari ini belum diteruskan docker-compose.yml rilis.

DoD halaman ini dianggap terpenuhi bila:

• Setiap env di §D ada nilainya di .env instalasi (bukan mengandalkan default implisit di kode).
• REDIS_QUEUE_PASSWORD terisi dan berbeda dari REDIS_PASSWORD.
• Baris-baris di §E sudah ditambahkan, atau ketiadaannya disadari dan diterima.
• Keputusan di §F diambil eksplisit — bukan terlewat.

B. Peta service: siapa menulis, siapa membaca

C. Env global (dipakai lintas service)

Semua sudah ada di .env.example rilis.

asynqmon tidak punya autentikasi bawaan dan payload yang ditampilkannya berisi snapshot variabel proses Camunda (data bisnis pelanggan). Ia tidak didaftarkan di nginx dan port-nya di-bind ke 127.0.0.1 — akses lewat SSH tunnel:

ssh -L 8106:127.0.0.1:8106 <host>   # lalu buka http://127.0.0.1:8106

Menghapus binding 127.0.0.1 itu supaya "lebih gampang diakses" berarti siapa pun di jaringan yang sama bisa membaca payload dan menghapus job produksi.

D. Env per service

D.1. Relay (container relay)

Relay adalah container tersendiri yang menjalankan image integration-service dengan command: ["./relay"] — sengaja bukan goroutine di dalam proses API: goroutine akan ter-duplikasi tiap replika API dan ikut mati tiap deploy/OOM/restart API.

Koneksi (wajib): DB_* dan REDIS_QUEUE_*. Relay menolak start (exit 1) kalau REDIS_QUEUE_HOST kosong — sengaja, supaya tidak ada relay yang jalan ke Redis yang tidak dikonfigurasi.

Gate consumer. Relay juga membaca ENABLE_TASK_REMINDER_WORKER dan ENABLE_TASK_EVENT_NOTIFICATION_WORKER — env yang sama persis dengan yang dibaca container integration, supaya relay dan konsumennya tidak pernah berbeda pendapat soal apakah sebuah topik "hidup". Kedua container wajib menerima nilai identik. Gate ini hanya berlaku untuk dua topik itu; semua topik lain di-relay tanpa syarat.

D.2. integration-service (container integration)

D.3. report-service (container report)

D.4. notification-service (container notification)

AppReminderWorker hidup hari ini tanpa flag enable sama sekali — jadi tidak ada ENABLE_... untuk service ini, hanya flag transport di atas.

D.5. bpm-service & camunda — tidak ada env antrean

Keduanya produsen queue_jobs dan tidak mengonsumsi apa pun dari asynq. Tidak ada REDIS_QUEUE_*, tidak ada flag consumer. Worker milik bpm (discussion_outbox, discussion_status_sync, sla) memakai outbox privatnya sendiri dan tidak tersentuh konsolidasi ini.

D.6. generate-test & simulation — tidak ada env antrean

Kedua service ini dulu menjalankan asynq.Server dengan ServeMux kosong — nol handler, nol enqueue — di DB Redis yang sama dengan cache aplikasi, dan dengan nama antrean yang identik satu sama lain. Server mati itu sudah dicabut.

CACHE_PROVIDER / CACHE_HOST / CACHE_PORT / CACHE_PASSWORD / CACHE_DB / CACHE_ENABLED tetap ada dan tetap dipakai — itu cache aplikasi sungguhan (UserResolver, DriveAccessMiddleware), bukan sisa antrean. Jangan hapus.

E. Yang belum diteruskan compose rilis

Semua env bertanda 🔴 di §D punya default yang benar di kode, jadi ketiadaannya tidak merusak apa pun hari ini. Yang hilang adalah kemampuan operator mengubahnya lewat .env — untuk mengubahnya sekarang, docker-compose.yml harus diedit langsung. Selama semuanya masih legacy, ini belum menghambat; ia menghambat tepat pada saat cutover, ketika angka-angka itu justru perlu diputar.

Tambahkan ke .env (dan ke blok environment: service yang bersangkutan bila instalasi Anda tidak memakai env_file: .env):

# --- integration-service (container `integration`) ---
TASK_REMINDER_CONSUMER=legacy
TASK_EVENT_NOTIFICATION_CONSUMER=legacy
WEBHOOK_ASYNQ_CONCURRENCY=3
WEBHOOK_ASYNQ_RATE_PER_SECOND=10

# --- report-service (container `report`) ---
QUEUE_PROCESSOR_CONSUMER=legacy
QUEUE_PROCESSOR_ASYNQ_CONCURRENCY=5
QUEUE_PROCESSOR_ASYNQ_RATE_PER_SECOND=20

# --- notification-service (container `notification`) ---
APP_REMINDER_ASYNQ_CONCURRENCY=3
APP_REMINDER_ASYNQ_RATE_PER_SECOND=10

# --- relay (container `relay`) ---
RELAY_ASYNQ_TASK_RETENTION_SECONDS=86400
RELAY_ASYNQ_TASK_RETENTION_REMINDER_SECONDS=600
QUEUE_JOB_RETENTION_DAYS=30
QUEUE_JOB_RETENTION_SWEEP_INTERVAL_SECONDS=3600
RELAY_STALE_REMINDER_THRESHOLD_SECONDS=3600
RELAY_STALE_WEBHOOK_THRESHOLD_SECONDS=86400
RELAY_TIMEOUT_REPORT_SECONDS=60
RELAY_TIMEOUT_INTEGRATION_SECONDS=30

F. Container relay jalan otomatis — baca sebelum deploy

Masalahnya: relay bersifat table-wide, bukan per-topik. Gate ConsumerEnabledForTopic hanya menahan dua topik (task.active.reminder, task.notification). Semua topik lain — webhook_delivery, notification.app.reminder, seluruh camunda.*/report.* — akan di-enqueue ke Redis dan barisnya ditandai completed, sementara konsumen mereka masih legacy dan mencari baris pending yang tidak akan pernah ada lagi.

Gejalanya bukan error. Webhook berhenti terkirim, tabel pivot Camunda berhenti terisi, log bersih, queue_jobs terlihat sehat karena semuanya completed.

Sampai cutover benar-benar dijalankan, jalankan compose tanpa relay:

docker compose up -d --scale relay=0

Perbaikan permanennya adalah menambahkan profiles: pada service relay di release-alurkerja-local sehingga ia hanya ikut naik saat profil antrean diaktifkan — layak jadi tiket tersendiri di repo itu.

G. Urutan aman menyalakan

Tiap langkah punya verifikasi. Jangan simpulkan "berhasil" dari "tidak ada yang rusak".

1. Isi kredensial. REDIS_QUEUE_PASSWORD terisi dan berbeda dari REDIS_PASSWORD; REDIS_QUEUE_MAXMEMORY disesuaikan RAM host.

   docker compose up -d redis-queue
   docker compose exec redis-queue redis-cli -a "$REDIS_QUEUE_PASSWORD" config get maxmemory maxmemory-policy
   # harus: maxmemory sesuai .env, maxmemory-policy noeviction

2. Naikkan compose tanpa relay (--scale relay=0). Semua *_CONSUMER tetap legacy. Perilaku antrean belum berubah sama sekali.
3. Siapkan cutover: index idx_queue_jobs_pending_relay dan penandaan backlog historis jadi skipped. Tanpa ini, relay pada boot pertama akan menyapu seluruh timbunan pending historis — termasuk topik yang memang tidak pernah punya konsumen — langsung ke RAM Redis.

   SELECT topic, status, count(*) FROM public.queue_jobs GROUP BY 1,2 ORDER BY 3 DESC;

4. Nyalakan relay, konsumen masih legacy — hanya sesudah langkah 3 dan hanya dalam jendela terjadwal, karena inilah titik di mana konsumen legacy mulai kelaparan (§F).
5. Pindahkan konsumen satu per satu, satu topik per deploy: ubah *_CONSUMER ke asynq untuk satu topik, verifikasi lewat asynqmon bahwa antreannya benar-benar terkuras, baru lanjut ke topik berikutnya.

H. Troubleshooting

I. Rujukan

Dokumen teknis mendalam ada di repo masing-masing: