tcb 0.5.0

data/lib/generators/tcb/domain/templates/command_handler.rb.tt

@@ -0,0 +1,11 @@
+module <%= module_class_name %>
+  class <%= current_command.handler_class_name %>
+    def call(command)
+<% if comments? %>
+      # Perform the side effect and publish an event when done.
+      # WelcomeMailer.with(email: command.email).deliver_later
+      # TCB.publish(WelcomeEmailSent.new(user_id: command.user_id))
+<% end %>
+    end
+  end
+end

data/lib/generators/tcb/domain/templates/domain_module.rb.tt

@@ -0,0 +1,34 @@
+module <%= module_class_name %>
+  include TCB::Domain
+<% if comments? %>
+
+  # Events — past tense, immutable facts from other domains or this module
+  # UserRegistered = Data.define(:user_id, :email)
+<% end %>
+<% parsed_commands.each do |cmd| %>
+
+  <%= cmd.command_class_name %> = Data.define(<%= cmd.attrs.map { |a| ":#{a}" }.join(", ") %>) do
+    def validate!
+<% cmd.attrs.each do |attr| %>
+      raise ArgumentError, "<%= attr %> is required" if <%= attr %>.nil?
+<% end %>
+    end
+  end
+<% end %>
+
+<% parsed_commands.each do |cmd| %>
+  handle <%= cmd.command_class_name %>, with(<%= cmd.handler_class_name %>)
+<% end %>
+<% if comments? %>
+
+  # Reactions — handlers are called asynchronously when events are published
+  # on EventClass, react_with(EventHandlerClass)
+<% end %>
+
+  # Facade
+<% parsed_commands.each do |cmd| %>
+  def self.<%= cmd.name %>(<%= cmd.attrs.map { |a| "#{a}:" }.join(", ") %>)
+    TCB.publish(<%= cmd.command_class_name %>.new(<%= cmd.attrs.map { |a| "#{a}: #{a}" }.join(", ") %>))
+  end
+<% end %>
+end

data/lib/generators/tcb/event_store/event_store_generator.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+require_relative "../shared/command_argument"
+
+module TCB
+  module Generators
+    class EventStoreGenerator < Rails::Generators::Base
+      namespace "TCB:event_store"
+      source_root File.expand_path("templates", __dir__)
+
+      argument :module_name, type: :string
+      argument :commands, type: :array, default: [], banner: "command:attr1,attr2"
+
+      class_option :skip_domain,    type: :boolean, default: false, desc: "Skip domain module generation"
+      class_option :skip_migration, type: :boolean, default: false, desc: "Skip migration generation"
+      class_option :no_comments,    type: :boolean, default: false, desc: "Generate without inline comments"
+
+      def create_domain_module
+        return if options[:skip_domain]
+        template "domain_module.rb.tt", "app/domain/#{module_name.underscore}.rb"
+      end
+
+      def create_handlers
+        return if options[:skip_domain]
+        parsed_commands.each do |cmd|
+          @current_command = cmd
+          template "command_handler.rb.tt", cmd.handler_file_path(module_name.underscore)
+        end
+      end
+
+      def create_migration
+        return if options[:skip_migration]
+        timestamp = Time.now.utc.strftime("%Y%m%d%H%M%S")
+        template "migration.rb.tt", "db/migrate/#{timestamp}_create_#{table_name}.rb"
+      end
+
+      private
+
+      def parsed_commands
+        @parsed_commands ||= CommandArgumentParser.parse(commands)
+      end
+
+      def module_class_name
+        module_name.camelize
+      end
+
+      def table_name
+        "#{module_name.underscore}_events"
+      end
+
+      def migration_class_name
+        "Create#{module_name.camelize}Events"
+      end
+
+      def comments?
+        !options[:no_comments]
+      end
+
+      def current_command
+        @current_command
+      end
+    end
+  end
+end

data/lib/generators/tcb/event_store/templates/command_handler.rb.tt

@@ -0,0 +1,18 @@
+module <%= module_class_name %>
+  class <%= current_command.handler_class_name %>
+    def call(command)
+<% if comments? %>
+      # 1. Load or build your aggregate
+      # order = Order.new(id: command.order_id)
+
+      # 2. TCB.record collects events and persists them within a transaction
+      # events = TCB.record(aggregates: [order], within: ApplicationRecord) do
+      #   order.place(...)
+      # end
+
+      # 3. TCB.publish dispatches events to subscribers
+      # TCB.publish(*events)
+<% end %>
+    end
+  end
+end

data/lib/generators/tcb/event_store/templates/domain_module.rb.tt

