zizq 0.2.1 → 0.3.1

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.1" #: String
 end

data/lib/zizq.rb

@@ -12,20 +12,24 @@ require_relative "zizq/configuration"
 autoload :MessagePack, "msgpack"
 
 module Zizq
-  autoload :AckProcessor,    "zizq/ack_processor"
-  autoload :ActiveJobConfig, "zizq/active_job_config"
-  autoload :Backoff,         "zizq/backoff"
-  autoload :BulkEnqueue,     "zizq/bulk_enqueue"
-  autoload :Client,          "zizq/client"
-  autoload :EnqueueRequest,  "zizq/enqueue_request"
-  autoload :EnqueueWith,     "zizq/enqueue_with"
-  autoload :Job,             "zizq/job"
-  autoload :JobConfig,       "zizq/job_config"
-  autoload :Middleware,      "zizq/middleware"
-  autoload :Lifecycle,       "zizq/lifecycle"
-  autoload :Query,           "zizq/query"
-  autoload :Resources,       "zizq/resources"
-  autoload :Worker,          "zizq/worker"
+  autoload :AckProcessor,        "zizq/ack_processor"
+  autoload :ActiveJobConfig,     "zizq/active_job_config"
+  autoload :Backoff,             "zizq/backoff"
+  autoload :BulkEnqueue,         "zizq/bulk_enqueue"
+  autoload :Client,              "zizq/client"
+  autoload :Crontab,             "zizq/crontab"
+  autoload :CrontabBuilder,      "zizq/crontab_builder"
+  autoload :CrontabEntry,        "zizq/crontab_entry"
+  autoload :CrontabEntryBuilder, "zizq/crontab_entry_builder"
+  autoload :EnqueueRequest,      "zizq/enqueue_request"
+  autoload :EnqueueWith,         "zizq/enqueue_with"
+  autoload :Job,                 "zizq/job"
+  autoload :JobConfig,           "zizq/job_config"
+  autoload :Middleware,          "zizq/middleware"
+  autoload :Lifecycle,           "zizq/lifecycle"
+  autoload :Query,               "zizq/query"
+  autoload :Resources,           "zizq/resources"
+  autoload :Worker,              "zizq/worker"
 
   # Sentinel indicating a field should not be included in the request.
   # Used as the default for update parameters.
@@ -59,7 +63,9 @@ module Zizq
     def configure #: () { (Configuration) -> void } -> void
       yield configuration
     ensure
-      @client = nil # shared client is potentially stale
+      # shared client is potentially stale
+      @client&.close
+      @client = nil
     end
 
     # Returns a shared client instance built from the global configuration.
@@ -75,7 +81,9 @@ module Zizq
           @client = Client.new(
             url: configuration.url,
             format: configuration.format,
-            ssl_context: configuration.ssl_context
+            ssl_context: configuration.ssl_context,
+            read_timeout: configuration.read_timeout,
+            stream_idle_timeout: configuration.stream_idle_timeout
           )
         end
       end
@@ -114,6 +122,88 @@ module Zizq
       Query.new(...)
     end
 
