event_sourced_record 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 092ed18da567347e5ac8f364e1d0f462f53e017d
+  data.tar.gz: ee8bd1282829f2b7f4f0f67a52415ef5d2d2b433
+SHA512:
+  metadata.gz: 5453d5b029fc488d6ac88d910b5c200bc9fe435b30616256c1058aa7dc686024c263ec8f8b66bf3db3427031d2d105d288760bbad91005efdc32096429ac1a68
+  data.tar.gz: c8a38090c8720b7fd0d5476ccd56dec501bebe5503077eafb63da0a7c91834a5af9d4d7911d73f10228619cff5c531f43ab8f9ff00f9efb24ad060ef8fdbd8e7

data/.gitignore

@@ -0,0 +1,25 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp
+*.bundle
+*.so
+*.o
+*.a
+mkmf.log
+.ruby-version
+gemfiles/*.gemfile
+gemfiles/*.gemfile.lock

data/Appraisals

@@ -0,0 +1,8 @@
+appraise "rails-4-0" do
+  gem "rails", "4.0.13"
+end
+
+appraise "rails-4-2" do
+  gem "rails", "4.2.0"
+end
+

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in event_sourced_record.gemspec
+gemspec

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2014 Francis Hwang
+
+MIT License
+
+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,131 @@
+# Event Sourced Record
+
+Event Sourced Record offers an idiomatic way to use the Event Sourcing pattern in Rails code.
+
+With Event Sourcing, every change to the state of an object is recorded as an immutable event in a replayable sequence.  The result is decoupled code that simplifies state debugging and retrospective reporting.
+
+For more, see Martin Fowler's writeup of the pattern: http://martinfowler.com/eaaDev/EventSourcing.html
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'event_sourced_record'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install event_sourced_record
+    
+Event Sourced Record uses observers, so you'll need to add them to your Gemfile:
+
+    gem 'rails-observers'
+    
+Note that only Rails 4 is supported as of this writing.  Rails 3 support is coming soon.
+
+## Usage
+
+Generate the required classes with `rails generate event_sourced_record`:
+
+    rails generate event_sourced_record Subscription \
+          user_id:integer bottles_per_shipment:integer \
+          bottles_left:integer
+
+The argument list is the same as with `rails generate model`.  This will generate the event model, the projection, the calculator, and the observer.
+
+### Event model
+
+The event model is an ActiveRecord model but it can act significantly different based on what type of event it is.  Use `event_type` to configure these types:
+
+    class SubscriptionEvent < ActiveRecord::Base
+      include EventSourcedRecord::Event
+
+      event_type :creation do
+        attributes :bottles_per_shipment, :bottles_purchased, :user_id
+
+        validates :bottles_per_shipment, presence: true, numericality: true
+        validates :bottles_purchased, presence: true, numericality: true
+        validates :user_id, presence: true
+      end
+
+      event_type :change_settings do
+        attributes :bottles_per_shipment
+ 
+        validates :bottles_per_shipment, numericality: true
+      end
+    end
+    
+The easiest way to create these records is with the scopes that are automatically generated by `event_type`:
+
+    SubscriptionEvent.creation.create!(
+      bottles_per_shipment: 1, bottles_purchased: 6, user_id: current_user.id
+    )
+    
+## Projection
+
+The projection is the ActiveRecord model that is generated deterministically with the data in the timestamped events combined with the logic in the calculator.  Projections shouldn't have any code for modifying themselves, as that will be done externally.  Accordingly, projections end up being fairly small classes:
+
+    class Subscription < ActiveRecord::Base
+      has_many :subscription_events
+
+      validates :uuid, uniqueness: true
+    end
+    
+(`uuid` is core to Event Sourced Model, so please don't remove its validations.)
+
+## Calculator
+
+The calculator is a service class that idempotently calculates the state of the projection by running one method for each event, in order.  Name the methods `advance_[event_type]`.
+
+    class SubscriptionCalculator < EventSourcedRecord::Calculator
+      events :subscription_events
+
+      def advance_creation(event)
+        @subscription.user_id = event.user_id
+        @subscription.bottles_per_shipment = event.bottles_per_shipment
+        @subscription.bottles_left = event.bottles_purchased
+      end
+
+      def advance_change_settings(event)
+        @subscription.bottles_per_shipment = event.bottles_per_shipment
+      end
+    end
+
+Calculators can also include other associated models, which can come in handy (as long as those models don't change significantly after creation).  Add that class to `events` and name the advance method `advance_[underscored class name]`:
+
+    class SubscriptionCalculator < EventSourcedRecord::Calculator
+      events :subscription_events, :shipments
+
+      def advance_shipment(shipment)
+        @subscription.bottles_left -= shipment.num_bottles
+      end
+    end
+    
+## Observer
+
+The observer simply tracks creations of events related to the projection and runs the calculator every time.  You may never have to modify what the generator creates for you:
+
+    class SubscriptionEventObserver < ActiveRecord::Observer
+      observe :subscription_event
+
+      def after_create(event)
+        SubscriptionCalculator.new(event).run.save!
+      end
+    end
+    
+If you use other models as events, simply add them to the `observe` method:
+
+    class SubscriptionEventObserver < ActiveRecord::Observer
+      observe :subscription_event, :shipment
+
+## Contributing
+
+1. Fork it ( https://github.com/[my-github-username]/event_sourced_record/fork )
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create a new Pull Request
+

data/Rakefile

@@ -0,0 +1,10 @@
+require "bundler/gem_tasks"
+require 'rake/testtask'
+
+Rake::TestTask.new do |t|
+  t.libs << "test"
+  t.test_files = FileList['test/**/*_test.rb']
+  t.verbose = true
+end
+
+task default: [:test]

