railsmith 1.0.0

data/lib/railsmith/base_service/bulk_contract.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module Railsmith
+  class BaseService
+    # Defines the bulk result/value contract.
+    # @api private
+    module BulkContract
+      private
+
+      def bulk_value(operation:, items:, results:, transaction_mode:)
+        item_payloads =
+          items.zip(results).each_with_index.map do |(item, result), index|
+            bulk_item_payload(item:, result:, index:)
+          end
+
+        {
+          operation: operation.to_s,
+          transaction_mode: transaction_mode.to_s,
+          items: item_payloads,
+          summary: bulk_summary(results)
+        }
+      end
+
+      def bulk_item_payload(item:, result:, index:)
+        {
+          index:,
+          input: item,
+          success: result.success?,
+          value: result.success? ? result.value : nil,
+          error: result.failure? ? result.error.to_h : nil
+        }
+      end
+
+      def bulk_summary(results)
+        success_count = results.count(&:success?)
+        failure_count = results.count(&:failure?)
+
+        {
+          total: results.size,
+          success_count:,
+          failure_count:,
+          all_succeeded: failure_count.zero?
+        }
+      end
+
+      def bulk_meta(model_klass, operation:, transaction_mode:, limit:)
+        {
+          model: model_klass.name,
+          operation: operation.to_s,
+          transaction_mode: transaction_mode.to_s,
+          limit:
+        }
+      end
+    end
+  end
+end

data/lib/railsmith/base_service/bulk_execution.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module Railsmith
+  class BaseService
+    # Implements bulk execution strategies (transaction modes, limits).
+    # @api private
+    module BulkExecution
+      private
+
+      # This project targets Ruby versions where anonymous block forwarding (`&`) may be unavailable.
+      # rubocop:disable Style/ArgumentsForwarding
+      def apply_bulk_operation(model_klass, operation:, items:, transaction_mode:, &block)
+        limit = bulk_limit
+        return bulk_limit_exceeded_result(limit:, count: items.size) if items.size > limit
+
+        results = apply_bulk_results(model_klass, items, transaction_mode:, &block)
+
+        Result.success(
+          value: bulk_value(operation:, items:, results:, transaction_mode:),
+          meta: bulk_meta(model_klass, operation:, transaction_mode:, limit:)
+        )
+      end
+      # rubocop:enable Style/ArgumentsForwarding
+
+      # rubocop:disable Style/ArgumentsForwarding
+      def apply_bulk_results(model_klass, items, transaction_mode:, &block)
+        return apply_bulk_all_or_nothing(model_klass, items, &block) if transaction_mode == :all_or_nothing
+
+        apply_bulk_best_effort(model_klass, items, &block)
+      end
+      # rubocop:enable Style/ArgumentsForwarding
+
+      def apply_bulk_best_effort(model_klass, items, &block)
+        bulk_map(items) do |item|
+          with_transaction(model_klass) { block.call(item) }
+        end
+      end
+
+      def apply_bulk_all_or_nothing(model_klass, items, &block)
+        results = nil
+        transaction_wrapper(model_klass) do
+          results = bulk_map(items) { |item| block.call(item) }
+          rollback_transaction if results.any?(&:failure?)
+        end
+        results
+      end
+
+      def bulk_map(items)
+        results = []
+        items.each_slice(bulk_batch_size) do |slice|
+          slice.each do |item|
+            results << yield(item)
+          end
+        end
+        results
+      end
+
+      def bulk_limit_exceeded_result(limit:, count:)
+        Result.failure(
+          error: Errors.validation_error(
+            message: "Bulk limit exceeded",
+            details: { limit:, count: }
+          )
+        )
+      end
+    end
+  end
+end

data/lib/railsmith/base_service/bulk_params.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module Railsmith
+  class BaseService
+    # Parses and normalizes bulk action params.
+    # @api private
+    module BulkParams
+      DEFAULT_BULK_LIMIT = 1000
+      DEFAULT_BATCH_SIZE = 100
+      TRANSACTION_MODE_ALL_OR_NOTHING = :all_or_nothing
+      TRANSACTION_MODE_BEST_EFFORT = :best_effort
+
+      private
+
+      def bulk_items
+        return [] unless params.is_a?(Hash)
+
+        items = params[:items]
+        return items if items.is_a?(Array)
+
+        []
+      end
+
+      def bulk_limit
+        return DEFAULT_BULK_LIMIT unless params.is_a?(Hash)
+
+        configured = params[:limit]
+        return DEFAULT_BULK_LIMIT unless configured.is_a?(Integer)
+        return DEFAULT_BULK_LIMIT if configured <= 0
+
+        configured
+      end
+
+      def bulk_batch_size
+        return DEFAULT_BATCH_SIZE unless params.is_a?(Hash)
+
+        configured = params[:batch_size]
+        return DEFAULT_BATCH_SIZE unless configured.is_a?(Integer)
+        return DEFAULT_BATCH_SIZE if configured <= 0
+
+        configured
+      end
+
+      def bulk_transaction_mode
+        return TRANSACTION_MODE_ALL_OR_NOTHING unless params.is_a?(Hash)
+
+        mode = params[:transaction_mode]
+        mode = mode.to_sym if mode.respond_to?(:to_sym)
+
+        return mode if [TRANSACTION_MODE_ALL_OR_NOTHING, TRANSACTION_MODE_BEST_EFFORT].include?(mode)
+
+        TRANSACTION_MODE_ALL_OR_NOTHING
+      end
+    end
+  end
+end

