zizq 0.2.0 → 0.3.0

data/lib/zizq/crontab.rb

@@ -0,0 +1,263 @@
+# 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 Crontab schedule defined on the Zizq server.
+  #
+  # This requires a Pro license on the Zizq server.
+  #
+  # The actual data is lazily fetched when first accessed.
+  #
+  # Crontabs are used to define collections of recurring jobs that run on a
+  # specified schedule, such as at 2am on every Monday. Each entry on the
+  # Crontab is a single job enqueue, which the Zizq server automatically
+  # triggers at the correct point in time. Zizq uses standard Cron expression
+  # syntax (with support for seconds via 6-fields) to define entries.
+  #
+  # Entire schedules, and individual entries on a schedule, can be paused and
+  # resumed.
+  #
+  # By default schedules operate in the system time zone of the Zizq server
+  # but an explicit IANA timezone name can be specified when defining the
+  # Crontab.
+  class Crontab
+    # The name of the cron group that this schedule is backed by.
+    attr_reader :name #: String
+
+    # True if this schedule is paused.
+    #
+    # When paused, the scheduler continues to run but does not enqueue any jobs
+    # and only advances the timer.
+    attr_writer :paused #: bool?
+
+    # Initialize the Crontab with the given group name.
+    #
+    # @rbs name: String
+    def initialize(name)
+      @building = false #: bool
+      @materialized = false #: bool
+      @name = name #: String
+      @entries = {} #: Hash[String, Zizq::CrontabEntry]
+      @paused = false #: bool?
+      @paused_at = nil #: Float?
+      @resumed_at = nil #: Float?
+    end
+
+    # Fetch data from the Zizq server if not already fetched.
+    #
+    # Once fetched, this method becomes a no-op, unless #clear is called to
+    # remove the fetched data.
+    def materialize #: () -> self
+      unless @building || @materialized
+        materialize_with(Zizq.client.get_cron_group(name))
+      end
+
+      self
+    end
+
+    # Clear materialized data that was fetched from the Zizq server.
+    #
+    # This triggers a refetch when the data is next accessed.
+    def clear #: () -> self
+      @entries = {}
+      @paused = nil
+      @paused_at = nil
+      @resumed_at = nil
+      @materialized = false
+
+      self
+    end
+
+    # Delete this entire Crontab schedule and its entries.
+    def delete! #: () -> void
+      Zizq.client.delete_cron_group(name)
+    end
+
+    # Pause this entire Crontab schedule.
+    #
+    # All entries will stop enqueueing jobs, but the server continues to
+    # advance the schedule until it is resumed.
+    def pause! #: () -> void
+      materialize_with(Zizq.client.update_cron_group(name, paused: true))
+    end
+
+    # Resume this Crontab schedule if it is currently paused.
+    #
+    # Individual entries that are paused will remain paused.
+    def resume! #: () -> void
+      materialize_with(Zizq.client.update_cron_group(name, paused: false))
+    end
+
+    # Check if this schedule is currently paused.
+    def paused #: () -> bool?
+      materialize
+      @paused
+    end
+
+    # Check if this schedule is currently paused.
+    #
+    # Alias of #paused.
+    def paused? = paused #: () -> bool?
+
+    # Return the timestamp at which this Crontab schedule was last paused.
+    def paused_at #: () -> Float?
+      materialize
+      @paused_at
+    end
+
+    # Return the timestamp at which this Crontab schedule was last resumed.
+    def resumed_at #: () -> Float?
+      materialize
+      @resumed_at
+    end
+
+    # Return a Hash of Zizq::CrontabEntry instances keyed by their names.
+    #
+    # 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.
+    def entries #: () -> Hash[String, Zizq::CrontabEntry]
+      materialize
+      @entries
+    end
+
+    # Redefine (replace) this Crontab schedule with another.
+    #
+    # This is equivalent to calling `Zizq.define_crontab` and is idempotent
+    # when given the same schedule more than once.
+    #
+    # @rbs ?timezone: String?
+    # @rbs ?paused: bool?
+    # @rbs &block: (Zizq::CrontabBuilder) -> void
+    # @rbs return: self
+    def redefine(timezone: nil, paused: nil, &block)
+      @building = true
+
+      yield CrontabBuilder.new(self, timezone:, paused:)
+
+      materialize_with(
+        Zizq.client.replace_cron_group(
+          name,
+          paused:,
+          entries: entries.values.map(&:to_params),
+        ),
+      )
+
+      @building = false
+
+      self
+    end
+
+    # Return a handle for the specified Zizq::CrontabEntry.
+    #
+    # The entry can be paused or resumed is isolation, can be deleted entirely
+    # or can be redefined (replaced) with another entry.
+    #
+    # @rbs name: String
+    # @rbs return: Zizq::CrontabEntry
+    def entry(name)
+      materialize
+      entries.fetch(name) do
+        entry = materialize_entry_with(
+          Zizq.client.get_cron_group_entry(self.name, name),
+        )
+        entries[name] = entry
+      end
+    end
+
+    # Define (or redefine) an entry with this Crontab schedule.
+    #
+    # Defining the same entry more than once is idempotent. If the entry does
+    # not exist, it is added to the schedule. If the entry already exists, it
+    # replaces the current entry.
+    #
+    # The return value is a Zizq::CrontabEntryBuilder instance, on which the
+    # caller must call one of the enqueue methods (`enqueue`, `enqueue_raw`,
+    # optionally chained onto `enqueue_with`, exactly the same as a regular job
+    # enqueue).
+    #
+    # All enqueue options are supported *except* `delay` and `ready_at` which
+    # make no sense for recurring jobs.
+    #
+    # Bulk enqueues are not supported.
+    #
+    #   crontab.define_entry(
+    #     "refresh_data_warehose",
+    #     "*/15 * * * *",
+    #   ).enqueue(RefreshDataWarehoseJob, incremental: true)
+    #
+    # @rbs name: String
+    # @rbs expression: String
+    # @rbs timezone: String?
+    # @rbs paused: bool?
+    # @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,
+          ),
+        )
+
+        materialize # in case this was the first entry operation
+
+        entry
+      end
+    end
+
+    private
+
+    # @rbs result: Zizq::Resources::CronGroup
+    # @rbs return: self
+    def materialize_with(result)
+      @paused = result.paused?
+      @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
+
+      @materialized = true
+
+      self
+    end
+
+    # @rbs result: Zizq::Resources::CronEntry
+    # @rbs return: Zizq::CrontabEntry
+    def materialize_entry_with(result)
+      CrontabEntry.new(
+        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,
+        ),
+        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,
+      )
+    end
+  end
+end

