dry-system 0.5.0

data/examples/standalone/system/container.rb

@@ -0,0 +1,9 @@
+require 'dry/system/container'
+
+class App < Dry::System::Container
+  configure do |config|
+    config.auto_register = %w(lib)
+  end
+
+  load_paths!('lib')
+end

data/examples/standalone/system/import.rb

@@ -0,0 +1,3 @@
+require_relative 'container'
+
+Import = App.injector

data/lib/dry-system.rb

@@ -0,0 +1 @@
+require 'dry/system'

data/lib/dry/system.rb

@@ -0,0 +1,4 @@
+module Dry
+  module System
+  end
+end

data/lib/dry/system/auto_registrar.rb

@@ -0,0 +1,80 @@
+require 'dry/system/constants'
+
+module Dry
+  module System
+    # Default auto-registration implementation
+    #
+    # This is currently configured by default for every System::Container.
+    # Auto-registrar objects are responsible for loading files from configured
+    # auto-register paths and registering components automatically withing the
+    # container.
+    #
+    # @api private
+    class AutoRegistrar
+      attr_reader :container
+
+      attr_reader :config
+
+      def initialize(container)
+        @container = container
+        @config = container.config
+      end
+
+      # @api private
+      def finalize!
+        Array(config.auto_register).each { |dir| call(dir) }
+      end
+
+      # @api private
+      def call(dir, &block)
+        components(dir).each do |component|
+          container.require_component(component) do
+            if block
+              register(component.identifier, yield(component))
+            else
+              register(component.identifier) { component.instance }
+            end
+          end
+        end
+      end
+
+      private
+
+      # @api private
+      def components(dir)
+        paths(dir).
+          map { |path| component(path) }.
+          reject { |component| key?(component.identifier) }
+      end
+
+      # @api private
+      def paths(dir)
+        dir_root = root.join(dir.to_s.split('/')[0])
+
+        Dir["#{root}/#{dir}/**/*.rb"].map { |path|
+          path.to_s.sub("#{dir_root}/", '').sub(RB_EXT, EMPTY_STRING)
+        }
+      end
+
+      # @api private
+      def component(path)
+        container.component(path)
+      end
+
+      # @api private
+      def root
+        container.root
+      end
+
+      # @api private
+      def key?(name)
+        container.key?(name)
+      end
+
+      # @api private
+      def register(*args, &block)
+        container.register(*args, &block)
+      end
+    end
+  end
+end

data/lib/dry/system/booter.rb

@@ -0,0 +1,101 @@
+require 'dry/system/errors'
+require 'dry/system/lifecycle'
+
+module Dry
+  module System
+    # Default booter implementation
+    #
+    # This is currently configured by default for every System::Container.
+    # Booter objects are responsible for loading system/boot files and expose
+    # an API for calling lifecycle triggers.
+    #
+    # @api private
+    class Booter
+      attr_reader :path
+
+      attr_reader :finalizers
+
+      attr_reader :booted
+
+      # @api private
+      def initialize(path)
+        @path = path
+        @booted = {}
+        @finalizers = {}
+      end
+
+      # @api private
+      def []=(name, fn)
+        @finalizers[name] = fn
+        self
+      end
+
+      # @api private
+      def finalize!
+        Dir[boot_files].each do |path|
+          boot!(File.basename(path, '.rb').to_sym)
+        end
+        freeze
+      end
+
+      # @api private
+      def boot(name)
+        Kernel.require(path.join(name.to_s))
+
+        call(name) do |lifecycle|
+          lifecycle.(:init)
+          yield(lifecycle) if block_given?
+        end
+
+        self
+      end
+
+      # @api private
+      def boot!(name)
+        check_component_identifier(name)
+
+        return self if booted.key?(name)
+
+        boot(name) { |lifecycle| lifecycle.(:start) }
+        booted[name] = true
+
+        self
+      end
+
+      # @api private
+      def call(name)
+        container, finalizer = finalizers[name]
+
+        if finalizer
+          lifecycle = Lifecycle.new(container, &finalizer)
+          yield(lifecycle) if block_given?
+          lifecycle
+        end
+      end
+
+      # @api private
+      def boot_dependency(component)
+        boot_file = component.boot_file(path)
+        boot!(boot_file.basename('.*').to_s.to_sym) if boot_file.exist?
+      end
+
+      private
+
+      # @api private
+      def boot_files
+        path.join('**/*.rb').to_s
+      end
+
+      # @api private
+      def check_component_identifier(name)
+        unless name.is_a?(Symbol)
+          raise InvalidComponentIdentifierTypeError, name
+        end
+
+        unless path.join("#{name}.rb").exist?
+          raise InvalidComponentIdentifierError, name
+        end
+      end
+    end
+  end
+end

