zizq 0.5.0 → 0.6.0

data/lib/zizq/configuration.rb

@@ -112,8 +112,8 @@ module Zizq
         @tls = TlsConfiguration.new(**value)
       else
         raise ArgumentError,
-          "Zizq.configure: tls= expects a Hash, Zizq::TlsConfiguration, or nil " \
-          "(got #{value.class})"
+              "Zizq.configure: tls= expects a Hash, Zizq::TlsConfiguration, or nil " \
+                "(got #{value.class})"
       end
     end
 
@@ -143,8 +143,8 @@ module Zizq
         @worker = WorkerConfiguration.new(**value)
       else
         raise ArgumentError,
-          "Zizq.configure: worker= expects a Hash, Zizq::WorkerConfiguration, or nil " \
-          "(got #{value.class})"
+              "Zizq.configure: worker= expects a Hash, Zizq::WorkerConfiguration, or nil " \
+                "(got #{value.class})"
       end
     end
 
@@ -175,15 +175,18 @@ module Zizq
       raise ArgumentError, "Zizq.configure: url is required" if url.empty?
 
       unless %i[msgpack json].include?(format)
-        raise ArgumentError, "Zizq.configure: format must be :msgpack or :json, got #{format.inspect}"
+        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}"
+        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}"
+        raise ArgumentError,
+              "Zizq.configure: stream_idle_timeout must be a positive number, got #{stream_idle_timeout.inspect}"
       end
 
       tls = @tls
@@ -255,11 +258,13 @@ module Zizq
 
     def validate_tls!(tls) #: (TlsConfiguration) -> void
       if tls.client_cert && !tls.client_key
-        raise ArgumentError, "Zizq.configure: tls.client_key is required when tls.client_cert is set"
+        raise ArgumentError,
+              "Zizq.configure: tls.client_key is required when tls.client_cert is set"
       end
 
       if tls.client_key && !tls.client_cert
-        raise ArgumentError, "Zizq.configure: tls.client_cert is required when tls.client_key is set"
+        raise ArgumentError,
+              "Zizq.configure: tls.client_cert is required when tls.client_key is set"
       end
     end
 
@@ -276,11 +281,7 @@ module Zizq
     # If the value looks like PEM data, return it as-is; otherwise treat
     # it as a file path and read the contents.
     def resolve_pem(value) #: (String) -> String
-      if value.include?("-----BEGIN ")
-        value
-      else
-        File.read(value)
-      end
+      value.include?("-----BEGIN ") ? value : File.read(value)
     end
   end
 end

data/lib/zizq/crontab.rb

@@ -142,8 +142,8 @@ module Zizq
         Zizq.client.replace_cron_group(
           name,
           paused:,
-          entries: entries.values.map(&:to_params),
-        ),
+          entries: entries.values.map(&:to_params)
+        )
       )
 
       @building = false
@@ -161,9 +161,10 @@ module Zizq
     def entry(name)
       materialize
       entries.fetch(name) do
-        entry = materialize_entry_with(
-          Zizq.client.get_cron_group_entry(self.name, name),
-        )
+        entry =
+          materialize_entry_with(
+            Zizq.client.get_cron_group_entry(self.name, name)
+          )
         entries[name] = entry
       end
     end
@@ -196,16 +197,17 @@ module Zizq
     # @rbs return: Zizq::CrontabEntryBuilder
     def define_entry(name, expression, timezone: nil, paused: nil)
       CrontabEntryBuilder.new(self, name, expression, timezone:, paused:) do |e|
-        entry = materialize_entry_with(
-          Zizq.client.replace_cron_group_entry(
-            self.name,
-            name,
-            expression: e.expression,
-            job: e.job.to_enqueue_params,
-            timezone: e.timezone,
-            paused: e.paused,
-          ),
-        )
+        entry =
+          materialize_entry_with(
+            Zizq.client.replace_cron_group_entry(
+              self.name,
+              name,
+              expression: e.expression,
+              job: e.job.to_enqueue_params,
+              timezone: e.timezone,
+              paused: e.paused
+            )
+          )
 
         materialize # in case this was the first entry operation
 
@@ -222,12 +224,11 @@ module Zizq
       @paused_at = result.paused_at
       @resumed_at = result.resumed_at
 
