tcb 0.5.0

data/lib/tcb/event_bus.rb

@@ -0,0 +1,118 @@
+# 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'
+
+module TCB
+  class EventBus
+    class ShutdownError < StandardError; end
+
+    attr_reader :queue, :registry, :mutex,
+                :active_dispatches, :dispatcher, :events_processed_during_shutdown
+
+    def initialize(
+      handle_signals: false,
+      shutdown_timeout: 30.0,
+      shutdown_signals: [:TERM, :INT],
+      on_signal: nil
+    )
+      @queue = Queue.new
+      @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
+    end
+
+    # Subscribe to a specific event class
+    def subscribe(event_class, &block)
+      @execution_strategy.subscribe(event_class, &block)
+    end
+
+    # Unsubscribe using a subscription token
+    def unsubscribe(subscription)
+      @registry.remove(subscription)
+    end
+
+    # Publish an event instance
+    def publish(event)
+      @execution_strategy.publish(event)
+    end
+
+    # Graceful shutdown - drains queue with timeout
+    def shutdown(drain: true, timeout: 5.0)
+      @execution_strategy = ShutdownStrategy.new(
+        event_bus: self,
+        drain: drain,
+        timeout: timeout
+      )
+      @execution_strategy.execute
+    end
+
+    # Force shutdown - immediate, no draining
+    def force_shutdown
+      shutdown(drain: false, timeout: 0)
+    end
+
+    # Check if bus is shut down
+    def shutdown?
+      @execution_strategy.shutdown?
+    end
+
+    # Public for strategy access
+    def dispatch(event)
+      @mutex.synchronize { @active_dispatches += 1 }
+
+      @events_processed_during_shutdown += 1 if shutdown?
+      handlers = @registry.handlers_for(event.class)
+
+      handlers.each do |handler|
+        execute_handler(handler, event)
+      end
+    ensure
+      @mutex.synchronize { @active_dispatches -= 1 }
+    end
+
+    private
+
+    def execute_handler(handler, event)
+      handler.call(event)
+    rescue => e
+      return if event.is_a?(SubscriberInvocationFailed)
+
+      failure_event = SubscriberInvocationFailed.build(
+        handler: handler,
+        original_event: event,
+        error: e
+      )
+
+      if shutdown?
+        dispatch(failure_event)
+      else
+        publish(failure_event)
+      end
+    end
+  end
+end

data/lib/tcb/event_bus_shutdown.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module TCB
+  EventBusShutdown = Data.define(
+    :status,           # :initiated, :completed, :timeout_exceeded
+    :drain_requested,  # true/false - was drain requested?
+    :timeout_seconds,  # timeout value used
+    :events_drained,   # number of events processed during shutdown
+    :occurred_at       # timestamp
+  )
+end

data/lib/tcb/event_query.rb

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+module TCB
+  class EventQuery
+    def initialize(store:, context:, stream_id: nil, from_version: nil, to_version: nil, occurred_after: nil)
+      @store = store
+      @context = context
+      @stream_id = stream_id
+      @from_version = from_version
+      @to_version = to_version
+      @occurred_after = occurred_after
+    end
+
+    def stream(aggregate_id)
+      self.class.new(
+        store: @store,
+        context: @context,
+        stream_id: StreamId.build(@context, aggregate_id).to_s,
+        from_version: @from_version,
+        to_version: @to_version,
+        occurred_after: @occurred_after
+      )
+    end
+
+    def from_version(version)
+      self.class.new(
+        store: @store,
+        context: @context,
+        stream_id: @stream_id,
+        from_version: version,
+        to_version: @to_version,
+        occurred_after: @occurred_after
+      )
+    end
+
+    def to_version(version)
+      self.class.new(
+        store: @store,
+        context: @context,
+        stream_id: @stream_id,
+        from_version: @from_version,
+        to_version: version,
+        occurred_after: @occurred_after
+      )
+    end
+
+    def between_versions(from, to)
+      from_version(from).to_version(to)
+    end
+
+    def occurred_after(time)
+      self.class.new(
+        store: @store,
+        context: @context,
+        stream_id: @stream_id,
+        from_version: @from_version,
+        to_version: @to_version,
+        occurred_after: time
+      )
+    end
+
+    def last(count)
+      return [] unless @stream_id
+
+      result = @store.read(
+        @stream_id,
+        from_version: @from_version,
+        to_version: @to_version,
+        occurred_after: @occurred_after,
+        limit: count,
+        order: :desc
+      )
+      result.reverse
+    end
+
+    def in_batches(of: 1000, from_version: nil, to_version: nil)
+      return enum_for(:in_batches, of: of, from_version: from_version, to_version: to_version) unless block_given?
+
+      cursor = from_version || @from_version
+      ceiling = to_version || @to_version
+
+      loop do
+        batch = @store.read(
+          @stream_id,
+          from_version: cursor,
+          to_version: ceiling,
+          occurred_after: @occurred_after,
+          limit: of
+        )
+
+        break if batch.empty?
+
+        yield batch
+
+        break if batch.size < of
+
+        cursor = batch.last.version + 1
+      end
+    end
+
+    def to_a
+      result = []
+      in_batches { |batch| result.push(*batch) }
+      result
+    end
+  end
+end

