hanami 2.0.0.beta4 → 2.0.0.rc1

data/lib/hanami/config/logger.rb

@@ -1,34 +1,116 @@
 # frozen_string_literal: true
 
 require "dry/configurable"
-require "hanami/logger"
+require "dry/logger"
 
 module Hanami
   class Config
     # Hanami logger config
     #
+    # @api public
     # @since 2.0.0
     class Logger
       include Dry::Configurable
 
+      # @return [Hanami::SliceName]
+      #
+      # @api private
+      # @since 2.0.o
       attr_reader :app_name
 
-      protected :config
-
+      # @!attribute [rw] level
+      #   Sets or returns the logger level.
+      #
+      #   Defaults to `:info` for the production environment and `:debug` for all others.
+      #
+      #   @return [Symbol]
+      #
+      #   @api public
+      #   @since 2.0.0
       setting :level
 
+      # @!attribute [rw] stream
+      #   Sets or returns the logger's stream.
+      #
+      #   This can be a file path or an `IO`-like object for the logger to write to.
+      #
+      #   Defaults to `"log/test.log"` for the test environment and `$stdout` for all others.
+      #
+      #   @return [String, #write]
+      #
+      #   @api public
+      #   @since 2.0.0
       setting :stream
 
+      # @!attribute [rw] formatter
+      #   Sets or returns the logger's formatter.
+      #
+      #   This may be a name that matches a formatter registered with `Dry::Logger`, which includes
+      #   `:string`, `:rack` and `:json`.
+      #
+      #   This may also be an instance of Ruby's built-in `::Logger::Formatter` or any compatible
+      #   object.
+      #
+      #   Defaults to `:json` for the production environment, and `:rack` for all others.
+      #
+      #   @return [Symbol, ::Logger::Formatter]
+      #
+      #   @api public
+      #   @since 2.0.0
       setting :formatter
 
-      setting :colors
-
+      # @!attribute [rw] template
+      #   Sets or returns log entry string template
+      #
+      #   Defaults to `false`.
+      #
+      #   @return [Boolean]
+      #
+      #   @api public
+      #   @since 2.0.0
+      setting :template, default: "[%<progname>s] [%<severity>s] [%<time>s] %<message>s"
+
+      # @!attribute [rw] filters
+      #   Sets or returns an array of attribute names to filter from logs.
+      #
+      #   Defaults to `["_csrf", "password", "password_confirmation"]`. If you want to preserve
+      #   these defaults, append to this array rather than reassigning it.
+      #
+      #   @return [Array<String>]
+      #
+      #   @api public
+      #   @since 2.0.0
       setting :filters, default: %w[_csrf password password_confirmation].freeze
 
-      setting :options, default: [], constructor: ->(value) { Array(value).flatten }, cloneable: true
-
-      setting :logger_class, default: Hanami::Logger
-
+      # @!attribute [rw] logger_constructor
+      #   Sets or returns the constructor proc to use for the logger instantiation.
+      #
+      #   Defaults to `Dry.method(:Logger)`.
+      #
+      #   @api public
+      #   @since 2.0.0
+      setting :logger_constructor, default: Dry.method(:Logger)
+
+      # @!attribute [rw] options
+      #   Sets or returns a hash of options to pass to the {logger_constructor} when initializing
+      #   the logger.
+      #
+      #   Defaults to `[]`
+      #
+      #   @return [Hash]
+      #
+      #   @api public
+      #   @since 2.0.0
+      setting :options, default: {}
+
+      # Returns a new `Logger` config.
+      #
+      # You should not need to initialize this directly, instead use {Hanami::Config#logger}.
+      #
+      # @param env [Symbol] the Hanami env
+      # @param app_name [Hanami::SliceName]
+      #
+      # @api private
       def initialize(env:, app_name:)
         @app_name = app_name
 
@@ -49,28 +131,34 @@ module Hanami
         config.formatter = case env
                            when :production
                              :json
+                           else
+                             :rack
                            end
