outboxer 0.1.0 → 0.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a573b50b1f20cc0966a9c6baef36216240ab20adee17adcf03da8a193436bf78
-  data.tar.gz: 86573195530a94aac112fd0c52169a7564e97f0e677ba03c26d37b87e8eb7c02
+  metadata.gz: 99b8c36fa2db36b780ca732a63aba4df7f38ccd06d7a2403961a2cb483085153
+  data.tar.gz: 33db69284cdbc1fbf8398c98799deabd2a09b38eb863df2e2f88943db2bfa25d
 SHA512:
-  metadata.gz: edd4bc1e08e57f742985e8382fa1202ee6df3812282f9b0d12054cce63406fb9a7101fa6a53d93f85205faf31ae324b35c3254c9ab586865959cdd1a2ccfe951
-  data.tar.gz: 5d5196f1bdcadb519720c4d80b01852d9463f1d5844a90bd8447d392675b17357adae4deb4088b8210ea65f0ab4555707b0affee69aac20b0832b5ff0505b77a
+  metadata.gz: 5191c2ba363decec6729efd72dbaadd697241f74c11f07dfd722874fdc6df8be0b5001e696159f0ba17e2c744447dc11c256f90af17edb6bb03c68452e237c31
+  data.tar.gz: fdd2cfaecfa7d2972566ef340a164992325a1c08cc5810c7eee20a4218901082fb2ce45dcd10cb66ecd3747ffc55b5a3f135cb8a0acb7fb80a74f2c4d9e012c0

data/README.md

@@ -1,10 +1,23 @@
 # Outboxer
 
-Creating a message in an SQL database and publishing it to redis via a sidekiq worker are two operations that cannot be combined into a single atomic operation. If either database fails, inconsistencies can occur.
+## Background
 
-In Outboxer, when a new message is created in your application's SQL database, Outboxer automatically creates a message in an outbox table with a status of 'unpublished', within the same local transaction. This ensures that either both operations succeed or both fail, preserving atomicity.
+Typically in event driven Ruby on Rails applications:
 
