dry-system 0.22.0 → 0.25.0

data/lib/dry/system/container.rb

@@ -2,25 +2,24 @@
 
 require "pathname"
 
-require "dry-auto_inject"
-require "dry-configurable"
-require "dry-container"
-require "dry/inflector"
-
-require "dry/core/constants"
+require "dry/configurable"
+require "dry/auto_inject"
+require "dry/container"
 require "dry/core/deprecations"
+require "dry/inflector"
 
-require "dry/system"
 require "dry/system/auto_registrar"
-require "dry/system/booter"
 require "dry/system/component"
 require "dry/system/constants"
 require "dry/system/errors"
 require "dry/system/identifier"
 require "dry/system/importer"
 require "dry/system/indirect_component"
-require "dry/system/manual_registrar"
+require "dry/system/manifest_registrar"
 require "dry/system/plugins"
+require "dry/system/provider_registrar"
+require "dry/system/provider"
+require "dry/system/provider/source"
 
 require_relative "component_dir"
 require_relative "config/component_dirs"
@@ -71,67 +70,102 @@ module Dry
     #
     # @api public
     class Container
-      extend Dry::Configurable
       extend Dry::Container::Mixin
       extend Dry::System::Plugins
 
       setting :name
-      setting :root, default: Pathname.pwd.freeze, constructor: -> path { Pathname(path) }
-      setting :system_dir, default: "system"
-      setting :bootable_dirs, default: ["system/boot"]
-      setting :registrations_dir, default: "container"
+      setting :root, default: Pathname.pwd.freeze, constructor: ->(path) { Pathname(path) }
+      setting :provider_dirs, default: ["system/providers"]
+      setting :bootable_dirs # Deprecated for provider_dirs, see .provider_paths below
+      setting :registrations_dir, default: "system/registrations"
       setting :component_dirs, default: Config::ComponentDirs.new, cloneable: true
+      setting :exports, reader: true
       setting :inflector, default: Dry::Inflector.new
-      setting :booter, default: Dry::System::Booter
       setting :auto_registrar, default: Dry::System::AutoRegistrar
-      setting :manual_registrar, default: Dry::System::ManualRegistrar
+      setting :manifest_registrar, default: Dry::System::ManifestRegistrar
+      setting :provider_registrar, default: Dry::System::ProviderRegistrar
       setting :importer, default: Dry::System::Importer
-      setting :components, default: {}, reader: true, constructor: :dup.to_proc
 
-      class << self
-        def strategies(value = nil)
-          if value
-            @strategies = value
-          else
-            @strategies ||= Dry::AutoInject::Strategies
-          end
-        end
+      # We presume "." as key namespace separator. This is not intended to be
+      # user-configurable.
+      config.namespace_separator = KEY_SEPARATOR
 
+      class << self
         extend Dry::Core::Deprecations["Dry::System::Container"]
 
-        # Define a new configuration setting
+        # @!method config
+        #   Returns the configuration for the container
         #
-        # @see https://dry-rb.org/gems/dry-configurable
+        #   @example
+        #     container.config.root = "/path/to/app"
+        #     container.config.root # => #<Pathname:/path/to/app>
         #
-        # @api public
-        def setting(name, default = Dry::Core::Constants::Undefined, **options, &block)
-          super(name, default, **options, &block)
-          # TODO: dry-configurable needs a public API for this
-          config._settings << _settings[name]
-          self
-        end
+        #   @return [Dry::Configurable::Config]
+        #
+        #   @api public
 
-        # Configures the container
+        # Yields a configuration object for the container, which you can use to modify the
+        # configuration, then runs the after-`configured` hooks and finalizes (freezes)
+        # the {config}.
+        #
+        # Does not finalize the config when given `finalize_config: false`
         #
         # @example
         #   class MyApp < Dry::System::Container
         #     configure do |config|
         #       config.root = Pathname("/path/to/app")
         #       config.name = :my_app
-        #       config.auto_register = %w(lib/apis lib/core)
         #     end
         #   end
         #
+        # @param finalize_config [Boolean]
+        #
         # @return [self]
         #
+        # @see after
+        #
         # @api public
-        def configure(&block)
-          hooks[:before_configure].each { |hook| instance_eval(&hook) }
+        def configure(finalize_config: true, &block)
           super(&block)
