hutch 1.3.1 → 1.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 02b687d56ec0d56dc49c07722e3e55c3b86ca274008394209b3fe60d6ecb8bf4
-  data.tar.gz: a6c38c9b5f26944f7abb3b078d4cf693bb29ed2fb08987b7f4bc5e4fe2a70f78
+  metadata.gz: d9ca80c1f8e42d188755ed5bc94834a841a3935f962e977f3fe01bc17753bdf7
+  data.tar.gz: '0149d00db0ebe07503caf6fd955a051cbc71581e2190a44f91c1128a9ebc3744'
 SHA512:
-  metadata.gz: 85513bc753214f4a077c4a50510519082e3f5bc8aee75cba1df09461be9723e4a8d438a97f3c6bd3025fb59a0d7008adb5577c7faee082367ddd85f7239f748a
-  data.tar.gz: f0d6fcc77c94a0349104243c3daac3e2f4fe057ce96a4b251c0577969fcaf1b69860ca3eadd163aac353275bbe517847573f6064ea46cad70aa8979004c6e9f7
+  metadata.gz: 5f1432e36ee499275c334b3f39268f2907ab842e766cc0dded754abeaca771692e7a11be8ef3d48c3c2f6e6a6ba1690de5ac5381db5dd0d1cde00cb1f65d7ffa
+  data.tar.gz: 16d5ef22b69e7468e097a2dacb49b736d27245e586767e013763f577bf69918f0b44f507ddc59c90ba116e9d473eeba3a5acdd8a95cb4b7407d5c899cadc0ebb

data/.github/workflows/test.yml

@@ -1,50 +1,68 @@
-name: Test
+name: CI
 
 concurrency:
   group: ${{ github.ref }}
   cancel-in-progress: true
 
-on: [push,pull_request,workflow_dispatch]
+on:
+  push:
+    branches:
+      - "main"
+  pull_request:
+    branches:
+      - "main"
+  workflow_dispatch:
 
 jobs:
   test:
-
+    name: RabbitMQ ${{ matrix.rabbitmq }}, Ruby ${{ matrix.ruby }}
     runs-on: ubuntu-latest
 
+    strategy:
+      fail-fast: false
+      matrix:
+        ruby:
+          - "4.0"
+          - "3.4"
+          - "3.3"
+          - "3.2"
+          - "3.1"
+          - "3.0"
+        rabbitmq:
+          - "4.2"
+          - "4.1"
+          - "4.0"
+          - "3.13"
+
+    env:
+      CI: true
+
     services:
       rabbitmq:
-        image: rabbitmq:3-management
+        image: rabbitmq:${{ matrix.rabbitmq }}-management
         ports:
           - 5672:5672
           - 15672:15672
         options: --name rabbitmq
 
-    strategy:
-      fail-fast: false
-      matrix:
-        ruby-version:
-          - '2.7'
-          - '3.0'
-          - '3.1'
-          - '3.2'
-          - '3.3'
-
     steps:
-    - uses: actions/checkout@v4
-    - name: Set up Ruby
-    # To automatically get bug fixes and new Ruby versions for ruby/setup-ruby,
-    # change this to (see https://github.com/ruby/setup-ruby#versioning):
-      uses: ruby/setup-ruby@v1
-    # uses: ruby/setup-ruby@473e4d8fe5dd94ee328fdfca9f8c9c7afc9dae5e
-      with:
-        ruby-version: ${{ matrix.ruby-version }}
-        bundler-cache: true # runs 'bundle install' and caches installed gems automatically
-    - name: Set up RabbitMQ
-      run: |
-        until sudo lsof -i:5672; do echo "Waiting for RabbitMQ to start..."; sleep 1; done
-        ./bin/ci/before_build_docker.sh
-    - name: Run tests
-      run: bundle exec rspec spec
+      - uses: actions/checkout@v4
+
+      - name: Set up Ruby ${{ matrix.ruby }}
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: ${{ matrix.ruby }}
+          bundler-cache: true
+
+      - name: Wait for RabbitMQ to start
+        run: sleep 10
+
+      - name: Set up RabbitMQ
+        run: ./bin/ci/before_build_docker.sh
+
+      - name: Run tests
+        run: bundle exec rspec spec
+
   test_all:
     if: ${{ always() }}
     runs-on: ubuntu-latest

data/AGENTS.md

