zizq 0.3.0 → 0.3.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a94a61282aba9442ace4ca8a3a302f75a843b14a76bd7d7748f006d5c8bf0888
-  data.tar.gz: 202f0842b2a2b22d8fce753c197635ea456ac94955f6f266f806471d01d06a7f
+  metadata.gz: 5f0af940d511a8e1aa6d89df8ca13e98733430827d5f3202bcf7434a94ee02da
+  data.tar.gz: 9341d2815e344b3e4b8ca402185e3de01bd488cb5a3159f18e132d3c65cc18ca
 SHA512:
-  metadata.gz: 03cb04925c7aac0aaaee30f86e27448641ec4864b903bedeee83cd61b0d0ed803655dd69c8ed586c4b83faa3d8d910c13c589398ca3157f130c569fa3edce5e9
-  data.tar.gz: b3a2c1232195698681ae743e04db5aff883c4e82e36bab9d1735b7459c7db5fdbcb9829171fa30318cec4ac01dc34432a79c2760824f4d2db93c89fbda12da58
+  metadata.gz: a3e04dffd06a36db8ca940105675428390867bd8dee62b2bcf0ef7cbeef03fe080b35bf93061e9ec00b6834be0940e1d69d7bd837178718a0bd288b6895464c3
+  data.tar.gz: 9d5a7d77ca3e143dbcc8c5bb72a58eb1c60092335d206579646dac8df3cbf178a9627a0d8e7a68e394d2b07c32a60a82c915ab049175624760a314042d12f9b7

data/README.md

@@ -1,12 +1,13 @@
 # Zizq — Official Ruby Client
 
+This is the official Zizq client library for Ruby.
+
 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)