data/lib/railsmith/base_service/crud_actions.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module Railsmith
+  class BaseService
+    # Default `create`/`update`/`destroy` action implementations.
+    # @api private
+    module CrudActions
+      def create
+        model_klass = model_class
+        return missing_model_class_result unless model_klass
+
+        with_transaction(model_klass) do
+          record = build_record(model_klass, sanitize_attributes(attributes_params))
+          persist_write(record, method_name: :save)
+        end
+      end
+
+      def update
+        model_klass = model_class
+        return missing_model_class_result unless model_klass
+
+        with_transaction(model_klass) do
+          record_result = find_record(model_klass, record_id)
+          return record_result if record_result.failure?
+
+          record = record_result.value
+          assign_attributes(record, sanitize_attributes(attributes_params))
+          persist_write(record, method_name: :save)
+        end
+      end
+
+      def destroy
+        model_klass = model_class
+        return missing_model_class_result unless model_klass
+
+        with_transaction(model_klass) do
+          record_result = find_record(model_klass, record_id)
+          return record_result if record_result.failure?
+
+          persist_write(record_result.value, method_name: :destroy)
+        end
+      end
+
+      private
+
+      def persist_write(record, method_name:)
+        record.public_send(method_name)
+
+        return Result.success(value: record) if write_succeeded?(record, method_name: method_name)
+
+        Result.failure(error: validation_error_for_record(record))
+      rescue StandardError => e
+        Result.failure(error: map_exception_to_error(e))
+      end
+
+      def write_succeeded?(record, method_name:)
+        return record.destroyed? || record.errors.empty? if method_name == :destroy
+
+        record.errors.empty?
+      end
+    end
+  end
+end

data/lib/railsmith/base_service/crud_error_mapping.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+module Railsmith
+  class BaseService
+    # Maps common persistence exceptions to Railsmith error payloads.
+    # @api private
+    module CrudErrorMapping
+      private
+
+      def validation_error_for_record(record)
+        details =
+          if record.respond_to?(:errors) && record.errors.respond_to?(:to_hash)
+            { errors: record.errors.to_hash(true) }
+          else
+            { errors: { base: ["Validation failed"] } }
+          end
+
+        Errors.validation_error(details:)
+      end
+
+      def map_exception_to_error(exception)
+        mapped = map_active_record_exception(exception)
+        return mapped unless mapped.nil?
+
+        Errors.unexpected(details: { exception_class: exception.class.name, message: exception.message })
+      end
+
+      def map_active_record_exception(exception)
+        return nil unless defined?(ActiveRecord)
+
+        not_found_error(exception) ||
+          record_invalid_error(exception) ||
+          not_unique_error(exception) ||
+          stale_object_error(exception)
+      end
+
+      def not_found_error(exception)
+        return nil unless defined?(ActiveRecord::RecordNotFound)
+        return nil unless exception.is_a?(ActiveRecord::RecordNotFound)
+
+        Errors.not_found(message: "Record not found", details: { message: exception.message })
+      end
+
+      def record_invalid_error(exception)
+        return nil unless defined?(ActiveRecord::RecordInvalid)
+        return nil unless exception.is_a?(ActiveRecord::RecordInvalid)
+
+        record = exception.record
+        return nil if record.nil?
+
+        validation_error_for_record(record)
+      end
+
+      def not_unique_error(exception)
+        return nil unless defined?(ActiveRecord::RecordNotUnique)
+        return nil unless exception.is_a?(ActiveRecord::RecordNotUnique)
+
+        Errors.conflict(message: "Conflict", details: { message: exception.message })
+      end
+
+      def stale_object_error(exception)
+        return nil unless defined?(ActiveRecord::StaleObjectError)
+        return nil unless exception.is_a?(ActiveRecord::StaleObjectError)
+
+        Errors.conflict(message: "Conflict", details: { message: exception.message })
+      end
+
+      def missing_model_class_result
+        Result.failure(
+          error: Errors.validation_error(
+            message: "Model class not configured",
+            details: { service: self.class.name }
+          )
+        )
+      end
+    end
+  end
+end