data/event_sourced_record.gemspec

@@ -0,0 +1,37 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'event_sourced_record/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "event_sourced_record"
+  spec.version       = EventSourcedRecord::VERSION
+  spec.authors       = ["Francis Hwang"]
+  spec.email         = ["sera@fhwang.net"]
+  spec.summary       = %q{Event Sourcing with ActiveRecord.}
+  spec.description   = %q{Event Sourcing with ActiveRecord.}
+  spec.homepage      = ""
+  spec.license       = "MIT"
+
+  spec.files         = `git ls-files -z`.split("\x0")
+  spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
+  spec.require_paths = ["lib"]
+
+  spec.post_install_message = <<-MESSAGE
+Thanks for installing!
+
+EventSourcedRecord uses Rails observers. If you are using Rails 4.0 or greater, add `rails-observers` to your Gemfile.
+  MESSAGE
+
+  spec.add_dependency 'activemodel'
+
+  spec.add_development_dependency "bundler", "~> 1.6"
+  spec.add_development_dependency "rake"
+  spec.add_development_dependency 'activerecord'
+  spec.add_development_dependency 'appraisal'
+  spec.add_development_dependency 'mocha'
+  spec.add_development_dependency 'railties'
+  spec.add_development_dependency 'sqlite3'
+  spec.add_development_dependency 'pry'
+end

data/lib/event_sourced_record/calculator.rb

