tcb 0.5.0 → 0.6.0

data/lib/generators/tcb/install/templates/tcb.rb.tt

@@ -1,18 +1,20 @@
+# Domain modules — which bounded contexts exist
+# Add your domain modules here after generating them:
+#   rails generate tcb:event_store orders place_order:order_id,customer
+#   rails generate tcb:domain notifications send_welcome_email:user_id,email
+TCB.domain_modules = [
+  # Orders,
+  # Notifications,
+]
+
+# Infrastructure — how events are transported and stored
+# Runs on every Rails reload in development
 Rails.application.config.to_prepare do
   TCB.configure do |c|
     c.event_bus   = TCB::EventBus.new(
       handle_signals: true,
       shutdown_timeout: 10.0
     )
-    c.event_store = Rails.env.test? ? TCB::EventStore::InMemory.new
-                                    : TCB::EventStore::ActiveRecord.new
-
-    # Add your domain modules here after generating them:
-    #   rails generate tcb:event_store orders place_order:order_id,customer
-    #   rails generate tcb:domain notifications send_welcome_email:user_id,email
-    c.domain_modules = [
-      # Orders,
-      # Notifications
-    ]
+    c.event_store = TCB::EventStore::ActiveRecord.new
   end
 end

data/lib/tcb/command_bus.rb

@@ -2,10 +2,14 @@
 module TCB
   CommandHandlerNotFound = Class.new(StandardError)
 
-  def self.dispatch(command)
+  def self.dispatch(command, correlation_id: SecureRandom.uuid)
     validate!(command)
     handler = resolve_handler(command)
+    Thread.current[:tcb_correlation_id] = correlation_id
     handler.new.call(command)
+    correlation_id
+  ensure
+    Thread.current[:tcb_correlation_id] = nil
   end
 
   def self.validate!(command)

data/lib/tcb/configuration.rb

@@ -62,6 +62,10 @@ module TCB
       ]
     end
 
+    def event_bus_configured?
+      !!@event_bus
+    end
+
     private
 
     def flush_domain_modules
@@ -70,8 +74,13 @@ module TCB
 
         domain_module.event_handler_registrations.each do |registration|
           registration.handlers.each do |handler|
-            event_bus.subscribe(registration.event_class) do |event|
-              handler.new.call(event)
+            event_bus.subscribe(registration.event_class) do |envelope|
+              Thread.current[:tcb_correlation_id] = envelope.correlation_id
+              Thread.current[:tcb_causation_id]   = envelope.event_id
+              handler.new.call(envelope.event)
+            ensure
+              Thread.current[:tcb_correlation_id] = nil
+              Thread.current[:tcb_causation_id]   = nil
             end
           end
         end
@@ -93,12 +102,13 @@ module TCB
       @persist_registrations = []
       @domain_modules.each do |domain_module|
         next unless domain_module.respond_to?(:persist_registrations)
+        next unless domain_module.persist_registrations.any?
 
         context = DomainContext.from_module(domain_module).to_s
         domain_module.persist_registrations.each do |registration|
           @persist_registrations << registration.with(context: context)
         end
-        define_event_record_for(domain_module) if domain_module.persist_registrations.any?
+        define_event_record_for(domain_module)
       end
     end
 
@@ -111,8 +121,4 @@ module TCB
       domain_module.const_set(:EventRecord, klass)
     end
   end
-
-  def self.config
-    @config ||= Configuration.new
-  end
 end

data/lib/tcb/correlation_query.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module TCB
+  class CorrelationQuery
+    def initialize(store:, correlation_id:, domains:, occurred_after: nil, occurred_before: nil)
+      @store          = store
+      @correlation_id = correlation_id
+      @domains        = domains
+      @occurred_after  = occurred_after
+      @occurred_before = occurred_before
+    end
+
+    def occurred_after(time)
+      self.class.new(store: @store, correlation_id: @correlation_id, domains: @domains, occurred_after: time, occurred_before: @occurred_before)
+    end
+
+    def occurred_before(time)
+      self.class.new(store: @store, correlation_id: @correlation_id, domains: @domains, occurred_after: @occurred_after, occurred_before: time)
+    end
+
+    def between(from, to)
+      occurred_after(from).occurred_before(to)
+    end
+
+    def to_a
+      @domains.flat_map do |domain|
+        context = DomainContext.from_module(domain).to_s
+        @store.read_by_correlation(@correlation_id, context: context, occurred_after: @occurred_after, occurred_before: @occurred_before)
+      end.sort_by(&:occurred_at)
+    end
+  end
+end

