sourced 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 86885b939ec61102ef829ec6272cbb32e789c91d0be359226e35fd1f70a13aee
+  data.tar.gz: 7ee1faaaf4e58800dd31dbb530e4549771e263084ae69379bf72bce01e784b06
+SHA512:
+  metadata.gz: 628959098ebde04be796875608fa1410bd3bec7d40a6d362d944eb77769134b4fbc38858caa10cdd5ffa06817d693e5e5c8ca1ed89d4f2cbf25465e57af10ebd
+  data.tar.gz: d669516fe37fa9b714d7163b1b2055a1fd3ef91f05b4101c6e469317f6e99842411648017d2f3d0380aef6f9931f2f9cbb57724a47bd638fbb3fe744495ec02f

data/.rspec

@@ -0,0 +1,3 @@
+--color
+--require spec_helper
+--format documentation

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+## [Unreleased]
+
+## [0.1.0] - 2024-09-27
+
+- Initial release

data/README.md

@@ -0,0 +1,34 @@
+# sourced
+
+** WORK IN PROGRESS**
+
+Event Sourcing / CQRS library for Ruby.
+There's many ES gems available already. The objectives here are:
+* Cohesive and toy-like DX.
+* Eventual consistency by default.
+* Explore ES as a programming model for Ruby apps.
+
+## Installation
+
+Install the gem and add to the application's Gemfile by executing:
+
+    $ bundle add sourced
+
+**Note**: this gem is under active development, so you probably want to install from Github:
+In your Gemfile:
+
+    $ gem 'sourced', github: 'ismasan/sourced'
+
+## Usage
+
+TODO: Write usage instructions here
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/sourced.

data/Rakefile

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task default: :spec

data/examples/cart.rb

