zizq 0.6.0 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 650d5af8c85dfe12fdf6280a3cf483ba1edd7f7d3d0536965a220c9f556221ef
-  data.tar.gz: ec340ce8d30065b6afeb9dc9404651bd769e8a604dec326aca97c332a11bc7ba
+  metadata.gz: ae77b1f8501b8eae45ac668e2af45a5c69be600173c33d50ebc06d5520a04a05
+  data.tar.gz: 72afdb1b19ab3fb3fb34f4dba1e9bb19db41d8125bfbd2f278151482aaa0098f
 SHA512:
-  metadata.gz: a7a239bed97e29977c9863f7e56d1ef94b1a1c1cd05bd4b74dde441910bd83f480b4d0453e58b32a3d623ad59bac8b771da5397794e1a05e614e4654cb744606
-  data.tar.gz: c60eae8cf1142ecb8e04218d551b5595554ebf5a085076111051c4a658518608715aae729d968d98f33aa7bd3f0f2a181fecbf97a031d6c21bb6a2472d8b291c
+  metadata.gz: 5b5177e0bf70576bc7632b35bbb9b32f4e85fb3324146b70420b1416ed1d312856eba49be52324c37154af3004f230e6667b3f403f123255af42e6059510367d
+  data.tar.gz: d8cbc6f97e3b4bcec66735f9089b3b4e6b201dfedd7e6210fe832a6b8afd718094a1ae1e9b50cb23bc4996f009f4f654c3587d334348431a7648d0628d153b65

data/README.md

@@ -1,10 +1,10 @@
 # Zizq — Official Ruby Client
 
