zizq 0.2.1 → 0.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: de36f4f8204a5d5b0c64e77b78249ed34ea6c667ceb6b03dbdca2a291cb0f330
-  data.tar.gz: 7cbb62aac1788627bb1047b474e5ca915c5dca059bc6f00be7a2f5adca798a7a
+  metadata.gz: 8f79a2e4601f42c8c9334601383a3659ffa5063a5df3ce2575b1d56b4df17a89
+  data.tar.gz: 730dbf9a98a6bb877234f3821e099e0363c5ebfad4905622106fa19b17db6610
 SHA512:
-  metadata.gz: 95b80cec6e0bb1704bd1244b37c4434b5d5467139e35c61bae39f342825a3e136a413aa55c0a0b7de379024bcdee3486e08cb211062a9d406011093a68de2899
-  data.tar.gz: '09952b2563e139e9987473b53524ea993f1c803ea0320082c166132053919f3401cad65c8dc063923837c3b1fe8a505e3e27dcd9ce6a20724313c1d6f82c00e3'
+  metadata.gz: 49f4a260cfbc35570e10e8fa0811e922be0c826ac0126f20e530353ae4c58df13e5f1cf8637d0a2f7a799ec3a0c64d9082c1a66d859de21b748db05e2db22802
+  data.tar.gz: 0e09b0848550330989701c703c5640e3df46e9e8a4229e3e15de99f033975356e24abee2e99fe537ed5b80c8a6edbfc9e302b518844ca9a6d99ce60766af5ccb

data/README.md

@@ -7,6 +7,7 @@ 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
 
@@ -18,17 +19,66 @@ This is the official Zizq client library for Ruby.
 * Scheduled jobs
 * Configurable backoff policies
 * Configurable job retention policies
+* Recurring jobs (cron)
 * Job introspection and management APIs, with support for `jq` query filters
 * Unique jobs
 