@@ -0,0 +1,44 @@
+module <%= module_class_name %>
+  include TCB::Domain
+<% if comments? %>
+
+  # Events — past tense, immutable facts
+  # OrderPlaced = Data.define(:order_id)
+<% end %>
+<% parsed_commands.each do |cmd| %>
+
+  <%= cmd.command_class_name %> = Data.define(<%= cmd.attrs.map { |a| ":#{a}" }.join(", ") %>) do
+    def validate!
+<% cmd.attrs.each do |attr| %>
+      raise ArgumentError, "<%= attr %> is required" if <%= attr %>.nil?
+<% end %>
+    end
+  end
+<% end %>
+<% if comments? %>
+
+  # Persistence — declare which events to store, and how to derive the stream id.
+  # Stream id is derived from an attribute on the event (stream_id_from_event:).
+  # Events are persisted by TCB.record in your command handlers (see below).
+  # persist events(
+  #   EventClass,
+  #   stream_id_from_event: :events_id_attribute
+  # )
+<% end %>
+
+<% parsed_commands.each do |cmd| %>
+  handle <%= cmd.command_class_name %>, with(<%= cmd.handler_class_name %>)
+<% end %>
+<% if comments? %>
+
+  # Reactions — handlers are called asynchronously when events are published
+  # on EventClass, react_with(EventHandlerClass)
+<% end %>
+
+  # Facade
+<% parsed_commands.each do |cmd| %>
+  def self.<%= cmd.name %>(<%= cmd.attrs.map { |a| "#{a}:" }.join(", ") %>)
+    TCB.dispatch(<%= cmd.command_class_name %>.new(<%= cmd.attrs.map { |a| "#{a}: #{a}" }.join(", ") %>))
+  end
+<% end %>
+end

data/lib/generators/tcb/event_store/templates/migration.rb.tt

@@ -0,0 +1,14 @@
+class <%= migration_class_name %> < ActiveRecord::Migration[8.0]
+  def change
+    create_table :<%= table_name %> do |t|
+      t.string   :event_id,    null: false
+      t.string   :stream_id,   null: false
+      t.integer  :version,     null: false
+      t.string   :event_type,  null: false
+      t.text     :payload,     null: false
+      t.datetime :occurred_at, null: false
+    end
+
+    add_index :<%= table_name %>, [:stream_id, :version], unique: true
+  end
+end

data/lib/generators/tcb/install/install_generator.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module TCB
+  module Generators
+    class InstallGenerator < Rails::Generators::Base
+      namespace "TCB:install"
+      source_root File.expand_path("templates", __dir__)
+
+      desc "Creates a TCB initializer in config/initializers"
+
+      def create_initializer
+        template "tcb.rb.tt", "config/initializers/tcb.rb"
+      end
+    end
+  end
+end

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

@@ -0,0 +1,18 @@
+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
+    ]
+  end
+end

data/lib/generators/tcb/shared/command_argument.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module TCB
+  module Generators
+    CommandArgument = Data.define(:name, :attrs) do
+      def command_class_name
+        camelize(name)
+      end
+
+      def handler_class_name
+        "#{camelize(name)}Handler"
+      end
+
+      def handler_file_name
+        "#{name}_handler"
+      end
+
+      def handler_file_path(module_name)
+        "app/domain/#{module_name}/#{handler_file_name}.rb"
+      end
+
+      private
+
+      def camelize(str)
+        str.split("_").map(&:capitalize).join
+      end
+    end
+
+    class CommandArgumentParser
+      def self.parse(args)
+        args.map do |arg|
+          name, attrs_str = arg.split(":", 2)
+          attrs = attrs_str ? attrs_str.split(",").map(&:to_sym) : []
+          CommandArgument.new(name: name, attrs: attrs)
+        end
+      end
+    end
+  end
+end

data/lib/tcb/command_bus.rb

@@ -0,0 +1,26 @@
+
+module TCB
+  CommandHandlerNotFound = Class.new(StandardError)
+
+  def self.dispatch(command)
+    validate!(command)
+    handler = resolve_handler(command)
+    handler.new.call(command)
+  end
+
+  def self.validate!(command)
+    unless command.respond_to?(:validate!)
+      raise NotImplementedError, "#{command.class} must implement validate!"
+    end
+    command.validate!
+  end
+  private_class_method :validate!
+
+  def self.resolve_handler(command)
+    handler = config.command_handler(command.class)
+    raise CommandHandlerNotFound, "No handler registered for #{command.class.name}" unless handler
+
+    handler
+  end
+  private_class_method :resolve_handler
+end

data/lib/tcb/configuration.rb

