smart_domain 0.1.0

data/lib/smart_domain/domain/policy.rb

@@ -0,0 +1,215 @@
+# frozen_string_literal: true
+
+module SmartDomain
+  module Domain
+    # Base class for domain policies (authorization).
+    #
+    # Policies encapsulate authorization logic for domain operations.
+    # They follow the Pundit-style pattern but are domain-centric.
+    #
+    # Key principles:
+    # - Policies are stateless (except for user and record context)
+    # - Policies answer "can this user perform this action on this record?"
+    # - Policies can be used in services, controllers, and views
+    # - Policies are domain-specific (UserPolicy, OrderPolicy, etc.)
+    #
+    # @example Define a policy
+    #   class UserPolicy < SmartDomain::Domain::Policy
+    #     def create?
+    #       user.admin? || user.manager?
+    #     end
+    #
+    #     def update?
+    #       user.admin? || user.id == record.id
+    #     end
+    #
+    #     def delete?
+    #       user.admin? && record.id != user.id
+    #     end
+    #
+    #     def activate?
+    #       user.admin? && record.pending?
+    #     end
+    #   end
+    #
+    # @example Use in a service
+    #   class UserService < SmartDomain::Domain::Service
+    #     def activate_user(user_id)
+    #       user = User.find(user_id)
+    #       policy = UserPolicy.new(current_user, user)
+    #
+    #       authorize!(policy, :activate?)
+    #
+    #       user.update!(status: 'active')
+    #       # ... publish event ...
+    #     end
+    #   end
+    class Policy
+      attr_reader :user, :record
+
+      # Initialize policy
+      #
+      # @param user [Object] User performing the action (current_user)
+      # @param record [Object] Record being operated on
+      def initialize(user, record)
+        @user = user
+        @record = record
+      end
+
+      # Check if user can perform index action
+      # Override in subclass
+      # @return [Boolean]
+      def index?
+        false
+      end
+
+      # Check if user can perform show action
+      # Override in subclass
+      # @return [Boolean]
+      def show?
+        false
+      end
+
+      # Check if user can perform create action
+      # Override in subclass
+      # @return [Boolean]
+      def create?
+        false
+      end
+
+      # Check if user can perform update action
+      # Override in subclass
+      # @return [Boolean]
+      def update?
+        false
+      end
+
+      # Check if user can perform destroy action
+      # Override in subclass
+      # @return [Boolean]
+      def destroy?
+        false
+      end
+
+      # Scope for index queries
+      #
+      # Override in subclass to return a scope of records
+      # the user can access.
+      #
+      # @param scope [ActiveRecord::Relation] Initial scope
+      # @return [ActiveRecord::Relation] Filtered scope
+      #
+      # @example
+      #   class UserPolicy < SmartDomain::Domain::Policy
+      #     class Scope
+      #       attr_reader :user, :scope
+      #
+      #       def initialize(user, scope)
+      #         @user = user
+      #         @scope = scope
+      #       end
+      #
+      #       def resolve
+      #         if user.admin?
+      #           scope.all
+      #         else
+      #           scope.where(organization_id: user.organization_id)
+      #         end
+      #       end
+      #     end
+      #   end
+      class Scope
+        attr_reader :user, :scope
+
+        def initialize(user, scope)
+          @user = user
+          @scope = scope
+        end
+
+        # Resolve scope based on user permissions
+        # Override in subclass
+        # @return [ActiveRecord::Relation]
+        def resolve
+          scope.none
+        end
+      end
+
+      # Helper method to check if user is present
+      # @return [Boolean]
+      def user_present?
+        !user.nil?
+      end
+
+      # Helper method to check if user is admin
+      # Override in subclass based on your user model
+      # @return [Boolean]
+      def admin?
+        user_present? && user.respond_to?(:admin?) && user.admin?
+      end
+
+      # Helper method to check if user owns the record
+      # @return [Boolean]
+      def owner?
+        user_present? && record.respond_to?(:user_id) && record.user_id == user.id
+      end
+
+      # Helper method to check if user is in same organization
+      # @return [Boolean]
+      def same_organization?
+        user_present? &&
+          record.respond_to?(:organization_id) &&
+          user.respond_to?(:organization_id) &&
+          record.organization_id == user.organization_id
+      end
+    end
+
+    # Authorization helper methods for services
+    module PolicyHelpers
+      # Authorize an action or raise an error
+      #
+      # @param policy [SmartDomain::Domain::Policy] Policy instance
+      # @param action [Symbol] Action to authorize (e.g., :create?, :update?)
+      # @raise [SmartDomain::Domain::UnauthorizedError] If not authorized
+      #
+      # @example
+      #   policy = UserPolicy.new(current_user, user)
+      #   authorize!(policy, :update?)
+      def authorize!(policy, action)
+        return if policy.public_send(action)
+
+        raise SmartDomain::Domain::UnauthorizedError.new(
+          "Not authorized to perform #{action} on #{policy.record.class.name}",
+          action: action,
+          resource: policy.record.class.name
+        )
+      end
+
+      # Check if action is authorized
+      #
+      # @param policy [SmartDomain::Domain::Policy] Policy instance
+      # @param action [Symbol] Action to check
+      # @return [Boolean] True if authorized
+      #
+      # @example
+      #   policy = UserPolicy.new(current_user, user)
+      #   if authorized?(policy, :update?)
+      #     # perform update
+      #   end
+      def authorized?(policy, action)
+        policy.public_send(action)
+      end
+
+      # Get scoped records based on user permissions
+      #
+      # @param scope [ActiveRecord::Relation] Initial scope
+      # @param policy_class [Class] Policy class
+      # @return [ActiveRecord::Relation] Filtered scope
+      #
+      # @example
+      #   users = policy_scope(User.all, UserPolicy)
+      def policy_scope(scope, policy_class)
+        policy_class::Scope.new(current_user, scope).resolve
+      end
+    end
+  end
+end

