zizq 0.1.0

data/lib/zizq/configuration.rb

@@ -0,0 +1,164 @@
+# 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 "logger"
+require "openssl"
+
+module Zizq
+  # Global configuration for the Zizq client.
+  #
+  # The configuration stores only client-level concerns: server URL,
+  # serialization format, and logger. Worker-specific settings (queues,
+  # threads, etc.) are passed directly to the Worker.
+  #
+  # See: [`Zizq::configure]`.
+  # See: [`Zizq::configuration]`.
+  class Configuration
+    # Base URL of the Zizq server (default: "http://localhost:7890").
+    attr_accessor :url #: String
+
+    # Choice of content-type encoding used in communication with the Zizq
+    # server.
+    #
+    # One of: `:json`, `:msgpack` (default)
+    attr_accessor :format #: Zizq::format
+
+    # Logger instance to which to write log messages.
+    attr_accessor :logger #: Logger
+
+    # TLS options for connecting to the server over HTTPS.
+    #
+    # All values may be PEM-encoded strings or file paths.
+    #
+    #   {
+    #     ca:          "path/to/ca-cert.pem",       # CA certificate for server verification
+    #     client_cert: "path/to/client-cert.pem",   # Client certificate for mTLS
+    #     client_key:  "path/to/client-key.pem",    # Client private key for mTLS
+    #   }
+    #
+    # Note: Mutual TLS support requires a Zizq Pro license on the server.
+    attr_accessor :tls #: Zizq::tls_options?
+
+    # Middleware chain for enqueue. Each middleware receives an
+    # `EnqueueRequest` and a chain to continue.
+    attr_reader :enqueue_middleware #: Middleware::Chain[EnqueueRequest, EnqueueRequest]
+
+    # Middleware chain for dequeue/dispatch. Each middleware receives
+    # a `Resources::Job` and a chain to continue.
+    attr_reader :dequeue_middleware #: Middleware::Chain[Resources::Job, void]
+
+    def initialize #: () -> void
+      @url = "http://localhost:7890"
+      @format = :msgpack
+      @logger = Logger.new($stdout, level: Logger::INFO)
+      @tls = nil
+      @enqueue_middleware = Middleware::Chain.new(Identity.new)
+      @dequeue_middleware = Middleware::Chain.new(Zizq::Job)
+    end
+
+    # The job dispatcher.
+    # This is the terminal of the dequeue middleware chain.
+    # Defaults to `Zizq::Job` which finds and executes jobs written by mixing
+    # in the `Zizq::Job` module.
+    def dispatcher #: () -> Zizq::dispatcher
+      @dequeue_middleware.terminal
+    end
+
+    # Set the dispatcher to a custom dispatcher implementation.
+    #
+    # A dispatcher is any object that responds to `#call` with a
+    # `Zizq::Resources::Job` instance and performs that job through some
+    # application-specific logic.
+    #
+    # This is the terminal of the dequeue middleware chain.
+    #
+    # Any errors raised by the dispatcher will result in the normal
+    # backoff/retry behaviour. Jobs are acknowledged automatically on success.
+    def dispatcher=(dispatcher) #: (Zizq::dispatcher) -> void
+      @dequeue_middleware.terminal = dispatcher
+    end
+
+    # Validates that required configuration is present.
+    def validate! #: () -> void
+      raise ArgumentError, "Zizq.configure: url is required" if url.empty?
+
+      unless %i[msgpack json].include?(format)
+        raise ArgumentError, "Zizq.configure: format must be :msgpack or :json, got #{format.inspect}"
+      end
+
+      tls = @tls
+      validate_tls!(tls) if tls
+    end
+
+    # @private
+    # Build an OpenSSL::SSL::SSLContext from the TLS options, or nil if
+    # no TLS options are configured.
+    def ssl_context #: () -> OpenSSL::SSL::SSLContext?
+      tls = @tls
+      return nil unless tls
+
+      ctx = OpenSSL::SSL::SSLContext.new
+
+      if (ca = tls[:ca])
+        store = OpenSSL::X509::Store.new
+        store.add_cert(load_cert(ca))
+        ctx.cert_store = store
+        ctx.verify_mode = OpenSSL::SSL::VERIFY_PEER
+      end
+
+      if (client_cert = tls[:client_cert])
+        ctx.cert = load_cert(client_cert)
+      end
+
+      if (client_key = tls[:client_key])
+        ctx.key = load_key(client_key)
+      end
+
+      ctx
+    end
+
+    # @private
+    # Identity terminal — returns the argument unchanged.
+    class Identity
+      def call(arg) #: (untyped) -> untyped
+        arg
+      end
+    end
+
+    private
+
+    # @rbs tls: Zizq::tls_options
+    def validate_tls!(tls) #: (Zizq::tls_options) -> void
+      if tls[:client_cert] && !tls[:client_key]
+        raise ArgumentError, "Zizq.configure: tls[:client_key] is required when tls[:client_cert] is set"
+      end
+
+      if tls[:client_key] && !tls[:client_cert]
+        raise ArgumentError, "Zizq.configure: tls[:client_cert] is required when tls[:client_key] is set"
+      end
+    end
+
+    # Load a certificate from a PEM string or file path.
+    def load_cert(pem_or_path) #: (String) -> OpenSSL::X509::Certificate
+      OpenSSL::X509::Certificate.new(resolve_pem(pem_or_path))
+    end
+
+    # Load a private key from a PEM string or file path.
+    def load_key(pem_or_path) #: (String) -> OpenSSL::PKey::PKey
+      OpenSSL::PKey.read(resolve_pem(pem_or_path))
+    end
+
+    # If the value looks like PEM data, return it as-is; otherwise treat
+    # it as a file path and read the contents.
+    def resolve_pem(value) #: (String) -> String
+      if value.include?("-----BEGIN ")
+        value
+      else
+        File.read(value)
+      end
+    end
+  end
+end