@@ -0,0 +1,229 @@
+# frozen_string_literal: true
+
+require 'bundler'
+Bundler.setup(:test)
+
+require 'sourced'
+require 'sequel'
+
+# ActiveRecord::Base.establish_connection(adapter: 'postgresql', database: 'decider')
+unless ENV['backend_configured']
+  puts 'aggregate config'
+  Sourced.configure do |config|
+    config.backend = Sequel.postgres('sourced_development')
+  end
+  ENV['backend_configured'] = 'true'
+end
+
+# A cart Actor/Aggregate
+# Example:
+#   cart = Cart.new('cart-1')
+#   cart.add_item(name: 'item1', price: 100)
+#   cart.place
+#   cart.events
+#
+# The above sends a Cart::Place command
+# which produces a Cart::Placed event
+class Cart < Sourced::Decider
+  State = Struct.new(:status, :notified, :items, :mailer_id) do
+    def total = items.sum(&:price)
+  end
+
+  def init_state(_id)
+    State.new(:open, false, [], nil)
+  end
+
+  ItemAdded = Sourced::Message.define('cart.item_added') do
+    attribute :name, String
+    attribute :price, Integer
+  end
+
+  Placed = Sourced::Message.define('cart.placed')
+  Notified = Sourced::Message.define('cart.notified') do
+    attribute :mailer_id, String
+  end
+
+  # Defines a Cart::AddItem command struct
+  command :add_item, 'cart.add_item', name: String, price: Integer do |cart, cmd|
+    apply(ItemAdded, cmd.payload.to_h)
+  end
+
+  # Defines a Cart::Place command struct
+  command :place, 'cart.place' do |_, cmd|
+    apply(Placed)
+  end
+
+  # Defines a Cart::Notify command struct
+  command :notify, 'cart.notify', mailer_id: String do |_, cmd|
+    puts "#{self.class.name} #{cmd.stream_id} NOTIFY"
+    apply(Notified, mailer_id: cmd.payload.mailer_id)
+  end
+
+  evolve ItemAdded do |cart, event|
+    cart.items << event.payload
+  end
+
+  evolve Placed do |cart, _event|
+    cart.status = :placed
+  end
+
+  evolve Notified do |cart, event|
+    cart.notified = true
+    cart.mailer_id = event.payload.mailer_id
+  end
+
+  # This block will run
+  # in the same transaction as appending
+  # new events to the store.
+  # So if either fails, eveything is rolled back.
+  # ergo, strong consistency.
+  sync do |command, events|
+    puts "#{self.class.name} #{events.last.seq} SYNC"
+  end
+
+  # Or register a Reactor interface to react to events
+  # synchronously
+  # sync CartListings
+end
+
+class Mailer < Sourced::Decider
+  EmailSent = Sourced::Message.define('mailer.email_sent') do
+    attribute :cart_id, String
+  end
+
+  def init_state(_id)
+    []
+  end
+
+  command :send_email, 'mailer.send_email', cart_id: String do |_, cmd|
+    # Send email here, emit EmailSent if successful
+    apply(EmailSent, cart_id: cmd.payload.cart_id)
+  end
+
+  evolve EmailSent do |list, event|
+    list << event
+  end
+end
+
+# A Saga that orchestrates the flow between Cart and Mailer
+class CartEmailsSaga < Sourced::Decider
+  # Listen for Cart::Placed events and
+  # send command to Mailer
+  react Cart::Placed do |event|
+    event.follow_with_stream_id(
+      Mailer::SendEmail,
+      "mailer-#{event.stream_id}",
+      cart_id: event.stream_id
+    )
+  end
+
+  # Listen for Mailer::EmailSent events and
+  # send command to Cart
+  react Mailer::EmailSent do |event|
+    event.follow_with_stream_id(
+      Cart::Notify,
+      event.payload.cart_id,
+      mailer_id: event.stream_id
+    )
+  end
+end
+
+# A projector
+# "reacts" to events registered with .evolve
+class CartListings < Sourced::Decider
+  class << self
+    def handled_events = self.handled_events_for_evolve
+
+    # The Reactor interface
+    # @param events [Array<Message>]
+    def handle_events(events)
+      # For this type of event sourced projections
+      # that load current state from events
+      # then apply "new" events
+      # TODO: the current state already includes
+      # the new events, so we need to load upto events.first.seq
+      instance = load(events.first.stream_id, upto: events.first.seq - 1)
+      instance.handle_events(events)
+    end
+  end
+
+  def handle_events(events)
+    evolve(state, events)
+    save
+    [] # no commands
+  end
+
+  def initialize(id, **_args)
+    super
+    FileUtils.mkdir_p('examples/carts')
+    @path = "./examples/carts/#{id}.json"
+  end
+
+  private def save
+    backend.transaction do
+      run_sync_blocks(state, nil, [])
+    end
+  end
+
+  def init_state(id)
+    { id:, items: [], status: :open, seq: 0, seqs: [] }
+  end
+
+  sync do |cart, _command, _events|
+    File.write(@path, JSON.pretty_generate(cart))
+  end
+
+  # Register all events from Cart
+  # So that before_evolve runs before all cart events
+  evolve_all Cart.handled_commands
+  evolve_all Cart
+
+  before_evolve do |cart, event|
+    cart[:seq] = event.seq
+    cart[:seqs] << event.seq
+  end
+
+  evolve Cart::Placed do |cart, event|
+    cart[:status] = :placed
+  end
+
+  evolve Cart::ItemAdded do |cart, event|
+    cart[:items] << event.payload.to_h
+  end
+end
+
+class LoggingReactor
+  extend Sourced::Consumer
+
+  class << self
+    # Register as a Reactor that cares about these events
+    # The workers will use this to fetch the right events
+    # and ACK offsets after processing
+    #
+    # @return [Array<Message>]
+    def handled_events = [Cart::Placed, Cart::ItemAdded]
+
+    # Workers pass available events to this method
+    # in order, with exactly-once semantics
+    # If a list of commands is returned,
+    # workers will send them to the router
+    # to be dispatched to the appropriate command handlers.
+    #
+    # @param events [Array<Message>]
+    # @return [Array<Message]
+    def handle_events(events)
+      puts "LoggingReactor received #{events}"
+      []
+    end
+  end
+end
+
+# Cart.sync CartListings
+
+# Register Reactor interfaces with the Router
+# This allows the Router to route commands and events to reactors
+Sourced::Router.register(LoggingReactor)
+Sourced::Router.register(Cart)
+Sourced::Router.register(Mailer)
+Sourced::Router.register(CartEmailsSaga)
+Sourced::Router.register(CartListings)

data/examples/workers.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+require_relative './cart'
+
+Sourced::Supervisor.start

data/lib/sourced/backends/active_record_backend.rb

