cuniculus 0.0.1 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a706ee37ab059f8897e2aba8cd1ab3a6dc15cdde2eabc78d98ddecd5113afb2a
-  data.tar.gz: 02bc1b2265e346485e99f583ed3f3c3a619335238d7f1552d809490dea3d5a0d
+  metadata.gz: ca0cc8cbcc9cc9607488d5c7c88903548fe4106799e6517e82b2efb5824a9971
+  data.tar.gz: 6a0589c882ae8de39a0192e2e5b54c537a709fbe6ca496ce3b999d3a03ff6da1
 SHA512:
-  metadata.gz: bc3a8d8a26b299ffab344a642fc539e762fd03f3922bd165ff0611d44a0ecd62a39cd4a242fe529bc283e063764a15e399c2f4ad1dbbb4112c97863953f032ab
-  data.tar.gz: efc582168bc82aa2b5a66ecb42f26dc1d4fc36a73f95a9f46fb9028114a0781d0ad0f4cc10dc4fb41ff0f32f93550c8f745b80fb1e6a93c16a502e7f19e4a73e
+  metadata.gz: 73fc5ea97169bdbdf5a72b95dec76e2b529a13c6b308a3c3c9c947d891bc3845d48ad5b4344820d0f1fed8cbed8b0bb1ffac3a4c3ea043ca0cb3c1737eb8014d
+  data.tar.gz: 7dbdd0c30c1dc808457fc408506aade75b65de83f5318799f8b7a5aab4c0891ed71fbb927e58eaa70b099442790b1c1d20b06d34d12a53967def89052f068887

data/LICENSE

@@ -1,6 +1,6 @@
 BSD 2-Clause License
 
-Copyright (c) 2020, Marcelo
+Copyright (c) 2021, Marcelo
 All rights reserved.
 
 Redistribution and use in source and binary forms, with or without

data/README.md

@@ -2,6 +2,36 @@
 
 Ruby job queue backed by RabbitMQ. The word _cuniculus_ comes from the scientific name of the European rabbit (Oryctolagus cuniculus).
 
