zizq 0.3.1 → 0.3.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8f79a2e4601f42c8c9334601383a3659ffa5063a5df3ce2575b1d56b4df17a89
-  data.tar.gz: 730dbf9a98a6bb877234f3821e099e0363c5ebfad4905622106fa19b17db6610
+  metadata.gz: 5f0af940d511a8e1aa6d89df8ca13e98733430827d5f3202bcf7434a94ee02da
+  data.tar.gz: 9341d2815e344b3e4b8ca402185e3de01bd488cb5a3159f18e132d3c65cc18ca
 SHA512:
-  metadata.gz: 49f4a260cfbc35570e10e8fa0811e922be0c826ac0126f20e530353ae4c58df13e5f1cf8637d0a2f7a799ec3a0c64d9082c1a66d859de21b748db05e2db22802
-  data.tar.gz: 0e09b0848550330989701c703c5640e3df46e9e8a4229e3e15de99f033975356e24abee2e99fe537ed5b80c8a6edbfc9e302b518844ca9a6d99ce60766af5ccb
+  metadata.gz: a3e04dffd06a36db8ca940105675428390867bd8dee62b2bcf0ef7cbeef03fe080b35bf93061e9ec00b6834be0940e1d69d7bd837178718a0bd288b6895464c3
+  data.tar.gz: 9d5a7d77ca3e143dbcc8c5bb72a58eb1c60092335d206579646dac8df3cbf178a9627a0d8e7a68e394d2b07c32a60a82c915ab049175624760a314042d12f9b7

data/README.md

@@ -1,11 +1,11 @@
 # 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)
 
@@ -32,13 +32,13 @@ This is the official Zizq client library for Ruby.
 Add it to your application's `Gemfile`:
 
 ```ruby
-gem 'zizq', '~> 0.3.1'
+gem 'zizq', '~> 0.3.2'
 ```
 
 Or install it manually:
 
 ```shell
-$ gem install zizq -v 0.3.1
+$ gem install zizq -v 0.3.2
 ```
 
 Ruby **3.2.8 or newer** is required. Client and server share version
@@ -55,12 +55,19 @@ require 'zizq'
 
 Zizq.configure do |c|
   c.url    = 'https://zizq.your.network:7890'
-  c.tls    = { ca: '/path/to/server-ca-cert.pem' }
   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
 ```
 
-For mutual TLS, add `client_cert:` and `client_key:` to the `tls` hash.
+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
@@ -149,20 +156,29 @@ end
 ### Running a worker
 
 Jobs are processed by a worker, typically in a separate process. The simplest
-way is the `zizq-worker` executable bundled with the gem — pass your
-application's entrypoint so it can load your job classes:
+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
-$ bundle exec zizq-worker --threads 5 --fibers 2 config/environment.rb
-I, [...] INFO -- : Zizq worker starting: 5 threads, 2 fibers, prefetch=20
+$ bundle exec zizq-worker
+I, [...] INFO -- : Zizq worker starting: 1 threads, 25 fibers, prefetch=50
 I, [...] INFO -- : Connected. Listening for jobs.
 ```
 
-A worker runs `threads × fibers` handlers concurrently. Leave `--fibers 1`
-if your application isn't fiber-safe — no `Async` context is loaded in that
-case. Restrict to specific queues with `--queue`. `INT` / `TERM` trigger a
-graceful shutdown (drains in-flight jobs up to `--shutdown-timeout`, default
-30s).
+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:
@@ -170,11 +186,9 @@ Rack app — construct `Zizq::Worker` directly:
 ```ruby
 require 'zizq'
 
-worker = Zizq::Worker.new(
-  thread_count: 5,
-  fiber_count:  2,
-  queues:       ['emails', 'payments'],
-)
+# 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

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/configuration.rb

@@ -29,19 +29,6 @@ module Zizq
     # Logger instance to which to write log messages.
     attr_accessor :logger #: Logger
 
-    # TLS options for connecting to the server over HTTPS.
-    #
-    # All values may be PEM-encoded strings or file paths.
-    #
-    #   {
-    #     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
-    #   }
-    #
-    # Note: Mutual TLS support requires a Zizq Pro license on the server.
-    attr_accessor :tls #: Zizq::tls_options?
-
     # 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
@@ -76,12 +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
@@ -130,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
 
@@ -161,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.1" #: 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.

data/sig/generated/zizq/configuration.rbs

@@ -22,19 +22,6 @@ module Zizq
     # Logger instance to which to write log messages.
     attr_accessor logger: Logger
 
-    # TLS options for connecting to the server over HTTPS.
-    #
-    # All values may be PEM-encoded strings or file paths.
-    #
-    #   {
-    #     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
-    #   }
-    #
-    # Note: Mutual TLS support requires a Zizq Pro license on the server.
-    attr_accessor tls: Zizq::tls_options?
-
     # 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
@@ -66,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
@@ -100,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.1
+  version: 0.3.2
 platform: ruby
 authors:
 - Chris Corbyn <chris@zizq.io>
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-05-21 00:00:00.000000000 Z
+date: 2026-05-24 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: async-http
@@ -100,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
@@ -131,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: