zizq 0.5.0 → 0.6.0

data/lib/zizq/job_config.rb

@@ -49,7 +49,8 @@ module Zizq
     #
     # Implemented by the including module.
     def zizq_payload_subset_filter(*args, **kwargs) #: (*untyped, **untyped) -> String
-      raise NotImplementedError, "#{self} must implement zizq_payload_subset_filter"
+      raise NotImplementedError,
+            "#{self} must implement zizq_payload_subset_filter"
     end
 
     # Declare the default queue for this job class.
@@ -116,7 +117,11 @@ module Zizq
           raise ArgumentError, "all of exponent:, base:, jitter: are required"
         end
 
-        @zizq_backoff = { exponent: exponent.to_f, base: base.to_f, jitter: jitter.to_f }
+        @zizq_backoff = {
+          exponent: exponent.to_f,
+          base: base.to_f,
+          jitter: jitter.to_f
+        }
       else
         @zizq_backoff
       end
@@ -170,6 +175,10 @@ module Zizq
       if unique.nil?
         @zizq_unique || false
       else
+        if unique && zizq_batched
+          raise ArgumentError,
+                "#{self}: zizq_unique cannot be combined with zizq_batched"
+        end
         @zizq_unique = !!unique
         @zizq_unique_scope = scope
         @zizq_unique
@@ -188,6 +197,105 @@ module Zizq
       end
     end
 
+    # Declare or read batched-job configuration for this class.
+    #
+    # When enabled, subsequent enqueues that share the batch key are
+    # folded into the pending job's payload rather than creating a new
+    # job. The batch target is a specific positional arg (`arg:`) or
+    # keyword arg (`kwarg:`) whose value must be an array; other args
+    # participate in the batch key.
+    #
+    #   zizq_batched true, limit: 100                     # arg: 0 by default
+    #   zizq_batched true, kwarg: :notifications, limit: 100
+    #   zizq_batched true, limit: 50, dedup: true         # + `| unique`
+    #   zizq_batched true, limit: 50, sorted: true        # + `| sort`
+    #   zizq_batched false                                # disable in a subclass
+    #
+    # Cannot be combined with `zizq_unique` — the server rejects the
+    # combination and the client raises at declaration time.
+    #
+    # @rbs enabled: bool?
+    # @rbs arg: Integer?
+    # @rbs kwarg: Symbol?
+    # @rbs limit: Integer?
+    # @rbs dedup: bool
+    # @rbs sorted: bool
+    # @rbs return: bool
+    def zizq_batched(
+      enabled = nil,
+      arg: nil,
+      kwarg: nil,
+      limit: nil,
+      dedup: false,
+      sorted: false
+    )
+      return @zizq_batched || false if enabled.nil?
+
+      if enabled
+        if zizq_unique
+          raise ArgumentError,
+                "#{self}: zizq_batched cannot be combined with zizq_unique"
+        end
+        if arg && kwarg
+          raise ArgumentError,
+                "#{self}: zizq_batched cannot specify both arg: and kwarg:"
+        end
+        if limit.nil?
+          raise ArgumentError, "#{self}: zizq_batched requires limit:"
+        end
+        unless limit.is_a?(Integer) && limit.positive?
+          raise ArgumentError,
+                "#{self}: zizq_batched limit: must be a positive Integer"
+        end
+
+        @zizq_batched = true
+        @zizq_batch_arg = kwarg.nil? ? (arg || 0) : nil
+        @zizq_batch_kwarg = kwarg
+        @zizq_batch_limit = limit
+        @zizq_batch_dedup = dedup
+        @zizq_batch_sorted = sorted
+      else
+        @zizq_batched = false
+        @zizq_batch_arg = nil
+        @zizq_batch_kwarg = nil
+        @zizq_batch_limit = nil
+        @zizq_batch_dedup = false
+        @zizq_batch_sorted = false
+      end
+
+      @zizq_batched
+    end
+
+    # Positional arg index that participates in the batch payload, or
+    # `nil` if `kwarg:` was chosen instead.
+    def zizq_batch_arg #: () -> Integer?
+      @zizq_batch_arg
+    end
+
+    # Keyword arg name that participates in the batch payload, or `nil`
+    # if `arg:` was chosen instead.
+    def zizq_batch_kwarg #: () -> Symbol?
+      @zizq_batch_kwarg
+    end
+
+    # Maximum combined length of the batch payload before the current
+    # batch is sealed and a fresh one starts.
+    def zizq_batch_limit #: () -> Integer?
+      @zizq_batch_limit
+    end
+
+    # Whether the fold expression appends `| unique` to dedup entries
+    # within a batch.
+    def zizq_batch_dedup? #: () -> bool
+      @zizq_batch_dedup || false
+    end
+
+    # Whether the fold expression appends `| sort` to sort entries
+    # within a batch.
+    def zizq_batch_sorted? #: () -> bool
+      @zizq_batch_sorted || false
+    end
+
     # Compute the unique key for a job with the given arguments.
     #
     # The default implementation uses the class name and hashes the
