hanami 2.0.0.beta4 → 2.0.0.rc1

data/lib/hanami/extensions/action/slice_configured_action.rb

@@ -1,7 +1,5 @@
 # frozen_string_literal: true
 
-require "hanami/action"
-
 module Hanami
   module Extensions
     module Action
@@ -35,12 +33,14 @@ module Hanami
           resolve_view = method(:resolve_paired_view)
           resolve_view_context = method(:resolve_view_context)
           resolve_routes = method(:resolve_routes)
+          resolve_rack_monitor = method(:resolve_rack_monitor)
 
           define_method(:new) do |**kwargs|
             super(
               view: kwargs.fetch(:view) { resolve_view.(self) },
               view_context: kwargs.fetch(:view_context) { resolve_view_context.() },
               routes: kwargs.fetch(:routes) { resolve_routes.() },
+              rack_monitor: kwargs.fetch(:rack_monitor) { resolve_rack_monitor.() },
               **kwargs,
             )
           end
@@ -86,12 +86,12 @@ module Hanami
             # the `:json` value configured in its immediate superclass.
             #
             # This would be surprising behavior, and we want to avoid it.
-            slice_value = slice.config.actions.public_send(:"#{setting}")
-            parent_value = slice.parent.config.actions.public_send(:"#{setting}") if slice.parent
+            slice_value = slice.config.actions.public_send(setting.name)
+            parent_value = slice.parent.config.actions.public_send(setting.name) if slice.parent
 
             next if slice.parent && slice_value == parent_value
 
-            action_class.config.public_send(:"#{setting}=", slice_value)
+            action_class.config.public_send(:"#{setting.name}=", slice_value)
           end
         end
 
@@ -137,6 +137,10 @@ module Hanami
           slice.app["routes"] if slice.app.key?("routes")
         end
 
+        def resolve_rack_monitor
+          slice.app["rack.monitor"] if slice.app.key?("rack.monitor")
+        end
+
         def actions_config
           slice.config.actions
         end

data/lib/hanami/extensions/action.rb

@@ -1,18 +1,19 @@
 # frozen_string_literal: true
 
 require "hanami/action"
-require_relative "../slice_configurable"
-require_relative "action/slice_configured_action"
 
 module Hanami
+  # @api private
   module Extensions
-    # Extended behavior for actions intended for use within an Hanami app.
+    # Integrated behavior for `Hanami::Action` classes within Hanami apps.
     #
-    # @see Hanami::Action
+    # @see InstanceMethods
+    # @see https://github.com/hanami/controller
     #
     # @api public
     # @since 2.0.0
     module Action
+      # @api private
       def self.included(action_class)
         super
 
@@ -21,46 +22,97 @@ module Hanami
         action_class.prepend(InstanceMethods)
       end
 
+      # Class methods for app-integrated actions.
+      #
+      # @since 2.0.0
       module ClassMethods
+        # @api private
         def configure_for_slice(slice)
           extend SliceConfiguredAction.new(slice)
         end
       end
 
+      # Instance methods for app-integrated actions.
+      #
+      # @since 2.0.0
       module InstanceMethods
-        attr_reader :view, :view_context, :routes
+        # @api private
+        attr_reader :view
 
-        def initialize(view: nil, view_context: nil, routes: nil, **kwargs)
+        # @api private
+        attr_reader :view_context
+
+        # Returns the app or slice's {Hanami::Slice::RoutesHelper RoutesHelper} for use within
+        # action instance methods.
+        #
+        # @return [Hanami::Slice::RoutesHelper]
+        #
+        # @api public
+        # @since 2.0.0
+        attr_reader :routes
+
+        # Returns the app or slice's `Dry::Monitor::Rack::Middleware` for use within
+        # action instance methods.
+        #
+        # @return [Dry::Monitor::Rack::Middleware]
+        #
+        # @api public
+        # @since 2.0.0
+        attr_reader :rack_monitor
+
+        # @overload def initialize(routes: nil, **kwargs)
+        #   Returns a new `Hanami::Action` with app components injected as dependencies.
+        #
+        #   These dependencies are injected automatically so that a call to `.new` (with no
+        #   arguments) returns a fully integrated action.
+        #
+        #   @param routes [Hanami::Slice::RoutesHelper]
+        #
+        #   @api public
+        #   @since 2.0.0
+        def initialize(view: nil, view_context: nil, rack_monitor: nil, routes: nil, **kwargs)
           @view = view
           @view_context = view_context
           @routes = routes
