zizq 0.2.1 → 0.3.0

data/lib/zizq/crontab_entry.rb

@@ -0,0 +1,182 @@
+# Copyright (c) 2026 Chris Corbyn <chris@zizq.io>
+# Licensed under the MIT License. See LICENSE file for details.
+
+# rbs_inline: enabled
+# frozen_string_literal: true
+
+module Zizq
+  # Represents a single entry within a Crontab schedule.
+  #
+  # Each entry specifies the cron expression at which it executes,
+  # information about when it last/next enqueued a job, and details of the
+  # job that the entry enqueues.
+  #
+  # Entries can be paused or resumed, and can be deleted or redefined in place.
+  class CrontabEntry
+    # The Crontab schedule to which this entry belongs.
+    attr_reader :crontab #: Zizq::Crontab
+
+    # The name of this entry within the schedule.
+    attr_reader :name #: String
+
+    # The cron expression used to define the schedule for the entry.
+    #
+    # Both standard 5-field and enhanced 6-field cron (with seconds) are
+    # supported, along with @daily, @weekly etc.
+    attr_reader :expression #: String
+
+    # The timezone in which the schedule entry is processed.
+    #
+    # Defaults to the Zizq server timezone unless specified.
+    attr_reader :timezone #: String?
+
+    # Parameters that will be used to enqueue jobs each time the schedule fires.
+    #
+    # These are the same parameters as those used to enqueue jobs normally.
+    attr_reader :job #: EnqueueRequest
+
+    # True if this entry is currrently paused.
+    attr_reader :paused #: bool?
+
+    # The timestamp at which this entry was last paused.
+    attr_reader :paused_at #: Float?
+
+    # The timestamp at which this entry was last resumed.
+    attr_reader :resumed_at #: Float?
+
+    # The timestamp at which a job was last enqueued for this entry.
+    attr_reader :last_enqueue_at #: Float?
+    #
+    # The timestamp at which the next job will be enqueued for this entry.
+    attr_reader :next_enqueue_at #: Float?
+
+    # Initialize the entry with all configured parameters.
+    #
+    # @rbs crontab: Zizq::Crontab
+    # @rbs name: String
+    # @rbs expression: String
+    # @rbs timezone: String?
+    # @rbs job: EnqueueRequest
+    # @rbs paused: bool?
+    # @rbs paused_at: Float?
+    # @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)
+      @crontab = crontab
+      @name = name
+      @expression = expression
+      @timezone = timezone
+      @job = job
+      @paused = paused
+      @paused_at = paused_at
+      @resumed_at = resumed_at
+      @last_enqueue_at = last_enqueue_at
+      @next_enqueue_at = next_enqueue_at
+    end
+
+    # Replace this entry with another.
+    #
+    # This is equivalent to calling `crontab.define_entry` with the same name.
+    #
+    # @rbs expression: String
+    # @rbs timezone: String?
+    # @rbs paused: bool?
+    # @rbs return: Zizq::CrontabEntryBuilder
+    def redefine(expression, timezone: nil, paused: nil)
+      CrontabEntryBuilder.new(crontab, name, expression, timezone:, paused:) do |e|
+        materialize_with(
+          Zizq.client.replace_cron_group_entry(
+            crontab.name,
+            name,
+            expression: e.expression,
+            job: e.job.to_enqueue_params,
+            timezone: e.timezone,
+            paused: e.paused,
+          ),
+        )
+      end
+    end
+
+    # Delete the entry from the schedule.
+    def delete! #: () -> void
+      Zizq.client.delete_cron_group_entry(crontab.name, name)
+      crontab.entries.delete(name)
+    end
+
+    # Pause the entry within the schedule.
+    #
+    # 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,
+        ),
+      )
+    end
+
+    # Resume this entry if it is currently paused.
+    #
+    # If the parent Crontab itself is paused, the entry will still not enqueue
+    # jobs until the Crontab is resumed.
+    def resume! #: () -> void
+      materialize_with(
+        Zizq.client.update_cron_group_entry(
+          crontab.name,
+          name,
+          paused: false,
+        ),
+      )
+    end
+
+    # @private
+    # @rbs return: Zizq::cron_entry_params
+    def to_params
+      {
+        name:,
+        expression:,
+        timezone:,
+        job: job.to_enqueue_params,
+        paused:,
+      }.compact #: Zizq::cron_entry_params
+    end
+
+    private
+
+    # @rbs result: Zizq::Resources::CronEntry
+    # @rbs return: self
+    def materialize_with(result)
+      @expression = result.expression
+      @timezone = result.timezone
+      @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
+      @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
+  end
+end