+[![Gem Version](https://img.shields.io/gem/v/zizq.svg)](https://rubygems.org/gems/zizq)
 
 ## Features
 
@@ -28,26 +29,63 @@ This is the official Zizq client library for Ruby.
 > If you have not yet installed the Zizq server, follow the
 > [Getting Started](https://zizq.io/docs/getting-started) guide first.
 
-Add it to your application's `Gemfile`.
+Add it to your application's `Gemfile`:
 
-``` ruby
-gem 'zizq', '~> 0.3.0'
+```ruby
+gem 'zizq', '~> 0.3.2'
 ```
 
 Or install it manually:
 
 ```shell
-$ gem install zizq -v 0.3.0
+$ gem install zizq -v 0.3.2
+```
+
+Ruby **3.2.8 or newer** is required. Client and server share version
+numbers — keep the client's major/minor at or below the server's.
+
+## Configuration
+
+Out of the box, the client talks to a server at `http://localhost:7890` —
+fine for local development. For anything else, configure it with
+`Zizq.configure` in your application's bootstrap (e.g. a Rails initializer):
+
+```ruby
+require 'zizq'
+
+Zizq.configure do |c|
+  c.url    = 'https://zizq.your.network:7890'
+  c.logger = Logger.new('log/zizq.log')
+
+  c.tls.ca = '/path/to/server-ca-cert.pem'
+
+  # Optional worker defaults — applied to every Zizq::Worker
+  # instance and to runs of the `zizq-worker` executable. Explicit
+  # kwargs or CLI flags override these.
+  c.worker.queues       = ['emails', 'payments']
+  c.worker.fiber_count  = 25
+end
 ```
 
-## Example
+For mutual TLS, also set `c.tls.client_cert` and `c.tls.client_key`.
+
+> [!CAUTION]
+> If your server is exposed directly to the internet, it should require
+> mutual TLS — otherwise anybody can talk to it.
+
+## Usage
 
 > [!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.
+> This README is an overview. The
+> [full documentation](https://zizq.io/docs/clients/ruby/) covers each
+> feature in depth — middleware, custom dispatchers, Active Job, job
+> querying, and more.
 
-Mixin-based job class.
+### Defining a job
+
+In most Ruby applications, a job is a plain class that includes `Zizq::Job`.
+The class declares its defaults with the `zizq_*` DSL and implements
+`#perform`:
 
 ```ruby
 class SendEmailJob
@@ -55,54 +93,140 @@ class SendEmailJob
 
   zizq_queue 'emails'
   zizq_priority 100
+  zizq_retry_limit 5
 
   def perform(user_id, template:)
-    # your application logic here
+    user = User.find(user_id)
+    Mailer.deliver(user, template)
   end
 end
 ```
 
-Enqueueing a job.
+Every default — `zizq_queue`, `zizq_priority`, `zizq_retry_limit`,
+`zizq_backoff`, `zizq_retention`, `zizq_unique` — can be overridden per
+enqueue. The job's class name (`"SendEmailJob"`) becomes the API-level job
+type, so keep it stable once jobs are in flight.
+
+### Enqueuing jobs
+
+Enqueue a job by passing the class and the arguments your `#perform` method
+expects:
+
+```ruby
+job = Zizq.enqueue(SendEmailJob, 42, template: 'welcome')
+job.id  # => "03fu0wm75gxgmfyfplwvazhex"
+```
+
+Override defaults for a single call with `Zizq.enqueue_with`, or with a block
+that mutates the request:
 
 ```ruby
-Zizq.enqueue(SendEmailJob, 42, template: 'welcome')
+# Don't retry this one.
+Zizq.enqueue_with(retry_limit: 0).enqueue(SendEmailJob, 42, template: 'welcome')
+
+# Bump the priority via the block form.
+Zizq.enqueue(SendEmailJob, 42, template: 'welcome') do |req|
+  req.priority = 1000
+end
+```
+
+Schedule a job for later with `delay` (seconds from now) or an absolute
+`ready_at`:
+
+```ruby
+Zizq.enqueue_with(delay: 3600).enqueue(SendEmailJob, 42, template: 'welcome')
+Zizq.enqueue_with(ready_at: Time.new(2027, 3, 15, 14, 30)).enqueue(SendEmailJob, 42, template: 'welcome')
+```
+
+To enqueue many jobs efficiently, `Zizq.enqueue_bulk` sends them in a single
+atomic request — across queues and job types, and `enqueue_raw` enqueues can
+be mixed in too:
+
+```ruby
+Zizq.enqueue_bulk do |b|
+  signups.each { |user_id| b.enqueue(SendEmailJob, user_id, template: 'welcome') }
+end
 ```
 
 > [!NOTE]
-> Jobs can also be enqueued and processed without `Zizq::Job`, which is
-> designed to support interoperability with any programming language.
+> Jobs can also be enqueued without `Zizq::Job` via `Zizq.enqueue_raw` —
+> designed for cross-language workflows where, for example, a Ruby app
+> enqueues jobs consumed by a Go service.
+
+### Running a worker
 
-Using the included `zizq-worker` executable.
+Jobs are processed by a worker, typically in a separate process. The simplest
+way is the `zizq-worker` executable bundled with the gem. **Rails apps need
+no arguments** — `zizq-worker` auto-detects `config/environment.rb` when run
+from the app's root:
 
 ```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.
+$ bundle exec zizq-worker
+I, [...] INFO -- : Zizq worker starting: 1 threads, 25 fibers, prefetch=50
+I, [...] INFO -- : Connected. Listening for jobs.
 ```
 
-> [!NOTE]
-> Workers can also be created directly in code. There is no requirement to use
-> `zizq-worker`.
+For Sinatra or other apps, pass the entrypoint explicitly:
+
+```shell
+$ bundle exec zizq-worker app.rb
+```
+
+Worker defaults (`queues`, `thread_count`, `fiber_count`, `prefetch`) come
+from your `Zizq.configure { |c| c.worker.* }` block. CLI flags
+(`--threads`, `--fibers`, `--queue`, `--all-queues`, etc.) override the
+configured defaults when needed. Leave `--fibers 1` if your application
+isn't fiber-safe — no `Async` context is loaded in that case. `INT` /
+`TERM` trigger a graceful shutdown (drains in-flight jobs up to
+`--shutdown-deadline`, default 30s).
+
+For more control — for example running the worker in-process alongside a
+Rack app — construct `Zizq::Worker` directly:
+
+```ruby
+require 'zizq'
+
+# Picks up queues, fiber_count, etc. from Zizq.configure { |c| c.worker.* };
+# any kwarg here overrides those defaults.
+worker = Zizq::Worker.new(queues: ['emails', 'payments'])
+
+Signal.trap('INT') { worker.stop }
+worker.run  # blocks until the worker stops
+```
+
+`#run` blocks until the worker terminates; `#stop` drains in-flight jobs
+gracefully, `#kill` forces an immediate stop. On any unclean shutdown the
+server returns unfinished jobs to the queue — no job is lost.
+
+### Recurring jobs (cron)
+
+Define a cron schedule in your application's startup code. Definitions are
+idempotent — every process can safely define the same schedule, and Zizq
+keeps the server in sync by adding, replacing, and removing entries as the
+definition changes. Cron requires a Pro license on the server.
+
+```ruby
+Zizq.define_crontab('maintenance', timezone: 'Europe/London') do |cron|
+  # Every 15 minutes.
+  cron.define_entry('refresh_warehouse', '*/15 * * * *').enqueue(
+    RefreshWarehouseJob, incremental: true
+  )
+
+  # 9am London time, every day.
+  cron.define_entry('daily_digest', '0 9 * * *').enqueue(SendDailyDigestJob)
+end
+```
+
+Once defined, schedules can be inspected and managed via
+`Zizq.crontab('maintenance')` — paused/resumed at the schedule level or per
+entry, and deleted entirely when no longer needed.
 
 ## 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 Ruby Client Source](https://github.com/zizq-labs/zizq-ruby)
 * [Zizq Source](https://github.com/zizq-labs/zizq)
 
 ## Support & Feedback
@@ -111,3 +235,7 @@ 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.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

data/bin/zizq-worker

@@ -11,58 +11,96 @@ 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))
+# --- Defaults from env vars (nil = "not set, defer to Zizq.configure then Worker default") ---
+#
+# Note: env-var-unset values stay as nil rather than being seeded
+# with the Worker's `DEFAULT_*` constants. This lets `Zizq.configure
+# { |c| c.worker.<field> = ... }` win when neither the env nor the
+# CLI explicitly set the value.
+
+thread_count = ENV.key?("ZIZQ_THREADS") ? Integer(ENV["ZIZQ_THREADS"]) : nil
+fiber_count = ENV.key?("ZIZQ_FIBERS") ? Integer(ENV["ZIZQ_FIBERS"]) : nil
 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
-  []
+retry_min_wait = ENV.key?("ZIZQ_RETRY_MIN_WAIT") ? Float(ENV["ZIZQ_RETRY_MIN_WAIT"]) : nil
+retry_max_wait = ENV.key?("ZIZQ_RETRY_MAX_WAIT") ? Float(ENV["ZIZQ_RETRY_MAX_WAIT"]) : nil
+retry_multiplier = ENV.key?("ZIZQ_RETRY_MULTIPLIER") ? Float(ENV["ZIZQ_RETRY_MULTIPLIER"]) : nil
+
+# Queue state: explicit list vs. all-queues vs. unset (defer to config).
+# `queues_set_by_user` toggles to true once any CLI/env queue flag is seen.
+queues = []
+queues_set_by_user = false
+all_queues = false
+
+if ENV.key?("ZIZQ_QUEUES")
+  parsed = ENV["ZIZQ_QUEUES"].split(",").map(&:strip).reject(&:empty?)
+  queues = parsed
+  queues_set_by_user = true
 end
 
 # --- CLI flag parsing (overrides env var defaults) ---
 
 parser = OptionParser.new do |opts|
-  opts.banner = "Usage: zizq-worker [OPTIONS] <ENTRYPOINT>"
+  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 "Start a Zizq worker process."
+  opts.separator ""
+  opts.separator "The ENTRYPOINT is a Ruby file that loads your application before the"
+  opts.separator "worker starts (so Zizq.configure runs and your job classes are loaded)."
+  opts.separator "Resolved in this order:"
+  opts.separator ""
+  opts.separator "  1. The ENTRYPOINT positional argument, if given."
+  opts.separator "  2. The ZIZQ_ENTRYPOINT environment variable, if set."
+  opts.separator "  3. config/environment.rb in the current directory, if it exists."
+  opts.separator "     (This is the canonical Rails boot file, so Rails apps run with"
+  opts.separator "     no entrypoint argument at all.)"
+  opts.separator ""
+  opts.separator "Configuration:"
+  opts.separator ""
+  opts.separator "  Client config (url, format, TLS, logger) and worker defaults"
+  opts.separator "  (queues, thread/fiber count, prefetch, etc.) belong in your"
+  opts.separator "  Zizq.configure block inside the entrypoint, e.g.:"
   opts.separator ""
-  opts.separator "Client configuration (url, format, logger) should be set in the"
-  opts.separator "entrypoint via Zizq.configure."
+  opts.separator "    Zizq.configure do |c|"
+  opts.separator "      c.url = \"https://...\""
+  opts.separator "      c.worker.queues = [\"emails\", \"webhooks\"]"
+  opts.separator "      c.worker.fiber_count = 25"
+  opts.separator "    end"
+  opts.separator ""
+  opts.separator "  CLI flags and env vars below override whatever is configured there."
   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|
+  opts.on("-t", "--threads N", Integer, "Number of worker threads (fallback 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|
+  opts.on("-f", "--fibers N", Integer, "Number of fibers per thread (fallback 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|
+  opts.on("-p", "--prefetch N", Integer, "Prefetch count (fallback 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
+    # First CLI `-q` replaces the env var default; subsequent ones
+    # accumulate. `queues_from_cli` distinguishes that from
+    # `queues_set_by_user` (which also tracks env-var input).
     unless queues_from_cli
       queues = []
       queues_from_cli = true
     end
+    queues_set_by_user = true
     queues.concat(q.split(",").map(&:strip).reject(&:empty?))
   end
 
+  opts.on("--all-queues", "Override any configured queues to process all queues (mutually exclusive with -q)") do
+    all_queues = true
+  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
@@ -100,22 +138,38 @@ end
 
 # --- Validate options ---
 
-if thread_count < 1
+if thread_count && thread_count < 1
   warn "Error: --threads must be at least 1 (got #{thread_count})"
   exit 1
 end
 
-if fiber_count < 1
+if fiber_count && fiber_count < 1
   warn "Error: --fibers must be at least 1 (got #{fiber_count})"
   exit 1
 end
 
-# --- Validate and load entrypoint ---
+if all_queues && queues_set_by_user
+  warn "Error: --all-queues and --queue (or ZIZQ_QUEUES) are mutually exclusive."
+  exit 1
+end
+
+# --- Resolve and load entrypoint ---
+#
+# Precedence:
+#   1. CLI argument: `zizq-worker path/to/entrypoint.rb`
+#   2. ZIZQ_ENTRYPOINT env var
+#   3. Auto-detect: `config/environment.rb` (Rails apps)
 
-entrypoint = ARGV[0]
+entrypoint = ARGV[0] || ENV["ZIZQ_ENTRYPOINT"] || (
+  File.file?("config/environment.rb") ? "config/environment.rb" : nil
+)
 
 if entrypoint.nil?
-  warn "Error: missing required ENTRYPOINT argument."
+  warn "Error: no entrypoint found."
+  warn ""
+  warn "Specify one as a CLI argument or via the ZIZQ_ENTRYPOINT env var."
+  warn "Rails apps are detected automatically via the presence of"
+  warn "config/environment.rb in the current directory."
   warn ""
   warn parser.help
   exit 1
@@ -128,17 +182,33 @@ end
 
 require File.expand_path(entrypoint)
 
-# --- Start the worker ---
+# --- Resolve queues ---
+#
+#   --all-queues          -> []  (explicit "all queues" override)
+#   -q / ZIZQ_QUEUES set  -> the parsed list
+#   neither               -> nil (defer to Zizq.configure → Worker default)
+
+queues_value =
+  if all_queues
+    []
+  elsif queues_set_by_user
+    queues
+  end
 
-worker = Zizq::Worker.new(
+# --- Start the worker ---
+#
+# `.compact` drops any unset kwarg so `Zizq::Worker#initialize`'s
+# fallback chain (kwarg -> Zizq.configuration.worker -> DEFAULT_*)
+# applies for whichever values weren't given on the CLI / via env.
+worker = Zizq::Worker.new(**{
   thread_count:,
   fiber_count:,
   prefetch:,
-  queues:,
+  queues: queues_value,
   retry_min_wait:,
   retry_max_wait:,
   retry_multiplier:,
-)
+}.compact)
 
 # `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
@@ -154,7 +224,10 @@ stopping = false
 %w[INT TERM].each do |signal|
   Signal.trap(signal) do
     if stopping
-      exit(1)
+      # Second signal: hard exit. `exit!` (not `exit`) so SystemExit
+      # terminates the process from any thread context, including
+      # the signal trap.
+      exit!(1)
     else
       worker.stop
       stopping = true
@@ -164,7 +237,10 @@ stopping = false
         worker.logger.warn do
           "Worker did not stop within #{shutdown_deadline}s, killing..."
         end
-        exit(1)
+        # `exit!` rather than `exit`: this runs in a watchdog thread,
+        # and `exit` would only raise SystemExit in *this* thread,
+        # leaving main (joining the hung worker thread) untouched.
+        exit!(1)
       end
     end
   end

data/lib/zizq/client.rb

@@ -50,15 +50,30 @@ module Zizq
     # Initialize a new instance of the client with the given base URL and
     # optional format options.
     #
+    # `read_timeout` and `stream_idle_timeout` are per-operation socket
+    # I/O timeouts (seconds). Each individual socket read/write is
+    # bounded by the timeout. The streaming `#take_jobs` endpoint uses
+    # `stream_idle_timeout` because the server sends heartbeats at
+    # periodic intervals which keeps the connection alive.
+    #
     # @rbs url: String
     # @rbs format: Zizq::format
     # @rbs ssl_context: OpenSSL::SSL::SSLContext?
+    # @rbs read_timeout: Numeric
+    # @rbs stream_idle_timeout: Numeric
     # @rbs return: void
-    def initialize(url:, format: :msgpack, ssl_context: nil)
+    def initialize(url:,
+                   format: :msgpack,
+                   ssl_context: nil,
+                   read_timeout: 30,
+                   stream_idle_timeout: 30)
       @url = url.chomp("/")
       @format = format
 
-      endpoint_options = { protocol: Async::HTTP::Protocol::HTTP2 } #: Hash[Symbol, untyped]
+      endpoint_options = {
+        protocol: Async::HTTP::Protocol::HTTP2,
+        timeout: read_timeout,
+      } #: Hash[Symbol, untyped]
       endpoint_options[:ssl_context] = ssl_context if ssl_context
 
       @endpoint = Async::HTTP::Endpoint.parse(
@@ -73,8 +88,14 @@ module Zizq
       # on separate threads with their own HTTP/2 clients, so they're
       # unaffected either way. HTTP/1.1 gives the stream a plain TCP
       # socket with no framing tax and measurably better throughput.
+      #
+      # The stream endpoint uses `stream_idle_timeout` for its socket
+      # timeout so server heartbeats (~3s) keep it alive while only
+      # genuinely dead connections (no data for the full window)
+      # trigger a reconnect.
       stream_endpoint_options = endpoint_options.merge(
         protocol: Async::HTTP::Protocol::HTTP11,
+        timeout: stream_idle_timeout,
       )
       @stream_endpoint = Async::HTTP::Endpoint.parse(
         @url,
@@ -709,7 +730,12 @@ module Zizq
           response.close rescue nil
         end
       end
-    rescue SocketError, IOError, EOFError, Errno::ECONNRESET, Errno::EPIPE,
+    rescue SocketError,
+           IOError,
+           EOFError,
+           Errno::ECONNRESET,
+           Errno::EPIPE,
+           IO::TimeoutError,
            OpenSSL::SSL::SSLError => e
       raise ConnectionError, e.message
     end

data/lib/zizq/configuration.rb

@@ -29,18 +29,26 @@ module Zizq
     # Logger instance to which to write log messages.
     attr_accessor :logger #: Logger
 
-    # TLS options for connecting to the server over HTTPS.
+    # Per-operation socket I/O timeout (seconds) for regular API calls
+    # (enqueue, queries, mutations). Each socket read/write is bounded
+    # by this value. A request whose handshake or any single read exceeds
+    # this raises `IO::TimeoutError`.
     #
-    # All values may be PEM-encoded strings or file paths.
+    # Default: 30.
+    attr_accessor :read_timeout #: Numeric
+
+    # Per-operation socket I/O timeout (seconds) for the long-lived
+    # `#take_jobs` stream. The server sends heartbeats every ~3 seconds,
+    # so each read returns within that window and keeps the connection
+    # alive; the connection only times out if the server falls silent for
+    # longer than this. The Worker catches the resulting error and
+    # reconnects with backoff.
     #
-    #   {
-    #     ca:          "path/to/ca-cert.pem",       # CA certificate for server verification
-    #     client_cert: "path/to/client-cert.pem",   # Client certificate for mTLS
-    #     client_key:  "path/to/client-key.pem",    # Client private key for mTLS
-    #   }
+    # Should be comfortably above the server's heartbeat interval to
+    # avoid false-positive disconnects.
     #
-    # Note: Mutual TLS support requires a Zizq Pro license on the server.
-    attr_accessor :tls #: Zizq::tls_options?
+    # Default: 30.
+    attr_accessor :stream_idle_timeout #: Numeric
 
     # Middleware chain for enqueue. Each middleware receives an
     # `EnqueueRequest` and a chain to continue.
@@ -55,10 +63,79 @@ module Zizq
       @format = :msgpack
       @logger = Logger.new($stdout, level: Logger::INFO)
       @tls = nil
+      @worker = nil
+      @read_timeout = 30
+      @stream_idle_timeout = 30
       @enqueue_middleware = Middleware::Chain.new(Identity.new)
       @dequeue_middleware = Middleware::Chain.new(Zizq::Job)
     end
 
+    # TLS settings for connecting to the server over HTTPS.
+    #
+    # Configure via the `c.tls` accessors inside a `Zizq.configure`
+    # block:
+    #
+    #   Zizq.configure do |c|
+    #     c.tls.ca          = "/path/to/server-ca-cert.pem"
+    #     c.tls.client_cert = "/path/to/client-cert.pem"
+    #     c.tls.client_key  = "/path/to/client-key.pem"
+    #   end
+    #
+    # All values may be PEM-encoded strings or file paths. Set
+    # `c.tls = nil` to explicitly disable TLS.
+    #
+    # Note: Mutual TLS support requires a Zizq Pro license on the
+    # server.
+    def tls #: () -> TlsConfiguration
+      @tls ||= TlsConfiguration.new
+    end
+
+    def tls=(value) #: ((Hash[Symbol, String?] | TlsConfiguration)?) -> void
+      case value
+      when nil
+        @tls = nil
+      when TlsConfiguration
+        @tls = value
+      when Hash
+        @tls = TlsConfiguration.new(**value)
+      else
+        raise ArgumentError,
+          "Zizq.configure: tls= expects a Hash, Zizq::TlsConfiguration, or nil " \
+          "(got #{value.class})"
+      end
+    end
+
+    # Defaults for `Zizq::Worker` instances. Apps populate this in
+    # their `Zizq.configure` block:
+    #
+    #   Zizq.configure do |c|
+    #     c.worker.queues = ["emails"]
+    #     c.worker.fiber_count = 25
+    #   end
+    #
+    # Anything left unset here falls through to the Worker's
+    # hardcoded defaults; anything explicitly passed to `Worker.new`
+    # (or set via `zizq-worker` CLI flags / env vars) overrides
+    # whatever is configured here.
+    def worker #: () -> WorkerConfiguration
+      @worker ||= WorkerConfiguration.new
+    end
+
+    def worker=(value) #: ((Hash[Symbol, untyped] | WorkerConfiguration)?) -> void
+      case value
+      when nil
+        @worker = nil
+      when WorkerConfiguration
+        @worker = value
+      when Hash
+        @worker = WorkerConfiguration.new(**value)
+      else
+        raise ArgumentError,
+          "Zizq.configure: worker= expects a Hash, Zizq::WorkerConfiguration, or nil " \
+          "(got #{value.class})"
+      end
+    end
+
     # The job dispatcher.
     # This is the terminal of the dequeue middleware chain.
     # Defaults to `Zizq::Job` which finds and executes jobs written by mixing
@@ -89,6 +166,14 @@ module Zizq
         raise ArgumentError, "Zizq.configure: format must be :msgpack or :json, got #{format.inspect}"
       end
 
+      unless read_timeout.is_a?(Numeric) && read_timeout > 0
+        raise ArgumentError, "Zizq.configure: read_timeout must be a positive number, got #{read_timeout.inspect}"
+      end
+
+      unless stream_idle_timeout.is_a?(Numeric) && stream_idle_timeout > 0
+        raise ArgumentError, "Zizq.configure: stream_idle_timeout must be a positive number, got #{stream_idle_timeout.inspect}"
+      end
+
       tls = @tls
       validate_tls!(tls) if tls
     end
@@ -99,21 +184,22 @@ module Zizq
     def ssl_context #: () -> OpenSSL::SSL::SSLContext?
       tls = @tls
       return nil unless tls
+      return nil if tls.to_h.values.all?(&:nil?)
 
       ctx = OpenSSL::SSL::SSLContext.new
 
-      if (ca = tls[:ca])
+      if (ca = tls.ca)
         store = OpenSSL::X509::Store.new
         store.add_cert(load_cert(ca))
         ctx.cert_store = store
         ctx.verify_mode = OpenSSL::SSL::VERIFY_PEER
       end
 
-      if (client_cert = tls[:client_cert])
+      if (client_cert = tls.client_cert)
         ctx.cert = load_cert(client_cert)
       end
 
-      if (client_key = tls[:client_key])
+      if (client_key = tls.client_key)
         ctx.key = load_key(client_key)
       end
 
@@ -130,14 +216,13 @@ module Zizq
 
     private
 
-    # @rbs tls: Zizq::tls_options
-    def validate_tls!(tls) #: (Zizq::tls_options) -> void
-      if tls[:client_cert] && !tls[:client_key]
-        raise ArgumentError, "Zizq.configure: tls[:client_key] is required when tls[:client_cert] is set"
+    def validate_tls!(tls) #: (TlsConfiguration) -> void
+      if tls.client_cert && !tls.client_key
+        raise ArgumentError, "Zizq.configure: tls.client_key is required when tls.client_cert is set"
       end
 
-      if tls[:client_key] && !tls[:client_cert]
-        raise ArgumentError, "Zizq.configure: tls[:client_cert] is required when tls[:client_key] is set"
+      if tls.client_key && !tls.client_cert
+        raise ArgumentError, "Zizq.configure: tls.client_cert is required when tls.client_key is set"
       end
     end
 

data/lib/zizq/tls_configuration.rb

@@ -0,0 +1,27 @@
+# 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
+
+module Zizq
+  # TLS settings for connecting to the Zizq server over HTTPS.
+  #
+  # Set inside a `Zizq.configure` block via the `c.tls` accessors:
+  #
+  #   Zizq.configure do |c|
+  #     c.tls.ca          = "/path/to/ca-cert.pem"
+  #     c.tls.client_cert = "/path/to/client-cert.pem"
+  #     c.tls.client_key  = "/path/to/client-key.pem"
+  #   end
+  #
+  # All values may be PEM-encoded strings or file paths.
+  #
+  # Note: Mutual TLS support requires a Zizq Pro license on the server.
+  TlsConfiguration = Struct.new(
+    :ca,          #: String?
+    :client_cert, #: String?
+    :client_key,  #: String?
+    keyword_init: true
+  )
+end

data/lib/zizq/version.rb

@@ -5,5 +5,5 @@
 # frozen_string_literal: true
 
 module Zizq
-  VERSION = "0.3.0" #: String
+  VERSION = "0.3.2" #: String
 end

data/lib/zizq/worker.rb

@@ -15,7 +15,7 @@ module Zizq
   #
   # Total concurrency is calculated as `thread_count * fiber_count`.
   class Worker
-    DEFAULT_THREADS = 5 #: Integer
+    DEFAULT_THREADS = 1 #: Integer
     DEFAULT_FIBERS = 1 #: Integer
     DEFAULT_RETRY_MIN_WAIT = 1
     DEFAULT_RETRY_MAX_WAIT = 30
@@ -50,11 +50,6 @@ module Zizq
     # pipeline full while ack round-trips are in flight.
     attr_reader :prefetch #: Integer
 
-    # Proc to derive a worker ID string for each thread and fiber.
-    #
-    # When not present, the Zizq server assigns a random worker ID.
-    attr_reader :worker_id_proc #: (^(Integer, Integer) -> String?)?
-
     # An instance of a Logger to be used for worker logging.
     attr_reader :logger #: Logger
 
@@ -66,45 +61,55 @@ module Zizq
     # their own `Zizq::Middleware::Chain` if middleware needs to be applied.
     attr_reader :dispatcher #: ^(Resources::Job) -> void
 
-    # @rbs queues: Array[String]
-    # @rbs thread_count: Integer
-    # @rbs fiber_count: Integer
+    # All keyword arguments default to `nil` and follow a three-level
+    # fallback chain:
+    #
+    #   1. Explicit kwarg passed to `Worker.new`.
+    #   2. `Zizq.configuration.worker.<field>` set in the app's
+    #      `Zizq.configure` block.
+    #   3. The Worker's hardcoded `DEFAULT_*` constants.
+    #
+    # @rbs queues: Array[String]?
+    # @rbs thread_count: Integer?
+    # @rbs fiber_count: Integer?
     # @rbs prefetch: Integer?
-    # @rbs retry_min_wait: (Float | Integer)
-    # @rbs retry_max_wait: (Float | Integer)
-    # @rbs retry_multiplier: (Float | Integer)
-    # @rbs worker_id: (^(Integer, Integer) -> String?)?
+    # @rbs retry_min_wait: (Float | Integer)?
+    # @rbs retry_max_wait: (Float | Integer)?
+    # @rbs retry_multiplier: (Float | Integer)?
     # @rbs logger: Logger?
     # @rbs dispatcher: (^(Resources::Job) -> void)?
     # @rbs return: void
     def initialize(
-      queues: [],
-      thread_count: DEFAULT_THREADS,
-      fiber_count: DEFAULT_FIBERS,
+      queues: nil,
+      thread_count: nil,
+      fiber_count: nil,
       prefetch: nil,
-      retry_min_wait: DEFAULT_RETRY_MIN_WAIT,
-      retry_max_wait: DEFAULT_RETRY_MAX_WAIT,
-      retry_multiplier: DEFAULT_RETRY_MULTIPLIER,
-      worker_id: nil,
+      retry_min_wait: nil,
+      retry_max_wait: nil,
+      retry_multiplier: nil,
       logger: nil,
       dispatcher: nil
     )
-      raise ArgumentError, "thread_count must be at least 1 (got #{thread_count})" if thread_count < 1
-      raise ArgumentError, "fiber_count must be at least 1 (got #{fiber_count})" if fiber_count < 1
-
       Zizq.configuration.validate!
-
-      @queues = queues
-      @thread_count = thread_count
-      @fiber_count = fiber_count
-      @prefetch = prefetch || thread_count * fiber_count * 2
-      @retry_min_wait = retry_min_wait
-      @retry_max_wait = retry_max_wait
-      @retry_multiplier = retry_multiplier
-      @worker_id_proc = worker_id
+      config = Zizq.configuration.worker
+
+      @queues = queues || config.queues || []
+      @thread_count = thread_count || config.thread_count || DEFAULT_THREADS
+      @fiber_count = fiber_count || config.fiber_count || DEFAULT_FIBERS
+      @prefetch = prefetch || config.prefetch || @thread_count * @fiber_count * 2
+      @retry_min_wait = retry_min_wait || config.retry_min_wait || DEFAULT_RETRY_MIN_WAIT
+      @retry_max_wait = retry_max_wait || config.retry_max_wait || DEFAULT_RETRY_MAX_WAIT
+      @retry_multiplier = retry_multiplier || config.retry_multiplier || DEFAULT_RETRY_MULTIPLIER
       @logger = logger || Zizq.configuration.logger
       @dispatcher = dispatcher || Zizq.configuration.dequeue_middleware
 
+      if @thread_count < 1
+        raise ArgumentError, "thread_count must be at least 1 (got #{@thread_count})"
+      end
+      if @fiber_count < 1
+        raise ArgumentError, "fiber_count must be at least 1 (got #{@fiber_count})"
+      end
+
       reset_runtime_state
     end
 
@@ -360,14 +365,12 @@ module Zizq
         format("Worker %d:%d started", thread_idx, fiber_idx)
       end
 
-      wid = resolve_worker_id(thread_idx, fiber_idx)
-
       loop do
         # pop returns nil when queue is closed and empty
         job = @dispatch_queue.pop
         break if job.nil?
 
-        dispatch(job, wid)
+        dispatch(job)
       end
 
       logger.info do
@@ -392,7 +395,7 @@ module Zizq
     #
     # Delegates to the configured dispatcher (default: `Zizq::Job.dispatch`)
     # and reports success or failure.
-    def dispatch(job, worker_id) #: (Resources::Job, String?) -> void
+    def dispatch(job) #: (Resources::Job) -> void
       job_id, job_type = job.id, job.type
 
       begin
@@ -460,8 +463,5 @@ module Zizq
       ))
     end
 
-    def resolve_worker_id(thread_idx, fiber_idx) #: (Integer, Integer) -> String?
-      worker_id_proc&.call(thread_idx, fiber_idx)
-    end
   end
 end

data/lib/zizq/worker_configuration.rb

@@ -0,0 +1,48 @@
+# 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
+
+module Zizq
+  # Defaults for `Zizq::Worker` instances. Accessed via
+  # `Zizq.configuration.worker` and typically populated inside an
+  # application's `Zizq.configure` block:
+  #
+  #   Zizq.configure do |c|
+  #     c.url = "https://..."
+  #     c.worker.queues = ["emails", "webhooks"]
+  #     c.worker.thread_count = 1
+  #     c.worker.fiber_count = 25
+  #   end
+  #
+  # Every field defaults to `nil`, meaning "use the Worker's own
+  # hardcoded default." Anything explicitly passed to `Worker.new` —
+  # or set via CLI flag / env var when launching `zizq-worker` —
+  # overrides whatever is set here.
+  #
+  # See `Zizq::Worker#initialize` for the full resolution order
+  # (explicit kwarg → Zizq.configuration.worker → `Worker::DEFAULT_*`).
+  #
+  # Fields:
+  #
+  # * `queues` — Queues to consume. `[]` means all queues.
+  # * `thread_count` — Number of worker threads.
+  # * `fiber_count` — Number of fibers per worker thread.
+  # * `prefetch` — Server-side prefetch limit. Defaults to
+  #   `2 * threads * fibers`.
+  # * `retry_min_wait` — Minimum reconnect backoff in seconds.
+  # * `retry_max_wait` — Maximum reconnect backoff in seconds.
+  # * `retry_multiplier` — Multiplicative backoff factor between
+  #   reconnect attempts.
+  WorkerConfiguration = Struct.new(
+    :queues,           #: Array[String]?
+    :thread_count,     #: Integer?
+    :fiber_count,      #: Integer?
+    :prefetch,         #: Integer?
+    :retry_min_wait,   #: (Float | Integer)?
+    :retry_max_wait,   #: (Float | Integer)?
+    :retry_multiplier, #: (Float | Integer)?
+    keyword_init: true
+  )
+end

data/lib/zizq.rb

@@ -29,7 +29,9 @@ module Zizq
   autoload :Lifecycle,           "zizq/lifecycle"
   autoload :Query,               "zizq/query"
   autoload :Resources,           "zizq/resources"
+  autoload :TlsConfiguration,    "zizq/tls_configuration"
   autoload :Worker,              "zizq/worker"
+  autoload :WorkerConfiguration, "zizq/worker_configuration"
 
   # Sentinel indicating a field should not be included in the request.
   # Used as the default for update parameters.
@@ -81,7 +83,9 @@ module Zizq
           @client = Client.new(
             url: configuration.url,
             format: configuration.format,
-            ssl_context: configuration.ssl_context
+            ssl_context: configuration.ssl_context,
+            read_timeout: configuration.read_timeout,
+            stream_idle_timeout: configuration.stream_idle_timeout
           )
         end
       end

data/sig/generated/zizq/client.rbs

@@ -42,11 +42,19 @@ module Zizq
     # Initialize a new instance of the client with the given base URL and
     # optional format options.
     #
+    # `read_timeout` and `stream_idle_timeout` are per-operation socket
+    # I/O timeouts (seconds). Each individual socket read/write is
+    # bounded by the timeout. The streaming `#take_jobs` endpoint uses
+    # `stream_idle_timeout` because the server sends heartbeats at
+    # periodic intervals which keeps the connection alive.
+    #
     # @rbs url: String
     # @rbs format: Zizq::format
     # @rbs ssl_context: OpenSSL::SSL::SSLContext?
+    # @rbs read_timeout: Numeric
+    # @rbs stream_idle_timeout: Numeric
     # @rbs return: void
-    def initialize: (url: String, ?format: Zizq::format, ?ssl_context: OpenSSL::SSL::SSLContext?) -> void
+    def initialize: (url: String, ?format: Zizq::format, ?ssl_context: OpenSSL::SSL::SSLContext?, ?read_timeout: Numeric, ?stream_idle_timeout: Numeric) -> void
 
     # Close all thread-local HTTP clients and release connections.
     def close: () -> untyped

data/sig/generated/zizq/configuration.rbs

@@ -22,18 +22,26 @@ module Zizq
     # Logger instance to which to write log messages.
     attr_accessor logger: Logger
 
-    # TLS options for connecting to the server over HTTPS.
+    # Per-operation socket I/O timeout (seconds) for regular API calls
+    # (enqueue, queries, mutations). Each socket read/write is bounded
+    # by this value. A request whose handshake or any single read exceeds
+    # this raises `IO::TimeoutError`.
     #
-    # All values may be PEM-encoded strings or file paths.
+    # Default: 30.
+    attr_accessor read_timeout: Numeric
+
+    # Per-operation socket I/O timeout (seconds) for the long-lived
+    # `#take_jobs` stream. The server sends heartbeats every ~3 seconds,
+    # so each read returns within that window and keeps the connection
+    # alive; the connection only times out if the server falls silent for
+    # longer than this. The Worker catches the resulting error and
+    # reconnects with backoff.
     #
-    #   {
-    #     ca:          "path/to/ca-cert.pem",       # CA certificate for server verification
-    #     client_cert: "path/to/client-cert.pem",   # Client certificate for mTLS
-    #     client_key:  "path/to/client-key.pem",    # Client private key for mTLS
-    #   }
+    # Should be comfortably above the server's heartbeat interval to
+    # avoid false-positive disconnects.
     #
-    # Note: Mutual TLS support requires a Zizq Pro license on the server.
-    attr_accessor tls: Zizq::tls_options?
+    # Default: 30.
+    attr_accessor stream_idle_timeout: Numeric
 
     # Middleware chain for enqueue. Each middleware receives an
     # `EnqueueRequest` and a chain to continue.
@@ -45,6 +53,42 @@ module Zizq
 
     def initialize: () -> untyped
 
+    # TLS settings for connecting to the server over HTTPS.
+    #
+    # Configure via the `c.tls` accessors inside a `Zizq.configure`
+    # block:
+    #
+    #   Zizq.configure do |c|
+    #     c.tls.ca          = "/path/to/server-ca-cert.pem"
+    #     c.tls.client_cert = "/path/to/client-cert.pem"
+    #     c.tls.client_key  = "/path/to/client-key.pem"
+    #   end
+    #
+    # All values may be PEM-encoded strings or file paths. Set
+    # `c.tls = nil` to explicitly disable TLS.
+    #
+    # Note: Mutual TLS support requires a Zizq Pro license on the
+    # server.
+    def tls: () -> untyped
+
+    def tls=: (untyped value) -> untyped
+
+    # Defaults for `Zizq::Worker` instances. Apps populate this in
+    # their `Zizq.configure` block:
+    #
+    #   Zizq.configure do |c|
+    #     c.worker.queues = ["emails"]
+    #     c.worker.fiber_count = 25
+    #   end
+    #
+    # Anything left unset here falls through to the Worker's
+    # hardcoded defaults; anything explicitly passed to `Worker.new`
+    # (or set via `zizq-worker` CLI flags / env vars) overrides
+    # whatever is configured here.
+    def worker: () -> untyped
+
+    def worker=: (untyped value) -> untyped
+
     # The job dispatcher.
     # This is the terminal of the dequeue middleware chain.
     # Defaults to `Zizq::Job` which finds and executes jobs written by mixing
@@ -79,8 +123,7 @@ module Zizq
 
     private
 
-    # @rbs tls: Zizq::tls_options
-    def validate_tls!: (Zizq::tls_options tls) -> untyped
+    def validate_tls!: (untyped tls) -> untyped
 
     # Load a certificate from a PEM string or file path.
     def load_cert: (untyped pem_or_path) -> untyped

data/sig/generated/zizq/tls_configuration.rbs

@@ -0,0 +1,27 @@
+# Generated from lib/zizq/tls_configuration.rb with RBS::Inline
+
+module Zizq
+  # TLS settings for connecting to the Zizq server over HTTPS.
+  #
+  # Set inside a `Zizq.configure` block via the `c.tls` accessors:
+  #
+  #   Zizq.configure do |c|
+  #     c.tls.ca          = "/path/to/ca-cert.pem"
+  #     c.tls.client_cert = "/path/to/client-cert.pem"
+  #     c.tls.client_key  = "/path/to/client-key.pem"
+  #   end
+  #
+  # All values may be PEM-encoded strings or file paths.
+  #
+  # Note: Mutual TLS support requires a Zizq Pro license on the server.
+  class TlsConfiguration < Struct[String?]
+    attr_accessor ca(): String?
+
+    attr_accessor client_cert(): String?
+
+    attr_accessor client_key(): String?
+
+    def self.new: (?ca: String?, ?client_cert: String?, ?client_key: String?) -> instance
+                | ({ ?ca: String?, ?client_cert: String?, ?client_key: String? }) -> instance
+  end
+end

data/sig/generated/zizq/worker.rbs

@@ -46,11 +46,6 @@ module Zizq
     # pipeline full while ack round-trips are in flight.
     attr_reader prefetch: Integer
 
-    # Proc to derive a worker ID string for each thread and fiber.
-    #
-    # When not present, the Zizq server assigns a random worker ID.
-    attr_reader worker_id_proc: (^(Integer, Integer) -> String?)?
-
     # An instance of a Logger to be used for worker logging.
     attr_reader logger: Logger
 
@@ -62,18 +57,25 @@ module Zizq
     # their own `Zizq::Middleware::Chain` if middleware needs to be applied.
     attr_reader dispatcher: ^(Resources::Job) -> void
 
-    # @rbs queues: Array[String]
-    # @rbs thread_count: Integer
-    # @rbs fiber_count: Integer
+    # All keyword arguments default to `nil` and follow a three-level
+    # fallback chain:
+    #
+    #   1. Explicit kwarg passed to `Worker.new`.
+    #   2. `Zizq.configuration.worker.<field>` set in the app's
+    #      `Zizq.configure` block.
+    #   3. The Worker's hardcoded `DEFAULT_*` constants.
+    #
+    # @rbs queues: Array[String]?
+    # @rbs thread_count: Integer?
+    # @rbs fiber_count: Integer?
     # @rbs prefetch: Integer?
-    # @rbs retry_min_wait: (Float | Integer)
-    # @rbs retry_max_wait: (Float | Integer)
-    # @rbs retry_multiplier: (Float | Integer)
-    # @rbs worker_id: (^(Integer, Integer) -> String?)?
+    # @rbs retry_min_wait: (Float | Integer)?
+    # @rbs retry_max_wait: (Float | Integer)?
+    # @rbs retry_multiplier: (Float | Integer)?
     # @rbs logger: Logger?
     # @rbs dispatcher: (^(Resources::Job) -> void)?
     # @rbs return: void
-    def initialize: (?queues: Array[String], ?thread_count: Integer, ?fiber_count: Integer, ?prefetch: Integer?, ?retry_min_wait: Float | Integer, ?retry_max_wait: Float | Integer, ?retry_multiplier: Float | Integer, ?worker_id: (^(Integer, Integer) -> String?)?, ?logger: Logger?, ?dispatcher: (^(Resources::Job) -> void)?) -> void
+    def initialize: (?queues: Array[String]?, ?thread_count: Integer?, ?fiber_count: Integer?, ?prefetch: Integer?, ?retry_min_wait: (Float | Integer)?, ?retry_max_wait: (Float | Integer)?, ?retry_multiplier: (Float | Integer)?, ?logger: Logger?, ?dispatcher: (^(Resources::Job) -> void)?) -> void
 
     # Request a graceful shutdown.
     #
@@ -136,7 +138,7 @@ module Zizq
     #
     # Delegates to the configured dispatcher (default: `Zizq::Job.dispatch`)
     # and reports success or failure.
-    def dispatch: (untyped job, untyped worker_id) -> untyped
+    def dispatch: (untyped job) -> untyped
 
     # @rbs job_id: String
     # @rbs return: void
@@ -146,7 +148,5 @@ module Zizq
     # @rbs error: Exception
     # @rbs return: void
     def push_nack: (String job_id, Exception error) -> void
-
-    def resolve_worker_id: (untyped thread_idx, untyped fiber_idx) -> untyped
   end
 end

data/sig/generated/zizq/worker_configuration.rbs

@@ -0,0 +1,52 @@
+# Generated from lib/zizq/worker_configuration.rb with RBS::Inline
+
+module Zizq
+  # Defaults for `Zizq::Worker` instances. Accessed via
+  # `Zizq.configuration.worker` and typically populated inside an
+  # application's `Zizq.configure` block:
+  #
+  #   Zizq.configure do |c|
+  #     c.url = "https://..."
+  #     c.worker.queues = ["emails", "webhooks"]
+  #     c.worker.thread_count = 1
+  #     c.worker.fiber_count = 25
+  #   end
+  #
+  # Every field defaults to `nil`, meaning "use the Worker's own
+  # hardcoded default." Anything explicitly passed to `Worker.new` —
+  # or set via CLI flag / env var when launching `zizq-worker` —
+  # overrides whatever is set here.
+  #
+  # See `Zizq::Worker#initialize` for the full resolution order
+  # (explicit kwarg → Zizq.configuration.worker → `Worker::DEFAULT_*`).
+  #
+  # Fields:
+  #
+  # * `queues` — Queues to consume. `[]` means all queues.
+  # * `thread_count` — Number of worker threads.
+  # * `fiber_count` — Number of fibers per worker thread.
+  # * `prefetch` — Server-side prefetch limit. Defaults to
+  #   `2 * threads * fibers`.
+  # * `retry_min_wait` — Minimum reconnect backoff in seconds.
+  # * `retry_max_wait` — Maximum reconnect backoff in seconds.
+  # * `retry_multiplier` — Multiplicative backoff factor between
+  #   reconnect attempts.
+  class WorkerConfiguration < Struct[Array[String]? | Integer? | (Float | Integer)?]
+    attr_accessor queues(): Array[String]?
+
+    attr_accessor thread_count(): Integer?
+
+    attr_accessor fiber_count(): Integer?
+
+    attr_accessor prefetch(): Integer?
+
+    attr_accessor retry_min_wait(): (Float | Integer)?
+
+    attr_accessor retry_max_wait(): (Float | Integer)?
+
+    attr_accessor retry_multiplier(): (Float | Integer)?
+
+    def self.new: (?queues: Array[String]?, ?thread_count: Integer?, ?fiber_count: Integer?, ?prefetch: Integer?, ?retry_min_wait: (Float | Integer)?, ?retry_max_wait: (Float | Integer)?, ?retry_multiplier: (Float | Integer)?) -> instance
+                | ({ ?queues: Array[String]?, ?thread_count: Integer?, ?fiber_count: Integer?, ?prefetch: Integer?, ?retry_min_wait: (Float | Integer)?, ?retry_max_wait: (Float | Integer)?, ?retry_multiplier: (Float | Integer)? }) -> instance
+  end
+end

data/sig/zizq.rbs

@@ -67,7 +67,8 @@ module Zizq
     ?paused: bool?
   }
 
-  # TLS options for connecting over HTTPS. Values are PEM strings or file paths.
+  # TLS options hash accepted by `Configuration#tls=` for back-compat.
+  # Values are PEM strings or file paths.
   type tls_options = { ?ca: String, ?client_cert: String, ?client_key: String }
 
   # Any object that can dispatch a job. Must respond to #call(job).

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: zizq
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.3.2
 platform: ruby
 authors:
 - Chris Corbyn <chris@zizq.io>
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-05-06 00:00:00.000000000 Z
+date: 2026-05-24 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: async-http
@@ -38,11 +38,27 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '1.7'
-description: |+
+description: |-
   This is the official Ruby client for the Zizq job queue server.
 
   Zizq is a simple, single binary, zero dependency, language agnostic job queue.
 
+  Features:
+
+  - Enqueue and process jobs across programming languages
+  - Persistent/journalled
+  - Multi-thread and/or multi-fiber
+  - Scheduled jobs
+  - Prioritized queues
+  - Optional ActiveJob integration
+  - Unique jobs
+  - Cron scheduling (recurring jobs)
+  - Job introspection and management, including `jq` filters
+
+
+  This client supports multi-threaded and/or multi-fiber concurrency and is very fast. The Zizq server provides everything needed. There are no separate external storage dependencies to configure such as Redis or a RDBMS.
+
+  See https://zizq.io for full details and documentation.
 email:
 executables:
 - zizq-worker
@@ -84,8 +100,10 @@ files:
 - lib/zizq/resources/job_template.rb
 - lib/zizq/resources/page.rb
 - lib/zizq/resources/resource.rb
+- lib/zizq/tls_configuration.rb
 - lib/zizq/version.rb
 - lib/zizq/worker.rb
+- lib/zizq/worker_configuration.rb
 - sig/generated/zizq.rbs
 - sig/generated/zizq/ack_processor.rbs
 - sig/generated/zizq/active_job_config.rbs
@@ -115,8 +133,10 @@ files:
 - sig/generated/zizq/resources/job_template.rbs
 - sig/generated/zizq/resources/page.rbs
 - sig/generated/zizq/resources/resource.rbs
+- sig/generated/zizq/tls_configuration.rbs
 - sig/generated/zizq/version.rbs
 - sig/generated/zizq/worker.rbs
+- sig/generated/zizq/worker_configuration.rbs
 - sig/zizq.rbs
 homepage: https://zizq.io
 licenses:
@@ -145,4 +165,3 @@ signing_key:
 specification_version: 4
 summary: The official Ruby client for the Zizq job queue
 test_files: []
-...