@@ -198,8 +306,46 @@ module Zizq
     #     super(user_id)  # unique per user, ignoring template
     #   end
     def zizq_unique_key(*args, **kwargs) #: (*untyped, **untyped) -> String
-      payload = normalize_payload(zizq_serialize(*args, **kwargs))
-      "#{name}:#{Digest::SHA256.hexdigest(JSON.generate(payload))}"
+      hash_args(*args, **kwargs)
+    end
+
+    # Compute the batch key for a job with the given arguments.
+    #
+    # The default implementation drops the configured batch target
+    # (positional `arg:` or `kwarg:`) from the arguments and hashes
+    # everything else. Two enqueues with the same non-batch arguments
+    # therefore produce the same batch key, so they fold into the same
+    # pending job; different non-batch arguments produce different keys
+    # and end up in separate batches.
+    #
+    # Override this method to customize batching — for example, to
+    # batch by tenant regardless of what else is passed:
+    #
+    #   def self.zizq_batch_key(_notifications, tenant_id:, **_)
+    #     "#{name}:tenant-#{tenant_id}"
+    #   end
+    def zizq_batch_key(*args, **kwargs) #: (*untyped, **untyped) -> String
+      filtered_args =
+        args.dup.tap { |a| a.delete_at(zizq_batch_arg) if zizq_batch_arg }
+      filtered_kwargs = kwargs.except(zizq_batch_kwarg)
+
+      hash_args(*filtered_args, **filtered_kwargs)
+    end
+
+    # Build the static jq expressions (`when` predicate, `fold`
+    # reducer) for this class's batch configuration.
+    #
+    # Implemented by the including module — `Zizq::Job` and
+    # `Zizq::ActiveJobConfig` know how to target the right JSON path
+    # for their respective payload shapes. Returns `nil` when the
+    # class is not batched.
+    #
+    # Override to supply completely custom `when`/`fold` expressions
+    # that the DSL flags don't cover.
+    def zizq_batch_expressions #: () -> Zizq::batch_expressions?
+      return nil unless zizq_batched
+
+      raise NotImplementedError, "#{self} must implement zizq_batch_expressions"
     end
 
     # Build a `Zizq::EnqueueRequest` from the class-level job config.
@@ -214,26 +360,84 @@ module Zizq
     #   end
     def zizq_enqueue_request(*args, **kwargs) #: (*untyped, **untyped) -> EnqueueRequest
       EnqueueRequest.new(
-        type:         name || raise(ArgumentError, "Cannot enqueue anonymous class"),
-        queue:        zizq_queue,
-        payload:      zizq_serialize(*args, **kwargs),
-        priority:     zizq_priority,
-        retry_limit:  zizq_retry_limit,
-        backoff:      zizq_backoff,
-        retention:    zizq_retention,
+        type: name || raise(ArgumentError, "Cannot enqueue anonymous class"),
+        queue: zizq_queue,
+        payload: zizq_serialize(*args, **kwargs),
+        priority: zizq_priority,
+        retry_limit: zizq_retry_limit,
+        backoff: zizq_backoff,
+        retention: zizq_retention,
         unique_while: zizq_unique ? zizq_unique_scope : nil,
-        unique_key:   zizq_unique ? zizq_unique_key(*args, **kwargs) : nil
+        unique_key: zizq_unique ? zizq_unique_key(*args, **kwargs) : nil,
+        batch: zizq_batched ? batch_for_enqueue(*args, **kwargs) : nil
       )
     end
 
     private
 
