active_outbox 0.0.2 → 0.0.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: aa92d48552facbc79e9ec9ae9f58a599d533267a490f7199c5b4e87b9f62f83b
-  data.tar.gz: a04f7dbe86d0b7e53296079be077db720c50baa48f2b53237cb18423fb33209d
+  metadata.gz: 1b6c2d51498f61533b935cb0d210cbed4c6159eeee4ae9d142e08564c43a7362
+  data.tar.gz: f12ce116296edaf0100e39e927b3a264fac24cc8c66f778a49a7b5ebe2b008fe
 SHA512:
-  metadata.gz: acfbc64c4ad058a44d56c170fd194d300841cdfd8bdcaa950b9d63b90ae23f392f3bfdf7c1240e0564d7312680362057360114e9e98e9aaafec842639dd0ab98
-  data.tar.gz: 6449a7b730797fb16e55fca130e0ee7d4813bda5d06c34c4093f23bb6e20d77e5bca07cdcc5ed212d30c42617b6035ffcb31c2fc0033b90ebb0653dd6fe6bf25
+  metadata.gz: 5b0583688cda8d0a641e3ff22624d6ae11976bd664a35ff393bd6fa5b1afe4206acda7bb1f9e6cd66b6c0cd6bde77d5ab57920c5ce07be40425f652571ea9fc1
+  data.tar.gz: 252a0cea22365fdb05527ce7fbe9dd59c63e8560cb6d655d07b81e26f4b95af25b424e8d0f28fe5ae9611731a30c980d44c11145450f8501479b96a82ae3c225

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/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.config.outbox_mapping[namespace&.underscore]
+    end
+
+    def default_outbox_mapping
+      ActiveOutbox.config.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,15 @@
-require 'active_outbox/configuration'
+# frozen_string_literal: true
+
+require 'active_outbox/adapter_helper'
 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)
+require 'dry-configurable'
+
+module ActiveOutbox
+  extend Dry::Configurable
+
+  setting :adapter, default: :sqlite
+  setting :outbox_mapping, default: {}
+end

metadata

@@ -1,128 +1,44 @@
 --- !ruby/object:Gem::Specification
 name: active_outbox
 version: !ruby/object:Gem::Version
-  version: 0.0.2
+  version: 0.0.4
 platform: ruby
 authors:
 - Guillermo Aguirre
-autorequire: 
+autorequire:
 bindir: bin
 cert_chain: []
-date: 2023-07-05 00:00:00.000000000 Z
+date: 2023-10-23 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
-  name: rails
+  name: dry-configurable
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '7.0'
+        version: '1.0'
   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
+        version: '1.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
+  name: rails
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 11.1.3
-  type: :development
+        version: '6.1'
+  type: :runtime
   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 +48,9 @@ files:
 - README.md
 - bin/outbox
 - lib/active_outbox.rb
-- lib/active_outbox/configuration.rb
+- lib/active_outbox/adapter_helper.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 +58,7 @@ homepage: https://rubygems.org/gems/active_outbox
 licenses:
 - MIT
 metadata: {}
-post_install_message: 
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -150,15 +66,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: []

data/lib/active_outbox/configuration.rb

@@ -1,26 +0,0 @@
-module ActiveOutbox
-  class << self
-    attr_accessor :configuration
-
-    def configuration
-      @configuration ||= ActiveOutbox::Configuration.new
-    end
-
-    def reset
-      @configuration = ActiveOutbox::Configuration.new
-    end
-
-    def configure
-      yield(configuration)
-    end
-  end
-
-  class Configuration
-    attr_accessor :adapter, :outbox_mapping
-
-    def initialize
-      @adapter = :sqlite
-      @outbox_mapping = {}
-    end
-  end
-end