+
+          unless configured?
+            hooks[:after_configure].each { |hook| instance_eval(&hook) }
+            config.finalize! if finalize_config
+            @__configured__ = true
+          end
+
+          self
+        end
+
+        # Marks the container as configured, runs the after-`configured` hooks, then
+        # finalizes (freezes) the {config}.
+        #
+        # This method is useful to call if you're modifying the container's {config}
+        # directly, rather than via the config object yielded when calling {configure}.
+        #
+        # Does not finalize the config if given `finalize_config: false`.
+        #
+        # @param finalize_config [Boolean]
+        #
+        # @return [self]
+        #
+        # @see after
+        #
+        # @api public
+        def configured!(finalize_config: true)
+          return self if configured?
+
           hooks[:after_configure].each { |hook| instance_eval(&hook) }
+          config.finalize! if finalize_config
+          @__configured__ = true
+
           self
         end
 
+        def configured?
+          @__configured__.equal?(true)
+        end
+
         # Registers another container for import
         #
         # @example
@@ -158,122 +192,142 @@ module Dry
         # @param other [Hash, Dry::Container::Namespace]
         #
         # @api public
-        def import(other)
-          case other
-          when Hash then importer.register(other)
-          when Dry::Container::Namespace then super
-          else
-            raise ArgumentError, <<-STR
-              +other+ must be a hash of names and systems, or a Dry::Container namespace
-            STR
+        def import(keys: nil, from: Undefined, as: Undefined, **deprecated_import_hash)
+          if deprecated_import_hash.any?
+            Dry::Core::Deprecations.announce(
+              "Dry::System::Container.import with {namespace => container} hash",
+              "Use Dry::System::Container.import(from: container, as: namespace) instead",
+              tag: "dry-system",
+              uplevel: 1
+            )
+
+            deprecated_import_hash.each do |namespace, container|
+              importer.register(container: container, namespace: namespace)
+            end
+            return self
+          elsif from == Undefined || as == Undefined
+            # These keyword arguments can become properly required in the params list once
+            # we remove the deprecation shim above
+            raise ArgumentError, "required keyword arguments: :from, :as"
           end
+
+          importer.register(container: from, namespace: as, keys: keys)
+
+          self
         end
 
-        # Registers finalization function for a bootable component
+        # rubocop:disable Layout/LineLength
+
+        # @overload register_provider(name, namespace: nil, from: nil, source: nil, if: true, &block)
+        #   Registers a provider and its lifecycle hooks
         #
-        # By convention, boot files for components should be placed in a
-        # `bootable_dirs` entry and they will be loaded on demand when
-        # components are loaded in isolation, or during the finalization
-        # process.
+        #   By convention, you should place a file for each provider in one of the
+        #   configured `provider_dirs`, and they will be loaded on demand when components
+        #   are loaded in isolation, or during container finalization.
         #
-        # @example
-        #   # system/container.rb
-        #   class MyApp < Dry::System::Container
-        #     configure do |config|
-        #       config.root = Pathname("/path/to/app")
-        #       config.name = :core
-        #       config.auto_register = %w(lib/apis lib/core)
+        #   @example
+        #     # system/container.rb
+        #     class MyApp < Dry::System::Container
+        #       configure do |config|
+        #         config.root = Pathname("/path/to/app")
+        #       end
         #     end
         #
-        #   # system/boot/db.rb
-        #   #
-        #   # Simple component registration
-        #   MyApp.boot(:db) do |container|
-        #     require 'db'
-        #
-        #     container.register(:db, DB.new)
-        #   end
-        #
-        #   # system/boot/db.rb
-        #   #
-        #   # Component registration with lifecycle triggers
-        #   MyApp.boot(:db) do |container|
-        #     init do
-        #       require 'db'
-        #       DB.configure(ENV['DB_URL'])
-        #       container.register(:db, DB.new)
+        #     # system/providers/db.rb
+        #     #
+        #     # Simple provider registration
+        #     MyApp.register_provider(:db) do
+        #       start do
+        #         require "db"
+        #         register("db", DB.new)
+        #       end
         #     end
         #