@@ -0,0 +1,101 @@
+class EventSourcedRecord::Calculator
+  def self.events(*event_symbols)
+    @@event_symbols = event_symbols
+  end
+
+  def self.event_classes
+    @@event_symbols.map { |sym| 
+      Module.const_get(sym.to_s.singularize.camelize)
+    }
+  end
+
+  def initialize(lookup)
+    @lookup = lookup
+  end
+
+  def run(options = {})
+    instance_variable_set(projection_variable_name, find_or_build_record)
+    sorted_events(options[:last_event_time]).each do |event|
+      advance_event(event)
+    end
+    instance_variable_get projection_variable_name
+  end
+
+  private
+
+  def advance_event(event)
+    if event.respond_to?(:event_type)
+      method = "advance_#{event.event_type}"
+    else
+      method = "advance_#{event.class.name.underscore}"
+    end
+    self.send(method, event)
+  end
+
+  def event_class
+    Module.const_get(projection_class_name + 'Event')
+  end
+
+  def find_or_build_record
+    case @lookup
+    when Integer
+      projection_class.where(id: @lookup).first
+    when projection_class
+      projection_class.where(id: @lookup.id).first
+    when *self.class.event_classes
+      find_or_build_record_by_event_instance(@lookup)
+    else
+      find_or_build_record_by_uuid(@lookup)
+    end
+  end
+
+  def find_or_build_record_by_event_instance(event)
+    if event.respond_to?(uuid_field)
+      find_or_build_record_by_uuid(event.send(uuid_field))
+    else
+      conditions = {id: event.send(projection_name + '_id')}
+      projection_class.where(conditions).first
+    end
+  end
+
+  def find_or_build_record_by_uuid(uuid)
+    projection_class.where(uuid: uuid).first || projection_class.new(uuid: uuid)
+  end
+
+  def projection_class
+    Module.const_get(projection_class_name)
+  end
+
+  def projection_class_name
+    self.class.name.gsub(/Calculator$/, '')
+  end
+
+  def projection_name
+    projection_class_name.underscore
+  end
+
+  def projection_variable_name
+    "@#{projection_name}".to_sym
+  end
+
+  def sorted_events(last_event_time)
+    projection = instance_variable_get projection_variable_name
+    self.class.event_classes.map { |event_class|
+      conditions = nil
+      if event_class.column_names.include?(uuid_field)
+        conditions = {uuid_field => projection.uuid}
+      else
+        conditions = {projection_name + '_id' => projection.id} if projection
+      end
+      conditions ? event_class.where(conditions).to_a : []
+    }.flatten.sort_by(&:created_at).reject { |evt|
+      if last_event_time
+        evt.created_at > last_event_time
+      end
+    }
+  end
+
+  def uuid_field
+    projection_name + '_uuid'
+  end
+end

data/lib/event_sourced_record/event/event_type_config.rb

@@ -0,0 +1,30 @@
+require 'active_model'
+
+class EventSourcedRecord::Event::EventTypeConfig
+  include ::ActiveModel::Validations::ClassMethods
+
+  attr_reader :_validators
+
+  def initialize
+    @_validators = Hash.new { |h,k| h[k] = [] }
+  end
+
+  def attributes(*attrs)
+    attrs.present? ? @attributes = attrs : @attributes
+  end
+
+  def const_get(sym_or_str, inherit=true)
+    ActiveModel::Validations.const_get(sym_or_str, inherit)
+  end
+
+  # Don't do anything; the interesting work has already been done in
+  # `validate_with` adding validators to @_validators
+  def validate(*args, &block)
+  end
+
+  def validate_record(record)
+    _validators.values.flatten.each do |validator|
+      validator.validate(record)
+    end
+  end
+end

data/lib/event_sourced_record/event.rb

