replay 0.0.1 → 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 1c2e196bd8e54aa363a8ad762f41797aa99c989e
+  data.tar.gz: cda39f5a62f384de3ba509f291407a54035b007b
+SHA512:
+  metadata.gz: af511f51f8dbec4f12fc284bebf4232786081e6832089d1bd7209f7ab88b001e02a40bb85a7182acb562c19715c037c797c0e5be4d54b4bfd51228e9bb853c94
+  data.tar.gz: 25ff65cea036543f63088c7ff299acbd1128cbbfd70c74aa6fbfefa4fa4c9312a0b034ac687cecff2e4ef041c063aac18ec5956d897d9f2d63da3c71c8351a57

data/.rvmrc

@@ -1 +1 @@
-rvm use 1.9.2@replay
+rvm use 2.0.0@replay --create

data/Gemfile

@@ -3,8 +3,12 @@ source "http://rubygems.org"
 # Specify your gem's dependencies in replay.gemspec
 gemspec
 
+group :development do
+  gem 'guard'
+  gem 'guard-shell'
+end
+
 group :test do
-  gem "ruby-debug19", :platforms => :ruby_19
-  gem "minitest"
-  gem "mocha"
+  gem "proof", :git => 'https://github.com/Sans/proof.git'
+  gem 'byebug'
 end

data/Guardfile

@@ -0,0 +1,10 @@
+# A sample Guardfile
+# More info at https://github.com/guard/guard#readme
+
+# Add files and commands to this file, like the example:
+#   watch(%r{file/path}) { `command(s)` }
+#
+guard :shell, :all_on_start => false do
+  watch(/lib\/(.*).rb/) {|m| `ruby proofs/all.rb` }
+  watch(/proofs\/(.*).rb/) {|m| `ruby #{m[0]}`}
+end