data/lib/smart_domain/domain/service.rb

@@ -0,0 +1,230 @@
+# frozen_string_literal: true
+
+module SmartDomain
+  module Domain
+    # Base class for domain services.
+    #
+    # Domain services contain business logic that doesn't naturally fit
+    # within a single entity. They orchestrate operations across multiple
+    # entities and publish domain events.
+    #
+    # Key principles:
+    # - Services own business logic, not controllers
+    # - Services publish events after successful operations
+    # - Services use transactions for data consistency
+    # - Services are stateless (except for injected context)
+    #
+    # @example Define a domain service
+    #   class UserService < SmartDomain::Domain::Service
+    #     def create_user(attributes)
+    #       User.transaction do
+    #         user = User.create!(attributes)
+    #
+    #         event = UserCreatedEvent.new(
+    #           event_type: 'user.created',
+    #           aggregate_id: user.id,
+    #           aggregate_type: 'User',
+    #           organization_id: current_organization_id,
+    #           user_id: user.id,
+    #           email: user.email
+    #         )
+    #
+    #         publish_after_commit(event)
+    #         user
+    #       end
+    #     end
+    #   end
+    #
+    # @example Use the service in a controller
+    #   class UsersController < ApplicationController
+    #     def create
+    #       service = UserService.new(
+    #         current_user: current_user,
+    #         organization_id: current_organization.id
+    #       )
+    #       @user = service.create_user(user_params)
+    #       redirect_to @user, notice: 'User created successfully'
+    #     end
+    #   end
+    class Service
+      include PolicyHelpers
+
+      attr_reader :current_user, :current_user_id, :current_organization_id, :logger
+
+      # Initialize service with context
+      #
+      # @param current_user [Object, nil] Current user performing the action
+      # @param current_user_id [String, Integer, nil] Current user ID
+      # @param organization_id [String, Integer, nil] Organization/tenant ID
+      # @param logger [Logger, nil] Logger instance (defaults to Rails.logger)
+      def initialize(current_user: nil, current_user_id: nil, organization_id: nil, logger: nil)
+        @current_user = current_user
+        @current_user_id = current_user_id || current_user&.id
+        @current_organization_id = organization_id || current_user&.organization_id
+        @logger = logger || (defined?(Rails) ? Rails.logger : Logger.new($stdout))
+        @pending_events = []
+      end
+
+      # Publish event after the current transaction commits
+      #
+      # This ensures events are only published if the database transaction
+      # succeeds. If the transaction rolls back, events are discarded.
+      #
+      # @param event [SmartDomain::Event::Base] Event to publish
+      #
+      # @example
+      #   def create_user(attributes)
+      #     User.transaction do
+      #       user = User.create!(attributes)
+      #       event = UserCreatedEvent.new(...)
+      #       publish_after_commit(event)
+      #       user
+      #     end
+      #   end
+      def publish_after_commit(event)
+        if active_record_available? && in_transaction?
+          # Queue event for publishing after commit
+          ActiveRecord::Base.connection.after_transaction_commit do
+            publish_event(event)
+          end
+        else
+          # No transaction, publish immediately
+          publish_event(event)
+        end
+      end
+
+      # Publish multiple events after commit
+      #
+      # @param events [Array<SmartDomain::Event::Base>] Events to publish
+      def publish_all_after_commit(events)
+        events.each { |event| publish_after_commit(event) }
+      end
+
+      # Run a block within a database transaction
+      #
+      # This is a convenience method for wrapping operations in a transaction.
+      # Events should be published using #publish_after_commit within the block.
+      #
+      # @yield Block to run within transaction
+      # @return [Object] Result of the block
+      #
+      # @example
+      #   def transfer_funds(from_account, to_account, amount)
+      #     with_transaction do
+      #       from_account.withdraw(amount)
+      #       to_account.deposit(amount)
+      #
+      #       event = FundsTransferredEvent.new(...)
+      #       publish_after_commit(event)
+      #
+      #       true
+      #     end
+      #   end
+      def with_transaction(&block)
+        if active_record_available?
+          ActiveRecord::Base.transaction(&block)
+        else
+          yield
+        end
+      end
+
+      # Build event with common context fields
+      #
+      # This helper method reduces boilerplate by automatically filling in
+      # organization_id and actor fields from the service context.
+      #
+      # @param event_class [Class] Event class to instantiate
+      # @param attributes [Hash] Event attributes
+      # @return [SmartDomain::Event::Base] Instantiated event
+      #
+      # @example
+      #   event = build_event(UserCreatedEvent,
+      #     event_type: 'user.created',
+      #     aggregate_id: user.id,
+      #     aggregate_type: 'User',
+      #     user_id: user.id,
+      #     email: user.email
+      #   )
+      def build_event(event_class, attributes = {})
+        # Auto-fill organization_id if not provided
+        attributes[:organization_id] ||= current_organization_id
+
+        # Auto-fill actor fields if event includes ActorMixin
+        if event_class.instance_methods.include?(:actor_id)
+          attributes[:actor_id] ||= current_user_id&.to_s
+          attributes[:actor_email] ||= current_user&.email
+        end
+
+        event_class.new(attributes)
+      end
+
+      # Extract changes from an ActiveRecord model for ChangeTrackingMixin
+      #
+      # This helper extracts changed fields and their old/new values from
+      # an ActiveRecord model's saved_changes.
+      #
+      # @param record [ActiveRecord::Base] Record with changes
+      # @return [Hash] Hash with changed_fields, old_values, new_values
+      #
+      # @example
+      #   user.update!(email: 'new@example.com', name: 'New Name')
+      #   changes = extract_changes(user)
+      #   # => {
+      #   #   changed_fields: ['email', 'name'],
+      #   #   old_values: { email: 'old@example.com', name: 'Old Name' },
+      #   #   new_values: { email: 'new@example.com', name: 'New Name' }
+      #   # }
+      def extract_changes(record)
+        return { changed_fields: [], old_values: {}, new_values: {} } unless record.respond_to?(:saved_changes)
+
+        changes = record.saved_changes
+        {
+          changed_fields: changes.keys,
+          old_values: changes.transform_values(&:first),
+          new_values: changes.transform_values(&:last)
+        }
+      end
+
+      # Log a message with service context
+      #
+      # @param level [Symbol] Log level (:info, :warn, :error, :debug)
+      # @param message [String] Log message
+      # @param data [Hash] Additional structured data
+      def log(level, message, data = {})
+        context = {
+          service: self.class.name,
+          organization_id: current_organization_id,
+          user_id: current_user_id
+        }.merge(data)
+
+        @logger.send(level, "[#{self.class.name}] #{message} - #{context.to_json}")
+      end
+
+      private
+
+      # Publish an event to the event bus
+      # @param event [SmartDomain::Event::Base] Event to publish
+      def publish_event(event)
+        SmartDomain::Event.bus.publish(event)
+      rescue StandardError => e
+        @logger.error "[#{self.class.name}] Failed to publish event: #{e.message}"
+        @logger.error e.backtrace.join("\n")
+        raise
+      end
+
+      # Check if ActiveRecord is available
+      # @return [Boolean]
+      def active_record_available?
+        defined?(ActiveRecord::Base)
+      end
+
+      # Check if currently in a database transaction
+      # @return [Boolean]
+      def in_transaction?
+        return false unless active_record_available?
+
+        ActiveRecord::Base.connection.transaction_open?
+      end
+    end
+  end
+end