@@ -0,0 +1,94 @@
+module EventSourcedRecord::Event
+  def self.included(model)
+    model.cattr_accessor :_event_type_configs
+    model.extend ClassMethods
+    model.after_initialize :ensure_data
+    model.after_initialize :ensure_projection_uuid
+    model.after_initialize :lock_event_type
+    model.validates :event_type, presence: true
+    model.validate :validate_corrent_event_type
+    model.validate :validate_by_event_type
+    model.serialize :data
+  end
+
+  def event_type
+    attributes["event_type"]
+  end
+
+  def event_type=(value)
+    if @event_type_locked
+      raise EventTypeImmutableError, "Event types can't be changed"
+    else
+      write_attribute(:event_type, value)
+    end
+  end
+
+  private
+
+  def ensure_data
+    self.data ||= {}
+  end
+
+  def ensure_projection_uuid
+    unless self.send(projection_uuid_name)
+      self.send("#{projection_uuid_name}=", SecureRandom.uuid)
+    end
+  end
+
+  def event_type_config
+    self.class.event_type_config(event_type)
+  end
+
+  def lock_event_type
+    @event_type_locked = true
+  end
+
+  def method_missing(meth, *args, &block)
+    if event_type_config && event_type_config.attributes.include?(meth)
+      ensure_data
+      self.data[meth.to_s]
+    elsif event_type_config && event_type_config.attributes.any? { |a| "#{a}=".to_sym == meth }
+      ensure_data
+      attr = meth.to_s.gsub(/=$/, '')
+      self.data[attr] = args.first
+    else
+      super
+    end
+  end
+
+  def projection_uuid_name
+    self.class.name.underscore.gsub(/_event$/, '') + '_uuid'
+  end
+
+  def validate_corrent_event_type
+    unless self.class.event_types.include?(event_type.to_s)
+      errors.add(:event_type, "is not a valid event type")
+    end
+  end
+
+  def validate_by_event_type
+    event_type_config.validate_record(self) if event_type_config
+  end
+
+  module ClassMethods
+    def event_type(event_type, &block)
+      scope event_type, -> { where(event_type: event_type) }
+      self._event_type_configs ||= HashWithIndifferentAccess.new
+      config = EventTypeConfig.new
+      self._event_type_configs[event_type] = config
+      config.instance_eval(&block)
+    end
+
+    def event_type_config(event_type)
+      self._event_type_configs[event_type]
+    end
+
+    def event_types
+      self._event_type_configs.keys
+    end
+  end
+
+  class EventTypeImmutableError < StandardError; end
+end
+
+require 'event_sourced_record/event/event_type_config'

data/lib/event_sourced_record/version.rb

@@ -0,0 +1,3 @@
+module EventSourcedRecord
+  VERSION = "0.0.1"
+end

data/lib/event_sourced_record.rb

@@ -0,0 +1,7 @@
+module EventSourcedRecord
+  # Your code goes here...
+end
+
+require "event_sourced_record/calculator"
+require "event_sourced_record/event"
+require "event_sourced_record/version"

data/lib/generators/event_sourced_record/USAGE

@@ -0,0 +1,8 @@
+Description:
+    Explain the generator
+
+Example:
+    rails generate event_sourced_record Thing
+
+    This will create:
+        what/will/it/create

data/lib/generators/event_sourced_record/calculator_generator.rb

@@ -0,0 +1,19 @@
+class EventSourcedRecord::CalculatorGenerator < Rails::Generators::NamedBase
+  source_root File.expand_path('../templates', __FILE__)
+  argument :attributes, 
+    :type => :array, :default => []
+
+  def create_calculator_file
+    template(
+      'calculator.rb', File.join('app/services', class_path, "#{file_name}.rb")
+    )
+  end
+
+  hook_for :test_framework, as: :service
+  
+  private
+
+  def event_name
+    file_name.gsub(/_calculator$/, '') + '_event'
+  end
+end

data/lib/generators/event_sourced_record/event_generator.rb

@@ -0,0 +1,40 @@
+class EventSourcedRecord::EventGenerator < Rails::Generators::NamedBase
+  source_root File.expand_path('../templates', __FILE__)
+  argument :attributes, 
+    :type => :array, :default => []
+
+  def create_migration_file
+    attributes_str = attributes.map { |attr|
+      attr_banner = attr.name
+      attr_banner << ":#{attr.type}" if attr.type
+      attr_banner << ':index' if attr.has_index?
+      attr_banner
+    }.join(' ')
+    generate(
+      "migration", "create_#{event_table_name} #{attributes_str}"
+    )
+  end
+
+  def create_model_file
+    template(
+      'event_model.rb', 
+      File.join('app/models', class_path, "#{event_file_name}.rb")
+    )
+  end
+
+  hook_for :test_framework, as: :model
+
+  private
+
+  def event_class_name
+    class_name
+  end
+
+  def event_file_name
+    file_name
+  end
+
+  def event_table_name
+    table_name
+  end
+end