data/lib/dry/system/component.rb

@@ -0,0 +1,167 @@
+require 'concurrent/map'
+
+require 'dry-equalizer'
+require 'dry/system/loader'
+require 'dry/system/errors'
+require 'dry/system/constants'
+
+module Dry
+  module System
+    # Components are objects providing information about auto-registered files.
+    # They expose an API to query this information and use a configurable
+    # loader object to initialize class instances.
+    #
+    # Components are created automatically through auto-registration and can be
+    # accessed through `Container.auto_register!` which yields them.
+    #
+    # @api public
+    class Component
+      include Dry::Equalizer(:identifier, :path)
+
+      DEFAULT_OPTIONS = { separator: DEFAULT_SEPARATOR, namespace: nil }.freeze
+
+      # @!attribute [r] identifier
+      #   @return [String] component's unique identifier
+      attr_reader :identifier
+
+      # @!attribute [r] path
+      #   @return [String] component's relative path
+      attr_reader :path
+
+      # @!attribute [r] file
+      #   @return [String] component's file name
+      attr_reader :file
+
+      # @!attribute [r] options
+      #   @return [Hash] component's options
+      attr_reader :options
+
+      # @!attribute [r] loader
+      #   @return [Object#call] component's loader object
+      attr_reader :loader
+
+      # @api private
+      def self.new(*args)
+        cache.fetch_or_store(args.hash) do
+          name, options = args
+          options = DEFAULT_OPTIONS.merge(options || {})
+
+          ns, sep = options.values_at(:namespace, :separator)
+
+          ns_name = ensure_valid_namespace(ns, sep)
+          identifier = ensure_valid_identifier(name, ns_name, sep)
+
+          path = name.to_s.gsub(sep, PATH_SEPARATOR)
+          loader = options.fetch(:loader, Loader).new(path)
+
+          super(identifier, path, options.merge(loader: loader))
+        end
+      end
+
+      # @api private
+      def self.ensure_valid_namespace(ns, sep)
+        ns_name = ns.to_s
+        raise InvalidNamespaceError, ns_name if ns && ns_name.include?(sep)
+        ns_name
+      end
+
+      # @api private
+      def self.ensure_valid_identifier(name, ns_name, sep)
+        keys = name.to_s.scan(WORD_REGEX)
+
+        if keys.uniq.size != keys.size
+          raise InvalidComponentError, name, 'duplicated keys in the name'
+        end
+
+        keys.reject { |s| ns_name == s }.join(sep)
+      end
+
+      # @api private
+      def self.cache
+        @cache ||= Concurrent::Map.new
+      end
+
+      # @api private
+      def initialize(identifier, path, options)
+        @identifier, @path = identifier, path
+        @options = options
+        @file = "#{path}.rb".freeze
+        @loader = options.fetch(:loader)
+        freeze
+      end
+
+      # Returns components instance
+      #
+      # @example
+      #   class MyApp < Dry::System::Container
+      #     configure do |config|
+      #       config.name = :my_app
+      #       config.root = Pathname('/my/app')
+      #     end
+      #
+      #     auto_register!('lib/clients') do |component|
+      #       # some custom initialization logic, ie:
+      #       constant = component.loader.constant
+      #       constant.create
+      #     end
+      #   end
+      #
+      # @return [Object] component's class instance
+      #
+      # @api public
+      def instance(*args)
+        loader.call(*args)
+      end
+
+      # @api private
+      def bootable?(path)
+        boot_file(path).exist?
+      end
+
+      # @api private
+      def boot_file(path)
+        path.join("#{root_key}.rb")
+      end
+
+      # @api private
+      def file_exists?(paths)
+        paths.any? { |path| path.join(file).exist? }
+      end
+
+      # @api private
+      def prepend(name)
+        self.class.new(
+          [name, identifier].join(separator), options.merge(loader: loader.class)
+        )
+      end
+
+      # @api private
+      def namespaced(namespace)
+        self.class.new(
+          path, options.merge(loader: loader.class, namespace: namespace)
+        )
+      end
+
+      # @api private
+      def separator
+        options[:separator]
+      end
+
+      # @api private
+      def namespace
+        options[:namespace]
+      end
+
+      # @api private
+      def root_key
+        namespaces.first
+      end
+
+      private
+
+      def namespaces
+        identifier.split(separator).map(&:to_sym)
+      end
+    end
+  end
+end