+          @rack_monitor = rack_monitor
 
           super(**kwargs)
         end
 
         private
 
+        # @api private
         def build_response(**options)
           options = options.merge(view_options: method(:view_options))
           super(**options)
         end
 
+        # @api private
         def finish(req, res, halted)
           res.render(view, **req.params) if !halted && auto_render?(res)
           super
         end
 
+        # @api private
+        def _handle_exception(request, _response, exception)
+          rack_monitor&.instrument(:error, exception: exception, env: request.env)
+
+          super
+        end
+
+        # @api private
         def view_options(req, res)
           {context: view_context&.with(**view_context_options(req, res))}.compact
         end
 
+        # @api private
         def view_context_options(req, res)
           {request: req, response: res}
         end
 
         # Returns true if a view should automatically be rendered onto the response body.
         #
-        # This may be overridden to enable/disable automatic rendering.
+        # This may be overridden to enable or disable automatic rendering.
         #
         # @param res [Hanami::Action::Response]
         #

data/lib/hanami/extensions/view/context.rb

@@ -3,16 +3,15 @@
 require "hanami/view"
 require "hanami/view/context"
 require_relative "../../errors"
-require_relative "../../slice_configurable"
-require_relative "slice_configured_context"
 
 module Hanami
   module Extensions
     module View
       # View context for views in Hanami apps.
       #
-      # @api public
-      # @since 2.0.0
+      # This is NOT RELEASED as of 2.0.0.
+      #
+      # @api private
       module Context
         def self.included(context_class)
           super

data/lib/hanami/extensions/view/slice_configured_view.rb

@@ -32,7 +32,7 @@ module Hanami
         # rubocop:disable Metrics/AbcSize
         def configure_view(view_class)
           view_class.settings.each do |setting|
-            next unless slice.config.views.respond_to?(:"#{setting}")
+            next unless slice.config.views.respond_to?(setting.name)
 
             # Configure the view from config on the slice, _unless it has already been configured by
             # a parent slice_, and re-configuring it for this slice would make no change.
@@ -72,12 +72,12 @@ module Hanami
             # in its immediate superclass.
             #
             # This would be surprising behavior, and we want to avoid it.
-            slice_value = slice.config.views.public_send(:"#{setting}")
-            parent_value = slice.parent.config.views.public_send(:"#{setting}") if slice.parent
+            slice_value = slice.config.views.public_send(setting.name)
+            parent_value = slice.parent.config.views.public_send(setting.name) if slice.parent
 
             next if slice.parent && slice_value == parent_value
 
-            view_class.config.public_send(:"#{setting}=", slice_value)
+            view_class.config.public_send(:"#{setting.name}=", slice_value)
           end
 
           view_class.config.inflector = inflector

data/lib/hanami/extensions/view.rb

@@ -1,18 +1,19 @@
 # frozen_string_literal: true
 
 require "hanami/view"
-require_relative "../slice_configurable"
-require_relative "view/slice_configured_view"
 
 module Hanami
+  # @api private
   module Extensions
-    # Extended behavior for actions intended for use within an Hanami app.
+    # Integrated behavior for `Hanami::View` classes within Hanami apps.
+    #
+    # This is NOT RELEASED as of 2.0.0.
     #
     # @see Hanami::View
     #
-    # @api public
-    # @since 2.0.0
+    # @api private
     module View
+      # @api private
       def self.included(view_class)
         super
 