-
-        config.colors = case env
-                        when :production, :test
-                          false
-                        end
       end
 
+      # Returns a new instance of the logger.
+      #
+      # @return [logger_class]
+      #
+      # @api public
+      # @since 2.0.0
       def instance
-        logger_class.new(
-          app_name.name,
-          *options,
-          stream: stream,
-          level: level,
-          formatter: formatter,
-          filter: filters,
-          colorizer: colors
-        )
+        logger_constructor.call(app_name.name, **logger_constructor_opts)
       end
 
       private
 
+      # @api private
+      def logger_constructor_opts
+        {stream: stream,
+          level: level,
+          formatter: formatter,
+          filters: filters,
+          template: template,
+          **options}
+      end
+
+      # @api private
       def method_missing(name, *args, &block)
         if config.respond_to?(name)
           config.public_send(name, *args, &block)
@@ -79,6 +167,7 @@ module Hanami
         end
       end
 
+      # @api private
       def respond_to_missing?(name, _incude_all = false)
         config.respond_to?(name) || super
       end

data/lib/hanami/config/router.rb

@@ -1,7 +1,6 @@
 # frozen_string_literal: true
 
 require "dry/configurable"
-require_relative "../slice/routing/resolver"
 
 module Hanami
   class Config

data/lib/hanami/config/views.rb

@@ -7,7 +7,9 @@ module Hanami
   class Config
     # Hanami views config
     #
-    # @since 2.0.0
+    # This is NOT RELEASED as of 2.0.0.
+    #
+    # @api private
     class Views
       include Dry::Configurable
 
@@ -16,6 +18,7 @@ module Hanami
       attr_reader :base_config
       protected :base_config
 
+      # @api private
       def initialize(*)
         super
 
@@ -24,21 +27,14 @@ module Hanami
         configure_defaults
       end
 
+      # @api private
       def initialize_copy(source)
         super
         @base_config = source.base_config.dup
       end
+      private :initialize_copy
 
-      # Returns the list of available settings
-      #
-      # @return [Set]
-      #
-      # @since 2.0.0
       # @api private
-      def settings
-        self.class.settings + View.settings - NON_FORWARDABLE_METHODS
-      end
-
       def finalize!
         return self if frozen?
 

data/lib/hanami/config.rb

@@ -1,33 +1,97 @@
 # frozen_string_literal: true
 
 require "uri"
-require "concurrent/hash"
-require "concurrent/array"
+require "pathname"
 require "dry/configurable"
 require "dry/inflector"
-require "pathname"
 
 require_relative "constants"
-require_relative "config/logger"
-require_relative "config/sessions"
-require_relative "settings/env_store"
-require_relative "slice/routing/middleware/stack"
 
 module Hanami
-  # Hanami app configuration
+  # Hanami app config
   #
   # @since 2.0.0
   class Config
     include Dry::Configurable
 
+    # @!attribute [rw] root
+    #   Sets the root for the app or slice.
+    #
+    #   For the app, this defaults to `Dir.pwd`. For slices detected in `slices/` `config/slices/`,
+    #   this defaults to `slices/[slice_name]/`.
+    #
+    #   Accepts a string path and will return a `Pathname`.
+    #
+    #   @return [Pathname]
+    #
+    #   @api public
+    #   @since 2.0.0
     setting :root, constructor: ->(path) { Pathname(path) if path }
 
-    setting :no_auto_register_paths, default: %w[entities]
-
+    # @!attribute [rw] inflector
+    #   Sets the app's inflector.
+    #
+    #   This expects a `Dry::Inflector` (or compatible) inflector instance.
+    #
+    #   To configure custom inflection rules without having to assign a whole inflector, see
+    #   {#inflections}.
+    #
+    #   @return [Dry::Inflector]
+    #
+    #   @see #inflections
+    #
+    #   @api public
+    #   @since 2.0.0
     setting :inflector, default: Dry::Inflector.new
 