-      @entries = result.entries.map do |entry|
-        [
-          entry.name,
-          materialize_entry_with(entry),
-        ]
-      end.to_h
+      @entries =
+        result
+          .entries
+          .map { |entry| [entry.name, materialize_entry_with(entry)] }
+          .to_h
 
       @materialized = true
 
@@ -241,22 +242,23 @@ module Zizq
         self,
         result.name,
         result.expression,
-        job: EnqueueRequest.new(
-          type: result.job.type,
-          queue: result.job.queue,
-          priority: result.job.priority,
-          payload: result.job.payload,
-          retry_limit: result.job.retry_limit,
-          backoff: result.job.backoff,
-          retention: result.job.retention,
-          unique_key: result.job.unique_key,
-          unique_while: result.job.unique_while,
-        ),
+        job:
+          EnqueueRequest.new(
+            type: result.job.type,
+            queue: result.job.queue,
+            priority: result.job.priority,
+            payload: result.job.payload,
+            retry_limit: result.job.retry_limit,
+            backoff: result.job.backoff,
+            retention: result.job.retention,
+            unique_key: result.job.unique_key,
+            unique_while: result.job.unique_while
+          ),
         paused: result.paused?,
         paused_at: result.paused_at,
         resumed_at: result.resumed_at,
         last_enqueue_at: result.last_enqueue_at,
-        next_enqueue_at: result.next_enqueue_at,
+        next_enqueue_at: result.next_enqueue_at
       )
     end
   end

data/lib/zizq/crontab_builder.rb

@@ -40,13 +40,7 @@ module Zizq
     # @rbs paused: bool?
     # @rbs return: Zizq::CrontabEntryBuilder
     def define_entry(name, expression, timezone: self.timezone, paused: nil)
-      CrontabEntryBuilder.new(
-        target,
-        name,
-        expression,
-        timezone:,
-        paused:,
-      )
+      CrontabEntryBuilder.new(target, name, expression, timezone:, paused:)
     end
   end
 end

data/lib/zizq/crontab_entry.rb

@@ -62,16 +62,18 @@ module Zizq
     # @rbs resumed_at: Float?
     # @rbs last_enqueue_at: Float?
     # @rbs next_enqueue_at: Float?
-    def initialize(crontab,
-                   name,
-                   expression,
-                   job:,
-                   timezone: nil,
-                   paused: nil,
-                   paused_at: nil,
-                   resumed_at: nil,
-                   last_enqueue_at: nil,
-                   next_enqueue_at: nil)
+    def initialize(
+      crontab,
+      name,
+      expression,
+      job:,
+      timezone: nil,
+      paused: nil,
+      paused_at: nil,
+      resumed_at: nil,
+      last_enqueue_at: nil,
+      next_enqueue_at: nil
+    )
       @crontab = crontab
       @name = name
       @expression = expression
@@ -93,7 +95,13 @@ module Zizq
     # @rbs paused: bool?
     # @rbs return: Zizq::CrontabEntryBuilder
     def redefine(expression, timezone: nil, paused: nil)
-      CrontabEntryBuilder.new(crontab, name, expression, timezone:, paused:) do |e|
+      CrontabEntryBuilder.new(
+        crontab,
+        name,
+        expression,
+        timezone:,
+        paused:
+      ) do |e|
         materialize_with(
           Zizq.client.replace_cron_group_entry(
             crontab.name,
@@ -101,8 +109,8 @@ module Zizq
             expression: e.expression,
             job: e.job.to_enqueue_params,
             timezone: e.timezone,
-            paused: e.paused,
-          ),
+            paused: e.paused
+          )
         )
       end
     end
@@ -118,11 +126,7 @@ module Zizq
     # This is independent of the paused state of the Crontab itself.
     def pause! #: () -> void
       materialize_with(
-        Zizq.client.update_cron_group_entry(
-          crontab.name,
-          name,
-          paused: true,
-        ),
+        Zizq.client.update_cron_group_entry(crontab.name, name, paused: true)
       )
     end
 
@@ -132,11 +136,7 @@ module Zizq
     # jobs until the Crontab is resumed.
     def resume! #: () -> void
       materialize_with(
-        Zizq.client.update_cron_group_entry(
-          crontab.name,
-          name,
-          paused: false,
-        ),
+        Zizq.client.update_cron_group_entry(crontab.name, name, paused: false)
       )
     end
 