@@ -20,6 +21,7 @@ module Hanami
         view_class.extend(ClassMethods)
       end
 
+      # @api private
       module ClassMethods
         # @api private
         def configure_for_slice(slice)

data/lib/hanami/providers/inflector.rb

@@ -1,8 +1,14 @@
 # frozen_string_literal: true
 
 module Hanami
+  # @api private
   module Providers
+    # Provider source to register inflector component in Hanami slices.
+    #
+    # @api private
+    # @since 2.0.0
     class Inflector < Dry::System::Provider::Source
+      # @api private
       def start
         register :inflector, Hanami.app.inflector
       end

data/lib/hanami/providers/logger.rb

@@ -1,8 +1,16 @@
 # frozen_string_literal: true
 
 module Hanami
+  # @api private
   module Providers
+    # Provider source to register logger component in Hanami slices.
+    #
+    # @see Hanami::Config#logger
+    #
+    # @api private
+    # @since 2.0.0
     class Logger < Dry::System::Provider::Source
+      # @api private
       def start
         register :logger, Hanami.app.config.logger_instance
       end

data/lib/hanami/providers/rack.rb

@@ -1,8 +1,19 @@
 # frozen_string_literal: true
 
 module Hanami
+  # @api private
   module Providers
+    # Provider source to register Rack integration components in Hanami slices.
+    #
+    # @see Hanami::Providers::Logger
+    # @see Hanami::Web::RackLogger
+    # @see https://github.com/rack/rack
+    # @see https://dry-rb.org/gems/dry-monitor/
+    #
+    # @api private
+    # @since 2.0.0
     class Rack < Dry::System::Provider::Source
+      # @api private
       def prepare
         require "dry/monitor"
         require "hanami/web/rack_logger"
@@ -10,6 +21,7 @@ module Hanami
         Dry::Monitor.load_extensions(:rack)
       end
 
+      # @api private
       def start
         target.start :logger
 

data/lib/hanami/providers/routes.rb

@@ -1,27 +1,37 @@
 # frozen_string_literal: true
 
 module Hanami
+  # @api private
   module Providers
+    # Provider source to register routes helper component in Hanami slices.
+    #
+    # @see Hanami::Slice::RoutesHelper
+    #
+    # @api private
+    # @since 2.0.0
     class Routes < Dry::System::Provider::Source
+      # @api private
       def self.for_slice(slice)
         Class.new(self) do |klass|
           klass.instance_variable_set(:@slice, slice)
         end
       end
 
+      # @api private
       def self.slice
         @slice || Hanami.app
       end
 
+      # @api private
       def prepare
         require "hanami/slice/routes_helper"
       end
 
+      # @api private
       def start
-        # Register a lazy instance of RoutesHelper to ensure we don't load prematurely
-        # load the router during the process of booting. This ensures the router's
-        # resolver can run strict action key checks once when it runs on a fully booted
-        # slice.
+        # Register a lazy instance of RoutesHelper to ensure we don't load prematurely load the
+        # router during the process of booting. This ensures the router's resolver can run strict
+        # action key checks once when it runs on a fully booted slice.
         register :routes do
           Hanami::Slice::RoutesHelper.new(self.class.slice.router)
         end

data/lib/hanami/routes.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
-require "hanami/slice/router"
+require_relative "constants"
+require_relative "errors"
 
 module Hanami
   # App routes
@@ -25,6 +26,40 @@ module Hanami
   # @see Hanami::Slice::Router
   # @since 2.0.0
   class Routes