data/lib/zizq/crontab_entry_builder.rb

@@ -0,0 +1,133 @@
+# Copyright (c) 2026 Chris Corbyn <chris@zizq.io>
+# Licensed under the MIT License. See LICENSE file for details.
+
+# rbs_inline: enabled
+# frozen_string_literal: true
+
+module Zizq
+  # Builder class used to define individual entries within a Crontab schedule.
+  #
+  # This is used internally by `Zizq.define_crontab`. See documentation for
+  # that method for full details.
+  #
+  # Callers *must* call one of the enqueue methods to complete the build
+  # process.
+  class CrontabEntryBuilder
+    # The Crontab instance onto which entries are applied.
+    attr_reader :target #: Zizq::Crontab
+
+    # The name of the entry being built.
+    attr_reader :name #: String
+
+    # The cron expression for the entry.
+    attr_reader :expression #: String
+
+    # Optional timezone for the entry.
+    #
+    # Defaults to the Zizq server timezone when not specified.
+    attr_reader :timezone #: String?
+
+    # True if this entry will be paused.
+    attr_reader :paused #: bool?
+
+    # Callback through which the built entry is passed before being added to
+    # the Crontab schedule.
+    #
+    # The callback receives the Zizq::CrontabEntry instance and may return an
+    # alternative instance to be used after it has done any processing on the
+    # entry.
+    attr_reader :callback #: ^(Zizq::CrontabEntry) -> Zizq::CrontabEntry
+
+    # Initialize the builder with the given inputs.
+    #
+    # @rbs target: Zizq::Crontab
+    # @rbs name: String
+    # @rbs expression: String
+    # @rbs timezone: String?
+    # @rbs paused: bool?
+    # @rbs ?&block: (Zizq::CrontabEntry) -> Zizq::CrontabEntry
+    def initialize(target,
+                   name,
+                   expression,
+                   timezone: nil,
+                   paused: nil,
+                   &block)
+      @target = target
+      @name = name
+      @expression = expression
+      @timezone = timezone
+      @paused = paused
+      @callback = block || :itself.to_proc
+    end
+
+    # Enqueue a Zizq::Job or ActiveJob class using Zizq::ActiveJobConfig via
+    # this entry.
+    #
+    # @rbs job_class: Class & Zizq::JobConfig
+    # @rbs args: Array[untyped]
+    # @rbs kwargs: Hash[Symbol, untyped]
+    # @rbs &block: ?(EnqueueRequest) -> void
+    # @rbs return: void
+    def enqueue(job_class, *args, **kwargs, &block)
+      push_entry(Zizq.build_enqueue_request(job_class, *args, **kwargs, &block))
+    end
+
+    # Process a raw job enqueue for this entry.
+    #
+    # This is used for low-level or cross-language support.
+    #
+    # @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 return: void
+    def enqueue_raw(queue:, type:, payload:, **opts)
+      push_entry(EnqueueRequest.new(queue:, type:, payload:, **opts))
+    end
+
+    # Bulk enqueues are not supported via cron.
+    #
+    # @rbs &block: (BulkEnqueue) -> void
+    # @rbs return: self
+    def enqueue_bulk(&block)
+      raise NotImplementedError, 'bulk enqueues are not supported via cron'
+    end
+
+    # Provide common fields to be used when enqueueing a job.
+    #
+    # @rbs overrides: Hash[Symbol, untyped]
+    # @rbs return: EnqueueWith
+    def enqueue_with(**overrides)
+      EnqueueWith.new(self, overrides)
+    end
+
+    private
+
+    # @rbs job: EnqueueRequest
+    # @rbs return: untyped
+    def push_entry(req)
+      if req.ready_at || req.delay
+        raise ArgumentError, 'delayed job are not permitted via cron'
+      end
+
+      entry = callback.call(
+        CrontabEntry.new(
+          target,
+          name,
+          expression,
+          job: req,
+          timezone:,
+          paused:,
+        ),
+      )
+
+      target.entries[entry.name] = entry
+    end
+  end
+end