data/lib/tcb/envelope.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require "securerandom"
+
+module TCB
+  Envelope = Data.define(
+    :event,
+    :event_id,
+    :stream_id,
+    :version,
+    :occurred_at,
+    :correlation_id,
+    :causation_id
+  ) do
+    def self.wrap(event, correlation_id: nil, causation_id: nil)
+      new(
+        event:          event,
+        event_id:       SecureRandom.uuid,
+        stream_id:      nil,
+        version:        nil,
+        occurred_at:    Time.now,
+        correlation_id: correlation_id,
+        causation_id:   causation_id
+      )
+    end
+
+    def self.coerce(event_or_envelope)
+      event_or_envelope.is_a?(self) ? event_or_envelope : wrap(event_or_envelope)
+    end
+  end
+end

data/lib/tcb/event_bus/queue_pressure_monitor.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module TCB
+  class EventBus
+    class QueuePressureMonitor
+      def self.for(max_queue_size:, high_water_mark:)
+        return new(high_water_mark:) if max_queue_size && high_water_mark
+
+        NullQueuePressureMonitor.new
+      end
+
+      def initialize(high_water_mark:)
+        @high_water_mark = high_water_mark
+        @emitted = false
+      end
+
+      def check?(queue_size)
+        if queue_size >= @high_water_mark
+          return false if @emitted
+          @emitted = true
+          true
+        else
+          @emitted = false
+          false
+        end
+      end
+    end
+
+    class NullQueuePressureMonitor
+      def check?(_queue_size)
+        false
+      end
+    end
+  end
+end

data/lib/tcb/event_bus/running_strategy.rb

@@ -3,12 +3,31 @@
 module TCB
   class EventBus
     class RunningStrategy
-      def initialize(event_bus)
+      def initialize(event_bus, sync: false)
         @event_bus = event_bus
+        @sync = sync
+      end
+
+      def start
+        return if @sync
+
+        @event_bus.dispatcher = Thread.new do
+          loop do
+            event = @event_bus.queue.pop
+            break if event == :shutdown_sentinel
+
+            @event_bus.dispatch(event)
+            @event_bus.dispatch(build_pressure_event) if @event_bus.high_water_mark_reached?
+          end
+        end
       end
 
       def publish(event)
-        @event_bus.queue << event
+        if @sync
+          @event_bus.dispatch(event)
+        else
+          @event_bus.queue << event
+        end
         event
       end
 
@@ -19,6 +38,17 @@ module TCB
       def shutdown?
         false
       end
+
+      private
+
+      def build_pressure_event
+        EventBusQueuePressure.new(
+          queue_size: @event_bus.queue.size,
+          max_queue_size: @event_bus.max_queue_size,
+          occupancy: @event_bus.queue.size.to_f / @event_bus.max_queue_size,
+          occurred_at: Time.now
+        )
+      end
     end
   end
 end

data/lib/tcb/event_bus/shutdown_strategy.rb

@@ -61,12 +61,16 @@ module TCB
       end
 
       def force_terminate
+        return unless @event_bus.dispatcher
+
         @event_bus.queue << :shutdown_sentinel
         @event_bus.dispatcher.kill if @event_bus.dispatcher.alive?
         @event_bus.dispatcher.join(0.1)
       end
 
       def terminate_dispatcher
+        return unless @event_bus.dispatcher
+
         @event_bus.queue << :shutdown_sentinel
         @event_bus.dispatcher.join(0.5)
       end

data/lib/tcb/event_bus.rb

@@ -1,49 +1,38 @@
 # frozen_string_literal: true
 
-require 'set'
-require_relative 'event_bus/running_strategy'
-require_relative 'event_bus/shutdown_strategy'
-require_relative 'event_bus/termination_signal_handler'
-require_relative 'event_bus/subscriber_registry'
+require "set"
+require_relative "event_bus/running_strategy"
+require_relative "event_bus/shutdown_strategy"
+require_relative "event_bus/termination_signal_handler"
+require_relative "event_bus/subscriber_registry"
 
 module TCB
   class EventBus
     class ShutdownError < StandardError; end
 