data/lib/tcb/event_store/active_record.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+require "securerandom"
+
+module TCB
+  class EventStore
+    class ActiveRecord
+      def initialize
+        @mutex = Mutex.new
+      end
+
+      def append(stream_id:, events:, occurred_at: Time.now)
+        @mutex.synchronize do
+          next_ver = next_version(stream_id)
+
+          envelopes = events.map.with_index(next_ver) do |event, version|
+            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
+            )
+
+            EventStreamEnvelope.new(
+              event:       event,
+              event_id:    event_id,
+              stream_id:   stream_id,
+              version:     version,
+              occurred_at: occurred_at
+            )
+          end
+
+          envelopes
+        end
+      end
+
+      def read(stream_id, from_version: nil, to_version: nil, occurred_after: nil, limit: nil, order: :asc)
+        scope = event_record_for(stream_id)
+          .where(stream_id: stream_id)
+          .order(version: order)
+
+        scope = scope.where("version >= ?", from_version) if from_version
+        scope = scope.where("version <= ?", to_version) if to_version
+        scope = scope.where("occurred_at > ?", occurred_after) if occurred_after
+        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
+          )
+        end
+      end
+
+      private
+
+      def next_version(stream_id)
+        event_record_for(stream_id)
+          .where(stream_id: stream_id)
+          .maximum(:version)
+          .to_i + 1
+      end
+
+      def event_record_for(stream_id)
+        context = stream_id.split("|").first
+        module_name = context
+          .split("/")
+          .map { |part| part.split("_").map(&:capitalize).join }
+          .join("::")
+        Object.const_get("#{module_name}::EventRecord")
+      end
+
+      def serialize(event)
+        YAML.dump(event)
+      end
+
+      def deserialize(payload)
+        YAML.safe_load(payload, permitted_classes: permitted_classes, aliases: true)
+      end
+
+      def permitted_classes
+        TCB.config.permitted_serialization_classes
+      end
+    end
+  end
+end

data/lib/tcb/event_store/event_stream_envelope.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module TCB
+  class EventStore
+    EventStreamEnvelope = Data.define(
+      :event,
+      :event_id,
+      :stream_id,
+      :version,
+      :occurred_at
+    )
+  end
+end

