Hutch Documentation

You can define groups of consumers in your configuration file to allow running only specific subsets of your workers.

1. Define the group in your YAML config:

consumer_groups:
  payments:
    - DepositConsumer
    - CashoutConsumer

2. Run only that group using the --only-group flag:

hutch --only-group=payments --config=/path/to/hutch.yaml

consumer_groups:
  payments:
    - DepositConsumer
    - CashoutConsumer
  notification:
    - EmailNotificationConsumer

Hutch supports graceful shutdowns, meaning it will wait for the current message processing to finish before exiting. To trigger a graceful stop, send one of the following signals to the Hutch process:

• SIGINT (Ctrl+C)
• SIGTERM
• SIGQUIT

kill -SIGINT 123
kill -SIGTERM 456
kill -SIGQUIT 789

If you are writing producers in languages other than Ruby, you cannot use Hutch.publish. To ensure compatibility with Hutch consumers, follow these requirements:

• Exchange Name: The producer exchange name must match the exchange name used by Hutch.
• Exchange Type: Hutch uses topic exchanges; ensure your producer also uses topic exchanges.
• Routing Keys: Use message routing keys that match those used in your Hutch consumers.
• Durability: Exchanges must be marked as durable (e.g., by passing durable: true during exchange creation).
• Persistence: Publish messages as persistent.
• Reliability: Using publisher confirms is highly recommended.

Hutch can be configured using a configuration file, environment variables, or explicit settings via Hutch::Config.set.

Configuration Precedence

Settings are applied in the following order (highest precedence wins):

1. Explicit settings through Hutch::Config.set
2. Configuration file
3. HUTCH_* environment variables
4. Default values

Using Environment Variables

You can pass any configuration option via environment variables by prefixing the option name with HUTCH_. For example, setting connection_timeout is done via HUTCH_CONNECTION_TIMEOUT.

Install the Hutch gem using the standard RubyGems command to enable asynchronous inter-service communication via RabbitMQ.

gem install hutch

Before using Hutch, ensure your environment meets the following requirements:

• Ruby: 3.0+ or JRuby 9.4+
• RabbitMQ: 3.13 or later

To use Hutch with Rails, place your consumers in app/consumers/. Hutch will automatically load them when started in the Rails directory or via --require path/to/rails-app.

If using the Zeitwerk autoloader (Rails 6+), you may need to trigger eager loading in an initializer to ensure consumers are loaded in development environments:

# Option 1: Eager load everything
::Zeitwerk::Loader.eager_load_all

# Option 2: Preload specifically defined consumers
autoloader = Rails.autoloaders.main
Dir.glob(File.join('app/consumers', '*_consumer.rb')).each do |consumer|
  autoloader.preload(consumer)
end

To achieve maximum message reliability, you can force Hutch to use Publisher Confirms. When enabled, Hutch will wait for a confirmation after every message published.

Warning: While this is the safest option for publishers, it results in a significant throughput drop.

Hutch::Config.set(:force_publisher_confirms, true)

Producers are not run via the hutch CLI command. Instead, they are configured within your Ruby code using Hutch::Config.set.

You can specify the exchange name used by the producer using the :mq_exchange key.

Hutch::Config.set(:mq_exchange, 'name')

To create a consumer in Hutch, include the Hutch::Consumer module in your class. This automatically registers the class as a consumer and provides several class methods for configuration and instance methods for message acknowledgement.

Once included, you must use the consume method to specify which routing keys the consumer should subscribe to.

class MyConsumer
  include Hutch::Consumer

  def consume('my.routing.key')
  end

  def process(message)
    # handle message
  end
end

Hutch can automatically load your application code so that consumers are available. You can specify paths to require or instruct Hutch to look for a Rails app in the current directory.

# Load a specific path/file
hutch --require ./lib/my_consumers

# Automatically attempt to load a Rails app in the current directory
hutch --autoload-rails

# Load configuration from a file
hutch --config config/hutch.yml

You can start a Hutch worker from the command line using the hutch binary. The CLI allows you to configure RabbitMQ connection details, load application code (including Rails apps), and manage worker behavior like daemonization or consumer grouping.

# Example: Running hutch with specific RabbitMQ settings and loading a specific path
hutch --mq-host localhost --mq-username guest --mq-password guest --require ./my_app_code