zizq 0.1.0

data/sig/generated/zizq/client.rbs

@@ -0,0 +1,419 @@
+# Generated from lib/zizq/client.rb with RBS::Inline
+
+module Zizq
+  # Low-level HTTP wrapper for the Zizq job queue server API.
+  #
+  # Supports both JSON and MessagePack serialization formats, determined at
+  # construction time.
+  #
+  # HTTP requests are dispatched through a persistent background IO thread
+  # when called from non-Async contexts, keeping the HTTP/2 connection alive
+  # across calls and avoiding ephemeral port exhaustion. When called from
+  # within an existing Async reactor, the shared HTTP client is used directly.
+  class Client
+    # A fully-read HTTP response (status + decoded body), safe to use outside
+    # the async reactor that produced it.
+    class RawResponse < Data
+      attr_reader status(): untyped
+
+      attr_reader body(): untyped
+
+      attr_reader content_type(): untyped
+
+      def self.new: (untyped status, untyped body, untyped content_type) -> instance
+                  | (status: untyped, body: untyped, content_type: untyped) -> instance
+
+      def self.members: () -> [ :status, :body, :content_type ]
+
+      def members: () -> [ :status, :body, :content_type ]
+    end
+
+    CONTENT_TYPES: untyped
+
+    STREAM_ACCEPT: untyped
+
+    # The base URL of the Zizq server (e.g. "https://localhost:7890")
+    attr_reader url: String
+
+    # The message format to use for all communication between the client and
+    # the server (default = `:msgpack`).
+    attr_reader format: Zizq::format
+
+    # Initialize a new instance of the client with the given base URL and
+    # optional format options.
+    #
+    # @rbs url: String
+    # @rbs format: Zizq::format
+    # @rbs ssl_context: OpenSSL::SSL::SSLContext?
+    # @rbs return: void
+    def initialize: (url: String, ?format: Zizq::format, ?ssl_context: OpenSSL::SSL::SSLContext?) -> void
+
+    # Close all thread-local HTTP clients and release connections.
+    def close: () -> untyped
+
+    def cleanup_internal_clients: () -> untyped
+
+    # Enqueue a new job.
+    #
+    # This is a low-level primitive that makes a direct API call to the server
+    # using the Zizq API's expected inputs. Callers should generally use
+    # [`Zizq::enqueue`] instead.
+    #
+    # Returns a resource instance of the new job wrapping the API response.
+    #
+    # @rbs queue: String
+    # @rbs type: String
+    # @rbs payload: Hash[String | Symbol, 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 enqueue: (queue: String, type: String, payload: Hash[String | Symbol, untyped], ?priority: Integer?, ?ready_at: Zizq::to_f?, ?retry_limit: Integer?, ?backoff: Zizq::backoff?, ?retention: Zizq::retention?, ?unique_key: String?, ?unique_while: Zizq::unique_scope?) -> Resources::Job
+
+    # Enqueue multiple jobs atomically in a single bulk request.
+    #
+    # This is a low-level primitive that makes a direct API call to the server
+    # using the Zizq API's expected inputs. Callers should generally use
+    # [`Zizq::enqueue_bulk`] instead.
+    #
+    # Returns an array of resource instances wrapping the API response.
+    #
+    # @rbs jobs: Array[Hash[Symbol, untyped]]
+    # @rbs return: Array[Resources::Job]
+    def enqueue_bulk: (jobs: Array[Hash[Symbol, untyped]]) -> Array[Resources::Job]
+
+    # Get a single job by ID.
+    def get_job: (untyped id) -> untyped
+
+    # List jobs with optional filters.
+    #
+    # Multi-value filters (`status`, `queue`, `type`, `id`) accept arrays —
+    # they are joined with commas as the server expects.
+    #
+    # The `filter` parameter accepts a jq expression for filtering jobs by
+    # payload content (e.g. `.user_id == 42`).
+    #
+    # @rbs id: (String | Array[String])?
+    # @rbs status: (String | Array[String])?
+    # @rbs queue: (String | Array[String])?
+    # @rbs type: (String | Array[String])?
+    # @rbs filter: String?
+    # @rbs from: String?
+    # @rbs order: Zizq::sort_direction?
+    # @rbs limit: Integer?
+    # @rbs return: Resources::JobPage
+    def list_jobs: (?id: (String | Array[String])?, ?status: (String | Array[String])?, ?queue: (String | Array[String])?, ?type: (String | Array[String])?, ?filter: String?, ?from: String?, ?order: Zizq::sort_direction?, ?limit: Integer?) -> Resources::JobPage
+
+    # Delete a single job by ID.
+    #
+    # @rbs id: String
+    # @rbs return: void
+    def delete_job: (String id) -> void
+
+    # Delete jobs matching the given filters.
+    #
+    # Filters in the `where:` argument use the same keys as `list_jobs`. An
+    # empty `where:` hash deletes all jobs.
+    #
+    # Returns the number of deleted jobs.
+    #
+    # @rbs where: Zizq::where_params
+    # @rbs return: Integer
+    def delete_all_jobs: (?where: Zizq::where_params) -> Integer
+
+    # Update a single job's mutable fields.
+    #
+    # Fields not provided are left unchanged. Use `Zizq::RESET` to clear
+    # a nullable field back to the server default.
+    #
+    # Raises `Zizq::NotFoundError` if the job does not exist.
+    # Raises `Zizq::ClientError` (422) if the job is in a terminal state.
+    #
+    # @rbs id: String
+    # @rbs queue: (String | singleton(Zizq::UNCHANGED))?
+    # @rbs priority: (Integer | singleton(Zizq::UNCHANGED))?
+    # @rbs ready_at: (Zizq::to_f | singleton(Zizq::RESET) | singleton(Zizq::UNCHANGED))?
+    # @rbs retry_limit: (Integer | singleton(Zizq::RESET) | singleton(Zizq::UNCHANGED))?
+    # @rbs backoff: (Zizq::backoff | singleton(Zizq::RESET) | singleton(Zizq::UNCHANGED))?
+    # @rbs retention: (Zizq::retention | singleton(Zizq::RESET) | singleton(Zizq::UNCHANGED))?
+    # @rbs return: Resources::Job
+    def update_job: (String id, ?queue: (String | singleton(Zizq::UNCHANGED))?, ?priority: (Integer | singleton(Zizq::UNCHANGED))?, ?ready_at: (Zizq::to_f | singleton(Zizq::RESET) | singleton(Zizq::UNCHANGED))?, ?retry_limit: (Integer | singleton(Zizq::RESET) | singleton(Zizq::UNCHANGED))?, ?backoff: (Zizq::backoff | singleton(Zizq::RESET) | singleton(Zizq::UNCHANGED))?, ?retention: (Zizq::retention | singleton(Zizq::RESET) | singleton(Zizq::UNCHANGED))?) -> Resources::Job
+
+    # Update all jobs matching the given filters.
+    #
+    # Filters in the `where:` argument use the same keys as `list_jobs`.
+    # Fields in the `apply:` argument use the same keys as `update_job`.
+    #
+    # Terminal jobs (completed/dead) are silently skipped unless explicitly
+    # requested via `status:` in `where:`, which returns 422.
+    #
+    # Returns the number of updated jobs.
+    #
+    # @rbs where: Zizq::where_params
+    # @rbs apply: Zizq::apply_params
+    # @rbs return: Integer
+    def update_all_jobs: (?where: Zizq::where_params, ?apply: Zizq::apply_params) -> Integer
+
+    # Get a single error record by job ID and attempt number.
+    #
+    # @rbs id: String
+    # @rbs attempt: Integer
+    # @rbs return: Resources::ErrorRecord
+    def get_error: (String id, attempt: Integer) -> Resources::ErrorRecord
+
+    # List error records for a job.
+    #
+    # @rbs id: String
+    # @rbs from: String?
+    # @rbs order: Zizq::sort_direction?
+    # @rbs limit: Integer?
+    # @rbs return: Resources::ErrorPage
+    def list_errors: (String id, ?from: String?, ?order: Zizq::sort_direction?, ?limit: Integer?) -> Resources::ErrorPage
+
+    # Health check.
+    def health: () -> untyped
+
+    # Server version string.
+    def server_version: () -> untyped
+
+    # List all distinct queue names on the server.
+    def get_queues: () -> untyped
+
+    # Mark a job as successfully completed (ack).
+    #
+    # If this method (or [`#report_failure`]) is not called upon job
+    # completion, the Zizq server will consider it in-flight and will not
+    # send any more jobs if the prefetch limit has been reached, or the
+    # server's global in-flight limit has been reached. Jobs must be either
+    # acknowledged or failed before new jobs are sent.
+    #
+    # Jobs are durable and "at least once" delivery is guaranteed. If the
+    # client disconnects before it is able to report success or failure the
+    # server automatically moves the job back to the queue where it will be
+    # provided to another worker. Clients should be prepared to see the same
+    # job more than once for this reason.
+    #
+    # The Zizq server sends heartbeat messages to connected workers so that
+    # it can quickly detect and handle disconnected clients.
+    def report_success: (untyped id) -> untyped
+
+    # Bulk-mark jobs as successfully completed (bulk ack).
+    #
+    # See [`#report_success`] for full details of how acknowledgemen works.
+    #
+    # There are two ways in which the server can respond successfully:
+    #
+    # 1. 204 - No Content (All jobs acknowledged)
+    # 2. 422 - Unprocessible Entity (Some jobs were not found)
+    #
+    # Both of these statuses are in reality treated as success because missing
+    # jobs have either been previously acknowledged and purged, or moved to
+    # some other status that cannot be acknowledged.
+    #
+    # Other error response types will still raise.
+    #
+    # @rbs ids: Array[String]
+    # @rbs return: nil
+    def report_success_bulk: (Array[String] ids) -> nil
+
+    alias ack_bulk report_success_bulk
+
+    # Report a job failure (nack).
+    #
+    # Returns the updated job metadata.
+    #
+    # If this method is not called when errors occur processing jobs, the
+    # Zizq server will consider it in-flight and will not send any more jobs
+    # if the prefetch limit has been reached, or the server's global in-flight
+    # limit has been reached. Jobs must be either acknowledged or failed before
+    # new jobs are sent.
+    #
+    # Jobs are durable and "at least once" delivery is guaranteed. If the
+    # client disconnects before it is able to report success or failure the
+    # server automatically moves the job back to the queue where it will be
+    # provided to another worker. Clients should be prepared to see the same
+    # job more than once for this reason.
+    #
+    # The Zizq server sends heartbeat messages to connected workers so that
+    # it can quickly detect and handle disconnected clients.
+    #
+    # @rbs id: String
+    # @rbs message: String
+    # @rbs error_type: String?
+    # @rbs backtrace: String?
+    # @rbs retry_at: Float?
+    # @rbs kill: bool
+    # @rbs return: Resources::Job
+    def report_failure: (String id, message: String, ?error_type: String?, ?backtrace: String?, ?retry_at: Float?, ?kill: bool) -> Resources::Job
+
+    # Aliases for ack/nack vs report_success/report_failure.
+    alias ack report_success
+
+    alias nack report_failure
+
+    # Stream jobs from the server. Yields parsed job hashes.
+    #
+    # This method does not return unless the server closes the connection or
+    # the connection is otherwise interrupted. Jobs are continuously streamed
+    # to the client, and when no jobs are available the client waits for new
+    # jobs to become ready.
+    #
+    # If the client does not acknowledge or fail jobs with `[#report_success`]
+    # or [`#report_failure`] the server will stop sending new jobs to the
+    # client as it hits its prefetch limit.
+    #
+    # Jobs are durable and "at least once" delivery is guaranteed. If the
+    # client disconnects before it is able to report success or failure the
+    # server automatically moves the job back to the queue where it will be
+    # provided to another worker. Clients should be prepared to see the same
+    # job more than once for this reason.
+    #
+    # The Zizq server sends periodic heartbeat messages to the client which are
+    # silently consumed.
+    #
+    # Example:
+    #
+    #    client.take_jobs(prefetch: 5) do |job|
+    #      puts "Got job: #{job.inspect}"
+    #      client.ack(job.id) # mark the job completed
+    #    end
+    #
+    # @rbs prefetch: Integer
+    # @rbs queues: Array[String]
+    # @rbs worker_id: String?
+    # @rbs &block: (Resources::Job) -> void
+    # @rbs return: void
+    def take_jobs: (?prefetch: Integer, ?queues: Array[String], ?worker_id: String?, ?on_connect: untyped, ?on_response: untyped) { (Resources::Job) -> void } -> void
+
+    # Parse an NDJSON stream from an enumerable of byte chunks.
+    #
+    # Buffers chunks and splits on newline boundaries. The buffer only
+    # ever holds one partial line between extractions, so the `slice!`
+    # cost is trivial. Empty lines (heartbeats) are silently skipped.
+    def self.parse_ndjson: (untyped chunks) -> untyped
+
+    # Parse a length-prefixed MessagePack stream from an enumerable of byte
+    # chunks.
+    #
+    # Format: [4-byte big-endian length][MsgPack payload].
+    # A zero-length frame is a heartbeat and is silently skipped.
+    #
+    # Uses StringIO for efficient position-based reading rather than
+    # repeatedly slicing from the front of a String (which copies all
+    # remaining bytes on every extraction).
+    def self.parse_msgpack_stream: (untyped chunks) -> untyped
+
+    # GET a path on the server and return the decoded response body.
+    #
+    # The path should include any query parameters already (e.g. pagination
+    # links from the server's `pages` object). This is intentionally public
+    # so that resource objects like Page can follow links without resorting
+    # to `.send`.
+    def get_path: (untyped path) -> untyped
+
+    private
+
+    # Build a relative path with optional query parameters.
+    def build_path: (untyped path, ?params: untyped) -> untyped
+
+    # Validate and normalize filter parameters for bulk operations.
+    #
+    # Uses keyword arguments so that unknown keys raise ArgumentError.
+    #
+    # @rbs id: (String | Array[String])?
+    # @rbs status: (String | Array[String])?
+    # @rbs queue: (String | Array[String])?
+    # @rbs type: (String | Array[String])?
+    # @rbs filter: String?
+    # @rbs return: Hash[Symbol, untyped]
+    def validate_where: (?id: (String | Array[String])?, ?status: (String | Array[String])?, ?queue: (String | Array[String])?, ?type: (String | Array[String])?, ?filter: String?) -> Hash[Symbol, untyped]
+
+    # Validate set parameters via keyword args (rejects unknown keys) and
+    # build the JSON body. Used by `update_all_jobs`.
+    #
+    # @rbs queue: (String | singleton(Zizq::UNCHANGED))?
+    # @rbs priority: (Integer | singleton(Zizq::UNCHANGED))?
+    # @rbs ready_at: (Zizq::to_f | singleton(Zizq::RESET) | singleton(Zizq::UNCHANGED))?
+    # @rbs retry_limit: (Integer | singleton(Zizq::RESET) | singleton(Zizq::UNCHANGED))?
+    # @rbs backoff: (Zizq::backoff | singleton(Zizq::RESET) | singleton(Zizq::UNCHANGED))?
+    # @rbs retention: (Zizq::retention | singleton(Zizq::RESET) | singleton(Zizq::UNCHANGED))?
+    # @rbs return: Hash[Symbol, untyped]
+    def validate_and_build_set: (?queue: (String | singleton(Zizq::UNCHANGED))?, ?priority: (Integer | singleton(Zizq::UNCHANGED))?, ?ready_at: (Zizq::to_f | singleton(Zizq::RESET) | singleton(Zizq::UNCHANGED))?, ?retry_limit: (Integer | singleton(Zizq::RESET) | singleton(Zizq::UNCHANGED))?, ?backoff: (Zizq::backoff | singleton(Zizq::RESET) | singleton(Zizq::UNCHANGED))?, ?retention: (Zizq::retention | singleton(Zizq::RESET) | singleton(Zizq::UNCHANGED))?) -> Hash[Symbol, untyped]
+
+    # Build the JSON body hash for a PATCH request from set parameters.
+    #
+    # - `UNCHANGED` values are omitted (field not sent).
+    # - `RESET` values are sent as `nil` (JSON null).
+    # - `nil` is rejected — use `RESET` to clear a field.
+    # - Other values are converted to their wire format.
+    #
+    # @rbs return: Hash[Symbol, untyped]
+    def build_set_body: (?queue: untyped, ?priority: untyped, ?ready_at: untyped, ?retry_limit: untyped, ?backoff: untyped, ?retention: untyped) -> Hash[Symbol, untyped]
+
+    # Build query params for list endpoints, joining multi-value keys with ",".
+    def build_where_params: (untyped options, ?multi_keys: untyped) -> untyped
+
+    def encode_body: (untyped body) -> untyped
+
+    def decode_body: (untyped data, ?content_type: untyped) -> untyped
+
+    # Dispatch a block to the appropriate execution context.
+    #
+    # If already inside an Async reactor (e.g. AckProcessor, producer),
+    # yields the calling thread's HTTP client directly. Otherwise,
+    # dispatches via the persistent background IO thread.
+    def request: () ?{ (?) -> untyped } -> untyped
+
+    # Read the response body and close it, returning a RawResponse that is
+    # safe to use outside the reactor.
+    def consume_response: (untyped response) -> untyped
+
+    # Push a work block to the background IO thread and block until it
+    # completes, returning the result or re-raising any exception.
+    def sync_call: () ?{ (?) -> untyped } -> untyped
+
+    # Lazily start the background IO thread (double-checked locking).
+    def ensure_io_thread: () -> untyped
+
+    # Main loop for the background IO thread. Mirrors AckProcessor: runs an
+    # Async reactor, pops work from the queue (fiber-scheduler-aware), and
+    # dispatches each call as a concurrent fiber via a barrier.
+    def io_thread_run: () -> untyped
+
+    # Return the calling thread's HTTP client, creating one if needed.
+    # Uses thread_variable_get/set (not Thread.current[]) because the
+    # latter is fiber-local — each Async fiber would get its own client.
+    # The tracking array holds WeakRefs so clients from exited threads
+    # can be garbage-collected.
+    def http: () -> untyped
+
+    # Return the calling thread's streaming HTTP client (HTTP/1.1),
+    # creating one if needed. See `#http` for the thread-local locking
+    # rationale. Kept separate from the main client so the long-lived
+    # `/jobs/take` connection doesn't share an HTTP/2 session with
+    # ack/enqueue traffic.
+    def stream_http: () -> untyped
+
+    def thread_local_http: (untyped key, untyped endpoint) -> untyped
+
+    def get: (untyped path, ?params: untyped) -> untyped
+
+    def post: (untyped path, untyped body) -> untyped
+
+    def raw_post: (untyped path) -> untyped
+
+    def delete: (untyped path, ?params: untyped) -> untyped
+
+    def patch: (untyped path, untyped body, ?params: untyped) -> untyped
+
+    # Check response status and decode body, raising on errors.
+    def handle_response!: (untyped response, expected: untyped) -> untyped
+
+    # @private
+    def self.make_finalizer: (untyped io_queue, untyped http_clients) -> untyped
+  end
+end

