dry-system 0.22.0 → 0.23.0

data/lib/dry/system/plugins/monitoring.rb

@@ -21,7 +21,7 @@ module Dry
 
         # @api private
         def self.dependencies
-          {'dry-events': "dry/events/publisher"}
+          {"dry-events": "dry/events/publisher"}
         end
 
         # @api private

data/lib/dry/system/plugins/notifications.rb

@@ -12,7 +12,7 @@ module Dry
 
         # @api private
         def self.dependencies
-          {'dry-monitor': "dry/monitor/notifications"}
+          {"dry-monitor": "dry/monitor/notifications"}
         end
 
         # @api private

data/lib/dry/system/plugins/zeitwerk/compat_inflector.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Dry
+  module System
+    module Plugins
+      class Zeitwerk < Module
+        # @api private
+        class CompatInflector
+          attr_reader :config
+
+          def initialize(config)
+            @config = config
+          end
+
+          def camelize(string, _)
+            config.inflector.camelize(string)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/dry/system/plugins/zeitwerk.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+require "dry/system/constants"
+
+module Dry
+  module System
+    module Plugins
+      # @api private
+      class Zeitwerk < Module
+        # @api private
+        def self.dependencies
+          [
+            "dry/system/loader/autoloading",
+            "dry/system/plugins/zeitwerk/compat_inflector",
+            {"zeitwerk" => "zeitwerk"}
+          ]
+        end
+
+        # @api private
+        attr_reader :loader, :run_setup, :eager_load, :debug
+
+        # @api private
+        def initialize(loader: nil, run_setup: true, eager_load: nil, debug: false)
+          @loader = loader || ::Zeitwerk::Loader.new
+          @run_setup = run_setup
+          @eager_load = eager_load
+          @debug = debug
+          super()
+        end
+
+        # @api private
+        def extended(system)
+          system.setting :autoloader, reader: true
+
+          system.config.autoloader = loader
+          system.config.component_dirs.loader = Dry::System::Loader::Autoloading
+          system.config.component_dirs.add_to_load_path = false
+
+          system.after(:configure, &method(:setup_autoloader))
+
+          super
+        end
+
+        private
+
+        def setup_autoloader(system)
+          configure_loader(system.autoloader, system)
+
+          push_component_dirs_to_loader(system, system.autoloader)
+
+          system.autoloader.setup if run_setup
+
+          system.after(:finalize) { system.autoloader.eager_load } if eager_load?(system)
+
+          system
+        end
+
+        # Build a zeitwerk loader with the configured component directories
+        #
+        # @return [Zeitwerk::Loader]
+        def configure_loader(loader, system)
+          loader.tag = system.config.name || system.name unless loader.tag
+          loader.inflector = CompatInflector.new(system.config)
+          loader.logger = method(:puts) if debug
+        end
+
+        # Add component dirs to the zeitwerk loader
+        #
+        # @return [Zeitwerk::Loader]
+        def push_component_dirs_to_loader(system, loader)
+          system.config.component_dirs.each do |dir|
+            dir.namespaces.each do |ns|
+              loader.push_dir(
+                system.root.join(dir.path, ns.path.to_s),
+                namespace: module_for_namespace(ns, system.config.inflector)
+              )
+            end
+          end
+
+          loader
+        end
+
+        def module_for_namespace(namespace, inflector)
+          return Object unless namespace.const
+
+          begin
+            inflector.constantize(inflector.camelize(namespace.const))
+          rescue NameError
+            namespace.const.split(PATH_SEPARATOR).reduce(Object) { |parent_mod, mod_path|
+              get_or_define_module(parent_mod, inflector.camelize(mod_path))
+            }
+          end
+        end
+
+        def get_or_define_module(parent_mod, name)
+          parent_mod.const_get(name)
+        rescue NameError
+          parent_mod.const_set(name, Module.new)
+        end
+
+        def eager_load?(system)
+          return eager_load unless eager_load.nil?
+
+          system.config.respond_to?(:env) && system.config.env == :production
+        end
+      end
+    end
+  end
+end

data/lib/dry/system/plugins.rb

@@ -21,8 +21,8 @@ module Dry
         end
 
         # @api private
