zizq 0.5.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 424b67e8dbba3c82506c24ed18cbaa9fc87af3febe9e079ef458f705e9299fdd
-  data.tar.gz: 53bc5f8b3aefbdddc69e2471e6efbd2ba7c84016cb8eb63ff16bc463107991fe
+  metadata.gz: 650d5af8c85dfe12fdf6280a3cf483ba1edd7f7d3d0536965a220c9f556221ef
+  data.tar.gz: ec340ce8d30065b6afeb9dc9404651bd769e8a604dec326aca97c332a11bc7ba
 SHA512:
-  metadata.gz: 10f7ab3fe215f04eff3c1753826734c609454c93f9c30c586dd0f38f49ac563d23dcb47317c12e7c00cde3dff558cb124ce0ae25a3c801b9b71a85ce806d96e9
-  data.tar.gz: 422601a65e9862a73360e036a0e5f44ac36bdcaa04a3fe585567e4fefaf9b73e4fa4736ac3fe9d0cc552173bcd9c47fef98cbc1a6935ef3a64870a839a5a13b9
+  metadata.gz: a7a239bed97e29977c9863f7e56d1ef94b1a1c1cd05bd4b74dde441910bd83f480b4d0453e58b32a3d623ad59bac8b771da5397794e1a05e614e4654cb744606
+  data.tar.gz: c60eae8cf1142ecb8e04218d551b5595554ebf5a085076111051c4a658518608715aae729d968d98f33aa7bd3f0f2a181fecbf97a031d6c21bb6a2472d8b291c

data/README.md

@@ -21,7 +21,8 @@ API.
 * Configurable job retention policies
 * Recurring jobs (cron)
 * Job introspection and management APIs, with support for `jq` query filters
-* Unique jobs
+* Unique jobs (deduplicated)
+* Batched jobs (folded/merged)
 * Testing helpers
 
 ## Installation
@@ -33,13 +34,13 @@ API.
 Add it to your application's `Gemfile`:
 
 ```ruby
-gem 'zizq', '~> 0.5.0'
+gem 'zizq', '~> 0.6.0'
 ```
 
 Or install it manually:
 
 ```shell
-$ gem install zizq -v 0.5.0
+$ gem install zizq -v 0.6.0
 ```
 
 Ruby **3.2.8 or newer** is required. Client and server share version

data/lib/active_job/queue_adapters/zizq_adapter.rb

@@ -33,7 +33,8 @@ module ActiveJob
     class ZizqAdapter
       # Enqueue a job for immediate execution.
       def enqueue(job)
-        result = Zizq.enqueue_raw(**build_enqueue_request(job).to_enqueue_params)
+        result =
+          Zizq.enqueue_raw(**build_enqueue_request(job).to_enqueue_params)
         job.provider_job_id = result.id
         job.successfully_enqueued = true
         result
@@ -42,7 +43,8 @@ module ActiveJob
       # Enqueue a job for execution at a specific time.
       def enqueue_at(job, timestamp)
         job.scheduled_at = timestamp
-        result = Zizq.enqueue_raw(**build_enqueue_request(job).to_enqueue_params)
+        result =
+          Zizq.enqueue_raw(**build_enqueue_request(job).to_enqueue_params)
         job.provider_job_id = result.id
         job.successfully_enqueued = true
         result
@@ -53,16 +55,19 @@ module ActiveJob
       # Called by `ActiveJob.perform_all_later` (Rails 7.1+).
       # Returns the number of successfully enqueued jobs.
       def enqueue_all(jobs)
-        results = Zizq.enqueue_bulk do |b|
-          jobs.each do |job|
-            b.enqueue_raw(**build_enqueue_request(job).to_enqueue_params)
+        results =
+          Zizq.enqueue_bulk do |b|
+            jobs.each do |job|
+              b.enqueue_raw(**build_enqueue_request(job).to_enqueue_params)
+            end
           end
-        end
 
-        jobs.zip(results).each do |job, result|
-          job.provider_job_id = result.id
-          job.successfully_enqueued = true
-        end
+        jobs
+          .zip(results)
+          .each do |job, result|
+            job.provider_job_id = result.id
+            job.successfully_enqueued = true
+          end
 
         jobs.size
       rescue => e
@@ -85,22 +90,39 @@ module ActiveJob
       def build_enqueue_request(job)
         klass = job.class
 
-        req = Zizq::EnqueueRequest.new(
-          queue:    job.queue_name,
-          type:     klass.name,
-          payload:  job.serialize,
-          priority: job.priority,
-          ready_at: job.scheduled_at
-        )
+        req =
+          Zizq::EnqueueRequest.new(
+            queue: job.queue_name,
+            type: klass.name,
+            payload: job.serialize,
+            priority: job.priority,
+            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
         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
+        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

data/lib/zizq/ack_processor.rb

@@ -79,13 +79,9 @@ module Zizq
           # Partition: acks go bulk, nacks go individually.
           acks, nacks = batch.partition { |i| i.is_a?(Ack) }
 
-          unless acks.empty?
-            barrier.async { process_ack_batch(acks) }
-          end
+          barrier.async { process_ack_batch(acks) } unless acks.empty?
 
-          nacks.each do |nack|
-            barrier.async { process_nack(nack) }
-          end
+          nacks.each { |nack| barrier.async { process_nack(nack) } }
         end
 
         barrier.wait
@@ -101,9 +97,13 @@ module Zizq
       begin
         @client.report_success_bulk(ids)
       rescue ClientError => e
-        @logger.warn { "Bulk ack (#{ids.size} jobs) returned #{e.status} (dropping: #{e.message})" }
+        @logger.warn do
+          "Bulk ack (#{ids.size} jobs) returned #{e.status} (dropping: #{e.message})"
+        end
       rescue => e
-        @logger.warn { "Retrying bulk ack (#{ids.size} jobs) in #{backoff.duration}s: #{e.message}" }
+        @logger.warn do
+          "Retrying bulk ack (#{ids.size} jobs) in #{backoff.duration}s: #{e.message}"
+        end
         backoff.wait
         retry
       end
@@ -119,11 +119,17 @@ module Zizq
           backtrace: nack.backtrace
         )
       rescue NotFoundError