@@ -0,0 +1,118 @@
+module TCB
+  ConfigurationError = Class.new(StandardError)
+
+  class Configuration
+    def initialize
+      @persist_registrations = []
+    end
+
+    def persist_registrations
+      @persist_registrations
+    end
+
+    def event_bus=(bus)
+      @event_bus = bus
+    end
+
+    def event_bus
+      @event_bus ||
+        raise(
+          ConfigurationError,
+          "TCB event_bus is not configured. Call TCB.configure { |c| c.event_bus = TCB::EventBus.new }"
+        )
+    end
+
+    def event_store=(store)
+      @event_store = store
+    end
+
+    def event_store
+      @event_store
+    end
+
+    def domain_modules=(modules)
+      @domain_modules = modules
+      flush_domain_modules
+      flush_command_handlers
+      flush_persist_registrations
+    end
+
+    def domain_modules
+      @domain_modules || []
+    end
+
+    def command_handler(command_class)
+      @command_handlers ||= {}
+      @command_handlers[command_class]
+    end
+
+    def extra_serialization_classes=(classes)
+      @extra_serialization_classes = classes
+    end
+
+    def extra_serialization_classes
+      @extra_serialization_classes || []
+    end
+
+    def permitted_serialization_classes
+      @permitted_serialization_classes ||= [
+        Symbol, Time, Date, BigDecimal,
+        *persist_registrations.flat_map(&:event_classes),
+        *extra_serialization_classes
+      ]
+    end
+
+    private
+
+    def flush_domain_modules
+      @domain_modules.each do |domain_module|
+        next unless domain_module.respond_to?(:event_handler_registrations)
+
+        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)
+            end
+          end
+        end
+      end
+    end
+
+    def flush_command_handlers
+      @command_handlers = {}
+      @domain_modules.each do |domain_module|
+        next unless domain_module.respond_to?(:command_handler_registrations)
+
+        domain_module.command_handler_registrations.each do |reg|
+          @command_handlers[reg.command_class] = reg.handler
+        end
+      end
+    end
+
+    def flush_persist_registrations
+      @persist_registrations = []
+      @domain_modules.each do |domain_module|
+        next unless domain_module.respond_to?(:persist_registrations)
+
+        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?
+      end
+    end
+
+    def define_event_record_for(domain_module)
+      return if domain_module.const_defined?(:EventRecord, false)
+
+      klass = Class.new(::ActiveRecord::Base) do
+        self.table_name = DomainContext.from_module(domain_module).table_name
+      end
+      domain_module.const_set(:EventRecord, klass)
+    end
+  end
+
+  def self.config
+    @config ||= Configuration.new
+  end
+end

data/lib/tcb/domain.rb

@@ -0,0 +1,8 @@
+module TCB
+  module Domain
+    def self.included(base)
+      base.include(HandlesEvents)
+      base.include(HandlesCommands)
+    end
+  end
+end

data/lib/tcb/domain_context.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module TCB
+  class DomainContext < Data.define(:value)
+    NAMESPACE_SEPARATOR = "/"
+    TABLE_SEPARATOR     = "__"
+    TABLE_SUFFIX        = "_events"
+
+    def self.from_module(domain_module)
+      value = domain_module.name
+        .gsub("::", NAMESPACE_SEPARATOR)
+        .gsub(/([A-Z]+)([A-Z][a-z])/, '\1_\2')
+        .gsub(/([a-z\d])([A-Z])/, '\1_\2')
+        .downcase
+
+      new(value: value)
+    end
+
+    def to_s
+      value
+    end
+
+    def table_name
+      value
+        .gsub(NAMESPACE_SEPARATOR, TABLE_SEPARATOR)
+        .concat(TABLE_SUFFIX)
+    end
+  end
+end

data/lib/tcb/event_bus/running_strategy.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module TCB
+  class EventBus
+    class RunningStrategy
+      def initialize(event_bus)
+        @event_bus = event_bus
+      end
+
+      def publish(event)
+        @event_bus.queue << event
+        event
+      end
+
+      def subscribe(event_class, &block)
+        @event_bus.registry.add(event_class, block)
+      end
+
+      def shutdown?
+        false
+      end
+    end
+  end
+end

