dry-system 0.22.0 → 0.25.0

data/lib/dry/system/provider.rb

@@ -1,48 +1,288 @@
 # frozen_string_literal: true
 
-require "concurrent/map"
-require "dry/system/constants"
-require "dry/system/components/bootable"
+require "dry/core/deprecations"
+require_relative "constants"
+require_relative "provider/source"
 
 module Dry
   module System
+    # Providers can prepare and register one or more objects and typically work with third
+    # party code. A typical provider might be for a database library, or an API client.
+    #
+    # The particular behavior for any provider is defined in a {Provider::Source}, which
+    # is a subclass created when you run {Container.register_provider} or
+    # {Dry::System.register_provider_source}. The Source provides this behavior through
+    # methods for each of the steps in the provider lifecycle: `prepare`, `start`, and
+    # `run`. These methods typically create and configure various objects, then register
+    # them with the {#provider_container}.
+    #
+    # The Provider manages this lifecycle by implementing common behavior around the
+    # lifecycle steps, such as running step callbacks, and only running steps when
+    # appropriate for the current status of the lifecycle.
+    #
+    # Providers can be registered via {Container.register_provider}.
+    #
+    # @example Simple provider
+    #   class App < Dry::System::Container
+    #     register_provider(:logger) do
+    #       prepare do
+    #         require "logger"
+    #       end
+    #
+    #       start do
+    #         register(:logger, Logger.new($stdout))
+    #       end
+    #     end
+    #   end
+    #
+    #   App[:logger] # returns configured logger
+    #
+    # @example Using an external Provider Source
+    #   class App < Dry::System::Container
+    #     register_provider(:logger, from: :some_external_provider_source) do
+    #       configure do |config|
+    #         config.log_level = :debug
+    #       end
+    #
+    #       after :start do
+    #         register(:my_extra_logger, resolve(:logger))
+    #       end
+    #     end
+    #   end
+    #
+    #   App[:my_extra_logger] # returns the extra logger registered in the callback
+    #
+    # @api public
     class Provider
+      # Returns the provider's unique name.
+      #
+      # @return [Symbol]
+      #
+      # @api public
       attr_reader :name
 
-      attr_reader :options
+      # Returns the default namespace for the provider's container keys.
+      #
+      # @return [Symbol,String]
+      #
+      # @api public
+      attr_reader :namespace
 
-      attr_reader :components
+      # Returns an array of lifecycle steps that have been run.
+      #
+      # @return [Array<Symbol>]
+      #
+      # @example
+      #   provider.statuses # => [:prepare, :start]
+      #
+      # @api public
+      attr_reader :statuses
 
-      def initialize(name, options)
+      # Returns the name of the currently running step, if any.
+      #
+      # @return [Symbol, nil]
+      #
+      # @api private
+      attr_reader :step_running
+      private :step_running
+
+      # Returns the container for the provider.
+      #
+      # This is where the provider's source will register its components, which are then
+      # later marged into the target container after the `prepare` and `start` lifecycle
+      # steps.
+      #
+      # @return [Dry::Container]
+      #
+      # @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]
+      #
+      # @api public
+      attr_reader :target_container
+      alias_method :target, :target_container
+
+      # Returns the provider's source
+      #
+      # The source provides the specific behavior for the provider via methods
+      # implementing the lifecycle steps.
+      #
+      # The provider's source is defined when registering a provider with the container,
+      # or an external provider source.
+      #
+      # @see Dry::System::Container.register_provider
+      # @see Dry::System.register_provider_source
+      #
+      # @return [Dry::System::Provider::Source]
+      #
+      # @api private
+      attr_reader :source
+
+      # @api private
+      def initialize(name:, namespace: nil, target_container:, source_class:, &block) # rubocop:disable Style/KeywordParametersOrder
         @name = name
-        @options = options
-        @components = Concurrent::Map.new
+        @namespace = namespace
+        @target_container = target_container
+
+        @provider_container = build_provider_container
+        @statuses = []
+        @step_running = nil
+
+        @source = source_class.new(
+          provider_container: provider_container,
+          target_container: target_container,
+          &block
+        )
+      end
+
+      # Runs the `prepare` lifecycle step.
+      #
+      # Also runs any callbacks for the step, and then merges any registered components
+      # from the provider container into the target container.
+      #
+      # @return [self]
+      #
+      # @api public
+      def prepare
+        run_step(:prepare)
       end
 
