dry-system 0.18.1 → 1.0.1

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

@@ -0,0 +1,276 @@
+# frozen_string_literal: true
+
+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, &block)
+            Class.new(self) { |klass|
+              klass.source_name name
+              klass.source_group group
+              SourceDSL.evaluate(klass, &block) if block
+            }
+          end
+
+          def inherited(subclass)
+            super
+
+            # Include Dry::Configurable only when first subclassing to ensure that
+            # distinct Source subclasses do not share settings.
+            #
+            # The superclass check here allows deeper Source class hierarchies to be
+            # created without running into a Dry::Configurable::AlreadyIncluded error.
+            if subclass.superclass == Source
+              subclass.include Dry::Configurable
+            end
+          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
+
+        # 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)
+          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)
+          callbacks[:after][step_name] << block
+          self
+        end
+
+        # @api private
+        def run_callback(hook, step)
+          callbacks[hook][step].each do |callback|
+            instance_eval(&callback)
+          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,55 @@
+# frozen_string_literal: true
+
+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
+        def self.evaluate(source_class, &block)
+          new(source_class).instance_eval(&block)
+        end
+
+        attr_reader :source_class
+
+        def initialize(source_class)
+          @source_class = source_class
+        end
+
+        def setting(...)
+          source_class.setting(...)
+        end
+
+        def prepare(&block)
+          source_class.define_method(:prepare, &block)
+        end
+
+        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

data/lib/dry/system/provider.rb

@@ -1,48 +1,286 @@
 # frozen_string_literal: true
 
-require "concurrent/map"
 require "dry/system/constants"
-require "dry/system/components/bootable"
 
 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
-      attr_reader :identifier
+      # 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(identifier, options)
-        @identifier = identifier
-        @options = options
-        @components = Concurrent::Map.new
+      # 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::Core::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
+        @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(name, options = {})
-        identifier = options[:key] || name
-        components.fetch(identifier).new(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 = Core::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