zizq 0.3.5 → 0.3.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3d7eb0e9668c055e6f5b6b8ec6aacb5c09f8df5eedcea038acdb14d164a58acf
-  data.tar.gz: d30b95be8bab2eae5100b89fa7957278a20c301538e5630156bf9892739864a3
+  metadata.gz: a95c96d7b844064db29aea81935d6ec6e3c6953fc47459fcfd6253b6b44aa1e7
+  data.tar.gz: 19a8e38ef04716ba02b21bb4ce1f8f2b3e597b1f9845ada71dde5ae7d31fecd3
 SHA512:
-  metadata.gz: dbe8d111b4083de907b4522ae4f0c110554a0ab5821a544d808c363868602178c15f983140436da6525b96ab30be159ac52309adfb05cb271739a7aee73174cc
-  data.tar.gz: 39606af98c372c50147922ba7640dcd9e58d449c63927008abbcc03ac2b926e68d4856764152f51f16fb26554241e801df1fb862542e405a1087bd2213d4eaab
+  metadata.gz: d4158e9e2b3f58e2c1b823b26f8c81a9ee5ab347d72683377909fed7b4d0d163caf3e27708d3e1f3cbd1af3018068fda34d97405ec6095732b0cda57909a82fc
+  data.tar.gz: 95c1453a0af6a82e8ad0abd5e2a8085550ce4cf5ef6b2871cb653fdd1068994f69b36bb04a5e30d2ec76c1ccc02a1e142621a5c5bde7de9bab84517917b90fef

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.6'
 ```
 
 Or install it manually:
 
 ```shell
-$ gem install zizq -v 0.3.5
+$ gem install zizq -v 0.3.6
 ```
 
 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 { #router }
+
+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/version.rb

@@ -5,5 +5,5 @@
 # frozen_string_literal: true
 
 module Zizq
-  VERSION = "0.3.5" #: String
+  VERSION = "0.3.6" #: 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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: zizq
 version: !ruby/object:Gem::Version
-  version: 0.3.5
+  version: 0.3.6
 platform: ruby
 authors:
 - Chris Corbyn <chris@zizq.io>
@@ -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