+    # @!attribute [rw] settings_store
+    #   Sets the store used to retrieve {Hanami::Settings} values.
+    #
+    #   Defaults to an instance of {Hanami::Settings::EnvStore}.
+    #
+    #   @return [#fetch]
+    #
+    #   @see Hanami::Settings
+    #   @see Hanami::Settings::EnvStore#fetch
+    #
+    #   @api public
+    #   @since 2.0.0
     setting :settings_store, default: Hanami::Settings::EnvStore.new
 
+    # @!attribute [rw] slices
+    #   Sets the slices to load when the app is preared or booted.
+    #
+    #   Defaults to `nil`, which will load all slices. Set this to an array of slice names to load
+    #   only those slices.
+    #
+    #   This attribute is also populated from the `HANAMI_SLICES` environment variable.
+    #
+    #   @example
+    #     config.slices = ["admin", "search"]
+    #
+    #   @example
+    #     ENV["HANAMI_SLICES"] # => "admin,search"
+    #     config.slices # => ["admin", "search"]
+    #
+    #   @return [Array<String>, nil]
+    #
+    #   @api public
+    #   @since 2.0.0
+    setting :slices
+
+    # @!attribute [rw] shared_app_component_keys
+    #   Sets the keys for the components to be imported from the app into all other slices.
+    #
+    #   You should append items to this array, since the default shared components are essential for
+    #   slices to operate within the app.
+    #
+    #   @example
+    #     config.shared_app_component_keys += ["shared_component_a", "shared_component_b"]
+    #
+    #   @return [Array<String>]
+    #
+    #   @api public
+    #   @since 2.0.0
     setting :shared_app_component_keys, default: %w[
       inflector
       logger
@@ -37,73 +101,125 @@ module Hanami
       settings
     ]
 
-    setting :slices
+    # @!attribute [rw] no_auto_register_paths
+    #   Sets the paths to skip from container auto-registration.
+    #
+    #   Defaults to `["entities"]`.
+    #
+    #   @return [Array<String>] array of relative paths
+    #
+    #   @api public
+    #   @since 2.0.0
+    setting :no_auto_register_paths, default: %w[entities]
 
+    # @!attribute [rw] base_url
+    #   Sets the base URL for app's web server.
+    #
+    #   This is passed to the {Slice::ClassMethods#router router} and used for generating links.
+    #
+    #   Defaults to `"http://0.0.0.0:2300"`. String values passed are turned into `URI` instances.
+    #
+    #   @return [URI]
+    #
+    #   @see Slice::ClassMethods#router
+    #
+    #   @api public
+    #   @since 2.0.0
     setting :base_url, default: "http://0.0.0.0:2300", constructor: ->(url) { URI(url) }
 
-    setting :sessions, default: :null, constructor: ->(*args) { Sessions.new(*args) }
-
-    setting :logger, cloneable: true
-
-    DEFAULT_ENVIRONMENTS = Concurrent::Hash.new { |h, k| h[k] = Concurrent::Array.new }
-    private_constant :DEFAULT_ENVIRONMENTS
-
-    # @return [Symbol] The name of the application
+    # Returns the app or slice's {Hanami::SliceName slice_name}.
     #
-    # @api public
+    # This is useful for default config values that depend on this name.
+    #
+    # @return [Hanami::SliceName]
+    #
+    # @api private
+    # @since 2.0.0
     attr_reader :app_name
 
-    # @return [String] The current environment
+    # Returns the app's environment.
     #
-    # @api public
+    # @example
+    #   config.env # => :development
+    #
+    # @return [Symbol]
+    #
+    # @see #environment
+    #
+    # @api private
+    # @since 2.0.0
     attr_reader :env
 
-    # @return [Hanami::Config::Actions]
+    # Returns the app's actions config, or a null config if hanami-controller is not bundled.
+    #
+    # @example When hanami-controller is bundled
+    #   config.actions.default_request_format # => :html
+    #
+    # @example When hanami-controller is not bundled
+    #   config.actions.default_request_format # => NoMethodError
+    #
+    # @return [Hanami::Config::Actions, Hanami::Config::NullConfig]
     #
     # @api public