-      def boot_path
-        options.fetch(:boot_path)
+      # Runs the `start` lifecycle step.
+      #
+      # Also runs any callbacks for the step, and then merges any registered components
+      # from the provider container into the target container.
+      #
+      # @return [self]
+      #
+      # @api public
+      def start
+        run_step(:prepare)
+        run_step(:start)
       end
 
-      def boot_files
-        ::Dir[boot_path.join("**/#{RB_GLOB}")].sort
+      # Runs the `stop` lifecycle step.
+      #
+      # Also runs any callbacks for the step.
+      #
+      # @return [self]
+      #
+      # @api public
+      def stop
+        return self unless started?
+
+        run_step(:stop)
       end
 
-      def register_component(name, fn)
-        components[name] = Components::Bootable.new(name, &fn)
+      # Returns true if the provider's `prepare` lifecycle step has run
+      #
+      # @api public
+      def prepared?
+        statuses.include?(:prepare)
       end
 
-      def boot_file(name)
-        boot_files.detect { |path| Pathname(path).basename(RB_EXT).to_s == name.to_s }
+      # Returns true if the provider's `start` lifecycle step has run
+      #
+      # @api public
+      def started?
+        statuses.include?(:start)
       end
 
-      def component(component_name, options = {})
-        component_key = options[:key] || component_name
-        components.fetch(component_key).new(component_name, options)
+      # Returns true if the provider's `stop` lifecycle step has run
+      #
+      # @api public
+      def stopped?
+        statuses.include?(:stop)
       end
 
-      def load_components
-        boot_files.each { |f| Kernel.require f }
-        freeze
+      private
+
+      # @api private
+      def build_provider_container
+        container = Dry::Container.new
+
+        case namespace
+        when String, Symbol
+          container.namespace(namespace) { |c| return c }
+        when true
+          container.namespace(name) { |c| return c }
+        when nil
+          container
+        else
+          raise ArgumentError,
+                "+namespace:+ must be true, string or symbol: #{namespace.inspect} given."
+        end
+      end
+
+      # @api private
+      def run_step(step_name)
+        return self if step_running? || statuses.include?(step_name)
+
+        @step_running = step_name
+
+        source.run_callback(:before, step_name)
+        source.public_send(step_name)
+        source.run_callback(:after, step_name)
+
+        statuses << step_name
+
+        apply
+
+        @step_running = nil
+
+        self
+      end
+
+      # Returns true if a step is currenly running.
+      #
+      # This is important for short-circuiting the invocation of {#run_step} and avoiding
+      # infinite loops if a provider step happens to result in resolution of a component
+      # with the same root key as the provider's own name (which ordinarily results in
+      # that provider being started).
+      #
+      # @return [Boolean]
+      #
+      # @see {#run_step}
+      #
+      # @api private
+      def step_running?
+        !!step_running
+      end
+
+      # Registers any components from the provider's container in the main container.
+      #
+      # Called after each lifecycle step runs.
+      #
+      # @return [self]
+      #
+      # @api private
+      def apply
+        provider_container.each_key do |key|
+          next if target_container.registered?(key)
+
+          # Access the provider's container items directly so that we can preserve all
+          # their options when we merge them with the target container (e.g. if a
+          # component in the provider container was registered with a block, we want block
+          # registration behavior to be exhibited when later resolving that component from
+          # the target container). TODO: Make this part of dry-system's public API.
+          item = provider_container._container[key]
+
+          if item.callable?
+            target_container.register(key, **item.options, &item.item)
+          else
+            target_container.register(key, item.item, **item.options)
+          end
+        end
+
         self
       end
     end

data/lib/dry/system/provider_registrar.rb