+    # Return a list of all available Crontab schedules.
+    def crontabs #: () -> Array[String]
+      Zizq.client.list_cron_groups
+    end
+
+    # Define (or redefine) a Crontab schedule.
+    #
+    # This requires a Pro license on the Zizq server.
+    #
+    # 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.
+    #
+    # This is designed to be idempotent. You can define a schedule somewhere in
+    # your application startup process (after `Zizq.configure`) and it doesn't
+    # matter if multiple process all define the same schedule. Zizq is smart
+    # enough to handle this correctly.
+    #
+    # 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.
+    #
+    # This method sends exactly *one* request to the Zizq server upon
+    # completion of the block. Any existing entries are retained. Any new
+    # entries are added, any absent entries are removed, and any modified
+    # entries are replaced. In short, whatever the block defines is what the
+    # entire resulting Crontab schedule will look like.
+    #
+    #   Zizq.define_crontab("example", timezone: "Europe/Rome") do |cron|
+    #     cron.define_entry(
+    #       "refresh_data_warehose",
+    #       "*/15 * * * *"
+    #     ).enqueue(RefreshDataWarehoseJob, incremental: true)
+    #
+    #     cron.define_entry(
+    #       "expire_acess_tokens",
+    #       "*/10 * * * * *"
+    #     ).enqueue_raw(
+    #       queue: "identity-server",
+    #       type: "expire_access_tokens",
+    #       priority: 100,
+    #       payload: {},
+    #     )
+    #   end
+    #
+    # When jobs are pushed to the queue at their execution time, Zizq handles
+    # this atomically, so there is no risk of a duplicate enqueue for the same
+    # schedule tick. However, if you have long-running jobs that should not be
+    # permitted to overlap, such as in the case your schedule runs every 10
+    # seconds but jobs can take 30 seconds to execute, you should consider
+    # using unique jobs.
+    #
+    # @rbs name: String
+    # @rbs timezone: String?
+    # @rbs paused: bool?
+    # @rbs &block: (Zizq::CrontabBuilder) -> void
+    # @rbs return: Zizq::Crontab
+    def define_crontab(name, timezone: nil, paused: nil, &block)
+      crontab = Crontab.new(name)
+      crontab.redefine(timezone:, paused:, &block)
+      crontab
+    end
+
+    # Obtain a handle for the given Crontab schedule.
+    #
+    # This is a lazy operation. The schedule data is only fetched from the Zizq
+    # server upon first accessing data within the schedule.
+    #
+    #   Zizq.crontab("default").paused?
+    #   Zizq.crontab("default").resume!
+    #
+    # @rbs name: String
+    # @rbs return: Zizq::Crontab
+    def crontab(name)
+      Crontab.new(name)
+    end
+
     # Enqueue a job by class with positional and keyword arguments.
     #
     # By default all arguments are serialized as JSON, which means hashes with
@@ -149,7 +239,7 @@ module Zizq
     #     end
     #   end
     #
-    # @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
@@ -247,7 +337,7 @@ module Zizq
     # @api private
     # Build an EnqueueRequest for a single job class enqueue.
     #
-    # @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
@@ -257,7 +347,7 @@ module Zizq
         raise ArgumentError, "#{job_class.inspect} must include Zizq::Job or extend Zizq::ActiveJobConfig"
       end
 
-      zizq_job_class = job_class #: Zizq::job_class
+      zizq_job_class = job_class #: Zizq::JobConfig
       req = zizq_job_class.zizq_enqueue_request(*args, **kwargs)
       yield req if block_given?
       req

data/sig/generated/zizq/bulk_enqueue.rbs

@@ -16,12 +16,12 @@ module Zizq
     # Collect a job class enqueue. Accepts the same arguments as
     # `Zizq.enqueue`.
     #
-    # @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
     # @rbs return: void
-    def enqueue: (Class & Zizq::job_class job_class, *untyped args, **untyped kwargs) ?{ (EnqueueRequest) -> void } -> void
+    def enqueue: (Class & Zizq::JobConfig job_class, *untyped args, **untyped kwargs) ?{ (EnqueueRequest) -> void } -> void
 
     # Collect a raw enqueue. Accepts the same arguments as
     # `Zizq.enqueue_raw`.

data/sig/generated/zizq/client.rbs

@@ -42,11 +42,19 @@ module Zizq
     # Initialize a new instance of the client with the given base URL and
     # optional format options.
     #
+    # `read_timeout` and `stream_idle_timeout` are per-operation socket
+    # I/O timeouts (seconds). Each individual socket read/write is
+    # bounded by the timeout. The streaming `#take_jobs` endpoint uses
+    # `stream_idle_timeout` because the server sends heartbeats at
+    # periodic intervals which keeps the connection alive.
+    #
     # @rbs url: String
     # @rbs format: Zizq::format
     # @rbs ssl_context: OpenSSL::SSL::SSLContext?
+    # @rbs read_timeout: Numeric
+    # @rbs stream_idle_timeout: Numeric
     # @rbs return: void
-    def initialize: (url: String, ?format: Zizq::format, ?ssl_context: OpenSSL::SSL::SSLContext?) -> void
+    def initialize: (url: String, ?format: Zizq::format, ?ssl_context: OpenSSL::SSL::SSLContext?, ?read_timeout: Numeric, ?stream_idle_timeout: Numeric) -> void
 
     # Close all thread-local HTTP clients and release connections.
     def close: () -> untyped
@@ -196,6 +204,90 @@ module Zizq
     # List all distinct queue names on the server.
     def get_queues: () -> untyped
 