data/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2014 Keith Gaddis
+
+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,153 @@
+#Replay
+Replay is a gem to support event sourcing data within domain boundaries. With event sourced data, the application stores data as a series of domain events, which are applied to the domain object in order to mutate state.
+
+###CQRS/ES 30 second intro
+[Command Query Responsibility Segregation](http://codebetter.com/gregyoung/2010/02/16/cqrs-task-based-uis-event-sourcing-agh/) (and [Fowler's explanation](http://martinfowler.com/bliki/CQRS.html) is a pattern popularized by Greg Young and Udi Dahan from within the sphere of Domain Driven Design. The general idea is that within domain models, objects are rarely good at both representing truth and being purposeful for queries and reporting, and therefore we should separate the responsibilities.  
+
+[Event Sourcing](http://martinfowler.com/eaaDev/EventSourcing.html) is a pattern that is not required by (but pairs extremely well with) CQRS. However, by embracing this pattern a system can adapt to new reporting and query requirements at any time with a great deal of flexibility, and the use of messaging/pub-sub along with events creates an easy path to breaking apart monolithic applications and separating domains.
+
+###A short example
+
+    class ReplayExample
+      include Replay::Publisher
+      
+	    #define events
+      events do
+        SomethingHappened(name: String, pid: Integer)
+        SomethingElseHappened(pid: Integer)
+        #....
+      end
+     
+      #applying events (changing state)
+      apply SomethingHappened do |event|
+        @name = event.name
+        @pid  = event.pid
+      end
+      
+      apply SomethingElseHappened do |event|
+        @state = :happened_again
+        @pid = nil if event.pid == @pid
+      end
+      
+      def do_something(pid = nil)
+        #the command validates inputs
+        #InvalidCommand is defined by the application
+        raise InvalidCommand.new("parameters were invalid") unless pid
+        
+        #publish events
+        publish SomethingHappened.new(:name = "foo", :pid => pid)
+
+        #publish with method syntax
+        publish SomethingElseHappened(pid: pid)
+      end
+    end
+
+There's a couple of things to note about the above example.  ReplayExample is a domain object. (Clearly this example is a bit contrived.) [Domain objects](http://martinfowler.com/eaaCatalog/domainModel.html) represent and encapsulate domain logic in its purest sense. No application code should make its way into a domain object, nor should concerns from another bounded context.
+
+Domain objects publish events in order to mutate state.  The events published by this domain object are defined within the `events` block; `ReplayExample::SomethingHappened` is a class defined there, which has two attributes `name` and `pid`, which are `String` and `Integer` respectively. Events may also be defined manually, like any other class. Because they're essentially value objects, with zero behavior, the shorthand form above is usually going to be easier.
+
+`ReplayExample` instances change state by applying events. These events are handled in the `apply` blocks in the above example (you see what I did there?) This part is, mostly, really simple. You probably did a lot of this state thing in your freshman programming class. More on that later.
+
+So if we've got the events defined, and we know what events change state in which ways, where do they come from? Commands, of course. The role of a command is to validate its inputs and publish the events if the command is valid. That's it. No changing state allowed there—seriously, none. Ever heard the term [snowflake server](http://martinfowler.com/bliki/SnowflakeServer.html)? Break the state rule and you're going to have snowflake instances and weird bugs.
+
+Commands are the art and science of CQRS. In the above example, I've implemented it as a method on the domain object (which is also called an aggregate root in the language of DDD.) Its just as frequently done as a class, e.g.
+
+    class ReplayExample::DoSomething
+       include Replay::Publisher
+
+       def initialize(name, pid=nil)
+          raise InvalidCommand.new unless pid
+          @name = name
+          @pid = pid
+       end
+       
+       def perform
+         #the publish the event, but don't raise an error if an application block can't be found
+         publish ReplayExample::SomethingHappened.new(name: @name, pid: @pid), false
+       end
+    end
+
+    ReplayExample::DoSomething.new("foo", 123).perform
+
+The above command class performs the same function, but has some advantages. In a Rails application, you can mix in ActiveModel::Validations to get ActiveRecord-style validators on it. You can also use Virtus (recommended) or ActiveModel to make it ActiveModel compliant and use it as a form object. This pattern is especially useful when you're dealing with non-domain services (e.g. credit card processors.) You can publish events from any model; there's nothing special about that (though its best if you don't do it without good reason, or you'll subvert one of the great advantages of DDD—separation of bounded contexts).
+
+##Digging deeper
+
+###The Repository
+The Repository is an application-defined object (replay will generate one for you) which will load your domain objects from storage. The repository's job is to find the event stream requested and apply the events from the event stream to a newly created object of the supplied type. Every application has at least one repository, and may have several.
+
+Use it like so:
+    
+    example = Repository.load(ReplayExample, some_guid)
+
+What you'll get back is a newly initialized instance of your object, with all events from the stream applied in sequence. By default, if it doesn't find any events for that stream identifier, it will raise an exception; you can change this behavior by supplying `:create => false` or `:create => true` to `load`. When false, the Repository will not attempt to create the instance. If true, and the object defines a `create` method that takes no parameters, the default implementation will call `create`. (Its standard practice for that method to publish a `Created` event.)
+
+Your application's repository will look something like this:
+
+    class Repository
+      include Replay::Repository
+
+      configure do |config|
+        config.store = :active_record
+        config.add_default_subscriber EventLogger
+      end
+    end
+
+You can also create a repository for your test environment (though for unit tests its typically unnecessary and for higher levels adding a subscriber will suffice. For example, in Cucumber or its analogues:
+
+    #features/env.rb
+    Repository.configuration.add_default_listener EventMonitor.new
+
+###Observers
+Replay provides a default message router for observers of events. 
+
+In your repository implementation, add :replay_router to the configuration's default subscribers:
+
+    class Repository
+      include Replay::Repository
+
+      configure do |config|
+        config.add_default_subscriber :replay_router
+      end
+    end
+
+In your application or domain services:
+
+    class MailService
+      include Replay::Observer
+
+      observe Model::EventHappened do |event|
+        #handle the event 
+      end
+    end
+
+It may be advantageous in some situations to create multiple routers:
+
+    class InternalRouter
+      include Replay::Router
+    end
+
+    class Repository
+      include Replay::Repository
+
+      configure do |config|
+        config.add_default_subscriber InternalRouter
+      end
+    end
+
+    class MailService
+      include Replay::Observer
+      router InternalRouter
+
+      #observations...
+    end
+
+##Additional gems
+
+[replay-rails](http://github.com/karmajunkie/replay-rails) provides a very basic ActiveRecord-based event store. Its a good template for building your own event store and light duties in an application in which aggregates don't receive hundreds or thousands of events. 
+
+
+##TODO
+* Implement snapshots for efficient load from repository
+* Better documentation
+* Build a demonstration app

data/Rakefile

@@ -1 +1,16 @@
 require "bundler/gem_tasks"
+require 'rake/testtask'
+
+task :prove_all do
+  Bundler.setup
+  Bundler.require :default
+  require_relative "proofs/all"
+end
+Rake::TestTask.new do |t|
+  t.libs.push "lib"
+  t.libs.push "test"
+  t.test_files = FileList['test/**/*_spec.rb']
+  t.verbose = true
+end
+
+task :default => [:test, :prove_all]

data/lib/replay.rb

@@ -1,14 +1,43 @@
-require "replay/version"
-require 'active_support/concern'
-require 'replay/unknown_event_error'
-require 'replay/test_storage'
-require 'replay/configuration'
-require 'replay/event'
-require 'replay/event_store'
-require 'replay/active_record_event_store'
-require 'replay/domain'
-require 'replay/projector'
+require 'virtus'
 
 module Replay
+  def self.logger=(logger)
+    @logger = logger
+  end
 
+  def self.logger
+    @logger
+  end
+
+  class ReplayError            < StandardError; end
+  class UndefinedKeyError      < ReplayError; end
+  class UnhandledEventError    < ReplayError; end
+  class UnknownEventError      < ReplayError; end
+  class InvalidStorageError    < ReplayError;
+    def initialize(*args)
+      klass = args.shift
+      super( "Storage #{klass.to_s} does not implement #event_stream(stream, event)", *args)
+    end
+  end
+  class InvalidSubscriberError < ReplayError;
+    def initialize(*args)
+      obj = args.shift
+      super( "Subscriber#{obj.to_s} does not implement #published(stream, event)", *args)
+    end
+  end
 end
+
+require 'replay/inflector'
+require 'replay/events'
+require 'replay/event_decorator'
+require 'replay/event_declarations'
+require 'replay/publisher'
+require 'replay/subscription_manager'
+require 'replay/backends'
+require 'replay/repository'
+require 'replay/repository/identity_map'
+require 'replay/repository/configuration'
+require 'replay/observer'
+require 'replay/router'
+require 'replay/router/default_router'
+

data/lib/replay/backends.rb

@@ -0,0 +1,50 @@
+require 'singleton'
+module Replay
+  class Backends
+    def self.register(shorthand, klass)
+      @backends ||= {}
+      @backends[shorthand] = klass
+      return klass
+    end
+    def self.resolve(shorthand)
+      @backends[shorthand] || shorthand
+    end
+
+    class MemoryStore
+      include Singleton
+      def initialize
+        @store = {}
+      end
+      def self.published(stream_id, event)
+        instance.published(stream_id, event)
+      end
+
+      def self.clear
+        instance.clear
+      end
+
+      def clear
+        @store = {}
+      end
+
+      def published(stream_id, event)
+        @store[stream_id] ||= []
+        @store[stream_id] << event
+      end
+      
+      def event_stream(stream_id)
+        @store[stream_id] || []
+      end
+
+      def self.event_stream(stream_id)
+        instance.event_stream(stream_id)
+      end
+      def self.[](stream_id)
+        instance.event_stream(stream_id)
+      end
+    end
+    register :memory, MemoryStore
+  end
+end
+
+

data/lib/replay/event_declarations.rb

@@ -0,0 +1,36 @@
+module Replay
+  module EventDeclarations
+    def self.included(base)
+      base.extend(Replay::Events)
+    end
+
+    def included(base)
+      self.constants.each do |c| 
+        base.const_set(c, const_get(c).dup)
+        klass = base.const_get(c)
+        base.class_eval do
+          define_method c do |props|
+            klass.new props
+          end
+        end
+      end
+    end
+    def method_missing(name, *args)
+      declare_event(self, name, args.first)
+    end
+
+    def declare_event(base, name, props)
+      klass = Class.new do
+        include Replay::EventDecorator
+        attribute :published_at, Time, default: lambda{|p,a| Time.now}
+        values do
+          props.keys.each do |prop|
+            attribute prop, props[prop]
+          end
+        end
+        include Virtus::Equalizer.new("#{name.to_s} equalizer", (self.attribute_set.map(&:name) - [:published_at]).map(&:to_s))
+      end
+      base.const_set name, klass
+    end
+  end
+end

data/lib/replay/event_decorator.rb

@@ -0,0 +1,13 @@
+module Replay
+  #hook class to apply global decorators to events
+  module EventDecorator 
+    def self.included(base)
+      base.class_eval do 
+        include Virtus.value_object
+        def inspect
+          "#{self.class.to_s}: #{self.attributes.map{|k, v| "#{k.to_s} = #{v.to_s}"}.join(", ")}"
+        end
+      end
+    end
+  end
+end

data/lib/replay/events.rb

@@ -0,0 +1,24 @@
+
+module Replay
+  module Events
+    def self.extended(base)
+      base.extend(ClassMethods)
+    end
+    def self.included(base)
+      base.extend(ClassMethods)
+      #self.constants.each{|c| base.const_set(c, const_get(c))}
+    end
+    module ClassMethods
+      def events(mod = nil, &block)
+        unless mod
+          mod = Module.new do
+            extend Replay::EventDeclarations
+            module_eval &block
+          end
+          self.const_set(:Events, mod)
+        end
+        include mod
+      end
+    end
+  end
+end

data/lib/replay/inflector.rb

@@ -0,0 +1,55 @@
+#This class substantially copied from ActiveSupport, licensed under MIT
+#Their version is generally better, so use that unless you've got a good reason
+#not to do so. also, i've changed certain aspects of behavior.
+class Replay::Inflector
+
+    # By default, +camelize+ converts strings to UpperCamelCase. If the argument
+    # to +camelize+ is set to <tt>:lower</tt> then +camelize+ produces
+    # lowerCamelCase.
+    #
+    # +camelize+ will also convert '/' to '::' which is useful for converting
+    # paths to namespaces.
+    #
+    #   'active_model'.camelize                # => "ActiveModel"
+    #   'active_model'.camelize(:lower)        # => "activeModel"
+    #   'active_model/errors'.camelize         # => "ActiveModel::Errors"
+    #   'active_model/errors'.camelize(:lower) # => "activeModel::Errors"
+    #
+    # As a rule of thumb you can think of +camelize+ as the inverse of
+    # +underscore+, though there are cases where that does not hold:
+    #
+    #   'SSLError'.underscore.camelize # => "SslError"
+    def self.camelize(term, uppercase_first_letter = false)
+      string = term.to_s
+      string = string.sub(/^[A-Z_]/) { $&.downcase }
+      string.gsub!(/(?:_|(\/))([a-z\d]*)/i) { "#{$1}#{$2.capitalize}" }
+      string.gsub!('/', '::')
+      string.gsub!('.', '::')
+      string
+    end
+    # Makes an underscored, lowercase form from the expression in the string.
+    #
+    # Changes '::' to '/' to convert namespaces to paths.
+    #
+    #   'ActiveModel'.underscore         # => "active_model"
+    #   'ActiveModel::Errors'.underscore # => "active_model/errors"
+    #
+    # As a rule of thumb you can think of +underscore+ as the inverse of
+    # +camelize+, though there are cases where that does not hold:
+    #
+    #   'SSLError'.underscore.camelize # => "SslError"
+    def self.underscore(camel_cased_word)
+      return camel_cased_word unless camel_cased_word =~ /[A-Z-]|::/
+      word = camel_cased_word.to_s.gsub('::', '.')
+      word.gsub!(/(?:([A-Za-z\d])^)(?=\b|[^a-z])/) { "#{$1}#{$2 && '_'}#{$2.downcase}" }
+      word.gsub!(/([A-Z\d]+)([A-Z][a-z])/,'\1_\2')
+      word.gsub!(/([a-z\d])([A-Z])/,'\1_\2')
+      word.tr!("-", "_")
+      word.downcase!
+      word
+    end
+
+    def self.constantize(class_name)
+      class_name.to_s.split("::").inject(Kernel){|parent, mod| parent.const_get(mod)}
+    end
+end