+    # @since 2.0.0
     attr_reader :actions
 
-    # @return [Hanami::Slice::Routing::Middleware::Stack]
+    # Returns the app's middleware stack, or nil if hanami-router is not bundled.
+    #
+    # Use this to configure middleware that should apply to all routes.
+    #
+    # @example
+    #   config.middleware.use :body_parser, :json
+    #   config.middleware.use MyCustomMiddleware
+    #
+    # @return [Hanami::Slice::Routing::Middleware::Stack, nil]
     #
     # @api public
+    # @since 2.0.0
     attr_reader :middleware
 
     # @api private
+    # @since 2.0.0
     alias_method :middleware_stack, :middleware
 
-    # @return [Hanami::Config::Router]
+    # Returns the app's router config, or a null config if hanami-router is not bundled.
+    #
+    # @example When hanami-router is bundled
+    #   config.router.resolver # => Hanami::Slice::Routing::Resolver
+    #
+    # @example When hanami-router is not bundled
+    #   config.router.resolver # => NoMethodError
+    #
+    # @return [Hanami::Config::Router, Hanami::Config::NullConfig]
     #
     # @api public
+    # @since 2.0.0
     attr_reader :router
 
-    # @return [Hanami::Config::Views]
+    # Returns the app's views config, or a null config if hanami-view is not bundled.
     #
-    # @api public
+    # This is NOT RELEASED as of 2.0.0.
+    #
+    # @api private
     attr_reader :views
 
-    # @return [Hanami::Assets::AppConfiguration]
+    # Returns the app's assets config.
     #
-    # @api public
-    attr_reader :assets
-
-    # @return [Concurrent::Hash] A hash of default environments
+    # This is NOT RELEASED as of 2.0.0.
     #
     # @api private
-    attr_reader :environments
-    private :environments
+    attr_reader :assets
 
     # @api private
     def initialize(app_name:, env:)
       @app_name = app_name
-
-      @environments = DEFAULT_ENVIRONMENTS.clone
       @env = env
 
       # Apply default values that are only knowable at initialize-time (vs require-time)
       self.root = Dir.pwd
       load_from_env
 
-      config.logger = Config::Logger.new(env: env, app_name: app_name)
+      @logger = Config::Logger.new(env: env, app_name: app_name)
 
       # TODO: Make assets config dependent
       require "hanami/assets/app_config"
@@ -128,37 +244,11 @@ module Hanami
       yield self if block_given?
     end
 
-    # Apply config for the given environment
-    #
-    # @param env [String] the environment name
-    #
-    # @return [Hanami::Config]
-    #
-    # @api public
-    def environment(env_name, &block)
-      environments[env_name] << block
-      apply_env_config
-
-      self
-    end
-
-    # Configure application's inflections
-    #
-    # @see https://dry-rb.org/gems/dry-inflector
-    #
-    # @return [Dry::Inflector]
-    #
-    # @api public
-    def inflections(&block)
-      self.inflector = Dry::Inflector.new(&block)
-    end
-
     # @api private
     def initialize_copy(source)
       super
 
       @app_name = app_name.dup
-      @environments = environments.dup
 
       @assets = source.assets.dup
       @actions = source.actions.dup
@@ -168,11 +258,15 @@ module Hanami
       end
       @views = source.views.dup
     end
+    private :initialize_copy
 
+    # Finalizes the config.
+    #
+    # This is called when the app or slice is prepared. After this, no further changes to config can
+    # be made.
+    #
     # @api private
     def finalize!
-      apply_env_config
-
       # Finalize nested configs
       assets.finalize!
       actions.finalize!
@@ -183,16 +277,90 @@ module Hanami
       super
     end
 