+    # List all cron group names.
+    #
+    # @rbs return: Array[String]
+    def list_cron_groups: () -> Array[String]
+
+    # Fetch a cron group and all its entries.
+    #
+    # @rbs name: String
+    # @rbs return: Resources::CronGroup
+    def get_cron_group: (String name) -> Resources::CronGroup
+
+    # Create or replace an entire cron group.
+    #
+    # Entries not present in the request are removed. Entries with unchanged
+    # expressions preserve their scheduling state.
+    #
+    # @rbs name: String
+    # @rbs paused: bool?
+    # @rbs entries: Array[Zizq::cron_entry_params]
+    # @rbs return: Resources::CronGroup
+    def replace_cron_group: (String name, ?paused: bool?, ?entries: Array[Zizq::cron_entry_params]) -> Resources::CronGroup
+
+    # Update group-level fields (currently just pause/unpause).
+    #
+    # @rbs name: String
+    # @rbs paused: bool?
+    # @rbs return: Resources::CronGroup
+    def update_cron_group: (String name, ?paused: bool?) -> Resources::CronGroup
+
+    # Delete a cron group and all its entries.
+    #
+    # @rbs name: String
+    # @rbs return: void
+    def delete_cron_group: (String name) -> void
+
+    # Fetch a single cron entry.
+    #
+    # @rbs group: String
+    # @rbs entry: String
+    # @rbs return: Resources::CronEntry
+    def get_cron_group_entry: (String group, String entry) -> Resources::CronEntry
+
+    # Add a single entry to a cron group (creates the group if needed).
+    #
+    # Raises a ClientError (409 Conflict) if an entry with the same name
+    # already exists.
+    #
+    # @rbs group: String
+    # @rbs name: String
+    # @rbs expression: String
+    # @rbs job: Zizq::cron_job_params
+    # @rbs timezone: String?
+    # @rbs paused: bool?
+    # @rbs return: Resources::CronEntry
+    def add_cron_group_entry: (String group, name: String, expression: String, job: Zizq::cron_job_params, ?timezone: String?, ?paused: bool?) -> Resources::CronEntry
+
+    # Create or replace a single cron entry.
+    #
+    # Preserves scheduling state if the expression is unchanged.
+    #
+    # @rbs group: String
+    # @rbs entry: String
+    # @rbs expression: String
+    # @rbs job: Zizq::cron_job_params
+    # @rbs timezone: String?
+    # @rbs paused: bool?
+    # @rbs return: Resources::CronEntry
+    def replace_cron_group_entry: (String group, String entry, expression: String, job: Zizq::cron_job_params, ?timezone: String?, ?paused: bool?) -> Resources::CronEntry
+
+    # Update entry-level fields (currently just pause/unpause).
+    #
+    # @rbs group: String
+    # @rbs entry: String
+    # @rbs paused: bool
+    # @rbs return: Resources::CronEntry
+    def update_cron_group_entry: (String group, String entry, paused: bool) -> Resources::CronEntry
+
+    # Delete a single cron entry.
+    #
+    # @rbs group: String
+    # @rbs entry: String
+    # @rbs return: void
+    def delete_cron_group_entry: (String group, String entry) -> void
+
     # Mark a job as successfully completed (ack).
     #
     # If this method (or [`#report_failure`]) is not called upon job
@@ -330,9 +422,38 @@ module Zizq
 
     private
 
+    # URL-encode a single path segment.
+    def enc: (untyped value) -> untyped
+
     # Build a relative path with optional query parameters.
     def build_path: (untyped path, ?params: untyped) -> untyped
 
