zizq 0.1.0

data/sig/generated/zizq/error.rbs

@@ -0,0 +1,41 @@
+# Generated from lib/zizq/error.rb with RBS::Inline
+
+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: (untyped message, status: untyped, ?body: untyped) -> untyped
+  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/sig/generated/zizq/job.rbs

@@ -0,0 +1,136 @@
+# Generated from lib/zizq/job.rb with RBS::Inline
+
+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: (untyped base) -> untyped
+
+    # 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: (Resources::Job job) -> void
+
+    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: (*untyped args, **untyped kwargs) -> untyped
+
+      # 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: (untyped payload) -> untyped
+
+      # 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: (*untyped args, **untyped kwargs) -> untyped
+
+      # 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: (*untyped args, **untyped kwargs) -> untyped
+    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: (*untyped args, **untyped kwargs) -> untyped
+
+    # The unique job ID assigned by the server.
+    def zizq_id: () -> untyped
+
+    # How many times this job has previously been attempted (0 on the first
+    # run, 1 on the second, etc...).
+    def zizq_attempts: () -> untyped
+
+    # The queue this job was dequeued from.
+    def zizq_queue: () -> untyped
+
+    # The priority this job was enqueued with.
+    def zizq_priority: () -> untyped
+
+    # 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: () -> untyped
+
+    # @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: (untyped job) -> untyped
+  end
+end

data/sig/generated/zizq/job_config.rbs

@@ -0,0 +1,150 @@
+# Generated from lib/zizq/job_config.rb with RBS::Inline
+
+module Zizq
+  # Shared class-level configuration DSL for Zizq job classes.
+  #
+  # This module provides the queue, priority, retry, backoff, retention,
+  # and uniqueness configuration methods. It is extended onto job classes
+  # by `Zizq::Job` and can also be used with ActiveJob via
+  # `Zizq::ActiveJobConfig`.
+  #
+  # Modules including this module must implement `zizq_serialize` and
+  # `zizq_deserialize` to define how job arguments are serialized for the API.
+  module JobConfig
+    # The class name where this is included (invisible to steep without this).
+    def name: () -> String?
+
+    # Serialize positional and keyword arguments into a JSON-serializable
+    # payload.
+    #
+    # Implemented by the including module.
+    def zizq_serialize: (*untyped args, **untyped kwargs) -> untyped
+
+    # Deserialize positional and keyword arguments from the serialized payload.
+    #
+    # Implemented by the including module.
+    def zizq_deserialize: (untyped payload) -> untyped
+
+    # Generate a jq expression that exactly matches payloads with the given
+    # arguments.
+    #
+    # Implemented by the including module.
+    def zizq_payload_filter: (*untyped args, **untyped kwargs) -> untyped
+
+    # Generate a jq expression that matches a subset of the given arguments.
+    #
+    # Implemented by the including module.
+    def zizq_payload_subset_filter: (*untyped args, **untyped kwargs) -> untyped
+
+    # Declare the default queue for this job class.
+    #
+    # If not called, defaults to "default". Jobs enqueued for this class will
+    # use the specified queue unless explicitly overridden during
+    # [`Zizq::enqueue`] or by overriding `::zizq_enqueue_options` on the job
+    # class.
+    def zizq_queue: (?untyped name) -> untyped
+
+    # Declare the default priority for this job class.
+    #
+    # If not called, defaults to the default priority on the Zizq server.
+    # Jobs enqueued for this class will use the specified priority unless
+    # explicitly overridden during [`Zizq::enqueue`] or by overriding
+    # `::zizq_enqueue_options` on the job class.
+    def zizq_priority: (?untyped priority) -> untyped
+
+    # Declare the default retry limit for this job class.
+    #
+    # The job may fail up to the number of times specified by the retry limit
+    # and will exponentially backoff. Once the retry limit is reached, the
+    # job is killed and becomes part of the dead set.
+    #
+    # If not configured, the server's default is used.
+    def zizq_retry_limit: (?untyped limit) -> untyped
+
+    # Declare the default backoff configuration for this job class.
+    #
+    # Times are specified in seconds (optionally fractional).
+    # In a Rails app `ActiveSupport::Duration` is supported too.
+    #
+    # All three parameters must be specified together and are used in the
+    # following exponential backoff formula:
+    #
+    #   delay = base + attempts**exponent + rand(0.0..jitter)*attempts
+    #
+    # Example:
+    #
+    #   zizq_backoff exponent: 4.0, base: 15, jitter: 30
+    #
+    # If not configured, the server's default backoff policy is used.
+    def zizq_backoff: (?exponent: untyped, ?base: untyped, ?jitter: untyped) -> untyped
+
+    # Declare the default retention configuration for this job class.
+    #
+    # Times are specified in seconds (optionally fractional).
+    # In a Rails app `ActiveSupport::Duration` is supported too.
+    #
+    # Both parameters are optional — only the ones provided will be sent
+    # to the server. Omitted values use the server's defaults.
+    #
+    # Example:
+    #
+    #   zizq_retention completed: 0, dead: 7 * 86_400
+    #
+    # If not configured, the server's default is used.
+    def zizq_retention: (?completed: untyped, ?dead: untyped) -> untyped
+
+    # Declare uniqueness for this job class.
+    #
+    # Requires a pro license.
+    #
+    # When enabled, duplicate jobs with the same unique key are rejected
+    # at enqueue time. The optional scope controls how long the
+    # uniqueness guard lasts:
+    #
+    #   :queued  — unique while "scheduled" or "ready" (server default)
+    #   :active  — unique while "scheduled", "ready", or "in_flight"
+    #   :exists  — unique until the job is reaped by the server
+    #
+    # Examples:
+    #
+    #   zizq_unique true                   # unique, server default scope
+    #   zizq_unique true, scope: :active   # unique while active
+    #   zizq_unique false                  # disable (e.g. in a subclass)
+    def zizq_unique: (?untyped unique, ?scope: untyped) -> untyped
+
+    # Declare or read the uniqueness scope for this job class.
+    #
+    # Usually set via `zizq_unique true, scope: :active` but can also
+    # be set independently.
+    def zizq_unique_scope: (?untyped scope) -> untyped
+
+    # Compute the unique key for a job with the given arguments.
+    #
+    # The default implementation uses the class name and hashes the
+    # normalized serialized payload. Override this method to customize
+    # uniqueness — for example, to ignore certain arguments:
+    #
+    #   def self.zizq_unique_key(user_id, template:)
+    #     super(user_id)  # unique per user, ignoring template
+    #   end
+    def zizq_unique_key: (*untyped args, **untyped kwargs) -> untyped
+
+    # Build a `Zizq::EnqueueRequest` from the class-level job config.
+    #
+    # Subclasses can override this to implement dynamic logic such as
+    # priority based on arguments:
+    #
+    #   def self.zizq_enqueue_request(user_id, template:)
+    #     req = super
+    #     req.priority = 0 if template == "urgent"
+    #     req
+    #   end
+    def zizq_enqueue_request: (*untyped args, **untyped kwargs) -> untyped
+
+    private
+
+    # Deep-sort all Hash keys so that serialization is deterministic
+    # regardless of insertion order or JSON library.
+    def normalize_payload: (untyped obj) -> untyped
+  end
+end

