zizq 0.3.5 → 0.3.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3d7eb0e9668c055e6f5b6b8ec6aacb5c09f8df5eedcea038acdb14d164a58acf
-  data.tar.gz: d30b95be8bab2eae5100b89fa7957278a20c301538e5630156bf9892739864a3
+  metadata.gz: 3252547a350b856e8122d15a77275769f62a4495efe36b36e252eba2246b51cf
+  data.tar.gz: 570e3ef065cbe42cfc038d6c1dd6669940d62f051d53965c48bea548f329e941
 SHA512:
-  metadata.gz: dbe8d111b4083de907b4522ae4f0c110554a0ab5821a544d808c363868602178c15f983140436da6525b96ab30be159ac52309adfb05cb271739a7aee73174cc
-  data.tar.gz: 39606af98c372c50147922ba7640dcd9e58d449c63927008abbcc03ac2b926e68d4856764152f51f16fb26554241e801df1fb862542e405a1087bd2213d4eaab
+  metadata.gz: 545bc4510f7df1acc51817c48ec2fae04c3a96df3589c2e3f12017d8bebb311a69cd7d18b14941ed3206829d08dd1cf28dd1d0461d44c7d2a265eead57f70710
+  data.tar.gz: 00b8916adf6921aded73d0f16cde1c2c52c98f338b3a9e4ad79a4131f06aef42b4001623c2e43d53a7c9d67e289c62f97b6abfbee6b0bb240ed89726e273ae7e

data/README.md