+    # Validate and build a cron entry body from keyword arguments.
+    #
+    # @rbs name: String
+    # @rbs expression: String
+    # @rbs job: Zizq::cron_job_params
+    # @rbs timezone: String?
+    # @rbs paused: bool?
+    # @rbs return: Hash[Symbol, untyped]
+    def build_cron_entry: (?name: String, ?expression: String, ?job: Zizq::cron_job_params, ?timezone: String?, ?paused: bool?) -> Hash[Symbol, untyped]
+
+    # Validate and build a cron job template from keyword arguments.
+    #
+    # Uses keyword args so that unknown keys raise ArgumentError.
+    #
+    # @rbs type: String
+    # @rbs queue: String
+    # @rbs payload: untyped
+    # @rbs priority: Integer?
+    # @rbs retry_limit: Integer?
+    # @rbs backoff: Zizq::backoff?
+    # @rbs retention: Zizq::retention?
+    # @rbs unique_key: String?
+    # @rbs unique_while: Zizq::unique_scope?
+    # @rbs return: Hash[Symbol, untyped]
+    def build_cron_job: (?type: String, ?queue: String, ?payload: untyped, ?priority: Integer?, ?retry_limit: Integer?, ?backoff: Zizq::backoff?, ?retention: Zizq::retention?, ?unique_key: String?, ?unique_while: Zizq::unique_scope?) -> Hash[Symbol, untyped]
+
     # Validate and normalize filter parameters for bulk operations.
     #
     # Uses keyword arguments so that unknown keys raise ArgumentError.
@@ -419,6 +540,8 @@ module Zizq
 
     def raw_post: (untyped path) -> untyped
 
+    def put: (untyped path, untyped body) -> untyped
+
     def delete: (untyped path, ?params: untyped) -> untyped
 
     def patch: (untyped path, untyped body, ?params: untyped) -> untyped

data/sig/generated/zizq/configuration.rbs

@@ -35,6 +35,27 @@ module Zizq
     # Note: Mutual TLS support requires a Zizq Pro license on the server.
     attr_accessor tls: Zizq::tls_options?
 
+    # Per-operation socket I/O timeout (seconds) for regular API calls
+    # (enqueue, queries, mutations). Each socket read/write is bounded
+    # by this value. A request whose handshake or any single read exceeds
+    # this raises `IO::TimeoutError`.
+    #
+    # Default: 30.
+    attr_accessor read_timeout: Numeric
+
+    # Per-operation socket I/O timeout (seconds) for the long-lived
+    # `#take_jobs` stream. The server sends heartbeats every ~3 seconds,
+    # so each read returns within that window and keeps the connection
+    # alive; the connection only times out if the server falls silent for
+    # longer than this. The Worker catches the resulting error and
+    # reconnects with backoff.
+    #
+    # Should be comfortably above the server's heartbeat interval to
+    # avoid false-positive disconnects.
+    #
+    # Default: 30.
+    attr_accessor stream_idle_timeout: Numeric
+
     # Middleware chain for enqueue. Each middleware receives an
     # `EnqueueRequest` and a chain to continue.
     attr_reader enqueue_middleware: Middleware::Chain[EnqueueRequest, EnqueueRequest]

data/sig/generated/zizq/crontab.rbs

@@ -0,0 +1,141 @@
+# Generated from lib/zizq/crontab.rb with RBS::Inline
+
+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: (String name) -> untyped
+
+    # 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: () -> untyped
+
+    # Clear materialized data that was fetched from the Zizq server.
+    #
+    # This triggers a refetch when the data is next accessed.
+    def clear: () -> untyped
+
+    # Delete this entire Crontab schedule and its entries.
+    def delete!: () -> untyped
+
+    # 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!: () -> untyped
+
+    # Resume this Crontab schedule if it is currently paused.
+    #
+    # Individual entries that are paused will remain paused.
+    def resume!: () -> untyped
+
+    # Check if this schedule is currently paused.
+    def paused: () -> untyped
+
+    # Check if this schedule is currently paused.
+    #
+    # Alias of #paused.
+    def paused?: () -> untyped
+
+    # Return the timestamp at which this Crontab schedule was last paused.
+    def paused_at: () -> untyped
+
+    # Return the timestamp at which this Crontab schedule was last resumed.
+    def resumed_at: () -> untyped
+
+    # 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: () -> untyped
+
+    # 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: untyped, ?paused: untyped) { (Zizq::CrontabBuilder) -> void } -> self
+
+    # 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: (String name) -> Zizq::CrontabEntry
+
+    # 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: (String name, String expression, ?timezone: String?, ?paused: bool?) -> Zizq::CrontabEntryBuilder
+
+    private
+
+    # @rbs result: Zizq::Resources::CronGroup
+    # @rbs return: self
+    def materialize_with: (Zizq::Resources::CronGroup result) -> self
+
+    # @rbs result: Zizq::Resources::CronEntry
+    # @rbs return: Zizq::CrontabEntry
+    def materialize_entry_with: (Zizq::Resources::CronEntry result) -> Zizq::CrontabEntry
+  end
+end