+    # Error raised when no action could be found in an app or slice container for the key given in a
+    # routes file.
+    #
+    # @api public
+    # @since 2.0.0
+    class MissingActionError < Hanami::Error
+      # @api private
+      def initialize(action_key, slice)
+        action_path = action_key.gsub(CONTAINER_KEY_DELIMITER, PATH_DELIMITER)
+        action_constant = slice.inflector.camelize(
+          "#{slice.inflector.underscore(slice.namespace.to_s)}#{PATH_DELIMITER}#{action_path}"
+        )
+        action_file = slice.root.join("#{action_path}#{RB_EXT}")
+
+        super(<<~MSG)
+          Could not find action with key #{action_key.inspect} in #{slice}
+
+          To fix this, define the action class #{action_constant} in #{action_file}
+        MSG
+      end
+    end
+
+    # Error raised when a given routes endpoint does not implement the `#call` interface required
+    # for Rack.
+    #
+    # @api public
+    # @since 2.0.0
+    class NotCallableEndpointError < Hanami::Error
+      # @api private
+      def initialize(endpoint)
+        super("#{endpoint.inspect} is not compatible with Rack. Please make sure it implements #call.")
+      end
+    end
+
     # @api private
     def self.routes
       @routes ||= build_routes

data/lib/hanami/settings/env_store.rb

@@ -4,7 +4,7 @@ require "dry/core/constants"
 
 module Hanami
   class Settings
-    # The default store for {Hanami:Settings}, loading setting values from `ENV`.
+    # The default store for {Hanami::Settings}, loading setting values from `ENV`.
     #
     # If your app loads the dotenv gem, then `ENV` will also be populated from various `.env` files when
     # you subclass `Hanami::App`.

data/lib/hanami/settings.rb

@@ -1,43 +1,95 @@
 # frozen_string_literal: true
 
-require "dry/core"
+require "dry/core/constants"
 require "dry/configurable"
+require_relative "errors"
 
 module Hanami
-  # App settings
+  # Provides user-defined settings for an Hanami app or slice.
   #
-  # Users are expected to inherit from this class to define their app settings.
+  # Define your own settings by inheriting from this class in `config/settings.rb` within an app or
+  # slice. Your settings will be loaded from matching ENV vars (with upper-cased names) and made
+  # registered as a component as part of the Hanami app {Hanami::Slice::ClassMethods#prepare
+  # prepare} step.
+  #
+  # The settings instance is registered in your app and slice containers as a `"settings"`
+  # component. You can use the `Deps` mixin to inject this dependency and make settings available to
+  # your other components as required.
   #
   # @example
   #   # config/settings.rb
   #   # frozen_string_literal: true
   #
-  #   require "hanami/settings"
-  #   require "my_app/types"
-  #
   #   module MyApp
   #     class Settings < Hanami::Settings
-  #       setting :database_url
-  #       setting :feature_flag, default: false, constructor: Types::Params::Bool
+  #       Secret = Types::String.constrained(min_size: 20)
+  #
+  #       setting :database_url, constructor: Types::String
+  #       setting :session_secret, constructor: Secret
+  #       setting :some_flag, default: false, constructor: Types::Params::Bool
   #     end
   #   end
   #
-  # Settings are defined with [dry-configurable](https://dry-rb.org/gems/dry-configurable/), so you
-  # can take a look there to see the supported syntax.
+  # Settings are defined with [dry-configurable][dry-c]'s `setting` method. You may likely want to
+  # provide `default:` and `constructor:` options for your settings.
+  #
+  # If you have [dry-types][dry-t] bundled, then a nested `Types` module will be available for type
+  # checking your setting values. Pass type objects to the setting `constructor:` options to ensure
+  # their values meet your type expectations. You can use dry-types' default type objects or define
+  # your own.
   #
-  # Users work with an instance of this class made available within the `settings` key in the
-  # container. The instance gets its settings populated from a configurable store, which defaults to
-  # {Hanami::Settings::EnvStore}.
+  # When the settings are initialized, all type errors will be collected and presented together for
+  # correction. Settings are loaded early, as part of the Hanami app's
+  # {Hanami::Slice::ClassMethods#prepare prepare} step, to ensure that the app boots only when valid
+  # settings are present.
   #