-        @logger.debug { "Nack for #{nack.job_id} returned 404 (already handled)" }
+        @logger.debug do
+          "Nack for #{nack.job_id} returned 404 (already handled)"
+        end
       rescue ClientError => e
-        @logger.error { "Nack for #{nack.job_id} returned #{e.status} (dropping)" }
+        @logger.error do
+          "Nack for #{nack.job_id} returned #{e.status} (dropping)"
+        end
       rescue => e
-        @logger.warn { "Retrying nack for #{nack.job_id} in #{backoff.duration}s: #{e.message}" }
+        @logger.warn do
+          "Retrying nack for #{nack.job_id} in #{backoff.duration}s: #{e.message}"
+        end
         backoff.wait
         retry
       end

data/lib/zizq/active_job_config.rb

@@ -65,16 +65,7 @@ module Zizq
     # side. This method is not used in the ActiveJob dispatch path.
     def zizq_deserialize(_payload) #: (untyped) -> [Array[untyped], Hash[Symbol, untyped]]
       raise NotImplementedError,
-        "ActiveJob handles deserialization via ActiveJob::Base.execute"
-    end
-
-    # Override unique key generation to hash only the arguments portion
-    # of the serialized payload. The full payload contains volatile fields
-    # (job_id, enqueued_at, etc.) that change per instance.
-    def zizq_unique_key(*args, **kwargs) #: (*untyped, **untyped) -> String
-      arguments = new(*args, **kwargs).serialize["arguments"]
-      payload = normalize_payload(arguments)
-      "#{name}:#{Digest::SHA256.hexdigest(JSON.generate(payload))}"
+            "ActiveJob handles deserialization via ActiveJob::Base.execute"
     end
 
     # Generate a jq expression that exactly matches payloads with the given
@@ -139,5 +130,34 @@ module Zizq
 
       parts.join(" and ")
     end
+
+    # Static jq expressions for the batched-job configuration on this
+    # class. Targets `.arguments[N]` for a positional batch arg or
+    # `.arguments[-1].NAME` for a keyword batch arg — the latter
+    # assumes the class actually receives kwargs so that the last
+    # argument is the ActiveJob kwargs hash. Behaviour is unspecified
+    # if the declared `kwarg:` isn't present at enqueue time.
+    def zizq_batch_expressions #: () -> Zizq::batch_expressions?
+      return nil unless zizq_batched
+
+      target =
+        if (idx = zizq_batch_arg)
+          ".arguments[#{idx}]"
+        else
+          ".arguments[-1].#{zizq_batch_kwarg}"
+        end
+
+      build_batch_expressions(target)
+    end
+
+    private
+
+    # Hash only the arguments portion of the serialized ActiveJob
+    # payload. The full envelope contains volatile fields (job_id,
+    # enqueued_at, etc.) that change per instance and would defeat
+    # both `zizq_unique_key` and `zizq_batch_key`.
+    def hashable_args(*args, **kwargs) #: (*untyped, **untyped) -> untyped
+      new(*args, **kwargs).serialize["arguments"]
+    end
   end
 end

data/lib/zizq/backoff.rb

@@ -44,7 +44,11 @@ module Zizq
 
     # Returns a new Backoff with the same configuration but reset state.
     def fresh #: () -> Backoff
-      self.class.new(min_wait: @min_wait, max_wait: @max_wait, multiplier: @multiplier)
+      self.class.new(
+        min_wait: @min_wait,
+        max_wait: @max_wait,
+        multiplier: @multiplier
+      )
     end
   end
 end

data/lib/zizq/bulk_enqueue.rb

@@ -28,7 +28,12 @@ module Zizq
     # @rbs &block: ?(EnqueueRequest) -> void
     # @rbs return: void
     def enqueue(job_class, *args, **kwargs, &block)
-      @requests << Zizq.build_enqueue_request(job_class, *args, **kwargs, &block)
+      @requests << Zizq.build_enqueue_request(
+        job_class,
+        *args,
+        **kwargs,
+        &block
+      )
     end
 
     # Collect a raw enqueue. Accepts the same arguments as
@@ -44,6 +49,7 @@ module Zizq
     # @rbs retention: Zizq::retention?
     # @rbs unique_key: String?
     # @rbs unique_while: Zizq::unique_scope?
+    # @rbs batch: Zizq::batch?
     # @rbs return: void
     def enqueue_raw(queue:, type:, payload:, **opts)
       @requests << EnqueueRequest.new(queue:, type:, payload:, **opts)