-        def apply_to(system, options)
-          system.extend(stateful? ? mod.new(options) : mod)
+        def apply_to(system, **options)
+          system.extend(stateful? ? mod.new(**options) : mod)
           system.instance_eval(&block) if block
           system
         end
@@ -90,13 +90,13 @@ module Dry
       # @return [self]
       #
       # @api public
-      def use(name, options = {})
+      def use(name, **options)
         return self if enabled_plugins.include?(name)
 
         raise PluginNotFoundError, name unless (plugin = Plugins.registry[name])
 
         plugin.load_dependencies
-        plugin.apply_to(self, options)
+        plugin.apply_to(self, **options)
 
         enabled_plugins << name
 
@@ -131,6 +131,9 @@ module Dry
 
       require "dry/system/plugins/dependency_graph"
       register(:dependency_graph, Plugins::DependencyGraph)
+
+      require "dry/system/plugins/zeitwerk"
+      register(:zeitwerk, Plugins::Zeitwerk)
     end
   end
 end

data/lib/dry/system/provider/source.rb

@@ -0,0 +1,324 @@
+# frozen_string_literal: true
+
+require "dry/configurable"
+require "dry/core/class_attributes"
+require "dry/core/deprecations"
+require_relative "source_dsl"
+
+module Dry
+  module System
+    class Provider
+      # A provider's source provides the specific behavior for a given provider to serve
+      # its purpose.
+      #
+      # Sources should be subclasses of `Dry::System::Source::Provider`, with instance
+      # methods for each lifecycle step providing their behavior: {#prepare}, {#start},
+      # and {#stop}.
+      #
+      # Inside each of these methods, you should create and configure your provider's
+      # objects as required, and then {#register} them with the {#provider_container}.
+      # When the provider's lifecycle steps are run (via {Dry::System::Provider}), these
+      # registered components will be merged into the target container.
+      #
+      # You can prepare a provider's source in two ways:
+      #
+      # 1. Passing a bock when registering the provider, which is then evaluated via
+      #    {Dry::System::Provider::SourceDSL} to prepare the provider subclass. This
+      #    approach is easiest for simple providers.
+      # 2. Manually creare your own subclass of {Dry::System::Provider} and implement your
+      #    own instance methods for the lifecycle steps (you should not implement your own
+      #    `#initialize`). This approach may be useful for more complex providers.
+      #
+      # @see Dry::System::Container.register_provider
+      # @see Dry::System.register_provider_source
+      # @see Dry::System::Source::ProviderDSL
+      #
+      # @api public
+      class Source
+        class << self
+          # Returns a new Dry::System::Provider::Source subclass with its behavior supplied by the
+          # given block, which is evaluated using Dry::System::Provider::SourceDSL.
+          #
+          # @see Dry::System::Provider::SourceDSL
+          #
+          # @api private
+          def for(name:, group: nil, target_container:, &block) # rubocop:disable Style/KeywordParametersOrder
+            Class.new(self) { |klass|
+              klass.source_name name
+              klass.source_group group
+              SourceDSL.evaluate(klass, target_container, &block) if block
+            }
+          end
+
+          def inherited(subclass)
+            super
+
+            # FIXME: This shouldn't _need_ to be in an inherited hook but right now it's
+            # the only way to prevent individual Source instances from sharing settings
+            subclass.include Dry::Configurable
+          end
+
+          # @api private
+          def name
+            source_str = source_name
+            source_str = "#{source_group}->#{source_str}" if source_group
+
+            "Dry::System::Provider::Source[#{source_str}]"
+          end
+
+          # @api private
+          def to_s
+            "#<#{name}>"
+          end
+
+          # @api private
+          def inspect
+            to_s
+          end
+        end
+
+        CALLBACK_MAP = Hash.new { |h, k| h[k] = [] }.freeze
+
+        extend Dry::Core::ClassAttributes
+
+        defines :source_name, :source_group
+
+        # @api private
+        attr_reader :callbacks
+
+        # Returns the provider's own container for the provider.
+        #
+        # This container is namespaced based on the provider's `namespace:` configuration.
+        #
+        # Registered components in this container will be merged into the target container
+        # after the `prepare` and `start` lifecycle steps.
+        #
+        # @return [Dry::Container]
+        #
+        # @see #target_container
+        # @see Dry::System::Provider
+        #
+        # @api public
+        attr_reader :provider_container
+        alias_method :container, :provider_container
+
+        # Returns the target container for the provider.
+        #
+        # This is the container with which the provider is registered (via
+        # {Dry::System::Container.register_provider}).
+        #
+        # Registered components from the provider's container will be merged into this
+        # container after the `prepare` and `start` lifecycle steps.
+        #
+        # @return [Dry::System::Container]
+        #
+        # @see #provider_container
+        # @see Dry::System::Provider
+        #
+        # @api public
+        attr_reader :target_container
+        alias_method :target, :target_container
+
+        # @api private
+        def initialize(provider_container:, target_container:, &block)
+          super()
+          @callbacks = {before: CALLBACK_MAP.dup, after: CALLBACK_MAP.dup}
+          @provider_container = provider_container
+          @target_container = target_container
+          instance_exec(&block) if block
+        end
+
+        # Returns a string containing a human-readable representation of the provider.
+        #
+        # @return [String]
+        #
+        # @api private
+        def inspect
+          ivars = instance_variables.map { |ivar|
+            "#{ivar}=#{instance_variable_get(ivar).inspect}"
+          }.join(" ")
+
+          "#<#{self.class.name} #{ivars}>"
+        end
+
+        # Runs the behavior for the "prepare" lifecycle step.
+        #
+        # This should be implemented by your source subclass or specified by
+        # `SourceDSL#prepare` when registering a provider using a block.
+        #
+        # @return [void]
+        #
+        # @see SourceDSL#prepare
+        #
+        # @api public
+        def prepare; end
+
+        # Runs the behavior for the "start" lifecycle step.
+        #
+        # This should be implemented by your source subclass or specified by
+        # `SourceDSL#start` when registering a provider using a block.
+        #
+        # You can presume that {#prepare} has already run by the time this method is
+        # called.
+        #
+        # @return [void]
+        #
+        # @see SourceDSL#start
+        #
+        # @api public
+        def start; end
+
+        # Runs the behavior for the "stop" lifecycle step.
+        #
+        # This should be implemented by your source subclass or specified by
+        # `SourceDSL#stop` when registering a provider using a block.
+        #
+        # You can presume that {#prepare} and {#start} have already run by the time this
+        # method is called.
+        #
+        # @return [void]
+        #
+        # @see SourceDSL#stop
+        #
+        # @api public
+        def stop; end
+
+        def use(*provider_names)
+          Dry::Core::Deprecations.announce(
+            "Dry::System::Provider#use",
+            "Use `target_container.start` instead, e.g. `target_container.start(:another_provider)`", # rubocop:disable Layout/LineLength
+            tag: "dry-system",
+            uplevel: 1
+          )
+
+          provider_names.each do |name|
+            target_container.start(name)
+          end
+
+          self
+        end
+
+        # Registers a "before" callback for the given lifecycle step.
+        #
+        # The given block will be run before the lifecycle step method is run. The block
+        # will be evaluated in the context of the instance of this source.
+        #
+        # @param step_name [Symbol]
+        # @param block [Proc] the callback block
+        #
+        # @return [self]
+        #
+        # @see #after
+        #
+        # @api public
+        def before(step_name, &block)
+          if step_name.to_sym == :init
+            Dry::Core::Deprecations.announce(
+              "Dry::System::Provider before(:init) callback",
+              "Use `before(:prepare)` callback instead",
+              tag: "dry-system",
+              uplevel: 1
+            )
+
+            step_name = :prepare
+          end
+
+          callbacks[:before][step_name] << block
+          self
+        end
+
+        # Registers an "after" callback for the given lifecycle step.
+        #
+        # The given block will be run after the lifecycle step method is run. The block
+        # will be evaluated in the context of the instance of this source.
+        #
+        # @param step_name [Symbol]
+        # @param block [Proc] the callback block
+        #
+        # @return [self]
+        #
+        # @see #before
+        #
+        # @api public
+        def after(step_name, &block)
+          if step_name.to_sym == :init
+            Dry::Core::Deprecations.announce(
+              "Dry::System::Provider after(:init) callback",
+              "Use `after(:prepare)` callback instead",
+              tag: "dry-system",
+              uplevel: 1
+            )
+
+            step_name = :prepare
+          end
+
+          callbacks[:after][step_name] << block
+          self
+        end
+
+        # @api private
+        def run_callback(hook, step)
+          callbacks[hook][step].each do |callback|
+            if callback.parameters.any?
+              Dry::Core::Deprecations.announce(
+                "Dry::System::Provider::Source.before and .after callbacks with single block parameter", # rubocop:disable Layout/LineLength
+                "Use `provider_container` (or `container` for short) inside your block instead",
+                tag: "dry-system",
+                uplevel: 1
+              )
+
+              instance_exec(provider_container, &callback)
+            else
+              instance_eval(&callback)
+            end
+          end
+        end
+
+        private
+
+        # Registers a component in the provider container.
+        #
+        # When the provider's lifecycle steps are run (via {Dry::System::Provider}), these
+        # registered components will be merged into the target container.
+        #
+        # @return [Dry::Container] the provider container
+        #
+        # @api public
+        def register(...)
+          provider_container.register(...)
+        end
+
+        # Resolves a previously registered component from the provider container.
+        #
+        # @param key [String] the key for the component to resolve
+        #
+        # @return [Object] the previously registered component
+        #
+        # @api public
+        def resolve(key)
+          provider_container.resolve(key)
+        end
+
+        # @api private
+        def run_step_block(step_name)
+          step_block = self.class.step_blocks[step_name]
+          instance_eval(&step_block) if step_block
+        end
+
+        # @api private
+        def method_missing(name, *args, &block)
+          if container.key?(name)
+            container[name]
+          else
+            super
+          end
+        end
+
+        # @api private
+        def respond_to_missing?(name, include_all = false)
+          container.key?(name) || super
+        end
+      end
+    end
+  end
+end

