zizq 0.1.0

data/lib/zizq/active_job_config.rb

@@ -0,0 +1,122 @@
+# 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
+
+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:
+  #
+  #   class SendEmailJob < ApplicationJob
+  #     extend Zizq::ActiveJobConfig
+  #
+  #     zizq_unique true, scope: :active
+  #     zizq_backoff exponent: 4.0, base: 15, jitter: 30
+  #
+  #     def perform(user_id, template:)
+  #       # ...
+  #     end
+  #   end
+  #
+  # Serialization uses ActiveJob's own format so that GlobalID, Time, and
+  # other ActiveJob-supported types are handled correctly. The Zizq worker
+  # must use the ActiveJob dispatcher:
+  #
+  #   Zizq.configure do |c|
+  #     c.dispatcher = ActiveJob::QueueAdapters::ZizqAdapter::Dispatcher
+  #   end
+  module ActiveJobConfig
+    include JobConfig
+
+    # @rbs!
+    #   # ActiveJob::Base.new — invisible to steep without this.
+    #   def new: (*untyped, **untyped) -> untyped
+
+    # Serialize arguments using ActiveJob's serialization 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"]
+    end
+
+    # Deserialization is handled by ActiveJob::Base.execute on the worker
+    # side. This method is not used in the ActiveJob dispatch path.
+    def zizq_deserialize(_payload) #: (untyped) -> [Array[untyped], Hash[Symbol, untyped]]
+      raise NotImplementedError,
+        "ActiveJob handles deserialization via ActiveJob::Base.execute"
+    end
+
+    # Generate a jq expression that exactly matches payloads with the given
+    # arguments.
+    #
+    # This is used for filtering in Zizq::Query.
+    #
+    # Generates an expression of the form:
+    #
+    #   .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)}"
+    end
+
+    # Generate a jq expression that matches jobs whose positional args
+    # start with the given values and whose kwargs contain the given
+    # key/value pairs.
+    #
+    # This is used for filtering in Zizq::Query.
+    #
+    # Generates expressions of the form:
+    #
+    #   (.arguments[0:2] == ["a","b"])
+    #
+    # or
+    #
+    #   (.arguments[0:2] == ["a","b"]) and
+    #   (.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)
+
+      # 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
+          # See what the last argument looks like. It might be kwargs.
+          maybe_kwargs = payload.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")]
+          else
+            # It wasn't kwargs, so put it back.
+            [payload.push(maybe_kwargs), nil]
+          end
+        else
+          [payload, nil]
+        end
+
+      parts = [] #: Array[String]
+      parts << %Q<(.arguments[0:#{serialized_args.size}] == #{JSON.generate(serialized_args)})>
+
+      if serialized_kwargs
+        parts << %Q<(.arguments[-1] | has("_aj_ruby2_keywords"))>
+        parts << %Q<(.arguments[-1] | contains(#{JSON.generate(serialized_kwargs)}))>
+      end
+
+      parts.join(" and ")
+    end
+  end
+end

data/lib/zizq/backoff.rb

@@ -0,0 +1,50 @@
+# 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
+  # Encapsulates exponential backoff state for retry loops.
+  #
+  # Each call to `wait` sleeps for the current duration and then advances
+  # to the next interval. Call `reset` to return to the initial wait time
+  # after a successful operation.
+  class Backoff
+    attr_reader :min_wait #: Float
+    attr_reader :max_wait #: Float
+    attr_reader :multiplier #: Float
+
+    # @rbs min_wait: (Float | Integer)
+    # @rbs max_wait: (Float | Integer)
+    # @rbs multiplier: (Float | Integer)
+    # @rbs return: void
+    def initialize(min_wait:, max_wait:, multiplier:)
+      @min_wait = min_wait.to_f
+      @max_wait = max_wait.to_f
+      @multiplier = multiplier.to_f
+      @current = @min_wait #: Float
+    end
+
+    # Returns the current backoff duration without advancing.
+    def duration #: () -> Float
+      @current
+    end
+
+    # Sleeps for the current backoff duration, then advances to the next.
+    def wait #: () -> void
+      sleep @current
+      @current = [@current * @multiplier, @max_wait].min
+    end
+
+    # Resets the backoff to the initial min_wait.
+    def reset #: () -> void
+      @current = @min_wait
+    end
+
+    # Returns a new Backoff with the same configuration but reset state.
+    def fresh #: () -> Backoff
+      self.class.new(min_wait: @min_wait, max_wait: @max_wait, multiplier: @multiplier)
+    end
+  end
+end

data/lib/zizq/bulk_enqueue.rb

@@ -0,0 +1,87 @@
+# 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 for collecting multiple job params to be sent as a single bulk
+  # request via `Zizq.enqueue_bulk`.
+  #
+  #   Zizq.enqueue_bulk do |b|
+  #     b.enqueue(MyApp::FooJob, 42)
+  #     b.enqueue(MyApp::OtherJob, 42, x: 7)
+  #   end
+  class BulkEnqueue
+    attr_reader :requests #: Array[EnqueueRequest]
+
+    def initialize #: () -> void
+      @requests = [] #: Array[EnqueueRequest]
+    end
+
+    # Collect a job class enqueue. Accepts the same arguments as
+    # `Zizq.enqueue`.
+    #
+    # @rbs job_class: Class & Zizq::job_class
+    # @rbs args: Array[untyped]
+    # @rbs kwargs: Hash[Symbol, untyped]
+    # @rbs &block: ?(EnqueueRequest) -> void
+    # @rbs return: void
+    def enqueue(job_class, *args, **kwargs, &block)
+      @requests << Zizq.build_enqueue_request(job_class, *args, **kwargs, &block)
+    end
+
+    # Collect a raw enqueue. Accepts the same arguments as
+    # `Zizq.enqueue_raw`.
+    #
+    # @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)
+      @requests << EnqueueRequest.new(queue:, type:, payload:, **opts)
+    end
+
+    # Build a scoped enqueue helper that applies the given overrides to a
+    # single enqueue inside this bulk block. Sugar for the block form:
+    #
+    #   b.enqueue_with(ready_at: Time.now + 3600).enqueue(OtherJob, 42)
+    #
+    # is equivalent to:
+    #
+    #   b.enqueue(OtherJob, 42) { |req| req.ready_at = Time.now + 3600 }
+    #
+    # @rbs overrides: Hash[Symbol, untyped]
+    # @rbs return: EnqueueWith
+    def enqueue_with(**overrides)
+      EnqueueWith.new(self, overrides)
+    end
+
+    # Nested bulk is a no-op — we're already inside a bulk block, so we
+    # just yield this same builder. This exists to satisfy the
+    # `_EnqueueTarget` interface, which lets `EnqueueWith#enqueue_bulk`
+    # work uniformly against both the top-level `Zizq` module and a
+    # `BulkEnqueue` instance without branching on target type.
+    #
+    #   Zizq.enqueue_bulk do |b|
+    #     b.enqueue_with(priority: 0).enqueue_bulk do |b2|
+    #       b2.enqueue(MyJob, 1)
+    #       b2.enqueue(MyJob, 2)
+    #     end
+    #   end
+    #
+    # @rbs &block: (BulkEnqueue) -> void
+    # @rbs return: self
+    def enqueue_bulk(&block)
+      yield self
+      self
+    end
+  end
+end