-    # Set a default global logger instance
+    # Configures the app's custom inflections.
+    #
+    # You should call this one time only. Subsequent calls will override previously configured
+    # inflections.
+    #
+    # @example
+    #   config.inflections do |inflections|
+    #     inflections.acronym "WNBA"
+    #   end
+    #
+    # @see https://dry-rb.org/gems/dry-inflector
+    #
+    # @return [Dry::Inflector] the configured inflector
+    #
+    # @api public
+    # @since 2.0.0
+    def inflections(&block)
+      self.inflector = Dry::Inflector.new(&block)
+    end
+
+    # Disabling this to permit distinct documentation for `#logger` vs `#logger=`
+    #
+    # rubocop:disable Style/TrivialAccessors
+
+    # Returns the logger config.
+    #
+    # Use this to configure various options for the default `Dry::Logger::Dispatcher` logger instance.
+    #
+    # @example
+    #   config.logger.level = :debug
+    #
+    # @return [Hanami::Config::Logger]
+    #
+    # @see Hanami::Config::Logger
+    #
+    # @api public
+    # @since 2.0.0
+    def logger
+      @logger
+    end
+
+    # Sets the app's logger instance.
+    #
+    # This entirely replaces the default `Dry::Logger::Dispatcher` instance that would have been
+    #
+    # @see #logger_instance
     #
     # @api public
+    # @since 2.0.0
     def logger=(logger_instance)
       @logger_instance = logger_instance
     end
 
-    # Return configured logger instance
+    # rubocop:enable Style/TrivialAccessors
+
+    # Returns the configured logger instance.
+    #
+    # Unless you've replaced the logger with {#logger=}, this returns a `Dry::Logger::Dispatcher` configured
+    # with the options configured through {#logger}.
+    #
+    # This configured logger is registered in all app and slice containers as `"logger"`. For
+    # typical usage, you should access the logger via this component, not directly from config.
+    #
+    # @example Accessing the logger component
+    #   Hanami.app["logger"] # => #<Dry::Logger::Dispatcher>
+    #
+    # @example Injecting the logger as a dependency
+    #   module MyApp
+    #     class MyClass
+    #       include Deps["logger"]
+    #
+    #       def my_method
+    #         logger.info("hello")
+    #       end
+    #     end
+    #   end
+    #
+    # @return [Dry::Logger::Dispatcher]
+    #
+    # @see #logger
+    # @see Hanami::Config::Logger
     #
     # @api public
+    # @since 2.0.0
     def logger_instance
       @logger_instance || logger.instance
     end
@@ -203,12 +371,6 @@ module Hanami
       self.slices = ENV["HANAMI_SLICES"]&.split(",")&.map(&:strip)
     end
 
-    def apply_env_config(env = self.env)
-      environments[env].each do |block|
-        instance_eval(&block)
-      end
-    end
-
     # @api private
     def load_dependent_config(gem_name)
       if Hanami.bundled?(gem_name)

data/lib/hanami/constants.rb

@@ -13,6 +13,10 @@ module Hanami
   PATH_DELIMITER = "/"
   private_constant :PATH_DELIMITER
 
+  # @api private
+  APP_PATH = "config/app.rb"
+  private_constant :APP_PATH
+
   # @api private
   CONFIG_DIR = "config"
   private_constant :CONFIG_DIR

data/lib/hanami/errors.rb

@@ -1,18 +1,35 @@
 # frozen_string_literal: true
 
 module Hanami
+  # Base class for all Hanami errors.
+  #
+  # @api public
   # @since 2.0.0
   Error = Class.new(StandardError)
 
+  # Error raised when {Hanami::App} fails to load.
+  #
+  # @api public
   # @since 2.0.0
   AppLoadError = Class.new(Error)
 
+  # Error raised when an {Hanami::Slice} fails to load.
+  #
+  # @api public
   # @since 2.0.0
   SliceLoadError = Class.new(Error)
 
+  # Error raised when an individual component fails to load.
+  #
+  # @api public
   # @since 2.0.0
   ComponentLoadError = Class.new(Error)
 
+  # Error raised when unsupported middleware configuration is given.
+  #
+  # @see Hanami::Slice::Routing::Middleware::Stack#use
+  #
+  # @api public
   # @since 2.0.0
   UnsupportedMiddlewareSpecError = Class.new(Error)
 end