servactory 2.16.1 → 3.0.0.rc1

data/lib/servactory/dsl.rb

@@ -16,17 +16,19 @@ module Servactory
       end
     end
 
+    Stroma::Registry.register(:configuration, Configuration::DSL)
+    Stroma::Registry.register(:info, Info::DSL)
+    Stroma::Registry.register(:context, Context::DSL)
+    Stroma::Registry.register(:inputs, Inputs::DSL)
+    Stroma::Registry.register(:internals, Internals::DSL)
+    Stroma::Registry.register(:outputs, Outputs::DSL)
+    Stroma::Registry.register(:actions, Actions::DSL)
+    Stroma::Registry.finalize!
+
     def self.included(base)
-      base.include(Configuration::DSL)
-      base.include(Info::DSL)
-      base.include(Context::DSL)
-      base.include(Inputs::DSL)
-      base.include(Internals::DSL)
-      base.include(Outputs::DSL)
+      base.include(Stroma::DSL)
 
       Extensions.registry.each { |extension| base.include(extension) }
-
-      base.include(Actions::DSL)
     end
 
     def self.with_extensions(*extensions)

data/lib/servactory/maintenance/attributes/tools/validation.rb

@@ -74,7 +74,7 @@ module Servactory
           def raise_errors
             return if (tmp_errors = errors.not_blank).empty?
 
-            raise @context.class.config
+            raise @context.config
                           .public_send(:"#{@attribute.system_name}_exception_class")
                           .new(context: @context, message: tmp_errors.first)
           end

data/lib/servactory/result.rb

@@ -117,7 +117,7 @@ module Servactory
       @outputs ||= Outputs.new(
         outputs: @context.send(:servactory_service_warehouse).outputs,
         predicate_methods_enabled:
-          @context.is_a?(Servactory::TestKit::Result) || @context.class.config.predicate_methods_enabled?
+          @context.is_a?(Servactory::TestKit::Result) || @context.config.predicate_methods_enabled
       )
     end
 
@@ -126,7 +126,7 @@ module Servactory
     def rescue_no_method_error_with(exception:) # rubocop:disable Metrics/MethodLength
       raise exception if @context.blank? || @context.instance_of?(Servactory::TestKit::Result)
 
