Queue render QR terdengar sederhana: terima input, render gambar QR, simpan hasil, lalu kirim ke klien. Masalahnya muncul saat trafik naik, request sama datang berulang, worker berjalan paralel, dan sistem harus tetap menghasilkan output yang konsisten tanpa memboroskan CPU. Jika tidak dirancang dengan benar, Anda bisa mendapat render duplikat, retry yang menggandakan beban, cache basi, atau lock yang tidak pernah lepas.

Artikel ini membahas desain backend produksi untuk pipeline render QR berbasis queue, dengan inspirasi dari ide render QR yang deterministik seperti pada proyek font TrueType QR, tetapi fokus pada layanan backend: request -> enqueue -> worker -> cache -> delivery. Tujuannya adalah memastikan input yang sama menghasilkan hasil yang sama, hanya diproses seperlunya, dan tetap aman saat banyak worker memproses payload identik secara bersamaan.

Masalah inti: render QR itu deterministik, tetapi eksekusinya sering tidak

Secara logika, render QR biasanya deterministik: jika konten, ukuran, format, error correction level, margin, dan parameter lain sama, hasilnya seharusnya identik. Justru karena deterministik, render QR adalah kandidat bagus untuk:

  • idempotency, karena request identik semestinya tidak membuat pekerjaan baru berulang-ulang,
  • cache, karena hasil bisa dipakai ulang,
  • deduplikasi, karena banyak request dapat mengacu ke artefak yang sama.

Namun di level eksekusi, ada banyak sumber ketidakkonsistenan:

  • dua request identik masuk hampir bersamaan dan keduanya membuat job,
  • dua worker mengambil job yang merepresentasikan input sama,
  • worker gagal setelah render selesai tetapi sebelum status tersimpan,
  • retry job menyebabkan render ulang yang sebenarnya tidak perlu,
  • cache kedaluwarsa serentak dan memicu stampede.

Karena itu, kuncinya bukan hanya membuat QR, tetapi mendesain control plane untuk memastikan prosesnya idempoten dan hasilnya konsisten.

Arsitektur pipeline: request -> enqueue -> worker -> cache -> delivery

Komponen utama

  • API/service layer: menerima request render QR.
  • Canonicalizer: menormalkan input agar request identik benar-benar dipandang identik.
  • Idempotency store: menyimpan relasi antara idempotency key, status proses, dan hasil.
  • Queue: menampung pekerjaan render.
  • Worker: mengambil job, memperoleh lock, render, lalu menyimpan hasil.
  • Cache/object store: menyimpan artefak hasil render dan metadata.
  • Delivery layer: mengembalikan hasil sinkron, URL artefak, atau status polling.

Alur yang disarankan

  1. Klien mengirim payload QR beserta parameter render.
  2. Backend menormalisasi payload menjadi bentuk kanonik.
  3. Backend menghitung content hash dari input kanonik.
  4. Backend memeriksa cache hasil berdasarkan hash.
  5. Jika belum ada, backend membuat atau memakai record idempoten yang sudah ada.
  6. Backend enqueue job dengan kunci deduplikasi berbasis hash.
  7. Worker memproses job dengan distributed lock untuk hash tersebut.
  8. Worker menulis hasil ke object store/cache dan memperbarui status.
  9. Klien menerima hasil langsung, atau token/status untuk mengambil hasil kemudian.

Poin pentingnya: jangan jadikan queue sebagai satu-satunya mekanisme deduplikasi. Queue bisa membantu, tetapi sumber kebenaran tetap harus ada di storage yang bisa memodelkan status pekerjaan dan hasil akhirnya.

Normalisasi input dan idempotency key

Mengapa normalisasi penting

Dua request bisa semantik sama tetapi byte-nya berbeda. Contohnya:

  • urutan field JSON berbeda,
  • nilai default tidak dikirim di request pertama tetapi dikirim eksplisit di request kedua,
  • spasi atau encoding string berbeda,
  • format output ditulis PNG pada satu request dan png pada request lain.

