rails_simple_event_sourcing 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 9789524ed9ede4a4a16561d587fbfc729fe825d0e4196390b6bd39d4196ed56d
+  data.tar.gz: 5bbc7f33e45dd59ce805b06cea72a84a4a8f63c852fc859270eef9f2b8d11cb7
+SHA512:
+  metadata.gz: 4112017f8f52f621b401dc463be3673f635176bfcee2732a7a0502757d4472a2897328169a68ddea60e4e8ec9726068d45daa8f1f4d70e6b471d42efffbd0da7
+  data.tar.gz: cbe47f8933ff692665a019fce022e1f52bdc849067fb7ae10bbebef02a9fb3c5eb6222d28d3ce5205249e37466a6733544de7dbd388f4aae43fc4a1219cb96c2

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright Damian Baćkowski
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,268 @@
+# RailsSimpleEventSourcing ![tests](https://github.com/dbackowski/rails_simple_event_sourcing/actions/workflows/minitest.yml/badge.svg) ![codecheck](https://github.com/dbackowski/rails_simple_event_sourcing/actions/workflows/codecheck.yml/badge.svg)
+
+This is a very minimalist implementation of an event sourcing pattern, if you want a full-featured framework in ruby you can check out one of these:
+- https://www.sequent.io
+- https://railseventstore.org
+
+I wanted to learn how to build this from scratch and also wanted to build something that would be very easy to use since most of the fully featured frameworks like the two above require a lot of configuration and learning.
+
+### Important notice
+
+This plugin will only work with Postgres database because it uses JSONB data type which is only supported by this database.
+
+## Usage
+
+So how does it all work?
+
+Let's start with the directory structure:
+
+```
+app/
+├─ domain/
+│  ├─ customer/
+│  │  ├─ command_handlers/
+│  │  │  ├─ create.rb
+│  │  ├─ events/
+│  │  │  ├─ customer_created.rb
+│  │  ├─ commands/
+│  │  │  ├─ create.rb
+```
+
+The name of the top directory can be different because Rails does not namespace it.
+
+Based on the example above, the usage looks like this
+
+Command -> Command Handler -> Create Event (which under the hood writes changes to the appropriate model)
+
+Explanation of each of these blocks above:
+
+- `Command` - is responsible for any action you want to take in your system, it is also responsible for validating the input parameters it takes (you can use the same validations you would normally use in models).
+
+Example:
+
+```ruby
+class Customer
+  module Commands
+    class Create < RailsSimpleEventSourcing::Commands::Base
+      attr_accessor :first_name, :last_name, :email
+
+      validates :first_name, presence: true
+      validates :last_name, presence: true
+      validates :email, presence: true
+    end
+  end
+end
+```
+
+- `CommandHandler` - is responsible for handling the passed command (it automatically checks if a command is valid), making additional API calls, doing additional business logic, and finally creating a proper event. This should always return the `RailsSimpleEventSourcing::Result` struct.
+
+This struct has 3 keywords:
+- `success?:` true/false (if everything went well, commands are automatically validated, but there might still be an API call here, etc., so you can return false if something went wrong)
+- `data:` data that you want to return, eg. to the controller (in the example above the `event.aggregate` will return a proper instance of the Customer model)
+- `errors:` in a scenario where you set `success?:false`, you can also return some related errors here (see: test/dummy/app/domain/customer/command_handlers/create.rb for an example)
+
+Example:
+
+```ruby
+class Customer
+  module CommandHandlers
+    class Create < RailsSimpleEventSourcing::CommandHandlers::Base
+      def call
+        event = Customer::Events::CustomerCreated.create(
+          first_name: @command.first_name,
+          last_name: @command.last_name,
+          email: @command.email,
+          created_at: Time.zone.now,
+          updated_at: Time.zone.now
+        )
+
+        RailsSimpleEventSourcing::Result.new(success?: true, data: event.aggregate)
+      end
+    end
+  end
+end
+```
+
+- `Event` - is responsible for storing immutable data of your actions, you should use past tense for naming events since an event is something that has already happened (e.g. customer was created)
+
+Example:
+
+```ruby
+class Customer
+  module Events
+    class CustomerCreated < RailsSimpleEventSourcing::Event
+      aggregate_model_name Customer
+      event_attributes :first_name, :last_name, :email, :created_at, :updated_at
+
+      def apply(aggregate)
+        aggregate.id = aggregate_id
+        aggregate.first_name = first_name
+        aggregate.last_name = last_name
+        aggregate.email = email
+        aggregate.created_at = created_at
+        aggregate.updated_at = updated_at
+      end
+    end
+  end
+end
+```
+
+In the example above:
+- `aggregate_model_name` is used for the corresponding model (each model is normally set to read-only mode since the only way to modify it should be via events), this param is optional since you can have an event that is not applied to the model, e.g. UserLoginAlreadyTaken
+- `event_attributes` - defines params that will be stored in the event and these params will be available to apply to the model via the `apply(aggregate)` method (where aggregate is an instance of your model passed in aggregate_model_name).
+
+Here is an example of a custom controller that uses all the blocks described above:
+
+```ruby
+class CustomersController < ApplicationController
+  def create
+    cmd = Customer::Commands::Create.new(
+      first_name: params[:first_name],
+      last_name: params[:last_name],
+      email: params[:email]
+    )
+    handler = RailsSimpleEventSourcing::CommandHandler.new(cmd).call
+
+    if handler.success?
+      render json: handler.data
+    else
+      render json: { errors: handler.errors }, status: :unprocessable_entity
+    end
+  end
+end
+```
+
+Now, if you make an API call using curl:
+
+```sh
+curl -X POST http://localhost:3000/customers \
+  -H 'Content-Type: application/json' \
+  -d '{ "first_name": "John", "last_name": "Doe" }' | jq
+```
+
+You will get the response:
+
+```json
+{
+  "id": 1,
+  "first_name": "John",
+  "last_name": "Doe",
+  "created_at": "2024-08-03T16:52:30.829Z",
+  "updated_at": "2024-08-03T16:52:30.848Z"
+}
+```
+
+Run `rails c` and do the following:
+
+```ruby
+Customer.last
+=>
+#<Customer:0x0000000107e20998
+ id: 1,
+ first_name: "John",
+ last_name: "Doe",
+ created_at: Sat, 03 Aug 2024 16:52:30.829043000 UTC +00:00,
+ updated_at: Sat, 03 Aug 2024 16:52:30.848243000 UTC +00:00>
+Customer.last.events
+[#<Customer::Events::CustomerCreated:0x0000000108dbcac8
+  id: 1,
+  type: "Customer::Events::CustomerCreated",
+  event_type: "Customer::Events::CustomerCreated",
+  aggregate_id: "1",
+  eventable_type: "Customer",
+  eventable_id: 1,
+  payload: {"last_name"=>"Doe", "created_at"=>"2024-08-03T16:58:59.952Z", "first_name"=>"John", "updated_at"=>"2024-08-03T16:58:59.952Z"},
+  metadata:
+   {"request_id"=>"2a40d4f9-509b-4b49-a39f-d978679fa5ef",
+    "request_ip"=>"::1",
+    "request_params"=>{"action"=>"create", "customer"=>{"last_name"=>"Doe", "first_name"=>"John"}, "last_name"=>"Doe", "controller"=>"customers", "first_name"=>"John"},
+    "request_user_agent"=>"curl/8.6.0"},
+  created_at: Sat, 03 Aug 2024 16:58:59.973815000 UTC +00:00,
+  updated_at: Sat, 03 Aug 2024 16:58:59.973815000 UTC +00:00>]
+```
+
+As you can see, customer has been created and if you check its `.events` relationship, you should see an event that created it.
+This event has the same attributes in the payload as you set using the `event_attributes` method of the `Customer::Events::CustomerCreated` class.
+There is also a metadata field, which is also defined as JSON, and you can store additional things in this field (this is just for information).
+
+To have these metadata fields populated automatically, you need to include `RailsSimpleEventSourcing::SetCurrentRequestDetails` in your ApplicationController.
+
+Example:
+
+
+```ruby
+class ApplicationController < ActionController::Base
+  include RailsSimpleEventSourcing::SetCurrentRequestDetails
+end
+```
+
+You can override metadata fields by defining the `event_metadata` method in the controller, this method should return a Hash which will be stored in the metadata field of the event.
+
+By default, this method looks like this:
+
+```ruby
+def event_metadata
+  parameter_filter = ActiveSupport::ParameterFilter.new(Rails.application.config.filter_parameters)
+
+  {
+    request_id: request.uuid,
+    request_user_agent: request.user_agent,
+    request_referer: request.referer,
+    request_ip: request.ip,
+    request_params: parameter_filter.filter(request.params)
+  }
+end
+```
+
+#### Important notice
+
+The data stored in the events should be immutable (i.e., you shouldn't change it after it's created), so they have simple protection against accidental modification, which means that the model is marked as read-only.
+
+The same goes for models, any model that should be updated by events should include `include RailsSimpleEventSourcing::Events`, this will give you access to the `.events` relation and you will have read-only protection as well (model should only be updated by creating an event).
+
+Example:
+
+```ruby
+class Customer < ApplicationRecord
+  include RailsSimpleEventSourcing::Events
+end
+```
+
+One thing to note here is that it would be better to do soft-deletes (mark record as deleted) instead of deleting records from the DB, since every record has relations called `events` when you have all the events that were applied to it.
+
+#### More examples
+
+There is a sample application in the `test/dummy/app` directory so you can see how updates and deletes are handled.
+
+## Installation
+Add this line to your application's Gemfile:
+
+```ruby
+gem "rails_simple_event_sourcing"
+```
+
+And then execute:
+```bash
+$ bundle
+```
+
+Or install it yourself as:
+```bash
+$ gem install rails_simple_event_sourcing
+```
+
+Copy migration to your app:
+```ruby
+rails rails_simple_event_sourcing:install:migrations
+```
+
+And then run the migration in order to create the rails_simple_event_sourcing_events table (the table that will store the event log):
+```ruby
+rake db:migrate
+```
+
+## Contributing
+Contribution directions go here.
+
+## License
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,8 @@
+require "bundler/setup"
+
+APP_RAKEFILE = File.expand_path("test/dummy/Rakefile", __dir__)
+load "rails/tasks/engine.rake"
+
+load "rails/tasks/statistics.rake"
+
+require "bundler/gem_tasks"