-This is the official Zizq client library for Ruby.
+Zizq (**/zɪsk/**) is a fast and durable job queue packed into a single native
+binary, built on an embedded LSM database — not on Redis, and not on your
+RDBMS. It works in any stack, crossing programming language boundaries.
 
-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)
@@ -21,6 +21,8 @@ API.
 * Configurable job retention policies
 * Recurring jobs (cron)
 * Job introspection and management APIs, with support for `jq` query filters
+* Concurrency control that doesn't impact other jobs
+* Rate limiting with configurable burst
 * Unique jobs (deduplicated)
 * Batched jobs (folded/merged)
 * Testing helpers
@@ -34,13 +36,13 @@ API.
 Add it to your application's `Gemfile`:
 
 ```ruby
-gem 'zizq', '~> 0.6.0'
+gem 'zizq', '~> 0.7.0'
 ```
 
 Or install it manually:
 
 ```shell
-$ gem install zizq -v 0.6.0
+$ gem install zizq -v 0.7.0
 ```
 
 Ruby **3.2.8 or newer** is required. Client and server share version
@@ -141,8 +143,8 @@ Zizq.enqueue_with(ready_at: Time.new(2027, 3, 15, 14, 30)).enqueue(SendEmailJob,
 ```
 
 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:
+atomic request — across queues and job types, and job classes vs raw enqueues
+can be mixed in too:
 
 ```ruby
 Zizq.enqueue_bulk do |b|
@@ -150,22 +152,91 @@ Zizq.enqueue_bulk do |b|
 end
 ```
 
-Jobs can also be enqueued without `Zizq::Job` via `Zizq.enqueue_raw` —
+Jobs can also be enqueued without `Zizq::Job` by providing the named fields —
 designed for lower-level code style, and for cross-language workflows where,
 for example, a Ruby app enqueues jobs consumed by a Go service.
 
 ```ruby
-Zizq.enqueue_raw(
+Zizq.enqueue(
   type: "send_email",
   queue: "comms",
   payload: { user_id: 42, template: "welcome" }
 )
 ```
 
+### Concurrency control
+
+The Zizq server supports constraining the number of `in_flight` set of jobs for
+specific job types by binding a named _budget_ to those jobs.
+
+```ruby
+# Define a named budget called "notifications" that jobs can reference
+# (generally somewhere in your application startup code).
+Zizq.define_budget(
+  "notifications",
+  allocation: 10,
+  strategy: { type: :while_in_flight }
+)
+
+# Specify the budget on the Job class (or at enqueue time).
+class SendNotificationJob
+  include Zizq::Job
+
+  zizq_budget "notifications"
+
+  def perform(id)
+    # ...
+  end
+end
+
+# Those jobs execute no more than 10 at any given time. Other jobs continue to
+# flow normally.
+100.times do |n|
+  Zizq.enqueue(SendNotificationJob, n)
+end
+```
+
+### Rate limiting
+
+The Zizq server supports dispatching jobs to workers at a throttled rate by
+binding a named _budget_ to those jobs. Jobs that exceed the limit do not
+block other work. The server is smart enough to "park" them until the moment
+they are ready to dispatch.
+
+```ruby
+# Define a named budget called "image-service" that jobs can reference
+# (generally somewhere in your application startup code).
+Zizq.define_budget(
+  "image-service",
+  allocation: 1000,
+  strategy: {
+    type: :time_based,
+    duration: 1.minute # or just 60 without ActiveSupport
+  }
+)
+
+# Specify the budget on the Job class (or at enqueue time).
+class NormalizeImageJob
+  include Zizq::Job
+
+  zizq_budget "image-service"
+
+  def perform(id)
+    # ...
+  end
+end
+
+# Those jobs are delivered by the server at a rate of 1000/minute without
+# blocking other jobs. Your workers remain free of such knowledge.
+5000.times do |n|
+  Zizq.enqueue(NormalizeImageJob, n)
+end
+```
+
 ### Cross-language and low-level dispatch
 
 When a Ruby app needs to *process* jobs enqueued by another language
-(or by `Zizq.enqueue_raw`), `Zizq::Router` maps `type` strings to
+(or itself using raw enqueue form), `Zizq::Router` maps `type` strings to
 handler blocks operating on plain JSON payloads:
 
 ```ruby

data/lib/active_job/queue_adapters/zizq_adapter.rb

@@ -90,6 +90,7 @@ module ActiveJob
       def build_enqueue_request(job)
         klass = job.class
 
+        # Prepare with instance-specific config first.
         req =
           Zizq::EnqueueRequest.new(
             queue: job.queue_name,
@@ -99,31 +100,11 @@ module ActiveJob
             ready_at: job.scheduled_at
           )
 
-        if klass.respond_to?(:zizq_unique) && klass.zizq_unique
-          req.unique_key = klass.zizq_unique_key(*job.arguments)
-          req.unique_while = klass.zizq_unique_scope
+        # Augment with class-level config if the class extends ActiveJobConfig
+        if klass.respond_to?(:zizq_apply_class_config)
+          klass.zizq_apply_class_config(req, *job.arguments)
         end
 
-        if klass.respond_to?(:zizq_batched) && klass.zizq_batched
-          expr = klass.zizq_batch_expressions
-          if expr
-            req.batch = {
-              key: klass.zizq_batch_key(*job.arguments),
-              when: expr[:when],
-              fold: expr[:fold]
-            }
-          end
-        end
-
-        req.retry_limit = klass.zizq_retry_limit if klass.respond_to?(
-          :zizq_retry_limit
-        ) && klass.zizq_retry_limit
-        req.backoff = klass.zizq_backoff if klass.respond_to?(:zizq_backoff) &&
-          klass.zizq_backoff
-        req.retention = klass.zizq_retention if klass.respond_to?(
-          :zizq_retention
-        ) && klass.zizq_retention
-
         req
       end
     end

data/lib/zizq/bulk_enqueue.rb

@@ -27,7 +27,7 @@ module Zizq
     # @rbs kwargs: Hash[Symbol, untyped]
     # @rbs &block: ?(EnqueueRequest) -> void
     # @rbs return: void
-    def enqueue(job_class, *args, **kwargs, &block)
+    def enqueue_job_class(job_class, *args, **kwargs, &block)
       @requests << Zizq.build_enqueue_request(
         job_class,
         *args,
@@ -36,23 +36,70 @@ module Zizq
       )
     end
 
+    # Collect an enqueue, by class or by raw inputs.
+    #
+    # Both forms of `Zizq.enqueue` work here too:
+    #
+    #   b.enqueue(SendEmailJob, 42, template: "welcome")
+    #   b.enqueue(queue: "emails", type: "send_email", payload: {...})
+    #
+    # @rbs skip
+    # @rbs!
+    #   def enqueue: (
+    #     Class & Zizq::JobConfig job_class,
+    #     *untyped args,
+    #     **untyped kwargs
+    #   ) ?{ (EnqueueRequest) -> void } -> void
+    #   | (
+    #     queue: String,
+    #     type: String,
+    #     payload: untyped,
+    #     ?priority: Integer?,
+    #     ?delay: Zizq::to_f?,
+    #     ?ready_at: Zizq::to_f?,
+    #     ?retry_limit: Integer?,
+    #     ?backoff: Zizq::backoff?,
+    #     ?retention: Zizq::retention?,
+    #     ?unique_key: String?,
+    #     ?unique_while: Zizq::unique_scope?,
+    #     ?batch: Zizq::batch?,
+    #     ?budgets: Array[Zizq::budget_binding_params]?
+    #   ) ?{ (EnqueueRequest) -> void } -> void
+    def enqueue(*args, **kwargs, &block)
+      return enqueue_job_class(*args, **kwargs, &block) unless args.empty?
+
+      begin
+        # See `Zizq.enqueue` for why only this branch is wrapped.
+        enqueue_raw(**kwargs, &block) # steep:ignore InsufficientKeywordArguments
+      rescue ArgumentError => e
+        raise ArgumentError, e.message, caller(1)
+      end
+    end
+
     # Collect a raw enqueue. Accepts the same arguments as
     # `Zizq.enqueue_raw`.
     #
-    # @rbs queue: String
-    # @rbs type: String
-    # @rbs payload: untyped
-    # @rbs priority: Integer?
-    # @rbs ready_at: Zizq::to_f?
-    # @rbs retry_limit: Integer?
-    # @rbs backoff: Zizq::backoff?
-    # @rbs retention: Zizq::retention?
-    # @rbs unique_key: String?
-    # @rbs unique_while: Zizq::unique_scope?
-    # @rbs batch: Zizq::batch?
-    # @rbs return: void
+    # @rbs skip
+    # @rbs!
+    #   def enqueue_raw: (
+    #     queue: String,
+    #     type: String,
+    #     payload: untyped,
+    #     ?priority: Integer?,
+    #     ?delay: Zizq::to_f?,
+    #     ?ready_at: Zizq::to_f?,
+    #     ?retry_limit: Integer?,
+    #     ?backoff: Zizq::backoff?,
+    #     ?retention: Zizq::retention?,
+    #     ?unique_key: String?,
+    #     ?unique_while: Zizq::unique_scope?,
+    #     ?batch: Zizq::batch?,
+    #     ?budgets: Array[Zizq::budget_binding_params]?
+    #   ) ?{ (EnqueueRequest) -> void } -> void
     def enqueue_raw(queue:, type:, payload:, **opts)
-      @requests << EnqueueRequest.new(queue:, type:, payload:, **opts)
+      req = EnqueueRequest.new(queue:, type:, payload:, **opts)
+      yield req if block_given?
+      @requests << req
     end
 
     # Build a scoped enqueue helper that applies the given overrides to a