zizq 0.2.1 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: de36f4f8204a5d5b0c64e77b78249ed34ea6c667ceb6b03dbdca2a291cb0f330
-  data.tar.gz: 7cbb62aac1788627bb1047b474e5ca915c5dca059bc6f00be7a2f5adca798a7a
+  metadata.gz: a94a61282aba9442ace4ca8a3a302f75a843b14a76bd7d7748f006d5c8bf0888
+  data.tar.gz: 202f0842b2a2b22d8fce753c197635ea456ac94955f6f266f806471d01d06a7f
 SHA512:
-  metadata.gz: 95b80cec6e0bb1704bd1244b37c4434b5d5467139e35c61bae39f342825a3e136a413aa55c0a0b7de379024bcdee3486e08cb211062a9d406011093a68de2899
-  data.tar.gz: '09952b2563e139e9987473b53524ea993f1c803ea0320082c166132053919f3401cad65c8dc063923837c3b1fe8a505e3e27dcd9ce6a20724313c1d6f82c00e3'
+  metadata.gz: 03cb04925c7aac0aaaee30f86e27448641ec4864b903bedeee83cd61b0d0ed803655dd69c8ed586c4b83faa3d8d910c13c589398ca3157f130c569fa3edce5e9
+  data.tar.gz: b3a2c1232195698681ae743e04db5aff883c4e82e36bab9d1735b7459c7db5fdbcb9829171fa30318cec4ac01dc34432a79c2760824f4d2db93c89fbda12da58

data/README.md

@@ -18,9 +18,28 @@ This is the official Zizq client library for Ruby.
 * Scheduled jobs
 * Configurable backoff policies
 * Configurable job retention policies
+* Recurring jobs (cron)
 * Job introspection and management APIs, with support for `jq` query filters
 * Unique jobs
 
+## Installation
+
+> [!NOTE]
+> If you have not yet installed the Zizq server, follow the
+> [Getting Started](https://zizq.io/docs/getting-started) guide first.
+
+Add it to your application's `Gemfile`.
+
+``` ruby
+gem 'zizq', '~> 0.3.0'
+```
+
+Or install it manually:
+
+```shell
+$ gem install zizq -v 0.3.0
+```
+
 ## Example
 
 > [!TIP]

data/lib/zizq/bulk_enqueue.rb

@@ -22,7 +22,7 @@ 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

data/lib/zizq/client.rb

@@ -204,7 +204,7 @@ module Zizq
 
     # Get a single job by ID.
     def get_job(id) #: (String) -> Resources::Job
-      response = get("/jobs/#{id}")
+      response = get("/jobs/#{enc(id)}")
       data = handle_response!(response, expected: 200)
       Resources::Job.new(self, data)
     end
@@ -285,7 +285,7 @@ module Zizq
     # @rbs id: String
     # @rbs return: void
     def delete_job(id)
-      response = delete("/jobs/#{id}")
+      response = delete("/jobs/#{enc(id)}")
       handle_response!(response, expected: [200, 204])
       nil
     end
@@ -342,7 +342,7 @@ module Zizq
         queue:, priority:, ready_at:,
         retry_limit:, backoff:, retention:
       )
-      response = patch("/jobs/#{id}", body)
+      response = patch("/jobs/#{enc(id)}", body)
       data = handle_response!(response, expected: 200)
       Resources::Job.new(self, data)
     end
@@ -383,7 +383,7 @@ module Zizq
     # @rbs attempt: Integer
     # @rbs return: Resources::ErrorRecord
     def get_error(id, attempt:)
-      response = get("/jobs/#{id}/errors/#{attempt}")
+      response = get("/jobs/#{enc(id)}/errors/#{enc(attempt.to_s)}")
       data = handle_response!(response, expected: 200)
       Resources::ErrorRecord.new(self, data)
     end
@@ -397,7 +397,7 @@ module Zizq
     # @rbs return: Resources::ErrorPage
     def list_errors(id, from: nil, order: nil, limit: nil)
       params = { from:, order:, limit: }.compact #: Hash[Symbol, untyped]
-      response = get("/jobs/#{id}/errors", params:)
+      response = get("/jobs/#{enc(id)}/errors", params:)
       data = handle_response!(response, expected: 200)
       Resources::ErrorPage.new(self, data)
     end
@@ -422,6 +422,136 @@ module Zizq
       data["queues"]
     end
 