@@ -148,7 +148,7 @@ module Zizq
         expression:,
         timezone:,
         job: job.to_enqueue_params,
-        paused:,
+        paused:
       }.compact #: Zizq::cron_entry_params
     end
 
@@ -164,17 +164,18 @@ module Zizq
       @resumed_at = result.resumed_at
       @last_enqueue_at = result.last_enqueue_at
       @next_enqueue_at = result.next_enqueue_at
-      @job = EnqueueRequest.new(
-        type: result.job.type,
-        queue: result.job.queue,
-        priority: result.job.priority,
-        payload: result.job.payload,
-        retry_limit: result.job.retry_limit,
-        backoff: result.job.backoff,
-        retention: result.job.retention,
-        unique_key: result.job.unique_key,
-        unique_while: result.job.unique_while,
-      )
+      @job =
+        EnqueueRequest.new(
+          type: result.job.type,
+          queue: result.job.queue,
+          priority: result.job.priority,
+          payload: result.job.payload,
+          retry_limit: result.job.retry_limit,
+          backoff: result.job.backoff,
+          retention: result.job.retention,
+          unique_key: result.job.unique_key,
+          unique_while: result.job.unique_while
+        )
 
       self
     end

data/lib/zizq/crontab_entry_builder.rb

@@ -46,12 +46,7 @@ module Zizq
     # @rbs timezone: String?
     # @rbs paused: bool?
     # @rbs ?&block: (Zizq::CrontabEntry) -> Zizq::CrontabEntry
-    def initialize(target,
-                   name,
-                   expression,
-                   timezone: nil,
-                   paused: nil,
-                   &block)
+    def initialize(target, name, expression, timezone: nil, paused: nil, &block)
       @target = target
       @name = name
       @expression = expression
@@ -86,6 +81,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)
       push_entry(EnqueueRequest.new(queue:, type:, payload:, **opts))
@@ -96,7 +92,7 @@ module Zizq
     # @rbs &block: (BulkEnqueue) -> void
     # @rbs return: self
     def enqueue_bulk(&block)
-      raise NotImplementedError, 'bulk enqueues are not supported via cron'
+      raise NotImplementedError, "bulk enqueues are not supported via cron"
     end
 
     # Provide common fields to be used when enqueueing a job.
@@ -113,19 +109,20 @@ module Zizq
     # @rbs return: untyped
     def push_entry(req)
       if req.ready_at || req.delay
-        raise ArgumentError, 'delayed job are not permitted via cron'
+        raise ArgumentError, "delayed job are not permitted via cron"
       end
 
-      entry = callback.call(
-        CrontabEntry.new(
-          target,
-          name,
-          expression,
-          job: req,
-          timezone:,
-          paused:,
-        ),
-      )
+      entry =
+        callback.call(
+          CrontabEntry.new(
+            target,
+            name,
+            expression,
+            job: req,
+            timezone:,
+            paused:
+          )
+        )
 
       target.entries[entry.name] = entry
     end

data/lib/zizq/enqueue_request.rb

@@ -48,6 +48,9 @@ module Zizq
     # Uniqueness scope.
     attr_accessor :unique_while #: Zizq::unique_scope?
 
+    # Batch configuration for folded jobs.
+    attr_accessor :batch #: Zizq::batch?
+
     # @rbs type: String
     # @rbs queue: String
     # @rbs payload: untyped
@@ -59,18 +62,22 @@ module Zizq
     # @rbs retention: Zizq::retention?
     # @rbs unique_key: String?
     # @rbs unique_while: Zizq::unique_scope?
+    # @rbs batch: Zizq::batch?
     # @rbs return: void
-    def initialize(type:,
-                   queue:,
-                   payload:,
-                   priority: nil,
-                   delay: nil,
-                   ready_at: nil,
-                   retry_limit: nil,
-                   backoff: nil,
-                   retention: nil,
-                   unique_key: nil,
-                   unique_while: nil)
+    def initialize(
+      type:,
+      queue:,
+      payload:,
+      priority: nil,
+      delay: nil,
+      ready_at: nil,
+      retry_limit: nil,
+      backoff: nil,
+      retention: nil,
+      unique_key: nil,
+      unique_while: nil,
+      batch: nil
+    )
       update(
         type:,
         queue:,
@@ -83,6 +90,7 @@ module Zizq
         retention:,
         unique_key:,
         unique_while:,
+        batch:
       )
     end
 