-      raise @context.class.config.failure_class.new(
+      raise @context.config.failure_class.new(
         type: :base,
         message: @context.send(:servactory_service_info).translate(
           "common.undefined_method.missing_name",

data/lib/servactory/stroma/dsl.rb

@@ -0,0 +1,118 @@
+# frozen_string_literal: true
+
+module Servactory
+  module Stroma
+    # Main integration point between Stroma and service classes.
+    #
+    # ## Purpose
+    #
+    # Module that provides the core Stroma functionality to service classes:
+    # - Includes all registered DSL modules
+    # - Provides extensions block for hook registration
+    # - Handles inheritance with proper state copying
+    #
+    # ## Usage
+    #
+    # ```ruby
+    # class MyService
+    #   include Servactory::Stroma::DSL
+    #
+    #   extensions do
+    #     before :actions, MyExtension
+    #   end
+    # end
+    # ```
+    #
+    # ## Extension Settings Access
+    #
+    # Extensions access their settings through the stroma.settings hierarchy:
+    #
+    # ```ruby
+    # # In ClassMethods:
+    # stroma.settings[:actions][:authorization][:method_name] = :authorize
+    #
+    # # In InstanceMethods:
+    # self.class.stroma.settings[:actions][:authorization][:method_name]
+    # ```
+    #
+    # ## Integration
+    #
+    # Included by Servactory::DSL which is included by Servactory::Base.
+    # Provides ClassMethods with: stroma, inherited, extensions.
+    module DSL
+      def self.included(base)
+        base.extend(ClassMethods)
+
+        Registry.entries.each do |entry|
+          base.include(entry.extension)
+        end
+      end
+
+      # Class-level methods for Stroma integration.
+      #
+      # ## Purpose
+      #
+      # Provides access to Stroma state and hooks DSL at the class level.
+      # Handles proper duplication during inheritance.
+      #
+      # ## Key Methods
+      #
+      # - `stroma` - Access the State container
+      # - `inherited` - Copy state to child classes
+      # - `extensions` - DSL block for hook registration
+      module ClassMethods
+        def self.extended(base)
+          base.instance_variable_set(:@stroma, State.new)
+        end
+
+        # Handles inheritance by duplicating Stroma state.
+        #
+        # Creates an independent copy of hooks and settings for the child class,
+        # then applies all registered hooks to the child.
+        #
+        # @param child [Class] The child class being created
+        # @return [void]
+        def inherited(child)
+          super
+
+          child.instance_variable_set(:@stroma, stroma.dup)
+
+          Hooks::Applier.new(child, child.stroma.hooks).apply!
+        end
+
+        # Returns the Stroma state for this service class.
+        #
+        # @return [State] The Stroma state container
+        #
+        # @example Accessing hooks
+        #   stroma.hooks.before(:actions)
+        #
+        # @example Accessing settings
+        #   stroma.settings[:actions][:authorization][:method_name]
+        def stroma
+          @stroma ||= State.new
+        end
+
+        private
+
+        # DSL block for registering hooks.
+        #
+        # Evaluates the block in the context of a Hooks::Factory,
+        # allowing before/after hook registration.
+        #
+        # @yield Block with before/after DSL calls
+        # @return [void]
+        #
+        # @example
+        #   extensions do
+        #     before :actions, AuthorizationExtension
+        #     after :outputs, LoggingExtension
+        #   end
+        def extensions(&block)
+          @stroma_hooks_factory ||= Hooks::Factory.new(stroma.hooks)
+          @stroma_hooks_factory.instance_eval(&block)
+        end
+      end
+    end
+  end
+end

data/lib/servactory/stroma/entry.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Servactory
+  module Stroma
+    # Represents a registered DSL entry in the Stroma registry.
+    #
+    # ## Purpose
+    #
+    # Immutable value object that holds information about a DSL module
+    # registered in the Stroma system. Each entry has a unique key
+    # and references a Module that will be included in service classes.
+    #
+    # ## Attributes
+    #
+    # - `key` (Symbol): Unique identifier for the DSL module (:inputs, :outputs, :actions)
+    # - `extension` (Module): The actual DSL module to be included
+    #
+    # ## Usage
+    #
+    # Entries are created internally by Registry.register:
+    #
+    # ```ruby
+    # Stroma::Registry.register(:inputs, Servactory::Inputs::DSL)
+    # # Creates: Entry.new(key: :inputs, extension: Servactory::Inputs::DSL)
+    # ```
+    #
+    # ## Immutability
+    #
+    # Entry is immutable (Data object) - once created, it cannot be modified.
+    Entry = Data.define(:key, :extension)
+  end
+end

data/lib/servactory/stroma/exceptions/base.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module Servactory
+  module Stroma
+    module Exceptions
+      # Base exception class for all Stroma-specific exceptions
+      #
+      # ## Purpose
+      #
+      # Serves as the parent class for all custom exceptions in the Stroma subsystem.
+      # Allows catching all Stroma-related exceptions with a single rescue clause.
+      #
+      # ## Usage
+      #
+      # All Stroma exceptions inherit from this base class:
+      #
+      # ```ruby
+      # begin
+      #   Servactory::Stroma::Registry.register(:custom, CustomModule)
+      # rescue Servactory::Stroma::Exceptions::Base => e
+      #   # Catches any Stroma-specific exception
+      #   handle_stroma_error(e)
+      # end
+      # ```
+      #
+      # ## Integration
+      #
+      # Can be used in application error handlers for centralized error handling:
+      #
+      # ```ruby
+      # rescue_from Servactory::Stroma::Exceptions::Base, with: :handle_stroma_error
+      # ```
+      #
+      # ## Subclasses
+      #
+      # - RegistryFrozen - Raised when modifying a finalized registry
+      # - RegistryNotFinalized - Raised when accessing registry before finalization
+      # - KeyAlreadyRegistered - Raised when registering a duplicate key
+      # - UnknownHookTarget - Raised when using an invalid hook target key
+      # - InvalidHookType - Raised when using an invalid hook type (:before/:after)
+      class Base < StandardError
+      end
+    end
+  end
+end

data/lib/servactory/stroma/exceptions/invalid_hook_type.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Servactory
+  module Stroma
+    module Exceptions
+      # Raised when an invalid hook type is provided.
+      #
+      # ## Purpose
+      #
+      # Ensures that only valid hook types (:before, :after) are used
+      # when creating Servactory::Stroma::Hooks::Hook objects. Provides fail-fast
+      # behavior during class definition rather than silent failures at runtime.
+      #
+      # ## Usage
+      #
+      # ```ruby
+      # # This will raise InvalidHookType:
+      # Servactory::Stroma::Hooks::Hook.new(
+      #   type: :invalid,
+      #   target_key: :actions,
+      #   extension: MyModule
+      # )
+      # # => Servactory::Stroma::Exceptions::InvalidHookType:
+      # #    Invalid hook type: :invalid. Valid types: :before, :after
+      # ```
+      class InvalidHookType < Base; end
+    end
+  end
+end

data/lib/servactory/stroma/exceptions/key_already_registered.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Servactory
+  module Stroma
+    module Exceptions
+      # Raised when registering a duplicate key in the registry
+      #
+      # ## Purpose
+      #
+      # Indicates that a DSL module key has already been registered.
+      # Each DSL module must have a unique key in the registry.
+      #
+      # ## Usage
+      #
+      # Raised when attempting to register a duplicate key:
+      #
+      # ```ruby
+      # Servactory::Stroma::Registry.register(:inputs, Inputs::DSL)
+      # Servactory::Stroma::Registry.register(:inputs, AnotherModule)
+      # # Raises: Servactory::Stroma::Exceptions::KeyAlreadyRegistered
+      # ```
+      #
+      # ## Integration
+      #
+      # This exception typically indicates a configuration error - each
+      # DSL module should only be registered once. Check for duplicate
+      # registrations in your initialization code.
+      class KeyAlreadyRegistered < Base
+      end
+    end
+  end
+end

data/lib/servactory/stroma/exceptions/registry_frozen.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Servactory
+  module Stroma
+    module Exceptions
+      # Raised when attempting to modify a finalized registry
+      #
+      # ## Purpose
+      #
+      # Indicates that the Stroma::Registry has been finalized and cannot accept
+      # new module registrations. The registry is finalized once during gem
+      # initialization and remains immutable thereafter.
+      #
+      # ## Usage
+      #
+      # Raised when attempting to register modules after finalize!:
+      #
+      # ```ruby
+      # Servactory::Stroma::Registry.finalize!
+      # Servactory::Stroma::Registry.register(:custom, CustomModule)
+      # # Raises: Servactory::Stroma::Exceptions::RegistryFrozen
+      # ```
+      #
+      # ## Integration
+      #
+      # This exception typically indicates a programming error - module
+      # registration should only occur during application boot, before
+      # any service classes are defined.
+      class RegistryFrozen < Base
+      end
+    end
+  end
+end

data/lib/servactory/stroma/exceptions/registry_not_finalized.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Servactory
+  module Stroma
+    module Exceptions
+      # Raised when accessing registry before finalization
+      #
+      # ## Purpose
+      #
+      # Indicates that the Stroma::Registry was accessed before finalize! was called.
+      # The registry must be finalized before it can be used to ensure all DSL modules
+      # are registered in the correct order.
+      #
+      # ## Usage
+      #
+      # Raised when accessing registry methods before finalization:
+      #
+      # ```ruby
+      # # Before finalize! is called
+      # Servactory::Stroma::Registry.entries
+      # # Raises: Servactory::Stroma::Exceptions::RegistryNotFinalized
+      # ```
+      #
+      # ## Integration
+      #
+      # This exception typically indicates that Servactory::DSL module was not
+      # properly loaded. Ensure servactory gem is properly required before
+      # defining service classes.
+      class RegistryNotFinalized < Base
+      end
+    end
+  end
+end

data/lib/servactory/stroma/exceptions/unknown_hook_target.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Servactory
+  module Stroma
+    module Exceptions
+      # Raised when using an invalid hook target key
+      #
+      # ## Purpose
+      #
+      # Indicates that an unknown key was used as a hook target in the
+      # extensions block. Only registered DSL module keys can be used
+      # as hook targets.
+      #
+      # ## Usage
+      #
+      # Raised when using an invalid key in extensions block:
+      #
+      # ```ruby
+      # class ApplicationService::Base
+      #   include Servactory::DSL
+      #
+      #   extensions do
+      #     before :unknown_key, SomeModule
+      #     # Raises: Servactory::Stroma::Exceptions::UnknownHookTarget
+      #   end
+      # end
+      # ```
+      #
+      # ## Integration
+      #
+      # Valid hook target keys are determined by registered DSL modules:
+      # :configuration, :info, :context, :inputs, :internals, :outputs, :actions
+      #
+      # Check Servactory::Stroma::Registry.keys for the list of valid targets.
+      class UnknownHookTarget < Base
+      end
+    end
+  end
+end

data/lib/servactory/stroma/hooks/applier.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module Servactory
+  module Stroma
+    module Hooks
+      # Applies registered hooks to a target class.
+      #
+      # ## Purpose
+      #
+      # Iterates through all registered DSL modules and includes corresponding
+      # before/after hooks in the target class. For each registry entry,
+      # before hooks are included first, then after hooks.
+      #
+      # ## Usage
+      #
+      # ```ruby
+      # applier = Servactory::Stroma::Hooks::Applier.new(ChildService, hooks)
+      # applier.apply!
+      # # ChildService now includes all hook modules
+      # ```
+      #
+      # ## Integration
+      #
+      # Called by Servactory::Stroma::DSL.inherited after duplicating
+      # parent's configuration. Uses Registry.entries to determine
+      # hook application order.
+      class Applier
+        # Creates a new applier for applying hooks to a class.
+        #
+        # @param target_class [Class] The class to apply hooks to
+        # @param hooks [Collection] The hooks collection to apply
+        def initialize(target_class, hooks)
+          @target_class = target_class
+          @hooks = hooks
+        end
+
+        # Applies all registered hooks to the target class.
+        #
+        # For each registry entry, includes before hooks first,
+        # then after hooks. Does nothing if hooks collection is empty.
+        #
+        # @return [void]
+        #
+        # @example
+        #   applier.apply!
+        #   # Target class now includes all extension modules
+        def apply!
+          return if @hooks.empty?
+
+          Registry.entries.each do |entry|
+            @hooks.before(entry.key).each do |hook|
+              @target_class.include(hook.extension)
+            end
+
+            @hooks.after(entry.key).each do |hook|
+              @target_class.include(hook.extension)
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/servactory/stroma/hooks/collection.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+module Servactory
+  module Stroma
+    module Hooks
+      # Mutable collection manager for Hook objects.
+      #
+      # ## Purpose
+      #
+      # Stores Hook objects and provides query methods to retrieve hooks
+      # by type and target key. Supports proper duplication during class
+      # inheritance to ensure configuration isolation.
+      #
+      # ## Usage
+      #
+      # ```ruby
+      # hooks = Servactory::Stroma::Hooks::Collection.new
+      # hooks.add(:before, :actions, MyModule)
+      # hooks.add(:after, :actions, AnotherModule)
+      #
+      # hooks.before(:actions)  # => [Hook(...)]
+      # hooks.after(:actions)   # => [Hook(...)]
+      # hooks.empty?            # => false
+      # hooks.size              # => 2
+      # ```
+      #
+      # ## Integration
+      #
+      # Stored in Servactory::Stroma::State and used by
+      # Servactory::Stroma::Hooks::Applier to apply hooks to classes.
+      # Properly duplicated during class inheritance via initialize_dup.
+      class Collection
+        extend Forwardable
+
+        # @!method each
+        #   Iterates over all hooks in the collection.
+        #   @yield [Hook] Each hook in the collection
+        # @!method map
+        #   Maps over all hooks in the collection.
+        #   @yield [Hook] Each hook in the collection
+        #   @return [Array] Mapped results
+        # @!method size
+        #   Returns the number of hooks in the collection.
+        #   @return [Integer] Number of hooks
+        # @!method empty?
+        #   Checks if the collection is empty.
+        #   @return [Boolean] true if no hooks registered
+        def_delegators :@collection, :each, :map, :size, :empty?
+
+        # Creates a new hooks collection.
+        #
+        # @param collection [Set] Initial collection of hooks (default: empty Set)
+        def initialize(collection = Set.new)
+          @collection = collection
+        end
+
+        # Creates a deep copy during inheritance.
+        #
+        # @param original [Collection] The original collection being duplicated
+        # @return [void]
+        def initialize_dup(original)
+          super
+          @collection = original.instance_variable_get(:@collection).dup
+        end
+
+        # Adds a new hook to the collection.
+        #
+        # @param type [Symbol] Hook type (:before or :after)
+        # @param target_key [Symbol] Registry key to hook into
+        # @param extension [Module] Extension module to include
+        # @return [Set] The updated collection
+        #
+        # @example
+        #   hooks.add(:before, :actions, ValidationModule)
+        def add(type, target_key, extension)
+          @collection << Hook.new(type:, target_key:, extension:)
+        end
+
+        # Returns all before hooks for a given key.
+        #
+        # @param key [Symbol] The target key to filter by
+        # @return [Array<Hook>] Hooks that run before the target
+        #
+        # @example
+        #   hooks.before(:actions)  # => [Hook(type: :before, ...)]
+        def before(key)
+          @collection.select { |hook| hook.before? && hook.target_key == key }
+        end
+
+        # Returns all after hooks for a given key.
+        #
+        # @param key [Symbol] The target key to filter by
+        # @return [Array<Hook>] Hooks that run after the target
+        #
+        # @example
+        #   hooks.after(:actions)  # => [Hook(type: :after, ...)]
+        def after(key)
+          @collection.select { |hook| hook.after? && hook.target_key == key }
+        end
+      end
+    end
+  end
+end

data/lib/servactory/stroma/hooks/factory.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+module Servactory
+  module Stroma
+    module Hooks
+      # DSL interface for registering hooks in extensions block.
+      #
+      # ## Purpose
+      #
+      # Provides the `before` and `after` methods used within the extensions
+      # block to register hooks. Validates that target keys exist in Registry
+      # before adding hooks.
+      #
+      # ## Usage
+      #
+      # ```ruby
+      # class ApplicationService::Base < Servactory::Base
+      #   extensions do
+      #     before :actions, ValidationModule
+      #     after :outputs, LoggingModule
+      #   end
+      # end
+      # ```
+      #
+      # ## Integration
+      #
+      # Created by DSL.extensions method and receives instance_eval of the block.
+      # Validates keys against Registry.keys and raises UnknownHookTarget
+      # for invalid keys.
+      class Factory
+        # Creates a new factory for registering hooks.
+        #
+        # @param hooks [Collection] The hooks collection to add to
+        def initialize(hooks)
+          @hooks = hooks
+        end
+
+        # Registers one or more before hooks for a target key.
+        #
+        # @param key [Symbol] The registry key to hook before
+        # @param extensions [Array<Module>] Extension modules to include
+        # @raise [Exceptions::UnknownHookTarget] If key is not registered
+        #
+        # @example
+        #   before :actions, ValidationModule, AuthorizationModule
+        def before(key, *extensions)
+          validate_key!(key)
+          extensions.each { |extension| @hooks.add(:before, key, extension) }
+        end
+
+        # Registers one or more after hooks for a target key.
+        #
+        # @param key [Symbol] The registry key to hook after
+        # @param extensions [Array<Module>] Extension modules to include
+        # @raise [Exceptions::UnknownHookTarget] If key is not registered
+        #
+        # @example
+        #   after :outputs, LoggingModule, AuditModule
+        def after(key, *extensions)
+          validate_key!(key)
+          extensions.each { |extension| @hooks.add(:after, key, extension) }
+        end
+
+        private
+
+        # Validates that the key exists in the Registry.
+        #
+        # @param key [Symbol] The key to validate
+        # @raise [Exceptions::UnknownHookTarget] If key is not registered
+        def validate_key!(key)
+          return if Registry.key?(key)
+
+          raise Exceptions::UnknownHookTarget,
+                "Unknown hook target: #{key.inspect}. " \
+                "Valid keys: #{Registry.keys.map(&:inspect).join(', ')}"
+        end
+      end
+    end
+  end
+end