+    # Class-name-prefixed SHA256 of the normalized hashable payload.
+    # Shared primitive powering both `zizq_unique_key` and
+    # `zizq_batch_key` — the two features hash arguments the same way,
+    # they just choose *which* arguments to hash.
+    def hash_args(*args, **kwargs) #: (*untyped, **untyped) -> String
+      payload = normalize_payload(hashable_args(*args, **kwargs))
+      "#{name}:#{Digest::SHA256.hexdigest(JSON.generate(payload))}"
+    end
+
+    # The subset of the serialized payload that participates in key
+    # hashing. Defaults to the full serialized payload; overridden by
+    # `ActiveJobConfig` to hash only the ActiveJob `arguments` array
+    # (skipping volatile envelope fields like `job_id` and
+    # `enqueued_at` that vary per enqueue).
+    def hashable_args(*args, **kwargs) #: (*untyped, **untyped) -> untyped
+      zizq_serialize(*args, **kwargs)
+    end
+
+    # Compose `zizq_batch_expressions` (static) with `zizq_batch_key`
+    # (dynamic, arg-dependent) into a full API serialized `Zizq::batch`.
+    def batch_for_enqueue(*args, **kwargs) #: (*untyped, **untyped) -> Zizq::batch?
+      expr = zizq_batch_expressions
+      return nil unless expr
+
+      {
+        key: zizq_batch_key(*args, **kwargs),
+        when: expr[:when],
+        fold: expr[:fold]
+      }
+    end
+
+    # Compile `when`/`fold` expressions targeting a jq path (e.g.
+    # `.args[0]` for `Zizq::Job` or `.arguments[-1].notifications`
+    # for `ActiveJobConfig`). Applies dedup/sorted flags. Shared
+    # across payload shapes because only the target path differs.
+    def build_batch_expressions(target) #: (String) -> Zizq::batch_expressions
+      limit = zizq_batch_limit
+      when_expr = "($existing#{target} + $new#{target}) | length <= #{limit}"
+
+      fold_expr =
+        if zizq_batch_dedup?
+          # `unique` in jq also sorts, so it subsumes `sorted:` too.
+          "$existing | #{target} = " \
+            "(#{target} + $new#{target} | unique)"
+        elsif zizq_batch_sorted?
+          "$existing | #{target} = " \
+            "(#{target} + $new#{target} | sort)"
+        else
+          "$existing | #{target} += $new#{target}"
+        end
+
+      { when: when_expr, fold: fold_expr }
+    end
+
     # Deep-sort all Hash keys so that serialization is deterministic
     # regardless of insertion order or JSON library.
     def normalize_payload(obj) #: (untyped) -> untyped
       case obj
       when Hash
-        obj.sort_by { |k, _| k.to_s }.map { |k, v| [k, normalize_payload(v)] }.to_h
+        obj
+          .sort_by { |k, _| k.to_s }
+          .map { |k, v| [k, normalize_payload(v)] }
+          .to_h
       when Array
         obj.map { |v| normalize_payload(v) }
       else

data/lib/zizq/lifecycle.rb

@@ -34,7 +34,11 @@ module Zizq
       return unless @state == :running
 
       @state = :draining
-      @drain_latch.close rescue nil
+      begin
+        @drain_latch.close
+      rescue StandardError
+        nil
+      end
     end
 
     # Transition to :stopped.
@@ -42,7 +46,11 @@ module Zizq
       return if @state == :stopped
 
       @state = :stopped
-      @stop_latch.close rescue nil
+      begin
+        @stop_latch.close
+      rescue StandardError
+        nil
+      end
     end
 
     # Block until the state is no longer :running.

data/lib/zizq/middleware.rb

@@ -52,13 +52,14 @@ module Zizq
       private
 
       def build #: () -> untyped
-        @built ||= if @entries.empty?
-          @terminal
-        else
-          @entries.reverse.reduce(@terminal) do |next_link, mw|
-            Link.new(mw, next_link)
+        @built ||=
+          if @entries.empty?
+            @terminal
+          else
+            @entries
+              .reverse
+              .reduce(@terminal) { |next_link, mw| Link.new(mw, next_link) }
           end
-        end
       end
     end
 

