active_outbox 0.0.2 → 0.0.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: aa92d48552facbc79e9ec9ae9f58a599d533267a490f7199c5b4e87b9f62f83b
-  data.tar.gz: a04f7dbe86d0b7e53296079be077db720c50baa48f2b53237cb18423fb33209d
+  metadata.gz: f366197388646246ec6d819c6877f846fd732a3f0df79673c23e7d5883057d78
+  data.tar.gz: 72a2af511d588e32622444068d1e26cc57114debd08cade8b88399cf3ad297e8
 SHA512:
-  metadata.gz: acfbc64c4ad058a44d56c170fd194d300841cdfd8bdcaa950b9d63b90ae23f392f3bfdf7c1240e0564d7312680362057360114e9e98e9aaafec842639dd0ab98
-  data.tar.gz: 6449a7b730797fb16e55fca130e0ee7d4813bda5d06c34c4093f23bb6e20d77e5bca07cdcc5ed212d30c42617b6035ffcb31c2fc0033b90ebb0653dd6fe6bf25
+  metadata.gz: c3da7a34231c3161e4f65291aa78b304d94213d06cdefa7f0e5cfa0318772db56906ee27391610be9bcd18e640db4481c00eee40b9341f183b5877063c3d1120
+  data.tar.gz: b6d2e214d3dcaef57c7f774a934a814dca2c4d8a355d79721a0cfcc3d8f377bec36f7f1dd289d36a06fbcc6a695a09c6f61027fa6177d0e39419abda0c688492

data/README.md

@@ -1,2 +1,100 @@
 # Active Outbox
 A Transactional Outbox implementation for ActiveRecord