data/app/controllers/concerns/rails_simple_event_sourcing/set_current_request_details.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module RailsSimpleEventSourcing
+  module SetCurrentRequestDetails
+    extend ActiveSupport::Concern
+
+    included do
+      before_action :set_event_metadata
+
+      private
+
+      def set_event_metadata
+        CurrentRequest.metadata = event_metadata
+      end
+
+      def event_metadata
+        parameter_filter = ActiveSupport::ParameterFilter.new(Rails.application.config.filter_parameters)
+
+        {
+          request_id: request.uuid,
+          request_user_agent: request.user_agent,
+          request_referer: request.referer,
+          request_ip: request.ip,
+          request_params: parameter_filter.filter(request.params)
+        }
+      end
+    end
+  end
+end

data/app/models/concerns/rails_simple_event_sourcing/events.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module RailsSimpleEventSourcing
+  module Events
+    extend ActiveSupport::Concern
+    include ReadOnly
+
+    included do
+      has_many :events, class_name: 'RailsSimpleEventSourcing::Event', as: :eventable, dependent: :nullify
+    end
+  end
+end

data/app/models/concerns/rails_simple_event_sourcing/read_only.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module RailsSimpleEventSourcing
+  module ReadOnly
+    extend ActiveSupport::Concern
+
+    included do
+      def readonly?
+        super || !@write_access_enabled
+      end
+
+      def enable_write_access!
+        @write_access_enabled = true
+      end
+    end
+  end
+end

