📤 Outboxer

Outboxer is an implementation of the transactional outbox pattern for Ruby on Rails applications.

It helps you migrate to event-driven architecture with at least once delivery guarantees.

Quickstart

1. Install gem

bundle add outboxer
bundle install

2. Generate schema migrations, publisher script and tests

bin/rails g outboxer:install

3. Migrate database

bin/rails db:migrate

4. Generate event schema and model

bin/rails generate model Event type:string created_at:datetime --skip-timestamps
bin/rails db:migrate

5. Queue outboxer message after event created

# app/models/event.rb

class Event < ApplicationRecord
  after_create do |event|
    Outboxer::Message.queue(messageable: event)
  end
end

6. Derive event type

# app/models/accountify/invoice_raised_event.rb

module Accountify
  class InvoiceRaisedEvent < Event; end
end

7. Create derived event type

Accountify::InvoiceRaisedEvent.create!

8. Publish outboxer messages

# bin/outboxer_publisher

Outboxer::Publisher.publish_messages do |publisher, messages|
  # TODO: publish messages here

  Outboxer::Message.published_by_ids(
    ids: messages.map { |message| message[:id] },
    publisher_id: publisher[:id],
    publisher_name: publisher[:name])
rescue => error
  Outboxer::Message.failed_by_ids(
    ids: messages.map { |message| message[:id] },
    exception: error,
    publisher_id: publisher[:id],
    publisher_name: publisher[:name])
end

see https://github.com/fast-programmer/outboxer/wiki/Outboxer-publisher-block-examples

Testing

The generated spec/bin/outboxer_publisher adds end to end queue and publish message test coverage.

Monitoring

Monitor using the built-in web UI:

Publishers

Messages

Rails

# config/routes.rb

require 'outboxer/web'

mount Outboxer::Web, at: '/outboxer'

Rack

# config.ru

require 'outboxer/web'

map '/outboxer' { run Outboxer::Web }

Contributing

All contributions are welcome!

License

Open-sourced under LGPL v3.0.

outboxer

Runtime