+
+![transactional outbox pattern](./docs/images/transactional_outbox.png)
+
+This gem aims to implement the event persistance side of the pattern, focusing only on providing a seamless way to store Outbox records whenever a change occurs on a given model (#1 in the diagram).
+We do not provide an event publisher, nor a consumer as a part of this gem since the idea is to keep it as light weight as possible.
+
+## Motivation
+If you find yourself repeatedly defining a transaction block every time you need to persist an event, it might be a sign that something needs improvement. We believe that adopting a pattern should enhance your workflow, not hinder it. Creating, updating or destroying a record should remain a familiar and smooth process.
+
+Our primary objective is to ensure a seamless experience without imposing our own opinions or previous experiences. That's why this gem exclusively focuses on persisting records. We leave the other aspects of the pattern entirely open for your customization. You can emit these events using Sidekiq jobs, or explore more sophisticated solutions like Kafka Connect.
+
+## Why active_outbox?
+- Seamless integration with ActiveRecord
+- CRUD events out of the box
+- Ability to set custom events
+- Test helpers to easily check Outbox records are being created correctly
+- Customizable
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'active_outbox'
+```
+
+And then execute:
+```bash
+bundle install
+```
+Or install it yourself as:
+```bash
+gem install active_outbox
+```
+
+## Usage
+### Setup
+Create an `Outbox` table using the provided generator and corresponding model.
+```bash
+rails g active_outbox outbox
+```
+After running the migration, create an initializer under `config/initializers/active_outbox.rb` and setup the default outbox class to the new `Outbox` model you just created.
+```ruby
+# frozen_string_literal: true
+
+Rails.application.reloader.to_prepare do
+  ActiveOutbox.configure do |config|
+    config.outbox_mapping = {
+      'default' => 'Outbox'
+    }
+  end
+end
+```
+
+To allow models to store Outbox records on changes, you will have to include the `Outboxable` concern.
+```ruby
+# app/models/user.rb
+
+class User < ApplicationRecord
+  include ActiveOutbox::Outboxable
+end
+```
+### Base Events
+Using the User model as an example, the default event names provided are:
+- USER_CREATED
+- USER_UPDATED
+- USER_DESTROYED
+
+### Custom Events
+If you want to persist a custom event other than the provided base events, you can do so.
+```ruby
+user.save(outbox_event: 'YOUR_CUSTOM_EVENT')
+```
+## Advanced Usage
+If more granularity is desired multiple `Outbox` classes can be configured. After creating the needed `Outbox` classes for each module you can specify multiple mappings in the initializer.
+```ruby
+# frozen_string_literal: true
+
+Rails.application.reloader.to_prepare do
+  ActiveOutbox.configure do |config|
+    config.outbox_mapping = {
+      'Member' => 'Member::Outbox',
+      'UserAccess' => 'UserAccess::Outbox'
+    }
+  end
+end
+```
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/rootstrap/active_outbox. 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/rootstrap/active_outbox/blob/main/CODE_OF_CONDUCT.md).
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/license/mit/).
+
+## Code of Conduct
+
+Everyone interacting in the ActiveOutbox project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/rootstrap/active_outbox/blob/main/CODE_OF_CONDUCT.md).

data/bin/outbox

@@ -1,4 +1,5 @@
 #!/usr/bin/env ruby
+# frozen_string_literal: true
 
 require 'rails'
 require 'active_outbox'

data/lib/active_outbox/adapter_helper.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module ActiveOutbox
+  module AdapterHelper
+    def self.uuid_type
+      postgres? ? 'uuid' : 'string'
+    end
+
+    def self.json_type
+      postgres? ? 'jsonb' : 'string'
+    end
+
+    def self.postgres?
+      ActiveRecord::Base.connection.adapter_name.downcase == 'postgresql'
+    end
+  end
+end

data/lib/active_outbox/configuration.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module ActiveOutbox
   class << self
     attr_accessor :configuration

data/lib/active_outbox/errors.rb

@@ -2,21 +2,20 @@
 
 module ActiveOutbox
   class OutboxConfigurationError < StandardError; end
+
   class OutboxClassNotFoundError < OutboxConfigurationError
     def message
       <<~MESSAGE
-Missing Outbox class definition in module. Use `rails generate outbox <outbox model name>`.
-Define default class in `config/initializers/active_outbox.rb`:
+        Missing Outbox class definition. Configure mapping in `config/initializers/active_outbox.rb`:
 
-Rails.application.reloader.to_prepare do
-  ActiveOutbox.configure do |config|
-    config.outbox_mapping = {
-      'Default' => <outbox model name>,
-      'Meetings' => 'Meetings::Outbox'
-    }
-  end
-end
-MESSAGE
+        Rails.application.reloader.to_prepare do
+          ActiveOutbox.configure do |config|
+            config.outbox_mapping = {
+              'default' => <outbox model name>
+            }
+          end
+        end
+      MESSAGE
     end
   end
 end

data/lib/active_outbox/generators/{outbox_generator.rb → active_outbox_generator.rb}

@@ -1,16 +1,19 @@
+# frozen_string_literal: true
+
 require 'rails'
 require 'rails/generators'
 require 'rails/generators/active_record'
 
-class OutboxGenerator < ActiveRecord::Generators::Base
-  source_root File.expand_path("../templates", __FILE__)
+class ActiveOutboxGenerator < ActiveRecord::Generators::Base
+  include ActiveOutbox::AdapterHelper
+  source_root File.expand_path('templates', __dir__)
 
   class_option :root_components_path, type: :string, default: Rails.root
 
   def create_migration_files
     migration_path = "#{options['root_components_path']}/db/migrate"
     migration_template(
-      "migration.rb",
+      'migration.rb',
       "#{migration_path}/outbox_create_#{table_name}.rb",
       migration_version: migration_version
     )
@@ -23,16 +26,4 @@ class OutboxGenerator < ActiveRecord::Generators::Base
   def table_name
     "#{name}_outboxes"
   end
-
-  def uuid_type
-    postgres? ? 'uuid' : 'string'
-  end
-
-  def json_type
-    postgres? ? 'jsonb' : 'string'
-  end
-
-  def postgres?
-    ActiveRecord::Base.connection.adapter_name.downcase == 'postgresql'
-  end
 end

data/lib/active_outbox/generators/templates/migration.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 class OutboxCreate<%= table_name.camelize.singularize %> < ActiveRecord::Migration<%= migration_version %>
   def change
     create_table :<%= table_name %> do |t|

data/lib/active_outbox/outboxable.rb

@@ -24,36 +24,23 @@ module ActiveOutbox
     end
 
     def save(**options, &block)
-      if options[:outbox_event].present?
-        @outbox_event = options[:outbox_event].underscore.upcase
-      end
-
+      assign_outbox_event(options)
       super(**options, &block)
     end
 
     def save!(**options, &block)
-      if options[:outbox_event].present?
-        @outbox_event = options[:outbox_event].underscore.upcase
-      end
-
+      assign_outbox_event(options)
       super(**options, &block)
     end
 
     private
 
+    def assign_outbox_event(options)
+      @outbox_event = options[:outbox_event].underscore.upcase if options[:outbox_event].present?
+    end
+
     def create_outbox!(action, event_name)
-      unless self.class.module_parent.const_defined?('OUTBOX_MODEL')
-        *namespace, klass = self.class.name.underscore.upcase.split('/')
-        namespace = namespace.reverse.join('.')
-        outbox_model_name = ActiveOutbox.configuration.outbox_mapping[self.class.module_parent.name.underscore] ||
-                              ActiveOutbox.configuration.outbox_mapping['default']
-        raise OutboxClassNotFoundError if outbox_model_name.nil?
-      
-        outbox_model = outbox_model_name.safe_constantize
-        self.class.module_parent.const_set('OUTBOX_MODEL', outbox_model)
-      end
-      
-      outbox = self.class.module_parent.const_get('OUTBOX_MODEL').new(
+      outbox = outbox_model.new(
         aggregate: self.class.name,
         aggregate_identifier: try(:identifier) || id,
         event: @outbox_event || event_name,
@@ -62,41 +49,59 @@ module ActiveOutbox
       )
       @outbox_event = nil
 
-      if outbox.invalid?
-        outbox.errors.each do |error|
-          self.errors.import(error, attribute: "outbox.#{error.attribute}")
-        end
+      handle_outbox_errors(outbox) if outbox.invalid?
+      outbox.save!
+    end
+
+    def outbox_model
+      module_parent = self.class.module_parent
+
+      unless module_parent.const_defined?('OUTBOX_MODEL')
+        outbox_model = outbox_model_name!.safe_constantize
+        module_parent.const_set('OUTBOX_MODEL', outbox_model)
       end
 
-      outbox.save!
+      module_parent.const_get('OUTBOX_MODEL')
     end
 
-    def formatted_payload(action)
-      payload = payload(action)
-      case ActiveRecord::Base.connection.adapter_name.downcase
-      when 'postgresql'
-        payload
-      else
-        payload.to_json
+    def outbox_model_name!
+      namespace_outbox_mapping || default_outbox_mapping || raise(OutboxClassNotFoundError)
+    end
+
+    def namespace_outbox_mapping
+      namespace = self.class.name.split('/').first
+
+      ActiveOutbox.configuration.outbox_mapping[namespace&.underscore]
+    end
+
+    def default_outbox_mapping
+      ActiveOutbox.configuration.outbox_mapping['default']
+    end
+
+    def handle_outbox_errors(outbox)
+      outbox.errors.each do |error|
+        errors.import(error, attribute: "outbox.#{error.attribute}")
       end
     end
 
-    def payload(action)
-      payload = { before: nil, after: nil }
+    def formatted_payload(action)
+      payload = construct_payload(action)
+      AdapterHelper.postgres? ? payload : payload.to_json
+    end
+
+    def construct_payload(action)
       case action
       when :create
-        payload[:after] = as_json
+        { before: nil, after: as_json }
       when :update
-        # previous_changes => { 'name' => ['bob', 'robert']  }
         changes = previous_changes.transform_values(&:first)
-        payload[:before] = as_json.merge(changes)
-        payload[:after] = as_json
+        { before: as_json.merge(changes), after: as_json }
       when :destroy
-        payload[:before] = as_json
+        { before: as_json, after: nil }
       else
-        raise ActiveRecord::RecordNotSaved.new("Failed to create Outbox payload for #{self.class.name}: #{identifier}", self)
+        raise ActiveRecord::RecordNotSaved.new("Failed to create Outbox payload for #{self.class.name}: #{identifier}",
+                                               self)
       end
-      payload
     end
   end
 end

data/lib/active_outbox/railtie.rb

@@ -1,4 +1,6 @@
+# frozen_string_literal: true
+
 module ActiveOutbox
   class Railtie < Rails::Railtie
   end
-end
+end

data/lib/active_outbox.rb

@@ -1,5 +1,8 @@
+# frozen_string_literal: true
+
+require 'active_outbox/adapter_helper'
 require 'active_outbox/configuration'
 require 'active_outbox/errors'
+require 'active_outbox/generators/active_outbox_generator'
 require 'active_outbox/outboxable'
-require 'active_outbox/generators/outbox_generator'
 require 'active_outbox/railtie' if defined?(Rails::Railtie)

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: active_outbox
 version: !ruby/object:Gem::Version
-  version: 0.0.2
+  version: 0.0.3
 platform: ruby
 authors:
 - Guillermo Aguirre
-autorequire: 
+autorequire:
 bindir: bin
 cert_chain: []
-date: 2023-07-05 00:00:00.000000000 Z
+date: 2023-10-20 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -16,113 +16,15 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '7.0'
+        version: '6.1'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '7.0'
-- !ruby/object:Gem::Dependency
-  name: pry-rails
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: 0.3.6
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: 0.3.6
-- !ruby/object:Gem::Dependency
-  name: reek
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: 6.0.6
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: 6.0.6
-- !ruby/object:Gem::Dependency
-  name: rspec-rails
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: 3.8.0
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: 3.8.0
-- !ruby/object:Gem::Dependency
-  name: rubocop
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: 1.22.0
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: 1.22.0
-- !ruby/object:Gem::Dependency
-  name: simplecov
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: 0.17.1
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: 0.17.1
-- !ruby/object:Gem::Dependency
-  name: sqlite3
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - '='
-      - !ruby/object:Gem::Version
-        version: 1.4.2
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - '='
-      - !ruby/object:Gem::Version
-        version: 1.4.2
-- !ruby/object:Gem::Dependency
-  name: byebug
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: 11.1.3
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: 11.1.3
-description: A Transactional Outbox implementation for ActiveRecord
+        version: '6.1'
+description:
 email: guillermoaguirre1@gmail.com
 executables:
 - outbox
@@ -132,9 +34,10 @@ files:
 - README.md
 - bin/outbox
 - lib/active_outbox.rb
+- lib/active_outbox/adapter_helper.rb
 - lib/active_outbox/configuration.rb
 - lib/active_outbox/errors.rb
-- lib/active_outbox/generators/outbox_generator.rb
+- lib/active_outbox/generators/active_outbox_generator.rb
 - lib/active_outbox/generators/templates/migration.rb
 - lib/active_outbox/outboxable.rb
 - lib/active_outbox/railtie.rb
@@ -142,7 +45,7 @@ homepage: https://rubygems.org/gems/active_outbox
 licenses:
 - MIT
 metadata: {}
-post_install_message: 
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -150,15 +53,15 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '0'
+      version: '3.0'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.1.6
-signing_key: 
+rubygems_version: 3.4.10
+signing_key:
 specification_version: 4
-summary: ActiveOutbox
+summary: A Transactional Outbox implementation for ActiveRecord
 test_files: []