-    attr_reader :queue, :registry, :mutex,
-                :active_dispatches, :dispatcher, :events_processed_during_shutdown
+    attr_reader :queue, :registry, :mutex, :active_dispatches, :events_processed_during_shutdown, :max_queue_size
+    attr_accessor :dispatcher
 
     def initialize(
       handle_signals: false,
       shutdown_timeout: 30.0,
       shutdown_signals: [:TERM, :INT],
-      on_signal: nil
+      on_signal: nil,
+      max_queue_size: nil,
+      high_water_mark: nil,
+      sync: false
     )
-      @queue = Queue.new
+      @sync = sync
+      @queue = max_queue_size ? SizedQueue.new(max_queue_size) : Queue.new
+      @max_queue_size = max_queue_size
+      @pressure_monitor = QueuePressureMonitor.for(max_queue_size:, high_water_mark:)
       @registry = SubscriberRegistry.new
       @mutex = Mutex.new
       @active_dispatches = 0
       @events_processed_during_shutdown = 0
-      @execution_strategy = RunningStrategy.new(self)
-
-      @dispatcher = Thread.new do
-        loop do
-          event = @queue.pop
-          break if event == :shutdown_sentinel
-
-          dispatch(event)
-        end
-      end
-
-      if handle_signals
-        @termination_signal_handler = TerminationSignalHandler.new(
-          event_bus: self,
-          shutdown_timeout: shutdown_timeout,
-          signals: shutdown_signals,
-          on_signal: on_signal
-        )
-        @termination_signal_handler.install
-      end
+      @execution_strategy = RunningStrategy.new(self, sync: @sync)
+      @execution_strategy.start
+      install_signal_handlers(shutdown_timeout:, shutdown_signals:, on_signal:) if handle_signals
     end
 
     # Subscribe to a specific event class
@@ -82,30 +71,33 @@ module TCB
     end
 
     # Public for strategy access
-    def dispatch(event)
+    def dispatch(event_or_envelope)
       @mutex.synchronize { @active_dispatches += 1 }
+      envelope = TCB::Envelope.coerce(event_or_envelope)
 
       @events_processed_during_shutdown += 1 if shutdown?
-      handlers = @registry.handlers_for(event.class)
+      handlers = @registry.handlers_for(envelope.event.class)
 
       handlers.each do |handler|
-        execute_handler(handler, event)
+        execute_handler(handler, envelope)
       end
     ensure
       @mutex.synchronize { @active_dispatches -= 1 }
     end
 
+    def high_water_mark_reached? = @pressure_monitor.check?(@queue.size)
+
     private
 
-    def execute_handler(handler, event)
-      handler.call(event)
+    def execute_handler(handler, envelope)
+      handler.call(envelope)
     rescue => e
-      return if event.is_a?(SubscriberInvocationFailed)
+      return if envelope.event.is_a?(SubscriberInvocationFailed)
 
       failure_event = SubscriberInvocationFailed.build(
-        handler: handler,
-        original_event: event,
-        error: e
+        handler:        handler,
+        original_event: envelope.event,
+        error:          e
       )
 
       if shutdown?
@@ -114,5 +106,15 @@ module TCB
         publish(failure_event)
       end
     end
+
+    def install_signal_handlers(shutdown_timeout:, shutdown_signals:, on_signal:)
+      @termination_signal_handler = TerminationSignalHandler.new(
+        event_bus: self,
+        shutdown_timeout: shutdown_timeout,
+        signals: shutdown_signals,
+        on_signal: on_signal
+      )
+      @termination_signal_handler.install
+    end
   end
 end

data/lib/tcb/event_bus_queue_pressure.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module TCB
+  EventBusQueuePressure = Data.define(
+    :queue_size,      # current number of elements in queue
+    :max_queue_size,  # maximum queue capacity
+    :occupancy,       # queue_size / max_queue_size (float)
+    :occurred_at      # timestamp
+  )
+end

data/lib/tcb/event_store/active_record.rb

@@ -9,7 +9,7 @@ module TCB
         @mutex = Mutex.new
       end
 
-      def append(stream_id:, events:, occurred_at: Time.now)
+      def append(stream_id:, events:, occurred_at: Time.now, correlation_id: nil, causation_id: nil)
         @mutex.synchronize do
           next_ver = next_version(stream_id)
 