data/lib/zizq/enqueue_request.rb

@@ -0,0 +1,178 @@
+# 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 job enqueue request.
+  #
+  # Contains all the information needed to enqueue a job. Built by
+  # `Job::ClassMethods#zizq_enqueue_options` or directly for raw enqueues.
+  # Mutable — callers can override values via the block form of
+  # `Zizq.enqueue`.
+  #
+  #   Zizq.enqueue(MyJob, 42) { |req| req.priority = 0 }
+  #
+  class EnqueueRequest
+    # Job type string (e.g. class name).
+    attr_accessor :type #: String
+
+    # Target queue name.
+    attr_accessor :queue #: String
+
+    # Job payload (serialized arguments).
+    attr_accessor :payload #: untyped
+
+    # Job priority (lower = higher priority).
+    attr_accessor :priority #: Integer?
+
+    # Delay before the job becomes ready (seconds).
+    attr_accessor :delay #: Zizq::to_f?
+
+    # Absolute time when the job becomes ready (fractional seconds since epoch).
+    attr_accessor :ready_at #: Zizq::to_f?
+
+    # Maximum number of retries before the job is killed.
+    attr_accessor :retry_limit #: Integer?
+
+    # Backoff configuration (in seconds).
+    attr_accessor :backoff #: Zizq::backoff?
+
+    # Retention configuration (in seconds).
+    attr_accessor :retention #: Zizq::retention?
+
+    # Unique key for deduplication.
+    attr_accessor :unique_key #: String?
+
+    # Uniqueness scope.
+    attr_accessor :unique_while #: Zizq::unique_scope?
+
+    # @rbs type: String
+    # @rbs queue: String
+    # @rbs payload: untyped
+    # @rbs priority: Integer?
+    # @rbs delay: Zizq::to_f?
+    # @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 initialize(type:,
+                   queue:,
+                   payload:,
+                   priority: nil,
+                   delay: nil,
+                   ready_at: nil,
+                   retry_limit: nil,
+                   backoff: nil,
+                   retention: nil,
+                   unique_key: nil,
+                   unique_while: nil)
+      update(
+        type:,
+        queue:,
+        payload:,
+        priority:,
+        delay:,
+        ready_at:,
+        retry_limit:,
+        backoff:,
+        retention:,
+        unique_key:,
+        unique_while:,
+      )
+    end
+
+    # Update one or more fields in place.
+    #
+    # Each keyword argument defaults to the current field value, so
+    # callers only need to name the fields they want to change. Returns
+    # `self` for chaining. Unknown keys raise `ArgumentError` — this is
+    # the signal that prevents typos like `:retries` from silently
+    # doing nothing.
+    #
+    #   req.update(priority: 0, ready_at: Time.now + 60)
+    #
+    # Used by `Zizq::EnqueueWith` to apply scoped overrides, and can be
+    # called directly from enqueue blocks as an alternative to assigning
+    # individual attributes.
+    #
+    # @rbs type: String
+    # @rbs queue: String
+    # @rbs payload: untyped
+    # @rbs priority: Integer?
+    # @rbs delay: Zizq::to_f?
+    # @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: self
+    def update(type: @type,
+               queue: @queue,
+               payload: @payload,
+               priority: @priority,
+               delay: @delay,
+               ready_at: @ready_at,
+               retry_limit: @retry_limit,
+               backoff: @backoff,
+               retention: @retention,
+               unique_key: @unique_key,
+               unique_while: @unique_while)
+      @type         = type
+      @queue        = queue
+      @payload      = payload
+      @priority     = priority
+      @delay        = delay
+      @ready_at     = ready_at
+      @retry_limit  = retry_limit
+      @backoff      = backoff
+      @retention    = retention
+      @unique_key   = unique_key
+      @unique_while = unique_while
+      self
+    end
+
+    # Convert to the params expected by `Client#enqueue`.
+    #
+    # Handles seconds -> milliseconds conversion for time-based fields,
+    # delay -> ready_at resolution, and nil omission.
+    def to_enqueue_params #: () -> Hash[Symbol, untyped]
+      params = { queue:, type:, payload: } #: Hash[Symbol, untyped]
+      params[:priority] = priority if priority
+
+      effective_ready_at = if delay
+        Time.now.to_f + delay.to_f
+      else
+        ready_at
+      end
+      params[:ready_at] = effective_ready_at if effective_ready_at
+
+      params[:retry_limit] = retry_limit if retry_limit
+
+      if backoff
+        params[:backoff] = {
+          exponent: backoff[:exponent].to_f,
+          base_ms: (backoff[:base].to_f * 1000).to_f,
+          jitter_ms: (backoff[:jitter].to_f * 1000).to_f
+        }
+      end
+
+      if retention
+        ret = {} #: Hash[Symbol, Integer]
+        ret[:completed_ms] = (retention[:completed].to_f * 1000).to_i if retention[:completed]
+        ret[:dead_ms] = (retention[:dead].to_f * 1000).to_i if retention[:dead]
+        params[:retention] = ret
+      end
+
+      params[:unique_key] = unique_key if unique_key
+      params[:unique_while] = unique_while.to_s if unique_while
+
+      params
+    end
+  end
+end