-## Example
+## Installation
+
+> [!NOTE]
+> 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`:
+
+```ruby
+gem 'zizq', '~> 0.3.1'
+```
+
+Or install it manually:
+
+```shell
+$ gem install zizq -v 0.3.1
+```
+
+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.tls    = { ca: '/path/to/server-ca-cert.pem' }
+  c.logger = Logger.new('log/zizq.log')
+end
+```
+
+For mutual TLS, add `client_cert:` and `client_key:` to the `tls` hash.
+
+> [!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.
+
+### Defining a job
 
-Mixin-based job class.
+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
@@ -36,54 +86,133 @@ 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
-Zizq.enqueue(SendEmailJob, 42, template: 'welcome')
+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
+# 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 — pass your
+application's entrypoint so it can load your job classes:
 
 ```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 --threads 5 --fibers 2 config/environment.rb
+I, [...] INFO -- : Zizq worker starting: 5 threads, 2 fibers, prefetch=20
+I, [...] INFO -- : Connected. Listening for jobs.
 ```
 
-> [!NOTE]
-> Workers can also be created directly in code. There is no requirement to use
-> `zizq-worker`.
+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 more control — for example running the worker in-process alongside a
+Rack app — construct `Zizq::Worker` directly:
+
+```ruby
+require 'zizq'
+
+worker = Zizq::Worker.new(
+  thread_count: 5,
+  fiber_count:  2,
+  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
@@ -92,3 +221,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/lib/zizq/bulk_enqueue.rb

@@ -22,7 +22,7 @@ module Zizq
     # Collect a job class enqueue. Accepts the same arguments as
     # `Zizq.enqueue`.
     #
-    # @rbs job_class: Class & Zizq::job_class
+    # @rbs job_class: Class & Zizq::JobConfig
     # @rbs args: Array[untyped]
     # @rbs kwargs: Hash[Symbol, untyped]
     # @rbs &block: ?(EnqueueRequest) -> void

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,
@@ -204,7 +225,7 @@ module Zizq
 
     # Get a single job by ID.
     def get_job(id) #: (String) -> Resources::Job
-      response = get("/jobs/#{id}")
+      response = get("/jobs/#{enc(id)}")
       data = handle_response!(response, expected: 200)
       Resources::Job.new(self, data)
     end
@@ -285,7 +306,7 @@ module Zizq
     # @rbs id: String
     # @rbs return: void
     def delete_job(id)
-      response = delete("/jobs/#{id}")
+      response = delete("/jobs/#{enc(id)}")
       handle_response!(response, expected: [200, 204])
       nil
     end
@@ -342,7 +363,7 @@ module Zizq
         queue:, priority:, ready_at:,
         retry_limit:, backoff:, retention:
       )
-      response = patch("/jobs/#{id}", body)
+      response = patch("/jobs/#{enc(id)}", body)
       data = handle_response!(response, expected: 200)
       Resources::Job.new(self, data)
     end
@@ -383,7 +404,7 @@ module Zizq
     # @rbs attempt: Integer
     # @rbs return: Resources::ErrorRecord
     def get_error(id, attempt:)
-      response = get("/jobs/#{id}/errors/#{attempt}")
+      response = get("/jobs/#{enc(id)}/errors/#{enc(attempt.to_s)}")
       data = handle_response!(response, expected: 200)
       Resources::ErrorRecord.new(self, data)
     end
@@ -397,7 +418,7 @@ module Zizq
     # @rbs return: Resources::ErrorPage
     def list_errors(id, from: nil, order: nil, limit: nil)
       params = { from:, order:, limit: }.compact #: Hash[Symbol, untyped]
-      response = get("/jobs/#{id}/errors", params:)
+      response = get("/jobs/#{enc(id)}/errors", params:)
       data = handle_response!(response, expected: 200)
       Resources::ErrorPage.new(self, data)
     end
@@ -422,6 +443,136 @@ module Zizq
       data["queues"]
     end
 
+    # List all cron group names.
+    #
+    # @rbs return: Array[String]
+    def list_cron_groups
+      response = get("/crons")
+      data = handle_response!(response, expected: 200)
+      data["crons"]
+    end
+
+    # Fetch a cron group and all its entries.
+    #
+    # @rbs name: String
+    # @rbs return: Resources::CronGroup
+    def get_cron_group(name)
+      response = get("/crons/#{enc(name)}")
+      data = handle_response!(response, expected: 200)
+      Resources::CronGroup.new(self, data)
+    end
+
+    # Create or replace an entire cron group.
+    #
+    # Entries not present in the request are removed. Entries with unchanged
+    # expressions preserve their scheduling state.
+    #
+    # @rbs name: String
+    # @rbs paused: bool?
+    # @rbs entries: Array[Zizq::cron_entry_params]
+    # @rbs return: Resources::CronGroup
+    def replace_cron_group(name, paused: nil, entries: [])
+      body = {
+        paused:,
+        entries: entries.map { |entry| build_cron_entry(**entry) }
+      }.compact
+      response = put("/crons/#{enc(name)}", body)
+      data = handle_response!(response, expected: 200)
+      Resources::CronGroup.new(self, data)
+    end
+
+    # Update group-level fields (currently just pause/unpause).
+    #
+    # @rbs name: String
+    # @rbs paused: bool?
+    # @rbs return: Resources::CronGroup
+    def update_cron_group(name, paused: nil)
+      response = patch("/crons/#{enc(name)}", { paused: }.compact)
+      data = handle_response!(response, expected: 200)
+      Resources::CronGroup.new(self, data)
+    end
+
+    # Delete a cron group and all its entries.
+    #
+    # @rbs name: String
+    # @rbs return: void
+    def delete_cron_group(name)
+      response = delete("/crons/#{enc(name)}")
+      handle_response!(response, expected: 204)
+      nil
+    end
+
+    # Fetch a single cron entry.
+    #
+    # @rbs group: String
+    # @rbs entry: String
+    # @rbs return: Resources::CronEntry
+    def get_cron_group_entry(group, entry)
+      response = get("/crons/#{enc(group)}/entries/#{enc(entry)}")
+      data = handle_response!(response, expected: 200)
+      Resources::CronEntry.new(self, data)
+    end
+
+    # Add a single entry to a cron group (creates the group if needed).
+    #
+    # Raises a ClientError (409 Conflict) if an entry with the same name
+    # already exists.
+    #
+    # @rbs group: String
+    # @rbs name: String
+    # @rbs expression: String
+    # @rbs job: Zizq::cron_job_params
+    # @rbs timezone: String?
+    # @rbs paused: bool?
+    # @rbs return: Resources::CronEntry
+    def add_cron_group_entry(group, name:, expression:, job:, timezone: nil, paused: nil)
+      body = build_cron_entry(name:, expression:, job:, timezone:, paused:)
+      response = post("/crons/#{enc(group)}/entries", body)
+      data = handle_response!(response, expected: 201)
+      Resources::CronEntry.new(self, data)
+    end
+
+    # Create or replace a single cron entry.
+    #
+    # Preserves scheduling state if the expression is unchanged.
+    #
+    # @rbs group: String
+    # @rbs entry: String
+    # @rbs expression: String
+    # @rbs job: Zizq::cron_job_params
+    # @rbs timezone: String?
+    # @rbs paused: bool?
+    # @rbs return: Resources::CronEntry
+    def replace_cron_group_entry(group, entry, expression:, job:, timezone: nil, paused: nil)
+      body = build_cron_entry(name: entry, expression:, job:, timezone:, paused:)
+      response = put("/crons/#{enc(group)}/entries/#{enc(entry)}", body)
+      data = handle_response!(response, expected: 200)
+      Resources::CronEntry.new(self, data)
+    end
+
+    # Update entry-level fields (currently just pause/unpause).
+    #
+    # @rbs group: String
+    # @rbs entry: String
+    # @rbs paused: bool
+    # @rbs return: Resources::CronEntry
+    def update_cron_group_entry(group, entry, paused:)
+      response = patch("/crons/#{enc(group)}/entries/#{enc(entry)}", { paused: })
+      data = handle_response!(response, expected: 200)
+      Resources::CronEntry.new(self, data)
+    end
+
+    # Delete a single cron entry.
+    #
+    # @rbs group: String
+    # @rbs entry: String
+    # @rbs return: void
+    def delete_cron_group_entry(group, entry)
+      response = delete("/crons/#{enc(group)}/entries/#{enc(entry)}")
+      handle_response!(response, expected: 204)
+      nil
+    end
+
     # Mark a job as successfully completed (ack).
     #
     # If this method (or [`#report_failure`]) is not called upon job
@@ -439,7 +590,7 @@ module Zizq
     # The Zizq server sends heartbeat messages to connected workers so that
     # it can quickly detect and handle disconnected clients.
     def report_success(id) #: (String) -> nil
-      response = raw_post("/jobs/#{id}/success")
+      response = raw_post("/jobs/#{enc(id)}/success")
       handle_response!(response, expected: 204)
       nil
     end
@@ -503,7 +654,7 @@ module Zizq
       body[:retry_at] = (retry_at * 1000).to_i if retry_at
       body[:kill] = kill if kill
 
-      response = post("/jobs/#{id}/failure", body)
+      response = post("/jobs/#{enc(id)}/failure", body)
       data = handle_response!(response, expected: 200)
       Resources::Job.new(self, data)
     end
@@ -579,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
@@ -660,6 +816,11 @@ module Zizq
 
     private
 
+    # URL-encode a single path segment.
+    def enc(value) #: (String) -> String
+      URI.encode_uri_component(value)
+    end
+
     # Build a relative path with optional query parameters.
     def build_path(path, params: {}) #: (String, ?params: Hash[Symbol, untyped]) -> String
       unless params.empty?
@@ -668,6 +829,57 @@ module Zizq
       path
     end
 
+    # Validate and build a cron entry body from keyword arguments.
+    #
+    # @rbs name: String
+    # @rbs expression: String
+    # @rbs job: Zizq::cron_job_params
+    # @rbs timezone: String?
+    # @rbs paused: bool?
+    # @rbs return: Hash[Symbol, untyped]
+    def build_cron_entry(name: nil, expression: nil, job: nil, timezone: nil, paused: nil)
+      {
+        name:,
+        expression:,
+        timezone:,
+        paused:,
+        job: build_cron_job(**job),
+      }.compact
+    end
+
+    # Validate and build a cron job template from keyword arguments.
+    #
+    # Uses keyword args so that unknown keys raise ArgumentError.
+    #
+    # @rbs type: String
+    # @rbs queue: String
+    # @rbs payload: untyped
+    # @rbs priority: Integer?
+    # @rbs retry_limit: Integer?
+    # @rbs backoff: Zizq::backoff?
+    # @rbs retention: Zizq::retention?
+    # @rbs unique_key: String?
+    # @rbs unique_while: Zizq::unique_scope?
+    # @rbs return: Hash[Symbol, untyped]
+    def build_cron_job(type: nil,
+                       queue: nil,
+                       payload: nil,
+                       priority: nil,
+                       retry_limit: nil,
+                       backoff: nil,
+                       retention: nil,
+                       unique_key: nil,
+                       unique_while: nil)
+      job = { type:, queue:, payload: } #: Hash[Symbol, untyped]
+      job[:priority] = priority if priority
+      job[:retry_limit] = retry_limit if retry_limit
+      job[:backoff] = backoff if backoff
+      job[:retention] = retention if retention
+      job[:unique_key] = unique_key if unique_key
+      job[:unique_while] = unique_while.to_s if unique_while
+      job
+    end
+
     # Validate and normalize filter parameters for bulk operations.
     #
     # Uses keyword arguments so that unknown keys raise ArgumentError.
@@ -942,6 +1154,18 @@ module Zizq
       end
     end
 
+    def put(path, body) #: (String, Hash[Symbol, untyped]) -> RawResponse
+      request do |http|
+        consume_response(
+          http.put(
+            build_path(path),
+            {"content-type" => @content_type, "accept" => @content_type},
+            Protocol::HTTP::Body::Buffered.wrap(encode_body(body))
+          )
+        )
+      end
+    end
+
     def delete(path, params: {}) #: (String, ?params: Hash[Symbol, untyped]) -> RawResponse
       request do |http|
         consume_response(

data/lib/zizq/configuration.rb

@@ -42,6 +42,27 @@ module Zizq
     # 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
+    # this raises `IO::TimeoutError`.
+    #
+    # 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.
+    #
+    # Should be comfortably above the server's heartbeat interval to
+    # avoid false-positive disconnects.
+    #
+    # Default: 30.
+    attr_accessor :stream_idle_timeout #: Numeric
+
     # Middleware chain for enqueue. Each middleware receives an
     # `EnqueueRequest` and a chain to continue.
     attr_reader :enqueue_middleware #: Middleware::Chain[EnqueueRequest, EnqueueRequest]
@@ -55,6 +76,8 @@ module Zizq
       @format = :msgpack
       @logger = Logger.new($stdout, level: Logger::INFO)
       @tls = nil
+      @read_timeout = 30
+      @stream_idle_timeout = 30
       @enqueue_middleware = Middleware::Chain.new(Identity.new)
       @dequeue_middleware = Middleware::Chain.new(Zizq::Job)
     end
@@ -89,6 +112,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