Jika Anda langsung membuat hash dari payload mentah, deduplikasi akan mudah gagal. Karena itu, buat representasi kanonik:

  • urutkan key JSON,
  • isi nilai default secara eksplisit,
  • normalisasi huruf besar-kecil jika memang tidak signifikan,
  • normalisasi tipe angka dan boolean,
  • pastikan parameter yang memengaruhi output benar-benar ikut di-hash.

Dua jenis key yang sering dibutuhkan

Dalam praktik, pisahkan dua konsep:

  • Idempotency key request: mewakili satu permintaan dari klien, biasanya dibawa lewat header atau dibuat server-side untuk mencegah submit ulang akibat timeout atau retry HTTP.
  • Content key/hash: mewakili hasil render deterministik berdasarkan input kanonik.

Perbedaannya penting. Dua request berbeda dari klien yang menginginkan QR sama mungkin punya idempotency key request berbeda, tetapi content hash sama. Dalam kasus ini, sistem sebaiknya tetap memetakan keduanya ke artefak render yang sama.

Skema data minimal

render_requests
- request_id
- idempotency_key
- content_hash
- status            # pending | processing | ready | failed
- result_ref        # lokasi file / object key
- error_code
- created_at
- updated_at

render_results
- content_hash      # unique
- format
- checksum
- result_ref
- expires_at
- created_at

content_hash idealnya unik di tabel hasil. Ini memberi pengaman tambahan agar hasil yang sama tidak tercatat berkali-kali walaupun terjadi balapan di level worker.

Deduplikasi job dan distributed locking

Deduplikasi di saat enqueue

Begitu request datang dan cache belum berisi hasil, jangan langsung memasukkan job baru tanpa cek. Gunakan salah satu pendekatan berikut:

  • Unique constraint di database untuk kombinasi yang mewakili pekerjaan aktif, misalnya content_hash + status in active states.
  • Set/marker di Redis untuk menandai bahwa content hash tertentu sedang memiliki job aktif.
  • Upsert record status lalu enqueue hanya jika transisi status berhasil dari kondisi awal.

Tujuannya adalah mencegah ribuan request identik melahirkan ribuan job identik.

Mengapa tetap perlu lock di worker

Deduplikasi saat enqueue tidak cukup. Dalam sistem terdistribusi, kondisi balapan tetap mungkin terjadi:

  • job terduplikasi karena retry publisher,
  • worker crash lalu queue mengirim ulang,
  • sumber queue memberi setidaknya sekali kirim (at-least-once delivery).

Karena itu, worker perlu mengambil distributed lock berdasarkan content_hash sebelum render. Hanya satu worker yang boleh benar-benar merender hash tertentu pada satu waktu.

Pola lock yang aman

Lock minimal harus punya:

  • scope yang jelas: satu lock per content_hash,
  • TTL: agar lock tidak abadi saat worker mati,
  • owner token: agar hanya pemilik lock yang boleh melepas lock,
  • opsi renewal bila render bisa lebih lama dari TTL lock.

Kesalahan umum adalah memakai lock tanpa owner token. Jika lock kedaluwarsa lalu diambil worker lain, worker lama bisa salah menghapus lock baru milik worker kedua.

Pseudocode enqueue dan worker

function handleRequest(payload, clientIdempotencyKey=None):
    canonical = canonicalize(payload)
    contentHash = sha256(canonical)

    result = cache.get("qr:result:" + contentHash)
    if result exists:
        return ready(result)

    requestKey = clientIdempotencyKey or generateRequestKey()

    req = requests.findByIdempotencyKey(requestKey)
    if req exists:
        return mapRequestStateToResponse(req)

    begin transaction
        req = requests.insertIfAbsent({
            idempotency_key: requestKey,
            content_hash: contentHash,
            status: "pending"
        })

        createdJob = jobs.markActiveIfAbsent(contentHash)
        if createdJob:
            queue.publish({ content_hash: contentHash })
    commit

    return accepted(requestKey, contentHash)