data/lib/zizq/enqueue_with.rb

@@ -0,0 +1,109 @@
+# 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
+  # A scoped enqueue helper that applies a set of option overrides to every
+  # enqueue routed through it.
+  #
+  # This is sugar for the block form of `Zizq.enqueue`. The two forms below
+  # are equivalent:
+  #
+  #   Zizq.enqueue(SendEmailJob, 42) { |req| req.ready_at = Time.now + 3600 }
+  #   Zizq.enqueue_with(ready_at: Time.now + 3600).enqueue(SendEmailJob, 42)
+  #
+  # Chainable: successive `enqueue_with` calls merge, with later keys
+  # winning:
+  #
+  #   Zizq.enqueue_with(queue: "hi").enqueue_with(priority: 0).enqueue(MyJob)
+  #
+  # This works inside a bulk block too, applying the overrides to just that one
+  # enqueue:
+  #
+  #   Zizq.enqueue_bulk do |b|
+  #     b.enqueue(MyJob, 1)
+  #     b.enqueue_with(ready_at: Time.now + 3600).enqueue(OtherJob, 42)
+  #   end
+  #
+  # Also wraps a whole bulk block when used at the top level, applying the
+  # overrides to every job in the batch:
+  #
+  #   Zizq.enqueue_with(priority: 0).enqueue_bulk do |b|
+  #     b.enqueue(MyJob, 1)
+  #     b.enqueue(MyJob, 2)
+  #   end
+  #
+  # A user block is still allowed and runs *after* the overrides, so it can
+  # override them further for that one call:
+  #
+  #   Zizq.enqueue_with(priority: 100).enqueue(MyJob) { |req| req.priority = 0 }
+  #
+  # Instances are immutable — `enqueue_with` returns a new instance. Safe
+  # to stash and reuse:
+  #
+  #   high_priority = Zizq.enqueue_with(queue: "hi", priority: 0)
+  #   high_priority.enqueue(MyJob, 1)
+  #   high_priority.enqueue(OtherJob, 2)
+  #
+  class EnqueueWith
+    # @rbs target: Zizq::enqueue_target
+    # @rbs overrides: Hash[Symbol, untyped]
+    # @rbs return: void
+    def initialize(target, overrides)
+      @target = target
+      @overrides = overrides.freeze
+    end
+
+    # Merge additional overrides into this scope, returning a new instance.
+    # Later keys win.
+    #
+    # @rbs overrides: Hash[Symbol, untyped]
+    # @rbs return: EnqueueWith
+    def enqueue_with(**overrides)
+      self.class.new(@target, @overrides.merge(overrides))
+    end
+
+    # 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 args: Array[untyped]
+    # @rbs kwargs: Hash[Symbol, untyped]
+    # @rbs &block: ?(EnqueueRequest) -> void
+    # @rbs return: untyped
+    def enqueue(job_class, *args, **kwargs, &block)
+      @target.enqueue(job_class, *args, **kwargs) do |req|
+        req.update(**@overrides)
+        block&.call(req)
+      end
+    end
+
+    # Enqueue a raw request via the underlying target, with overrides
+    # merged into the kwargs (explicit kwargs take precedence).
+    #
+    # @rbs queue: String
+    # @rbs type: String
+    # @rbs payload: untyped
+    # @rbs opts: Hash[Symbol, untyped]
+    # @rbs return: untyped
+    def enqueue_raw(queue:, type:, payload:, **opts)
+      @target.enqueue_raw(queue:, type:, payload:, **@overrides.merge(opts))
+    end
+
+    # Wrap a bulk block so that every enqueue inside it inherits the
+    # scoped overrides. Works uniformly against both the top-level
+    # `Zizq` module (starts a new bulk batch) and a `BulkEnqueue`
+    # instance (appends to the existing batch), because `BulkEnqueue`
+    # implements `enqueue_bulk` as a no-op that yields itself.
+    #
+    # @rbs &block: (EnqueueWith) -> void
+    # @rbs return: untyped
+    def enqueue_bulk(&block)
+      @target.enqueue_bulk do |b|
+        block.call(self.class.new(b, @overrides))
+      end
+    end
+  end
+end

