inboxable

Inboxable

The Inboxable gem is an opinionated gem that implements the Transactional Inbox pattern for Rails applications. The gem provides support for both ActiveRecord and Mongoid. If you are using the Transactional Outbox pattern in your application, you can use the Outboxable to handle both ends of the pattern.

Please take into consideration that this Gem is opinionated, meaning it expects you to follow a certain pattern and specific setting. If you don't like it, you can always fork it and change it.

Note: If you are not familiar with the Transactional Outbox and Inbox patterns, please read the following article Microservices 101: Transactional Outbox and Inbox before proceeding.

Installation

Add this line to your application's Gemfile:

gem 'inboxable'

And then execute:

bundle install

Or install it yourself as:

gem install inboxable

How It Works

The inboxable gem uses a cron job to poll the inbox for new messages. The cron job is scheduled to run every 5 seconds by default. The cron job will fetch the messages from the inbox and process them in batches. The number of messages to be processed in each batch is 100 by default. In the event of a failure, the message will be retried up to 3 times with a delay of 5 seconds between each retry. If the message is still not processed after 3 attempts, the message will be moved to the dead letter queue. Note that all the previous values can be configured using the configuration options. (See the Configuration section below for more information.)

Usage

The installation command above will install the Inboxable gem and its dependencies. However, in order for Inboxable to work, you must set up your application to use Inboxable gem to process the inboxes. The following sections will show you how to set up your application to use Inboxable gem.

The below command is to initialize the gem and generate the configuration file.

rails g inboxable:install --orm <orm>

The gem provides support for both ActiveRecord and Mongoid. The --orm option is used to specify the ORM that you are using in your application. The --orm option can be either active_record or mongoid. Here is an example of how to generate the configuration file for an application that uses ActiveRecord.

rails g inboxable:install --orm active_record

The above command will generate the following files:

1. config/initializers/inboxable.rb: This file contains the configuration for the gem. (See the Configuration section below for more information.)
2. app/models/inbox.rb: This file contains the Inbox model. This model is used to store the messages in the inbox. (See the Inbox Model section below for more information.)
3. If you are using ActiveRecord, the following migration file will be generated:
   • db/migrate/<timestamp>_create_inboxable_inboxes.rb: This migration file is used to create the inboxes table in the database. (See the Inbox Model section below for more information.)

Generating Handler Files & Processors

The Inboxable gem provides generators that can be used to generate event handler files and processors. Here is how to generate the files.

Generating Handler Files

The following command is used to generate the handler files.

rails g inboxable:handler --handler_name <handler_name> --namespace <namespace>

The options are as follows:

• handler_name: This option is used to specify the name of the handler. An example of a handler name is user_update_handler.
• namespace: This option is used to specify the namespace for the handler class. The namespace must be in the format <namespace1>::<namespace2>. For example, if the namespace is Common::UsersApi, the handler file will be generated in the app/handlers/common/users_api directory.

Generating Processor Files

The following command is used to generate the processor files.

rails g inboxable:processor --processor_name <processor_name>

The options are as follows:

• processor_name: This option is used to specify the name of the processor. An example of a processor name is user_update_job.

Inbox Model

The Inbox model is used to store the messages in the inbox. The Inbox model is generated by the gem when you run the rails g inboxable:install --orm <orm> command. Based on the ORM that you are using, the gem will generate the appropriate model.The following is the structure of the Inbox model for ActiveRecord and Mongoid.

If you would like to use a different name for the Inbox model. You can configure it by setting the inbox_model config to the name of you custom defined model. See the Configuration section below for more information.

Fields & Attributes

The Inbox model has the following fields and attributes:

---

Field	Type	Description
route_name	String	The routing key that is used to route the message to the appropriate handler.
postman_name	String	The name of the postman that delivered the message.
payload	String	The payload of the message.
event_id	String	The ID of the event. It is used for idempotency.
attempts	Integer	The number of attempts tried to process the message.
last_attempted_at	Time	The time of the last attempt to process the message.
processor_class_name	String	The name of the processor class that is used to process the message (a Sidekiq worker class).
metadata	Hash	The metadata of the message.

---

Methods

The Inbox model has the following methods:

---

Method	Description
increment_attempt	Increments the number of attempts to process the message.
process	Processes the message by enqueuing the processor class to Sidekiq.
check_threshold_reach	Checks if the maximum number of attempts to process the message is reached. If so, it sets the status of the message to failed and stops processing the message.
check_publishing	Checks if the message is already processed. If so, it stops processing the message.

---

Flow

When an event is received by the Rails application, the Handler class should ensure that this message is delivered to the inbox by creating a new record in the inbox. After the record is created, the Inbox model tries to process once the job by enqueuing the processor class to Sidekiq. If the job fails, the Inboxable::PollingReceiverWorker will retry the job up to 3 times with a delay of 5 seconds between each retry. If the job is still not processed after 3 attempts, the job will be moved to the dead letter queue.

Configuration

The Inboxable gem provides a number of configuration options that can be used to customize the behavior of the gem. The following is a list of the configuration options that are available.

---

Option	Description	Default Value	Applied To
orm	The ORM that is used in the application.	:active_record	/config/initializers/z_inboxable.rb
inbox_model	The name of the Inbox model.	Inbox	/config/initializers/z_inboxable.rb
INBOXABLE__CRON_POLL_INTERVAL	The interval in seconds between each poll of the inbox.	5	Can be overridden by providing an environment variable with the same name.
INBOXABLE__CRON	The cron expression that is used to poll the inbox.	*/5 * * * * *	Can be overridden by providing an environment variable with the same name.
INBOXABLE__BATCH_SIZE	The number of messages to be processed in each batch.	100	Can be overridden by providing an environment variable with the same name.
INBOXABLE__MAX_ATTEMPTS	The maximum number of attempts to process a message.	3	Can be overridden by providing an environment variable with the same name.
INBOXABLE__RETRY_DELAY_IN_SECONDS	The delay in seconds before retrying to process a message.	5	Can be overridden by providing an environment variable with the same name.

---

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/inboxable. This project is intended to be a safe, welcoming space for collaboration, and contributors. Please go to issues page to report any bugs or feature requests. If you would like to contribute, please fork the repository and submit a pull request.

To, use the gem locally, clone the repository and run bundle install to install dependencies. Then, run bundle exec rspec to run the tests.

License

The gem is available as open source under the terms of the MIT License.