-  # A different store can be set through the `settings_store` Hanami configuration option. All it
-  # needs to do is implementing a `#fetch` method with the same signature as `Hash#fetch`.
+  # Setting values are loaded from a configurable store, which defaults to
+  # {Hanami::Settings::EnvStore}, which fetches the values from equivalent upper-cased keys in
+  # `ENV`. You can configue an alternative store via {Hanami::Config#settings_store}. Setting stores
+  # must implement a `#fetch` method with the same signature as `Hash#fetch`.
+  #
+  # [dry-c]: https://dry-rb.org/gems/dry-configurable/
+  # [dry-t]: https://dry-rb.org/gems/dry-types/
   #
   # @see Hanami::Settings::DotenvStore
   #
   # @api public
   # @since 2.0.0
   class Settings
+    # Error raised when setting values do not meet their type expectations.
+    #
+    # Its message collects all the individual errors that can be raised for each setting.
+    #
+    # @api public
+    # @since 2.0.0
+    class InvalidSettingsError < Hanami::Error
+      # @api private
+      def initialize(errors)
+        super()
+        @errors = errors
+      end
+
+      # Returns the exception's message.
+      #
+      # @return [String]
+      #
+      # @api public
+      # @since 2.0.0
+      def to_s
+        <<~STR.strip
+          Could not initialize settings. The following settings were invalid:
+
+          #{@errors.map { |setting, message| "#{setting}: #{message}" }.join("\n")}
+        STR
+      end
+    end
+
     class << self
+      # Defines a nested `Types` constant in `Settings` subclasses if dry-types is bundled.
+      #
+      # @see https://dry-rb.org/gems/dry-types
+      #
+      # @api private
       def inherited(subclass)
         super
 
@@ -94,25 +146,6 @@ module Hanami
       end
     end
 
-    # Exception for errors in the definition of settings.
-    #
-    # Its message collects all the individual errors that can be raised for each setting.
-    #
-    # @api public
-    InvalidSettingsError = Class.new(StandardError) do
-      def initialize(errors)
-        @errors = errors
-      end
-
-      def to_s
-        <<~STR.strip
-          Could not initialize settings. The following settings were invalid:
-
-          #{@errors.map { |setting, message| "#{setting}: #{message}" }.join("\n")}
-        STR
-      end
-    end
-
     # @api private
     Undefined = Dry::Core::Constants::Undefined
 
@@ -143,14 +176,47 @@ module Hanami
       config.finalize!
     end
 
+    # Returns a string containing a human-readable representation of the settings.
+    #
+    # This includes setting names only, not any values, to ensure that sensitive values do not
+    # inadvertently leak.
+    #
+    # Use {#inspect_values} to inspect settings with their values.
+    #
+    # @example
+    #   settings.inspect
+    #   # => #<MyApp::Settings [database_url, session_secret, some_flag]>
+    #
+    # @return [String]
+    #
+    # @see #inspect_values
+    #
+    # @api public
+    # @since 2.0.0
     def inspect
-      "#<#{self.class.to_s} [#{config._settings.map(&:name).join(", ")}]>"
+      "#<#{self.class} [#{config._settings.map(&:name).join(", ")}]>"
     end
 
+    # rubocop:disable Layout/LineLength
+
+    # Returns a string containing a human-readable representation of the settings and their values.
+    #
+    # @example
+    #   settings.inspect_values
+    #   # => #<MyApp::Settings database_url="postgres://localhost/my_db", session_secret="xxx", some_flag=true]>
+    #
+    # @return [String]
+    #
+    # @see #inspect
+    #
+    # @api public
+    # @since 2.0.0
     def inspect_values
-      "#<#{self.class.to_s} #{config._settings.map { |setting| "#{setting.name}=#{config[setting.name].inspect}" }.join(" ")}>"
+      "#<#{self.class} #{config._settings.map { |setting| "#{setting.name}=#{config[setting.name].inspect}" }.join(" ")}>"
     end
 
+    # rubocop:enable Layout/LineLength
+
     private
 
     def method_missing(name, *args, &block)