zizq 0.1.0

data/sig/generated/zizq/resources/resource.rbs

@@ -0,0 +1,26 @@
+# Generated from lib/zizq/resources/resource.rb with RBS::Inline
+
+module Zizq
+  module Resources
+    # Base class for all typed response wrappers. Holds a reference to the
+    # Client (for following links) and the raw response hash.
+    class Resource
+      # Returns the client instance that returned this resource.
+      attr_reader client: Client
+
+      # @rbs client: Zizq::Client
+      # @rbs data: Hash[String, untyped]
+      # @rbs return: void
+      def initialize: (Zizq::Client client, Hash[String, untyped] data) -> void
+
+      # Returns the underlying raw response hash.
+      def to_h: () -> untyped
+
+      # Omit the client from inspect output to reduce noise.
+      def inspect: () -> untyped
+
+      # Convert a millisecond timestamp to fractional seconds, nil-safe.
+      def ms_to_seconds: (untyped value) -> untyped
+    end
+  end
+end

data/sig/generated/zizq/version.rbs

@@ -0,0 +1,5 @@
+# Generated from lib/zizq/version.rb with RBS::Inline
+
+module Zizq
+  VERSION: String
+end

data/sig/generated/zizq/worker.rbs

@@ -0,0 +1,152 @@
+# Generated from lib/zizq/worker.rb with RBS::Inline
+
+module Zizq
+  # Top-level worker process which orchestrates fetching jobs from the server
+  # and dispatching them to a pool of worker tasks for processing.
+  #
+  # Fiber support (when `fiber_count > 1`) creates an Async context. When
+  # `fiber_count == 1`, no Async context is created.
+  #
+  # Total concurrency is calculated as `thread_count * fiber_count`.
+  class Worker
+    DEFAULT_THREADS: Integer
+
+    DEFAULT_FIBERS: Integer
+
+    DEFAULT_RETRY_MIN_WAIT: ::Integer
+
+    DEFAULT_RETRY_MAX_WAIT: ::Integer
+
+    DEFAULT_RETRY_MULTIPLIER: ::Integer
+
+    # Convenience class method to create and run a worker.
+    def self.run: () -> untyped
+
+    # The total number of worker threads to run.
+    #
+    # For applications that are not threadsafe, this should be set to 1
+    # (default: 5).
+    attr_reader thread_count: Integer
+
+    # The total number of fibers to run within each worker thread.
+    #
+    # For applications that cannot handle multi-fiber execution, this should be
+    # set to 1. Any value greater than 1 runs workers inside an Async context
+    # (default: 1).
+    attr_reader fiber_count: Integer
+
+    # The set of queues from which to fetch jobs.
+    #
+    # An empty set (default) means all queues.
+    attr_reader queues: Array[String]
+
+    # The total number of jobs to allow to be sent from the server at once.
+    #
+    # Defaults to 2x the total concurrency (threads * fibers) to keep the
+    # pipeline full while ack round-trips are in flight.
+    attr_reader prefetch: Integer
+
+    # Proc to derive a worker ID string for each thread and fiber.
+    #
+    # When not present, the Zizq server assigns a random worker ID.
+    attr_reader worker_id_proc: (^(Integer, Integer) -> String?)?
+
+    # An instance of a Logger to be used for worker logging.
+    attr_reader logger: Logger
+
+    # The dispatcher used to handle each job.
+    #
+    # Defaults to the globally-configured `dequeue_middleware` chain.
+    # When a custom dispatcher is provided to `#initialize`, it is used as-is
+    # and the configured middleware chain is ignored. Caller may construct
+    # their own `Zizq::Middleware::Chain` if middleware needs to be applied.
+    attr_reader dispatcher: ^(Resources::Job) -> void
+
+    # @rbs queues: Array[String]
+    # @rbs thread_count: Integer
+    # @rbs fiber_count: Integer
+    # @rbs prefetch: Integer?
+    # @rbs retry_min_wait: (Float | Integer)
+    # @rbs retry_max_wait: (Float | Integer)
+    # @rbs retry_multiplier: (Float | Integer)
+    # @rbs worker_id: (^(Integer, Integer) -> String?)?
+    # @rbs logger: Logger?
+    # @rbs dispatcher: (^(Resources::Job) -> void)?
+    # @rbs return: void
+    def initialize: (?queues: Array[String], ?thread_count: Integer, ?fiber_count: Integer, ?prefetch: Integer?, ?retry_min_wait: Float | Integer, ?retry_max_wait: Float | Integer, ?retry_multiplier: Float | Integer, ?worker_id: (^(Integer, Integer) -> String?)?, ?logger: Logger?, ?dispatcher: (^(Resources::Job) -> void)?) -> void
+
+    # Request a graceful shutdown.
+    #
+    # Transitions the lifecycle to `:draining` and closes the dispatch
+    # queue. Worker threads finish any in-flight jobs, the ack processor
+    # flushes pending acks, and the producer stays connected to the server
+    # while all of that drains — only then is the streaming connection
+    # closed and `#run` returns.
+    #
+    # Safe to call from a signal handler (uses only atomic ivar assignment
+    # and `Thread::Queue#close`).
+    def stop: () -> untyped
+
+    # Request an immediate shutdown.
+    #
+    # Like `#stop`, but the streaming connection is closed immediately
+    # during teardown (rather than after workers drain), so the server
+    # re-dispatches any in-flight jobs after its visibility timeout. Use
+    # this when `#stop` has been given adequate time and still hasn't
+    # returned.
+    #
+    # In-progress jobs on worker threads continue to completion — we
+    # don't interrupt user code mid-execution — but no new jobs are
+    # pulled from the queue and cleanup uses short deadlines.
+    #
+    # Safe to call from a signal handler.
+    def kill: () -> untyped
+
+    # Start the worker.
+    #
+    # Spawns the desired number of worker threads and fibers, distributes
+    # jobs to those workers and then blocks until shutdown. Safe to call
+    # multiple times on the same Worker instance — all mutable runtime
+    # state (lifecycle, dispatch queue, ack processor, backoff) is reset
+    # at the start of each run.
+    def run: () -> untyped
+
+    private
+
+    # Reset all mutable runtime state so `#run` can be called multiple
+    # times on the same Worker instance. Called from `#initialize` and
+    # from the top of `#run`.
+    def reset_runtime_state: () -> untyped
+
+    def start_producer_thread: () -> untyped
+
+    def start_worker_threads: () -> untyped
+
+    # Internal worker run loop.
+    #
+    # Each worker thread or fiber continually pops jobs from the internal queue
+    # and dispatches them to the correct job class until the queue is closed
+    # and drained.
+    def run_loop: (untyped thread_idx, untyped fiber_idx) -> untyped
+
+    # Fiber-based worker loop. Requires the `async` gem.
+    def run_fiber_workers: (untyped thread_idx) -> untyped
+
+    # Process a single job.
+    #
+    # Delegates to the configured dispatcher (default: `Zizq::Job.dispatch`)
+    # and reports success or failure.
+    def dispatch: (untyped job, untyped worker_id) -> untyped
+
+    # @rbs job_id: String
+    # @rbs return: void
+    def push_ack: (String job_id) -> void
+
+    # @rbs job_id: String
+    # @rbs error: Exception
+    # @rbs return: void
+    def push_nack: (String job_id, Exception error) -> void
+
+    def resolve_worker_id: (untyped thread_idx, untyped fiber_idx) -> untyped
+  end
+end

