sourced 0.0.1

data/lib/sourced/configuration.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require 'console' #  comes with async gem
+require 'sourced/types'
+require 'sourced/backends/test_backend'
+
+module Sourced
+  class Configuration
+    #  Backends must expose these methods
+    BackendInterface = Types::Interface[
+      :installed?,
+      :reserve_next_for_reactor,
+      :append_to_stream,
+      :read_correlation_batch,
+      :read_event_stream,
+      :schedule_commands,
+      :next_command,
+      :transaction
+    ]
+
+    attr_accessor :logger
+    attr_reader :backend
+
+    def initialize
+      @logger = Console
+      @backend = Backends::TestBackend.new
+    end
+
+    def backend=(bnd)
+      @backend = case bnd.class.name
+                 when 'Sequel::Postgres::Database', 'Sequel::SQLite::Database'
+                   require 'sourced/backends/sequel_backend'
+                   Sourced::Backends::SequelBackend.new(bnd)
+                 else
+                   BackendInterface.parse(bnd)
+                 end
+    end
+  end
+end

data/lib/sourced/consumer.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Sourced
+  module Consumer
+    class ConsumerInfo < Types::Data
+      ToBlock = Types::Any.transform(Proc) { |v| -> { v } }
+      StartFromBeginning = Types::Value[:beginning] >> Types::Static[nil] >> ToBlock
+      StartFromNow = Types::Value[:now] >> Types::Static[-> { Time.now - 5 }.freeze]
+      StartFromTime = Types::Interface[:call].check('must return a Time') { |v| v.call.is_a?(Time) }
+
+      StartFrom = (
+        StartFromBeginning | StartFromNow | StartFromTime
+      ).default { -> { nil } }
+
+      attribute :group_id, Types::String.present, writer: true
+      attribute :start_from, StartFrom, writer: true
+      attribute :async, Types::Boolean.default(true), writer: true
+
+      def sync!
+        self.async = false
+      end
+
+      def async!
+        self.async = true
+      end
+    end
+
+    def consumer_info
+      @consumer_info ||= ConsumerInfo.new(group_id: name, start_from: :beginning)
+    end
+
+    def consumer(&)
+      return consumer_info unless block_given?
+
+      info = ConsumerInfo.new(group_id: name)
+      yield info
+      raise Plumb::ParseError, info.errors unless info.valid?
+
+      @consumer_info = info
+    end
+  end
+end

data/lib/sourced/decide.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module Sourced
+  module Decide
+    PREFIX = 'command'
+
+    def self.included(base)
+      super
+      base.extend ClassMethods
+    end
+
+    # Run command handler methods
+    # defined with the .decide(Command, &) macro
+    # The signature will depend on how the command handler is defined
+    # Example:
+    #   decide(state, command)
+    #   decide(command)
+    def decide(*args)
+      events = case args
+               in [command]
+                 send(Sourced.message_method_name(PREFIX, command.class.name), command)
+               in [state, command]
+                 send(Sourced.message_method_name(PREFIX, command.class.name), state, command)
+               end
+      [events].flatten.compact
+    end
+
+    module ClassMethods
+      def inherited(subclass)
+        super
+        handled_commands.each do |cmd_type|
+          subclass.handled_commands << cmd_type
+        end
+      end
+
+      def handle_command(_command)
+        raise NoMethodError, "implement .handle_command(Command) in #{self}"
+      end
+
+      def handled_commands
+        @handled_commands ||= []
+      end
+
+      def decide(cmd_type, &block)
+        handled_commands << cmd_type
+        define_method(Sourced.message_method_name(PREFIX, cmd_type.name), &block)
+      end
+    end
+  end
+end

data/lib/sourced/decider.rb