data/lib/tcb/event_store/in_memory.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+require "securerandom"
+
+module TCB
+  class EventStore
+    class InMemory
+      def initialize
+        @streams = Hash.new { |h, k| h[k] = [] }
+        @mutex = Mutex.new
+      end
+
+      def append(stream_id:, events:, occurred_at: Time.now)
+        @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
+            )
+          end
+          @streams[stream_id].concat(envelopes)
+          envelopes
+        end
+      end
+
+      def read(stream_id, from_version: nil, to_version: nil, occurred_after: nil, limit: nil, order: :asc)
+        @mutex.synchronize { @streams[stream_id].dup }
+          .then { |e| from_version   ? e.select { |env| env.version >= from_version }      : e }
+          .then { |e| to_version     ? e.select { |env| env.version <= to_version }        : e }
+          .then { |e| occurred_after ? e.select { |env| env.occurred_at > occurred_after } : e }
+          .then { |e| order == :desc ? e.reverse                                           : e }
+          .then { |e| limit          ? e.first(limit)                                      : e }
+      end
+
+      def reset!
+        @mutex.synchronize do
+          @streams = Hash.new { |h, k| h[k] = [] }
+        end
+      end
+
+      private
+
+      def next_version(stream_id)
+        @streams[stream_id].size + 1
+      end
+    end
+  end
+end

data/lib/tcb/handles_commands.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module TCB
+  module HandlesCommands
+    CommandHandlerRegistration = Data.define(:command_class, :handler)
+
+    def self.included(base)
+      base.extend(ClassMethods)
+      base.instance_variable_set(:@command_handler_registrations, [])
+    end
+
+    module ClassMethods
+      def handle(command_class, handler)
+        @command_handler_registrations << CommandHandlerRegistration.new(
+          command_class: command_class,
+          handler: handler
+        )
+      end
+
+      def with(*handlers)
+        raise ArgumentError, "command accepts exactly one handler" unless handlers.compact.size == 1
+
+        handlers.first
+      end
+
+      def command_handler_registrations
+        @command_handler_registrations
+      end
+    end
+  end
+end

data/lib/tcb/handles_events.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module TCB
+  module HandlesEvents
+    EventHandlerRegistration = Data.define(:event_class, :handlers)
+    PersistRegistration = Data.define(:event_classes, :stream_id_from_event, :context)
+
+    def self.included(base)
+      base.extend(ClassMethods)
+      base.instance_variable_set(:@event_handler_registrations, [])
+      base.instance_variable_set(:@persist_registrations, [])
+    end
+
+    module ClassMethods
+      def react_with(*handlers)
+        EventHandlerRegistration.new(event_class: :undefined, handlers: handlers)
+      end
+
+      def on(event_class, registration)
+        @event_handler_registrations << registration.with(event_class: event_class)
+      end
+
+      def persist(registration)
+        @persist_registrations << registration
+      end
+
+      def events(*event_classes, stream_id_from_event:)
+        PersistRegistration.new(
+          event_classes: event_classes,
+          stream_id_from_event: stream_id_from_event,
+          context: nil
+        )
+      end
+
+      def event_handler_registrations
+        @event_handler_registrations
+      end
+
+      def persist_registrations
+        @persist_registrations
+      end
+    end
+  end
+end

data/lib/tcb/minitest_helpers.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require_relative "test_helpers/shared"
+
+module TCB
+  module MinitestHelpers
+    include TestHelpers::Shared
+
+    def assert_published(*expected, within: 1.0, &block)
+      event_classes = expected.map { |arg| arg.is_a?(Class) ? arg : arg.class }.uniq
+
+      with_subscriptions(*event_classes) do |captured|
+        block.call
+
+        expected.each do |arg|
+          if arg.is_a?(Class)
+            met = poll_until(within: within) { captured[arg].any? }
+            raise Minitest::Assertion, "Expected #{arg} to be published, but it was not" unless met
+          else
+            event_class = arg.class
+            met = poll_until(within: within) { captured[event_class].any? { |e| e == arg } }
+            raise Minitest::Assertion, "Expected #{arg.inspect} to be published, but it was not" unless met
+          end
+        end
+      end
+    end
+
+    def poll_assert(message = nil, within: 1.0, interval: 0.001, &block)
+      met = poll_until(within: within, interval: interval, &block)
+      return if met
+
+      failure_message = "Condition not met within #{within}s"
+      failure_message += ": \"#{message}\"" if message
+      raise Minitest::Assertion, failure_message
+    end
+  end
+end

data/lib/tcb/publish.rb

@@ -0,0 +1,6 @@
+module TCB
+  def self.publish(*events)
+    events.each { |event| config.event_bus.publish(event) }
+    events
+  end
+end