data/lib/generators/event_sourced_record/event_sourced_record_generator.rb

@@ -0,0 +1,41 @@
+class EventSourcedRecord::EventSourcedRecordGenerator < Rails::Generators::NamedBase
+  source_root File.expand_path('../templates', __FILE__)
+  argument :attributes, 
+    :type => :array, :default => [], 
+    :banner => "field[:type][:index] field[:type][:index]"
+
+  check_class_collision
+
+  def create_calculator_class
+    generate "event_sourced_record:calculator", "#{file_name}_calculator"
+  end
+
+  def create_event
+    arguments = [
+      "#{file_name}_uuid:string:index", "event_type:string", 
+      "data:text", "created_at:datetime"
+    ].join(' ')
+    generate "event_sourced_record:event", "#{file_name}_event #{arguments}"
+  end
+
+  def create_observer
+    generate "event_sourced_record:observer", "#{file_name}_event_observer"
+  end
+
+  def create_projection
+    attr_strings = attributes.map { |attr|
+      attr_string = attr.name
+      attr_string << ":#{attr.type}" if attr.type
+      attr_string << ':index' if attr.has_index?
+      attr_string
+    }
+    projection_attributes = attr_strings.join(' ')
+    generate "event_sourced_record:projection", "#{file_name} #{projection_attributes}"
+  end
+
+  protected
+
+  def calculator_class_name
+    class_name + 'Calculator'
+  end
+end

data/lib/generators/event_sourced_record/observer_generator.rb

@@ -0,0 +1,34 @@
+class EventSourcedRecord::ObserverGenerator < Rails::Generators::NamedBase
+  source_root File.expand_path('../templates', __FILE__)
+
+  def create_observer_file
+    template(
+      'observer.rb', 
+      File.join('app/observers', class_path, "#{file_name}.rb")
+    )
+  end
+
+  def create_application_observer_hook
+    application do
+      "config.active_record.observers = :#{file_name}"
+    end
+  end
+
+  private
+
+  def calculator_class_name
+    (projection_name + '_calculator').camelize
+  end
+
+  def event_name
+    projection_name + '_event'
+  end
+
+  def event_uuid_field
+    projection_name + '_uuid'
+  end
+
+  def projection_name
+    file_name.gsub(/_event_observer$/, '')
+  end
+end

data/lib/generators/event_sourced_record/projection_generator.rb

@@ -0,0 +1,50 @@
+class EventSourcedRecord::ProjectionGenerator < Rails::Generators::NamedBase
+  source_root File.expand_path('../templates', __FILE__)
+  argument :attributes, 
+    :type => :array, :default => []
+
+  def create_migration_file
+    generate(
+      "migration", "create_#{projection_table_name} #{migration_attributes}"
+    )
+  end
+
+  def create_model_file
+    template(
+      'projection_model.rb', 
+      File.join('app/models', class_path, "#{projection_file_name}.rb")
+    )
+  end
+
+  hook_for :test_framework, as: :model
+
+  private
+
+  def migration_attributes
+    attr_strings = attributes.map { |attr|
+      attr_string = attr.name
+      attr_string << ":#{attr.type}" if attr.type
+      attr_string << ':index' if attr.has_index?
+      attr_string
+    }
+    attr_strings << "uuid:string:uniq"
+    attr_strings.join(' ')
+  end
+
+
+  def projection_class_name
+    class_name
+  end
+
+  def projection_file_name
+    file_name
+  end
+
+  def projection_parent_class_name
+    "ActiveRecord::Base"
+  end
+
+  def projection_table_name
+    table_name
+  end
+end