active_record_projection 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 6db014f62ef839ae834307bbc60593b93dce62c2d78eee1a4df8cd02fb848f5f
+  data.tar.gz: bc2f4ed0e4c6afd4814448b6e61a0059ea4b73a998620e5d6ed184578940d0ef
+SHA512:
+  metadata.gz: b14e19b67a68e8662058c2022c7f6d6f21119646b5814cb700d3a4d13b956fef39a5a674ac387cdbf5d8cb681e19c870019be54b53b9f37139d2efc62f3abe7b
+  data.tar.gz: 5c56b026f4c90725189dbce6d09652243889eb2a8c7373f072a9c998321750aee184cde2c87306acc47d5a08acd4d687dfd8350a104cfaa82c88b4cf4452a7b6

data/README.md

@@ -0,0 +1,94 @@
+# Active Record Projection
+
+Persistent [Rails Event Store](https://railseventstore.org/) projections built on [Active Record](https://guides.rubyonrails.org/active_record_basics.html) models.
+
+Built on the Rails Event Store [Aggregate Root](https://railseventstore.org/docs/core-concepts/event-sourcing).
+
+How it works:
+- a projection is built from a [stream](https://railseventstore.org/docs/core-concepts/link) of events
+  - a projection only has a single stream but a stream can be the source of multiple projections
+- each projection has a [polymorphic](https://guides.rubyonrails.org/association_basics.html#polymorphic-associations) association to a record
+  - this record is your Active Record model that functions as an [aggregate root](https://www.baeldung.com/cs/aggregate-root-ddd#aggregates-and-aggregate-roots)
+  - it can update its own state and the state of its children by projecting events
+- an async event handler is automatically [subscribed](https://railseventstore.org/docs/core-concepts/subscribe) to all events that you project using the `on` method
+  - when an event of each type occurs, the projections subscribed to all streams in which that event is linked are notified
+  - unseen events are then read, applied and the record is saved
+- [optimistic locking](https://api.rubyonrails.org/classes/ActiveRecord/Locking/Optimistic.html) is used to control concurrent updates to the projection/record
+
+```mermaid
+---
+title: Records and Projections
+---
+classDiagram
+  namespace ActiveRecordProjection{
+	  class Projection{
+	    String: stream
+	    Integer: lock_version
+	    UUID: last_event_id
+	    Integer: record_id
+	    String: record_type
+	  }
+	 }
+    
+  class AggregateRoot{
+  }
+  
+  class Child{
+  }
+    
+  namespace ActiveRecord{
+    class Base{
+    }
+  }
+  
+  namespace RailsEventStore{
+    class Stream{
+    }
+  }
+  
+  AggregateRoot --|> Base
+  Child --|> Base
+  AggregateRoot *-- Child
+  Projection o-- AggregateRoot : record
+  Projection o-- Stream : stream
+```
+
+## Installation
+Add to your `Gemfile` and run `bundle`.
+```ruby
+gem 'active_record_projection'
+```
+
+Create a `active_record_projection_projections` table in your database:
+```bash
+bundle exec rails generate active_record_projection:install
+```
+
+## Adding an Active Record Projection
+To make your Active Record model a projection of an aggregate root:
+- include `ActiveRecordProjection`
+- define a `get_stream` method to allow a stream to be determined from the model data
+- define how to project each event using the [Aggregate Root syntax](https://railseventstore.org/docs/core-concepts/event-sourcing#define-aggregate-logic) (define `on` methods)
+
+```ruby
+class Order < ApplicationRecord
+  include ActiveRecordProjection
+
+  on OrderSubmitted.event_type do |event|
+    self.state = :submitted
+    self.delivery_date = event.data.fetch(:delivery_date)
+  end
+
+  on OrderExpired.event_type do |_event|
+    self.state = :expired
+  end
+
+  private
+
+  def get_stream
+    "orders$#{uuid}"
+  end
+end
+```
+
+You need to add a `on` method for each event type in a stream, even if you don't need it in order to project.

data/lib/active_record_projection/event_handlers/update_subscribed_projections.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+# don't require this file, RailsEventStore::AsyncHandler requires rails to be configured first
+
+require 'active_record_projection/jobs/update_projection'
+require 'active_record_projection/models/projection'
+
+module ActiveRecordProjection
+  module EventHandlers
+    class UpdateSubscribedProjections < ActiveJob::Base
+      prepend RailsEventStore::AsyncHandler
+
+      def perform(event)
+        streams = Rails.configuration.event_store.streams_of(event.event_id).map(&:name)
+        Models::Projection.where(stream: streams).pluck(:id).each do |id|
+          Jobs::UpdateProjection.perform_later(id:)
+        end
+      end
+    end
+  end
+end

data/lib/active_record_projection/event_handlers.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require 'active_record_projection/event_handlers/update_subscribed_projections'

data/lib/active_record_projection/jobs/update_projection.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+require 'active_record_projection/models/projection'
+
+module ActiveRecordProjection
+  module Jobs
+    class UpdateProjection < ActiveJob::Base
+      def perform(id:)
+        Models::Projection.find(id).update_projection!
+      end
+    end
+  end
+end

data/lib/active_record_projection/mixin.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+require 'active_record_projection/models/projection'
+require 'active_record_projection/projected_event_registry'
+
+module ActiveRecordProjection
+  module Mixin
+    extend ActiveSupport::Concern
+
+    included do
+      include AggregateRoot
+
+      has_one :projection, class_name: 'ActiveRecordProjection::Models::Projection', as: :record
+
+      delegate :last_event_id, :last_event_id=, :stream, to: :projection, allow_nil: true
+      after_initialize :add_projection, :initialize_transient
+
+      def self.on(*event_klasses, &)
+        ProjectedEventRegistry.register(event_klasses)
+        super
+      end
+    end
+
+    # the update needs to happen from this end to ensure that
+    # the correct projection is saved - the one updated
+    # as unseen events are applied
+    def update_projection!
+      apply_unseen
+
+      ActiveRecord::Base.transaction do
+        save!
+        projection.save!
+      end
+    end
+
+    private
+
+    def apply_unseen
+      query = Rails.configuration.event_store.read.stream(stream)
+      query = query.from(last_event_id) if last_event_id
+      query.reduce do |_, ev|
+        apply(ev)
+        self.last_event_id = ev.event_id
+      end
+    end
+
+    def add_projection
+      self.projection ||= Models::Projection.new(
+        record: self,
+        stream: get_stream
+      )
+    end
+
+    def initialize_transient
+      # this sets the variables at https://github.com/RailsEventStore/rails_event_store/blob/c2df01c4ac5d974e127b95b8d9eea21b7bebbad0/aggregate_root/lib/aggregate_root.rb#L35
+      # #new is not called when an AR model is loaded
+      # there must be a better way to use the module directly instead to avoid repeating
+      instance_variable_set(:@version, -1)
+      instance_variable_set(:@unpublished_events, [])
+    end
+  end
+end

data/lib/active_record_projection/models/projection.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+require 'active_record'
+
+module ActiveRecordProjection
+  module Models
+    class Projection < ActiveRecord::Base
+      delegate :update_projection!, to: :record
+
+      self.table_name = :active_record_projection_projections
+
+      belongs_to :record, polymorphic: true
+    end
+  end
+end

data/lib/active_record_projection/projected_event_registry.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module ActiveRecordProjection
+  class ProjectedEventRegistry
+    class_attribute :event_types, default: Set.new
+    class_attribute :unsubscribe_handler
+
+    def self.register(event_types)
+      self.event_types.merge(event_types)
+      unsubscribe_handler&.call
+      self.unsubscribe_handler = Rails.configuration.event_store.subscribe(
+        EventHandlers::UpdateSubscribedProjections,
+        to: self.event_types
+      )
+    end
+
+    private :event_types, :event_types=, :unsubscribe_handler, :unsubscribe_handler=
+  end
+end

data/lib/active_record_projection/railtie.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+require 'rails/railtie'
+
+module ActiveRecordProjection
+  class Railtie < ::Rails::Railtie
+    config.after_initialize do
+      # the prepend RailsEventStore::AsyncHandler in the handlers
+      # requires that rails event store has been configured first
+      require 'active_record_projection/event_handlers'
+    end
+  end
+end

data/lib/active_record_projection/version.rb

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

data/lib/active_record_projection.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+require 'active_record_projection/mixin'
+require 'active_record_projection/railtie'
+
+module ActiveRecordProjection
+  def self.included(clazz)
+    clazz.include(Mixin)
+  end
+end

data/lib/generators/active_record_projection/install/USAGE

@@ -0,0 +1,8 @@
+Description:
+  Generates a migration to add the projections table including indexes.
+
+Examples:
+  rails generate active_record_projection:install
+
+  This will create:
+    db/migrate/[TIMESTAMP]_create_active_record_projection_projections.rb

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

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require 'rails/generators/active_record'
+require 'rails/generators/active_record/migration'
+
+module ActiveRecordProjection
+  class InstallGenerator < Rails::Generators::Base
+    include ::Rails::Generators::Migration
+
+    source_root File.expand_path('templates', __dir__)
+    argument :migration_name, type: :string, default: 'create_active_record_projection_projections'
+
+    def create_migration_file
+      migration_template 'migration.rb.erb', "db/migrate/#{migration_name}.rb"
+    end
+
+    def self.next_migration_number(dirname)
+      ActiveRecord::Generators::Base.next_migration_number(dirname)
+    end
+  end
+end

data/lib/generators/active_record_projection/install/templates/migration.rb.erb

@@ -0,0 +1,15 @@
+class <%= migration_name.camelize %> < ActiveRecord::Migration[<%= Rails::VERSION::MAJOR %>.<%= Rails::VERSION::MINOR %>]
+  def change
+    create_table :active_record_projection_projections, id: :uuid do |t|
+      t.string :stream, null: false
+      t.integer :lock_version, null: false, default: 0
+      t.uuid :last_event_id, null: true
+      t.references :record, polymorphic: true
+
+      t.timestamps
+    end
+
+    add_index :active_record_projection_projections, [:record_id, :record_type]
+    add_index :active_record_projection_projections, [:stream]
+  end
+end

metadata

@@ -0,0 +1,127 @@
+--- !ruby/object:Gem::Specification
+name: active_record_projection
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+platform: ruby
+authors:
+- Brent Snook
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activerecord
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: aggregate_root
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rails_event_store
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: Builds Rails Event Store AggregateRoot
+email: brent@fuglylogic.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- lib/active_record_projection.rb
+- lib/active_record_projection/event_handlers.rb
+- lib/active_record_projection/event_handlers/update_subscribed_projections.rb
+- lib/active_record_projection/jobs/update_projection.rb
+- lib/active_record_projection/mixin.rb
+- lib/active_record_projection/models/projection.rb
+- lib/active_record_projection/projected_event_registry.rb
+- lib/active_record_projection/railtie.rb
+- lib/active_record_projection/version.rb
+- lib/generators/active_record_projection/install/USAGE
+- lib/generators/active_record_projection/install/install_generator.rb
+- lib/generators/active_record_projection/install/templates/migration.rb.erb
+homepage: https://github.com/brentsnook/active_record_projection
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/brentsnook/active_record_projection
+  bug_tracker_uri: https://github.com/brentsnook/active_record_projection/issues
+  changelog_uri: https://github.com/brentsnook/active_record_projection/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.1'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.1'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: Persistent, automatically updated ActiveRecord projections for Rails Event
+  Store
+test_files: []