+    # List all cron group names.
+    #
+    # @rbs return: Array[String]
+    def list_cron_groups
+      response = get("/crons")
+      data = handle_response!(response, expected: 200)
+      data["crons"]
+    end
+
+    # Fetch a cron group and all its entries.
+    #
+    # @rbs name: String
+    # @rbs return: Resources::CronGroup
+    def get_cron_group(name)
+      response = get("/crons/#{enc(name)}")
+      data = handle_response!(response, expected: 200)
+      Resources::CronGroup.new(self, data)
+    end
+
+    # 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(name, paused: nil, entries: [])
+      body = {
+        paused:,
+        entries: entries.map { |entry| build_cron_entry(**entry) }
+      }.compact
+      response = put("/crons/#{enc(name)}", body)
+      data = handle_response!(response, expected: 200)
+      Resources::CronGroup.new(self, data)
+    end
+
+    # Update group-level fields (currently just pause/unpause).
+    #
+    # @rbs name: String
+    # @rbs paused: bool?
+    # @rbs return: Resources::CronGroup
+    def update_cron_group(name, paused: nil)
+      response = patch("/crons/#{enc(name)}", { paused: }.compact)
+      data = handle_response!(response, expected: 200)
+      Resources::CronGroup.new(self, data)
+    end
+
+    # Delete a cron group and all its entries.
+    #
+    # @rbs name: String
+    # @rbs return: void
+    def delete_cron_group(name)
+      response = delete("/crons/#{enc(name)}")
+      handle_response!(response, expected: 204)
+      nil
+    end
+
+    # Fetch a single cron entry.
+    #
+    # @rbs group: String
+    # @rbs entry: String
+    # @rbs return: Resources::CronEntry
+    def get_cron_group_entry(group, entry)
+      response = get("/crons/#{enc(group)}/entries/#{enc(entry)}")
+      data = handle_response!(response, expected: 200)
+      Resources::CronEntry.new(self, data)
+    end
+
+    # 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(group, name:, expression:, job:, timezone: nil, paused: nil)
+      body = build_cron_entry(name:, expression:, job:, timezone:, paused:)
+      response = post("/crons/#{enc(group)}/entries", body)
+      data = handle_response!(response, expected: 201)
+      Resources::CronEntry.new(self, data)
+    end
+
+    # 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(group, entry, expression:, job:, timezone: nil, paused: nil)
+      body = build_cron_entry(name: entry, expression:, job:, timezone:, paused:)
+      response = put("/crons/#{enc(group)}/entries/#{enc(entry)}", body)
+      data = handle_response!(response, expected: 200)
+      Resources::CronEntry.new(self, data)
+    end
+
+    # 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(group, entry, paused:)
+      response = patch("/crons/#{enc(group)}/entries/#{enc(entry)}", { paused: })
+      data = handle_response!(response, expected: 200)
+      Resources::CronEntry.new(self, data)
+    end
+
+    # Delete a single cron entry.
+    #
+    # @rbs group: String
+    # @rbs entry: String
+    # @rbs return: void
+    def delete_cron_group_entry(group, entry)
+      response = delete("/crons/#{enc(group)}/entries/#{enc(entry)}")
+      handle_response!(response, expected: 204)
+      nil
+    end
+
     # Mark a job as successfully completed (ack).
     #
     # If this method (or [`#report_failure`]) is not called upon job
@@ -439,7 +569,7 @@ module Zizq
     # The Zizq server sends heartbeat messages to connected workers so that
     # it can quickly detect and handle disconnected clients.
     def report_success(id) #: (String) -> nil
-      response = raw_post("/jobs/#{id}/success")
+      response = raw_post("/jobs/#{enc(id)}/success")
       handle_response!(response, expected: 204)
       nil
     end
@@ -503,7 +633,7 @@ module Zizq
       body[:retry_at] = (retry_at * 1000).to_i if retry_at
       body[:kill] = kill if kill
 
-      response = post("/jobs/#{id}/failure", body)
+      response = post("/jobs/#{enc(id)}/failure", body)
       data = handle_response!(response, expected: 200)
       Resources::Job.new(self, data)
     end
@@ -660,6 +790,11 @@ module Zizq
 
     private
 
+    # URL-encode a single path segment.
+    def enc(value) #: (String) -> String
+      URI.encode_uri_component(value)
+    end
+
     # Build a relative path with optional query parameters.
     def build_path(path, params: {}) #: (String, ?params: Hash[Symbol, untyped]) -> String
       unless params.empty?
@@ -668,6 +803,57 @@ module Zizq
       path
     end
 
+    # 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: nil, expression: nil, job: nil, timezone: nil, paused: nil)
+      {
+        name:,
+        expression:,
+        timezone:,
+        paused:,
+        job: build_cron_job(**job),
+      }.compact
+    end
+
+    # 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: nil,
+                       queue: nil,
+                       payload: nil,
+                       priority: nil,
+                       retry_limit: nil,
+                       backoff: nil,
+                       retention: nil,
+                       unique_key: nil,
+                       unique_while: nil)
+      job = { type:, queue:, payload: } #: Hash[Symbol, untyped]
+      job[:priority] = priority if priority
+      job[:retry_limit] = retry_limit if retry_limit
+      job[:backoff] = backoff if backoff
+      job[:retention] = retention if retention
+      job[:unique_key] = unique_key if unique_key
+      job[:unique_while] = unique_while.to_s if unique_while
+      job
+    end
+
     # Validate and normalize filter parameters for bulk operations.
     #
     # Uses keyword arguments so that unknown keys raise ArgumentError.
@@ -942,6 +1128,18 @@ module Zizq
       end
     end
 
+    def put(path, body) #: (String, Hash[Symbol, untyped]) -> RawResponse
+      request do |http|
+        consume_response(
+          http.put(
+            build_path(path),
+            {"content-type" => @content_type, "accept" => @content_type},
+            Protocol::HTTP::Body::Buffered.wrap(encode_body(body))
+          )
+        )
+      end
+    end
+
     def delete(path, params: {}) #: (String, ?params: Hash[Symbol, untyped]) -> RawResponse
       request do |http|
         consume_response(

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