data/lib/zizq/query.rb

@@ -62,17 +62,19 @@ module Zizq
     # @rbs limit: Integer?
     # @rbs page_size: Integer?
     # @rbs return: void
-    def initialize(id: nil,
-                   queue: nil,
-                   type: nil,
-                   status: nil,
-                   jq_filter: nil,
-                   priority: nil,
-                   ready_at: nil,
-                   attempts: nil,
-                   order: nil,
-                   limit: nil,
-                   page_size: nil)
+    def initialize(
+      id: nil,
+      queue: nil,
+      type: nil,
+      status: nil,
+      jq_filter: nil,
+      priority: nil,
+      ready_at: nil,
+      attempts: nil,
+      order: nil,
+      limit: nil,
+      page_size: nil
+    )
       @id = id
       @queue = queue
       @type = type
@@ -232,8 +234,11 @@ module Zizq
     # @rbs return: Query
     def by_job_class_and_args(job_class, *args, **kwargs)
       validate_job_class!(job_class)
-      name = job_class.name or raise ArgumentError, "anonymous classes are not supported"
-      by_type(name).add_jq_filter(job_class.zizq_payload_filter(*args, **kwargs))
+      name = job_class.name or
+        raise ArgumentError, "anonymous classes are not supported"
+      by_type(name).add_jq_filter(
+        job_class.zizq_payload_filter(*args, **kwargs)
+      )
     end
 
     # Filter by job class and a subset of arguments.
@@ -250,8 +255,11 @@ module Zizq
     # @rbs return: Query
     def by_job_class_and_args_subset(job_class, *args, **kwargs)
       validate_job_class!(job_class)
-      name = job_class.name or raise ArgumentError, "anonymous classes are not supported"
-      by_type(name).add_jq_filter(job_class.zizq_payload_subset_filter(*args, **kwargs))
+      name = job_class.name or
+        raise ArgumentError, "anonymous classes are not supported"
+      by_type(name).add_jq_filter(
+        job_class.zizq_payload_subset_filter(*args, **kwargs)
+      )
     end
 
     # Replace the jq payload filter expression.
@@ -363,16 +371,17 @@ module Zizq
     def count(*args, &block)
       return super if block || !args.empty?
 
-      total = Zizq.client.count_jobs(
-        id: @id,
-        queue: @queue,
-        type: @type,
-        status: @status,
-        filter: @jq_filter,
-        priority: @priority,
-        ready_at: @ready_at,
-        attempts: @attempts,
-      )
+      total =
+        Zizq.client.count_jobs(
+          id: @id,
+          queue: @queue,
+          type: @type,
+          status: @status,
+          filter: @jq_filter,
+          priority: @priority,
+          ready_at: @ready_at,
+          attempts: @attempts
+        )
 
       @limit ? [total, @limit].min : total
     end
@@ -483,18 +492,23 @@ module Zizq
       enumerator = enum_for(:each_page)
 
       if block_given?
-        page = Zizq.client.list_jobs(
-          id: @id,
-          queue: @queue,
-          type: @type,
-          status: @status,
-          filter: @jq_filter,
-          priority: @priority,
-          ready_at: @ready_at,
-          attempts: @attempts,
-          limit: [@page_size, @limit, (@page_size || @limit) && MAX_PAGE_SIZE].compact.min,
-          order: @order,
-        )
+        page =
+          Zizq.client.list_jobs(
+            id: @id,
+            queue: @queue,
+            type: @type,
+            status: @status,
+            filter: @jq_filter,
+            priority: @priority,
+            ready_at: @ready_at,
+            attempts: @attempts,
+            limit: [
+              @page_size,
+              @limit,
+              (@page_size || @limit) && MAX_PAGE_SIZE
+            ].compact.min,
+            order: @order
+          )
 
         remaining = @limit
 
@@ -529,12 +543,14 @@ module Zizq
     # @rbs backoff: (Zizq::backoff | singleton(Zizq::RESET) | singleton(Zizq::UNCHANGED))?
     # @rbs retention: (Zizq::retention | singleton(Zizq::RESET) | singleton(Zizq::UNCHANGED))?
     # @rbs return: Integer