@@ -0,0 +1,276 @@
+# frozen_string_literal: true
+
+require "dry/core/deprecations"
+require "dry/system"
+require "pathname"
+require_relative "errors"
+require_relative "constants"
+require_relative "provider"
+
+module Dry
+  module System
+    # Default provider registrar implementation
+    #
+    # This is currently configured by default for every Dry::System::Container. The
+    # provider registrar is responsible for loading provider files and exposing an API for
+    # running the provider lifecycle steps.
+    #
+    # @api private
+    class ProviderRegistrar
+      extend Dry::Core::Deprecations["Dry::System::Container"]
+
+      # @api private
+      attr_reader :providers
+
+      # @api private
+      attr_reader :container
+
+      # @api private
+      def initialize(container)
+        @providers = {}
+        @container = container
+      end
+
+      # @api private
+      def freeze
+        providers.freeze
+        super
+      end
+
+      # rubocop:disable Metrics/PerceivedComplexity
+
+      # @see Container.register_provider
+      # @api private
+      def register_provider(name, namespace: nil, from: nil, source: nil, if: true, &block)
+        raise ProviderAlreadyRegisteredError, name if providers.key?(name)
+
+        if from && source.is_a?(Class)
+          raise ArgumentError, "You must supply a block when using a provider source"
+        end
+
+        if block && source.is_a?(Class)
+          raise ArgumentError, "You must supply only a `source:` option or a block, not both"
+        end
+
+        return self unless binding.local_variable_get(:if)
+
+        provider =
+          if from
+            build_provider_from_source(
+              name,
+              namespace: namespace,
+              source: source || name,
+              group: from,
+              &block
+            )
+          else
+            build_provider(name, namespace: namespace, source: source, &block)
+          end
+
+        providers[provider.name] = provider
+
+        self
+      end
+
+      # rubocop:enable Metrics/PerceivedComplexity
+
+      # Returns a provider for the given name, if it has already been loaded
+      #
+      # @api public
+      def [](provider_name)
+        providers[provider_name]
+      end
+      alias_method :provider, :[]
+
+      # @api private
+      def key?(provider_name)
+        providers.key?(provider_name)
+      end
+
+      # Returns a provider if it can be found or loaded, otherwise nil
+      #
+      # @return [Dry::System::Provider, nil]
+      #
+      # @api private
+      def find_and_load_provider(name)
+        name = name.to_sym
+
+        if (provider = providers[name])
+          return provider
+        end
+
+        return if finalized?
+
+        require_provider_file(name)
+
+        providers[name]
+      end
+
+      # @api private
+      def start_provider_dependency(component)
+        if (provider = find_and_load_provider(component.root_key))
+          provider.start
+        end
+      end
+
+      # Returns all provider files within the configured provider_paths.
+      #
+      # Searches for files in the order of the configured provider_paths. In the case of multiple
+      # identically-named boot files within different provider_paths, the file found first will be
+      # returned, and other matching files will be discarded.
+      #
+      # This method is public to allow other tools extending dry-system (like dry-rails)
+      # to access a canonical list of real, in-use provider files.
+      #
+      # @see Container.provider_paths
+      #
+      # @return [Array<Pathname>]
+      # @api public
+      def provider_files
+        @provider_files ||= provider_paths.each_with_object([[], []]) { |path, (provider_files, loaded)| # rubocop:disable Layout/LineLength
+          files = Dir["#{path}/#{RB_GLOB}"].sort
+
+          files.each do |file|
+            basename = File.basename(file)
+
+            unless loaded.include?(basename)
+              provider_files << Pathname(file)
+              loaded << basename
+            end
+          end
+        }.first
+      end
+      deprecate :boot_files, :provider_files
+
+      # @api private
+      def finalize!
+        provider_files.each do |path|
+          load_provider(path)
+        end
+
+        providers.each_value(&:start)
+
+        freeze
+      end
+
+      # @!method finalized?
+      #   Returns true if the booter has been finalized
+      #
+      #   @return [Boolean]
+      #   @api private
+      alias_method :finalized?, :frozen?
+
+      # @api private
+      def shutdown
+        providers.each_value(&:stop)
+        self
+      end
+
+      # @api private
+      def prepare(provider_name)
+        with_provider(provider_name, &:prepare)
+        self
+      end
+
+      # @api private
+      def start(provider_name)
+        with_provider(provider_name, &:start)
+        self
+      end
+
+      # @api private
+      def stop(provider_name)
+        with_provider(provider_name, &:stop)
+        self
+      end
+
+      private
+
+      # rubocop:disable Metrics/AbcSize, Metrics/PerceivedComplexity, Layout/LineLength
+      # @api private
+      def provider_paths
+        provider_dirs = container.config.provider_dirs
+        bootable_dirs = container.config.bootable_dirs || ["system/boot"]
+
+        if container.config.provider_dirs == ["system/providers"] && \
+           provider_dirs.none? { |d| container.root.join(d).exist? } && \
+           bootable_dirs.any? { |d| container.root.join(d).exist? }
+          Dry::Core::Deprecations.announce(
+            "Dry::System::Container.config.bootable_dirs (defaulting to 'system/boot')",
+            "Use `Dry::System::Container.config.provider_dirs` (defaulting to 'system/providers') instead",
+            tag: "dry-system",
+            uplevel: 2
+          )
+
+          provider_dirs = bootable_dirs
+        end
+
+        provider_dirs.map { |dir|
+          dir = Pathname(dir)
+
+          if dir.relative?
+            container.root.join(dir)
+          else
+            dir
+          end
+        }
+      end
+      # rubocop:enable Metrics/AbcSize, Metrics/PerceivedComplexity, Layout/LineLength
+
+      def build_provider(name, namespace:, source: nil, &block)
+        source_class = source || Provider::Source.for(
+          name: name,
+          target_container: container,
+          &block
+        )
+
+        Provider.new(
+          name: name,
+          namespace: namespace,
+          target_container: container,
+          source_class: source_class
+        )
+      end
+
+      def build_provider_from_source(name, source:, group:, namespace:, &block)
+        source_class = System.provider_sources.resolve(name: source, group: group)
+
+        Provider.new(
+          name: name,
+          namespace: namespace,
+          target_container: container,
+          source_class: source_class,
+          &block
+        )
+      end
+
+      def with_provider(provider_name)
+        require_provider_file(provider_name) unless providers.key?(provider_name)
+
+        provider = providers[provider_name]
+
+        raise ProviderNotFoundError, provider_name unless provider
+
+        yield(provider)
+      end
+
+      def load_provider(path)
+        name = Pathname(path).basename(RB_EXT).to_s.to_sym
+
+        Kernel.require path unless providers.key?(name)
+
+        self
+      end
+
+      def require_provider_file(name)
+        provider_file = find_provider_file(name)
+
+        Kernel.require provider_file if provider_file
+      end
+
+      def find_provider_file(name)
+        provider_files.detect { |file| File.basename(file, RB_EXT) == name.to_s }
+      end
+    end
+  end
+end