@@ -0,0 +1,251 @@
+# frozen_string_literal: true
+
+module Sourced
+  class Decider
+    include Evolve
+    include React
+    include Sync
+    extend Consumer
+
+    PREFIX = 'decide'
+
+    class << self
+      def inherited(subclass)
+        super
+        handled_commands.each do |cmd_type|
+          subclass.handled_commands << cmd_type
+        end
+      end
+
+      # Register as a Reactor
+      def handled_events = self.handled_events_for_react
+
+      # The Reactor interface
+      # @param events [Array<Message>]
+      def handle_events(events)
+        load(events.first.stream_id).handle_events(events)
+      end
+
+      # The Decider interface
+      # @param cmd [Command]
+      def handle_command(cmd)
+        load(cmd.stream_id).handle_command(cmd)
+      end
+
+      # Load a Decider from event history
+      #
+      # @param stream_id [String] the stream id
+      # @return [Decider]
+      def load(stream_id, upto: nil)
+        new(stream_id).load(upto:)
+      end
+
+      def handled_commands
+        @handled_commands ||= []
+      end
+
+      def decide(cmd_type, &block)
+        handled_commands << cmd_type
+        define_method(Sourced.message_method_name(PREFIX, cmd_type.name), &block)
+      end
+
+      # Define a command class, register a command handler
+      # and define a method to send the command
+      # Example:
+      #   command :add_item, name: String do |cmd|
+      #     cmd.follow(ItemAdded, item_id: SecureRandom.uuid, name: cmd.payload.name)
+      #   end
+      #
+      # # The exmaple above will define a command class `AddItem` in the current namespace:
+      # AddItem = Message.define('namespace.add_item', payload_schema: { name: String })
+      #
+      # # Optionally you can pass an explicit command type string:
+      #   command :add_item, 'todos.items.add', name: String do |cmd|
+      #
+      # # It will also register the command handler:
+      # decide AddItem do |cmd|
+      #   cmd.follow(ItemAdded, item_id: SecureRandom.uuid, name: cmd.payload.name)
+      # end
+      #
+      # # And an :add_item method to send the command:
+      # def add_item(name:)
+      #   issue_command AddItem, name:
+      # end
+      #
+      # This method can be used on Decider instances:
+      #   aggregate.add_item(name: 'Buy milk')
+      #
+      # Payload schema is a Plumb Hash schema.
+      # See: https://github.com/ismasan/plumb#typeshash
+      #
+      # The helper method will instantiate an instance of the command class
+      # and validate its attributes with #valid?
+      # Only valid commands will be issued to the handler.
+      # The method returns the command instance. If #valid? is false, then the command was not issued.
+      # Example:
+      #   cmd = aggregate.add_item(name: 10)
+      #   cmd.valid? # => false
+      #   cmd.errors # => { name: 'must be a String' }
+      #
+      # @param cmd_name [Symbol] example: :add_item
+      # @param payload_schema [Hash] A Plumb Hash schema. example: { name: String }
+      # @param block [Proc] The command handling code
+      # @return [Message] the command instance, which can be #valid? or not
+      def command(*args, &block)
+        raise ArgumentError, 'command block expects signature (state, command)' unless block.arity == 2
+
+        message_type = nil
+        cmd_name = nil
+        payload_schema = {}
+        segments = name.split('::').map(&:downcase)
+
+        case args
+          in [cmd_name]
+            message_type = [*segments, cmd_name].join('.')
+          in [cmd_name, Hash => payload_schema]
+            message_type = [*segments, cmd_name].join('.')
+          in [cmd_name, String => message_type, Hash => payload_schema]
+          in [cmd_name, String => message_type]
+        else
+          raise ArgumentError, "Invalid arguments for #{self}.command"
+        end
+
+        klass_name = cmd_name.to_s.split('_').map(&:capitalize).join
+        cmd_class = Command.define(message_type, payload_schema:)
+        const_set(klass_name, cmd_class)
+        decide cmd_class, &block
+        define_method(cmd_name) do |**payload|
+          issue_command cmd_class, payload
+        end
+      end
+    end
+
+    attr_reader :id, :seq, :state, :uncommitted_events
+
+    def initialize(id = SecureRandom.uuid, backend: Sourced.config.backend, logger: Sourced.config.logger)
+      @id = id
+      @backend = backend
+      @logger = logger
+      @seq = 0
+      @state = init_state(id)
+      @uncommitted_events = []
+      @__current_command = nil
+    end
+
+    def inspect
+      %(<#{self.class} id:#{id} seq:#{seq}>)
+    end
+
+    def ==(other)
+      other.is_a?(self.class) && id == other.id && seq == other.seq
+    end
+
+    def init_state(id)
+      nil
+    end
+
+    def load(after: nil, upto: nil)
+      events = backend.read_event_stream(id, after:, upto:)
+      if events.any?
+        @seq = events.last.seq 
+        evolve(state, events)
+      end
+      self
+    end
+
+    def catch_up
+      seq_was = seq
+      load(after: seq_was)
+      [seq_was, seq]
+    end
+
+    def events(upto: seq)
+      backend.read_event_stream(id, upto:)
+    end
+
+    def decide(command)
+      command = __set_current_command(command)
+      send(Sourced.message_method_name(PREFIX, command.class.name), state, command)
+      @__current_command = nil
+      [state, uncommitted_events]
+    end
+
+    def apply(event_class, payload = {})
+      evt = __current_command.follow_with_attributes(
+        event_class, 
+        attrs: { seq: __next_sequence }, 
+        metadata: { producer: self.class.consumer_info.group_id },
+        payload:
+      )
+      uncommitted_events << evt
+      evolve(state, [evt])
+    end
+
+    def commit(&)
+      output_events = uncommitted_events.slice(0..-1)
+      yield output_events
+      @uncommitted_events = []
+      output_events
+    end
+
+    # Register a first sync block to append new events to backend
+    sync do |_state, command, events|
+      messages = [command, *events]
+      backend.append_to_stream(id, messages) if messages.any?
+    end
+
+    sync do |_state, command, events|
+      Sourced::Router.handle_events(events)
+    end
+
+    def handle_command(command)
+      # TODO: this might raise an exception from a worker
+      # Think what to do with invalid commands here
+      raise "invalid command #{command.inspect} #{command.errors.inspect}" unless command.valid?
+      logger.info "#{self.inspect} Handling #{command.type}"
+      decide(command)
+      save
+    end
+
+    # TODO: idempotent event and command handling
+    # Reactor interface
+    # Handle events, return new commands
+    # Workers will handle route these commands
+    # to their target Deciders
+    def handle_events(events)
+      react(events)
+    end
+
+    private
+
+    attr_reader :backend, :logger, :__current_command
+
+    def save
+      events = commit do |messages|
+        backend.transaction do
+          run_sync_blocks(state, messages[0], messages[1..-1])
+        end
+      end
+      [ self, events ]
+    end
+
+    def __set_current_command(command)
+      command.with(seq: __next_sequence).tap do |cmd|
+        uncommitted_events << cmd
+        @__current_command = cmd
+      end
+    end
+
+    def __next_sequence
+      @seq += 1
+    end
+
+    def issue_command(klass, payload = {})
+      cmd = klass.new(stream_id: id, payload:)
+      return cmd unless cmd.valid?
+
+      handle_command(cmd)
+      cmd
+    end
+  end
+end

data/lib/sourced/evolve.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+module Sourced
+  module Evolve
+    PREFIX = 'evolution'
+    NOOP_HANDLER = ->(*_) { nil }
+
+    def self.included(base)
+      super
+      base.extend ClassMethods
+    end
+
+    def evolve(*args)
+      state = self
+
+      case args
+      in [events]
+        events.each do |event|
+          method_name = Sourced.message_method_name(Evolve::PREFIX, event.class.to_s)
+          if respond_to?(method_name)
+            before_evolve(event)
+            send(method_name, event) 
+        end
+        end
+      in [obj, events]
+        state = obj
+        events.each do |event|
+          method_name = Sourced.message_method_name(Evolve::PREFIX, event.class.to_s)
+          if respond_to?(method_name)
+            before_evolve(state, event)
+            send(method_name, state, event)
+          end
+        end
+      end
+
+      state
+    end
+
+    private def before_evolve(*_)
+      nil
+    end
+
+    module ClassMethods
+      def inherited(subclass)
+        super
+        handled_events_for_evolve.each do |evt_type|
+          subclass.handled_events_for_evolve << evt_type
+        end
+      end
+
+      # These two are the Reactor interface
+      # expected by Worker
+      def handle_events(_events)
+        raise NoMethodError, "implement .handle_events(Array<Event>) in #{self}"
+      end
+
+      def handled_events_for_evolve
+        @handled_events_for_evolve ||= []
+      end
+
+      # Example:
+      #   evolve :event_type do |event|
+      #     @updated_at = event.created_at
+      #   end
+      #
+      # @param event_type [Sourced::Message]
+      def evolve(event_type, &block)
+        handled_events_for_evolve << event_type unless event_type.is_a?(Symbol)
+        block = NOOP_HANDLER unless block_given?
+        define_method(Sourced.message_method_name(Evolve::PREFIX, event_type.to_s), &block)
+      end
+
+      # Run this block before any of the registered event handlers
+      # Example:
+      #   before_evolve do |event|
+      #     @updated_at = event.created_at
+      #   end
+      def before_evolve(&block)
+        define_method(:before_evolve, &block)
+      end
+
+      # Example:
+      #   # With an Array of event types
+      #   evolve_all [:event_type1, :event_type2] do |event|
+      #     @updated_at = event.created_at
+      #   end
+      #
+      #   # From another Evolver that responds to #handled_events_for_evolve
+      #   evolve_all CartAggregate do |event|
+      #     @updated_at = event.created_at
+      #   end
+      #
+      # @param event_list [Array<Sourced::Message>, #handled_events_for_evolve() {Array<Sourced::Message>}]
+      def evolve_all(event_list, &block)
+        event_list = event_list.handled_events_for_evolve if event_list.respond_to?(:handled_events_for_evolve)
+        event_list.each do |event_type|
+          evolve(event_type, &block)
+        end
+      end
+    end
+  end
+end

data/lib/sourced/message.rb

@@ -0,0 +1,202 @@
+# frozen_string_literal: true
+
+require 'sourced/types'
+
+# A superclass and registry to define event types
+# for example for an event-driven or event-sourced system.
+# All events have an "envelope" set of attributes,
+# including unique ID, stream_id, type, timestamp, causation ID,
+# event subclasses have a type string (ex. 'users.name.updated') and an optional payload
+# This class provides a `.define` method to create new event types with a type and optional payload struct,
+# a `.from` method to instantiate the correct subclass from a hash, ex. when deserializing from JSON or a web request.
+# and a `#follow` method to produce new events based on a previous event's envelope, where the #causation_id and #correlation_id
+# are set to the parent event
+# @example
+#
+#  # Define event struct with type and payload
+#  UserCreated = Message.define('users.created') do
+#    attribute :name, Types::String
+#    attribute :email, Types::Email
+#  end
+#
+#  # Instantiate a full event with .new
+#  user_created = UserCreated.new(stream_id: 'user-1', payload: { name: 'Joe', email: '...' })
+#
+#  # Use the `.from(Hash) => Message` factory to lookup event class by `type` and produce the right instance
+#  user_created = Message.from(type: 'users.created', stream_id: 'user-1', payload: { name: 'Joe', email: '...' })
+#
+#  # Use #follow(payload Hash) => Message to produce events following a command or parent event
+#  create_user = CreateUser.new(...)
+#  user_created = create_user.follow(UserCreated, name: 'Joe', email: '...')
+#  user_created.causation_id == create_user.id
+#  user_created.correlation_id == create_user.correlation_id
+#  user_created.stream_id == create_user.stream_id
+#
+# ## Message registries
+# Each Message class has its own registry of sub-classes.
+# You can use the top-level Sourced::Message.from(hash) to instantiate all message types.
+# You can also scope the lookup by sub-class.
+# 
+# @example
+#
+#   class PublicCommand < Sourced::Message; end
+#   
+#   DoSomething = PublicCommand.define('commands.do_something')
+#
+#   # Use .from scoped to PublicCommand subclass
+#   # to ensure that only PublicCommand subclasses are accessible.
+#   cmd = PublicCommand.from(type: 'commands.do_something', payload: { ... })
+#
+# ## JSON Schemas
+# Plumb data structs support `.to_json_schema`, so you can document all events in the registry with something like
+#
+#   Message.subclasses.map(&:to_json_schema)
+#
+module Sourced
+  UnknownMessageError = Class.new(ArgumentError)
+  PastMessageDateError = Class.new(ArgumentError)
+
+  class Message < Types::Data
+    attribute :id, Types::AutoUUID
+    attribute :stream_id, Types::String.present
+    attribute :type, Types::String.present
+    attribute :created_at, Types::Forms::Time.default { Time.now } #Types::JSON::AutoUTCTime
+    attribute? :causation_id, Types::UUID::V4
+    attribute? :correlation_id, Types::UUID::V4
+    attribute :seq, Types::Integer.default(1)
+    attribute :metadata, Types::Hash.default(Plumb::BLANK_HASH)
+    attribute :payload, Types::Static[nil]
+
+    class Registry
+      def initialize(message_class)
+        @message_class = message_class
+        @lookup = {}
+      end
+
+      def []=(key, klass)
+        @lookup[key] = klass
+      end
+
+      def [](key)
+        klass = lookup[key]
+        return klass if klass
+
+        message_class.subclasses.each do |c|
+          klass = c.registry[key]
+          return klass if klass
+        end
+        nil
+      end
+
+      def inspect
+        %(<#{self.class}:#{object_id} #{lookup.size} keys, #{message_class.subclasses.size} child registries>)
+      end
+
+      private
+
+      attr_reader :lookup, :message_class
+    end
+
+    def self.registry
+      @registry ||= Registry.new(self)
+    end
+
+    class Payload < Types::Data
+      def [](key) = attributes[key]
+      def fetch(...) = to_h.fetch(...)
+    end
+
+    def self.define(type_str, payload_schema: nil, &payload_block)
+      type_str.freeze unless type_str.frozen?
+      if registry[type_str]
+        Sourced.config.logger.warn("Message '#{type_str}' already defined")
+      end
+
+      registry[type_str] = Class.new(self) do
+        def self.node_name = :data
+        define_singleton_method(:type) { type_str }
+
+        attribute :type, Types::Static[type_str]
+        if payload_schema
+          attribute :payload, Payload[payload_schema]
+        elsif block_given?
+          attribute :payload, Payload, &payload_block if block_given?
+        end
+      end
+    end
+
+    def self.from(attrs)
+      klass = registry[attrs[:type]]
+      raise UnknownMessageError, "Unknown event type: #{attrs[:type]}" unless klass
+
+      klass.new(attrs)
+    end
+
+    def initialize(attrs = {})
+      unless attrs[:payload]
+        attrs = attrs.merge(payload: {})
+      end
+      super(attrs)
+    end
+
+    def with_metadata(meta = {})
+      return self if meta.empty?
+
+      attrs = metadata.merge(meta)
+      with(metadata: attrs)
+    end
+
+    def follow(event_class, payload_attrs = nil)
+      follow_with_attributes(
+        event_class,
+        payload: payload_attrs
+      )
+    end
+
+    def follow_with_seq(event_class, seq, payload_attrs = nil)
+      follow_with_attributes(
+        event_class,
+        attrs: { seq: },
+        payload: payload_attrs
+      )
+    end
+
+    def follow_with_stream_id(event_class, stream_id, payload_attrs = nil)
+      follow_with_attributes(
+        event_class,
+        attrs: { stream_id: },
+        payload: payload_attrs
+      )
+    end
+
+    def follow_with_attributes(event_class, attrs: {}, payload: nil, metadata: nil)
+      meta = self.metadata
+      meta = meta.merge(metadata) if metadata
+      attrs = { stream_id:, causation_id: id, correlation_id:, metadata: meta }.merge(attrs)
+      attrs[:payload] = payload.to_h if payload
+      event_class.parse(attrs)
+    end
+
+    def delay(datetime)
+      if datetime < created_at
+        raise PastMessageDateError, "Message #{type} can't be delayed to a date in the past"
+      end
+      with(created_at: datetime)
+    end
+
+    def to_json(*)
+      to_h.to_json(*)
+    end
+
+    private
+
+    def prepare_attributes(attrs)
+      attrs[:correlation_id] = attrs[:id] unless attrs[:correlation_id]
+      attrs[:causation_id] = attrs[:id] unless attrs[:causation_id]
+      attrs
+    end
+  end
+
+  class Command < Message; end
+  class Event < Message; end
+end