zizq 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 77ab05fe491ab193d0c5c3b1106aac3e5effe7b1dcb7e0117b70e0e05652426b
+  data.tar.gz: 05f26bd94ca2127e7e859212348e063bc9354d866945ae500514dcfbcfe57828
+SHA512:
+  metadata.gz: f12216566271dbd68395eeada829ffd68bfd853e86c1a8e598dbac6c3c7f5d8af5008ee084a9a7ebaef99d74144c6d05995fe32e01f0349b47dac6beb082c702
+  data.tar.gz: 505804d9abd2c1cff8a749bd9cb6ad3d224d09545648a314b54a3094a96f2d18cb18257661833479bf1b59959d6d300730e2cbcbb70572afee5195bb538d8460

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Chris Corbyn <chris@zizq.io>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,94 @@
+# Zizq — Official Ruby Client
+
+Zizq is a simple, zero dependency, single binary job queue system that is both
+fast and durable. It is designed to work in any stack through a simple HTTP
+API.
+
+This is the official Zizq client library for Ruby.
+
+[![CI](https://github.com/zizq-labs/zizq-ruby/actions/workflows/ci.yml/badge.svg)](https://github.com/zizq-labs/zizq-ruby/actions/workflows/ci.yml)
+
+## Features
+
+* Multi-thread and/or multi-fiber concurrent worker (via [`async`](https://github.com/socketry/async))
+* `Zizq::Job` based job classes, Active Job support, or completely custom
+* Enqueue and process jobs from one language to another
+* Arbitrary named queues
+* Granular job priorities
+* Scheduled jobs
+* Configurable backoff policies
+* Configurable job retention policies
+* Job introspection and management APIs, with support for `jq` query filters
+* Unique jobs
+
+## Example
+
+> [!TIP]
+> The client is very flexible and supports being used in a range of different
+> ways. Read the [full documentation](https://zizq.io/docs/clients/ruby/) on
+> the website for more details.
+
+Mixin-based job class.
+
+```ruby
+class SendEmailJob
+  include Zizq::Job
+
+  zizq_queue 'emails'
+  zizq_priority 100
+
+  def perform(user_id, template:)
+    # your application logic here
+  end
+end
+```
+
+Enqueueing a job.
+
+```ruby
+Zizq.enqueue(SendEmailJob, 42, template: 'welcome')
+```
+
+> [!NOTE]
+> Jobs can also be enqueued and processed without `Zizq::Job`, which is
+> designed to support interoperability with any programming language.
+
+Using the included `zizq-worker` executable.
+
+```shell
+$ zizq-worker --threads 5 --fibers 2 app.rb
+I, [2026-03-24T15:25:57.738131 #1331422]  INFO -- : Zizq worker starting: 5 threads, 2 fibers, prefetch=20
+I, [2026-03-24T15:25:57.738222 #1331422]  INFO -- : Queues: (all)
+I, [2026-03-24T15:25:57.739861 #1331422]  INFO -- : Worker 0:0 started
+I, [2026-03-24T15:25:57.739962 #1331422]  INFO -- : Worker 0:1 started
+I, [2026-03-24T15:25:57.740131 #1331422]  INFO -- : Worker 1:0 started
+I, [2026-03-24T15:25:57.740211 #1331422]  INFO -- : Worker 1:1 started
+I, [2026-03-24T15:25:57.740352 #1331422]  INFO -- : Worker 2:0 started
+I, [2026-03-24T15:25:57.740408 #1331422]  INFO -- : Worker 2:1 started
+I, [2026-03-24T15:25:57.740532 #1331422]  INFO -- : Worker 3:0 started
+I, [2026-03-24T15:25:57.740590 #1331422]  INFO -- : Worker 3:1 started
+I, [2026-03-24T15:25:57.740722 #1331422]  INFO -- : Worker 4:0 started
+I, [2026-03-24T15:25:57.740776 #1331422]  INFO -- : Worker 4:1 started
+I, [2026-03-24T15:25:57.740844 #1331422]  INFO -- : Zizq producer thread started
+I, [2026-03-24T15:25:57.740878 #1331422]  INFO -- : Connecting to http://localhost:7890...
+I, [2026-03-24T15:25:57.792173 #1331422]  INFO -- : Connected. Listening for jobs.
+```
+
+> [!NOTE]
+> Workers can also be created directly in code. There is no requirement to use
+> `zizq-worker`.
+
+## Resources
+
+* [Ruby Client Docs](https://zizq.io/docs/clients/ruby/)
+* [Getting Started Docs](https://zizq.io/docs/getting-started/)
+* [Zizq Command Reference](https://zizq.io/docs/cli/)
+* [Zizq Node.js Client Source](https://github.com/zizq-labs/zizq-node)
+* [Zizq Source](https://github.com/zizq-labs/zizq)
+
+## Support & Feedback
+
+If you need help using Zizq,
+[create an issue](https://github.com/zizq-labs/zizq-ruby/issues) on the
+[zizq-ruby](https://github.com/zizq-labs/zizq-ruby) repo. Feedback is very
+welcome.

data/bin/profile-worker

@@ -0,0 +1,145 @@
+#!/usr/bin/env ruby
+# Copyright (c) 2026 Chris Corbyn <chris@zizq.io>
+# Licensed under the MIT License. See LICENSE file for details.
+
+# frozen_string_literal: true
+
+# Profile the worker using Vernier (wall-clock mode, all threads/fibers).
+#
+# All settings are controlled via environment variables — the same ones
+# accepted by zizq-worker, plus:
+#
+#   VERNIER_OUT         Output file (default: profile.vernier.json)
+#   VERNIER_INTERVAL    Sample interval in microseconds (default: 1000)
+#   VERNIER_TEXT        Set to 1 to print a text summary to stderr
+#
+# Example:
+#
+#   ZIZQ_THREADS=5 ZIZQ_FIBERS=5 bundle exec bin/profile-worker entrypoint.rb
+#
+
+require "vernier"
+require "set"
+require "zizq"
+
+# --- Worker settings (same env vars as zizq-worker) ---
+
+thread_count = Integer(ENV.fetch("ZIZQ_THREADS", Zizq::Worker::DEFAULT_THREADS))
+fiber_count = Integer(ENV.fetch("ZIZQ_FIBERS", Zizq::Worker::DEFAULT_FIBERS))
+prefetch = ENV.key?("ZIZQ_PREFETCH") ? Integer(ENV["ZIZQ_PREFETCH"]) : nil
+retry_min_wait = Float(ENV.fetch("ZIZQ_RETRY_MIN_WAIT", Zizq::Worker::DEFAULT_RETRY_MIN_WAIT))
+retry_max_wait = Float(ENV.fetch("ZIZQ_RETRY_MAX_WAIT", Zizq::Worker::DEFAULT_RETRY_MAX_WAIT))
+retry_multiplier = Float(ENV.fetch("ZIZQ_RETRY_MULTIPLIER", Zizq::Worker::DEFAULT_RETRY_MULTIPLIER))
+
+queues = if ENV.key?("ZIZQ_QUEUES")
+  ENV["ZIZQ_QUEUES"].split(",").map(&:strip).reject(&:empty?)
+else
+  []
+end
+
+# --- Vernier settings ---
+
+out = ENV.fetch("VERNIER_OUT", "profile.vernier.json")
+interval = Integer(ENV.fetch("VERNIER_INTERVAL", 1000))
+text_output = ENV["VERNIER_TEXT"] == "1"
+
+# --- Load entrypoint ---
+
+entrypoint = ARGV[0]
+
+if entrypoint.nil?
+  warn "Usage: bundle exec bin/profile-worker <ENTRYPOINT>"
+  warn ""
+  warn "Example: ZIZQ_THREADS=5 bundle exec bin/profile-worker entrypoint.rb"
+  exit 1
+end
+
+unless File.file?(entrypoint)
+  warn "Error: entrypoint file not found: #{entrypoint}"
+  exit 1
+end
+
+require File.expand_path(entrypoint)
+
+# --- Run under profiler ---
+
+warn "Profiling worker (wall-clock, interval=#{interval}µs) → #{out}"
+warn "Send SIGINT/SIGTERM to stop and write the profile."
+
+Vernier.profile(out: out, interval: interval, allocation_sample_rate: 0) do
+  Zizq::Worker.run(
+    thread_count:,
+    fiber_count:,
+    prefetch:,
+    queues:,
+    retry_min_wait:,
+    retry_max_wait:,
+    retry_multiplier:,
+  )
+end
+
+warn "Profile written to #{out}"
+warn "View with: https://profiler.firefox.com/ and load #{out}"
+
+if text_output
+  require "json"
+
+  data = JSON.parse(File.read(out))
+  data["threads"].each do |thread|
+    samples = thread["samples"]
+    next unless samples && samples["length"] > 0
+
+    stack_table = thread["stackTable"]
+    frame_table = thread["frameTable"]
+    func_table = thread["funcTable"]
+    strings = thread["stringArray"]
+
+    # Count self-time: how often each function is at the top of the stack.
+    self_counts = Hash.new(0)
+    total_weight = 0.0
+
+    samples["length"].times do |i|
+      stack_idx = samples["stack"][i]
+      weight = samples["weight"] ? samples["weight"][i] : 1
+      total_weight += weight
+
+      frame_idx = stack_table["frame"][stack_idx]
+      func_idx = frame_table["func"][frame_idx]
+      name = strings[func_table["name"][func_idx]]
+
+      self_counts[name] += weight
+    end
+
+    # Count total-time: how often each function appears anywhere in the stack.
+    total_counts = Hash.new(0)
+
+    samples["length"].times do |i|
+      stack_idx = samples["stack"][i]
+      weight = samples["weight"] ? samples["weight"][i] : 1
+      seen = Set.new
+
+      while stack_idx
+        frame_idx = stack_table["frame"][stack_idx]
+        func_idx = frame_table["func"][frame_idx]
+        name = strings[func_table["name"][func_idx]]
+
+        total_counts[name] += weight unless seen.include?(name)
+        seen << name
+
+        stack_idx = stack_table["prefix"][stack_idx]
+      end
+    end
+
+    sorted = self_counts.sort_by { |_, v| -v }
+
+    warn ""
+    warn "=== Thread: #{thread["name"]} (#{samples["length"]} samples) ==="
+    warn "%8s %6s  %8s %6s  %s" % ["SELF", "(%)", "TOTAL", "(%)", "FUNCTION"]
+    sorted.first(40).each do |name, self_w|
+      total_w = total_counts[name]
+      self_pct = (self_w / total_weight * 100).round(1)
+      total_pct = (total_w / total_weight * 100).round(1)
+      warn "%8.1f %5.1f%%  %8.1f %5.1f%%  %s" % [self_w, self_pct, total_w, total_pct, name]
+    end
+  end
+end

data/bin/zizq-worker

@@ -0,0 +1,174 @@
+#!/usr/bin/env ruby
+# Copyright (c) 2026 Chris Corbyn <chris@zizq.io>
+# Licensed under the MIT License. See LICENSE file for details.
+
+# frozen_string_literal: true
+
+require "optparse"
+require "timeout"
+require "zizq"
+
+# Default deadline for a graceful `stop` before escalating to `kill`.
+DEFAULT_SHUTDOWN_DEADLINE = 30.0
+
+# --- Defaults from env vars, falling back to hardcoded defaults ---
+
+thread_count = Integer(ENV.fetch("ZIZQ_THREADS", Zizq::Worker::DEFAULT_THREADS))
+fiber_count = Integer(ENV.fetch("ZIZQ_FIBERS", Zizq::Worker::DEFAULT_FIBERS))
+prefetch = ENV.key?("ZIZQ_PREFETCH") ? Integer(ENV["ZIZQ_PREFETCH"]) : nil
+shutdown_deadline = Float(ENV.fetch("ZIZQ_SHUTDOWN_DEADLINE", DEFAULT_SHUTDOWN_DEADLINE))
+retry_min_wait = Float(ENV.fetch("ZIZQ_RETRY_MIN_WAIT", Zizq::Worker::DEFAULT_RETRY_MIN_WAIT))
+retry_max_wait = Float(ENV.fetch("ZIZQ_RETRY_MAX_WAIT", Zizq::Worker::DEFAULT_RETRY_MAX_WAIT))
+retry_multiplier = Float(ENV.fetch("ZIZQ_RETRY_MULTIPLIER", Zizq::Worker::DEFAULT_RETRY_MULTIPLIER))
+
+queues = if ENV.key?("ZIZQ_QUEUES")
+  ENV["ZIZQ_QUEUES"].split(",").map(&:strip).reject(&:empty?)
+else
+  []
+end
+
+# --- CLI flag parsing (overrides env var defaults) ---
+
+parser = OptionParser.new do |opts|
+  opts.banner = "Usage: zizq-worker [OPTIONS] <ENTRYPOINT>"
+
+  opts.separator ""
+  opts.separator "Start a Zizq worker process. The ENTRYPOINT is a Ruby file that loads your"
+  opts.separator "application (e.g. config/environment.rb for a Rails app)."
+  opts.separator ""
+  opts.separator "Client configuration (url, format, logger) should be set in the"
+  opts.separator "entrypoint via Zizq.configure."
+  opts.separator ""
+  opts.separator "Options:"
+
+  opts.on("-t", "--threads N", Integer, "Number of worker threads (default: #{Zizq::Worker::DEFAULT_THREADS}, env: ZIZQ_THREADS)") do |n|
+    thread_count = n
+  end
+
+  opts.on("-f", "--fibers N", Integer, "Number of fibers per thread (default: #{Zizq::Worker::DEFAULT_FIBERS}, env: ZIZQ_FIBERS)") do |n|
+    fiber_count = n
+  end
+
+  opts.on("-p", "--prefetch N", Integer, "Prefetch count (default: 2*threads*fibers, env: ZIZQ_PREFETCH)") do |n|
+    prefetch = n
+  end
+
+  queues_from_cli = false
+  opts.on("-q", "--queue QUEUE", "Queue to process (repeatable or comma-separated, env: ZIZQ_QUEUES)") do |q|
+    # First -q flag replaces the env var default entirely
+    unless queues_from_cli
+      queues = []
+      queues_from_cli = true
+    end
+    queues.concat(q.split(",").map(&:strip).reject(&:empty?))
+  end
+
+  opts.on("--shutdown-deadline N", Float, "Graceful shutdown deadline in seconds before escalating to kill (default: #{DEFAULT_SHUTDOWN_DEADLINE}, env: ZIZQ_SHUTDOWN_DEADLINE)") do |n|
+    shutdown_deadline = n
+  end
+
+  opts.on("--retry-min-wait N", Float, "Minimum retry wait in seconds (default: #{Zizq::Worker::DEFAULT_RETRY_MIN_WAIT}, env: ZIZQ_RETRY_MIN_WAIT)") do |n|
+    retry_min_wait = n
+  end
+
+  opts.on("--retry-max-wait N", Float, "Maximum retry wait in seconds (default: #{Zizq::Worker::DEFAULT_RETRY_MAX_WAIT}, env: ZIZQ_RETRY_MAX_WAIT)") do |n|
+    retry_max_wait = n
+  end
+
+  opts.on("--retry-multiplier N", Float, "Retry backoff multiplier (default: #{Zizq::Worker::DEFAULT_RETRY_MULTIPLIER}, env: ZIZQ_RETRY_MULTIPLIER)") do |n|
+    retry_multiplier = n
+  end
+
+  opts.on("-v", "--version", "Print version and exit") do
+    puts "zizq-worker #{Zizq::VERSION}"
+    exit
+  end
+
+  opts.on("-h", "--help", "Show this help message") do
+    puts opts
+    exit
+  end
+end
+
+begin
+  parser.parse!
+rescue OptionParser::ParseError => e
+  warn e.message
+  warn "See 'zizq-worker --help' for usage information."
+  exit 1
+end
+
+# --- Validate options ---
+
+if thread_count < 1
+  warn "Error: --threads must be at least 1 (got #{thread_count})"
+  exit 1
+end
+
+if fiber_count < 1
+  warn "Error: --fibers must be at least 1 (got #{fiber_count})"
+  exit 1
+end
+
+# --- Validate and load entrypoint ---
+
+entrypoint = ARGV[0]
+
+if entrypoint.nil?
+  warn "Error: missing required ENTRYPOINT argument."
+  warn ""
+  warn parser.help
+  exit 1
+end
+
+unless File.file?(entrypoint)
+  warn "Error: entrypoint file not found: #{entrypoint}"
+  exit 1
+end
+
+require File.expand_path(entrypoint)
+
+# --- Start the worker ---
+
+worker = Zizq::Worker.new(
+  thread_count:,
+  fiber_count:,
+  prefetch:,
+  queues:,
+  retry_min_wait:,
+  retry_max_wait:,
+  retry_multiplier:,
+)
+
+# `Zizq::Worker#stop` is patient (waits forever for in-flight jobs and
+# acks to drain). We enforce the shutdown deadline at the CLI level: the
+# signal handler calls `worker.stop` and spawns a shutdown thread that
+# joins the worker with `Timeout::timeout`, escalating to `kill` on
+# expiry.
+worker_thread = Thread.new { worker.run }
+
+# First INT/TERM: graceful stop with deadline watchdog.
+# Second INT/TERM: hard process exit.
+stopping = false
+
+%w[INT TERM].each do |signal|
+  Signal.trap(signal) do
+    if stopping
+      exit(1)
+    else
+      worker.stop
+      stopping = true
+      Thread.new do
+        Timeout.timeout(shutdown_deadline) { worker_thread.join }
+      rescue Timeout::Error
+        worker.logger.warn do
+          "Worker did not stop within #{shutdown_deadline}s, killing..."
+        end
+        exit(1)
+      end
+    end
+  end
+end
+
+# Wait until the worker finishes cleanly.
+worker_thread.join

data/lib/active_job/queue_adapters/zizq_adapter.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+require "zizq"
+require "zizq/active_job_config"
+
+module ActiveJob
+  module QueueAdapters
+    # ActiveJob adapter for Zizq jobs.
+    #
+    # To use, set the queue adapter in your Rails configuration:
+    #
+    #   # config/application.rb
+    #   config.active_job.queue_adapter = :zizq
+    #
+    # And configure the Zizq client to dispatch to ActiveJob:
+    #
+    #   # config/initializers/zizq.rb
+    #   Zizq.configure do |c|
+    #     c.url = "http://localhost:7890"
+    #     c.dispatcher = ActiveJob::QueueAdapters::ZizqAdapter::Dispatcher
+    #   end
+    #
+    # To use Zizq features (unique jobs, backoff, retention) with ActiveJob
+    # classes, you can extend `Zizq::ActiveJobConfig` in your classes:
+    #
+    #   class SendEmailJob < ApplicationJob
+    #     extend Zizq::ActiveJobConfig
+    #
+    #     zizq_unique true, scope: :active
+    #     zizq_backoff exponent: 4.0, base: 15, jitter: 30
+    #   end
+    #
+    class ZizqAdapter
+      # Enqueue a job for immediate execution.
+      def enqueue(job)
+        result = Zizq.enqueue_raw(**build_enqueue_request(job).to_enqueue_params)
+        job.provider_job_id = result.id
+        job.successfully_enqueued = true
+        result
+      end
+
+      # Enqueue a job for execution at a specific time.
+      def enqueue_at(job, timestamp)
+        job.scheduled_at = timestamp
+        result = Zizq.enqueue_raw(**build_enqueue_request(job).to_enqueue_params)
+        job.provider_job_id = result.id
+        job.successfully_enqueued = true
+        result
+      end
+
+      # Enqueue multiple jobs atomically in a single bulk request.
+      #
+      # Called by `ActiveJob.perform_all_later` (Rails 7.1+).
+      # Returns the number of successfully enqueued jobs.
+      def enqueue_all(jobs)
+        results = Zizq.enqueue_bulk do |b|
+          jobs.each do |job|
+            b.enqueue_raw(**build_enqueue_request(job).to_enqueue_params)
+          end
+        end
+
+        jobs.zip(results).each do |job, result|
+          job.provider_job_id = result.id
+          job.successfully_enqueued = true
+        end
+
+        jobs.size
+      rescue => e
+        jobs.each { |job| job.successfully_enqueued = false }
+        raise e
+      end
+
+      # Dispatcher for Zizq workers that executes ActiveJob payloads.
+      #
+      # ActiveJob handles its own deserialization, callbacks, and error
+      # handling. We just pass the serialized payload to `Base.execute`.
+      module Dispatcher
+        def self.call(job)
+          ActiveJob::Base.execute(job.payload)
+        end
+      end
+
+      private
+
+      def build_enqueue_request(job)
+        klass = job.class
+
+        req = Zizq::EnqueueRequest.new(
+          queue:    job.queue_name,
+          type:     klass.name,
+          payload:  job.serialize,
+          priority: job.priority,
+          ready_at: job.scheduled_at
+        )
+
+        if klass.respond_to?(:zizq_unique) && klass.zizq_unique
+          req.unique_key = klass.zizq_unique_key(*job.arguments)
+          req.unique_while = klass.zizq_unique_scope
+        end
+
+        req.retry_limit  = klass.zizq_retry_limit  if klass.respond_to?(:zizq_retry_limit) && klass.zizq_retry_limit
+        req.backoff      = klass.zizq_backoff       if klass.respond_to?(:zizq_backoff) && klass.zizq_backoff
+        req.retention    = klass.zizq_retention     if klass.respond_to?(:zizq_retention) && klass.zizq_retention
+
+        req
+      end
+    end
+  end
+end

data/lib/zizq/ack_processor.rb

@@ -0,0 +1,132 @@
+# Copyright (c) 2026 Chris Corbyn <chris@zizq.io>
+# Licensed under the MIT License. See LICENSE file for details.
+
+# rbs_inline: enabled
+# frozen_string_literal: true
+
+require "async"
+require "async/barrier"
+
+module Zizq
+  # Dedicated background thread that processes ack/nack HTTP requests on
+  # behalf of worker threads, decoupling job processing from network I/O.
+  #
+  # Workers push Ack/Nack items to a thread-safe queue. The processor runs
+  # an async event loop that spawns an independent fiber per ack/nack
+  # request, enabling true concurrent I/O over a single HTTP/2 connection.
+  # Each fiber handles its own retries with exponential backoff.
+  class AckProcessor
+    # Immutable value object representing a successful job completion.
+    Ack = Data.define(:job_id)
+
+    # Immutable value object representing a job failure.
+    Nack = Data.define(:job_id, :message, :error_type, :backtrace)
+
+    # @rbs client: Client
+    # @rbs capacity: Integer
+    # @rbs logger: Logger
+    # @rbs backoff: Backoff
+    # @rbs return: void
+    def initialize(client:, capacity:, logger:, backoff:)
+      @client = client
+      @logger = logger
+      @backoff = backoff
+      @queue = Thread::SizedQueue.new(capacity)
+    end
+
+    # Push an Ack or Nack to the processing queue.
+    # Blocks if the queue is at capacity (backpressure).
+    #
+    # @rbs item: Ack | Nack
+    # @rbs return: void
+    def push(item)
+      @queue.push(item)
+    end
+
+    # Start the background processor thread.
+    def start #: () -> Thread
+      @thread = Thread.new { run }
+      @thread.name = "zizq-ack-processor"
+      @thread
+    end
+
+    # Close the queue and wait for the processor to drain. Waits indefinitely —
+    # callers who want a deadline should wrap the call in `Timeout::timeout`.
+    #
+    # @rbs return: void
+    def stop
+      @queue.close
+      @thread&.join
+    end
+
+    private
+
+    def run #: () -> void
+      Sync do
+        barrier = Async::Barrier.new
+
+        while (item = @queue.pop)
+          # Put the item into a batch.
+          batch = [item]
+
+          # Drain any additional ready items into the batch.
+          loop do
+            batch << @queue.pop(true) # non-blocking
+          rescue ThreadError
+            break
+          end
+
+          # Partition: acks go bulk, nacks go individually.
+          acks, nacks = batch.partition { |i| i.is_a?(Ack) }
+
+          unless acks.empty?
+            barrier.async { process_ack_batch(acks) }
+          end
+
+          nacks.each do |nack|
+            barrier.async { process_nack(nack) }
+          end
+        end
+
+        barrier.wait
+      end
+    rescue => e
+      @logger.error { "Ack processor crashed: #{e.class}: #{e.message}" }
+      @logger.debug { e.backtrace&.join("\n") }
+    end
+
+    def process_ack_batch(acks) #: (Array[Ack]) -> void
+      backoff = @backoff.fresh
+      ids = acks.map(&:job_id)
+      begin
+        @client.report_success_bulk(ids)
+      rescue ClientError => e
+        @logger.warn { "Bulk ack (#{ids.size} jobs) returned #{e.status} (dropping: #{e.message})" }
+      rescue => e
+        @logger.warn { "Retrying bulk ack (#{ids.size} jobs) in #{backoff.duration}s: #{e.message}" }
+        backoff.wait
+        retry
+      end
+    end
+
+    def process_nack(nack) #: (Nack) -> void
+      backoff = @backoff.fresh
+      begin
+        @client.report_failure(
+          nack.job_id,
+          message: nack.message,
+          error_type: nack.error_type,
+          backtrace: nack.backtrace
+        )
+      rescue NotFoundError
+        @logger.debug { "Nack for #{nack.job_id} returned 404 (already handled)" }
+      rescue ClientError => e
+        @logger.error { "Nack for #{nack.job_id} returned #{e.status} (dropping)" }
+      rescue => e
+        @logger.warn { "Retrying nack for #{nack.job_id} in #{backoff.duration}s: #{e.message}" }
+        backoff.wait
+        retry
+      end
+    end
+  end
+end