zizq 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fb5651af26b76aeb9da0d00636cb1c2f10479c544c52083d16436f46670ba346
-  data.tar.gz: 30b0a1142d96c565d11ef4252f07305e6ef55ac264217a8540975236ae007958
+  metadata.gz: a94a61282aba9442ace4ca8a3a302f75a843b14a76bd7d7748f006d5c8bf0888
+  data.tar.gz: 202f0842b2a2b22d8fce753c197635ea456ac94955f6f266f806471d01d06a7f
 SHA512:
-  metadata.gz: 73d90b0c47f1dcf3452d573829211d69f853b38aca8d0b7e14be74017ac9b802f3faa9151f11ae1fcc0644a574d0b91dc308eec7c8fd560dccf93e1ab31ef321
-  data.tar.gz: '0843a45519c6d0c6256450e242887a08489fdfb84040f6f302ba615118e5dfb9171cc52db1e5407446d0caa4012ff3b136a583f421c19ea3cd0fe6ba92a38371'
+  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/active_job_config.rb

@@ -9,8 +9,9 @@ require_relative "job_config"
 module Zizq
   # Zizq configuration DSL for ActiveJob classes.
   #
-  # Extend this module in an ActiveJob subclass to gain access to Zizq
-  # features like unique jobs, backoff, and retention:
+  # Extend this module in an ActiveJob subclass to allow enqueueing jobs via
+  # `Zizq.enqueue` and to gain access to Zizq features like unique jobs,
+  # backoff, and retention:
   #
   #   class SendEmailJob < ApplicationJob
   #     extend Zizq::ActiveJobConfig
@@ -36,17 +37,28 @@ module Zizq
     # @rbs!
     #   # ActiveJob::Base.new — invisible to steep without this.
     #   def new: (*untyped, **untyped) -> untyped
+    #
+    #   # ActiveJob::Base.queue_name — invisible to steep without this.
+    #   def queue_name: () -> String?
+
+    # Use ActiveJob's `queue_name` as the default queue, falling back to
+    # any explicit `zizq_queue` setting, then "default".
+    def zizq_queue(name = nil) #: (?String?) -> String
+      if name
+        super
+      else
+        @zizq_queue || queue_name || "default"
+      end
+    end
 
-    # Serialize arguments using ActiveJob's serialization format.
+    # Serialize using ActiveJob's own format.
     #
     # Creates a temporary ActiveJob instance to produce the canonical
-    # serialized form, including `_aj_ruby2_keywords` markers for kwargs.
-    # This ensures unique key generation uses the same format as the
-    # enqueued payload.
-    #
-    # This is needed so that unique job keys can be correctly generated.
-    def zizq_serialize(*args, **kwargs) #: (*untyped, **untyped) -> Array[untyped]
-      new(*args, **kwargs).serialize["arguments"]
+    # serialized form. Returns the full serialized hash (including
+    # `job_class`, `arguments`, `queue_name`, etc.) so that the payload
+    # stored in Zizq matches what `ActiveJob::Base.execute` expects.
+    def zizq_serialize(*args, **kwargs) #: (*untyped, **untyped) -> Hash[String, untyped]
+      new(*args, **kwargs).serialize
     end
 
     # Deserialization is handled by ActiveJob::Base.execute on the worker
@@ -56,6 +68,15 @@ module Zizq
         "ActiveJob handles deserialization via ActiveJob::Base.execute"
     end
 
+    # Override unique key generation to hash only the arguments portion
+    # of the serialized payload. The full payload contains volatile fields
+    # (job_id, enqueued_at, etc.) that change per instance.
+    def zizq_unique_key(*args, **kwargs) #: (*untyped, **untyped) -> String
+      arguments = new(*args, **kwargs).serialize["arguments"]
+      payload = normalize_payload(arguments)
+      "#{name}:#{Digest::SHA256.hexdigest(JSON.generate(payload))}"
+    end
+
     # Generate a jq expression that exactly matches payloads with the given
     # arguments.
     #
@@ -65,8 +86,8 @@ module Zizq
     #
     #   .arguments == ["a","b",{"example":true,"_aj_ruby2_keywords":["example"]}]
     def zizq_payload_filter(*args, **kwargs) #: (*untyped, **untyped) -> String
-      payload = zizq_serialize(*args, **kwargs)
-      ".arguments == #{JSON.generate(payload)}"
+      arguments = zizq_serialize(*args, **kwargs)["arguments"]
+      ".arguments == #{JSON.generate(arguments)}"
     end
 
     # Generate a jq expression that matches jobs whose positional args
@@ -85,27 +106,27 @@ module Zizq
     #   (.arguments[-1] | has("_aj_ruby2_keywords")) and
     #   (.arguments[-1] | contains({"example":true}))
     def zizq_payload_subset_filter(*args, **kwargs) #: (*untyped, **untyped) -> String
-      payload = zizq_serialize(*args, **kwargs)
+      arguments = zizq_serialize(*args, **kwargs)["arguments"]
 
       # ActiveJob flattens arguments into a single array, but marks kwargs with
       # "_aj_ruby2_keywords" => ["key1", "key2", ...] in the last element of
       # the array where kwargs are present. We need to detect this to generate
       # a suitable expression.
       serialized_args, serialized_kwargs =
-        if payload.size > 0
+        if arguments.size > 0
           # See what the last argument looks like. It might be kwargs.
-          maybe_kwargs = payload.pop
+          maybe_kwargs = arguments.pop
 
           # If it's got "_aj_ruby2_keywords" then it is kwargs.
           if maybe_kwargs.is_a?(Hash) && maybe_kwargs["_aj_ruby2_keywords"]
             # We only want the actual kwargs, not the marker.
-            [payload, maybe_kwargs.except("_aj_ruby2_keywords")]
+            [arguments, maybe_kwargs.except("_aj_ruby2_keywords")]
           else
             # It wasn't kwargs, so put it back.
-            [payload.push(maybe_kwargs), nil]
+            [arguments.push(maybe_kwargs), nil]
           end
         else
-          [payload, nil]
+          [arguments, nil]
         end
 
       parts = [] #: Array[String]

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(