hutch 0.25.0.pre.rc1-java → 2.0.0.rc1-java

data/README.md

@@ -1,9 +1,5 @@
-![](http://cl.ly/image/3h0q3F3G142K/hutch.png)
-
-[![Gem Version](https://badge.fury.io/rb/hutch.svg)](http://badge.fury.io/rb/hutch)
-[![Build Status](https://travis-ci.org/gocardless/hutch.svg?branch=master)](https://travis-ci.org/gocardless/hutch)
-[![Dependency Status](https://gemnasium.com/gocardless/hutch.svg)](https://gemnasium.com/gocardless/hutch)
-[![Code Climate](https://codeclimate.com/github/gocardless/hutch.svg)](https://codeclimate.com/github/gocardless/hutch)
+[![Gem Version](https://badge.fury.io/rb/hutch.svg)](https://badge.fury.io/rb/hutch)
+[![CI](https://github.com/ruby-amqp/hutch/actions/workflows/test.yml/badge.svg)](https://github.com/ruby-amqp/hutch/actions/workflows/test.yml)
 
 Hutch is a Ruby library for enabling asynchronous inter-service communication
 in a service-oriented architecture, using RabbitMQ.
@@ -25,6 +21,8 @@ gem install hutch
     - [Message Processing Tracers](#message-processing-tracers)
   - [Running Hutch](#running-hutch)
     - [Loading Consumers](#loading-consumers)
+    - [Consumer Groups](#consumer-groups)
+    - [Loading Consumers Manually (One-by-One)](#loading-consumers-manually-one-by-one)
     - [Stopping Hutch](#stopping-hutch)
   - [Producers](#producers)
     - [Producer Configuration](#producer-configuration)
@@ -40,8 +38,8 @@ gem install hutch
 
 ## Requirements
 
-- Hutch requires Ruby 2.0+ or JRuby 9K.
-- Hutch requires RabbitMQ 3.3 or later.
+- Hutch requires Ruby 3.2+ or JRuby 10+
+- Hutch requires RabbitMQ 3.13 or later
 
 ## Overview
 
@@ -54,13 +52,14 @@ With Hutch, consumers are stored in separate files and include the `Hutch::Consu
 They are then loaded by a command line runner which connects to RabbitMQ, sets up queues and bindings,
 and so on. Publishers connect to RabbitMQ via `Hutch.connect` and publish using `Hutch.publish`.
 
-Hutch uses [Bunny](http://rubybunny.info) or [March Hare](http://rubymarchhare.info)
+Hutch uses [Bunny](https://github.com/ruby-amqp/bunny) or [March Hare](https://github.com/ruby-amqp/march_hare)
 (on JRuby) under the hood.
 
 ### Project Maturity
 
-Hutch is a moderately mature project (started in early 2013)
-that was extracted from production systems.
+Hutch is a mature project that was originally extracted from production systems
+at [GoCardless](https://gocardless.com) in 2013 and is now maintained by its contributors
+and users.
 
 ## Consumers
 
@@ -80,7 +79,7 @@ message[:id]  # => "02ABCXYZ"
 To subscribe to a topic, pass a routing key to `consume` in the class
 definition. To bind to multiple routing keys, simply pass extra routing keys
 in as additional arguments. Refer to the [RabbitMQ docs on topic exchanges
-](http://www.rabbitmq.com/tutorials/tutorial-five-ruby.html) for more information
+](https://www.rabbitmq.com/tutorials/tutorial-five-ruby) for more information
 about how to use routing keys. Here's an example consumer:
 
 ```ruby
@@ -109,6 +108,28 @@ class FailedPaymentConsumer
 end
 ```
 
+It is possible to set some custom options to consumer's queue explicitly.
+This example sets the consumer's queue as a
+[quorum queue](https://www.rabbitmq.com/docs/quorum-queues)
+and to operate in the [lazy mode](https://www.rabbitmq.com/docs/lazy-queues).
+The `initial_group_size`
+[argument](https://www.rabbitmq.com/docs/quorum-queues#replication-factor) is
+optional.
+
+```ruby
+class FailedPaymentConsumer
+  include Hutch::Consumer
+  consume 'gc.ps.payment.failed'
+  queue_name 'failed_payments'
+  lazy_queue
+  quorum_queue initial_group_size: 3
+
+  def process(message)
+    mark_payment_as_failed(message[:id])
+  end
+end
+```
+
 You can also set custom arguments per consumer. This example declares a consumer with
 a maximum length of 10 messages:
 
@@ -121,11 +142,11 @@ end
 ```
 
 This sets the `x-max-length` header. For more details, see the [RabbitMQ
-documentation on Queue Length Limit](https://www.rabbitmq.com/maxlength.html). To find out more
-about custom queue arguments, consult the [RabbitMQ documentation on AMQP Protocol Extensions](https://www.rabbitmq.com/extensions.html). 
+documentation on Queue Length Limit](https://www.rabbitmq.com/docs/maxlength). To find out more
+about custom queue arguments, consult the [RabbitMQ documentation on AMQP Protocol Extensions](https://www.rabbitmq.com/docs/extensions).
 
 Consumers can write to Hutch's log by calling the logger method. The logger method returns
-a [Logger object](http://ruby-doc.org/stdlib-2.1.2/libdoc/logger/rdoc/Logger.html).
+a [Logger object](https://docs.ruby-lang.org/en/3.0/Logger.html).
 
 ```ruby
 class FailedPaymentConsumer
@@ -153,7 +174,7 @@ client_logger = Logger.new("/path/to/bunny.log")
 Hutch::Config.set(:client_logger, client_logger)
 ```
 
-See this [RabbitMQ tutorial on topic exchanges](http://www.rabbitmq.com/tutorials/tutorial-five-ruby.html)
+See this [RabbitMQ tutorial on topic exchanges](https://www.rabbitmq.com/tutorials/tutorial-five-ruby)
 to learn more.
 
 ### Message Processing Tracers
@@ -166,7 +187,13 @@ This will enable NewRelic custom instrumentation:
 Hutch::Config.set(:tracer, Hutch::Tracers::NewRelic)
 ```
 
-Batteries included! 
+And this will enable Datadog custom instrumentation:
+
+```ruby
+Hutch::Config.set(:tracer, Hutch::Tracers::Datadog)
+```
+
+Batteries included!
 
 ## Running Hutch
 
@@ -179,7 +206,7 @@ usage: hutch [options]
         --mq-host HOST               Set the RabbitMQ host
         --mq-port PORT               Set the RabbitMQ port
     -t, --[no-]mq-tls                Use TLS for the AMQP connection
-        --mq-tls-cert FILE           Certificate  for TLS client verification
+        --mq-tls-cert FILE           Certificate for TLS client verification
         --mq-tls-key FILE            Private key for TLS client verification
         --mq-exchange EXCHANGE       Set the RabbitMQ exchange
         --mq-vhost VHOST             Set the RabbitMQ vhost
@@ -215,17 +242,59 @@ in the config file, allowing for easy customization.
 
 Using Hutch with a Rails app is simple. Either start Hutch in the working
 directory of a Rails app, or pass the path to a Rails app in with the
-`--require` option. Consumers defined in Rails apps should be placed with in
+`--require` option. Consumers defined in Rails apps should be placed within
 the `app/consumers/` directory, to allow them to be auto-loaded when Rails
 boots.
 
+If you're using the Zeitwerk autoloader (the default since Rails 6)
+and the consumers are not loaded in the development environment, you will need to
+trigger eager loading in an initializer with
+
+```ruby
+::Zeitwerk::Loader.eager_load_all
+```
+
+or with something more specific like
+
+```ruby
+autoloader = Rails.autoloaders.main
+
+Dir.glob(File.join('app/consumers', '*_consumer.rb')).each do |consumer|
+  autoloader.preload(consumer)
+end
+```
+
+### Consumer Groups
+
+It is possible to load only a subset of consumers. This is done by defining a consumer
+group under the `consumer_groups` configuration key:
+
+``` yaml
+consumer_groups:
+  payments:
+    - DepositConsumer
+    - CashoutConsumer
+  notification:
+    - EmailNotificationConsumer
+```
+
+To only load a group of consumers, use the `--only-group` option:
+
+``` shell
+hutch --only-group=payments --config=/path/to/hutch.yaml
+```
+
+### Loading Consumers Manually (One-by-One)
+
 To require files that define consumers manually, simply pass each file as an
 option to `--require`. Hutch will automatically detect whether you've provided
 a Rails app or a standard file, and take the appropriate behaviour:
 
 ```bash
-$ hutch --require path/to/rails-app  # loads a rails app
-$ hutch --require path/to/file.rb    # loads a ruby file
+# loads a rails app
+hutch --require path/to/rails-app
+# loads a ruby file
+hutch --require path/to/file.rb
 ```
 
 ### Stopping Hutch
@@ -240,8 +309,6 @@ kill -SIGTERM 456 # or kill -15 456
 kill -SIGQUIT 789 # or kill -3 789
 ```
 
-![](http://g.recordit.co/wyCdzG9Kh3.gif)
-
 ## Producers
 
 Hutch includes a `publish` method for sending messages to Hutch consumers. When
@@ -265,7 +332,7 @@ Hutch::Config.set(:mq_exchange, 'name')
 ### Publisher Confirms
 
 For maximum message reliability when producing messages, you can force Hutch to use
-[Publisher Confirms](https://www.rabbitmq.com/confirms.html) and wait for a confirmation
+[Publisher Confirms](https://www.rabbitmq.com/docs/confirms) and wait for a confirmation
 after every message published. This is the safest possible option for publishers
 but also results in a **significant throughput drop**.
 
@@ -285,25 +352,27 @@ send messages to Hutch.
 - Hutch works with topic exchanges, check the producer is also using topic
   exchanges.
 - Use message routing keys that match those used in your Hutch consumers.
-- Be sure your exchanges are marked as durable. In the Ruby AMQP gem, this is
-  done by passing `durable: true` to the exchange creation method.
-- Publish messages as persistent.
-- Using publisher confirms is highly recommended.
+- Be sure your exchanges are marked as durable, by passing `durable: true`
+  to the exchange creation method
+- Publish messages as persistent
+- Using publisher confirms is highly recommended
 
 Here's an example of a well-behaved publisher, minus publisher confirms:
 
 ```ruby
-AMQP.connect(host: config[:host]) do |connection|
-  channel  = AMQP::Channel.new(connection)
-  exchange = channel.topic(config[:exchange], durable: true)
+require 'bunny'
 
-  message = JSON.dump({ subject: 'Test', id: 'abc' })
-  exchange.publish(message, routing_key: 'test', persistent: true)
-end
-```
+conn = Bunny.new(host: config[:host])
+conn.start
 
-If using publisher confirms with amqp gem, see [this issue](https://github.com/ruby-amqp/amqp/issues/92)
-and [this gist](https://gist.github.com/3042381) for more info.
+ch       = conn.create_channel
+exchange = ch.topic(config[:exchange], durable: true)
+
+message = JSON.dump({ subject: 'Test', id: 'abc' })
+exchange.publish(message, routing_key: 'test', persistent: true)
+
+conn.close
+```
 
 ## Configuration
 
@@ -316,7 +385,7 @@ Known configuration parameters are:
  * `mq_host`: RabbitMQ hostname (default: `localhost`)
  * `mq_port`: RabbitMQ port (default: `5672`)
  * `mq_vhost`: vhost to use (default: `/`)
- * `mq_username`: username to use (default: `guest`, only can connect from localhost as of RabbitMQ 3.3.0)
+ * `mq_username`: username to use (default: `guest`, can only connect from localhost)
  * `mq_password`: password to use (default: `guest`)
  * `mq_tls`: should TLS be used? (default: `false`)
  * `mq_tls_cert`: path to client TLS certificate (public key)
@@ -337,11 +406,15 @@ Known configuration parameters are:
  * `error_acknowledgements`: a chain of responsibility of objects that acknowledge/reject/requeue messages when an
     exception happens, see classes in `Hutch::Acknowledgements`.
  * `mq_exchange`: exchange to use for publishing (default: `hutch`)
- * `heartbeat`: [RabbitMQ heartbeat timeout](http://rabbitmq.com/heartbeats.html) (default: `30`)
+ * `mq_client_properties`: Bunny's [client properties](https://www.rabbitmq.com/docs/connections#capabilities) (default: `{}`)
+ * `heartbeat`: [RabbitMQ heartbeat timeout](https://www.rabbitmq.com/docs/heartbeats) (default: `30`)
  * `connection_timeout`: Bunny's socket open timeout (default: `11`)
  * `read_timeout`: Bunny's socket read timeout (default: `11`)
  * `write_timeout`: Bunny's socket write timeout (default: `11`)
+ * `automatically_recover`: Bunny's enable/disable network recovery (default: `true`)
+ * `network_recovery_interval`: Bunny's reconnect interval (default: `1`)
  * `tracer`: tracer to use to track message processing
+ * `namespace`: A namespace string to help group your queues (default: `nil`)
 
 ### Environment variables
 
@@ -400,6 +473,13 @@ Generate with
       <td><tt>HUTCH_MQ_EXCHANGE</tt></td>
       <td><p>RabbitMQ Exchange to use for publishing</p></td>
     </tr>
+    <tr>
+      <td><tt>mq_exchange_type</tt></td>
+      <td>topic</td>
+      <td>String</td>
+      <td><tt>HUTCH_MQ_EXCHANGE_TYPE</tt></td>
+      <td><p>RabbitMQ Exchange type to use for publishing</p></td>
+    </tr>
     <tr>
       <td><tt>mq_vhost</tt></td>
       <td>/</td>
@@ -454,7 +534,7 @@ Generate with
       <td>30</td>
       <td>Number</td>
       <td><tt>HUTCH_HEARTBEAT</tt></td>
-      <td><p><a href="http://rabbitmq.com/heartbeats.html">RabbitMQ heartbeat timeout</a></p></td>
+      <td><p><a href="https://www.rabbitmq.com/docs/heartbeats">RabbitMQ heartbeat timeout</a></p></td>
     </tr>
     <tr>
       <td><tt>channel_prefetch</tt></td>
@@ -463,6 +543,13 @@ Generate with
       <td><tt>HUTCH_CHANNEL_PREFETCH</tt></td>
       <td><p>The <tt>basic.qos</tt> prefetch value to use.</p></td>
     </tr>
+    <tr>
+      <td><tt>connection_name</tt></td>
+      <td>nil</td>
+      <td>String</td>
+      <td><tt>HUTCH_CONNECTION_NAME</tt></td>
+      <td><p><a href="https://www.rabbitmq.com/docs/connections#client-provided-names">Client-Provided Connection Name</a></p></td>
+    </tr>
     <tr>
       <td><tt>connection_timeout</tt></td>
       <td>11</td>
@@ -484,12 +571,26 @@ Generate with
       <td><tt>HUTCH_WRITE_TIMEOUT</tt></td>
       <td><p>Bunny's socket write timeout</p></td>
     </tr>
+    <tr>
+      <td><tt>automatically_recover</tt></td>
+      <td>true</td>
+      <td>Boolean</td>
+      <td><tt>HUTCH_AUTOMATICALLY_RECOVER</tt></td>
+      <td><p>Bunny's enable/disable network recovery</p></td>
+    </tr>
+    <tr>
+      <td><tt>network_recovery_interval</tt></td>
+      <td>1</td>
+      <td>Number</td>
+      <td><tt>HUTCH_NETWORK_RECOVERY_INTERVAL</tt></td>
+      <td><p>Bunny's reconnect interval</p></td>
+    </tr>
     <tr>
       <td><tt>graceful_exit_timeout</tt></td>
       <td>11</td>
       <td>Number</td>
       <td><tt>HUTCH_GRACEFUL_EXIT_TIMEOUT</tt></td>
-      <td><p>FIXME: DOCUMENT THIS</p></td>
+      <td><p>Timeout (in seconds) for consumer threads to finish before being killed during graceful shutdown</p></td>
     </tr>
     <tr>
       <td><tt>consumer_pool_size</tt></td>
@@ -545,7 +646,7 @@ Generate with
       <td>false</td>
       <td>Boolean</td>
       <td><tt>HUTCH_FORCE_PUBLISHER_CONFIRMS</tt></td>
-      <td><p>Enables publisher confirms, forces Hutch::Broker#wait_for_confirms for</p></td>
+      <td><p>Enables publisher confirms, forces Hutch::Broker#wait_for_confirms for every publish</p></td>
     </tr>
     <tr>
       <td><tt>enable_http_api_use</tt></td>
@@ -568,10 +669,19 @@ Generate with
       <td><tt>HUTCH_CONSUMER_TAG_PREFIX</tt></td>
       <td><p>Prefix displayed on the consumers tags.</p></td>
     </tr>
+    <tr>
+      <td><tt>namespace</tt></td>
+      <td>nil</td>
+      <td>String</td>
+      <td><tt>HUTCH_NAMESPACE</tt></td>
+      <td><p>A namespace to help group your queues</p></td>
+    </tr>
+    <tr>
+      <td><tt>group</tt></td>
+      <td>''</td>
+      <td>String</td>
+      <td><tt>HUTCH_GROUP</tt></td>
+      <td><p>Consumer group to load (see Consumer Groups)</p></td>
+    </tr>
   </tbody>
 </table>
-
-
----
-
-GoCardless ♥ open source. If you do too, come [join us](https://gocardless.com/jobs/backend_developer).

data/bin/ci/before_build.sh

@@ -0,0 +1,20 @@
+#!/usr/bin/env sh
+
+CTL=${BUNNY_RABBITMQCTL:-"sudo rabbitmqctl"}
+PLUGINS=${BUNNY_RABBITMQ_PLUGINS:-"sudo rabbitmq-plugins"}
+
+echo "Will use rabbitmqctl at ${CTL}"
+echo "Will use rabbitmq-plugins at ${PLUGINS}"
+
+$PLUGINS enable rabbitmq_management
+
+sleep 3
+
+# guest:guest has full access to /
+$CTL add_vhost /
+$CTL add_user guest guest
+$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().' || 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

data/bin/ci/before_build_docker.sh

@@ -0,0 +1,15 @@
+#!/bin/sh
+
+CTL=${MARCH_HARE_RABBITMQCTL:="docker exec rabbitmq rabbitmqctl"}
+
+# guest:guest has full access to /
+
+$CTL add_vhost /
+# $CTL add_user guest guest # already exists
+$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().' || 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/bin/ci/install_on_debian.sh

@@ -0,0 +1,46 @@
+#!/bin/sh
+
+sudo apt-get install curl gnupg debian-keyring debian-archive-keyring apt-transport-https -y
+
+## Team RabbitMQ's main signing key
+sudo apt-key adv --keyserver "hkps://keys.openpgp.org" --recv-keys "0x0A9AF2115F4687BD29803A206B73A36E6026DFCA"
+## Launchpad PPA that provides modern Erlang releases
+sudo apt-key adv --keyserver "keyserver.ubuntu.com" --recv-keys "F77F1EDA57EBB1CC"
+## PackageCloud RabbitMQ repository
+sudo apt-key adv --keyserver "keyserver.ubuntu.com" --recv-keys "F6609E60DC62814E"
+
+## Add apt repositories maintained by Team RabbitMQ
+sudo tee /etc/apt/sources.list.d/rabbitmq.list <<EOF
+## Provides modern Erlang/OTP releases
+##
+## "bionic" as distribution name should work for any reasonably recent Ubuntu or Debian release.
+## See the release to distribution mapping table in RabbitMQ doc guides to learn more.
+deb http://ppa.launchpad.net/rabbitmq/rabbitmq-erlang/ubuntu bionic main
+deb-src http://ppa.launchpad.net/rabbitmq/rabbitmq-erlang/ubuntu bionic main
+
+## Provides RabbitMQ
+##
+## "bionic" as distribution name should work for any reasonably recent Ubuntu or Debian release.
+## See the release to distribution mapping table in RabbitMQ doc guides to learn more.
+deb https://packagecloud.io/rabbitmq/rabbitmq-server/ubuntu/ bionic main
+deb-src https://packagecloud.io/rabbitmq/rabbitmq-server/ubuntu/ bionic main
+EOF
+
+## Update package indices
+sudo apt-get update -y
+
+## Install Erlang packages
+sudo apt-get install -y erlang-base \
+                        erlang-asn1 erlang-crypto erlang-eldap erlang-ftp erlang-inets \
+                        erlang-mnesia erlang-os-mon erlang-parsetools erlang-public-key \
+                        erlang-runtime-tools erlang-snmp erlang-ssl \
+                        erlang-syntax-tools erlang-tftp erlang-tools erlang-xmerl
+
+## Install rabbitmq-server and its dependencies
+sudo apt-get install rabbitmq-server -y --fix-missing
+
+sudo service rabbitmq-server start
+
+sudo rabbitmqctl await_startup --timeout 120
+
+until sudo lsof -i:5672; do echo "Waiting for RabbitMQ to start..."; sleep 1; done

data/lib/hutch/acknowledgements/nack_on_all_failures.rb

@@ -10,7 +10,7 @@ module Hutch
         prefix = "message(#{properties.message_id || '-'}): "
         logger.debug "#{prefix} nacking message"
 
-        broker.nack(delivery_info.delivery_tag)
+        broker.nack(delivery_info.delivery_tag, channel: delivery_info.channel)
 
         true
       end

data/lib/hutch/adapters/bunny.rb

@@ -1,17 +1,21 @@
 require 'bunny'
 require 'forwardable'
 
+require 'hutch/logging'
+
 module Hutch
   module Adapters
     class BunnyAdapter
       extend Forwardable
+      include Logging
 
       DEFAULT_VHOST = Bunny::Session::DEFAULT_VHOST
 
       ConnectionRefused = Bunny::TCPConnectionFailed
+      ChannelAlreadyClosed = Bunny::ChannelAlreadyClosed
       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)
@@ -25,9 +29,33 @@ module Hutch
         ch.prefetch(prefetch) if prefetch
       end
 
+      def queue_exists?(name)
+        @connection.queue_exists?(name)
+      end
+
+      def install_channel_recovery(ch)
+        # A consumer timeout invalidates the delivery tag, so a handler that
+        # was still running acknowledges an unknown tag and closes the channel.
+        ch.on_error do |channel, close|
+          next unless close.delivery_ack_timeout? || close.unknown_delivery_tag?
+
+          begin
+            channel.reopen
+            recover_channel_topology(channel)
+            logger.warn "recovered consumer channel closed with '#{close.reply_text}'"
+          rescue => ex
+            logger.error "channel recovery failed: #{ex.class}: #{ex.message}"
+          end
+        end
+      end
+
       def current_timestamp
         Time.now.to_i
       end
+
+      def self.new_exchange(ch, exchange_type, exchange_name, exchange_options)
+        Bunny::Exchange.new(ch, exchange_type, exchange_name, exchange_options)
+      end
     end
   end
 end

data/lib/hutch/adapters/march_hare.rb

@@ -9,6 +9,7 @@ module Hutch
       DEFAULT_VHOST = "/"
 
       ConnectionRefused = MarchHare::ConnectionRefused
+      ChannelAlreadyClosed = MarchHare::ChannelAlreadyClosed
       PreconditionFailed = MarchHare::PreconditionFailed
 
       def_delegators :@connection, :start, :disconnect, :close, :open?
@@ -25,6 +26,25 @@ module Hutch
         ch.prefetch = prefetch if prefetch
       end
 
+      # `MarchHare::Session` has no `queue_exists?` counterpart, and a failed
+      # passive declare closes the channel, hence the throwaway one.
+      def queue_exists?(name)
+        ch = @connection.create_channel
+        begin
+          ch.queue(name, passive: true)
+          true
+        rescue MarchHare::NotFound
+          false
+        ensure
+          ch.close rescue nil
+        end
+      end
+
+      # MarchHare::Channel has no on_error callback, and neither Channel#reopen
+      # nor Session#recover_channel_topology has a `march_hare` counterpart.
+      def install_channel_recovery(ch)
+      end
+
       def create_channel(n = nil, consumer_pool_size = 1, consumer_pool_abort_on_exception = false)
         @connection.create_channel(n)
       end
@@ -32,6 +52,10 @@ module Hutch
       def current_timestamp
         Time.now
       end
+
+      def self.new_exchange(ch, exchange_type, exchange_name, exchange_options)
+        MarchHare::Exchange.new(ch, exchange_name, exchange_options.merge(type: exchange_type)).tap(&:declare!)
+      end
     end
   end
 end