-## Installation
+1. a domain event model is created in an SQL database table
+2. a sidekiq worker is queued to handle the domain event asynchronously
+
+## Problem
+
+As these two operations span multiple database types (SQL and redis), they can not be combined into a single atomic operation using a transaction. If either step fails, inconsistencies can occur.
+
+## Solution
+
+Outboxer is a simple Ruby on Rails implementation of the [transactional outbox pattern](https://microservices.io/patterns/data/transactional-outbox.html): a well established solution to this problem. It ensures both operations succeed _eventually_, or both fail.
+
+### Getting started
+
+### Installation
 
 1. Add the Outboxer gem to your application's Gemfile:
 
@@ -24,18 +37,9 @@ bundle install
 bin/rails generate outboxer:install
 ```
 
-## Usage
-
-### 1. Migrate your database
-
-```bash
-bin/rake db:migrate
-```
-
-
-### 2. Include Outboxer into existing model
+### Usage
 
-First, include `Outboxer::Outboxable` into your existing `Message` model:
+#### 1. Include `Outboxer::Outboxable` into your existing Message model
 
 ```ruby
 class Message < ApplicationRecord
@@ -43,26 +47,50 @@ class Message < ApplicationRecord
 end
 ```
 
-### 3. Update the publish block
+#### 2. Update the generated bin/publish block e.g.
 
-By default, the `bin/publisher` script does not do anything with the message in its block.
+```ruby
+Outboxer::Publisher.publish do |args|
+  args.logger.info("[#{message.id}] publishing")
 
-To customize this behavior, you should update the block in the `bin/publisher` file:
+  Worker.perform_async({ message_id: args.message.id })
 
-```ruby
-Outboxer::Publisher.publish do |message:, logger:|
-  Worker.perform_async({ message_id: message.id })
+  args.logger.info("[#{message.id}] published")
 end
 ```
 
-### 3. Run the Publisher
+#### 3. Migrate the database
 
-To start publishing messages, run the `bin/publisher` script:
+```bash
+bin/rake db:migrate
+```
+
+#### 4. Run the publisher
 
 ```bash
 bin/publisher
 ```
 
+## Implementation
+
+1. when an `ActiveRecord` model that includes `Outbox::Outboxable` is created, an `unpublished` `Outboxer::Message` is automatically created in the same transaction, with `Outboxer::Message#message` polymorphically assigned to the original model
+
+2. When the publisher finds a new `unpublished` `Outboxer::Message`, it yields to a user-supplied block and then:
+    - removes it if the task completes successfully
+    - marks it as failed and records the error if there's a problem
+
+To see all the parts working together in a single place, check out the [publisher_spec.rb](https://github.com/fast-programmer/outboxer/blob/master/spec/outboxer/publisher_spec.rb)
+
+
+## Motivation
+
+Outboxer was created with 4 key benefits in mind:
+
+1. speed of integration into existing Ruby on Rails applications (< 1 hour)
+2. comprehensive documentation that is easy to understand
+3. high reliability in production environments (100% code coverage)
+4. forever free to use in commerical applications (MIT licence)
+
 ## Contributing
 
 Bug reports and pull requests are welcome on GitHub at https://github.com/fast-programmer/outboxer. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/fast-programmer/outboxer/blob/main/CODE_OF_CONDUCT.md).

data/doc/Outboxer/Models/Exception.html

@@ -0,0 +1,124 @@
+<!DOCTYPE html>
+<html>
+  <head>
+    <meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1.0">
+<title>
+  Class: Outboxer::Models::Exception
+  
+    &mdash; Documentation by YARD 0.9.34
+  
+</title>
+
+  <link rel="stylesheet" href="../../css/style.css" type="text/css" />
+
+  <link rel="stylesheet" href="../../css/common.css" type="text/css" />
+
+<script type="text/javascript">
+  pathId = "Outboxer::Models::Exception";
+  relpath = '../../';
+</script>
+
+
+  <script type="text/javascript" charset="utf-8" src="../../js/jquery.js"></script>
+
+  <script type="text/javascript" charset="utf-8" src="../../js/app.js"></script>
+
+
+  </head>
+  <body>
+    <div class="nav_wrap">
+      <iframe id="nav" src="../../class_list.html?1"></iframe>
+      <div id="resizer"></div>
+    </div>
+
+    <div id="main" tabindex="-1">
+      <div id="header">
+        <div id="menu">
+  
+    <a href="../../_index.html">Index (E)</a> &raquo;
+    <span class='title'><span class='object_link'><a href="../../Outboxer.html" title="Outboxer (module)">Outboxer</a></span></span> &raquo; <span class='title'><span class='object_link'><a href="../Models.html" title="Outboxer::Models (module)">Models</a></span></span>
+     &raquo; 
+    <span class="title">Exception</span>
+  
+</div>
+
+        <div id="search">
+  
+    <a class="full_list_link" id="class_list_link"
+        href="../../class_list.html">
+
+        <svg width="24" height="24">
+          <rect x="0" y="4" width="24" height="4" rx="1" ry="1"></rect>
+          <rect x="0" y="12" width="24" height="4" rx="1" ry="1"></rect>
+          <rect x="0" y="20" width="24" height="4" rx="1" ry="1"></rect>
+        </svg>
+    </a>
+  
+</div>
+        <div class="clear"></div>
+      </div>
+
+      <div id="content"><h1>Class: Outboxer::Models::Exception
+  
+  
+  
+</h1>
+<div class="box_info">
+  
+  <dl>
+    <dt>Inherits:</dt>
+    <dd>
+      <span class="inheritName">ActiveRecord::Base</span>
+      
+        <ul class="fullTree">
+          <li>Object</li>
+          
+            <li class="next">ActiveRecord::Base</li>
+          
+            <li class="next">Outboxer::Models::Exception</li>
+          
+        </ul>
+        <a href="#" class="inheritanceTree">show all</a>
+      
+    </dd>
+  </dl>
+  
+
+  
+  
+  
+  
+  
+
+  
+
+  
+  <dl>
+    <dt>Defined in:</dt>
+    <dd>lib/outboxer/models/exception.rb</dd>
+  </dl>
+  
+</div>
+
+
+
+
+
+
+
+
+
+  
+
+</div>
+
+      <div id="footer">
+  Generated on Sat Aug  5 04:37:46 2023 by
+  <a href="https://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
+  0.9.34 (ruby-2.7.8).
+</div>
+
+    </div>
+  </body>
+</html>

data/doc/Outboxer/Models/Message.html

@@ -0,0 +1,144 @@
+<!DOCTYPE html>
+<html>
+  <head>
+    <meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1.0">
+<title>
+  Class: Outboxer::Models::Message
+  
+    &mdash; Documentation by YARD 0.9.34
+  
+</title>
+
+  <link rel="stylesheet" href="../../css/style.css" type="text/css" />
+
+  <link rel="stylesheet" href="../../css/common.css" type="text/css" />
+
+<script type="text/javascript">
+  pathId = "Outboxer::Models::Message";
+  relpath = '../../';
+</script>
+
+
+  <script type="text/javascript" charset="utf-8" src="../../js/jquery.js"></script>
+
+  <script type="text/javascript" charset="utf-8" src="../../js/app.js"></script>
+
+
+  </head>
+  <body>
+    <div class="nav_wrap">
+      <iframe id="nav" src="../../class_list.html?1"></iframe>
+      <div id="resizer"></div>
+    </div>
+
+    <div id="main" tabindex="-1">
+      <div id="header">
+        <div id="menu">
+  
+    <a href="../../_index.html">Index (M)</a> &raquo;
+    <span class='title'><span class='object_link'><a href="../../Outboxer.html" title="Outboxer (module)">Outboxer</a></span></span> &raquo; <span class='title'><span class='object_link'><a href="../Models.html" title="Outboxer::Models (module)">Models</a></span></span>
+     &raquo; 
+    <span class="title">Message</span>
+  
+</div>
+
+        <div id="search">
+  
+    <a class="full_list_link" id="class_list_link"
+        href="../../class_list.html">
+
+        <svg width="24" height="24">
+          <rect x="0" y="4" width="24" height="4" rx="1" ry="1"></rect>
+          <rect x="0" y="12" width="24" height="4" rx="1" ry="1"></rect>
+          <rect x="0" y="20" width="24" height="4" rx="1" ry="1"></rect>
+        </svg>
+    </a>
+  
+</div>
+        <div class="clear"></div>
+      </div>
+
+      <div id="content"><h1>Class: Outboxer::Models::Message
+  
+  
+  
+</h1>
+<div class="box_info">
+  
+  <dl>
+    <dt>Inherits:</dt>
+    <dd>
+      <span class="inheritName">ActiveRecord::Base</span>
+      
+        <ul class="fullTree">
+          <li>Object</li>
+          
+            <li class="next">ActiveRecord::Base</li>
+          
+            <li class="next">Outboxer::Models::Message</li>
+          
+        </ul>
+        <a href="#" class="inheritanceTree">show all</a>
+      
+    </dd>
+  </dl>
+  
+
+  
+  
+  
+  
+  
+
+  
+
+  
+  <dl>
+    <dt>Defined in:</dt>
+    <dd>lib/outboxer/models/message.rb</dd>
+  </dl>
+  
+</div>
+
+
+  
+    <h2>
+      Constant Summary
+      <small><a href="#" class="constants_summary_toggle">collapse</a></small>
+    </h2>
+
+    <dl class="constants">
+      
+        <dt id="STATUS-constant" class="">STATUS =
+          
+        </dt>
+        <dd><pre class="code"><span class='lbrace'>{</span>
+  <span class='label'>unpublished:</span> <span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>unpublished</span><span class='tstring_end'>&quot;</span></span><span class='comma'>,</span>
+  <span class='label'>publishing:</span> <span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>publishing</span><span class='tstring_end'>&quot;</span></span><span class='comma'>,</span>
+  <span class='label'>failed:</span> <span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>failed</span><span class='tstring_end'>&quot;</span></span>
+<span class='rbrace'>}</span><span class='period'>.</span><span class='id identifier rubyid_freeze'>freeze</span></pre></dd>
+      
+    </dl>
+  
+
+
+
+
+
+
+
+
+  
+
+</div>
+
+      <div id="footer">
+  Generated on Sat Aug  5 04:37:46 2023 by
+  <a href="https://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
+  0.9.34 (ruby-2.7.8).
+</div>
+
+    </div>
+  </body>
+</html>

data/doc/Outboxer/Models/Outboxable/ClassMethods.html

@@ -0,0 +1,105 @@
+<!DOCTYPE html>
+<html>
+  <head>
+    <meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1.0">
+<title>
+  Module: Outboxer::Models::Outboxable::ClassMethods
+  
+    &mdash; Documentation by YARD 0.9.34
+  
+</title>
+
+  <link rel="stylesheet" href="../../../css/style.css" type="text/css" />
+
+  <link rel="stylesheet" href="../../../css/common.css" type="text/css" />
+
+<script type="text/javascript">
+  pathId = "Outboxer::Models::Outboxable::ClassMethods";
+  relpath = '../../../';
+</script>
+
+
+  <script type="text/javascript" charset="utf-8" src="../../../js/jquery.js"></script>
+
+  <script type="text/javascript" charset="utf-8" src="../../../js/app.js"></script>
+
+
+  </head>
+  <body>
+    <div class="nav_wrap">
+      <iframe id="nav" src="../../../class_list.html?1"></iframe>
+      <div id="resizer"></div>
+    </div>
+
+    <div id="main" tabindex="-1">
+      <div id="header">
+        <div id="menu">
+  
+    <a href="../../../_index.html">Index (C)</a> &raquo;
+    <span class='title'><span class='object_link'><a href="../../../Outboxer.html" title="Outboxer (module)">Outboxer</a></span></span> &raquo; <span class='title'><span class='object_link'><a href="../../Models.html" title="Outboxer::Models (module)">Models</a></span></span> &raquo; <span class='title'><span class='object_link'><a href="../Outboxable.html" title="Outboxer::Models::Outboxable (module)">Outboxable</a></span></span>
+     &raquo; 
+    <span class="title">ClassMethods</span>
+  
+</div>
+
+        <div id="search">
+  
+    <a class="full_list_link" id="class_list_link"
+        href="../../../class_list.html">
+
+        <svg width="24" height="24">
+          <rect x="0" y="4" width="24" height="4" rx="1" ry="1"></rect>
+          <rect x="0" y="12" width="24" height="4" rx="1" ry="1"></rect>
+          <rect x="0" y="20" width="24" height="4" rx="1" ry="1"></rect>
+        </svg>
+    </a>
+  
+</div>
+        <div class="clear"></div>
+      </div>
+
+      <div id="content"><h1>Module: Outboxer::Models::Outboxable::ClassMethods
+  
+  
+  
+</h1>
+<div class="box_info">
+  
+
+  
+  
+  
+  
+  
+
+  
+
+  
+  <dl>
+    <dt>Defined in:</dt>
+    <dd>lib/outboxer/models/outboxable.rb</dd>
+  </dl>
+  
+</div>
+
+
+
+
+
+
+
+
+
+
+</div>
+
+      <div id="footer">
+  Generated on Sat Aug  5 04:37:46 2023 by
+  <a href="https://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
+  0.9.34 (ruby-2.7.8).
+</div>
+
+    </div>
+  </body>
+</html>