data/lib/zizq/crontab_builder.rb

@@ -0,0 +1,52 @@
+# 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 used to configure a Zizq::Crontab instance.
+  #
+  # Instances of this class are returned from `Zizq.define_crontab`. See
+  # documentation for that method for usage.
+  class CrontabBuilder
+    # The Crontab instance that this builder configures.
+    attr_reader :target #: Zizq::Crontab
+
+    # Optional timezone to be applied to all entries by default.
+    attr_accessor :timezone #: String?
+
+    # Initialize the builder with the given Crontab instance.
+    #
+    # @rbs target: Zizq::Crontab
+    # @rbs timezone: String?
+    # @rbs paused: bool?
+    def initialize(target, timezone: nil, paused: nil)
+      @target = target.clear
+      @timezone = timezone
+
+      target.paused = paused
+    end
+
+    # Add or replace an entry on the schedule
+    #
+    # If no entry with the given name exists, it is added to schedule. If an
+    # entry with the same name exist, this entry replaces that entry. If the
+    # entry is the same as the original, the result is idempotent.
+    #
+    # @rbs name: String
+    # @rbs expression: String
+    # @rbs timezone: String?
+    # @rbs paused: bool?
+    # @rbs return: Zizq::CrontabEntryBuilder
+    def define_entry(name, expression, timezone: self.timezone, paused: nil)
+      CrontabEntryBuilder.new(
+        target,
+        name,
+        expression,
+        timezone:,
+        paused:,
+      )
+    end
+  end
+end

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