data/lib/tcb/record.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+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)
+    end
+
+    def initialize(events_from:, events:, store:, registrations:)
+      @events_from = events_from
+      @events = events
+      @store = store
+      @registrations = registrations
+    end
+
+    def call(within:, &block)
+      if within
+        within.transaction { execute(&block) }
+      else
+        execute(&block)
+      end
+    end
+
+    private
+
+    def execute(&block)
+      block.call if block
+      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
+
+      grouped = Hash.new { |h, k| h[k] = [] }
+
+      events.each do |event|
+        registration = @registrations.find { |r| r.event_classes.include?(event.class) }
+        next unless registration
+
+        stream_id = StreamId.build(registration.context, event.public_send(registration.stream_id_from_event))
+        grouped[stream_id.to_s] << event
+      end
+
+      grouped.each { |stream_id, grouped_events| @store.append(stream_id: stream_id, events: grouped_events) }
+    end
+  end
+end

data/lib/tcb/records_events.rb

@@ -0,0 +1,23 @@
+module TCB
+  module RecordsEvents
+    def record(event)
+      recorded_events_array << event
+    end
+
+    def recorded_events
+      recorded_events_array.dup
+    end
+
+    def pull_recorded_events
+      events = recorded_events_array.dup
+      recorded_events_array.clear
+      events
+    end
+
+    private
+
+    def recorded_events_array
+      @recorded_events ||= []
+    end
+  end
+end

data/lib/tcb/rspec_helpers.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+require_relative "test_helpers/shared"
+
+module TCB
+  module RSpecHelpers
+    include TestHelpers::Shared
+
+    def self.included(base)
+      base.extend(Matchers)
+    end
+
+    module Matchers
+    end
+
+    RSpec::Matchers.define :have_published do |*expected, within: 1.0|
+      match do |block|
+        event_classes = expected.map { |arg| arg.is_a?(Class) ? arg : arg.class }.uniq
+        @missed = []
+
+        helper = Object.new.extend(TCB::TestHelpers::Shared)
+
+        helper.with_subscriptions(*event_classes) do |captured|
+          block.call
+
+          expected.each do |arg|
+            if arg.is_a?(Class)
+              met = helper.poll_until(within: within) { captured[arg].any? }
+              @missed << arg unless met
+            else
+              event_class = arg.class
+              met = helper.poll_until(within: within) { captured[event_class].any? { |e| e == arg } }
+              @missed << arg unless met
+            end
+          end
+        end
+
+        @missed.empty?
+      end
+
+      failure_message do
+        @missed.map { |arg| "Expected #{arg.inspect} to be published, but it was not" }.join("\n")
+      end
+
+      supports_block_expectations
+    end
+
+    RSpec::Matchers.define :poll_match do |within: 1.0, interval: 0.001|
+      match do |block|
+        helper = Object.new.extend(TCB::TestHelpers::Shared)
+        helper.poll_until(within: within, interval: interval) { block.call }
+      end
+
+      failure_message do
+        "Condition not met within #{within}s"
+      end
+
+      supports_block_expectations
+    end
+  end
+end

data/lib/tcb/stream_id.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module TCB
+  class StreamId < Data.define(:context, :id)
+    SEPARATOR = "|"
+    NAMESPACE_SEPARATOR = "/"
+
+    class << self
+      def build(context, id)
+        new(context: context.to_s.downcase, id: id.to_s)
+      end
+
+      def context_from_module(mod)
+        DomainContext.from_module(mod).to_s
+      end
+
+      def parse(string)
+        string = string.to_s
+        parts = string.split(SEPARATOR, 2)
+
+        if parts.size != 2 || parts.any?(&:empty?)
+          raise ArgumentError, "Invalid StreamId format: #{string.inspect}. Expected \"context#{SEPARATOR}id\""
+        end
+
+        new(context: parts[0], id: parts[1])
+      end
+    end
+
+    def to_s
+      "#{context}#{SEPARATOR}#{id}"
+    end
+  end
+end