data/sig/generated/zizq.rbs

@@ -0,0 +1,180 @@
+# Generated from lib/zizq.rb with RBS::Inline
+
+module Zizq
+  # Sentinel indicating a field should not be included in the request.
+  # Used as the default for update parameters.
+  module UNCHANGED
+  end
+
+  # Sentinel indicating a field should be sent as null to reset to server default.
+  module RESET
+  end
+
+  # Returns the client configuration.
+  #
+  # The configuration can be updated by calling [`Zizq::configure`].
+  #
+  # This configuration is for the client only. Worker parameters are
+  # configured on a per-run basis for flexibility.
+  def self.configuration: () -> untyped
+
+  # Yields the global configuration ready for updates, which should be done
+  # during application initialization, before any jobs are enqueued or
+  # worked.
+  #
+  #   Zizq.configure do |c|
+  #     c.url = "http://localhost:7890"
+  #     c.format = :msgpack
+  #     c.dequeue_middleware.use(MyDequeueMiddleware.new)
+  #   end
+  def self.configure: () -> untyped
+
+  # Returns a shared client instance built from the global configuration.
+  #
+  # The client is memoized so that persistent HTTP connections are reused
+  # across calls, reducing TCP connection overhead.
+  def self.client: () -> untyped
+
+  # Resets all global state: configuration and shared client.
+  # Intended for use in tests.
+  def self.reset!: () -> untyped
+
+  # Server version string.
+  def self.server_version: () -> untyped
+
+  # List all distinct queue names on the server.
+  def self.queues: () -> untyped
+
+  # Start a query to retrieve or modify job data.
+  #
+  # @rbs id: (String | Array[String])?
+  # @rbs queue: (String | Array[String])?
+  # @rbs type: (String | Array[String])?
+  # @rbs status: (String | Array[String])?
+  # @rbs jq_filter: String?
+  # @rbs order: Zizq::sort_direction?
+  # @rbs limit: Integer?
+  # @rbs page_size: Integer?
+  # @rbs return: Zizq::Query
+  def self.query: () -> Zizq::Query
+
+  # Enqueue a job by class with positional and keyword arguments.
+  #
+  # By default all arguments are serialized as JSON, which means hashes with
+  # symbol keys will become hashes with string keys. The serialization
+  # behaviour can be changed by implementing `::zizq_serialize` and
+  # `::zizq_deserialize` as class methods on the job class.
+  #
+  # Default job options can be overridden at enqueue-time by providing a
+  # block which receives a mutable `Zizq::EnqueueRequest` instance.
+  #
+  #   Zizq.enqueue(SendEmailJob, 42, template: "welcome")
+  #   Zizq.enqueue(SendEmailJob, 42) { |o| o.queue = "priority" }
+  #
+  # Job classes may also override `::zizq_enqueue_options` to implement
+  # dynamically computed options, such as dynamic prioritisation. This class
+  # method accepts the same arguments as the `#perform` method and returns an
+  # instance of `Zizq::EnqueueRequest`. Any overrides may call `super` and
+  # modify the result.
+  #
+  #   class SendEmailJob
+  #     include Zizq::Job
+  #
+  #     zizq_priority 1000
+  #
+  #     def self.zizq_enqueue_options(user_id, template:)
+  #       opts = super
+  #       opts.priority /= 2 if template == "welcome"
+  #       opts
+  #     end
+  #
+  #     def perform(user_id, template:)
+  #       # ...
+  #     end
+  #   end
+  #
+  # @rbs job_class: Class & Zizq::job_class
+  # @rbs args: Array[untyped]
+  # @rbs kwargs: Hash[Symbol, untyped]
+  # @rbs &block: ?(EnqueueRequest) -> void
+  # @rbs return: Resources::Job
+  def self.enqueue: (Class & Zizq::job_class job_class, *untyped args, **untyped kwargs) ?{ (EnqueueRequest) -> void } -> Resources::Job
+
+  # Enqueue a job by providing raw inputs to the Zizq server.
+  #
+  # This is for advanced use cases such as enqueueing jobs for consumption in
+  # other programming languages.
+  #
+  #   Zizq.enqueue_raw(
+  #     queue: "emails",
+  #     type: "send_email",
+  #     payload: {user_id: 42, template: "welcome"}
+  #   )
+  #
+  # If using this method to enqueue a job that is intended for consumption in
+  # the Ruby client itself a custom dispatcher implementation is likely
+  # required:
+  #
+  #   Zizq.configure do |c|
+  #     c.dispatcher = MyDispatcher.new
+  #   end
+  #
+  # @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: Resources::Job
+  def self.enqueue_raw: (queue: String, type: String, payload: untyped, **untyped opts) -> Resources::Job
+
+  # Enqueue multiple jobs atomically in a single bulk request.
+  #
+  # This can significantly imprive throughput when many jobs need to be
+  # enqueued collectively. There is no upper limit on the number of jobs in
+  # the request though generally it is probably wise to keep this to less
+  # than 1000 jobs unless you have strong atomicity requuirements for a
+  # larger number of jobs..
+  #
+  # Yields a builder object whose `#enqueue` method accepts the same
+  # arguments as `Zizq.enqueue`. All collected jobs are sent as a
+  # single `POST /jobs/bulk` request and an array of jobs is returned in the
+  # same order as the inputs.
+  #
+  #   Zizq.enqueue_bulk do |b|
+  #     b.enqueue(ProcessPaymentJob, 7)
+  #     b.enqueue(SendEmailJob, 42, template: "welcome")
+  #     b.enqueue(SendEmailJob, 42) { |o| o.queue = "priority" }
+  #   end
+  #
+  # Build a scoped enqueue helper that applies the given option overrides
+  # to every enqueue routed through it. Equivalent to using the block
+  # form of `Zizq.enqueue`, but composable and reusable.
+  #
+  #   Zizq.enqueue_with(ready_at: Time.now + 3600).enqueue(MyJob, 42)
+  #   Zizq.enqueue_with(priority: 0).enqueue_bulk { |b| ... }
+  #
+  # See `Zizq::EnqueueWith` for details.
+  #
+  # @rbs overrides: Hash[Symbol, untyped]
+  # @rbs return: EnqueueWith
+  def self.enqueue_with: (**untyped overrides) -> EnqueueWith
+
+  # @rbs &block: (BulkEnqueue) -> void
+  # @rbs return: Array[Resources::Job]
+  def self.enqueue_bulk: () { (BulkEnqueue) -> void } -> Array[Resources::Job]
+
+  # @api private
+  # Build an EnqueueRequest for a single job class enqueue.
+  #
+  # @rbs job_class: Class & Zizq::job_class
+  # @rbs args: Array[untyped]
+  # @rbs kwargs: Hash[Symbol, untyped]
+  # @rbs &block: ?(EnqueueRequest) -> void
+  # @rbs return: EnqueueRequest
+  def self.build_enqueue_request: (Class & Zizq::job_class job_class, *untyped args, **untyped kwargs) ?{ (EnqueueRequest) -> void } -> EnqueueRequest
+end

