zizq 0.3.0 → 0.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a94a61282aba9442ace4ca8a3a302f75a843b14a76bd7d7748f006d5c8bf0888
-  data.tar.gz: 202f0842b2a2b22d8fce753c197635ea456ac94955f6f266f806471d01d06a7f
+  metadata.gz: 8f79a2e4601f42c8c9334601383a3659ffa5063a5df3ce2575b1d56b4df17a89
+  data.tar.gz: 730dbf9a98a6bb877234f3821e099e0363c5ebfad4905622106fa19b17db6610
 SHA512:
-  metadata.gz: 03cb04925c7aac0aaaee30f86e27448641ec4864b903bedeee83cd61b0d0ed803655dd69c8ed586c4b83faa3d8d910c13c589398ca3157f130c569fa3edce5e9
-  data.tar.gz: b3a2c1232195698681ae743e04db5aff883c4e82e36bab9d1735b7459c7db5fdbcb9829171fa30318cec4ac01dc34432a79c2760824f4d2db93c89fbda12da58
+  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
 
@@ -28,26 +29,56 @@ 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.1'
 ```
 
 Or install it manually:
 
 ```shell
-$ gem install zizq -v 0.3.0
+$ 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
 ```
 
-## Example
+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
@@ -55,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
+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(SendEmailJob, 42, template: 'welcome')
+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
@@ -111,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/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

@@ -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

data/lib/zizq/version.rb

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

data/lib/zizq.rb

@@ -81,7 +81,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

@@ -35,6 +35,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]

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: zizq
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.3.1
 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-21 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
@@ -145,4 +161,3 @@ signing_key:
 specification_version: 4
 summary: The official Ruby client for the Zizq job queue
 test_files: []
-...