data/lib/dry/system/constants.rb

@@ -0,0 +1,9 @@
+module Dry
+  module System
+    RB_EXT = '.rb'.freeze
+    EMPTY_STRING = ''.freeze
+    PATH_SEPARATOR = '/'.freeze
+    DEFAULT_SEPARATOR = '.'.freeze
+    WORD_REGEX = /\w+/.freeze
+  end
+end

data/lib/dry/system/container.rb

@@ -0,0 +1,500 @@
+require 'pathname'
+
+require 'dry-configurable'
+require 'dry-container'
+
+require 'dry/system/errors'
+require 'dry/system/injector'
+require 'dry/system/loader'
+require 'dry/system/booter'
+require 'dry/system/auto_registrar'
+require 'dry/system/importer'
+require 'dry/system/component'
+require 'dry/system/constants'
+
+module Dry
+  module System
+    # Abstract container class to inherit from
+    #
+    # Container class is treated as a global registry with all system components.
+    # Container can also import dependencies from other containers, which is
+    # useful in complex systems that are split into sub-systems.
+    #
+    # Container can be finalized, which triggers loading of all the defined
+    # components within a system, after finalization it becomes frozen. This
+    # typically happens in cases like booting a web application.
+    #
+    # Before finalization, Container can lazy-load components on demand. A
+    # component can be a simple class defined in a single file, or a complex
+    # component which has init/start/stop lifecycle, and it's defined in a boot
+    # file. Components which specify their dependencies using. Import module can
+    # be safely required in complete isolation, and Container will resolve and
+    # load these dependencies automatically.
+    #
+    # Furthermore, Container supports auto-registering components based on
+    # dir/file naming conventions. This reduces a lot of boilerplate code as all
+    # you have to do is to put your classes under configured directories and
+    # their instances will be automatically registered within a container.
+    #
+    # Every container needs to be configured with following settings:
+    #
+    # * `:name` - a unique container identifier
+    # * `:root` - a system root directory (defaults to `pwd`)
+    # * `:system_dir` - directory name relative to root, where bootable components
+    #                 can be defined in `boot` dir this defaults to `component`
+    #
+    # @example
+    #   class MyApp < Dry::System::Container
+    #     configure do |config|
+    #       config.name = :my_app
+    #
+    #       # this will auto-register classes from 'lib/components'. ie if you add
+    #       # `lib/components/repo.rb` which defines `Repo` class, then it's
+    #       # instance will be automatically available as `MyApp['repo']`
+    #       config.auto_register = %w(lib/components)
+    #     end
+    #
+    #     # this will configure $LOAD_PATH to include your `lib` dir
+    #     load_paths!('lib)
+    #   end
+    #
+    # @api public
+    class Container
+      extend Dry::Configurable
+      extend Dry::Container::Mixin
+
+      setting :name
+      setting :default_namespace
+      setting :root, Pathname.pwd.freeze
+      setting :system_dir, 'system'.freeze
+      setting :auto_register, []
+      setting :loader, Dry::System::Loader
+      setting :booter, Dry::System::Booter
+      setting :auto_registrar, Dry::System::AutoRegistrar
+      setting :importer, Dry::System::Importer
+
+      class << self
+        # Configures the container
+        #
+        # @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
+        #
+        # @return [self]
+        #
+        # @api public
+        def configure(&block)
+          super(&block)
+          load_paths!(config.system_dir)
+          self
+        end
+
+        # Registers another container for import
+        #
+        # @example
+        #   # system/container.rb
+        #   class Core < Dry::System::Container
+        #     configure do |config|
+        #       config.root = Pathname("/path/to/app")
+        #       config.name = :core
+        #       config.auto_register = %w(lib/apis lib/core)
+        #     end
+        #   end
+        #
+        #   # apps/my_app/system/container.rb
+        #   require 'system/container'
+        #
+        #   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)
+        #     end
+        #
+        #     import core: Core
+        #   end
+        #
+        # @param other [Hash,Dry::Container::Namespace,Dry::System::Container]
+        #
+        # @api public
+        def import(other)
+          case other
+          when Hash then importer.register(other)
+          when Dry::Container::Namespace then super
+          else
+            if other < System::Container
+              importer.register(other.config.name => other)
+            end
+          end
+        end
+
+        # Registers finalization function for a bootable component
+        #
+        # By convention, boot files for components should be placed in
+        # `%{system_dir}/boot` and they will be loaded on demand when components
+        # are loaded in isolation, or during finalization process.
+        #
+        # @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)
+        #     end
+        #
+        #   # system/boot/db.rb
+        #   #
+        #   # Simple component registration
+        #   MyApp.finalize(:db) do |container|
+        #     require 'db'
+        #
+        #     container.register(:db, DB.new)
+        #   end
+        #
+        #   # system/boot/db.rb
+        #   #
+        #   # Component registration with lifecycle triggers
+        #   MyApp.finalize(:db) do |container|
+        #     init do
+        #       require 'db'
+        #       DB.configure(ENV['DB_URL'])
+        #       container.register(:db, DB.new)
+        #     end
+        #
+        #     start do
+        #       db.establish_connection
+        #     end
+        #
+        #     stop do
+        #       db.close_connection
+        #     end
+        #   end
+        #
+        #   # system/boot/db.rb
+        #   #
+        #   # Component registration which uses another bootable component
+        #   MyApp.finalize(:db) do |container|
+        #     use :logger
+        #
+        #     start do
+        #       require 'db'
+        #       DB.configure(ENV['DB_URL'], logger: logger)
+        #       container.register(:db, DB.new)
+        #     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 identifier for a bootable component
+        #
+        # @see Lifecycle
+        #
+        # @return [self]
+        #
+        # @api public
+        def finalize(name, &block)
+          booter[name] = [self, block]
+          self
+        end
+
+        # Finalizes the container
+        #
+        # This triggers importing components from other containers, booting
+        # registered components and auto-registering components. It should be
+        # called only in places where you want to finalize your system as a
+        # whole, ie when booting a web application
+        #
+        # @example
+        #   # system/container.rb
+        #   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
+        #
+        #   # You can put finalization file anywhere you want, ie system/boot.rb
+        #   MyApp.finalize!
+        #
+        #   # If you need last-moment adjustements just before the finalization
+        #   # you can pass a block and do it there
+        #   MyApp.finalize! do |container|
+        #     # stuff that only needs to happen for finalization
+        #   end
+        #
+        # @return [self] frozen container
+        #
+        # @api public
+        def finalize!(&block)
+          return self if frozen?
+
+          yield(self) if block
+
+          importer.finalize!
+          booter.finalize!
+          auto_registrar.finalize!
+
+          freeze
+        end
+
+        # Boots a specific component
+        #
+        # As a result, `init` and `start` lifecycle triggers are called
+        #
+        # @example
+        #   MyApp.boot!(:persistence)
+        #
+        # @param name [Symbol] the name of a registered bootable component
+        #
+        # @return [self]
+        #
+        # @api public
+        def boot!(name)
+          booter.boot!(name)
+          self
+        end
+
+        # Boots a specific component but calls only `init` lifecycle trigger
+        #
+        # This way of booting is useful in places where a heavy dependency is
+        # needed but its started environment is not required
+        #
+        # @example
+        #   MyApp.boot(:persistence)
+        #
+        # @param [Symbol] name The name of a registered bootable component
+        #
+        # @return [self]
+        #
+        # @api public
+        def boot(name)
+          booter.boot(name)
+          self
+        end
+
+        # Sets load paths relative to the container's root dir
+        #
+        # @example
+        #   class MyApp < Dry::System::Container
+        #     configure do |config|
+        #       # ...
+        #     end
+        #
+        #     load_paths!('lib')
+        #   end
+        #
+        # @param [Array<String>] *dirs
+        #
+        # @return [self]
+        #
+        # @api public
+        def load_paths!(*dirs)
+          dirs.map(&root.method(:join)).each do |path|
+            next if load_paths.include?(path)
+            load_paths << path
+            $LOAD_PATH.unshift(path.to_s)
+          end
+          self
+        end
+
+        # Auto-registers components from the provided directory
+        #
+        # Typically you want to configure auto_register directories, and it will
+        # work automatically. Use this method in cases where you want to have an
+        # explicit way where some components are auto-registered.
+        #
+        # @example
+        #   class MyApp < Dry::System::Container
+        #     configure do |config|
+        #       # ...
+        #     end
+        #
+        #     # with a dir
+        #     auto_register!('lib/core')
+        #
+        #     # with a dir and a custom registration block
+        #     auto_register!('lib/core') do |component|
+        #       # custom way of initializing a component
+        #     end
+        #   end
+        #
+        # @param [String] dir The dir name relative to the root dir
+        #
+        # @yield [Component]
+        # @see [Component]
+        #
+        # @return [self]
+        #
+        # @api public
+        def auto_register!(dir, &block)
+          auto_registrar.(dir, &block)
+          self
+        end
+
+        # Builds injector for this container
+        #
+        # An injector is a useful mixin which injects dependencies into
+        # automatically defined constructor.
+        #
+        # @example
+        #   # Define an injection mixin
+        #   #
+        #   # system/import.rb
+        #   Import = MyApp.injector
+        #
+        #   # Use it in your auto-registered classes
+        #   #
+        #   # lib/user_repo.rb
+        #   require 'import'
+        #
+        #   class UserRepo
+        #     include Import['persistence.db']
+        #   end
+        #
+        #   MyApp['user_repo].db # instance under 'persistence.db' key
+        #
+        # @param options [Hash] injector options
+        #
+        # @api public
+        def injector(options = {})
+          Injector.new(self, options: options)
+        end
+
+        # Requires one or more files relative to the container's root
+        #
+        # @example
+        #   # sinle file
+        #   MyApp.require('lib/core')
+        #
+        #   # glob
+        #   MyApp.require('lib/**/*')
+        #
+        # @param *paths [Array<String>] one or more paths, supports globs too
+        #
+        # @api public
+        def require(*paths)
+          paths.flat_map { |path|
+            path.to_s.include?('*') ? Dir[root.join(path)] : root.join(path)
+          }.each { |path|
+            Kernel.require path.to_s
+          }
+        end
+
+        # Returns container's root path
+        #
+        # @example
+        #   class MyApp < Dry::System::Container
+        #     configure do |config|
+        #       config.root = Pathname('/my/app')
+        #     end
+        #   end
+        #
+        #   MyApp.root # returns '/my/app' pathname
+        #
+        # @return [Pathname]
+        #
+        # @api public
+        def root
+          config.root
+        end
+
+        # @api private
+        def load_paths
+          @load_paths ||= []
+        end
+
+        # @api private
+        def booter
+          @booter ||= config.booter.new(root.join("#{config.system_dir}/boot"))
+        end
+
+        # @api private
+        def auto_registrar
+          @auto_registrar ||= config.auto_registrar.new(self)
+        end
+
+        # @api private
+        def importer
+          @importer ||= config.importer.new(self)
+        end
+
+        # @api private
+        def component(key)
+          Component.new(
+            key,
+            loader: config.loader,
+            namespace: config.default_namespace,
+            separator: config.namespace_separator
+          )
+        end
+
+        # @api private
+        def require_component(component)
+          return if key?(component.identifier)
+
+          unless component.file_exists?(load_paths)
+            raise FileNotFoundError, component
+          end
+
+          Kernel.require(component.path) && yield
+        end
+
+        # @api private
+        def load_component(key)
+          return self if key?(key)
+
+          component(key).tap do |component|
+            root_key = component.root_key
+
+            if importer.key?(root_key)
+              load_external_component(component.namespaced(root_key))
+            else
+              load_local_component(component)
+            end
+          end
+
+          self
+        end
+
+        private
+
+        # @api private
+        def load_local_component(component, fallback = false)
+          if component.bootable?(booter.path) || component.file_exists?(load_paths)
+            booter.boot_dependency(component) unless frozen?
+
+            require_component(component) do
+              register(component.identifier) { component.instance }
+            end
+          elsif !fallback
+            load_local_component(component.prepend(config.default_namespace), true)
+          else
+            raise ComponentLoadError, component
+          end
+        end
+
+        # @api private
+        def load_external_component(component)
+          container = importer[component.namespace]
+          container.load_component(component.identifier)
+          importer.(component.namespace, container)
+        end
+      end
+    end
+  end
+end