data/lib/tcb/event_bus/shutdown_strategy.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+module TCB
+  class EventBus
+    class ShutdownStrategy
+      def initialize(event_bus:, drain:, timeout:)
+        @event_bus = event_bus
+        @drain = drain
+        @timeout = timeout
+        @start_time = Time.now
+      end
+
+      def publish(event)
+        raise ShutdownError, "Cannot publish events after shutdown"
+      end
+
+      def subscribe(event_class, &block)
+        raise ShutdownError, "Cannot subscribe after shutdown"
+      end
+
+      def shutdown?
+        true
+      end
+
+      def execute
+        emit_shutdown_event(:initiated)
+
+        if @drain
+          drain_with_timeout
+        else
+          force_terminate
+        end
+      end
+
+      private
+
+      def drain_with_timeout
+        deadline = @start_time + @timeout
+
+        # Wait for queue to drain AND all active dispatches to complete
+        loop do
+          queue_empty = @event_bus.queue.size == 0
+          active_work = @event_bus.mutex.synchronize { @event_bus.active_dispatches }
+
+          if queue_empty && active_work == 0
+            # All work complete
+            terminate_dispatcher
+            emit_shutdown_event(:completed)
+            return
+          end
+
+          if Time.now >= deadline
+            # Timeout exceeded, force shutdown
+            force_terminate
+            emit_shutdown_event(:timeout_exceeded)
+            return
+          end
+
+          sleep 0.01 # Small poll interval
+        end
+      end
+
+      def force_terminate
+        @event_bus.queue << :shutdown_sentinel
+        @event_bus.dispatcher.kill if @event_bus.dispatcher.alive?
+        @event_bus.dispatcher.join(0.1)
+      end
+
+      def terminate_dispatcher
+        @event_bus.queue << :shutdown_sentinel
+        @event_bus.dispatcher.join(0.5)
+      end
+
+      def emit_shutdown_event(status)
+        shutdown_event = EventBusShutdown.new(
+          status: status,
+          drain_requested: @drain,
+          timeout_seconds: @timeout,
+          events_drained: @event_bus.events_processed_during_shutdown,
+          occurred_at: Time.now
+        )
+
+        # Dispatch directly, bypassing queue
+        @event_bus.dispatch(shutdown_event)
+      end
+    end
+  end
+end

data/lib/tcb/event_bus/subscriber_registry.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module TCB
+  class EventBus
+    class SubscriberRegistry
+      Subscription = Data.define(:event_class, :handler)
+
+      def initialize
+        @subscribers = Hash.new { |h, k| h[k] = Set.new }
+        @metadata = {}
+        @mutex = Mutex.new
+      end
+
+      def add(event_class, handler)
+        subscription = Subscription.new(event_class: event_class, handler: handler)
+        @mutex.synchronize do
+          @subscribers[event_class].add(handler)
+          @metadata[handler.object_id] = SubscriberMetadataExtractor.new(handler).extract
+        end
+        subscription
+      end
+
+      def remove(subscription)
+        @mutex.synchronize do
+          @subscribers[subscription.event_class].delete(subscription.handler)
+          @metadata.delete(subscription.handler.object_id)
+        end
+      end
+
+      def handlers_for(event_class)
+        @mutex.synchronize { @subscribers[event_class].dup.freeze }
+      end
+
+      def metadata_for(subscription)
+        @mutex.synchronize { @metadata[subscription.handler.object_id] }
+      end
+
+      def clear
+        @mutex.synchronize do
+          @subscribers.clear
+          @metadata.clear
+        end
+      end
+    end
+  end
+end

data/lib/tcb/event_bus/termination_signal_handler.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module TCB
+  class EventBus
+    class TerminationSignalHandler
+      def initialize(event_bus:, shutdown_timeout:, signals:, on_signal:)
+        @event_bus = event_bus
+        @shutdown_timeout = shutdown_timeout
+        @signals = signals
+        @on_signal = on_signal
+        @shutdown_thread = nil
+        @original_handlers = {}
+      end
+
+      def install
+        @signals.each do |sig|
+          @original_handlers[sig] = Signal.trap(sig) { handle_signal(sig) }
+        end
+      end
+
+      private
+
+      def handle_signal(sig)
+        if shutdown_in_progress?
+          handle_force_shutdown(sig)
+        else
+          handle_graceful_shutdown(sig)
+        end
+      end
+
+      def shutdown_in_progress?
+        @shutdown_thread&.alive?
+      end
+
+      def handle_graceful_shutdown(sig)
+        @shutdown_thread = Thread.new do
+          @on_signal&.call(sig) if @on_signal
+          @event_bus.shutdown(drain: true, timeout: @shutdown_timeout)
+          restore_and_reraise(sig)
+        end
+      end
+
+      def handle_force_shutdown(sig)
+        @shutdown_thread.kill
+        @event_bus.force_shutdown
+        restore_and_reraise(sig)
+      end
+
+      def restore_and_reraise(sig)
+        Signal.trap(sig, @original_handlers[sig])
+        Process.kill(sig, Process.pid)
+      end
+    end
+  end
+end