-    def update_all(queue: Zizq::UNCHANGED,
-                   priority: Zizq::UNCHANGED,
-                   ready_at: Zizq::UNCHANGED,
-                   retry_limit: Zizq::UNCHANGED,
-                   backoff: Zizq::UNCHANGED,
-                   retention: Zizq::UNCHANGED)
+    def update_all(
+      queue: Zizq::UNCHANGED,
+      priority: Zizq::UNCHANGED,
+      ready_at: Zizq::UNCHANGED,
+      retry_limit: Zizq::UNCHANGED,
+      backoff: Zizq::UNCHANGED,
+      retention: Zizq::UNCHANGED
+    )
       where = {
         id: @id,
         queue: @queue,
@@ -543,7 +559,7 @@ module Zizq
         filter: @jq_filter,
         priority: @priority,
         ready_at: @ready_at,
-        attempts: @attempts,
+        attempts: @attempts
       }
 
       apply = {
@@ -552,7 +568,7 @@ module Zizq
         ready_at:,
         retry_limit:,
         backoff:,
-        retention:,
+        retention:
       }
 
       if @limit || @page_size
@@ -567,10 +583,11 @@ module Zizq
           ids_on_page = page.jobs.map(&:id)
           ids_on_page = ids_on_page.take(remaining) if remaining
 
-          updated += Zizq.client.update_all_jobs(
-            where: where.merge(id: ids_on_page),
-            apply:,
-          )
+          updated +=
+            Zizq.client.update_all_jobs(
+              where: where.merge(id: ids_on_page),
+              apply:
+            )
 
           remaining -= ids_on_page.size if remaining
         end
@@ -603,7 +620,7 @@ module Zizq
         filter: @jq_filter,
         priority: @priority,
         ready_at: @ready_at,
-        attempts: @attempts,
+        attempts: @attempts
       }
 
       if @limit || @page_size
@@ -618,9 +635,8 @@ module Zizq
           ids_on_page = page.jobs.map(&:id)
           ids_on_page = ids_on_page.take(remaining) if remaining
 
-          deleted += Zizq.client.delete_all_jobs(
-            where: where.merge(id: ids_on_page),
-          )
+          deleted +=
+            Zizq.client.delete_all_jobs(where: where.merge(id: ids_on_page))
 
           remaining -= ids_on_page.size if remaining
         end
@@ -636,17 +652,19 @@ module Zizq
     # Build a new Query with the given overrides, preserving all other fields.
     #
     # @rbs return: Query
-    def rebuild(id: @id,
-                queue: @queue,
-                type: @type,
-                status: @status,
-                jq_filter: @jq_filter,
-                priority: @priority,
-                ready_at: @ready_at,
-                attempts: @attempts,
-                order: @order,
-                limit: @limit,
-                page_size: @page_size)
+    def rebuild(
+      id: @id,
+      queue: @queue,
+      type: @type,
+      status: @status,
+      jq_filter: @jq_filter,
+      priority: @priority,
+      ready_at: @ready_at,
+      attempts: @attempts,
+      order: @order,
+      limit: @limit,
+      page_size: @page_size
+    )
       self.class.new(
         id:,
         queue:,
@@ -658,7 +676,7 @@ module Zizq
         attempts:,
         limit:,
         order:,
-        page_size:,
+        page_size:
       )
     end
 
@@ -667,8 +685,8 @@ module Zizq
     def validate_job_class!(job_class)
       unless job_class.is_a?(JobConfig)
         raise ArgumentError,
-          "#{job_class} does not include Zizq::JobConfig " \
-          "(include Zizq::Job or extend Zizq::ActiveJobConfig)"
+              "#{job_class} does not include Zizq::JobConfig " \
+                "(include Zizq::Job or extend Zizq::ActiveJobConfig)"
       end
     end
   end

data/lib/zizq/resources/cron_entry.rb

@@ -8,13 +8,13 @@ module Zizq
   module Resources
     # Typed wrapper around a cron entry response hash.
     class CronEntry < Resource