-        #     start do
-        #       db.establish_connection
+        #     # system/providers/db.rb
+        #     #
+        #     # Provider registration with lifecycle triggers
+        #     MyApp.register_provider(:db) do |container|
+        #       init do
+        #         require "db"
+        #         DB.configure(ENV["DB_URL"])
+        #         container.register("db", DB.new)
+        #       end
+        #
+        #       start do
+        #         container["db"].establish_connection
+        #       end
+        #
+        #       stop do
+        #         container["db"].close_connection
+        #       end
         #     end
         #
-        #     stop do
-        #       db.close_connection
+        #     # system/providers/db.rb
+        #     #
+        #     # Provider registration which uses another provider
+        #     MyApp.register_provider(:db) do |container|
+        #       start do
+        #         use :logger
+        #
+        #         require "db"
+        #         DB.configure(ENV['DB_URL'], logger: logger)
+        #         container.register("db", DB.new)
+        #       end
         #     end
-        #   end
         #
-        #   # system/boot/db.rb
-        #   #
-        #   # Component registration which uses another bootable component
-        #   MyApp.boot(:db) do |container|
-        #     use :logger
-        #
-        #     start do
-        #       require 'db'
-        #       DB.configure(ENV['DB_URL'], logger: logger)
-        #       container.register(:db, DB.new)
+        #     # system/providers/db.rb
+        #     #
+        #     # Provider registration under a namespace. This will register the
+        #     # db object with the "persistence.db" key
+        #     MyApp.register_provider(:persistence, namespace: "db") do
+        #       start do
+        #         require "db"
+        #         DB.configure(ENV["DB_URL"])
+        #         register("db", DB.new)
+        #       end
         #     end
-        #   end
         #
-        #   # system/boot/db.rb
-        #   #
-        #   # Component registration under a namespace. This will register the
-        #   # db object under `persistence.db` key
-        #   MyApp.namespace(:persistence) do |persistence|
-        #     require 'db'
-        #     DB.configure(ENV['DB_URL'], logger: logger)
-        #     persistence.register(:db, DB.new)
-        #   end
-        #
-        # @param name [Symbol] a unique name for a bootable component
+        #   @param name [Symbol] a unique name for the provider
+        #   @param namespace [String, nil] the key namespace to use for any registrations
+        #     made during the provider's lifecycle
+        #   @param from [Symbol, nil] the group for the external provider source (with the
+        #     provider source name inferred from `name` or passsed explicitly as
+        #     `source:`)
+        #   @param source [Symbol, nil] the name of the external provider source to use
+        #     (if different from the value provided as `name`)
+        #   @param if [Boolean] a boolean to determine whether to register the provider
         #
-        # @see Lifecycle
+        #   @see Provider
+        #   @see Provider::Source
         #
-        # @return [self]
+        #   @return [self]
         #
-        # @api public
-        def boot(name, **opts, &block)
-          if components.key?(name)
-            raise DuplicatedComponentKeyError, <<-STR
-              Bootable component #{name.inspect} was already registered
-            STR
-          end
-
-          component =
-            if opts[:from]
-              boot_external(name, **opts, &block)
-            else
-              boot_local(name, **opts, &block)
-            end
-
-          booter.register_component component
-
-          components[name] = component
+        #   @api public
+        def register_provider(...)
+          providers.register_provider(...)
         end
-        deprecate :finalize, :boot
 