data/app/models/rails_simple_event_sourcing/current_request.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module RailsSimpleEventSourcing
+  class CurrentRequest < ActiveSupport::CurrentAttributes
+    attribute :metadata
+  end
+end

data/app/models/rails_simple_event_sourcing/event.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+module RailsSimpleEventSourcing
+  class Event < ApplicationRecord
+    include ReadOnly
+
+    belongs_to :eventable, polymorphic: true, optional: true
+
+    alias aggregate eventable
+
+    after_initialize :initialize_event
+    before_validation :enable_write_access_on_self, if: :new_record?
+    before_validation :apply_on_aggregate, if: :aggregate_defined?
+    before_save :add_metadata
+    before_save :assing_aggregate_id_and_persist_aggregate, if: :aggregate_defined?
+
+    def self.aggregate_model_name(name)
+      singleton_class.instance_variable_set(:@aggregate_model_name, name)
+    end
+
+    def aggregate_model_name
+      self.class.singleton_class.instance_variable_get(:@aggregate_model_name)
+    end
+
+    def self.event_attributes(*attributes)
+      @event_attributes ||= []
+
+      attributes.map(&:to_s).each do |attribute|
+        define_method attribute do
+          self.payload ||= {}
+          self.payload[attribute]
+        end
+
+        define_method "#{attribute}=" do |argument|
+          self.payload ||= {}
+          self.payload[attribute] = argument
+        end
+      end
+
+      @event_attributes
+    end
+
+    def apply(_aggregate)
+      raise NoMethodError, "You must implement #{self.class}#apply"
+    end
+
+    private
+
+    def aggregate_defined?
+      aggregate_model_name.present?
+    end
+
+    def initialize_event
+      self.class.prepend RailsSimpleEventSourcing::ApplyWithReturningAggregate
+      @aggregate = find_or_build_aggregate if aggregate_defined?
+      self.event_type = self.class
+      self.eventable = @aggregate
+    end
+
+    def enable_write_access_on_self
+      enable_write_access!
+    end
+
+    def apply_on_aggregate
+      @aggregate.enable_write_access!
+      apply(@aggregate)
+    end
+
+    def assing_aggregate_id_and_persist_aggregate
+      @aggregate.save! if aggregate_id.present?
+      self.aggregate_id = @aggregate.id
+    end
+
+    def add_metadata
+      return if CurrentRequest.metadata.blank?
+
+      self.metadata = CurrentRequest.metadata.compact.presence
+    end
+
+    def find_or_build_aggregate
+      return aggregate_model_name.find(aggregate_id).lock! if aggregate_id.present?
+
+      aggregate_model_name.new
+    end
+  end
+end