data/sig/zizq.rbs

@@ -0,0 +1,111 @@
+# Copyright (c) 2026 Chris Corbyn <chris@zizq.io>
+# Licensed under the MIT License. See LICENSE file for details.
+
+# Manual RBS declarations that rbs-inline can't generate.
+
+module Zizq
+  # Any object that can be converted to a Float (Time, Duration, Numeric, etc).
+  interface _ToF
+    def to_f: () -> Float
+  end
+
+  type to_f = _ToF
+
+  # Serialization format for communication with the server.
+  type format = :json | :msgpack
+
+  # Sort direction for paginated list endpoints.
+  type sort_direction = :asc | :desc
+
+  # Backoff configuration expressed in fractional seconds.
+  type backoff = { exponent: Float, base: Float, jitter: Float }
+
+  # Retention configuration expressed in fractional seconds.
+  type retention = { ?completed: Float, ?dead: Float }
+
+  # Uniqueness scope for deduplication at enqueue time.
+  type unique_scope = :queued | :active | :exists
+
+  # Filter parameters for bulk operations (delete, update) and list queries.
+  type where_params = {
+    ?id: (String | Array[String])?,
+    ?status: (String | Array[String])?,
+    ?queue: (String | Array[String])?,
+    ?type: (String | Array[String])?,
+    ?filter: String?
+  }
+
+  # Update parameters for single and bulk update operations.
+  type apply_params = {
+    ?queue: (String | singleton(UNCHANGED))?,
+    ?priority: (Integer | singleton(UNCHANGED))?,
+    ?ready_at: (to_f | singleton(RESET) | singleton(UNCHANGED))?,
+    ?retry_limit: (Integer | singleton(RESET) | singleton(UNCHANGED))?,
+    ?backoff: (backoff | singleton(RESET) | singleton(UNCHANGED))?,
+    ?retention: (retention | singleton(RESET) | singleton(UNCHANGED))?
+  }
+
+  # TLS options for connecting over HTTPS. Values are PEM strings or file paths.
+  type tls_options = { ?ca: String, ?client_cert: String, ?client_key: String }
+
+  # Any object that can dispatch a job. Must respond to #call(job).
+  interface _Dispatcher
+    def call: (Resources::Job) -> void
+  end
+
+  # Type alias for dispatcher configuration.
+  type dispatcher = _Dispatcher
+
+  # Structural type for a class that includes Zizq::Job.
+  #
+  # When a class includes Zizq::Job, the `included` callback extends
+  # ClassMethods onto the class. Steep can't infer this from the runtime
+  # `extend` call, so we describe the resulting shape as an interface.
+  #
+  # The `_` prefix is mandatory RBS syntax for interfaces. The `job_class`
+  # type alias below provides a cleaner name for use in source annotations.
+  interface _JobClass
+    def zizq_queue: (?String?) -> String
+    def zizq_retry_limit: (?Integer?) -> Integer?
+    def zizq_backoff: (?exponent: Numeric?, ?base: Numeric?, ?jitter: Numeric?) -> backoff?
+    def zizq_retention: (?completed: Numeric?, ?dead: Numeric?) -> retention?
+    def zizq_unique: (?bool?, ?scope: unique_scope?) -> bool
+    def zizq_unique_scope: (?unique_scope?) -> unique_scope?
+    def zizq_unique_key: (*untyped, **untyped) -> String
+    def zizq_serialize: (*untyped, **untyped) -> Hash[String, untyped]
+    def zizq_deserialize: (Hash[String, untyped]) -> [Array[untyped], Hash[Symbol, untyped]]
+    def zizq_payload_filter: (*untyped, **untyped) -> String
+    def zizq_payload_subset_filter: (*untyped, **untyped) -> String
+    def zizq_enqueue_request: (*untyped, **untyped) -> EnqueueRequest
+    def name: () -> String?
+    def new: () -> Job
+  end
+
+  # Alias so source code can write `Zizq::job_class` instead of `_JobClass`.
+  type job_class = _JobClass
+
+  # Structural type for anything that `Zizq::EnqueueWith` can forward to —
+  # both the top-level `Zizq` module and `Zizq::BulkEnqueue` instances
+  # satisfy this. `BulkEnqueue#enqueue_bulk` is a no-op that just yields
+  # itself, so nested `enqueue_with(...).enqueue_bulk { ... }` calls
+  # inside an existing bulk block compose naturally.
+  interface _EnqueueTarget
+    def enqueue: (
+      Class & job_class,
+      *untyped,
+      **untyped
+    ) ?{ (EnqueueRequest) -> void } -> untyped
+
+    def enqueue_raw: (
+      queue: String,
+      type: String,
+      payload: untyped,
+      **untyped
+    ) -> untyped
+
+    def enqueue_bulk: () { (_EnqueueTarget) -> void } -> untyped
+  end
+
+  # Alias so source code can write `Zizq::enqueue_target`.
+  type enqueue_target = _EnqueueTarget
+end