+## Benchmarks
+
+The following measurements were performed with the `bin/run_benchmarks` utility, with different command parameters. Run it with `-h` to see its usage.
+
+To simulate network latency, [Toxiproxy](https://github.com/Shopify/toxiproxy) was used. It needs to be started with `toxiproxy-server` before running the benchmarks.
+
+Network latency (_ms_) | Prefetch count       | Throughput (_jobs/s_) | Average latency (_ms_)
+----------------------:|---------------------:|----------------------:|----------------------:
+1                      | 65535 (max. allowed) | 10225                 | 2
+10                     | 65535 (max. allowed) | 9990                  | 13
+1                      |                   50 | 8051                  | 2
+10                     |                   50 | 2500                  | 13
+100                    |                   50 | 481                   | 103
+1                      |                   25 | 7824                  | 2
+10                     |                   25 | 1824                  | 13
+50                     |                   25 | 469                   | 53
+1                      |         10 (default) | 5266                  | 2
+10                     |         10 (default) | 807                   | 13
+1                      |                    1 | 481                   | 2
+10                     |                    1 | 81                    | 13
+
+Additional benchmark parameters:
+- throughput was measured by consuming 100k jobs;
+- job latency was averaged over 200 samples;
+- Ruby 2.7.2 was used.
+
+Several remarks can be made:
+- Higher prefetch counts lead to higher throughput, but there are downsides of having it too high; see [this reference](https://www.cloudamqp.com/blog/2017-12-29-part1-rabbitmq-best-practice.html#prefetch) on how to properly tune it.
+- Network latency has a severe impact on the throughput, and the effect is larger the smaller the prefetch count is.
+
 ## Getting started
 
 ```sh
@@ -18,6 +48,8 @@ require 'cuniculus/worker'
 class MyWorker
   include Cuniculus::Worker
 
+  # the queue name is not explicitly given, so "cun_default" is used.
+
   def perform(arg1, arg2)
     puts "Processing:"
     puts "arg1: #{arg1.inspect}"
@@ -52,6 +84,8 @@ There is also a more complete example in the Cuniculus repository itself. To run
   bin/cuniculus -I examples/ -r example/init_cuniculus.rb
   ```
 
+The `-I examples` option adds the `examples/` directory into the load path, and `-r example/init_cuniculus.rb` requires `init_cuniculus.rb` prior to starting the consumer. The latter is where configurations such as that described in the next section should be.
+
 ## Configuration
 
 Configuration is done through code, using `Cuniculus.configure`. 
@@ -75,6 +109,20 @@ Cuniculus.configure do |cfg|
   cfg.rabbitmq_opts = rabbitmq_conn
   cfg.pub_thr_pool_size = 5         # Only affects job producers
   cfg.dead_queue_ttl = 1000 * 60 * 60 * 24 * 30 # keep failed jobs for 30 days
+  cfg.add_queue({ name: "critical", durable: true, max_retry: 10, prefetch_count: 1})
+end
+```
+
+To configure the queue used by a worker, used `cuniculus_options`:
+
+```ruby
+class MyWorker
+  include Cuniculus::Worker
+
+  cuniculus_options queue: "critical"
+  def perform
+    # code
+  end
 end
 ```
 
@@ -92,15 +140,32 @@ The method expects a block that will receive an exception, and run in the scope
 
 ## Retry mechanism
 
-Cuniculus declares a `cun_default` queue, together with some `cun_default_{n}` queues used for job retries.
+Retries are enabled by default (with 8 retries) with an exponential backoff, meaning the time between retries increases the more failures happen. The formula for calculating the times between retries can be found in {Cuniculus::QueueConfig}, namely in the `x-message-ttl` line. As an example, the time between the 7th and 8th retries is roughly 29 days.
+
+Given a declared queue in the configuration, Cuniculus starts on RabbitMQ the corresponding base queue, in addition to its retry queues. As an example, let's consider the default queue `cun_default`: Cuniculus declares a `cun_default` queue, together with some `cun_default_{n}` queues used for job retries.
+
 When a job raises an exception, it is placed into the `cun_default_1` queue for the first retry. It stays there for some pre-defined time, and then gets moved back into the `cun_default` queue for execution.
 
 If it fails again, it gets moved to `cun_default_2`, where it stays for a longer period until it's moved back directly into the `cun_default` queue again.
 
-This goes on until there are no more retry attempts, in which case the job gets moved into the `cun_dead` queue. It can be then only be moved back into the `cun_default` queue manually; otherwise it is discarded after some time, defined as the `dead_queue_ttl`, in milliseconds (by default, 180 days).
+This goes on until there are no more retry attempts, in which case the job gets moved into the `cun_dead` queue. It can be then only be moved back into the `cun_default` queue manually; otherwise it is discarded after some time, defined as the {Cuniculus::Config.dead_queue_ttl}, in milliseconds (by default, 180 days).
 
 Note that if a job cannot even be parsed, it is moved straight to the dead queue, as there's no point in retrying.
 
+## Health check plugin
+
+Cuniculus ships with a health check plugin. When enabled, a Rack server is started (therefore the [Rack](https://github.com/rack/rack) gem is required, as well as the used handler), which responds with `200 OK` upon receiving a request in the configured port and path.
+
+Enable it with `Cuniculus.plugin(:health_check)`, which binds the server to `0.0.0.0:3000`, listening on the `/healthcheck` path. To configure the server, pass additional options:
+
+```ruby
+Cuniculus.plugin(:health_check, { "bind_to" => "127.0.0.1", "port" => 3003, "path" => "ping" })
+```
+
+Check {Cuniculus::Plugins::HealthCheck} for further details.
+
+_Note that the default handler "webrick" is not bundled by default with Ruby 3 and needs to be installed separately, if it is to be used._
+
 ## How it works
 
 Cuniculus code and conventions are very much inspired by another Ruby job queue library: [Sidekiq](https://github.com/mperham/sidekiq).

data/lib/cuniculus.rb

@@ -14,12 +14,14 @@ require "cuniculus/supervisor"
 module Cuniculus
 
   # Configure Cuniculus.
+  # Check {Cuniculus::Config} for the available options.
   #
   # @yield [Cuniculus::Config]
   #
   # @example Change RabbitMQ connection details.
   #   Cuniculus.configure do |cfg|
   #     cfg.rabbitmq_opts = { host: 'rmq.mycompany.com', user: 'guest', pass: 'guest' }
+  #     cfg.add_queue({ name: "new_queue", max_retry: 4 })
   #   end
   def self.configure
     cfg = Cuniculus::Config.new

data/lib/cuniculus/config.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "cuniculus/core"
+require "cuniculus/exceptions"
 require "cuniculus/queue_config"
 
 module Cuniculus
@@ -23,9 +24,37 @@ module Cuniculus
         vhost: "/"
       }
       @exchange_name = "cuniculus"
+      @pub_thr_pool_size = 5
       @dead_queue_ttl = 1000 * 60 * 60 * 24 * 180 # 180 days
     end
 
+    # Configure an additional queue
+    #
+    # Note that a single call to `add_queue` might lead to the creation of multiple queues on RabbitMQ: one base queue, and an additional queue for every retry attempt.
+    # For example, with a queue named `"test"` with `max_retry` set to `4`, 5 queues are created in RabbitMQ.
+    #
+    # For tuning `prefetch_count`, refer to [this guide](https://www.cloudamqp.com/blog/2017-12-29-part1-rabbitmq-best-practice.html#prefetch).
+    #
+    # If a queue already exists in RabbitMQ, and an attempt is done to add it again through `add_queue`, nothing happens, except if the options passed to `add_queue` conflict with the existing queue. For example if a queue exists that is durable, and `add_queue` is called with `"durable" => false`, a `Cuniculus::RMQQueueConfigurationConflict` is raised. To redeclare a queue with conflicting configurations, the original queue has first to be removed from RabbitMQ manually. This can be done, for example, through the management console.
+    #
+    # @param qopts [Hash] Queue config options.
+    # @option qopts [String] "name" Name of the queue.
+    # @option qopts [Boolean] "durable" (true) Whether queue is declared as durable in RabbitMQ. Jobs in non-durable queues may be lost if the RabbitMQ goes down.
+    # @option qopts [Integer] "max_retry" (8) Number of retries for failed jobs in this queue.
+    # @option qopts [Integer] "prefetch_count" (10) Prefetch count used when consuming jobs from this queue.
+    # @option qopts [Integer] "thread_pool_size" (5) Thread pool size for receiving jobs.
+    #
+    # @example Add queue named "critical"
+    #   Cuniculus.configure do |cfg|
+    #     cfg.add_queue({ name: "critical", max_retry: 10 })
+    #   end
+    def add_queue(qopts)
+      qopts = qopts.transform_keys(&:to_s)
+      qname = qopts["name"].to_s
+      raise Cuniculus::ConfigError, "Missing 'name' key in queue configuration hash" if qname.strip.empty?
+      @queues[qname] = QueueConfig.new(qopts)
+    end
+
     def declare!
       conn = ::Bunny.new(rabbitmq_opts.merge(ENFORCED_CONN_OPTS))
       conn.start
@@ -35,6 +64,10 @@ module Cuniculus
       @queues.each_value { |q| q.declare!(ch) }
     end
 
+    # Specify if the default queue `cun_default` should be created.
+    # `cun_default` is used by workers that don't explicitly specify a queue with `cuniculus_options queue: "another_queue"`.
+    #
+    # @param bool [Boolean] If false, queue `cun_default` is not created. Defaults to `true`.
     def default_queue=(bool)
       @queues.delete("cun_default") unless bool
     end

data/lib/cuniculus/consumer.rb

@@ -17,7 +17,6 @@ module Cuniculus
 
     def start
       @exchange = channel.direct(Cuniculus::CUNICULUS_EXCHANGE, { durable: true })
-      # channel.direct(Cuniculus::CUNICULUS_DLX_EXCHANGE, { durable: true })
       @job_queue = queue_config.declare!(channel)
       @_consumer = job_queue.subscribe(manual_ack: true, block: false) do |delivery_info, properties, payload|
         run_job(delivery_info, properties, payload)

data/lib/cuniculus/core.rb

@@ -23,7 +23,7 @@ module Cuniculus
     # the message and backtrace of `exception`.
     #
     # @param exception [Exception] The exception being wrapped
-    # @param [Cuniculus::Error] The subclass of `Cuniculus::Error`
+    # @param klass [Cuniculus::Error] The subclass of `Cuniculus::Error`
     #
     # @return [Cuniculus::Error] An instance of the input `Cuniculus::Error`
     def convert_exception_class(exception, klass)

data/lib/cuniculus/exceptions.rb

@@ -5,12 +5,14 @@ module Cuniculus
   #
   # * `Cuniculus::Error`: Default exception raised by Cuniculus.
   #   All exceptions classes defined by Cuniculus descend from this class.
-  # * `Cuniculus::RMQConnectionError`: Raised when unable to connect to RabbitMQ.
-  # * `Cuniculus::RMQQueueConfigurationConflict`: Raised when the queue configuration
+  # * `Cuniculus::BadlyFormattedPayload`: A Cuniculus consumer received an
+  #   improperly formatted job message.
+  # * `Cuniculus::ConfigError`: Incorrect configuration passed to Cuniculus.
+  # * `Cuniculus::RMQConnectionError`: Unable to connect to RabbitMQ.
+  # * `Cuniculus::RMQQueueConfigurationConflict`: The queue configuration
   #   given to Cuniculus conflicts with the current configuration of the same
   #   existing queue in RabbitMQ.
-  # * `Cuniculus::BadlyFormattedPayload`: Raised when Cuniculus consumer receives an
-  #   improperly formatted job message.
+  # * `Cuniculus::WorkerOptionsError`: Invalid options passed to cuniculus_options.
 
   class Error < ::StandardError
     # If the Cuniculus exception wraps an underlying exception, the latter
@@ -25,6 +27,18 @@ module Cuniculus
     end
   end
 
+  # Dev note:
+  # As explained [here](https://github.com/jeremyevans/sequel/commit/24681efad0fec48195e43801c224bf18cdc8be13#diff-64cd7b67eccdc6dfa69c23b3b19f34e318f9e6827c5dee5f6e845b2993ab035c), empty classes created
+  # with `Class.new` require about 200 bytes less memory than ones created as `class MyClass; end`.
+  # The call to `name` is used so that the names of such classes are cached before runtime.
+  (
+    BadlyFormattedPayload = Class.new(Error)
+  ).name
+
+  (
+    ConfigError = Class.new(Error)
+  ).name
+
   (
     RMQConnectionError = Class.new(Error)
   ).name
@@ -33,7 +47,8 @@ module Cuniculus
     RMQQueueConfigurationConflict = Class.new(Error)
   ).name
 
+
   (
-    BadlyFormattedPayload = Class.new(Error)
+    WorkerOptionsError = Class.new(Error)
   ).name
 end

data/lib/cuniculus/job_queue.rb

@@ -5,7 +5,7 @@ module Cuniculus
   class JobQueue
     extend Forwardable
 
-    def_delegators :@base_queue, :subscribe
+    def_delegators :@base_queue, :message_count, :subscribe
 
     def initialize(base_queue, retry_queue_names)
       @base_queue = base_queue

data/lib/cuniculus/plugins/health_check.rb

@@ -2,11 +2,12 @@
 
 require "socket"
 require "thread"
+require "rack"
 
 module Cuniculus
   module Plugins
-    # The HealthCheck plugin starts a TCP server together with consumers for health probing.
-    # It currently does not perform any additional checks returns '200 OK' regardless of whether
+    # The HealthCheck plugin starts a Rack server after consumers are initialized, for health probing.
+    # It currently does not perform any additional checks and returns '200 OK' regardless of whether
     # - the node can connect to RabbitMQ;
     # - consumers are stuck.
     #
@@ -17,23 +18,23 @@ module Cuniculus
     # Cuniculus.plugin(:health_check)
     # ```
     #
-    # Options may be passed as well (use `String` keys):
+    # Options may be passed as well:
     # ```ruby
     # opts = {
     #   "bind_to" => "127.0.0.1", # Default: "0.0.0.0"
     #   "port" => 8080            # Default: 3000
+    #   "path" => "alive"         # Default: "healtcheck"
     # }
     # Cuniculus.plugin(:health_check, opts)
     # ```
-    # This starts the server bound to 127.0.0.1 and port 8080.
-    #
-    # Note that the request path is not considered. The server responds with 200 to any path.
+    # This starts the server bound to 127.0.0.1 and port 8080, and responds on path "alive".
+    # The server responds with 404 when requests are made to different paths.
     module HealthCheck
-      HEALTH_CHECK_RESPONSE = "HTTP/1.1 200 OK\r\nContent-Type: text/plain\r\nContent-Length: 2\r\nConnection: close\r\n\r\nOK"
-
       DEFAULTS = {
         "bind_to" => "0.0.0.0",
+        "path" => "healthcheck",
         "port" => 3000,
+        "quiet" => false,
         "server" => "webrick",
         "block" => nil
       }.freeze
@@ -42,15 +43,19 @@ module Cuniculus
 
       # Configure `health_check` plugin
       #
-      # @param plugins_cfg [Hash] Global plugin config hash, passed by Cuniculus. This should not be used by plugin users.
+      # @param plugins_cfg [Hash] Global plugin config hash, passed by Cuniculus. This should not be modified by plugin users.
       # @param opts [Hash] Plugin specific options.
-      # @option opts [String] "bind_to" IP address to bind to (default: "0.0.0.0")
-      # @option opts [Numeric] "port" Port number to bind to (default: 3000)
+      # @option opts [String] "bind_to" ("0.0.0.0") IP address to bind to.
+      # @option opts [String] "path" ("healthcheck") Request path to respond to. Requests to other paths will get a 404 response.
+      # @option opts [Numeric] "port" (3000) Port number to bind to.
+      # @option opts [Boolean] "quiet" (false) Disable server logging to STDOUT and STDERR.
+      # @option opts [String] "server" ("webrick") Rack server handler to use .
       def self.configure(plugins_cfg, opts = {}, &block)
+        opts = opts.transform_keys(&:to_s)
         invalid_opts = opts.keys - DEFAULTS.keys
         raise Cuniculus::Error, "Invalid option keys for :health_check plugin: #{invalid_opts}" unless invalid_opts.empty?
 
-        plugins_cfg[OPTS_KEY] = h = opts.slice("bind_to", "port", "server")
+        plugins_cfg[OPTS_KEY] = h = opts.slice("bind_to", "path", "port", "quiet", "server")
         h["block"] = block if block
         DEFAULTS.each do |k, v|
           h[k] = v if v && !h.key?(k)
@@ -58,45 +63,43 @@ module Cuniculus
       end
 
       module SupervisorMethods
+        def initialize(config)
+          super(config)
+          hc_plugin_opts = config.opts[OPTS_KEY]
+          @hc_server = Rack::Handler.get(hc_plugin_opts["server"])
+          @hc_rack_app = build_rack_app(hc_plugin_opts)
+        end
+
         def start
-          hc_rd, @hc_wr = IO.pipe
-          start_health_check_server(hc_rd)
+          start_health_check_server
           super
         end
 
         def stop
-          @hc_wr << "a"
+          @hc_server.shutdown
           super
         end
 
 
         private
 
-        def start_health_check_server(pipe_reader)
-          opts = config.opts[OPTS_KEY]
-          server = ::TCPServer.new(opts["bind_to"], opts["port"])
-
-          # If port was assigned by OS (when 'port' option was given as 0),
-          # now override input value with it.
-          opts["port"] = server.addr[1]
-          @hc_thread = Thread.new do
-            sock = nil
-            done = false
-            loop do
-              begin
-                break if done
-                sock = server.accept_nonblock
-              rescue IO::WaitReadable, Errno::EINTR
-                io = IO.select([server, pipe_reader])
-                done = true if io.first.include?(pipe_reader)
-                retry
-              end
-
-              sock.print HEALTH_CHECK_RESPONSE
-              sock.shutdown
+        def build_rack_app(opts)
+          app = ::Object.new
+          app.define_singleton_method(:call) do |env|
+            if Rack::Request.new(env).path == "/#{opts['path']}"
+              [200, {}, ["OK"]]
+            else
+              [404, {}, ["Not Found"]]
             end
+          end
+          app
+        end
 
-            sock&.close if sock && !sock.closed?
+        def start_health_check_server
+          opts = config.opts[OPTS_KEY]
+          Thread.new do
+            access_log = opts["quiet"] ? [] : nil
+            @hc_server.run(@hc_rack_app, AccessLog: access_log, Port: opts["port"], Host: opts["bind_to"])
           end
         end
       end

data/lib/cuniculus/queue_config.rb

@@ -6,27 +6,32 @@ require "cuniculus/job_queue"
 
 module Cuniculus
   class QueueConfig
-    OPTS = {}.freeze
-
-    DEFAULT_MAX_RETRY = 4
-
-    attr_reader :max_retry, :name, :thread_pool_size
-
-    def initialize(opts = OPTS)
-      @name = read_opt(opts, "name") || "cun_default"
-      @max_retry = read_opt(opts, "max_retry") || DEFAULT_MAX_RETRY
-      @thread_pool_size = read_opt(opts, "thread_pool_size")
+    DEFAULT_MAX_RETRY = 8
+    DEFAULT_PREFETCH_COUNT = 10
+    DEFAULT_QUEUE_NAME = "cun_default"
+    DEFAULT_THREAD_POOL_SIZE = 5
+
+    attr_reader :durable, :max_retry, :name, :prefetch_count, :thread_pool_size
+
+    def initialize(opts = {})
+      opts = opts.transform_keys(&:to_s)
+      @durable = read_opt(opts["durable"], true)
+      @name = read_opt(opts["name"], DEFAULT_QUEUE_NAME)
+      @max_retry = read_opt(opts["max_retry"], DEFAULT_MAX_RETRY)
+      @prefetch_count = read_opt(opts["prefetch_count"], DEFAULT_PREFETCH_COUNT)
+      @thread_pool_size = read_opt(opts["thread_pool_size"], DEFAULT_THREAD_POOL_SIZE)
+      freeze
     end
 
-    def read_opt(opts, key)
-      opts[key.to_s] || opts[key.to_sym]
+    def read_opt(val, default)
+      val.nil? ? default : val
     end
 
     def declare!(channel)
       queue_name = name
       base_q = channel.queue(
         queue_name,
-        durable: true,
+        durable: durable,
         exclusive: false,
         arguments: { "x-dead-letter-exchange" => Cuniculus::CUNICULUS_DLX_EXCHANGE }
       )
@@ -38,7 +43,7 @@ module Cuniculus
 
         q = channel.queue(
           queue_name,
-          durable: true,
+          durable: durable,
           exclusive: false,
           arguments: {
             "x-dead-letter-exchange" => Cuniculus::CUNICULUS_EXCHANGE,

data/lib/cuniculus/supervisor.rb

@@ -37,9 +37,9 @@ module Cuniculus
 
     def create_consumers(conn, queues)
       consumers = []
-      consumer_pool_size = 5
       queues.each do |_name, q_cfg|
-        ch = conn.create_channel(nil, consumer_pool_size)
+        ch = conn.create_channel(nil, q_cfg.thread_pool_size)
+        ch.prefetch(q_cfg.prefetch_count) if q_cfg.prefetch_count
         consumers << Cuniculus::Consumer.new(q_cfg, ch)
       end
       consumers

data/lib/cuniculus/version.rb

@@ -6,11 +6,11 @@ module Cuniculus
 
   # The minor version of Cuniculus. Bumped for every non-patch level
   # release.
-  MINOR = 0
+  MINOR = 1
 
   # The tiny version of Cuniculus.  Usually 0, only bumped for bugfix
   # releases that fix regressions from previous versions.
-  TINY  = 1
+  TINY  = 0
 
   # The version of Cuniculus you are using, as a string (e.g. "2.11.0")
   VERSION = [MAJOR, MINOR, TINY].join(".").freeze

data/lib/cuniculus/worker.rb

@@ -7,15 +7,67 @@ module Cuniculus
   module Worker
     def self.included(base)
       base.extend(ClassMethods)
+
+      # Dev note:
+      # The point here is to allow options set via cuniculus_options to be
+      # inherited by subclasses.
+      # When reading the options, a subclass will call the singleton method cun_opts.
+      # If the subclass doesn't redefine this method via a call to cuniculus_options,
+      # it will still use the definition from its parent class.
+      base.define_singleton_method("cun_opts=") do |opts|
+        singleton_class.class_eval do
+          define_method("cun_opts") { opts }
+        end
+      end
     end
 
     module ClassMethods
+      DEFAULT_OPTS = { "queue" => "cun_default" }.freeze
+      VALID_OPT_KEYS = %w[queue].freeze
+
+      # Read-only cuniculus option values
+      #
+      # @return opts [Hash] hash with current values
+      def cun_opts
+        DEFAULT_OPTS
+      end
+
+      # Worker-specific options for running cuniculus.
+      #
+      # Note that options set on a worker class are inherited by its subclasses.
+      #
+      # @param opts [Hash]
+      # @option opts [String] "queue" ("cun_default") Name of the underlying RabbitMQ queue.
+      #
+      # @example Change the queue name of a worker
+      #   class MyWorker
+      #     include Cuniculus::Worker
+      #
+      #     cuniculus_options queue: "critical"
+      #
+      #     def perform
+      #       # run the task
+      #     end
+      #   end
+      def cuniculus_options(opts)
+        opts = validate_opts!(opts)
+        self.cun_opts = opts
+      end
+
+      def validate_opts!(opts)
+        raise WorkerOptionsError, "Argument passed to 'cuniculus_options' should be a Hash" unless opts.is_a?(Hash)
+        opts = opts.transform_keys(&:to_s)
+        invalid_keys = opts.keys - VALID_OPT_KEYS
+        raise WorkerOptionsError, "Invalid keys passed to 'cuniculus_options': #{invalid_keys.inspect}" unless invalid_keys.empty?
+        opts
+      end
+
       def perform_async(*args)
         publish({ "class" => self, "args" => args })
       end
 
       def publish(item)
-        routing_key = "cun_default"
+        routing_key = cun_opts["queue"]
         payload = normalize_item(item)
         Cuniculus::RMQPool.with_exchange do |x|
           x.publish(payload, { routing_key: routing_key, persistent: true })

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: cuniculus
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.1.0
 platform: ruby
 authors:
 - Marcelo Pereira
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2021-02-14 00:00:00.000000000 Z
+date: 2021-03-07 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bunny
@@ -52,6 +52,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: rack
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: redcarpet
   requirement: !ruby/object:Gem::Requirement
@@ -94,6 +108,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: toxiproxy
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: warning
   requirement: !ruby/object:Gem::Requirement
@@ -108,6 +136,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: webrick
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: yard
   requirement: !ruby/object:Gem::Requirement