data/app/models/rails_simple_event_sourcing.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module RailsSimpleEventSourcing
+  def self.table_name_prefix
+    'rails_simple_event_sourcing_'
+  end
+end

data/config/routes.rb

@@ -0,0 +1,2 @@
+Rails.application.routes.draw do
+end

data/db/migrate/20231231133250_create_rails_simple_event_sourcing_events.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+class CreateRailsSimpleEventSourcingEvents < ActiveRecord::Migration[7.1]
+  def change
+    create_table :rails_simple_event_sourcing_events do |t|
+      t.references :eventable, polymorphic: true
+      t.string :type, null: false
+      t.string :event_type, null: false
+      t.string :aggregate_id
+      t.jsonb :payload
+      t.jsonb :metadata
+
+      t.timestamps
+
+      t.index :type
+      t.index :event_type
+      t.index :aggregate_id
+      t.index :payload, using: :gin
+      t.index :metadata, using: :gin
+    end
+  end
+end

data/lib/rails_simple_event_sourcing/apply_with_returning_aggregate.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module RailsSimpleEventSourcing
+  module ApplyWithReturningAggregate
+    def apply(aggregate)
+      aggregate.tap { super }
+    end
+  end
+end

data/lib/rails_simple_event_sourcing/command_handler.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module RailsSimpleEventSourcing
+  class CommandHandler
+    def initialize(command)
+      @command = command
+    end
+
+    def call
+      return Result.new(success?: false, errors: @command.errors) unless @command.valid?
+
+      initialize_command_handler.call
+    end
+
+    private
+
+    def initialize_command_handler
+      @command.class.to_s.gsub('::Commands::', '::CommandHandlers::').constantize.new(command: @command)
+    end
+  end
+end