data/lib/zizq/enqueue_with.rb

@@ -68,7 +68,7 @@ module Zizq
     # Enqueue a job class via the underlying target, applying the scoped
     # overrides before invoking any caller-supplied block.
     #
-    # @rbs job_class: Class & Zizq::job_class
+    # @rbs job_class: Class & Zizq::JobConfig
     # @rbs args: Array[untyped]
     # @rbs kwargs: Hash[Symbol, untyped]
     # @rbs &block: ?(EnqueueRequest) -> void

data/lib/zizq/job.rb

@@ -46,11 +46,15 @@ module Zizq
     def self.call(job)
       job_class = Object.const_get(job.type)
 
-      unless job_class.is_a?(Class) && job_class.include?(Zizq::Job)
+      unless (
+          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
 
-      zizq_job_class = job_class #: Zizq::job_class
+      zizq_job_class = job_class #: (Class & Zizq::JobConfig & Zizq::job_class)
       instance = zizq_job_class.new
       instance.set_zizq_job(job)
 

data/lib/zizq/query.rb

@@ -161,7 +161,7 @@ module Zizq
     # Sets the type filter to the class name and adds a jq payload filter
     # for an exact match of the serialized arguments.
     #
-    # @rbs job_class: Zizq::job_class
+    # @rbs job_class: Class && Zizq::JobConfig
     # @rbs *args: untyped
     # @rbs **kwargs: untyped
     # @rbs return: Query
@@ -179,7 +179,7 @@ module Zizq
     # The job class must include `Zizq::Job` or for Active Job classes must
     # extend `Zizq::ActiveJobConfig`.
     #
-    # @rbs job_class: Zizq::job_class
+    # @rbs job_class: Class & Zizq::JobConfig
     # @rbs *args: untyped
     # @rbs **kwargs: untyped
     # @rbs return: Query

data/lib/zizq/resources/cron_entry.rb

@@ -0,0 +1,27 @@
+# Copyright (c) 2026 Chris Corbyn <chris@zizq.io>
+# Licensed under the MIT License. See LICENSE file for details.
+
+# rbs_inline: enabled
+# frozen_string_literal: true
+
+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 next_enqueue_at = ms_to_seconds(@data["next_enqueue_at"]) #: () -> Float?
+      def last_enqueue_at = ms_to_seconds(@data["last_enqueue_at"]) #: () -> Float?
+
+      # Returns the job template for this entry.
+      def job #: () -> JobTemplate
+        JobTemplate.new(client, @data["job"])
+      end
+    end
+  end
+end

data/lib/zizq/resources/cron_group.rb

@@ -0,0 +1,23 @@
+# Copyright (c) 2026 Chris Corbyn <chris@zizq.io>
+# Licensed under the MIT License. See LICENSE file for details.
+
+# rbs_inline: enabled
+# frozen_string_literal: true
+
+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?
+
+      # Returns the entries in this group as typed resources.
+      def entries #: () -> Array[CronEntry]
+        (@data["entries"] || []).map { |e| CronEntry.new(client, e) }
+      end
+    end
+  end
+end

data/lib/zizq/resources/job.rb

@@ -8,51 +8,19 @@ module Zizq
   module Resources
     # Typed wrapper around a job response hash.
     #
-    # Exposes named accessor methods with Ruby-idiomatic types (fractional
-    # seconds instead of milliseconds) and link methods that follow related
-    # resources through the Client.
-    class Job < Resource
+    # Inherits template fields (type, queue, priority, payload, backoff,
+    # retention, unique_key, unique_while) from JobTemplate and adds
+    # lifecycle fields and action methods.
+    class Job < JobTemplate
       def id          = @data["id"]          #: () -> String
-      def type        = @data["type"]        #: () -> String
-      def queue       = @data["queue"]       #: () -> String
-      def priority    = @data["priority"]    #: () -> Integer
       def status      = @data["status"]      #: () -> String
       def ready_at    = ms_to_seconds(@data["ready_at"])    #: () -> Float?
       def attempts    = @data["attempts"]    #: () -> Integer
-      def payload     = @data["payload"]     #: () -> Hash[String, untyped]?
       def dequeued_at = ms_to_seconds(@data["dequeued_at"]) #: () -> Float?
       def failed_at     = ms_to_seconds(@data["failed_at"])     #: () -> Float?
       def completed_at  = ms_to_seconds(@data["completed_at"])  #: () -> Float?
-      def retry_limit   = @data["retry_limit"] #: () -> Integer?
-      def unique_key    = @data["unique_key"]  #: () -> String?
-      def unique_while  = @data["unique_while"]&.to_sym #: () -> Zizq::unique_scope?
       def duplicate?    = @data["duplicate"] == true #: () -> bool
 
-      # Backoff configuration converted from the wire format (ms) to the
-      # Ruby-idiomatic format (seconds), matching the Zizq::backoff type.
-      def backoff #: () -> Zizq::backoff?
-        raw = @data["backoff"]
-        return nil unless raw
-
-        {
-          exponent: raw["exponent"].to_f,
-          base: raw["base_ms"] / 1000.0,
-          jitter: raw["jitter_ms"] / 1000.0
-        }
-      end
-
-      # Retention configuration converted from the wire format (ms) to the
-      # Ruby-idiomatic format (seconds), matching the Zizq::retention type.
-      def retention #: () -> Zizq::retention?
-        raw = @data["retention"]
-        return nil unless raw
-
-        result = {} #: Hash[Symbol, Float]
-        result[:completed] = raw["completed_ms"] / 1000.0 if raw["completed_ms"]
-        result[:dead] = raw["dead_ms"] / 1000.0 if raw["dead_ms"]
-        result
-      end
-
       # Fetch the error history for this job.
       #
       # @rbs order: Zizq::sort_direction?

data/lib/zizq/resources/job_template.rb

@@ -0,0 +1,46 @@
+# Copyright (c) 2026 Chris Corbyn <chris@zizq.io>
+# Licensed under the MIT License. See LICENSE file for details.
+
+# rbs_inline: enabled
+# frozen_string_literal: true
+
+module Zizq
+  module Resources
+    # Typed wrapper around a job template — the fields shared between
+    # live jobs and cron entry job definitions.
+    class JobTemplate < Resource
+      def type         = @data["type"]         #: () -> String
+      def queue        = @data["queue"]        #: () -> String
+      def priority     = @data["priority"]     #: () -> Integer?
+      def payload      = @data["payload"]      #: () -> Hash[String, untyped]?
+      def retry_limit  = @data["retry_limit"]  #: () -> Integer?
+      def unique_key   = @data["unique_key"]   #: () -> String?
+      def unique_while = @data["unique_while"]&.to_sym #: () -> Zizq::unique_scope?
+
+      # Backoff configuration converted from the wire format (ms) to the
+      # Ruby-idiomatic format (seconds), matching the Zizq::backoff type.
+      def backoff #: () -> Zizq::backoff?
+        raw = @data["backoff"]
+        return nil unless raw
+
+        {
+          exponent: raw["exponent"].to_f,
+          base: raw["base_ms"] / 1000.0,
+          jitter: raw["jitter_ms"] / 1000.0
+        }
+      end
+
+      # Retention configuration converted from the wire format (ms) to the
+      # Ruby-idiomatic format (seconds), matching the Zizq::retention type.
+      def retention #: () -> Zizq::retention?
+        raw = @data["retention"]
+        return nil unless raw
+
+        result = {} #: Hash[Symbol, Float]
+        result[:completed] = raw["completed_ms"] / 1000.0 if raw["completed_ms"]
+        result[:dead] = raw["dead_ms"] / 1000.0 if raw["dead_ms"]
+        result
+      end
+    end
+  end
+end

data/lib/zizq/resources.rb

@@ -6,11 +6,14 @@
 module Zizq
   module Resources
     autoload :Resource,        "zizq/resources/resource"
+    autoload :JobTemplate,     "zizq/resources/job_template"
     autoload :Job,             "zizq/resources/job"
     autoload :ErrorRecord,     "zizq/resources/error_record"
     autoload :Page,            "zizq/resources/page"
     autoload :JobPage,         "zizq/resources/job_page"
     autoload :ErrorPage,       "zizq/resources/error_page"
     autoload :ErrorEnumerator, "zizq/resources/error_enumerator"
+    autoload :CronGroup,       "zizq/resources/cron_group"
+    autoload :CronEntry,       "zizq/resources/cron_entry"
   end
 end

data/lib/zizq/version.rb

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