-      def name            = @data["name"]            #: () -> String
-      def expression      = @data["expression"]      #: () -> String
-      def timezone        = @data["timezone"]        #: () -> String?
-      def paused          = @data["paused"]          #: () -> bool
-      def paused?         = paused                   #: () -> bool
-      def paused_at       = ms_to_seconds(@data["paused_at"])   #: () -> Float?
-      def resumed_at      = ms_to_seconds(@data["resumed_at"])  #: () -> Float?
+      def name = @data["name"] #: () -> String
+      def expression = @data["expression"] #: () -> String
+      def timezone = @data["timezone"] #: () -> String?
+      def paused = @data["paused"] #: () -> bool
+      def paused? = paused #: () -> bool
+      def paused_at = ms_to_seconds(@data["paused_at"]) #: () -> Float?
+      def resumed_at = ms_to_seconds(@data["resumed_at"]) #: () -> Float?
       def next_enqueue_at = ms_to_seconds(@data["next_enqueue_at"]) #: () -> Float?
       def last_enqueue_at = ms_to_seconds(@data["last_enqueue_at"]) #: () -> Float?
 

data/lib/zizq/resources/cron_group.rb

@@ -8,11 +8,11 @@ module Zizq
   module Resources
     # Typed wrapper around a cron group response hash.
     class CronGroup < Resource
-      def name        = @data["name"]        #: () -> String
-      def paused      = @data["paused"]      #: () -> bool
-      def paused?     = paused               #: () -> bool
-      def paused_at   = ms_to_seconds(@data["paused_at"])   #: () -> Float?
-      def resumed_at  = ms_to_seconds(@data["resumed_at"])  #: () -> Float?
+      def name = @data["name"] #: () -> String
+      def paused = @data["paused"] #: () -> bool
+      def paused? = paused #: () -> bool
+      def paused_at = ms_to_seconds(@data["paused_at"]) #: () -> Float?
+      def resumed_at = ms_to_seconds(@data["resumed_at"]) #: () -> Float?
 
       # Returns the entries in this group as typed resources.
       def entries #: () -> Array[CronEntry]

data/lib/zizq/resources/error_enumerator.rb

@@ -25,10 +25,7 @@ module Zizq
       # @rbs limit: Integer?
       # @rbs page_size: Integer?
       # @rbs return: void
-      def initialize(id,
-                     order: nil,
-                     limit: nil,
-                     page_size: nil)
+      def initialize(id, order: nil, limit: nil, page_size: nil)
         @id = id
         @order = order
         @limit = limit
@@ -204,11 +201,16 @@ module Zizq
         enumerator = enum_for(:each_page)
 
         if block_given?
-          page = Zizq.client.list_errors(
-            @id,
-            limit: [@page_size, @limit, (@page_size || @limit) && MAX_PAGE_SIZE].compact.min,
-            order: @order,
-          )
+          page =
+            Zizq.client.list_errors(
+              @id,
+              limit: [
+                @page_size,
+                @limit,
+                (@page_size || @limit) && MAX_PAGE_SIZE
+              ].compact.min,
+              order: @order
+            )
 
           remaining = @limit
 

data/lib/zizq/resources/error_page.rb

@@ -10,7 +10,8 @@ module Zizq
     # @rbs inherits Page[ErrorRecord]
     class ErrorPage < Page
       def items #: () -> Array[ErrorRecord]
-        @items ||= (@data["errors"] || []).map { |e| ErrorRecord.new(client, e) }
+        @items ||=
+          (@data["errors"] || []).map { |e| ErrorRecord.new(client, e) }
       end
 
       alias errors items

data/lib/zizq/resources/error_record.rb

@@ -8,12 +8,12 @@ module Zizq
   module Resources
     # Typed wrapper around a single error record from the job error history.
     class ErrorRecord < Resource
-      def attempt     = @data["attempt"]     #: () -> Integer
-      def message     = @data["message"]     #: () -> String
-      def error_type  = @data["error_type"]  #: () -> String?
-      def backtrace   = @data["backtrace"]   #: () -> String?
+      def attempt = @data["attempt"] #: () -> Integer
+      def message = @data["message"] #: () -> String
+      def error_type = @data["error_type"] #: () -> String?
+      def backtrace = @data["backtrace"] #: () -> String?
       def dequeued_at = ms_to_seconds(@data["dequeued_at"]) #: () -> Float
-      def failed_at   = ms_to_seconds(@data["failed_at"])   #: () -> Float
+      def failed_at = ms_to_seconds(@data["failed_at"]) #: () -> Float
     end
   end
 end