@@ -17,20 +17,24 @@ module TCB
             event_id = SecureRandom.uuid
 
             event_record_for(stream_id).create!(
-              event_id:    event_id,
-              stream_id:   stream_id,
-              version:     version,
-              event_type:  event.class.name,
-              payload:     serialize(event),
-              occurred_at: occurred_at
+              event_id:       event_id,
+              stream_id:      stream_id,
+              version:        version,
+              event_type:     event.class.name,
+              payload:        serialize(event),
+              occurred_at:    occurred_at,
+              correlation_id: correlation_id,
+              causation_id:   causation_id
             )
 
-            EventStreamEnvelope.new(
-              event:       event,
-              event_id:    event_id,
-              stream_id:   stream_id,
-              version:     version,
-              occurred_at: occurred_at
+            TCB::Envelope.new(
+              event:          event,
+              event_id:       event_id,
+              stream_id:      stream_id,
+              version:        version,
+              occurred_at:    occurred_at,
+              correlation_id: correlation_id,
+              causation_id:   causation_id
             )
           end
 
@@ -49,12 +53,51 @@ module TCB
         scope = scope.limit(limit) if limit
 
         scope.map do |record|
-          EventStreamEnvelope.new(
-            event:       deserialize(record.payload),
-            event_id:    record.event_id,
-            stream_id:   record.stream_id,
-            version:     record.version,
-            occurred_at: record.occurred_at
+          TCB::Envelope.new(
+            event:          deserialize(record.payload),
+            event_id:       record.event_id,
+            stream_id:      record.stream_id,
+            version:        record.version,
+            occurred_at:    record.occurred_at,
+            correlation_id: record.correlation_id,
+            causation_id:   record.causation_id
+          )
+        end
+      end
+
+      def read_by_correlation(correlation_id, context:, occurred_after: nil, occurred_before: nil)
+        tables = find_tables_for_context(context)
+        return [] if tables.empty?
+
+        union_sql = tables.map do |table|
+          conditions = ["correlation_id = ?"]
+          conditions << "occurred_at > ?" if occurred_after
+          conditions << "occurred_at < ?" if occurred_before
+
+          "SELECT * FROM #{table} WHERE #{conditions.join(' AND ')}"
+        end.join(" UNION ALL ")
+
+        bindings = tables.flat_map do
+          params = [correlation_id]
+          params << occurred_after  if occurred_after
+          params << occurred_before if occurred_before
+          params
+        end
+
+        sql = "#{union_sql} ORDER BY occurred_at ASC"
+        records = ::ActiveRecord::Base.connection.exec_query(
+          ::ActiveRecord::Base.sanitize_sql_array([sql, *bindings])
+        )
+
+        records.map do |record|
+          TCB::Envelope.new(
+            event:          deserialize(record["payload"]),
+            event_id:       record["event_id"],
+            stream_id:      record["stream_id"],
+            version:        record["version"],
+            occurred_at:    Time.parse(record["occurred_at"].to_s),
+            correlation_id: record["correlation_id"],
+            causation_id:   record["causation_id"]
           )
         end
       end
@@ -88,6 +131,13 @@ module TCB
       def permitted_classes
         TCB.config.permitted_serialization_classes
       end
+
+      def find_tables_for_context(context)
+        ::ActiveRecord::Base.connection.tables.select do |table|
+          table.start_with?(context.gsub("/", "__").gsub("::", "__")) &&
+            table.end_with?("_events")
+        end
+      end
     end
   end
 end

data/lib/tcb/event_store/in_memory.rb

@@ -10,15 +10,17 @@ module TCB
         @mutex = Mutex.new
       end
 
-      def append(stream_id:, events:, occurred_at: Time.now)
+      def append(stream_id:, events:, occurred_at: Time.now, correlation_id: nil, causation_id: nil)
         @mutex.synchronize do
           envelopes = events.map.with_index(next_version(stream_id)) do |event, version|
-            EventStreamEnvelope.new(
-              event: event,
-              event_id: SecureRandom.uuid,
-              stream_id: stream_id,
-              version: version,
-              occurred_at: occurred_at
+            Envelope.new(
+              event:          event,
+              event_id:       SecureRandom.uuid,
+              stream_id:      stream_id,
+              version:        version,
+              occurred_at:    occurred_at,
+              correlation_id: correlation_id,
+              causation_id:   causation_id
             )
           end
           @streams[stream_id].concat(envelopes)
@@ -35,6 +37,14 @@ module TCB
           .then { |e| limit          ? e.first(limit)                                      : e }
       end
 
+      def read_by_correlation(correlation_id, context:, occurred_after: nil, occurred_before: nil)
+        @mutex.synchronize { @streams.values.flatten.dup }
+          .select { |e| e.stream_id.start_with?(context) }
+          .select { |e| e.correlation_id == correlation_id }
+          .then { |e| occurred_after  ? e.select { |env| env.occurred_at > occurred_after }  : e }
+          .then { |e| occurred_before ? e.select { |env| env.occurred_at < occurred_before } : e }
+      end
+
       def reset!
         @mutex.synchronize do
           @streams = Hash.new { |h, k| h[k] = [] }

data/lib/tcb/publish.rb

@@ -1,6 +1,9 @@
 module TCB
-  def self.publish(*events)
-    events.each { |event| config.event_bus.publish(event) }
-    events
+  def self.publish(*events_or_envelopes)
+    events_or_envelopes.each do |e|
+      envelope = TCB::Envelope.coerce(e)
+      config.event_bus.publish(envelope)
+    end
+    events_or_envelopes
   end
-end
+end

data/lib/tcb/record.rb

@@ -4,19 +4,28 @@ module TCB
   class Record
     def self.call(events_from:, events:, within:, store:, registrations:, &block)
       raise ArgumentError, "events_from: or events: must be provided" if events_from.empty? && events.empty?
-      new(events_from: events_from, events: events, store: store, registrations: registrations)
-        .call(within: within, &block)
+
+      new(
+        events_from:    events_from,
+        events:         events,
+        store:          store,
+        registrations:  registrations,
+        correlation_id: Thread.current[:tcb_correlation_id],
+        causation_id:   Thread.current[:tcb_causation_id]
+      ).call(within: within, &block)
     end
 
-    def initialize(events_from:, events:, store:, registrations:)
-      @events_from = events_from
-      @events = events
-      @store = store
-      @registrations = registrations
+    def initialize(events_from:, events:, store:, registrations:, correlation_id: nil, causation_id: nil)
+      @events_from    = events_from
+      @events         = events
+      @store          = store
+      @registrations  = registrations
+      @correlation_id = correlation_id
+      @causation_id = causation_id
     end
 
     def call(within:, &block)
-      if within
+      if within.respond_to?(:transaction)
         within.transaction { execute(&block) }
       else
         execute(&block)
@@ -30,15 +39,21 @@ module TCB
       events  = @events_from.flat_map(&:pull_recorded_events)
       events += @events
       persist(events)
-      events
     rescue
       @events_from.each(&:pull_recorded_events)
       raise
     end
 
     def persist(events)
-      return unless @store
+      return events.map { |event| wrap(event) } unless @store
+
+      persisted = persist_to_store(events)
+      remaining = wrap_remaining(events, persisted)
 
+      order_by_original(events, persisted, remaining)
+    end
+
+    def persist_to_store(events)
       grouped = Hash.new { |h, k| h[k] = [] }
 
       events.each do |event|
@@ -49,7 +64,28 @@ module TCB
         grouped[stream_id.to_s] << event
       end
 
-      grouped.each { |stream_id, grouped_events| @store.append(stream_id: stream_id, events: grouped_events) }
+      grouped.flat_map do |stream_id, grouped_events|
+        @store.append(
+          stream_id:      stream_id,
+          events:         grouped_events,
+          correlation_id: @correlation_id,
+          causation_id:   @causation_id
+        )
+      end
+    end
+
+    def wrap_remaining(events, persisted)
+      persisted_events = persisted.map(&:event)
+      events
+        .reject { |event| persisted_events.include?(event) }
+        .map    { |event| wrap(event) }
+    end
+
+    def order_by_original(events, persisted, remaining)
+      all = persisted + remaining
+      events.map { |event| all.find { |e| e.event == event } }
     end
+
+    def wrap(event) = TCB::Envelope.wrap(event, correlation_id: @correlation_id, causation_id: @causation_id)
   end
 end

data/lib/tcb/test_helpers/shared.rb

@@ -15,8 +15,8 @@ module TCB
       def with_subscriptions(*event_classes)
         captured = Hash.new { |h, k| h[k] = [] }
         subscriptions = event_classes.map do |event_class|
-          TCB.config.event_bus.subscribe(event_class) do |event|
-            captured[event_class] << event
+          TCB.config.event_bus.subscribe(event_class) do |envelope|
+            captured[event_class] << (envelope.is_a?(TCB::Envelope) ? envelope.event : envelope)
           end
         end
         yield captured