@@ -0,0 +1,184 @@
+# frozen_string_literal: true
+
+require 'active_record'
+require 'json'
+require 'sourced/message'
+
+module Sourced
+  module Backends
+    class ActiveRecordBackend
+      PREFIX = 'sourced'
+
+      class EventRecord < ActiveRecord::Base
+        self.inheritance_column = nil
+        self.table_name = [PREFIX, '_events'].join
+      end
+
+      class StreamRecord < ActiveRecord::Base
+        self.table_name = [PREFIX, '_streams'].join
+      end
+
+      class CommandRecord < ActiveRecord::Base
+        self.table_name = [PREFIX, '_commands'].join
+      end
+
+      def self.table_prefix=(prefix)
+        @table_prefix = prefix
+        EventRecord.table_name = [prefix, '_events'].join
+        StreamRecord.table_name = [prefix, '_streams'].join
+        CommandRecord.table_name = [prefix, '_commands'].join
+      end
+
+      def self.table_prefix
+        @table_prefix || PREFIX
+      end
+
+      def self.installed?
+        ActiveRecord::Base.connection.table_exists?(EventRecord.table_name) &&
+          ActiveRecord::Base.connection.table_exists?(StreamRecord.table_name) &&
+          ActiveRecord::Base.connection.table_exists?(CommandRecord.table_name)
+      end
+
+      def self.uninstall!
+        raise 'Not in test environment' unless ENV['ENVIRONMENT'] == 'test'
+
+        ActiveRecord::Base.connection.drop_table(EventRecord.table_name)
+        ActiveRecord::Base.connection.drop_table(CommandRecord.table_name)
+        ActiveRecord::Base.connection.drop_table(StreamRecord.table_name)
+      end
+
+      def initialize
+        @serialize_event = method(:serialize_jsonb_event)
+        @deserialize_event = method(:deserialize_jsonb_event)
+        if EventRecord.connection.class.name == 'ActiveRecord::ConnectionAdapters::SQLite3Adapter'
+          @serialize_event = method(:serialize_sqlite_event)
+          @deserialize_event = method(:deserialize_sqlite_event)
+        end
+      end
+
+      def installed? = self.class.installed?
+
+      def clear!
+        raise 'Not in test environment' unless ENV['ENVIRONMENT'] == 'test'
+
+        EventRecord.delete_all
+        CommandRecord.delete_all
+        StreamRecord.delete_all
+      end
+
+      # TODO: if all commands belong to the same stream_id
+      # we could upsert the streams table once here
+      def schedule_commands(commands)
+        return false if commands.empty?
+
+        # TODO: here we could use multi_insert
+        # for both streams and commands
+        CommandRecord.transaction do
+          commands.each do |command|
+            schedule_command(command.stream_id, command)
+          end
+        end
+        true
+      end
+
+      def schedule_command(stream_id, command)
+        CommandRecord.transaction do
+          StreamRecord.upsert({ stream_id: }, unique_by: :stream_id)
+          CommandRecord.create!(stream_id:, data: command.to_json)
+        end
+      end
+
+      # TODO: locking the stream could be 
+      # done in a single SQL query, or using an SQL function.
+      def reserve_next(&)
+        command_record = transaction do
+          cmd = CommandRecord
+            .joins("INNER JOIN #{StreamRecord.table_name} ON #{CommandRecord.table_name}.stream_id = #{StreamRecord.table_name}.stream_id")
+            .where(["#{StreamRecord.table_name}.locked = ?", false])
+            .order("#{CommandRecord.table_name}.id ASC")
+            .lock # "FOR UPDATE"
+            .first
+
+          if cmd
+            StreamRecord.where(stream_id: cmd.stream_id).update(locked: true)
+          end
+          cmd
+        end
+
+        cmd = nil
+        if command_record
+          # TODO: find out why #data isn't already
+          # deserialized here
+          data = JSON.parse(command_record.data, symbolize_names: true)
+          cmd = Message.from(data)
+          yield cmd
+          # Only delete the command if processing didn't raise
+          command_record.destroy
+        end
+        cmd
+      ensure
+        # Always unlock the stream
+        if command_record
+          StreamRecord.where(stream_id: command_record.stream_id).update(locked: false)
+        end
+      end
+
+      def transaction(&)
+        EventRecord.transaction(&)
+      end
+
+      def append_events(events)
+        rows = events.map { |e| serialize_event(e) }
+        EventRecord.insert_all!(rows)
+        true
+      rescue ActiveRecord::RecordNotUnique => e
+        raise Sourced::ConcurrentAppendError, e.message
+      end
+
+      def read_event_batch(causation_id)
+        EventRecord.where(causation_id:).order(:global_seq).map do |record|
+          deserialize_event(record)
+        end
+      end
+
+      def read_event_stream(stream_id, after: nil, upto: nil)
+        query = EventRecord.where(stream_id:)
+        query = query.where('seq > ?', after) if after
+        query = query.where('seq <= ?', upto) if upto
+        query.order(:global_seq).map do |record|
+          deserialize_event(record)
+        end
+      end
+
+      private
+
+      def serialize_event(event)
+        @serialize_event.(event)
+      end
+
+      def serialize_jsonb_event(event)
+        event.to_h
+      end
+
+      def serialize_sqlite_event(event)
+        attrs = event.to_h
+        attrs[:payload] = JSON.generate(attrs[:payload]) if attrs[:payload].present?
+        attrs
+      end
+
+      def deserialize_event(record)
+        Message.from(@deserialize_event.(record).deep_symbolize_keys)
+      end
+
+      def deserialize_jsonb_event(record)
+        record.attributes
+      end
+
+      def deserialize_sqlite_event(record)
+        attrs = record.attributes
+        attrs['payload'] = JSON.parse(attrs['payload']) if attrs['payload'].present?
+        attrs
+      end
+    end
+  end
+end