data/sig/generated/zizq/configuration.rbs

@@ -0,0 +1,95 @@
+# Generated from lib/zizq/configuration.rb with RBS::Inline
+
+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: () -> untyped
+
+    # 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: () -> untyped
+
+    # 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=: (untyped dispatcher) -> untyped
+
+    # Validates that required configuration is present.
+    def validate!: () -> untyped
+
+    # @private
+    # Build an OpenSSL::SSL::SSLContext from the TLS options, or nil if
+    # no TLS options are configured.
+    def ssl_context: () -> untyped
+
+    # @private
+    # Identity terminal — returns the argument unchanged.
+    class Identity
+      def call: (untyped arg) -> untyped
+    end
+
+    private
+
+    # @rbs tls: Zizq::tls_options
+    def validate_tls!: (Zizq::tls_options tls) -> untyped
+
+    # Load a certificate from a PEM string or file path.
+    def load_cert: (untyped pem_or_path) -> untyped
+
+    # Load a private key from a PEM string or file path.
+    def load_key: (untyped pem_or_path) -> untyped
+
+    # 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: (untyped value) -> untyped
+  end
+end

data/sig/generated/zizq/enqueue_request.rbs

@@ -0,0 +1,94 @@
+# Generated from lib/zizq/enqueue_request.rb with RBS::Inline
+
+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: String, queue: String, payload: untyped, ?priority: Integer?, ?delay: Zizq::to_f?, ?ready_at: Zizq::to_f?, ?retry_limit: Integer?, ?backoff: Zizq::backoff?, ?retention: Zizq::retention?, ?unique_key: String?, ?unique_while: Zizq::unique_scope?) -> void
+
+    # 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: String, ?queue: String, ?payload: untyped, ?priority: Integer?, ?delay: Zizq::to_f?, ?ready_at: Zizq::to_f?, ?retry_limit: Integer?, ?backoff: Zizq::backoff?, ?retention: Zizq::retention?, ?unique_key: String?, ?unique_while: Zizq::unique_scope?) -> self
+
+    # 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: () -> untyped
+  end
+end

data/sig/generated/zizq/enqueue_with.rbs

@@ -0,0 +1,88 @@
+# Generated from lib/zizq/enqueue_with.rb with RBS::Inline
+
+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: (Zizq::enqueue_target target, Hash[Symbol, untyped] overrides) -> void
+
+    # Merge additional overrides into this scope, returning a new instance.
+    # Later keys win.
+    #
+    # @rbs overrides: Hash[Symbol, untyped]
+    # @rbs return: EnqueueWith
+    def enqueue_with: (**untyped overrides) -> EnqueueWith
+
+    # 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: (Class & Zizq::job_class job_class, *untyped args, **untyped kwargs) ?{ (EnqueueRequest) -> void } -> untyped
+
+    # 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: String, type: String, payload: untyped, **untyped opts) -> untyped
+
+    # 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: () { (EnqueueWith) -> void } -> untyped
+  end
+end