data/lib/rails_simple_event_sourcing/command_handlers/base.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module RailsSimpleEventSourcing
+  module CommandHandlers
+    class Base
+      def initialize(command:)
+        @command = command
+      end
+
+      def call
+        raise NoMethodError, "You must implement #{self.class}#call"
+      end
+    end
+  end
+end

data/lib/rails_simple_event_sourcing/commands/base.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module RailsSimpleEventSourcing
+  module Commands
+    class Base
+      include ActiveModel::Model
+      include ActiveModel::Validations
+
+      attr_accessor :aggregate_id
+    end
+  end
+end

data/lib/rails_simple_event_sourcing/engine.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+require_relative 'command_handlers/base'
+require_relative 'commands/base'
+require_relative 'command_handler'
+require_relative 'apply_with_returning_aggregate'
+require_relative 'result'
+
+module RailsSimpleEventSourcing
+  class Engine < ::Rails::Engine
+    isolate_namespace RailsSimpleEventSourcing
+  end
+end

data/lib/rails_simple_event_sourcing/result.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module RailsSimpleEventSourcing
+  Result = Struct.new(:success?, :data, :errors, keyword_init: true)
+end

data/lib/rails_simple_event_sourcing/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module RailsSimpleEventSourcing
+  VERSION = '1.0.0'
+end

data/lib/rails_simple_event_sourcing.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require 'rails_simple_event_sourcing/version'
+require 'rails_simple_event_sourcing/engine'
+
+module RailsSimpleEventSourcing
+  # Your code goes here...
+end

data/lib/tasks/rails_simple_event_sourcing_tasks.rake

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+# desc "Explaining what the task does"
+# task :rails_simple_event_sourcing do
+#   # Task goes here
+# end

metadata

@@ -0,0 +1,121 @@
+--- !ruby/object:Gem::Specification
+name: rails_simple_event_sourcing
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Damian Baćkowski
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2024-10-08 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: pg
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.1'
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 7.1.2
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 7.1.2
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rubocop-rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: Rails simple event sourcing engine.
+email:
+- damianbackowski@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- MIT-LICENSE
+- README.md
+- Rakefile
+- app/assets/config/rails_simple_event_sourcing_manifest.js
+- app/controllers/concerns/rails_simple_event_sourcing/set_current_request_details.rb
+- app/models/concerns/rails_simple_event_sourcing/events.rb
+- app/models/concerns/rails_simple_event_sourcing/read_only.rb
+- app/models/rails_simple_event_sourcing.rb
+- app/models/rails_simple_event_sourcing/current_request.rb
+- app/models/rails_simple_event_sourcing/event.rb
+- config/routes.rb
+- db/migrate/20231231133250_create_rails_simple_event_sourcing_events.rb
+- lib/rails_simple_event_sourcing.rb
+- lib/rails_simple_event_sourcing/apply_with_returning_aggregate.rb
+- lib/rails_simple_event_sourcing/command_handler.rb
+- lib/rails_simple_event_sourcing/command_handlers/base.rb
+- lib/rails_simple_event_sourcing/commands/base.rb
+- lib/rails_simple_event_sourcing/engine.rb
+- lib/rails_simple_event_sourcing/result.rb
+- lib/rails_simple_event_sourcing/version.rb
+- lib/tasks/rails_simple_event_sourcing_tasks.rake
+homepage: https://github.com/dbackowski/rails_simple_event_sourcing
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/dbackowski/rails_simple_event_sourcing
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.1.6
+signing_key:
+specification_version: 4
+summary: Rails engine for simple event sourcing.
+test_files: []