Getting Started

Install

# Gemfile
gem 'lepus'

bundle install

You’ll also need a running RabbitMQ instance. For local dev:

docker run -d --rm -p 5672:5672 -p 15672:15672 rabbitmq:3-management

Configure

# config/initializers/lepus.rb (Rails) or your bootstrap file
Lepus.configure do |config|
  config.rabbitmq_url    = ENV.fetch('RABBITMQ_URL', 'amqp://guest:guest@localhost:5672')
  config.connection_name = 'my-service'
end

See configuration.md for the full DSL.

Define a consumer

class OrdersConsumer < Lepus::Consumer
  configure(
    queue:       'orders',
    exchange:    { name: 'orders', type: :topic, durable: true },
    routing_key: ['order.*']
  )

  use :json, symbolize_keys: true

  def perform(message)
    # message.payload       => the decoded JSON body (a hash, due to the :json middleware)
    # message.delivery_info => exchange, routing_key, redelivered?
    # message.metadata      => headers, content_type, correlation_id, etc.
    Order.create!(message.payload)
    :ack
  end
end

The perform method returns a symbol indicating disposition:

• :ack — acknowledge; RabbitMQ removes the message.
• :reject — reject; message is dropped (or routed to a dead-letter exchange if configured).
• :requeue — reject and requeue for another delivery attempt.
• :nack — negative-ack without requeue (similar to :reject).

ack!, reject!, requeue!, nack! are also available as helper methods.

Define a producer

class OrdersProducer < Lepus::Producer
  configure(
    exchange: { name: 'orders', type: :topic, durable: true },
    publish:  { persistent: true }
  )

  use :json
  use :correlation_id
end

Publish:

OrdersProducer.publish(
  { order_id: 42, total: 99.99 },
  routing_key: 'order.created'
)

Run

One-off (development)

bundle exec lepus start OrdersConsumer

Flags worth knowing:

bundle exec lepus start OrdersConsumer PaymentsConsumer \
  --require_file config/environment.rb \
  --debug

See cli.md.

As a long-running service

In production, run lepus start with all your consumer classes (or auto-load them — see below) under your favorite process supervisor (systemd, Foreman, Kamal, Kubernetes).

Auto-load consumers from a directory:

Lepus.configure do |config|
  config.consumers_directory = 'app/consumers'
end

bundle exec lepus start   # with no class args, starts all consumers from consumers_directory

Monitor

bundle exec lepus web --port 9292

Visit http://localhost:9292 to see consumer status, throughput, and recent activity. See web.md.

Next steps

• Consumers — full consumer DSL, retries, error handling
• Producers — exchange config, publishing options, hooks
• Middleware — built-in middlewares and writing your own
• Supervisor — process model, graceful shutdown, worker pools
• Rails integration — Railtie, executor wrapping