data/lib/dry/system/provider_source_registry.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+require "dry/core/deprecations"
+require_relative "constants"
+require_relative "provider/source"
+
+module Dry
+  module System
+    # @api private
+    class ProviderSourceRegistry
+      attr_reader :sources
+
+      def initialize
+        @sources = {}
+      end
+
+      def load_sources(path)
+        Dir[File.join(path, "**/#{RB_GLOB}")].sort.each do |file|
+          require file
+        end
+      end
+
+      def register(name:, group:, source:)
+        sources[key(name, group)] = source
+      end
+
+      def register_from_block(name:, group:, target_container:, &block)
+        register(
+          name: name,
+          group: group,
+          source: Provider::Source.for(
+            name: name,
+            group: group,
+            target_container: target_container,
+            &block
+          )
+        )
+      end
+
+      def resolve(name:, group:)
+        if group == :system
+          Dry::Core::Deprecations.announce(
+            "Providers using `from: :system`",
+            "Use `from: :dry_system` instead",
+            tag: "dry-system",
+            uplevel: 1
+          )
+
+          group = :dry_system
+        end
+
+        sources[key(name, group)].tap { |source|
+          unless source
+            raise ProviderSourceNotFoundError.new(
+              name: name,
+              group: group,
+              keys: sources.keys
+            )
+          end
+        }
+      end
+
+      private
+
+      def key(name, group)
+        {group: group, name: name}
+      end
+    end
+  end
+end