function workerProcess(job):
    contentHash = job.content_hash
    lockKey = "qr:lock:" + contentHash
    owner = randomToken()

    if !lock.acquire(lockKey, owner, ttl=60s):
        # worker lain sedang memproses; jangan render duplikat
        return requeueWithBackoff(job)

    try:
        result = cache.get("qr:result:" + contentHash)
        if result exists:
            markRequestsReady(contentHash, result.ref)
            jobs.clearActive(contentHash)
            return ack(job)

        markRequestsProcessing(contentHash)

        payload = rebuildPayloadFromHashOrMetadata(contentHash)
        artifact = renderQr(payload)
        ref = objectStore.put(artifact)

        begin transaction
            results.upsert({
                content_hash: contentHash,
                result_ref: ref,
                checksum: sha256(artifact)
            })
            markRequestsReady(contentHash, ref)
            jobs.clearActive(contentHash)
        commit

        cache.set("qr:result:" + contentHash, { ref: ref }, ttl=24h)
        return ack(job)

    catch transientError:
        return retryWithBackoff(job)

    catch permanentError as err:
        markRequestsFailed(contentHash, err.code)
        jobs.clearActive(contentHash)
        return moveToDLQ(job)

    finally:
        lock.releaseIfOwner(lockKey, owner)

Perhatikan urutannya: cek cache lagi di worker walaupun API sudah mengecek sebelumnya. Ini penting karena state bisa berubah di antara enqueue dan eksekusi.

Retry aman, dead-letter queue, dan efek samping yang harus dihindari

Retry hanya aman jika operasi idempoten

Queue produksi hampir selalu membutuhkan retry. Tetapi retry yang tidak dirancang dengan baik akan menggandakan beban CPU dan I/O. Agar retry aman:

  • gunakan content hash sebagai kunci identitas kerja,
  • cek hasil akhir sebelum render ulang,
  • pastikan penulisan hasil ke storage bersifat upsert atau dilindungi constraint unik,
  • pisahkan error transien dan permanen.

Contoh error transien: timeout object storage, koneksi Redis putus sesaat. Contoh error permanen: parameter format tidak valid, payload melanggar batas ukuran, atau library render menolak input karena aturan bisnis.

Backoff dan jitter

Retry sebaiknya memakai exponential backoff dengan jitter. Tanpa jitter, banyak job gagal akan bangun ulang pada waktu yang sama dan memukul dependensi secara serentak. Tujuannya bukan sekadar menunda, tetapi menyebarkan ulang beban.

Kapan job masuk dead-letter queue

Dead-letter queue (DLQ) dipakai saat job tidak bisa diproses setelah sejumlah percobaan tertentu atau mengalami error permanen. DLQ berguna untuk:

  • investigasi payload bermasalah,
  • replay manual setelah bug diperbaiki,
  • mencegah poison message terus berputar di antrean utama.

Simpan metadata yang cukup di DLQ:

  • content hash,
  • request id/idempotency key,
  • jumlah retry,
  • ringkasan error,
  • timestamp kegagalan terakhir.

Cache yang konsisten: TTL, cache stampede, dan hasil basi

Apa yang sebaiknya di-cache

Untuk pipeline ini, biasanya ada dua level cache:

  • metadata cache: status siap/tidak, pointer ke artefak, checksum, expiry.
  • binary cache atau object storage: file PNG/SVG final.

Jika hasil render benar-benar deterministik dan jarang berubah untuk input yang sama, cache metadata bisa bertahan cukup lama. Namun TTL tetap perlu untuk mengatasi kebutuhan housekeeping, invalidasi konfigurasi, atau migrasi format.

Masalah cache stampede

Cache stampede terjadi saat item populer kedaluwarsa dan banyak request serentak memicu render ulang. Pada render QR yang mahal, efeknya langsung terasa pada CPU worker. Beberapa teknik yang umum dipakai:

  • single-flight per content hash dengan lock,
  • TTL dengan jitter agar expiry tidak serentak,
  • stale-while-revalidate jika hasil lama masih dapat ditoleransi,
  • negative caching untuk kegagalan validasi tertentu agar request invalid tidak terus diproses ulang.