data/lib/dry/system/provider/source_dsl.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+require "dry/core/deprecations"
+
+module Dry
+  module System
+    class Provider
+      # Configures a Dry::System::Provider::Source subclass using a DSL that makes it
+      # nicer to define source behaviour via a single block.
+      #
+      # @see Dry::System::Container.register_provider
+      #
+      # @api private
+      class SourceDSL
+        extend Dry::Core::Deprecations["Dry::System::Provider::SourceDSL"]
+
+        def self.evaluate(source_class, target_container, &block)
+          if block.parameters.any?
+            Dry::Core::Deprecations.announce(
+              "Dry::System.register_provider with single block parameter",
+              "Use `target_container` (or `target` for short) inside your block instead",
+              tag: "dry-system"
+            )
+            new(source_class).instance_exec(target_container, &block)
+          else
+            new(source_class).instance_eval(&block)
+          end
+        end
+
+        attr_reader :source_class
+
+        def initialize(source_class)
+          @source_class = source_class
+        end
+
+        def setting(...)
+          source_class.setting(...)
+        end
+
+        # rubocop:disable Layout/LineLength
+
+        def settings(&block)
+          Dry::Core::Deprecations.announce(
+            "Dry::System.register_provider with nested settings block",
+            "Use individual top-level `setting` declarations instead (see dry-configurable docs for details)",
+            tag: "dry-system",
+            uplevel: 1
+          )
+
+          DeprecatedSettingsDSL.new(self).instance_eval(&block)
+        end
+
+        # rubocop:enable Layout/LineLength
+
+        class DeprecatedSettingsDSL
+          def initialize(base_dsl)
+            @base_dsl = base_dsl
+          end
+
+          def key(name, type)
+            @base_dsl.setting(name, constructor: type)
+          end
+        end
+
+        def prepare(&block)
+          source_class.define_method(:prepare, &block)
+        end
+        deprecate :init, :prepare
+
+        def start(&block)
+          source_class.define_method(:start, &block)
+        end
+
+        def stop(&block)
+          source_class.define_method(:stop, &block)
+        end
+
+        private
+
+        def method_missing(name, *args, &block)
+          if source_class.respond_to?(name)
+            source_class.public_send(name, *args, &block)
+          else
+            super
+          end
+        end
+
+        def respond_to_missing?(name, include_all = false)
+          source_class.respond_to?(name, include_all) || super
+        end
+      end
+    end
+  end
+end