data/sig/generated/zizq/lifecycle.rbs

@@ -0,0 +1,34 @@
+# Generated from lib/zizq/lifecycle.rb with RBS::Inline
+
+module Zizq
+  # Thread-safe state machine for coordinating worker shutdown.
+  #
+  # States:
+  #   :running  → normal operation
+  #   :draining → stop accepting work, finish in-progress jobs
+  #   :stopped  → all work drained, safe to disconnect
+  #
+  # Transitions: running -> draining -> stopped (forward only).
+  #
+  # All transitions are signal-trap safe — they use only atomic symbol
+  # assignment and Queue#close for wakeups.
+  class Lifecycle
+    # @rbs return: void
+    def initialize: () -> void
+
+    # Non-blocking, lock-free check.
+    def running?: () -> untyped
+
+    # Transition to :draining.
+    def drain!: () -> untyped
+
+    # Transition to :stopped.
+    def stop!: () -> untyped
+
+    # Block until the state is no longer :running.
+    def wait_while_running: () -> untyped
+
+    # Block until the state is :stopped.
+    def wait_until_stopped: () -> untyped
+  end
+end

data/sig/generated/zizq/middleware.rbs

@@ -0,0 +1,50 @@
+# Generated from lib/zizq/middleware.rb with RBS::Inline
+
+module Zizq
+  module Middleware
+    # A linked chain of middleware ending with a terminal.
+    #
+    # Each middleware must implement `#call(arg, chain)` where `chain` is
+    # the next link. The terminal implements `#call(arg)`.
+    #
+    # When no middleware is registered, `#call` delegates directly to the
+    # terminal with zero overhead.
+    #
+    #   chain = Zizq::Middleware::Chain.new(dispatcher)
+    #   chain.use(LoggingMiddleware.new)
+    #   chain.use(MetricsMiddleware.new)
+    #   chain.call(job)
+    #   # MetricsMiddleware -> LoggingMiddleware -> dispatcher
+    #
+    # @rbs generic Arg -- the type flowing through the chain
+    # @rbs generic Ret -- the return type of the terminal
+    class Chain[Arg, Ret]
+      # The terminal callable at the end of the chain.
+      attr_reader terminal: untyped
+
+      def initialize: (untyped terminal) -> untyped
+
+      # Replace the terminal, invalidating any built chain.
+      def terminal=: (untyped terminal) -> untyped
+
+      # Append a middleware to the chain.
+      def use: (untyped middleware) -> untyped
+
+      # Execute the chain with the given argument.
+      def call: (untyped arg) -> untyped
+
+      private
+
+      def build: () -> untyped
+    end
+
+    # A single link in the middleware chain, connecting a middleware to
+    # the next link (or terminal).
+    class Link
+      def initialize: (untyped middleware, untyped next_link) -> untyped
+
+      # Invoke this middleware, passing the next link for continuation.
+      def call: (untyped arg) -> untyped
+    end
+  end
+end