data/lib/smart_domain/event/adapters/memory.rb

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+
+module SmartDomain
+  module Event
+    module Adapters
+      # In-memory event bus adapter for synchronous event handling.
+      #
+      # This adapter stores event handlers in memory and publishes events
+      # synchronously. It's suitable for development, testing, and simple
+      # production applications.
+      #
+      # For more robust production use cases, consider Redis or ActiveJob adapters.
+      #
+      # @example
+      #   adapter = SmartDomain::Event::Adapters::Memory.new
+      #   adapter.subscribe('user.created', handler)
+      #   adapter.publish(event)
+      class Memory
+        def initialize
+          @handlers = Hash.new { |h, k| h[k] = [] }
+          @logger = ActiveSupport::TaggedLogging.new(Logger.new($stdout))
+        end
+
+        # Subscribe a handler to an event type
+        # @param event_type [String] Event type to subscribe to
+        # @param handler [Object] Handler that responds to #handle(event)
+        def subscribe(event_type, handler)
+          @handlers[event_type] << handler unless @handlers[event_type].include?(handler)
+        end
+
+        # Publish an event to all subscribed handlers
+        # @param event [SmartDomain::Event::Base] Event to publish
+        def publish(event)
+          # Find all matching handlers (exact match + wildcard patterns)
+          matching_handlers = find_matching_handlers(event.event_type)
+
+          if matching_handlers.empty?
+            @logger.debug "[SmartDomain::Memory] No handlers for event type: #{event.event_type}"
+            return
+          end
+
+          @logger.debug "[SmartDomain::Memory] Notifying #{matching_handlers.size} handler(s) for #{event.event_type}"
+
+          matching_handlers.each do |handler|
+            handle_event(handler, event)
+          end
+        end
+
+        # Get all registered handlers for an event type
+        # @param event_type [String] Event type
+        # @return [Array<Object>] List of handlers
+        def handlers_for(event_type)
+          @handlers[event_type]
+        end
+
+        # Clear all handlers (useful for testing)
+        # @api private
+        def clear!
+          @handlers.clear
+        end
+
+        private
+
+        # Find all handlers matching the given event type
+        # Supports exact matches and wildcard patterns (e.g., "user.*")
+        # @param event_type [String] Event type to match
+        # @return [Array<Object>] List of matching handlers
+        def find_matching_handlers(event_type)
+          handlers = []
+
+          @handlers.each do |pattern, pattern_handlers|
+            if event_type_matches?(event_type, pattern)
+              handlers.concat(pattern_handlers)
+            end
+          end
+
+          handlers.uniq
+        end
+
+        # Check if event type matches a subscription pattern
+        # @param event_type [String] Event type to check
+        # @param pattern [String] Subscription pattern (may include wildcards)
+        # @return [Boolean] True if event type matches pattern
+        def event_type_matches?(event_type, pattern)
+          # Exact match
+          return true if event_type == pattern
+
+          # Wildcard pattern match (e.g., "user.*" matches "user.created")
+          if pattern.end_with?(".*")
+            prefix = pattern[0..-3] # Remove ".*"
+            return event_type.start_with?("#{prefix}.")
+          end
+
+          false
+        end
+
+        # Handle event with error isolation
+        # @param handler [Object] Handler to execute
+        # @param event [SmartDomain::Event::Base] Event to handle
+        def handle_event(handler, event)
+          handler.handle(event)
+        rescue StandardError => e
+          @logger.error "[SmartDomain::Memory] Handler #{handler.class.name} failed: #{e.message}"
+          @logger.error e.backtrace.join("\n")
+          # Swallow exception to not affect other handlers
+        end
+      end
+    end
+  end
+end