ruby_cqrs 0.2.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: a0bff53f5c549da4478fd01b6c2cbfcf37f2c113
+  data.tar.gz: 6b699a6579e93f27d6af1f0305a90f941bddf1d9
+SHA512:
+  metadata.gz: 54d999384f32a945152bf47b482562212a660bb824f0dac7c0495b5d7461adac974919931ec37ad73a8d18a01e619f9097318e23a5898336ef598c119aebd8b6
+  data.tar.gz: 885545a8f2118cee2aa1957967b011225a6360607bd5669307c260d06baf05c7eccbc640fb288521ec39f39df7cba7fc0b01fd993f2bca3304caa3029ee4fb4a

data/License.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2015 Raven Chen
+
+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,33 @@
+[![Build Status](https://travis-ci.org/iravench/ruby_cqrs.svg?branch=master)](https://travis-ci.org/iravench/ruby_cqrs) [![Code Climate](https://codeclimate.com/github/iravench/ruby_cqrs/badges/gpa.svg)](https://codeclimate.com/github/iravench/ruby_cqrs) [![Test Coverage](https://codeclimate.com/github/iravench/ruby_cqrs/badges/coverage.svg)](https://codeclimate.com/github/iravench/ruby_cqrs)
+
+# RubyCqrs
+
+A Ruby implementation of CQRS, using event sourcing.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'ruby_cqrs'
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install ruby_cqrs
+
+## Usage
+refer to bellow spec for how to use this gem in your code
+https://github.com/iravench/ruby_cqrs/blob/master/spec/feature/basic_usage_spec.rb
+
+## Contributing
+
+1. Fork it ( https://github.com/iravench/ruby_cqrs/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/lib/ruby_cqrs/data/event_store.rb

@@ -0,0 +1,13 @@
+module RubyCqrs
+  module Data
+    module EventStore
+      def load_by guid, command_context
+        raise NotImplementedError
+      end
+
+      def save changes, command_context
+        raise NotImplementedError
+      end
+    end
+  end
+end

data/lib/ruby_cqrs/data/in_memory_event_store.rb

@@ -0,0 +1,70 @@
+module RubyCqrs
+  module Data
+    class InMemoryEventStore
+      include EventStore
+
+      def initialize
+        @aggregate_store = {}
+        @event_store = {}
+        @snapshot_store = {}
+      end
+
+      def load_by guid, command_context
+        key = guid.to_sym
+        state = { :aggregate_id => guid,
+                  :aggregate_type => @aggregate_store[key][:type] }
+
+        if @snapshot_store.has_key? key
+          extract_snapshot_into key, state
+        else
+          state[:events] = @event_store[key][:events]
+        end
+
+        state
+      end
+
+      def save changes, command_context
+        changes.each do |change|
+          key = change[:aggregate_id].to_sym
+          verify_state key, change
+        end
+        changes.each do |change|
+          key = change[:aggregate_id].to_sym
+          create_state key, change
+          update_state key, change
+        end
+        nil
+      end
+
+    private
+      def create_state key, change
+        unless @aggregate_store.has_key? key
+          @aggregate_store[key] = { :type => change[:aggregate_type], :version => 0 }
+          @event_store[key] = { :events => [] }
+        end
+        unless @snapshot_store.has_key? key or change[:snapshot].nil?
+          @snapshot_store[key] = {}
+        end
+      end
+
+      def update_state key, change
+        @aggregate_store[key][:version] = change[:expecting_version]
+        change[:events].each { |event| @event_store[key][:events] << event }
+        @snapshot_store[key] = change[:snapshot] unless change[:snapshot].nil?
+      end
+
+      def extract_snapshot_into key, state
+        snapshot_version = @snapshot_store[key][:version]
+        state[:events] = @event_store[key][:events]\
+          .select { |event_record| event_record[:version] > snapshot_version }
+        state[:snapshot] = @snapshot_store[key]
+      end
+
+      def verify_state key, change
+        raise AggregateConcurrencyError.new("on aggregate #{key}")\
+          if @aggregate_store.has_key? key\
+            and @aggregate_store[key][:version] != change[:expecting_source_version]
+      end
+    end
+  end
+end

data/lib/ruby_cqrs/data/serialization.rb

@@ -0,0 +1,30 @@
+require 'active_support/inflector'
+require 'beefcake'
+
+module RubyCqrs
+  class ObjectNotEncodableError < Error; end
+  class ObjectNotDecodableError < Error; end
+
+  module Data
+    module Encodable
+
+      def try_encode
+        return self.encode.to_s if self.is_a? Beefcake::Message
+        raise ObjectNotEncodableError
+      end
+    end
+  end
+end
+
+module RubyCqrs
+  module Data
+    module Decodable
+
+      def try_decode type_str, data
+        obj_type = type_str.constantize
+        raise ObjectNotDecodableError unless obj_type.include? Beefcake::Message
+        obj_type.decode data
+      end
+    end
+  end
+end

data/lib/ruby_cqrs/domain/aggregate.rb

@@ -0,0 +1,107 @@
+require 'active_support/inflector'
+
+module RubyCqrs
+  module Domain
+    module Aggregate
+      attr_reader :aggregate_id, :version
+
+      def initialize
+        @aggregate_id = Guid.create
+        @version = 0
+        @source_version = 0
+        @event_handler_cache = {}
+        @pending_events = []
+        super
+      end
+
+      def is_version_conflicted? client_side_version
+        client_side_version != @source_version
+      end
+
+    private
+
+      def load_from state
+        sorted_events = state[:events].sort { |x, y| x.version <=> y.version }
+        @aggregate_id = state[:aggregate_id]
+        try_load_snapshot_from state
+        sorted_events.each do |event|
+          apply(event)
+          @source_version += 1
+        end
+      end
+
+      def try_load_snapshot_from state
+        if state.has_key? :snapshot and self.is_a? Snapshotable
+          self.send :apply_snapshot, state[:snapshot][:state]
+          @version = state[:snapshot][:version]
+          @source_version = state[:snapshot][:version]
+          self.send(:reset_countdown, state[:events].size)
+        end
+      end
+
+      def get_changes
+        return nil unless @pending_events.size > 0
+        changes = {
+          :events => @pending_events,
+          :aggregate_id => @aggregate_id,
+          :aggregate_type => self.class.name,
+          :expecting_source_version => @source_version,
+          :expecting_version => @pending_events.max\
+          { |a, b| a.version <=> b.version }.version
+        }
+        try_extract_snapshot_into changes
+        changes
+      end
+
+      def try_extract_snapshot_into changes
+        snapshot_state = self.send :take_a_snapshot\
+          if self.is_a? Snapshotable and self.send(:should_take_a_snapshot?)
+        unless snapshot_state.nil?
+          raise NotADomainSnapshotError unless snapshot_state.is_a? Snapshot
+          changes[:snapshot] = { :state => snapshot_state,
+                                 :state_type => snapshot_state.class.name,
+                                 :version => @version }
+          self.send :set_snapshot_taken
+        end
+      end
+
+      def commit
+        @pending_events = []
+        @source_version = @version
+        if self.is_a? Snapshotable and self.send :should_reset_snapshot_countdown?
+          self.send(:reset_countdown, 0)
+        end
+      end
+
+      def raise_event(event)
+        raise NotADomainEventError unless event.is_a? Event
+        apply(event)
+        update_dispatch_detail_for(event)
+        @pending_events << event
+      end
+
+      def update_dispatch_detail_for(event)
+        event.instance_variable_set(:@aggregate_id, @aggregate_id)
+        event.instance_variable_set(:@version, @version)
+      end
+
+      def apply(event)
+        dispatch_handler_for(event)
+        self.send(:snapshot_countdown) if self.is_a? Snapshotable
+        @version += 1
+      end
+
+      def dispatch_handler_for(event)
+        target = retrieve_handler_for(event.class)
+        self.send(target, event)
+      end
+
+      def retrieve_handler_for(event_type)
+        @event_handler_cache[event_type] ||= begin
+          stripped_event_type_name = event_type.to_s.demodulize.underscore
+          "on_#{stripped_event_type_name}".to_sym
+        end
+      end
+    end
+  end
+end

data/lib/ruby_cqrs/domain/aggregate_repository.rb

@@ -0,0 +1,122 @@
+require 'active_support/inflector'
+require_relative '../guid'
+
+module RubyCqrs
+  class AggregateNotFound < Error; end
+  class AggregateConcurrencyError < Error; end
+  class AggregateInstanceDuplicatedError < Error; end
+
+  module Domain
+    class AggregateRepository
+      include RubyCqrs::Data::Decodable
+
+      def find_by aggregate_id
+        raise ArgumentError if aggregate_id.nil?
+        raise ArgumentError unless Guid.validate? aggregate_id
+
+        state = @event_store.load_by(aggregate_id, @command_context)
+        raise AggregateNotFound if (state.nil? or state[:aggregate_type].nil? or\
+                                    ((state[:events].nil? or state[:events].empty?) and state[:snapshot].nil?))
+
+        create_instance_from state
+      end
+
+      def save one_or_many_aggregate
+        raise ArgumentError if one_or_many_aggregate.nil?
+        return delegate_persistence_of [ one_or_many_aggregate ] if one_or_many_aggregate.is_a? Aggregate
+
+        raise ArgumentError unless one_or_many_aggregate.is_a? Enumerable and one_or_many_aggregate.size > 0
+        delegate_persistence_of one_or_many_aggregate
+      end
+
+    private
+      def initialize event_store, command_context
+        raise ArgumentError unless event_store.is_a? Data::EventStore
+        @event_store = event_store
+        @command_context = command_context
+      end
+
+      def create_instance_from state
+        try_decode_from state
+        instance = state[:aggregate_type].constantize.new
+        instance.send(:load_from, state)
+        instance
+      end
+
+      def delegate_persistence_of aggregates
+        verify_uniqueness_of aggregates
+
+        changes = prep_changes_for(aggregates)
+        if changes.size > 0
+          @event_store.save changes, @command_context
+          aggregates.each do |aggregate|
+            aggregate.send(:commit)
+          end
+        end
+
+        nil
+      end
+
+      def verify_uniqueness_of aggregates
+        uniq_array =  aggregates.uniq { |aggregate| aggregate.aggregate_id }
+        raise AggregateInstanceDuplicatedError unless uniq_array.size == aggregates.size
+      end
+
+      def prep_changes_for aggregates
+        to_return = []
+        aggregates.inject(to_return) do |product, aggregate|
+          raise ArgumentError unless aggregate.is_a? Aggregate
+          aggregate_change = aggregate.send(:get_changes)
+          next if aggregate_change.nil?
+          try_encode_from aggregate_change
+          product << aggregate_change
+        end
+        to_return
+      end
+
+      def try_decode_from state
+        state[:snapshot] = decode_snapshot_state_from state[:snapshot]\
+          if state.has_key? :snapshot
+
+        state[:events].map! { |event_record| decode_event_from event_record }\
+          if state[:events].size > 0
+      end
+
+      def decode_snapshot_state_from snapshot_record
+        snapshot_state = try_decode snapshot_record[:state_type], snapshot_record[:data]
+        { :state => snapshot_state, :version => snapshot_record[:version] }
+      end
+
+      def decode_event_from event_record
+        decoded_event = try_decode event_record[:event_type], event_record[:data]
+        decoded_event.instance_variable_set(:@aggregate_id, event_record[:aggregate_id])
+        decoded_event.instance_variable_set(:@version, event_record[:version])
+        decoded_event
+      end
+
+      def try_encode_from change
+        if change.has_key? :snapshot
+          encoded_snapshot = encode_data_from change[:snapshot][:state]
+          change[:snapshot] = { :state_type => change[:snapshot][:state_type],
+                                :version => change[:snapshot][:version],
+                                :data => encoded_snapshot }
+        end
+
+        if change[:events].size > 0
+          change[:events].map! { |event|
+            { :data => encode_data_from(event),
+              :aggregate_id => event.aggregate_id,
+              :event_type => event.class.name,
+              :version => event.version }
+          }
+        end
+      end
+
+      def encode_data_from obj
+        data = obj
+        data = data.try_encode if data.is_a? RubyCqrs::Data::Encodable
+        data
+      end
+    end
+  end
+end

data/lib/ruby_cqrs/domain/event.rb

@@ -0,0 +1,10 @@
+module RubyCqrs
+  class NotADomainEventError < Error; end
+
+  module Domain
+    module Event
+      include RubyCqrs::Data::Encodable
+      attr_reader :aggregate_id, :version
+    end
+  end
+end

data/lib/ruby_cqrs/domain/snapshot.rb

@@ -0,0 +1,9 @@
+module RubyCqrs
+  class NotADomainSnapshotError < Error; end
+
+  module Domain
+    module Snapshot
+      include RubyCqrs::Data::Encodable
+    end
+  end
+end

data/lib/ruby_cqrs/domain/snapshotable.rb

@@ -0,0 +1,48 @@
+module RubyCqrs
+  module Domain
+    module Snapshotable
+      def initialize
+        if self.class.const_defined? :SNAPSHOT_THRESHOLD
+          @snapshot_threshold = self.class.const_get(:SNAPSHOT_THRESHOLD)
+        else
+          @snapshot_threshold = 30
+        end
+        @snapshot_threshold = 30 if @snapshot_threshold <= 0
+        @countdown = @snapshot_threshold
+        @reset_snapshot_countdown_flag = false
+        super
+      end
+
+    private
+      def should_take_a_snapshot?
+        @countdown <= 0
+      end
+
+      def snapshot_countdown
+        @countdown -= 1
+      end
+
+      def reset_countdown loaded_event_count
+        @countdown = @snapshot_threshold - loaded_event_count
+        @reset_snapshot_countdown_flag = false
+      end
+
+      def should_reset_snapshot_countdown?
+        @reset_snapshot_countdown_flag
+      end
+
+      def set_snapshot_taken
+        @reset_snapshot_countdown_flag = true
+      end
+
+      # the including domain object should implement these two methods
+      def take_a_snapshot
+        raise NotImplementedError
+      end
+
+      def apply_snapshot snapshot_object
+        raise NotImplementedError
+      end
+    end
+  end
+end

data/lib/ruby_cqrs/error.rb

@@ -0,0 +1,3 @@
+module RubyCqrs
+  class Error < RuntimeError; end
+end

data/lib/ruby_cqrs/guid.rb

@@ -0,0 +1,13 @@
+require 'uuidtools'
+
+module RubyCqrs
+  class Guid
+    def self.create
+      UUIDTools::UUID.timestamp_create.to_s
+    end
+
+    def self.validate?(guid)
+      UUIDTools::UUID.parse(guid).valid?
+    end
+  end
+end

data/lib/ruby_cqrs/version.rb

@@ -0,0 +1,3 @@
+module RubyCqrs # :nodoc:
+  VERSION = '0.2.0'
+end

data/lib/ruby_cqrs.rb

@@ -0,0 +1,12 @@
+require('ruby_cqrs/error')
+require('ruby_cqrs/guid')
+
+require('ruby_cqrs/data/event_store')
+require('ruby_cqrs/data/serialization')
+require('ruby_cqrs/data/in_memory_event_store')
+
+require('ruby_cqrs/domain/event')
+require('ruby_cqrs/domain/snapshot')
+require('ruby_cqrs/domain/aggregate')
+require('ruby_cqrs/domain/snapshotable')
+require('ruby_cqrs/domain/aggregate_repository')

data/spec/feature/basic_usage_spec.rb

@@ -0,0 +1,177 @@
+require_relative('../spec_helper.rb')
+
+# define your domain object
+class Customer
+  # mark as a domain object
+  include RubyCqrs::Domain::Aggregate
+  # makr as snapshotable
+  # the default setting is when more 30 events are raised
+  # after the last snapshot is taken, a new snapshot is generated
+  # change the default by defining SNAPSHOT_THRESHOLD = 20(or other number)
+  include RubyCqrs::Domain::Snapshotable
+
+  attr_reader :name, :credit
+
+  # unfortunately, you should not try to define your own initialize method
+  # at the time being, it could potentially cause error when the aggregate
+  # repository try to load your domain object back.
+
+  # define your domain object's behaviors
+  def create_profile name, credit
+    # again, this is like your normal initialize method,
+    # it should get called only once...
+    raise RuntimeError.new('the profile has already been created') unless @name.nil?
+    raise AgumentError if name.nil?
+    raise AgumentError if credit < 100
+    # when business rules are met, raise corresponding event
+    raise_event CustomerCreated.new(:name => name, :credit => credit)
+  end
+
+  def order_product price
+    raise AgumentErrorr if price <= 0
+    raise AgumentError.new("#{@name}'s credit #{@credit} is not enough to pay for a product costs #{price}")\
+      if price > @credit
+    # when business rules are met, raise corresponding event
+    raise_event ProductOrdered.new(:cost => price)
+  end
+
+private
+  # when an event is raised or replayed,
+  # these methods will get called automatically,
+  # manage the domain object's internal state here
+  def on_customer_created customer_created
+    @name = customer_created.name
+    @credit = customer_created.credit
+  end
+
+  def on_product_ordered product_ordered
+    @credit -= product_ordered.cost
+  end
+
+  # when a domain object is marked as snapshotable,
+  # you must implement these two methods to record the object's vital state
+  # and apply the snapshot in order to restore your object's data respectively
+  def take_a_snapshot
+    CustomerSnapshot.new(:name => @name, :credit => @credit)
+  end
+
+  def apply_snapshot snapshot_object
+    @name = snapshot_object.name
+    @credit = snapshot_object.credit
+  end
+end
+
+# define a snapshot to keep all vital state of your domain object
+# the repository will use the latest snapshot it can find
+# and events happened after the snapshot has been taken
+# to recreate your domain object
+class CustomerSnapshot
+  include Beefcake::Message
+  include RubyCqrs::Domain::Snapshot
+
+  required :name,      :string, 1
+  required :credit,    :int32,  2
+end
+
+# defined the events your domain object will raise
+class CustomerCreated
+  include RubyCqrs::Domain::Event
+  include Beefcake::Message
+
+  required :name,      :string, 1
+  required :credit,    :int32,  2
+end
+
+class ProductOrdered
+  include RubyCqrs::Domain::Event
+  include Beefcake::Message
+
+  required :cost,       :int32,  1
+end
+
+# here goes the spec of how you can use the domain object
+describe 'Your awesome customer domain objects powered by ruby_cqrs' do
+  # a context related to the command, which is specific to your problem domain
+  # normally, when a command arrives, one or more domain objects are created or loaded
+  # in order to fulfill the command's request
+  let(:command_context) {}
+  # you should implement your own event_store in order to persist your aggregate state
+  # you should read about the InMemoryEventStore implementation
+  # and make sure your response with correct data format
+  let(:event_store) { RubyCqrs::Data::InMemoryEventStore.new }
+  # every time when a command arrives,
+  # an aggregate repository gets created with related command context and event_store implementation
+  let(:repository) { RubyCqrs::Domain::AggregateRepository.new event_store, command_context }
+
+  let(:lucy) do
+    instance = Customer.new
+    instance.create_profile('Lucy', 1000)
+    instance
+  end
+
+  it 'creates a new customer instance' do
+    expect(lucy.name).to eq('Lucy')
+    expect(lucy.credit).to eq(1000)
+
+    expect(lucy.version).to eq(1)
+  end
+
+  it 'operates a new customer instance' do
+    lucy.order_product 100
+
+    expect(lucy.name).to eq('Lucy')
+    expect(lucy.credit).to eq(900)
+
+    expect(lucy.version).to eq(2)
+  end
+
+  it 'saves a new customer instance' do
+    lucy.order_product 100
+    repository.save lucy
+
+    expect(lucy.name).to eq('Lucy')
+    expect(lucy.credit).to eq(900)
+    expect(lucy.version).to eq(2)
+  end
+
+  it 'finds an old customer instance by id' do
+    lucy.order_product 100
+    repository.save lucy
+    lucy_reload = repository.find_by lucy.aggregate_id
+
+    expect(lucy_reload.name).to eq('Lucy')
+    expect(lucy_reload.credit).to eq(900)
+    expect(lucy_reload.version).to eq(2)
+  end
+
+  it 'operates on an reloaded customer instance' do
+    lucy.order_product 100
+    repository.save lucy
+    lucy_reload = repository.find_by lucy.aggregate_id
+
+    lucy_reload.order_product 200
+
+    expect(lucy_reload.name).to eq('Lucy')
+    expect(lucy_reload.credit).to eq(700)
+    expect(lucy_reload.version).to eq(3)
+  end
+
+  it 'generates a customer snapshot when enough events get fired' do
+    (1..30).each { lucy.order_product(10) }
+    repository.save lucy
+
+    # well, you just have to trust a snapshot has been generated :)
+  end
+
+  it 'finds an old customer instance back from snapshot' do
+    (1..30).each { lucy.order_product(10) }
+    repository.save lucy
+    lucy_reload = repository.find_by lucy.aggregate_id
+
+    # again, it's been loaded from a snapshot ;)
+
+    expect(lucy_reload.name).to eq('Lucy')
+    expect(lucy_reload.credit).to eq(700)
+    expect(lucy_reload.version).to eq(31)
+  end
+end