metadata

@@ -0,0 +1,134 @@
+--- !ruby/object:Gem::Specification
+name: zizq
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Chris Corbyn <chris@zizq.io>
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-04-25 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: async-http
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.82'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.82'
+- !ruby/object:Gem::Dependency
+  name: msgpack
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.7'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.7'
+description: |-
+  This is the Ruby client for the Zizq job queue server.
+
+  [Zizq](https://zizq.io/) is a simple, single binary, zero dependency, language agnostic job queue.
+
+  This client supports multi-threaded and/or multi-fiber concurrency and is very fast. The Zizq server provides everything needed. There are no separate external storage dependencies to configure.
+email:
+executables:
+- zizq-worker
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- bin/profile-worker
+- bin/zizq-worker
+- lib/active_job/queue_adapters/zizq_adapter.rb
+- lib/zizq.rb
+- lib/zizq/ack_processor.rb
+- lib/zizq/active_job_config.rb
+- lib/zizq/backoff.rb
+- lib/zizq/bulk_enqueue.rb
+- lib/zizq/client.rb
+- lib/zizq/configuration.rb
+- lib/zizq/enqueue_request.rb
+- lib/zizq/enqueue_with.rb
+- lib/zizq/error.rb
+- lib/zizq/job.rb
+- lib/zizq/job_config.rb
+- lib/zizq/lifecycle.rb
+- lib/zizq/middleware.rb
+- lib/zizq/query.rb
+- lib/zizq/resources.rb
+- lib/zizq/resources/error_enumerator.rb
+- lib/zizq/resources/error_page.rb
+- lib/zizq/resources/error_record.rb
+- lib/zizq/resources/job.rb
+- lib/zizq/resources/job_page.rb
+- lib/zizq/resources/page.rb
+- lib/zizq/resources/resource.rb
+- lib/zizq/version.rb
+- lib/zizq/worker.rb
+- sig/generated/zizq.rbs
+- sig/generated/zizq/ack_processor.rbs
+- sig/generated/zizq/active_job_config.rbs
+- sig/generated/zizq/backoff.rbs
+- sig/generated/zizq/bulk_enqueue.rbs
+- sig/generated/zizq/client.rbs
+- sig/generated/zizq/configuration.rbs
+- sig/generated/zizq/enqueue_request.rbs
+- sig/generated/zizq/enqueue_with.rbs
+- sig/generated/zizq/error.rbs
+- sig/generated/zizq/job.rbs
+- sig/generated/zizq/job_config.rbs
+- sig/generated/zizq/lifecycle.rbs
+- sig/generated/zizq/middleware.rbs
+- sig/generated/zizq/query.rbs
+- sig/generated/zizq/resources/error_enumerator.rbs
+- sig/generated/zizq/resources/error_page.rbs
+- sig/generated/zizq/resources/error_record.rbs
+- sig/generated/zizq/resources/job.rbs
+- sig/generated/zizq/resources/job_page.rbs
+- sig/generated/zizq/resources/page.rbs
+- sig/generated/zizq/resources/resource.rbs
+- sig/generated/zizq/version.rbs
+- sig/generated/zizq/worker.rbs
+- sig/zizq.rbs
+homepage: https://zizq.io
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/zizq-labs/zizq-ruby
+  documentation_uri: https://zizq.io/docs/clients/ruby/
+  homepage_uri: https://zizq.io
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.8
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.22
+signing_key:
+specification_version: 4
+summary: The official Ruby client for the Zizq job queue
+test_files: []