rails_outbox 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 1d94b1bb0518502cdc2f533c9b2c62f74cba24977608ff9461bf26dcc199ae32
+  data.tar.gz: 0a391ea6f13216b6625ef7948356ff8e2a61d312b88670c9b5106708169de526
+SHA512:
+  metadata.gz: 66ffbab3bf48d09fd3b9013487da810f8b66da36c0b0fa6fd284027437127a07b8b322a27f2c4a602f2be3d0a1b11d425ca3d6e3ac3bf3beae837000b1d0fb8c
+  data.tar.gz: 93488c76456fd42a6dc344eecf836c42d60013bfa80e72baa5eb17cb3c18b75c4ad88cacf2e41965e020de9f7ad3832c4ea34253f001ee60cc78b32c852701f4

data/README.md

@@ -0,0 +1,110 @@
+# Rails Outbox
+A Transactional Outbox implementation for Rails and 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 rails_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 'rails_outbox'
+```
+
+And then execute:
+```bash
+bundle install
+```
+Or install it yourself as:
+```bash
+gem install rails_outbox
+```
+
+## Usage
+### Setup
+Create the outbox table and model using the provided generator. Any model name can be passed as an argument but if empty it will default to `outboxes` and `Outbox` respectively.
+```bash
+rails g rails_outbox:model <optional model_name>
+
+  create  db/migrate/20231115182800_rails_outbox_create_<model_name_>outboxes.rb
+  create  app/models/<model_name_>outbox.rb
+```
+After running the migration, create an initializer under `config/initializers/rails_outbox.rb` and setup the default outbox class to the new `Outbox` model you just created.
+```bash
+rails g rails_outbox:install
+```
+
+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 RailsOutbox::Outboxable
+end
+```
+### Base Events
+Using the User model as an example, the default event names provided are:
+- USER_CREATED
+- USER_UPDATED
+- USER_DESTROYED
+
+This will live under `RailsOutbox::Events` wherever you include the `Outboxable` concern. The intent is to define it under `Object` for non-namespaced models, as well as under each model namespace that is encountered.
+
+### 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
+### Supporting UUIDs
+By default our Outbox migration has an `aggregate_identifier` field which serves the purpose of identifying which record was involved in the event emission. We default to integer IDs, but if you're using UUIDs as a primary key for your records you have to adjust the migrations accordingly. To do so just run the model generator with the `--uuid` flag.
+```bash
+rails g rails_outbox:model <optional model_name> --uuid
+```
+### Modularized Outbox Mappings
+If more granularity is desired multiple outbox classes can be configured. Using the provided generators we can specify namespaces and the folder structure.
+```bash
+rails g rails_outbox:model user_access/ --component-path packs/user_access
+
+  create  packs/user_access/db/migrate/20231115181205_rails_outbox_create_user_access_outboxes.rb
+  create  packs/user_access/app/models/user_access/outbox.rb
+```
+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
+  RailsOutbox.configure do |config|
+    config.outbox_mapping = {
+      'member' => 'Member::Outbox',
+      'user_access' => 'UserAccess::Outbox'
+    }
+  end
+end
+```
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/guillermoap/rails_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/guillermoap/rails_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 RailsOutbox project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/guillermoap/rails_outbox/blob/main/CODE_OF_CONDUCT.md).

data/bin/outbox

@@ -0,0 +1,7 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require 'rails'
+require 'rails_outbox'
+
+rails g outbox ARGV[0]

data/lib/generators/rails_outbox/install/install_generator.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require 'rails/generators/base'
+
+module RailsOutbox
+  module Generators
+    class InstallGenerator < Rails::Generators::Base
+      source_root File.expand_path('../templates', __dir__)
+
+      desc 'Creates an initializer file at config/initializers/rails_outbox.rb'
+
+      def create_initializer_file
+        copy_file('initializer.rb', Rails.root.join('config', 'initializers', 'rails_outbox.rb'))
+      end
+    end
+  end
+end

data/lib/generators/rails_outbox/model/model_generator.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+require 'rails'
+require 'rails/generators/active_record'
+require 'rails/generators/base'
+require 'rails/generators/migration'
+
+module RailsOutbox
+  module Generators
+    class ModelGenerator < Rails::Generators::Base
+      source_root File.expand_path('../templates', __dir__)
+
+      include RailsOutbox::AdapterHelper
+      include Rails::Generators::Migration
+
+      class << self
+        delegate :next_migration_number, to: ActiveRecord::Generators::Base
+      end
+
+      desc 'Creates the Outbox model migration'
+
+      argument :model_name, type: :string, default: ''
+      class_option :component_path,
+        type: :string,
+        desc: 'Indicates where to create the outbox migration'
+      class_option :uuid,
+        type: :boolean,
+        default: false,
+        desc: 'Use UUID to identify aggregate records in events. Defaults to ID'
+
+      def create_migration_file
+        migration_path = "#{root_path}/db/migrate"
+        migration_template(
+          'migration.rb',
+          "#{migration_path}/rails_outbox_create_#{table_name}.rb",
+          migration_version: migration_version
+        )
+
+        template('model.rb', "#{root_path}/app/models/#{path_name}.rb")
+      end
+
+      def root_path
+        path = options['component_path'].blank? ? '' : "/#{options['component_path']}"
+        "#{Rails.root}#{path}"
+      end
+
+      def migration_version
+        "[#{Rails::VERSION::MAJOR}.#{Rails::VERSION::MINOR}]"
+      end
+
+      def table_name
+        *namespace, name = model_name.downcase.split('/')
+        name = name.blank? ? 'outboxes' : "#{name}_outboxes"
+        namespace = namespace.join('_')
+        namespace.blank? ? name : "#{namespace}_#{name}"
+      end
+
+      def path_name
+        name = ''
+        *namespace = model_name.downcase.split('/')
+        if (model_name.include?('/') && model_name.last != '/' && namespace.length > 1) || !model_name.include?('/')
+          name = namespace.pop
+        end
+        name = name.blank? ? 'outbox' : "#{name}_outbox"
+        namespace = namespace.join('/')
+        namespace.blank? ? name : "#{namespace}/#{name}"
+      end
+
+      def aggregate_identifier_type
+        options['uuid'].present? ? RailsOutbox::AdapterHelper.uuid_type : RailsOutbox::AdapterHelper.bigint_type
+      end
+    end
+  end
+end

data/lib/generators/rails_outbox/templates/initializer.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+Rails.application.reloader.to_prepare do
+  RailsOutbox.configure do |config|
+    # To configure which Outbox class maps to which domain
+    # See https://github.com/guillermoap/rails_outbox#advanced-usage for advanced examples
+    config.outbox_mapping = {
+      'default' => 'Outbox'
+    }
+
+    # Configure database adapter
+    # config.adapter = :postgresql
+  end
+end

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

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+class RailsOutboxCreate<%= table_name.camelize %> < ActiveRecord::Migration<%= migration_version %>
+  def change
+    create_table :<%= table_name %> do |t|
+      t.<%= RailsOutbox::AdapterHelper.uuid_type %> :identifier, null: false, index: { unique: true }
+      t.string :event, null: false
+      t.<%= RailsOutbox::AdapterHelper.json_type %> :payload
+      t.string :aggregate, null: false
+      t.<%= aggregate_identifier_type %> :aggregate_identifier, null: false, index: true
+
+      t.timestamps
+    end
+  end
+end

data/lib/generators/rails_outbox/templates/model.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+class <%= path_name.camelize %> < ApplicationRecord
+  validates_presence_of :identifier, :payload, :aggregate, :aggregate_identifier, :event
+end

data/lib/rails_outbox/adapter_helper.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module RailsOutbox
+  module AdapterHelper
+    def self.uuid_type
+      return 'uuid' if postgres?
+      return 'string' if mysql?
+
+      'string'
+    end
+
+    def self.json_type
+      return 'jsonb' if postgres?
+      return 'json' if mysql?
+
+      'string'
+    end
+
+    def self.bigint_type
+      return 'bigint' if postgres? || mysql?
+
+      'integer'
+    end
+
+    def self.postgres?
+      ActiveRecord::Base.connection.adapter_name.downcase == 'postgresql'
+    end
+
+    def self.mysql?
+      ActiveRecord::Base.connection.adapter_name.downcase == 'mysql2'
+    end
+  end
+end

data/lib/rails_outbox/errors.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module RailsOutbox
+  class OutboxConfigurationError < StandardError; end
+
+  class OutboxClassNotFoundError < OutboxConfigurationError
+    def message
+      <<~MESSAGE
+        Missing Outbox class definition. Configure mapping in `config/initializers/rails_outbox.rb`:
+
+        Rails.application.reloader.to_prepare do
+          RailsOutbox.configure do |config|
+            config.outbox_mapping = {
+              'default' => <outbox model name>
+            }
+          end
+        end
+      MESSAGE
+    end
+  end
+end

data/lib/rails_outbox/outboxable.rb

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+require 'active_support/concern'
+
+module RailsOutbox
+  module Outboxable
+    extend ActiveSupport::Concern
+
+    included do
+      *namespace, klass = name.underscore.upcase.split('/')
+      namespace = namespace.reverse.join('.')
+
+      module_parent.const_set('RailsOutbox', Module.new) unless module_parent.const_defined?('RailsOutbox', false)
+
+      unless module_parent::RailsOutbox.const_defined?('Events', false)
+        module_parent::RailsOutbox.const_set('Events', Module.new)
+      end
+
+      { create: 'CREATED', update: 'UPDATED', destroy: 'DESTROYED' }.each do |key, value|
+        const_name = "#{klass}_#{value}"
+
+        unless module_parent::RailsOutbox::Events.const_defined?(const_name)
+          module_parent::RailsOutbox::Events.const_set(const_name,
+            "#{const_name}#{namespace.blank? ? '' : '.'}#{namespace}")
+        end
+
+        event_name = module_parent::RailsOutbox::Events.const_get(const_name)
+
+        send("after_#{key}") { create_outbox!(key, event_name) }
+      end
+    end
+
+    def save(**options, &block)
+      assign_outbox_event(options)
+      super(**options, &block)
+    end
+
+    def save!(**options, &block)
+      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)
+      outbox = outbox_model.new(
+        aggregate: self.class.name,
+        aggregate_identifier: send(self.class.primary_key),
+        event: @outbox_event || event_name,
+        identifier: SecureRandom.uuid,
+        payload: formatted_payload(action)
+      )
+      @outbox_event = nil
+      handle_outbox_errors(outbox) if outbox.invalid?
+      outbox.save!
+    end
+
+    def outbox_model
+      module_parent = self.class.module_parent
+      # sets _inherit_ option to false so it doesn't lookup in ancestors for the constant
+      unless module_parent.const_defined?('OUTBOX_MODEL', false)
+        outbox_model = outbox_model_name!.safe_constantize
+        module_parent.const_set('OUTBOX_MODEL', outbox_model)
+      end
+
+      module_parent.const_get('OUTBOX_MODEL')
+    end
+
+    def outbox_model_name!
+      namespace_outbox_mapping || default_outbox_mapping || raise(OutboxClassNotFoundError)
+    end
+
+    def namespace_outbox_mapping
+      namespace = self.class.module_parent.name.underscore
+
+      RailsOutbox.config.outbox_mapping[namespace]
+    end
+
+    def default_outbox_mapping
+      RailsOutbox.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 formatted_payload(action)
+      payload = construct_payload(action)
+      AdapterHelper.postgres? ? payload : payload.to_json
+    end
+
+    def construct_payload(action)
+      case action
+      when :create
+        { before: nil, after: as_json }
+      when :update
+        changes = previous_changes.transform_values(&:first)
+        { before: as_json.merge(changes), after: as_json }
+      when :destroy
+        { before: as_json, after: nil }
+      else
+        raise ActiveRecord::RecordNotSaved.new(
+          "Failed to create Outbox payload for #{self.class.name}: #{send(self.class.primary_key)}",
+          self
+        )
+      end
+    end
+  end
+end

data/lib/rails_outbox/railtie.rb

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

data/lib/rails_outbox.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+require 'rails_outbox/adapter_helper'
+require 'rails_outbox/errors'
+require 'rails_outbox/outboxable'
+require 'rails_outbox/railtie' if defined?(Rails::Railtie)
+require 'dry-configurable'
+
+module RailsOutbox
+  extend Dry::Configurable
+
+  setting :adapter, default: :sqlite
+  setting :outbox_mapping, default: {}
+end

metadata

@@ -0,0 +1,83 @@
+--- !ruby/object:Gem::Specification
+name: rails_outbox
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Guillermo Aguirre
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2024-09-06 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: dry-configurable
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.1'
+description:
+email: guillermoaguirre@hey.com
+executables:
+- outbox
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- bin/outbox
+- lib/generators/rails_outbox/install/install_generator.rb
+- lib/generators/rails_outbox/model/model_generator.rb
+- lib/generators/rails_outbox/templates/initializer.rb
+- lib/generators/rails_outbox/templates/migration.rb
+- lib/generators/rails_outbox/templates/model.rb
+- lib/rails_outbox.rb
+- lib/rails_outbox/adapter_helper.rb
+- lib/rails_outbox/errors.rb
+- lib/rails_outbox/outboxable.rb
+- lib/rails_outbox/railtie.rb
+homepage: https://github.com/guillermoap/rails_outbox
+licenses:
+- MIT
+metadata: {}
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.16
+signing_key:
+specification_version: 4
+summary: A Transactional Outbox implementation for ActiveRecord and Rails
+test_files: []