Kapan stale-while-revalidate cocok

Jika output QR untuk input yang sama tidak bergantung pada data eksternal yang berubah, stale-while-revalidate cukup aman. Misalnya, file hasil lama masih boleh dilayani selama beberapa menit sambil worker merefresh metadata di belakang layar.

Namun jika parameter render berubah karena release baru dan Anda menuntut hasil byte-identical sesuai versi terbaru, stale-while-revalidate bisa menampilkan artefak lama yang tidak sesuai ekspektasi. Dalam kasus ini, masukkan renderer version atau render profile version ke dalam content hash agar cache lama otomatis terisolasi dari hasil baru.

Hasil cache basi dan cara menghindarinya

Cache basi sering terjadi bukan karena TTL terlalu lama, tetapi karena kunci cache tidak memasukkan semua faktor yang memengaruhi output. Pastikan hash mencakup:

  • konten QR,
  • format output,
  • ukuran/scale,
  • margin/quiet zone,
  • error correction level,
  • opsi warna jika ada,
  • versi profil render bila perubahan implementasi mengubah output.

Jika salah satu tertinggal, Anda akan mengembalikan file yang valid tetapi salah.

Skenario gagal yang sering muncul

1. Duplicate render untuk input yang sama

Gejala: CPU worker tinggi, object storage berisi file duplikat, antrean cepat menumpuk saat ada burst request identik.

Penyebab umum:

  • tidak ada deduplikasi saat enqueue,
  • lock hanya di API, bukan di worker,
  • retry queue memproses job yang sama tanpa cek hasil akhir.

Mitigasi:

  • gunakan content hash sebagai identitas kerja,
  • pasang unique record atau active marker,
  • cek cache dan tabel hasil lagi di worker sebelum render.

2. Lock bocor

Gejala: satu content hash tidak pernah selesai diproses, job lain terus menunggu atau retry.

Penyebab umum:

  • worker crash setelah mengambil lock,
  • lock tanpa TTL,
  • pelepasan lock tidak memakai owner token.

Mitigasi:

  • selalu beri TTL,
  • tambahkan mekanisme renewal jika render bisa lama,
  • hanya release lock bila token owner cocok,
  • monitor usia lock dan jumlah lock stale.

3. Hasil cache basi

Gejala: klien menerima QR dengan parameter lama setelah deployment baru.

Penyebab umum:

  • versi renderer tidak ikut dalam key,
  • cache invalidation tidak direncanakan,
  • metadata diperbarui tetapi artefak file lama masih dipakai.

Mitigasi:

  • sertakan render profile version ke content hash,
  • gunakan checksum artefak untuk verifikasi,
  • pisahkan namespace cache per versi jika perlu.

4. Retry menggandakan beban

Gejala: begitu ada gangguan sesaat pada storage, jumlah job melonjak dan worker sibuk merender ulang file yang sama.

Penyebab umum:

  • retry tanpa backoff/jitter,
  • hasil render tidak disimpan atomik dengan update status,
  • job gagal setelah artefak tersimpan tetapi sebelum status ready tercatat.

Mitigasi:

  • cek keberadaan hasil di object store sebelum render ulang,
  • gunakan checksum/result_ref sebagai sumber kebenaran,
  • buat update status dan hasil sedekat mungkin secara transaksional.

Redis vs DB queue: trade-off praktis

Kapan Redis cocok

Redis sering dipilih untuk queue render QR karena latensi rendah dan cocok untuk beban tinggi dengan job kecil-menengah. Redis juga nyaman untuk menyimpan lock, dedup marker, dan cache metadata di tempat yang sama.

Kelebihan:

  • enqueue/dequeue cepat,
  • cocok untuk burst traffic,
  • mudah dipakai untuk lock dan cache,
  • operasi berbasis TTL sederhana.