@@ -111,29 +119,34 @@ module Zizq
     # @rbs retention: Zizq::retention?
     # @rbs unique_key: String?
     # @rbs unique_while: Zizq::unique_scope?
+    # @rbs batch: Zizq::batch?
     # @rbs return: self
-    def update(type: @type,
-               queue: @queue,
-               payload: @payload,
-               priority: @priority,
-               delay: @delay,
-               ready_at: @ready_at,
-               retry_limit: @retry_limit,
-               backoff: @backoff,
-               retention: @retention,
-               unique_key: @unique_key,
-               unique_while: @unique_while)
-      @type         = type
-      @queue        = queue
-      @payload      = payload
-      @priority     = priority
-      @delay        = delay
-      @ready_at     = ready_at
-      @retry_limit  = retry_limit
-      @backoff      = backoff
-      @retention    = retention
-      @unique_key   = unique_key
+    def update(
+      type: @type,
+      queue: @queue,
+      payload: @payload,
+      priority: @priority,
+      delay: @delay,
+      ready_at: @ready_at,
+      retry_limit: @retry_limit,
+      backoff: @backoff,
+      retention: @retention,
+      unique_key: @unique_key,
+      unique_while: @unique_while,
+      batch: @batch
+    )
+      @type = type
+      @queue = queue
+      @payload = payload
+      @priority = priority
+      @delay = delay
+      @ready_at = ready_at
+      @retry_limit = retry_limit
+      @backoff = backoff
+      @retention = retention
+      @unique_key = unique_key
       @unique_while = unique_while
+      @batch = batch
       self
     end
 
@@ -145,11 +158,7 @@ module Zizq
       params = { queue:, type:, payload: } #: Hash[Symbol, untyped]
       params[:priority] = priority if priority
 
-      effective_ready_at = if delay
-        Time.now.to_f + delay.to_f
-      else
-        ready_at
-      end
+      effective_ready_at = (delay ? Time.now.to_f + delay.to_f : ready_at)
       params[:ready_at] = effective_ready_at if effective_ready_at
 
       params[:retry_limit] = retry_limit if retry_limit
@@ -164,7 +173,9 @@ module Zizq
 
       if retention
         ret = {} #: Hash[Symbol, Integer]
-        ret[:completed_ms] = (retention[:completed].to_f * 1000).to_i if retention[:completed]
+        ret[:completed_ms] = (
+          retention[:completed].to_f * 1000
+        ).to_i if retention[:completed]
         ret[:dead_ms] = (retention[:dead].to_f * 1000).to_i if retention[:dead]
         params[:retention] = ret
       end
@@ -172,6 +183,8 @@ module Zizq
       params[:unique_key] = unique_key if unique_key
       params[:unique_while] = unique_while.to_s if unique_while
 
+      params[:batch] = batch if batch
+
       params
     end
   end

data/lib/zizq/enqueue_with.rb

@@ -101,9 +101,7 @@ module Zizq
     # @rbs &block: (EnqueueWith) -> void
     # @rbs return: untyped
     def enqueue_bulk(&block)
-      @target.enqueue_bulk do |b|
-        block.call(self.class.new(b, @overrides))
-      end
+      @target.enqueue_bulk { |b| block.call(self.class.new(b, @overrides)) }
     end
   end
 end

data/lib/zizq/error.rb

@@ -6,10 +6,12 @@
 
 module Zizq
   # Base error class for all Zizq errors.
-  class Error < StandardError; end
+  class Error < StandardError
+  end
 
   # Network-level failure (connection refused, DNS, timeout etc).
-  class ConnectionError < Error; end
+  class ConnectionError < Error
+  end
 
   # HTTP error — the server returned a non-success status code.
   # Carries the status code and parsed body.
@@ -30,14 +32,18 @@ module Zizq
   end
 
   # 4xx client error.