data/lib/railsmith/base_service/crud_model_resolution.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Railsmith
+  class BaseService
+    # Model resolution helpers for CRUD defaults.
+    # @api private
+    module CrudModelResolution
+      private
+
+      def model_class
+        explicit = self.class.model
+        return explicit unless explicit.nil?
+
+        infer_model_class
+      end
+
+      def infer_model_class
+        return nil unless self.class.name
+
+        name = self.class.name.to_s
+        return nil unless name.end_with?("Service")
+
+        safe_constantize(name.delete_suffix("Service"))
+      end
+
+      def safe_constantize(constant_name)
+        return constant_name.constantize if constant_name.respond_to?(:constantize)
+        return nil unless defined?(ActiveSupport::Inflector)
+
+        ActiveSupport::Inflector.safe_constantize(constant_name.to_s)
+      rescue NameError
+        nil
+      end
+    end
+  end
+end

data/lib/railsmith/base_service/crud_record_helpers.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module Railsmith
+  class BaseService
+    # Record building and lookup helpers for CRUD defaults.
+    # @api private
+    module CrudRecordHelpers
+      private
+
+      def attributes_params
+        return params.fetch(:attributes) if params.is_a?(Hash) && params[:attributes].is_a?(Hash)
+        return params if params.is_a?(Hash)
+
+        {}
+      end
+
+      def sanitize_attributes(attributes)
+        attributes
+      end
+
+      def record_id
+        return params[:id] if params.is_a?(Hash) && params.key?(:id)
+
+        nil
+      end
+
+      def find_record(model_klass, id)
+        return missing_id_result if id.nil?
+
+        record = model_klass.find_by(id:)
+        return Result.success(value: record) unless record.nil?
+
+        not_found_result(model_klass, id)
+      rescue StandardError => e
+        Result.failure(error: map_exception_to_error(e))
+      end
+
+      def build_record(model_klass, attributes)
+        model_klass.new(attributes)
+      end
+
+      def assign_attributes(record, attributes)
+        record.assign_attributes(attributes)
+      end
+
+      def missing_id_result
+        Result.failure(error: Errors.validation_error(details: { missing: ["id"] }))
+      end
+
+      def not_found_result(model_klass, id)
+        Result.failure(
+          error: Errors.not_found(
+            message: "Record not found",
+            details: { model: model_klass.name, id: }
+          )
+        )
+      end
+    end
+  end
+end

data/lib/railsmith/base_service/crud_transactions.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Railsmith
+  class BaseService
+    # Transaction helpers for write-path actions.
+    # @api private
+    module CrudTransactions
+      private
+
+      def with_transaction(model_klass)
+        result = nil
+        transaction_wrapper(model_klass) do
+          result = yield
+          rollback_transaction if result.is_a?(Result) && result.failure?
+        end
+        result
+      end
+
+      def transaction_wrapper(model_klass, &)
+        return model_klass.transaction(&) if model_klass.respond_to?(:transaction)
+        return ActiveRecord::Base.transaction(&) if defined?(ActiveRecord::Base)
+
+        yield
+      end
+
+      def rollback_transaction
+        raise ActiveRecord::Rollback if defined?(ActiveRecord::Rollback)
+      end
+    end
+  end
+end

data/lib/railsmith/base_service/domain_context_propagation.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Railsmith
+  class BaseService
+    # Exposes the current domain from context and emits instrumentation events
+    # so domain tags flow into observability tooling on every service call.
+    # @api private
+    module DomainContextPropagation
+      # Returns the domain key from the service context, or nil when not set.
+      # A nil domain is permitted in flexible mode.
+      def current_domain
+        DomainContext.normalize_current_domain(context[:current_domain])
+      end
+
+      private
+
+      # Wraps action execution with a domain-tagged instrumentation event.
+      def execute_action(action:)
+        Railsmith::CrossDomainGuard.emit_if_violation(instance: self, action: action)
+        Instrumentation.instrument(
+          "service.call",
+          service: self.class.name,
+          action: action,
+          domain: current_domain
+        ) { super }
+      end
+    end
+  end
+end

data/lib/railsmith/base_service/dup_helpers.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Railsmith
+  class BaseService
+    # Deep-duplication helpers for params/context immutability.
+    # @api private
+    module DupHelpers
+      private
+
+      def deep_dup(value)
+        Railsmith.deep_dup(value)
+      end
+    end
+  end
+end