@@ -12,7 +12,7 @@ API.
 ## Features
 
 * Multi-thread and/or multi-fiber concurrent worker (via [`async`](https://github.com/socketry/async))
-* `Zizq::Job` based job classes, Active Job support, or completely custom
+* `Zizq::Job` based job classes, Active Job support, or low-level/custom
 * Enqueue and process jobs from one language to another
 * Arbitrary named queues
 * Granular job priorities
@@ -22,6 +22,7 @@ API.
 * Recurring jobs (cron)
 * Job introspection and management APIs, with support for `jq` query filters
 * Unique jobs
+* Testing helpers
 
 ## Installation
 
@@ -32,13 +33,13 @@ API.
 Add it to your application's `Gemfile`:
 
 ```ruby
-gem 'zizq', '~> 0.3.5'
+gem 'zizq', '~> 0.3.7'
 ```
 
 Or install it manually:
 
 ```shell
-$ gem install zizq -v 0.3.5
+$ gem install zizq -v 0.3.7
 ```
 
 Ruby **3.2.8 or newer** is required. Client and server share version
@@ -62,7 +63,7 @@ Zizq.configure do |c|
   # Optional worker defaults — applied to every Zizq::Worker
   # instance and to runs of the `zizq-worker` executable. Explicit
   # kwargs or CLI flags override these.
-  c.worker.queues       = ['emails', 'payments']
+  c.worker.queues = ['emails', 'payments']
   c.worker.fiber_count  = 25
 end
 ```
@@ -148,10 +149,42 @@ Zizq.enqueue_bulk do |b|
 end
 ```
 
-> [!NOTE]
-> Jobs can also be enqueued without `Zizq::Job` via `Zizq.enqueue_raw` —
-> designed for cross-language workflows where, for example, a Ruby app
-> enqueues jobs consumed by a Go service.
+Jobs can also be enqueued without `Zizq::Job` via `Zizq.enqueue_raw` —
+designed for lower-level code style, and for cross-language workflows where,
+for example, a Ruby app enqueues jobs consumed by a Go service.
+
+```ruby
+Zizq.enqueue_raw(
+  type: "send_email",
+  queue: "comms",
+  payload: { user_id: 42, template: "welcome" }
+)
+```
+
+### Cross-language and low-level dispatch
+
+When a Ruby app needs to *process* jobs enqueued by another language
+(or by `Zizq.enqueue_raw`), `Zizq::Router` maps `type` strings to
+handler blocks operating on plain JSON payloads:
+
+```ruby
+Zizq.configure do |c|
+  c.dispatcher = Zizq::Router.new do
+    route('send_email') do |payload|
+      Mailer.deliver(payload['user_id'], payload['template'])
+    end
+
+    # Apps that mix the two styles can fall back to Zizq::Job
+    # for anything not handled by an explicit route.
+    fallback { |job| Zizq::Job.call(job) }
+  end
+end
+```
+
+See [Custom Dispatchers](https://zizq.io/docs/clients/ruby/dispatchers.html)
+for full details. Dispatchers in Zizq are just objects that implement `#call`
+with a single `Zizq::Resources::Job` argument, and `Zizq::Router` is just a
+dispatcher itself.
 
 ### Running a worker
 

data/lib/zizq/router.rb

@@ -0,0 +1,100 @@
+# 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
+  # Dispatch jobs by `type` string, mapping each to a handler block.
+  #
+  # Designed for cross-language workflows: payloads are plain JSON
+  # values (Hashes / Arrays / strings / numbers), `type` is a String
+  # the producer agrees on with the consumer, and routes are
+  # registered explicitly — no `Zizq::Job` mixin involved.
+  #
+  #   Zizq.configure do |c|
+  #     c.dispatcher = Zizq::Router.new do
+  #       route("send_email") do |payload|
+  #         Mailer.deliver(payload["user_id"], payload["template"])
+  #       end
+  #
+  #       route("expire_tokens") do
+  #         TokenSweeper.run
+  #       end
+  #
+  #       route("generate_report") do |payload, job|
+  #         Reports.generate(payload["id"], attempts: job.attempts)
+  #       end
+  #
+  #       # `def` inside the block defines singleton methods on the
+  #       # router. Route blocks captured *inside* the constructor
+  #       # have lexical `self == router`, so they can call these
+  #       # helpers; routes added outside (`router.route("…") { … }`)
+  #       # keep their own lexical `self` and would need to go through
+  #       # the router explicitly (`router.logger`).
+  #       def logger
+  #         Zizq.configuration.logger
+  #       end
+  #
+  #       # Anything else falls back. A common pattern is delegating
+  #       # to `Zizq::Job` for the apps that mix the two styles.
+  #       fallback { |job| Zizq::Job.call(job) }
+  #     end
+  #   end
+  #
+  # Routes can also be registered outside the constructor block:
+  #
+  #   router = Zizq::Router.new
+  #   router.route("send_email") { |payload| ... }
+  #
+  # Handlers are called as `handler.call(payload, job)`. Block-arity
+  # rules let `{ |payload| }` or `{ }` ignore either argument.
+  # Strict-arity lambdas need to declare both.
+  class Router
+    # Raised when a job arrives with a type that has no registered
+    # route and no fallback. Caught by Zizq's normal worker error
+    # path, which nacks the job for retry (or dead-letters it once
+    # the retry limit is hit).
+    class UnknownJobType < Zizq::Error; end
+
+    # @rbs &block: ?(self) [self: Router] -> void
+    def initialize(&block)
+      @routes = {} #: Hash[String, ^(untyped, Resources::Job) -> void]
+      @fallback = nil #: (^(Resources::Job) -> void)?
+      instance_eval(&block) if block
+    end
+
+    # Register `handler` for jobs whose `type` matches.
+    #
+    # @rbs type: String | Symbol
+    # @rbs &handler: (untyped, Resources::Job) -> void
+    def route(type, &handler)
+      @routes[type.to_s] = handler
+    end
+
+    # Register a fallback handler invoked when no route matches.
+    # Receives the full `Resources::Job` (not split into payload /
+    # job pair), since the canonical use is delegation to another
+    # dispatcher:
+    #
+    #   fallback { |job| Zizq::Job.call(job) }
+    #
+    # @rbs &handler: (Resources::Job) -> void
+    def fallback(&handler)
+      @fallback = handler
+    end
+
+    # Dispatch a single job. Looks up the handler by `job.type`,
+    # falls back to the registered fallback if any, otherwise
+    # raises `UnknownJobType`.
+    def call(job) #: (Resources::Job) -> void
+      handler = @routes[job.type]
+
+      return handler.call(job.payload, job) if handler
+      return @fallback.call(job) if @fallback
+
+      raise UnknownJobType,
+        "no handler registered for job type #{job.type.inspect}"
+    end
+  end
+end

data/lib/zizq/test/client.rb

@@ -4,6 +4,8 @@
 # rbs_inline: enabled
 # frozen_string_literal: true
 
+require "json"
+
 module Zizq
   module Test
     # A `Zizq::Client` stand-in for use in test suites.
@@ -143,7 +145,7 @@ module Zizq
         req = EnqueueRequest.new(
           queue:,
           type:,
-          payload:,
+          payload: self.class.normalize_payload(payload),
           priority:,
           ready_at:,
           retry_limit:,
@@ -162,7 +164,7 @@ module Zizq
             req = EnqueueRequest.new(
               queue:        params[:queue],
               type:         params[:type],
-              payload:      params[:payload],
+              payload:      self.class.normalize_payload(params[:payload]),
               priority:     params[:priority],
               ready_at:     params[:ready_at],
               retry_limit:  params[:retry_limit],
@@ -236,6 +238,22 @@ module Zizq
         "#{ID_PREFIX}#{counter.to_s.rjust(ID_LENGTH - ID_PREFIX.length, '0')}"
       end
 
+      public
+
+      # Round-trip the payload through JSON so the in-memory
+      # representation matches what a consumer would receive over the
+      # wire: symbol keys / Symbol values become strings, nested
+      # hashes and arrays are normalized recursively, and non-JSON-
+      # safe values (BigDecimal, custom objects) raise here rather
+      # than surviving in test mode only to break in production.
+      #
+      # Also used by `Zizq::Test.enqueued_raw?` / `enqueued_raw_count`
+      # to normalize the query side so symbol-keyed assertion payloads
+      # still match the (now string-keyed) buffer.
+      def self.normalize_payload(payload) #: (untyped) -> untyped
+        JSON.parse(JSON.generate(payload))
+      end
+
       # Returns entries matching every named filter AND the predicate.
       # All filter kwargs are optional; unset means "don't filter on
       # this axis." Callers must hold `@mutex` — public accessors do

data/lib/zizq/test.rb

@@ -168,7 +168,13 @@ module Zizq
       filters = {}
       filters[:only_queues] = queue if queue
       filters[:only_types]  = type  if type
-      filters[:filter]      = ->(job) { job.payload == payload } unless payload.nil?
+      unless payload.nil?
+        # Normalize the assertion-side payload the same way enqueue
+        # normalizes the buffered one, so symbol-keyed test payloads
+        # still match the (string-keyed) wire-format buffer.
+        normalized = Client.normalize_payload(payload)
+        filters[:filter] = ->(job) { job.payload == normalized }
+      end
       client.enqueued_jobs(**filters).size
     end
 

data/lib/zizq/version.rb

@@ -5,5 +5,5 @@
 # frozen_string_literal: true
 
 module Zizq
-  VERSION = "0.3.5" #: String
+  VERSION = "0.3.7" #: String
 end

data/lib/zizq.rb

@@ -29,6 +29,7 @@ module Zizq
   autoload :Lifecycle,           "zizq/lifecycle"
   autoload :Query,               "zizq/query"
   autoload :Resources,           "zizq/resources"
+  autoload :Router,              "zizq/router"
   autoload :Test,                "zizq/test"
   autoload :TlsConfiguration,    "zizq/tls_configuration"
   autoload :Worker,              "zizq/worker"

data/sig/generated/zizq/router.rbs

@@ -0,0 +1,81 @@
+# Generated from lib/zizq/router.rb with RBS::Inline
+
+module Zizq
+  # Dispatch jobs by `type` string, mapping each to a handler block.
+  #
+  # Designed for cross-language workflows: payloads are plain JSON
+  # values (Hashes / Arrays / strings / numbers), `type` is a String
+  # the producer agrees on with the consumer, and routes are
+  # registered explicitly — no `Zizq::Job` mixin involved.
+  #
+  #   Zizq.configure do |c|
+  #     c.dispatcher = Zizq::Router.new do
+  #       route("send_email") do |payload|
+  #         Mailer.deliver(payload["user_id"], payload["template"])
+  #       end
+  #
+  #       route("expire_tokens") do
+  #         TokenSweeper.run
+  #       end
+  #
+  #       route("generate_report") do |payload, job|
+  #         Reports.generate(payload["id"], attempts: job.attempts)
+  #       end
+  #
+  #       # `def` inside the block defines singleton methods on the
+  #       # router. Route blocks captured *inside* the constructor
+  #       # have lexical `self == router`, so they can call these
+  #       # helpers; routes added outside (`router.route("…") { … }`)
+  #       # keep their own lexical `self` and would need to go through
+  #       # the router explicitly (`router.logger`).
+  #       def logger
+  #         Zizq.configuration.logger
+  #       end
+  #
+  #       # Anything else falls back. A common pattern is delegating
+  #       # to `Zizq::Job` for the apps that mix the two styles.
+  #       fallback { |job| Zizq::Job.call(job) }
+  #     end
+  #   end
+  #
+  # Routes can also be registered outside the constructor block:
+  #
+  #   router = Zizq::Router.new
+  #   router.route("send_email") { |payload| ... }
+  #
+  # Handlers are called as `handler.call(payload, job)`. Block-arity
+  # rules let `{ |payload| }` or `{ }` ignore either argument.
+  # Strict-arity lambdas need to declare both.
+  class Router
+    # Raised when a job arrives with a type that has no registered
+    # route and no fallback. Caught by Zizq's normal worker error
+    # path, which nacks the job for retry (or dead-letters it once
+    # the retry limit is hit).
+    class UnknownJobType < Zizq::Error
+    end
+
+    # @rbs &block: ?(self) [self: Router] -> void
+    def initialize: () ?{ (self) [self: Router] -> void } -> untyped
+
+    # Register `handler` for jobs whose `type` matches.
+    #
+    # @rbs type: String | Symbol
+    # @rbs &handler: (untyped, Resources::Job) -> void
+    def route: (String | Symbol type) { (untyped, Resources::Job) -> void } -> untyped
+
+    # Register a fallback handler invoked when no route matches.
+    # Receives the full `Resources::Job` (not split into payload /
+    # job pair), since the canonical use is delegation to another
+    # dispatcher:
+    #
+    #   fallback { |job| Zizq::Job.call(job) }
+    #
+    # @rbs &handler: (Resources::Job) -> void
+    def fallback: () { (Resources::Job) -> void } -> untyped
+
+    # Dispatch a single job. Looks up the handler by `job.type`,
+    # falls back to the registered fallback if any, otherwise
+    # raises `UnknownJobType`.
+    def call: (untyped job) -> untyped
+  end
+end

data/sig/generated/zizq/test/client.rbs

@@ -120,6 +120,20 @@ module Zizq
 
       def synthetic_id: (untyped counter) -> untyped
 
+      public
+
+      # Round-trip the payload through JSON so the in-memory
+      # representation matches what a consumer would receive over the
+      # wire: symbol keys / Symbol values become strings, nested
+      # hashes and arrays are normalized recursively, and non-JSON-
+      # safe values (BigDecimal, custom objects) raise here rather
+      # than surviving in test mode only to break in production.
+      #
+      # Also used by `Zizq::Test.enqueued_raw?` / `enqueued_raw_count`
+      # to normalize the query side so symbol-keyed assertion payloads
+      # still match the (now string-keyed) buffer.
+      def self.normalize_payload: (untyped payload) -> untyped
+
       # Returns entries matching every named filter AND the predicate.
       # All filter kwargs are optional; unset means "don't filter on
       # this axis." Callers must hold `@mutex` — public accessors do

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: zizq
 version: !ruby/object:Gem::Version
-  version: 0.3.5
+  version: 0.3.7
 platform: ruby
 authors:
 - Chris Corbyn <chris@zizq.io>
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-05-27 00:00:00.000000000 Z
+date: 2026-05-28 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: async-http
@@ -100,6 +100,7 @@ files:
 - lib/zizq/resources/job_template.rb
 - lib/zizq/resources/page.rb
 - lib/zizq/resources/resource.rb
+- lib/zizq/router.rb
 - lib/zizq/test.rb
 - lib/zizq/test/client.rb
 - lib/zizq/tls_configuration.rb
@@ -135,6 +136,7 @@ files:
 - sig/generated/zizq/resources/job_template.rbs
 - sig/generated/zizq/resources/page.rbs
 - sig/generated/zizq/resources/resource.rbs
+- sig/generated/zizq/router.rbs
 - sig/generated/zizq/test.rbs
 - sig/generated/zizq/test/client.rbs
 - sig/generated/zizq/tls_configuration.rbs