-  class ClientError < ResponseError; end
+  class ClientError < ResponseError
+  end
 
   # 404 specifically — job not found, etc.
-  class NotFoundError < ClientError; end
+  class NotFoundError < ClientError
+  end
 
   # 5xx server error.
-  class ServerError < ResponseError; end
+  class ServerError < ResponseError
+  end
 
   # Streaming take-jobs connection interrupted.
-  class StreamError < Error; end
+  class StreamError < Error
+  end
 end

data/lib/zizq/job.rb

@@ -47,10 +47,9 @@ module Zizq
       job_class = Object.const_get(job.type)
 
       unless (
-          job_class.is_a?(Class) &&
-          job_class.include?(Zizq::Job) &&
-          job_class.is_a?(Zizq::JobConfig)
-      )
+               job_class.is_a?(Class) && job_class.include?(Zizq::Job) &&
+                 job_class.is_a?(Zizq::JobConfig)
+             )
         raise "#{job.type} does not include Zizq::Job"
       end
 
@@ -58,9 +57,10 @@ module Zizq
       instance = zizq_job_class.new
       instance.set_zizq_job(job)
 
-      args, kwargs = zizq_job_class.zizq_deserialize(
-        job.payload || { "args" => [], "kwargs" => {} }
-      )
+      args, kwargs =
+        zizq_job_class.zizq_deserialize(
+          job.payload || { "args" => [], "kwargs" => {} }
+        )
 
       instance.perform(*args, **kwargs)
     end
@@ -106,7 +106,7 @@ module Zizq
       # Any failure to deserialize the arguments will cause the job to fail and
       # backoff according to the backoff policy.
       def zizq_deserialize(payload) #: (Hash[String, untyped]) -> [Array[untyped], Hash[Symbol, untyped]]
-        args   = payload.fetch("args")
+        args = payload.fetch("args")
         kwargs = payload.fetch("kwargs").transform_keys(&:to_sym)
         [args, kwargs]
       end
@@ -143,6 +143,23 @@ module Zizq
           "(.kwargs | contains(#{JSON.generate(serialized_kwargs)}))"
         ].join(" and ")
       end
+
+      # Static jq expressions for the batched-job configuration on this
+      # class. Targets `.args[N]` for a positional batch arg or
+      # `.kwargs.NAME` for a keyword batch arg, matching the payload
+      # shape produced by the default `zizq_serialize`.
+      def zizq_batch_expressions #: () -> Zizq::batch_expressions?
+        return nil unless zizq_batched
+
+        target =
+          if (idx = zizq_batch_arg)
+            ".args[#{idx}]"
+          else
+            ".kwargs.#{zizq_batch_kwarg}"
+          end
+
+        build_batch_expressions(target)
+      end
     end
 
     # This is your job's main entrypoint when it is run by the worker.
@@ -154,7 +171,8 @@ module Zizq
     # easier to evolve over time in a backwards compatible way with any already
     # enqueued jobs.
     def perform(*args, **kwargs) #: (*untyped, **untyped) -> void
-      raise NotImplementedError, "#{self.class.name}#perform must be implemented"
+      raise NotImplementedError,
+            "#{self.class.name}#perform must be implemented"
     end
 
     # --- Metadata helpers ---
@@ -164,17 +182,17 @@ module Zizq
     # metadata.
 
     # The unique job ID assigned by the server.
-    def zizq_id = @zizq_job&.id         #: () -> String?
+    def zizq_id = @zizq_job&.id #: () -> String?
 
     # How many times this job has previously been attempted (0 on the first
     # run, 1 on the second, etc...).
-    def zizq_attempts = @zizq_job&.attempts   #: () -> Integer?
+    def zizq_attempts = @zizq_job&.attempts #: () -> Integer?
 
     # The queue this job was dequeued from.
-    def zizq_queue = @zizq_job&.queue      #: () -> String?
+    def zizq_queue = @zizq_job&.queue #: () -> String?
 
     # The priority this job was enqueued with.
-    def zizq_priority = @zizq_job&.priority   #: () -> Integer?
+    def zizq_priority = @zizq_job&.priority #: () -> Integer?
 
     # Time at which this job was dequeued (fractional seconds since the Unix
     # epoch). This can be converted to `Time` by using `Time.at(dequeued_at)`