-        # @api private
-        def boot_external(name, from:, key: nil, namespace: nil, &block)
-          System.providers[from].component(
-            name, key: key, namespace: namespace, finalize: block, container: self
+        # rubocop:enable Layout/LineLength
+
+        # @see .register_provider
+        # @api public
+        def boot(name, **opts, &block)
+          Dry::Core::Deprecations.announce(
+            "Dry::System::Container.boot",
+            "Use `Dry::System::Container.register_provider` instead",
+            tag: "dry-system",
+            uplevel: 1
           )
-        end
 
-        # @api private
-        def boot_local(name, namespace: nil, &block)
-          Components::Bootable.new(name, container: self, namespace: namespace, &block)
+          register_provider(
+            name,
+            namespace: opts[:namespace],
+            from: opts[:from],
+            source: opts[:key],
+            &block
+          )
         end
+        deprecate :finalize, :boot
 
         # Return if a container was finalized
         #
@@ -316,71 +370,77 @@ module Dry
         def finalize!(freeze: true, &block)
           return self if finalized?
 
+          configured!
+
+          hooks[:before_finalize].each { |hook| instance_eval(&hook) }
           yield(self) if block
 
-          importer.finalize!
-          booter.finalize!
-          manual_registrar.finalize!
+          providers.finalize!
           auto_registrar.finalize!
+          manifest_registrar.finalize!
+          importer.finalize!
 
           @__finalized__ = true
 
           self.freeze if freeze
+          hooks[:after_finalize].each { |hook| instance_eval(&hook) }
           self
         end
 
-        # Boots a specific component
+        # Starts a provider
         #
-        # As a result, `init` and `start` lifecycle triggers are called
+        # As a result, the provider's `prepare` and `start` lifecycle triggers are called
         #
         # @example
         #   MyApp.start(:persistence)
         #
-        # @param name [Symbol] the name of a registered bootable component
+        # @param name [Symbol] the name of a registered provider to start
         #
         # @return [self]
         #
         # @api public
         def start(name)
-          booter.start(name)
+          providers.start(name)
           self
         end
 
-        # Boots a specific component but calls only `init` lifecycle trigger
+        # Prepares a provider using its `prepare` lifecycle trigger
         #
-        # This way of booting is useful in places where a heavy dependency is
-        # needed but its started environment is not required
+        # Preparing (as opposed to starting) a provider is useful in places where some
+        # aspects of a heavier dependency are needed, but its fully started environment
         #
         # @example
-        #   MyApp.init(:persistence)
+        #   MyApp.prepare(:persistence)
         #
-        # @param [Symbol] name The name of a registered bootable component
+        # @param name [Symbol] The name of the registered provider to prepare
         #
         # @return [self]
         #
         # @api public
-        def init(name)
-          booter.init(name)
+        def prepare(name)
+          providers.prepare(name)
           self
         end
+        deprecate :init, :prepare
 
         # Stop a specific component but calls only `stop` lifecycle trigger
         #
         # @example
         #   MyApp.stop(:persistence)
         #
-        # @param [Symbol] name The name of a registered bootable component
+        # @param name [Symbol] The name of a registered bootable component
         #
         # @return [self]
         #
         # @api public
         def stop(name)
-          booter.stop(name)
+          providers.stop(name)
           self
         end
 
+        # @api public
         def shutdown!
-          booter.shutdown
+          providers.shutdown
           self
         end
 
@@ -395,7 +455,7 @@ module Dry
         #     add_to_load_path!('lib')
         #   end
         #
-        # @param [Array<String>] dirs
+        # @param dirs [Array<String>]
         #
         # @return [self]
         #
@@ -409,7 +469,7 @@ module Dry
 
         # @api public
         def load_registrations!(name)
-          manual_registrar.(name)
+          manifest_registrar.(name)
           self
         end
 
@@ -438,8 +498,8 @@ module Dry
         # @param options [Hash] injector options
         #
         # @api public
-        def injector(options = {strategies: strategies})
-          Dry::AutoInject(self, options)
+        def injector(**options)
+          Dry::AutoInject(self, **options)
         end
 
         # Requires one or more files relative to the container's root
@@ -491,7 +551,7 @@ module Dry
         #
         # @!method registered?(key)
         #   Whether a +key+ is registered (doesn't trigger loading)
-        #   @param [String,Symbol] key The key
+        #   @param key [String,Symbol] The key
         #   @return [Boolean]
         #   @api public
         #
@@ -499,7 +559,7 @@ module Dry
         # Check if identifier is registered.
         # If not, try to load the component
         #
-        # @param [String,Symbol] key Identifier
+        # @param key [String,Symbol] Identifier
         # @return [Boolean]
         #
         # @api public
@@ -518,22 +578,10 @@ module Dry
         end
 
         # @api private
-        def booter
-          @booter ||= config.booter.new(boot_paths)
-        end
-
-        # @api private
-        def boot_paths
-          config.bootable_dirs.map { |dir|
-            dir = Pathname(dir)
-
-            if dir.relative?
-              root.join(dir)
-            else
-              dir
-            end
-          }
+        def providers
+          @providers ||= config.provider_registrar.new(self)
         end
+        deprecate :booter, :providers
 
         # @api private
         def auto_registrar
@@ -541,8 +589,8 @@ module Dry
         end
 
         # @api private
-        def manual_registrar
-          @manual_registrar ||= config.manual_registrar.new(self)
+        def manifest_registrar
+          @manifest_registrar ||= config.manifest_registrar.new(self)
         end
 
         # @api private
@@ -550,13 +598,45 @@ module Dry
           @importer ||= config.importer.new(self)
         end
 
-        # @api private
-        def after(event, &block)
-          hooks[:"after_#{event}"] << block
-        end
-
+        # Registers a callback hook to run before container lifecycle events.
+        #
+        # Currently, the only supported event is `:finalized`. This hook is called when
+        # you run `{finalize!}`.
+        #
+        # When the given block is called, `self` is the container class, and no block
+        # arguments are given.
+        #
+        # @param event [Symbol] the event name
+        # @param block [Proc] the callback hook to run
+        #
+        # @return [self]
+        #
+        # @api public
         def before(event, &block)
           hooks[:"before_#{event}"] << block
+          self
+        end
+
+        # Registers a callback hook to run after container lifecycle events.
+        #
+        # The supported events are:
+        #
+        # - `:configured`, called when you run {configure} or {configured!}, or when
+        #   running {finalize!} and neither of the prior two methods have been called.
+        # - `:finalized`, called when you run {finalize!}.
+        #
+        # When the given block is called, `self` is the container class, and no block
+        # arguments are given.
+        #
+        # @param event [Symbol] the event name
+        # @param block [Proc] the callback hook to run
+        #
+        # @return [self]
+        #
+        # @api public
+        def after(event, &block)
+          hooks[:"after_#{event}"] << block
+          self
         end
 
         # @api private
@@ -570,6 +650,7 @@ module Dry
             klass.hooks[event].concat blocks.dup
           end
 
+          klass.instance_variable_set(:@__configured__, false)
           klass.instance_variable_set(:@__finalized__, false)
 
           super
@@ -577,30 +658,34 @@ module Dry
 
         protected
 
+        # rubocop:disable Metrics/AbcSize, Metrics/PerceivedComplexity
         # @api private
         def load_component(key)
           return self if registered?(key)
 
-          if (bootable_component = booter.find_component(key))
-            booter.start(bootable_component)
+          if (provider = providers.find_and_load_provider(key))
+            provider.start
             return self
           end
 
           component = find_component(key)
 
-          booter.boot_dependency(component)
+          providers.start_provider_dependency(component)
           return self if registered?(key)
 
           if component.loadable?
             load_local_component(component)
-          elsif manual_registrar.file_exists?(component)
-            manual_registrar.(component)
-          elsif importer.key?(component.identifier.root_key)
-            load_imported_component(component.identifier)
+          elsif manifest_registrar.file_exists?(component)
+            manifest_registrar.(component)
+          elsif importer.namespace?(component.identifier.root_key)
+            load_imported_component(component.identifier, namespace: component.identifier.root_key)
+          elsif importer.namespace?(nil)
+            load_imported_component(component.identifier, namespace: nil)
           end
 
           self
         end
+        # rubocop:enable Metrics/AbcSize, Metrics/PerceivedComplexity
 
         private
 
@@ -610,26 +695,24 @@ module Dry
           end
         end
 
-        def load_imported_component(identifier)
-          import_namespace = identifier.root_key
-
-          container = importer[import_namespace]
+        def load_imported_component(identifier, namespace:)
+          return unless importer.namespace?(namespace)
 
-          container.load_component(identifier.namespaced(from: import_namespace, to: nil).key)
+          import_key = identifier.namespaced(from: namespace, to: nil).key
 
-          importer.(import_namespace, container)
+          importer.import(namespace, keys: [import_key])
         end
 
         def find_component(key)
           # Find the first matching component from within the configured component dirs.
           # If no matching component is found, return a null component; this fallback is
-          # important because the component may still be loadable via the manual registrar
-          # or an imported container.
+          # important because the component may still be loadable via the manifest
+          # registrar or an imported container.
           component_dirs.detect { |dir|
             if (component = dir.component_for_key(key))
               break component
             end
-          } || IndirectComponent.new(Identifier.new(key, separator: config.namespace_separator))
+          } || IndirectComponent.new(Identifier.new(key))
         end
       end