data/lib/zizq/error.rb

@@ -0,0 +1,43 @@
+# 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
+  # Base error class for all Zizq errors.
+  class Error < StandardError; end
+
+  # Network-level failure (connection refused, DNS, timeout etc).
+  class ConnectionError < Error; end
+
+  # HTTP error — the server returned a non-success status code.
+  # Carries the status code and parsed body.
+  class ResponseError < Error
+    # The HTTP response status from the Zizq server.
+    attr_reader :status #: Integer
+
+    # The decoded body of the error response.
+    attr_reader :body #: Hash[String, untyped]?
+
+    # Create a new ResponseError with the given error message, response status
+    # and decoded response body.
+    def initialize(message, status:, body: nil) #: (String, status: Integer, ?body: Hash[String, untyped]?) -> void
+      @status = status
+      @body = body
+      super(message)
+    end
+  end
+
+  # 4xx client error.
+  class ClientError < ResponseError; end
+
+  # 404 specifically — job not found, etc.
+  class NotFoundError < ClientError; end
+
+  # 5xx server error.
+  class ServerError < ResponseError; end
+
+  # Streaming take-jobs connection interrupted.
+  class StreamError < Error; end
+end

data/lib/zizq/job.rb

@@ -0,0 +1,188 @@
+# 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
+  # Mixin which all valid job classes must include.
+  #
+  # This module must be included in a class to make it a valid Zizq job. The
+  # class name becomes the job type, and the worker resolves types back to
+  # classes via `Object.const_get` (which naturally triggers any autoload
+  # logic).
+  #
+  #   class SendEmailJob
+  #     include Zizq::Job
+  #
+  #     zizq_queue "emails"   # optional, defaults to "default"
+  #
+  #     def perform(user_id, template:)
+  #       puts "Sending #{template} email to user #{user_id}"
+  #     end
+  #   end
+  #
+  # The job can be configured through class methods to set the queue, priority
+  # etc. Classes can also override `::zizq_enqueue_options` to implement
+  # dynamically configured jobs based on their arguments.
+  module Job
+    def self.included(base) #: (Class) -> void
+      base.extend(ClassMethods)
+    end
+
+    # Default dispatcher for Zizq jobs.
+    #
+    # Resolves the job class from the type string, deserializes the
+    # payload, and calls `#perform`. Any object that responds to
+    # `#call(job)` can replace this as a custom dispatcher via
+    # `Zizq.configure { |c| c.dispatcher = MyDispatcher.new }`.
+    #
+    # The contract is simple: return normally → ack, raise → nack.
+    #
+    # @rbs job: Resources::Job
+    # @rbs return: void
+    def self.call(job)
+      job_class = Object.const_get(job.type)
+
+      unless job_class.is_a?(Class) && job_class.include?(Zizq::Job)
+        raise "#{job.type} does not include Zizq::Job"
+      end
+
+      zizq_job_class = job_class #: Zizq::job_class
+      instance = zizq_job_class.new
+      instance.set_zizq_job(job)
+
+      args, kwargs = zizq_job_class.zizq_deserialize(
+        job.payload || { "args" => [], "kwargs" => {} }
+      )
+
+      instance.perform(*args, **kwargs)
+    end
+
+    module ClassMethods
+      include JobConfig
+
+      # Serialize positional and keyword arguments for the `#perform` method
+      # into a payload hash suitable for sending to the server.
+      #
+      # The result must be a JSON encodable Hash.
+      #
+      # The default implementation generates a hash of the form:
+      #
+      #   { "args" => [ 42, "Hello" ], "kwargs" => { "template": "example" } }
+      #
+      # If you override this method you almost certainly need to override
+      # `::zizq_deserialize`, `::zizq_payload_filter` and
+      # `::zizq_payload_subset_filter` too.
+      #
+      # Any failure to deserialize the arguments will cause the job to fail and
+      # backoff according to the backoff policy.
+      def zizq_serialize(*args, **kwargs) #: (*untyped, **untyped) -> Hash[String, untyped]
+        { "args" => args, "kwargs" => kwargs.transform_keys(&:to_s) }
+      end
+
+      # Deserialize a payload hash back into positional and keyword arguments.
+      #
+      # The payload is a JSON decoded Hash.
+      #
+      # The default implementation receives a Hash of the form:
+      #
+      #   { "args" => [ 42, "Hello" ], "kwargs" => { "template": "example" } }
+      #
+      # And returns an array for `args` and `kwargs` of the form:
+      #
+      #   [ [ 42, "Hello" ], {template: "example"} ]
+      #
+      # Because the default implementation uses a JSON decoded Hash, any symbol
+      # keys that were present at enqueue-time will be string keys after
+      # decoding.
+      #
+      # Any failure to deserialize the arguments will cause the job to fail and
+      # backoff according to the backoff policy.
+      def zizq_deserialize(payload) #: (Hash[String, untyped]) -> [Array[untyped], Hash[Symbol, untyped]]
+        args   = payload.fetch("args")
+        kwargs = payload.fetch("kwargs").transform_keys(&:to_sym)
+        [args, kwargs]
+      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:
+      #
+      #   . == {"args":["a","b","c"],"kwargs":{"example":true,"other":false}}
+      def zizq_payload_filter(*args, **kwargs) #: (*untyped, **untyped) -> String
+        payload = zizq_serialize(*args, **kwargs)
+        ". == #{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:
+      #
+      #   (.args[0:2] == ["a","b"]) and (.kwargs | contains({"example":true}))
+      def zizq_payload_subset_filter(*args, **kwargs) #: (*untyped, **untyped) -> String
+        payload = zizq_serialize(*args, **kwargs)
+        serialized_args = payload.fetch("args")
+        serialized_kwargs = payload.fetch("kwargs")
+
+        [
+          "(.args[0:#{serialized_args.size}] == #{JSON.generate(serialized_args)})",
+          "(.kwargs | contains(#{JSON.generate(serialized_kwargs)}))"
+        ].join(" and ")
+      end
+    end
+
+    # This is your job's main entrypoint when it is run by the worker.
+    #
+    # Override this method in your job class to define the work to perform.
+    # Declare any positional and keyword arguments your job needs.
+    #
+    # Strong recommendation: stick to keyword arguments because they are much
+    # easier to evolve over time in a backwards compatible way with any already
+    # enqueued jobs.
+    def perform(*args, **kwargs) #: (*untyped, **untyped) -> void
+      raise NotImplementedError, "#{self.class.name}#perform must be implemented"
+    end
+
+    # --- Metadata helpers ---
+    #
+    # These delegate to the Resources::Job instance set by the worker
+    # before calling #perform, giving the job access to its server-side
+    # metadata.
+
+    # The unique job ID assigned by the server.
+    def zizq_id = @zizq_job&.id         #: () -> String?
+
+    # How many times this job has previously been attempted (0 on the first
+    # run, 1 on the second, etc...).
+    def zizq_attempts = @zizq_job&.attempts   #: () -> Integer?
+
+    # The queue this job was dequeued from.
+    def zizq_queue = @zizq_job&.queue      #: () -> String?
+
+    # The priority this job was enqueued with.
+    def zizq_priority = @zizq_job&.priority   #: () -> Integer?
+
+    # Time at which this job was dequeued (fractional seconds since the Unix
+    # epoch). This can be converted to `Time` by using `Time.at(dequeued_at)`
+    # but that is intentionally left to the caller due to time zone
+    # considerations.
+    def zizq_dequeued_at = @zizq_job&.dequeued_at #: () -> Float?
+
+    # @api private
+    # Set by the worker before calling #perform. Receives the full
+    # Resources::Job object so all metadata is available through delegation.
+    def set_zizq_job(job) #: (Resources::Job) -> void
+      @zizq_job = job
+    end
+  end
+end