Kekurangan:

  • durabilitas bergantung pada konfigurasi persistence,
  • observabilitas dan audit historis sering butuh sistem tambahan,
  • desain harus hati-hati agar state queue dan state database tidak saling bertentangan.

Kapan DB queue cocok

Database-backed queue cocok bila Anda lebih mementingkan transaksi kuat, jejak audit, dan kesederhanaan operasional dibanding throughput maksimum.

Kelebihan:

  • lebih mudah menjaga konsistensi dengan tabel request/result,
  • bisa memakai transaksi dan unique constraint dengan natural,
  • lebih mudah diinspeksi dengan query SQL.

Kekurangan:

  • throughput umumnya lebih rendah,
  • polling worker bisa membebani database,
  • locking row dan kontensi bisa muncul saat traffic naik.

Panduan memilih

  • Pilih Redis jika prioritasnya throughput tinggi, latensi rendah, dan Anda siap membangun disiplin state management dengan baik.
  • Pilih DB queue jika volume masih moderat, kebutuhan audit kuat, dan Anda ingin konsistensi transaksional yang lebih sederhana dipahami tim.

Dalam banyak sistem nyata, kombinasi juga masuk akal: database untuk sumber kebenaran request/result, Redis untuk queue, lock, dan cache metadata.

Metrik yang wajib dipantau

Tanpa metrik, masalah idempotensi dan locking biasanya baru terlihat saat biaya naik atau klien mengeluh. Pantau setidaknya:

  • queue depth per jenis job,
  • job latency: waktu dari enqueue sampai selesai,
  • render duration di worker,
  • cache hit rate berdasarkan content hash,
  • dedup hit rate: berapa request/job yang berhasil digabung,
  • retry count dan distribusinya,
  • DLQ rate,
  • lock acquisition failure rate,
  • lock age dan jumlah lock stale,
  • duplicate artifact rate atau konflik unique constraint,
  • error rate per kategori transien/permanen,
  • object store put/get failures.

Jika memungkinkan, tambahkan korelasi log berdasarkan content_hash, request_id, dan job_id. Ini sangat membantu saat menelusuri balapan antar worker.

Checklist operasional untuk produksi

  • Input request dinormalisasi sebelum dihitung hash.
  • Content hash mencakup semua parameter yang memengaruhi output.
  • Ada pemisahan antara idempotency key request dan content hash hasil.
  • Enqueue memakai mekanisme deduplikasi atau active marker.
  • Worker selalu cek cache/hasil akhir sebelum render.
  • Distributed lock memakai TTL dan owner token.
  • Ada strategi renewal lock untuk job yang bisa berjalan lama.
  • Penulisan hasil dan update status dibuat seatomik mungkin.
  • Retry memakai backoff dan jitter.
  • Error transien dan permanen dipisahkan jelas.
  • Poison message masuk DLQ, bukan berputar tanpa henti.
  • TTL cache diberi jitter untuk mengurangi stampede.
  • Versi renderer atau render profile dimasukkan ke cache key bila memengaruhi output.
  • Metrik queue, cache, lock, retry, dan DLQ dipantau.
  • Tersedia tool replay aman untuk job di DLQ.

Penutup

Merancang queue render QR yang andal bukan terutama soal bagaimana menghasilkan gambar QR, melainkan bagaimana memastikan pekerjaan deterministik dijalankan secara idempoten, tidak berduplikasi, dan tetap konsisten saat sistem sibuk. Kombinasi normalisasi input, content hash, deduplikasi job, distributed locking, retry aman, dan cache yang disiplin adalah fondasi utamanya.

Jika Anda hanya mengandalkan queue tanpa sumber kebenaran status dan hasil, masalah akan muncul cepat saat ada retry, crash, atau burst trafik. Sebaliknya, jika state dirancang dengan jelas dan setiap langkah memverifikasi hasil akhir, banyak worker bisa memproses beban tinggi tanpa mengorbankan konsistensi atau membuang sumber daya untuk render yang sama berulang kali.