data/lib/railsmith/base_service/validation.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module Railsmith
+  class BaseService
+    # Parameter validation helpers for service actions.
+    module Validation
+      # Explicit validation helper intended to be called from action methods.
+      #
+      # Supports either:
+      # - required_keys: simple presence checks on Hash-like params
+      # - contract: a dry-validation-like contract responding to `call(input)` and returning
+      #   an object that responds to `success?` and `errors`
+      def validate(input = params, required_keys: [], contract: nil)
+        return validate_with_contract(contract, input) if contract
+
+        validate_required_keys(input, required_keys)
+      end
+
+      private
+
+      def validate_required_keys(input, required_keys)
+        hash = input.is_a?(Hash) ? input : {}
+        missing = required_keys.reject { |key| present_value?(hash[key]) }
+
+        return Result.success(value: hash) if missing.empty?
+
+        Result.failure(
+          error: Errors.validation_error(
+            message: "Validation failed",
+            details: { missing: missing.map(&:to_s) }
+          )
+        )
+      end
+
+      def validate_with_contract(contract, input)
+        result = contract.call(input)
+        return Result.success(value: input) if contract_success?(result)
+
+        Result.failure(
+          error: Errors.validation_error(
+            message: "Validation failed",
+            details: { errors: contract_errors(result) }
+          )
+        )
+      rescue StandardError => e
+        Result.failure(error: Errors.unexpected(message: e.message))
+      end
+
+      def contract_success?(result)
+        result.respond_to?(:success?) && result.success?
+      end
+
+      def contract_errors(result)
+        return result.errors if result.respond_to?(:errors)
+
+        { base: ["Invalid contract result"] }
+      end
+
+      def present_value?(value)
+        return false if value.nil?
+        return false if value.respond_to?(:empty?) && value.empty?
+
+        true
+      end
+    end
+  end
+end

data/lib/railsmith/base_service.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+module Railsmith
+  # Base service entrypoint with explicit (non-hook) lifecycle.
+  class BaseService
+    require_relative "base_service/dup_helpers"
+    require_relative "base_service/validation"
+    require_relative "base_service/crud_actions"
+    require_relative "base_service/bulk_params"
+    require_relative "base_service/bulk_execution"
+    require_relative "base_service/bulk_contract"
+    require_relative "base_service/bulk_actions"
+    require_relative "base_service/crud_model_resolution"
+    require_relative "base_service/crud_record_helpers"
+    require_relative "base_service/crud_error_mapping"
+    require_relative "base_service/crud_transactions"
+    require_relative "base_service/domain_context_propagation"
+    include DupHelpers
+    include Validation
+    include CrudActions
+    include BulkActions
+    prepend DomainContextPropagation
+
+    include CrudModelResolution
+    include CrudRecordHelpers
+    include CrudErrorMapping
+    include CrudTransactions
+
+    class << self
+      def call(action:, params: {}, context: {})
+        new(params:, context:).call(action:)
+      end
+
+      def model(model_class = nil)
+        return @model_class if model_class.nil?
+
+        @model_class = model_class
+      end
+
+      # Bounded-context key for this service (optional). When set, mismatches
+      # against +context[:current_domain]+ emit warn-only instrumentation unless
+      # the pair is listed in +Railsmith.configuration.cross_domain_allowlist+.
+      def service_domain(domain_key = nil)
+        return @service_domain if domain_key.nil?
+
+        @service_domain = DomainContext.normalize_current_domain(domain_key)
+      end
+    end
+
+    attr_reader :params, :context
+
+    def initialize(params:, context:)
+      @params = deep_dup(params || {})
+      @context = deep_dup(context || {})
+    end
+
+    def call(action:)
+      normalized_action = normalize_action(action)
+      return invalid_action_result(action: normalized_action) unless valid_action?(normalized_action)
+
+      result = execute_action(action: normalized_action)
+      normalize_result(result)
+    end
+
+    private
+
+    def execute_action(action:)
+      public_send(action)
+    end
+
+    def normalize_result(value)
+      return value if value.is_a?(Result)
+
+      Result.success(value:)
+    end
+
+    def valid_action?(action)
+      action.is_a?(Symbol) && respond_to?(action, true)
+    end
+
+    def normalize_action(action)
+      return action.to_sym if action.respond_to?(:to_sym)
+
+      action
+    end
+
+    def invalid_action_result(action:)
+      Result.failure(
+        error: Errors.validation_error(
+          message: "Invalid action",
+          details: { action: action }
+        )
+      )
+    end
+  end
+end

data/lib/railsmith/configuration.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Railsmith
+  # Stores global settings used by gem components.
+  class Configuration
+    attr_accessor :warn_on_cross_domain_calls, :strict_mode,
+                  :cross_domain_allowlist, :on_cross_domain_violation,
+                  :fail_on_arch_violations
+
+    def initialize
+      @warn_on_cross_domain_calls = true
+      @strict_mode = false
+      @cross_domain_allowlist = []
+      @on_cross_domain_violation = nil
+      @fail_on_arch_violations = false
+    end
+  end
+end