@@ -0,0 +1,127 @@
+# Instructions for AI Agents
+
+## Overview
+
+Hutch is a Ruby library for enabling asynchronous inter-service communication
+using RabbitMQ. It provides a conventions-based framework for consumers and
+producers using topic exchanges.
+
+Its key dependencies are [Bunny](https://github.com/ruby-amqp/bunny) (MRI Ruby)
+or [March Hare](https://github.com/ruby-amqp/march_hare) (JRuby), two RabbitMQ clients that use AMQP 0-9-1.
+
+On top, Hutch uses [carrot-top](https://github.com/change/carrot-top) for the RabbitMQ HTTP API,
+and [ActiveSupport](https://github.com/rails/rails/tree/main/activesupport) from Ruby on Rails.
+
+## Target Ruby Version
+
+This library targets Ruby 3.0 and later versions
+For JRuby, the supported series are 9.x and 10.x.
+
+## Build and Test
+
+```bash
+bundle install
+
+bundle exec rspec spec
+```
+
+To run tests use `rspec` directly (not Rake).
+
+## Key Files
+
+### Core
+
+ * `lib/hutch.rb`: top-level module, global consumer registry, a connection singleton
+ * `lib/hutch/broker.rb`: RabbitMQ connection and channel lifecycle, topology declaration, [delivery acknowledgements](https://www.rabbitmq.com/docs/confirms), [publisher confirms](https://www.rabbitmq.com/docs/confirms), [TLS](https://www.rabbitmq.com/docs/ssl), HTTP API client
+ * `lib/hutch/worker.rb`: the main consumer loop: topology and consumer setup, delivery dispatch, error handling
+ * `lib/hutch/consumer.rb`: `Hutch::Consumer` module included by consumer classes; DSL: `consume`, `queue_name`, `lazy_queue`, `quorum_queue`, `arguments`, `queue_options`, `serializer`
+ * `lib/hutch/publisher.rb`: message serialization, routing, publisher confirms
+ * `lib/hutch/message.rb`: message wrapper (delivery_info, properties, payload)
+ * `lib/hutch/config.rb`: configuration with 3-tier precedence (defaults < ENV `HUTCH_*` < config file < explicit set)
+ * `lib/hutch/cli.rb`: CLI (based on `OptionParser`), Rails app detection, consumer loading, daemonization
+ * `lib/hutch/exceptions.rb`: `ConnectionError`, `AuthenticationError`, `WorkerSetupError`, `PublishError`
+ * `lib/hutch/logging.rb`: configurable logger with `HutchFormatter`
+ * `lib/hutch/waiter.rb`: signal handling (`SIGINT`, `SIGTERM`, `SIGQUIT` for shutdown; `SIGUSR2` for thread dumps)
+ * `lib/hutch/version.rb`: the `Hutch::VERSION` constant
+
+### Adapters
+
+ * `lib/hutch/adapter.rb`: runtime adapter selector (Bunny on MRI, March Hare on JRuby)
+ * `lib/hutch/adapters/bunny.rb`: Bunny adapter
+ * `lib/hutch/adapters/march_hare.rb`: March Hare adapter
+
+### Serializers
+
+ * `lib/hutch/serializers/json.rb`: JSON serialization via `multi_json`
+ * `lib/hutch/serializers/identity.rb`: pass-through (no-op) serializer
+
+### Error Handlers
+
+ * `lib/hutch/error_handlers/base.rb`: base class
+ * `lib/hutch/error_handlers/logger.rb`: logs errors (default)
+ * `lib/hutch/error_handlers/sentry.rb`: sentry-ruby integration
+ * `lib/hutch/error_handlers/sentry_raven.rb`: legacy sentry-raven integration
+ * `lib/hutch/error_handlers/honeybadger.rb`: Honeybadger
+ * `lib/hutch/error_handlers/airbrake.rb`: Airbrake
+ * `lib/hutch/error_handlers/rollbar.rb`: Rollbar
+ * `lib/hutch/error_handlers/bugsnag.rb`: Bugsnag
+
+### Tracers
+
+ * `lib/hutch/tracers/null_tracer.rb`: no-op (default)
+ * `lib/hutch/tracers/newrelic.rb`: NewRelic APM
+ * `lib/hutch/tracers/datadog.rb`: Datadog tracing
+
+### Acknowledgement Strategies
+
+ * `lib/hutch/acknowledgements/base.rb`: base interface (a chain of responsibility)
+ * `lib/hutch/acknowledgements/nack_on_all_failures.rb`: the default fallback
+
+## Test Suite
+
+The test suite uses RSpec:
+
+```bash
+bundle exec rspec spec
+```
+
+Test files mirror the `lib/hutch/` structure under `spec/hutch/`. Tests are filtered
+by adapter at runtime: Bunny specs are excluded on JRuby, March Hare specs on MRI.
+
+## Comments
+
+ * Only add important comments that express the non-obvious intent, both in tests and in the implementation
+ * Keep the comments short
+ * Pay attention to the grammar of your comments, including punctuation, full stops, articles, and so on
+
+## Change Log
+
+If asked to perform change log updates, consult and modify `CHANGELOG.md` and stick to its
+existing writing style.
+
+## Releases
+
+### How to Roll (Produce) a New Release
+
+Suppose the current development version in `CHANGELOG.md` has
+a `## X.Y.0 (in development)` section at the top.
+
+To produce a new release:
+
+ 1. Update `CHANGELOG.md`: replace `(in development)` with today's date, e.g. `(Mar 30, 2026)`. Make sure all notable changes since the previous release are listed
+ 2. Update the version in `lib/hutch/version.rb` to match (remove the `.pre` suffix)
+ 3. Commit with the message `X.Y.0` (just the version number, nothing else)
+ 4. Tag the commit: `git tag vX.Y.0`
+ 5. Bump the dev version: add a new `## X.(Y+1).0 (in development)` section to `CHANGELOG.md` with `No changes yet.` underneath, and update `lib/hutch/version.rb` to the next dev version with a `.pre` suffix
+ 6. Commit with the message `Bump dev version`
+ 7. Push: `git push && git push origin vX.(Y+1).0`
+
+## Git Instructions
+
+ * Do not commit changes automatically without an explicit permission to do so
+ * Never add yourself to the list of commit co-authors
+ * Never mention yourself in commit messages in any way (no "Generated by", no AI tool links, etc)
+
+## Style Guide
+
+ * Never add full stops to Markdown list items

data/CHANGELOG.md

@@ -1,8 +1,51 @@
-## 1.3.2 (in development)
+## 1.4.0 (Apr 7, 2026)
 
-No changes yet.
+### Ruby 3.0 is Now Required
 
-## 1.3.1 (Dec 11, 2024)
+This version adopts [Bunny `3.x`](https://github.com/ruby-amqp/bunny/releases/tag/3.0.0)
+and as a result, requires Ruby 3.0.
+
+### `without_namespace` Consumer DSL Option
+
+Consumers can now opt out of the automatic namespace prefix
+for their queue name using the `without_namespace` DSL method:
+
+``` ruby
+class DeadLetterConsumer
+  include Hutch::Consumer
+  consume 'dead.letters'
+  queue_name 'deadletter'
+  without_namespace
+end
+```
+
+Originally contributed by @tlloydthwaites.
+
+GitHub issue: [#393](https://github.com/ruby-amqp/hutch/pull/393)
+
+### Consumer Channel Recovery After Delivery Acknowledgement Timeout
+
+Hutch now automatically "recovers" (reopens) consumer channels closed by RabbitMQ
+due to a [delivery acknowledgement timeout](https://www.rabbitmq.com/docs/consumers#acknowledgement-timeout).
+
+Note that this exception indicates a potential issue on Hutch's end:
+a delivery was not acknowledged in time (30 minutes by default). Even then,
+recovering the channel in this specific scenario is an operational improvement.
+
+Contributed by @Garaio-REM.
+
+GitHub issue: [#414](https://github.com/ruby-amqp/hutch/pull/414)
+
+### Migrated Datadog Tracer From the `ddtrace` Gem to `datadog`
+
+The Datadog tracer now uses the `datadog` gem instead of the deprecated `ddtrace`.
+The `ddtrace` gem is still supported but emits a deprecation warning at load time.
+Support for `ddtrace` will be removed in Hutch 2.0.
+
+### Deprecated `SentryRaven` Error Handler
+
+`Hutch::ErrorHandlers::SentryRaven` now emits a deprecation warning and will be
+removed in Hutch 2.0. Use `Hutch::ErrorHandlers::Sentry` (backed by `sentry-ruby`) instead.
 
 ### Rails 8.x Compatibility
 
@@ -19,7 +62,7 @@ GitHub issue: [#392](https://github.com/ruby-amqp/hutch/pull/392)
 
 ### Relaxed ActiveSupport Dependency Constraints
 
-Contributed by @drobny.
+Contributed by drobny.
 
 GitHub issue: [#402](https://github.com/ruby-amqp/hutch/pull/402)
 
@@ -93,7 +136,7 @@ contains potentially breaking changes.
 
    This means **some defaults introduced in `0.28.0` ([gocardless/hutch#341](https://github.com/gocardless/hutch/pull/341)) were reverted**.
    The user has to opt in to configure the queue type and mode and other [optional arguments](https://www.rabbitmq.com/queues.html#optional-arguments) they need to use.
-   Most optional arguments can be set via [policies](https://www.rabbitmq.com/parameters.html#policies) which is always the recommended approach. 
+   Most optional arguments can be set via [policies](https://www.rabbitmq.com/parameters.html#policies) which is always the recommended approach.
    Queue type, unfortunately, is not one of them as different queue types have completely different
    implementation details, on disk data formats and so on.
 
@@ -106,7 +149,7 @@ contains potentially breaking changes.
       # when in doubt, prefer using a policy to this DSL
       # https://www.rabbitmq.com/parameters.html#policies
       arguments 'x-key': :value
-        
+
       quorum_queue
    end
    ```
@@ -120,7 +163,7 @@ contains potentially breaking changes.
      # when in doubt, prefer using a policy to this DSL
       # https://www.rabbitmq.com/parameters.html#policies
       arguments 'x-key': :value
-     
+
      lazy_queue
      classic_queue
    end

data/Gemfile

@@ -1,6 +1,6 @@
 source 'https://rubygems.org'
 
-ruby '>= 2.7.0'
+ruby '>= 3.0.0'
 
 gemspec
 
@@ -23,7 +23,7 @@ group :development, :test do
   gem "sentry-ruby"
   gem "honeybadger"
   gem "newrelic_rpm"
-  gem "ddtrace", "~> 1.8"
+  gem "datadog"
   gem "airbrake", "~> 13.0"
   gem "rollbar"
   gem "bugsnag"

data/bin/ci/before_build_docker.sh

@@ -1,11 +1,6 @@
 #!/bin/sh
 
 CTL=${MARCH_HARE_RABBITMQCTL:="docker exec rabbitmq rabbitmqctl"}
-PLUGINS=${MARCH_HARE_RABBITMQ_PLUGINS:="docker exec rabbitmq rabbitmq-plugins"}
-
-$PLUGINS enable rabbitmq_management
-
-sleep 3
 
 # guest:guest has full access to /
 
@@ -14,7 +9,7 @@ $CTL add_vhost /
 $CTL set_permissions -p / guest ".*" ".*" ".*"
 
 # Reduce retention policy for faster publishing of stats
-$CTL eval 'supervisor2:terminate_child(rabbit_mgmt_sup_sup, rabbit_mgmt_sup), application:set_env(rabbitmq_management,       sample_retention_policies, [{global, [{605, 1}]}, {basic, [{605, 1}]}, {detailed, [{10, 1}]}]), rabbit_mgmt_sup_sup:start_child().'
-$CTL eval 'supervisor2:terminate_child(rabbit_mgmt_agent_sup_sup, rabbit_mgmt_agent_sup), application:set_env(rabbitmq_management_agent, sample_retention_policies, [{global, [{605, 1}]}, {basic, [{605, 1}]}, {detailed, [{10, 1}]}]), rabbit_mgmt_agent_sup_sup:start_child().'
+$CTL eval 'supervisor2:terminate_child(rabbit_mgmt_sup_sup, rabbit_mgmt_sup), application:set_env(rabbitmq_management,       sample_retention_policies, [{global, [{605, 1}]}, {basic, [{605, 1}]}, {detailed, [{10, 1}]}]), rabbit_mgmt_sup_sup:start_child().' || true
+$CTL eval 'supervisor2:terminate_child(rabbit_mgmt_agent_sup_sup, rabbit_mgmt_agent_sup), application:set_env(rabbitmq_management_agent, sample_retention_policies, [{global, [{605, 1}]}, {basic, [{605, 1}]}, {detailed, [{10, 1}]}]), rabbit_mgmt_agent_sup_sup:start_child().' || true
 
 sleep 3

data/hutch.gemspec

@@ -3,10 +3,10 @@ require File.expand_path('../lib/hutch/version', __FILE__)
 Gem::Specification.new do |gem|
   if defined?(JRUBY_VERSION)
     gem.platform = 'java'
-    gem.add_runtime_dependency 'march_hare', '>= 4.5.0'
+    gem.add_runtime_dependency 'march_hare', '>= 4.7.0'
   else
     gem.platform = Gem::Platform::RUBY
-    gem.add_runtime_dependency 'bunny', '>= 2.23', '< 3.0'
+    gem.add_runtime_dependency 'bunny', '>= 3.1', '< 4.0'
   end
   gem.add_runtime_dependency 'carrot-top', '~> 0.0.7'
   gem.add_runtime_dependency 'multi_json', '~> 1.15'
@@ -16,7 +16,7 @@ Gem::Specification.new do |gem|
   gem.summary = 'Opinionated asynchronous inter-service communication using RabbitMQ'
   gem.description = 'Hutch is a Ruby library for enabling asynchronous inter-service communication using RabbitMQ'
   gem.version = Hutch::VERSION.dup
-  gem.required_ruby_version = '>= 2.6'
+  gem.required_ruby_version = '>= 3.0'
   gem.authors = ['Harry Marr', 'Michael Klishin']
   gem.homepage = 'https://github.com/ruby-amqp/hutch'
   gem.require_paths = ['lib']

data/lib/hutch/adapters/bunny.rb

@@ -11,7 +11,7 @@ module Hutch
       ConnectionRefused = Bunny::TCPConnectionFailed
       PreconditionFailed = Bunny::PreconditionFailed
 
-      def_delegators :@connection, :start, :disconnect, :close, :create_channel, :open?
+      def_delegators :@connection, :start, :disconnect, :close, :create_channel, :open?, :recover_channel_topology
 
       def initialize(opts={})
         @connection = Bunny.new(opts)

data/lib/hutch/broker.rb

@@ -1,7 +1,6 @@
 require 'active_support/core_ext/object/blank'
 
 require 'carrot-top'
-require 'ostruct'
 require 'hutch/logging'
 require 'hutch/exceptions'
 require 'hutch/publisher'
@@ -114,6 +113,8 @@ module Hutch
           logger.info 'enabling publisher confirms'
           ch.confirm_select
         end
+
+        install_channel_recovery!(ch)
       end
     end
 
@@ -121,6 +122,20 @@ module Hutch
       @channel = open_channel
     end
 
+    def install_channel_recovery!(ch)
+      ch.on_error do |channel, close|
+        next unless close.delivery_ack_timeout?
+
+        begin
+          channel.reopen
+          connection.recover_channel_topology(channel)
+          logger.warn 'recovered consumer channel after a delivery acknowledgement timeout'
+        rescue => ex
+          logger.error "channel recovery failed: #{ex.class}: #{ex.message}"
+        end
+      end
+    end
+
     def declare_exchange(ch = channel)
       exchange_name = @config[:mq_exchange]
       exchange_type = @config[:mq_exchange_type]
@@ -171,15 +186,19 @@ module Hutch
       @config[:tracer] && @config[:tracer] != Hutch::Tracers::NullTracer
     end
 
-    # Create / get a durable queue and apply namespace if it exists.
+    # Create / get a durable queue.
     def queue(name, options = {})
       with_bunny_precondition_handler('queue') do
-        namespace = @config[:namespace].to_s.downcase.gsub(/[^-_:\.\w]/, "")
-        queue_name = namespace.present? ? "#{namespace}:#{name}" : name
-        channel.queue(queue_name, **options)
+        channel.queue(name, **options)
       end
     end
 
+    # Apply the configured namespace prefix to a queue name.
+    def namespaced_queue_name(name)
+      namespace = @config[:namespace].to_s.downcase.gsub(/[^-_:\.\w]/, "")
+      namespace.present? ? "#{namespace}:#{name}" : name
+    end
+
     # Return a mapping of queue names to the routing keys they're bound to.
     def bindings
       results = Hash.new { |hash, key| hash[key] = [] }
@@ -269,8 +288,11 @@ module Hutch
 
     private
 
+    Config = Struct.new(:host, :port, :username, :password, :ssl, :protocol, :sanitized_uri)
+    private_constant :Config
+
     def api_config
-      @api_config ||= OpenStruct.new.tap do |config|
+      @api_config ||= Config.new.tap do |config|
         config.host = @config[:mq_api_host]
         config.port = @config[:mq_api_port]
         config.username = @config[:mq_username]

data/lib/hutch/consumer.rb

@@ -47,6 +47,15 @@ module Hutch
         @queue_name = name
       end
 
+      # Opt out of the namespace prefix for this consumer's queue
+      def without_namespace
+        @without_namespace = true
+      end
+
+      def without_namespace?
+        !!@without_namespace
+      end
+
       # Explicitly set the queue mode to 'lazy'
       def lazy_queue
         @queue_mode = 'lazy'

data/lib/hutch/error_handlers/sentry_raven.rb

@@ -10,6 +10,9 @@ module Hutch
         unless Raven.respond_to?(:capture_exception)
           raise "The Hutch Sentry error handler requires Raven >= 0.4.0"
         end
+
+        warn "[DEPRECATION] Hutch::ErrorHandlers::SentryRaven is deprecated and will be removed in Hutch 2.0. " \
+             "Use Hutch::ErrorHandlers::Sentry (backed by the sentry-ruby gem) instead." \
       end
 
       def handle(properties, payload, consumer, ex)

data/lib/hutch/tracers/datadog.rb

@@ -1,5 +1,12 @@
-require 'ddtrace'
-require 'ddtrace/auto_instrument'
+begin
+  require 'datadog'
+  require 'datadog/auto_instrument'
+rescue LoadError
+  require 'ddtrace'
+  require 'ddtrace/auto_instrument'
+  warn "[DEPRECATION] The ddtrace gem is deprecated and Hutch will require the datadog gem in 2.0. " \
+       "Please switch to the datadog gem."
+end
 
 module Hutch
   module Tracers

data/lib/hutch/version.rb

@@ -1,3 +1,3 @@
 module Hutch
-  VERSION = '1.3.1'.freeze
+  VERSION = '1.4.0'.freeze
 end

data/lib/hutch/worker.rb

@@ -45,9 +45,11 @@ module Hutch
     # Bind a consumer's routing keys to its queue, and set up a subscription to
     # receive messages sent to the queue.
     def setup_queue(consumer)
-      logger.info "setting up queue: #{consumer.get_queue_name}"
+      queue_name = consumer.get_queue_name
+      queue_name = @broker.namespaced_queue_name(queue_name) unless consumer.without_namespace?
+      logger.info "setting up queue: #{queue_name}"
 
-      queue = @broker.queue(consumer.get_queue_name, consumer.get_options)
+      queue = @broker.queue(queue_name, consumer.get_options)
       @broker.bind_queue(queue, consumer.routing_keys)
 
       queue.subscribe(consumer_tag: unique_consumer_tag, manual_ack: true) do |*args|

data/spec/hutch/broker_spec.rb

@@ -95,7 +95,7 @@ describe Hutch::Broker do
 
     context 'when configured with a URI' do
       context 'which specifies the port' do
-        before { config[:uri] = 'amqp://guest:guest@127.0.0.1:5672/' }
+        before { config[:uri] = "amqp://#{config[:mq_username]}:#{config[:mq_password]}@#{config[:mq_host]}:#{config[:mq_port]}/" }
 
         it 'successfully connects' do
           c = broker.open_connection
@@ -105,7 +105,7 @@ describe Hutch::Broker do
       end
 
       context 'which does not specify port and uses the amqp scheme' do
-        before { config[:uri] = 'amqp://guest:guest@127.0.0.1/' }
+        before { config[:uri] = "amqp://#{config[:mq_username]}:#{config[:mq_password]}@#{config[:mq_host]}/" }
 
         it 'successfully connects' do
           c = broker.open_connection
@@ -115,7 +115,7 @@ describe Hutch::Broker do
       end
 
       context 'which specifies the amqps scheme' do
-        before { config[:uri] = 'amqps://guest:guest@127.0.0.1/' }
+        before { config[:uri] = "amqps://#{config[:mq_username]}:#{config[:mq_password]}@#{config[:mq_host]}/" }
 
         it 'utilises TLS' do
           expect(Hutch::Adapter).to receive(:new).with(
@@ -256,16 +256,30 @@ describe Hutch::Broker do
     let(:arguments) { { foo: :bar } }
     before { allow(broker).to receive(:channel) { channel } }
 
-    it 'applies a global namespace' do
-      config[:namespace] = 'mirror-all.service'
-      expect(broker.channel).to receive(:queue) do |*args|
-        args.first == ''
-        args.last == arguments
-      end
+    it 'creates a queue with the given name' do
+      expect(broker.channel).to receive(:queue).with('test', arguments: arguments)
       broker.queue('test'.freeze, arguments: arguments)
     end
   end
 
+  describe '#namespaced_queue_name' do
+    context 'with a namespace configured' do
+      before { config[:namespace] = 'mirror-all.service' }
+
+      it 'prepends the namespace' do
+        expect(broker.namespaced_queue_name('test')).to eq('mirror-all.service:test')
+      end
+    end
+
+    context 'without a namespace configured' do
+      before { config[:namespace] = nil }
+
+      it 'returns the name unchanged' do
+        expect(broker.namespaced_queue_name('test')).to eq('test')
+      end
+    end
+  end
+
   describe '#bindings', rabbitmq: true do
     around { |example| broker.connect { example.run } }
     subject { broker.bindings }

data/spec/hutch/consumer_spec.rb

@@ -97,6 +97,17 @@ describe Hutch::Consumer do
     end
   end
 
+  describe '.without_namespace' do
+    it 'is false by default' do
+      expect(simple_consumer.without_namespace?).to eq(false)
+    end
+
+    it 'returns true after calling without_namespace' do
+      simple_consumer.without_namespace
+      expect(simple_consumer.without_namespace?).to eq(true)
+    end
+  end
+
   describe 'default queue mode' do
     it 'does not specify any mode by default' do
       expect(simple_consumer.queue_mode).to eq(nil)

data/spec/hutch/error_handlers/airbrake_spec.rb

@@ -14,7 +14,7 @@ describe Hutch::ErrorHandlers::Airbrake do
 
     it "logs the error to Airbrake" do
       message_id = "1"
-      properties = OpenStruct.new(message_id: message_id)
+      properties = Struct.new(:message_id).new(message_id)
       payload = "{}"
       consumer = double
       ex = error

data/spec/hutch/error_handlers/bugsnag_spec.rb

@@ -23,7 +23,7 @@ describe Hutch::ErrorHandlers::Bugsnag do
 
     it "logs the error to Bugsnag" do
       message_id = "1"
-      properties = OpenStruct.new(message_id: message_id)
+      properties = Struct.new(:message_id).new(message_id)
       payload = "{}"
       consumer = double
       ex = error

data/spec/hutch/error_handlers/honeybadger_spec.rb

@@ -14,7 +14,7 @@ describe Hutch::ErrorHandlers::Honeybadger do
 
     it "logs the error to Honeybadger" do
       message_id = "1"
-      properties = OpenStruct.new(message_id: message_id)
+      properties = Struct.new(:message_id).new(message_id)
       payload = "{}"
       consumer = double
       ex = error

data/spec/hutch/error_handlers/logger_spec.rb

@@ -4,7 +4,7 @@ describe Hutch::ErrorHandlers::Logger do
   let(:error_handler) { Hutch::ErrorHandlers::Logger.new }
 
   describe '#handle' do
-    let(:properties) { OpenStruct.new(message_id: "1") }
+    let(:properties) { Struct.new(:message_id).new("1") }
     let(:payload) { "{}" }
     let(:error) { double(message: "Stuff went wrong", class: "RuntimeError",
                        backtrace: ["line 1", "line 2"]) }

data/spec/hutch/error_handlers/rollbar_spec.rb

@@ -14,7 +14,7 @@ describe Hutch::ErrorHandlers::Rollbar do
 
     it "logs the error to Rollbar" do
       message_id = "1"
-      properties = OpenStruct.new(message_id: message_id)
+      properties = Struct.new(:message_id).new(message_id)
       payload = "{}"
       consumer = double
       ex = error

data/spec/hutch/error_handlers/sentry_raven_spec.rb

@@ -4,7 +4,7 @@ describe Hutch::ErrorHandlers::SentryRaven do
   let(:error_handler) { Hutch::ErrorHandlers::SentryRaven.new }
 
   describe '#handle' do
-    let(:properties) { OpenStruct.new(message_id: "1") }
+    let(:properties) { Struct.new(:message_id).new("1") }
     let(:payload) { "{}" }
     let(:error) do
       begin

data/spec/hutch/error_handlers/sentry_spec.rb

@@ -12,7 +12,7 @@ describe Hutch::ErrorHandlers::Sentry do
   end
 
   describe '#handle' do
-    let(:properties) { OpenStruct.new(message_id: "1") }
+    let(:properties) { Struct.new(:message_id).new("1") }
     let(:payload) { "{}" }
     let(:error) do
       begin

data/spec/hutch/tracers/datadog_spec.rb

@@ -16,7 +16,7 @@ RSpec.describe Hutch::Tracers::Datadog do
         end
 
         def class
-          OpenStruct.new(name: 'ClassName')
+          Struct.new(:name).new('ClassName')
         end
 
         def process(message)

data/spec/hutch/worker_spec.rb

@@ -4,7 +4,8 @@ require 'hutch/worker'
 describe Hutch::Worker do
   let(:consumer) { double('Consumer', routing_keys: %w( a b c ),
                           get_queue_name: 'consumer', get_arguments: {},
-                          get_options: {}, get_serializer: nil) }
+                          get_options: {}, get_serializer: nil,
+                          without_namespace?: false) }
   let(:consumers) { [consumer, double('Consumer')] }
   let(:broker) { Hutch::Broker.new }
   let(:setup_procs) { Array.new(2) { Proc.new {} } }
@@ -32,13 +33,27 @@ describe Hutch::Worker do
 
   describe '#setup_queue' do
     let(:queue) { double('Queue', bind: nil, subscribe: nil) }
-    before { allow(broker).to receive_messages(queue: queue, bind_queue: nil) }
+    before { allow(broker).to receive_messages(queue: queue, bind_queue: nil, namespaced_queue_name: 'consumer') }
 
-    it 'creates a queue' do
-      expect(broker).to receive(:queue).with(consumer.get_queue_name, consumer.get_options).and_return(queue)
+    it 'creates a queue with a namespaced name' do
+      expect(broker).to receive(:namespaced_queue_name).with('consumer').and_return('ns:consumer')
+      expect(broker).to receive(:queue).with('ns:consumer', consumer.get_options).and_return(queue)
       worker.setup_queue(consumer)
     end
 
+    context 'when the consumer uses without_namespace' do
+      let(:consumer) { double('Consumer', routing_keys: %w( a b c ),
+                              get_queue_name: 'consumer', get_arguments: {},
+                              get_options: {}, get_serializer: nil,
+                              without_namespace?: true) }
+
+      it 'creates a queue without applying the namespace' do
+        expect(broker).not_to receive(:namespaced_queue_name)
+        expect(broker).to receive(:queue).with('consumer', consumer.get_options).and_return(queue)
+        worker.setup_queue(consumer)
+      end
+    end
+
     it 'binds the queue to each of the routing keys' do
       expect(broker).to receive(:bind_queue).with(queue, %w( a b c ))
       worker.setup_queue(consumer)
@@ -61,6 +76,7 @@ describe Hutch::Worker do
     context 'with a configured consumer tag prefix that is too long' do
       let(:maximum_size) { 255 - SecureRandom.uuid.size - 1 }
       before { Hutch::Config.set(:consumer_tag_prefix, 'a'.*(maximum_size + 1)) }
+      after { Hutch::Config.set(:consumer_tag_prefix, 'hutch') }
 
       it 'raises an error' do
         expect { worker.setup_queue(consumer) }.to raise_error(/Tag must be 255 bytes long at most/)

data/spec/integration/channel_recovery_spec.rb

@@ -0,0 +1,139 @@
+require 'spec_helper'
+require 'hutch/broker'
+require 'hutch/worker'
+require 'hutch/consumer'
+require 'bunny'
+require 'json'
+require 'securerandom'
+require 'timeout'
+
+describe 'channel recovery after delivery acknowledgement timeout', rabbitmq: true, adapter: :bunny do
+  let(:log) { StringIO.new }
+  let(:logger) { Logger.new(log) }
+  let(:exchange_name) { "hutch.integration.exchange.#{SecureRandom.hex(4)}" }
+  let(:queue_name) { "hutch.integration.queue.#{SecureRandom.hex(4)}" }
+  let(:routing_key) { "hutch.integration.key.#{SecureRandom.hex(4)}" }
+
+  let(:processed) { [] }
+  let(:processed_lock) { Mutex.new }
+  let(:timed_out_once) { [false] }
+
+  let(:consumer_class) do
+    msgs = processed
+    lock = processed_lock
+    rk = routing_key
+    qn = queue_name
+    timed_out = timed_out_once
+
+    Class.new do
+      include Hutch::Consumer
+
+      consume rk
+      queue_name qn
+      arguments(
+        'x-queue-type' => 'quorum',
+        'x-consumer-timeout' => 60_000
+      )
+
+      define_method(:process) do |message|
+        if message['id'] == 'trigger-timeout' && !timed_out[0]
+          timed_out[0] = true
+          sleep 210
+        end
+
+        lock.synchronize { msgs << message['id'] }
+      end
+    end
+  end
+
+  let(:broker) { Hutch::Broker.new }
+  let(:worker) { Hutch::Worker.new(broker, [consumer_class], []) }
+
+  let(:publisher) do
+    Bunny.new(
+      host: Hutch::Config[:mq_host],
+      port: Hutch::Config[:mq_port],
+      username: Hutch::Config[:mq_username],
+      password: Hutch::Config[:mq_password],
+      vhost: Hutch::Config[:mq_vhost]
+    ).tap(&:start)
+  end
+
+  let(:publisher_channel) { publisher.create_channel }
+  let(:exchange) { publisher_channel.topic(exchange_name, durable: true) }
+
+  before do
+    Hutch::Logging.logger = logger
+    Hutch::Config.set(:mq_exchange, exchange_name)
+    Hutch::Config.set(:force_publisher_confirms, false)
+    Hutch::Config.set(:client_logger, logger)
+  end
+
+  after do
+    publisher_channel.close rescue nil
+    publisher.close rescue nil
+    broker.disconnect rescue nil
+    Hutch::Logging.logger = Logger.new(File::NULL)
+  end
+
+  def wait_for(timeout, label)
+    Timeout.timeout(timeout) do
+      loop do
+        return true if yield
+        sleep 0.25
+      end
+    end
+  rescue Timeout::Error
+    raise <<~MSG
+      Timed out waiting for: #{label}
+
+      processed_messages=#{processed_messages.inspect}
+      channel_open=#{broker.channel.open? rescue 'unknown'}
+      channel_closed=#{broker.channel.closed? rescue 'unknown'}
+
+      log output:
+      #{log_output}
+    MSG
+  end
+
+  def processed_messages
+    processed_lock.synchronize { processed.dup }
+  end
+
+  def log_output
+    log.rewind
+    log.read
+  end
+
+  def publish_message(id)
+    exchange.publish(
+      JSON.dump('id' => id),
+      routing_key: routing_key,
+      content_type: 'application/json',
+      persistent: true
+    )
+  end
+
+  # This spec is intentionally slow because RabbitMQ enforces delivery
+  # acknowledgement timeouts on a periodic sweep, not immediately at the deadline.
+  it 're-subscribes and consumes later messages after RabbitMQ closes the channel for ack timeout' do
+    broker.connect
+    worker.setup_queues
+
+    publish_message('trigger-timeout')
+
+    wait_for(240, 'delivery acknowledgement timeout') do
+      log_output.match?(/delivery acknowledgement on channel \d+ timed out/i)
+    end
+
+    publish_message('after-recovery')
+
+    wait_for(90, 'after-recovery message consumption') do
+      processed_messages.include?('after-recovery')
+    end
+
+    expect(log_output).to match(/delivery acknowledgement on channel \d+ timed out/i)
+    expect(log_output).to match(/recovered consumer channel after a delivery acknowledgement timeout/i)
+    expect(processed_messages).to include('after-recovery')
+  end
+end

data/spec/integration/publish_consume_spec.rb

@@ -0,0 +1,48 @@
+require 'spec_helper'
+require 'hutch/broker'
+require 'hutch/worker'
+require 'hutch/consumer'
+require 'securerandom'
+require 'timeout'
+
+describe 'publishing and consuming messages', rabbitmq: true, adapter: :bunny do
+  let(:exchange_name) { "hutch.test.#{SecureRandom.hex(4)}" }
+  let(:routing_key) { "test.message" }
+  let(:received) { [] }
+
+  let(:consumer_class) do
+    msgs = received
+    rk = routing_key
+    qn = "test_consumer_#{SecureRandom.hex(4)}"
+
+    Class.new do
+      include Hutch::Consumer
+      consume rk
+      queue_name qn
+
+      define_method(:process) { |message| msgs << message.body }
+    end
+  end
+
+  let(:broker) { Hutch::Broker.new }
+  let(:worker) { Hutch::Worker.new(broker, [consumer_class], []) }
+
+  before do
+    Hutch::Config.set(:mq_exchange, exchange_name)
+  end
+
+  after do
+    broker.disconnect rescue nil
+  end
+
+  it 'publishes and consumes a message' do
+    broker.connect
+    worker.setup_queues
+
+    broker.publish(routing_key, { test: 'data' })
+
+    Timeout.timeout(5) { sleep 0.1 until received.any? }
+
+    expect(received.first).to eq('test' => 'data')
+  end
+end

metadata

@@ -1,15 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: hutch
 version: !ruby/object:Gem::Version
-  version: 1.3.1
+  version: 1.4.0
 platform: ruby
 authors:
 - Harry Marr
 - Michael Klishin
-autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-12-11 00:00:00.000000000 Z
+date: 2026-04-08 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bunny
@@ -17,20 +16,20 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '2.23'
+        version: '3.1'
     - - "<"
       - !ruby/object:Gem::Version
-        version: '3.0'
+        version: '4.0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '2.23'
+        version: '3.1'
     - - "<"
       - !ruby/object:Gem::Version
-        version: '3.0'
+        version: '4.0'
 - !ruby/object:Gem::Dependency
   name: carrot-top
   requirement: !ruby/object:Gem::Requirement
@@ -75,7 +74,6 @@ dependencies:
         version: '4.2'
 description: Hutch is a Ruby library for enabling asynchronous inter-service communication
   using RabbitMQ
-email:
 executables:
 - hutch
 extensions: []
@@ -85,6 +83,7 @@ files:
 - ".gitignore"
 - ".rspec"
 - ".yardopts"
+- AGENTS.md
 - CHANGELOG.md
 - Gemfile
 - Guardfile
@@ -150,6 +149,8 @@ files:
 - spec/hutch/waiter_spec.rb
 - spec/hutch/worker_spec.rb
 - spec/hutch_spec.rb
+- spec/integration/channel_recovery_spec.rb
+- spec/integration/publish_consume_spec.rb
 - spec/spec_helper.rb
 - templates/default/class/html/settings.erb
 - templates/default/class/setup.rb
@@ -164,7 +165,6 @@ homepage: https://github.com/ruby-amqp/hutch
 licenses:
 - MIT
 metadata: {}
-post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -172,15 +172,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '2.6'
+      version: '3.0'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.22
-signing_key:
+rubygems_version: 3.6.2
 specification_version: 4
 summary: Opinionated asynchronous inter-service communication using RabbitMQ
 test_files:
@@ -202,4 +201,6 @@ test_files:
 - spec/hutch/waiter_spec.rb
 - spec/hutch/worker_spec.rb
 - spec/hutch_spec.rb
+- spec/integration/channel_recovery_spec.rb
+- spec/integration/publish_consume_spec.rb
 - spec/spec_helper.rb