hanami 2.3.2 → 3.0.0.rc1

data/lib/hanami/providers/i18n/backend.rb

@@ -0,0 +1,369 @@
+# frozen_string_literal: true
+
+module Hanami
+  module Providers
+    class I18n < Hanami::Provider::Source
+      # A wrapper that provides a full `I18n`-like interface for an individual I18n backend. This
+      # allows each Hanami slice to have its own isolated I18n instance.
+      #
+      # Unlike the global I18n module which uses class variables for configuration,
+      # this wrapper maintains per-instance state for true isolation between slices.
+      #
+      # @api public
+      # @since x.x.x
+      class Backend
+        attr_reader :backend
+
+        # Returns the default locale.
+        #
+        # @return [Symbol] the default locale
+        #
+        # @api public
+        # @since x.x.x
+        attr_reader :default_locale
+
+        # Creates a new Backend instance.
+        #
+        # @param backend [I18n::Backend::Base] the underlying I18n backend
+        # @param locale [Symbol, String, nil] initial locale to set in thread-local storage
+        # @param default_locale [Symbol, String] the default locale to use when no locale is set
+        # @param available_locales [Array<Symbol, String>] list of available locales
+        # @param fallbacks [I18n::Locale::Fallbacks, nil] fallbacks configuration for missing translations
+        #
+        # @api private
+        # @since x.x.x
+        def initialize(backend, locale: nil, default_locale: :en, available_locales: [], fallbacks: nil)
+          @backend = backend
+          @default_locale = default_locale.to_sym
+          @available_locales = Array(available_locales).map(&:to_sym)
+          @fallbacks = fallbacks
+
+          # Set initial locale (if provided) in thread-local storage.
+          @storage_key = :"hanami_i18n_#{object_id}"
+          self.locale = locale if locale
+        end
+
+        # rubocop:disable Metrics/PerceivedComplexity
+
+        # Translates the given key.
+        #
+        # @param key [String, Symbol] the translation key to look up
+        # @param options [Hash] translation options
+        # @option options [Symbol, String] :locale the locale to use (defaults to current locale)
+        # @option options [String, Proc, Array] :default default value if translation is missing
+        # @option options [Hash] :scope additional scope for the key
+        # @option options [Integer] :count for pluralization
+        # @option options [Boolean] :raise whether to raise an exception for missing translations
+        #
+        # @return [String, Object] the translated string or default value
+        #
+        # @raise [I18n::MissingTranslationData] if translation is missing and :raise option is true
+        #
+        # @example Basic translation
+        #   translate("hello") # => "Hello"
+        #
+        # @example Translation with interpolation
+        #   translate("greeting", name: "Alice") # => "Hello, Alice"
+        #
+        # @example With explicit locale
+        #   translate("hello", locale: :fr) # => "Bonjour"
+        #
+        # @api public
+        # @since x.x.x
+        def translate(key, **options)
+          locale = options[:locale] || self.locale
+
+          result = catch(:exception) do
+            @backend.translate(locale, key, options)
+          end
+
+          # If translation is missing and fallbacks are configured, try fallback locales
+          if result.is_a?(::I18n::MissingTranslation) && @fallbacks && !options[:fallback]
+            fallback_locales = @fallbacks[locale] - [locale]
+            fallback_locales.each do |fallback_locale|
+              fallback_result = catch(:exception) do
+                @backend.translate(fallback_locale, key, options.merge(fallback: true))
+              end
+
+              unless fallback_result.is_a?(::I18n::MissingTranslation)
+                return fallback_result
+              end
+            end
+          end
+
+          if result.is_a?(::I18n::MissingTranslation)
+            if options[:raise]
+              raise ::I18n::MissingTranslationData.new(locale, key, options)
+            else
+              handle_missing_translation(result, options)
+            end
+          else
+            result
+          end
+        end
+
+        # rubocop:enable Metrics/PerceivedComplexity
+
+        # @api public
+        # @since x.x.x
+        alias_method :t, :translate
+
+        # Translates the given key, raising an exception if translation is missing.
+        #
+        # @param key [String, Symbol] the translation key to look up
+        # @param options [Hash] translation options (see {#translate})
+        #
+        # @return [String, Object] the translated string
+        #
+        # @raise [I18n::MissingTranslationData] if translation is missing
+        #
+        # @example
+        #   t!("hello") # => "Hello"
+        #   t!("missing.key") # raises I18n::MissingTranslationData
+        #
+        # @api public
+        # @since x.x.x
+        def t!(key, **options)
+          translate(key, **options.merge(raise: true))
+        end
+
+        # Localizes the given date or time.
+        #
+        # Resolves symbol formats through this instance's translations (e.g. `:short` becomes
+        # `date.formats.short` or `time.formats.short`). Also resolves locale-dependent strftime
+        # codes (e.g. `%a`, `%A`, `%b`, `%B`, `%p`, `%P`).
+        #
+        # @param object [Date, Time, DateTime] the object to localize
+        # @param locale [Symbol, String, nil] the locale to use (defaults to current locale)
+        # @param format [Symbol, String] the format to use for localization
+        # @param options [Hash] additional localization options
+        #
+        # @return [String] the localized string representation
+        #
+        # @example Localize a date
+        #   localize(Date.today, format: :long) # => "January 19, 2026"
+        #
+        # @example Localize with specific locale
+        #   localize(Date.today, locale: :fr, format: :long) # => "19 janvier 2026"
+        #
+        # @api public
+        # @since x.x.x
+        def localize(object, locale: nil, format: :default, **options)
+          locale ||= self.locale
+
+          return options[:default] if object.nil? && options.key?(:default)
+
+          unless object.respond_to?(:strftime)
+            raise ArgumentError, <<~MSG
+              Object must be a Date, DateTime or Time object. #{object.inspect} given.
+            MSG
+          end
+
+          if format.is_a?(Symbol)
+            type = object.respond_to?(:sec) ? "time" : "date"
+            format = translate(
+              :"#{type}.formats.#{format}",
+              **options, locale:, object:, raise: true
+            )
+          end
+
+          format = expand_localization_format(locale, object, format)
+          object.strftime(format)
+        end
+
+        # @api public
+        # @since x.x.x
+        alias_method :l, :localize
+
+        # Returns true if a translation exists for the given key.
+        #
+        # @param key [String, Symbol] the translation key to check
+        # @param locale [Symbol, String, nil] the locale to check (defaults to current locale)
+        # @param options [Hash] additional options
+        #
+        # @return [Boolean] true if the translation exists, false otherwise
+        #
+        # @example
+        #   exists?("hello") # => true
+        #   exists?("missing.key") # => false
+        #
+        # @api public
+        # @since x.x.x
+        def exists?(key, locale: nil, **options)
+          locale ||= self.locale
+          @backend.exists?(locale, key, options)
+        end
+
+        # Transliterates the given string.
+        #
+        # @param key [String] the string to transliterate
+        # @param locale [Symbol, String, nil] the locale to use (defaults to current locale)
+        # @param replacement [String, nil] replacement string for non-transliteratable characters
+        # @param options [Hash] additional transliteration options
+        #
+        # @return [String] the transliterated string
+        #
+        # @example
+        #   transliterate("Ærøskøbing") # => "AEroskobing"
+        #
+        # @api public
+        # @since x.x.x
+        def transliterate(key, locale: nil, replacement: nil, **options)
+          locale ||= self.locale
+          @backend.transliterate(locale, key, replacement)
+        end
+
+        # Returns available locales.
+        #
+        # If configured via `config.i18n.available_locales`, returns the configured locales.
+        # Otherwise, returns all locales detected from loaded translation files.
+        #
+        # @api public
+        # @since x.x.x
+        def available_locales
+          if @available_locales.any?
+            @available_locales
+          else
+            @backend.available_locales
+          end
+        end
+
+        # Reloads translations from translation files.
+        #
+        # @return [void]
+        #
+        # @api public
+        # @since x.x.x
+        def reload!
+          @backend.reload!
+        end
+
+        # Eager loads translations if the backend supports it.
+        #
+        # @return [void]
+        #
+        # @api public
+        # @since x.x.x
+        def eager_load!
+          @backend.eager_load! if @backend.respond_to?(:eager_load!)
+        end
+
+        # Returns the current locale from fiber/thread-local storage, or default_locale.
+        #
+        # This is thread-safe and works correctly with concurrent requests.
+        # Each backend instance maintains its own locale in thread storage.
+        #
+        # @return [Symbol] the current locale or default locale if none is set
+        #
+        # @example
+        #   locale # => :en
+        #   self.locale = :fr
+        #   locale # => :fr
+        #
+        # @api public
+        # @since x.x.x
+        def locale
+          Thread.current[@storage_key] || default_locale
+        end
+
+        # Sets the current locale in fiber/thread-local storage.
+        #
+        # This is thread-safe and works correctly with concurrent requests.
+        # Each backend instance maintains its own locale in thread storage.
+        #
+        # @param value [Symbol, String, nil] the locale to set (converted to symbol)
+        #
+        # @return [Symbol, nil] the locale value that was set
+        #
+        # @example
+        #   self.locale = :fr
+        #   self.locale = "de"
+        #   self.locale = nil # resets to default_locale
+        #
+        # @api public
+        # @since x.x.x
+        def locale=(value)
+          Thread.current[@storage_key] = value&.to_sym
+        end
+
+        # Executes a block with a temporary locale.
+        #
+        # This is useful for executing code with a specific locale without affecting
+        # other concurrent requests. The previous locale is restored even if the block raises.
+        #
+        # @param tmp_locale [Symbol, String, nil] the temporary locale to use
+        #
+        # @yieldreturn [Object] the return value of the block
+        #
+        # @return [Object] the return value of the block
+        #
+        # @example
+        #   with_locale(:fr) do
+        #     t("greeting") # Uses French locale
+        #   end
+        #   # locale is restored to previous value
+        #
+        # @example Nested usage
+        #   with_locale(:fr) do
+        #     with_locale(:de) do
+        #       t("hello") # Uses German
+        #     end
+        #     t("hello") # Uses French
+        #   end
+        #
+        # @api public
+        # @since x.x.x
+        def with_locale(tmp_locale)
+          previous_locale = Thread.current[@storage_key]
+          Thread.current[@storage_key] = tmp_locale&.to_sym
+          yield
+        ensure
+          Thread.current[@storage_key] = previous_locale
+        end
+
+        private
+
+        def handle_missing_translation(missing_translation, options)
+          default = options[:default]
+          return default if default.is_a?(String)
+
+          key = missing_translation.key
+          key.to_s
+        end
+
+        # rubocop:disable Layout/LineLength, Style/NestedTernaryOperator, Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
+
+        # Expands locale-dependent strftime codes (`%a`, `%A`, `%b`, `%B`, `%p`, `%P` and their
+        # uppercase `^` variants) by looking up day/month names and meridiem markers through this
+        # backend.
+        #
+        # This is a deliberate port of `I18n::Backend::Base#translate_localization_format`. We can't
+        # call this upstream method directly because it's private and also hardcodes `I18n.t!` (the
+        # global module) for every lookup, which defeats our per-slice isolated backends.
+        #
+        # This set of locale-dependent strftime codes is fixed by the C `strftime` spec and has not
+        # changed in the upstream gem since at least 2010, so this table is effectively frozen.
+        def expand_localization_format(locale, object, format)
+          format.to_s.gsub(/%(|\^)[aAbBpP]/) do |match|
+            case match
+            when "%a"   then t!(:"date.abbr_day_names",   locale:, format:)[object.wday]
+            when "%^a"  then t!(:"date.abbr_day_names",   locale:, format:)[object.wday].upcase
+            when "%A"   then t!(:"date.day_names",        locale:, format:)[object.wday]
+            when "%^A"  then t!(:"date.day_names",        locale:, format:)[object.wday].upcase
+            when "%b"   then t!(:"date.abbr_month_names", locale:, format:)[object.mon]
+            when "%^b"  then t!(:"date.abbr_month_names", locale:, format:)[object.mon].upcase
+            when "%B"   then t!(:"date.month_names",      locale:, format:)[object.mon]
+            when "%^B"  then t!(:"date.month_names",      locale:, format:)[object.mon].upcase
+            when "%p"   then t!(:"time.#{(object.respond_to?(:hour) ? object.hour : 0) < 12 ? :am : :pm}", locale:, format:).upcase
+            when "%P"   then t!(:"time.#{(object.respond_to?(:hour) ? object.hour : 0) < 12 ? :am : :pm}", locale:, format:).downcase
+            end
+          end
+        rescue ::I18n::MissingTranslationData => exception
+          exception.message
+        end
+
+        # rubocop:enable Layout/LineLength, Style/NestedTernaryOperator, Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
+      end
+    end
+  end
+end

data/lib/hanami/providers/i18n/locale/en.yml

@@ -0,0 +1,57 @@
+en:
+  date:
+    formats:
+      default: "%a, %-d %b %Y"
+      short: "%-d %b"
+      long: "%-d %B %Y"
+    day_names:
+      - Sunday
+      - Monday
+      - Tuesday
+      - Wednesday
+      - Thursday
+      - Friday
+      - Saturday
+    abbr_day_names:
+      - Sun
+      - Mon
+      - Tue
+      - Wed
+      - Thu
+      - Fri
+      - Sat
+    month_names:
+      - ~
+      - January
+      - February
+      - March
+      - April
+      - May
+      - June
+      - July
+      - August
+      - September
+      - October
+      - November
+      - December
+    abbr_month_names:
+      - ~
+      - Jan
+      - Feb
+      - Mar
+      - Apr
+      - May
+      - Jun
+      - Jul
+      - Aug
+      - Sep
+      - Oct
+      - Nov
+      - Dec
+  time:
+    formats:
+      default: "%a, %-d %b %Y %H:%M:%S %:z"
+      short: "%-d %b %-I:%M %P"
+      long: "%-d %B %Y %-I:%M %P"
+    am: "am"
+    pm: "pm"

data/lib/hanami/providers/i18n.rb

@@ -0,0 +1,114 @@
+# frozen_string_literal: true
+
+module Hanami
+  module Providers
+    # @api private
+    class I18n < Hanami::Provider::Source
+      SLICE_CONFIGURED_SETTINGS = %i[
+        default_locale available_locales load_path shared_load_path fallbacks
+      ].freeze
+
+      DEFAULT_LOCALE = :en
+      DEFAULT_AVAILABLE_LOCALES = [].freeze
+      DEFAULT_LOAD_PATH = ["config/i18n/**/*.{yml,yaml,json,rb}"].freeze
+      DEFAULT_SHARED_LOAD_PATH = ["config/i18n/shared/**/*.{yml,yaml,json,rb}"].freeze
+
+      # Built-in English baseline for date/time localization. Loaded into every slice before any
+      # user translation files, so users can supply overrides if desired.
+      BUNDLED_DEFAULTS_PATH = File.expand_path("i18n/locale/en.yml", __dir__).freeze
+
+      setting :default_locale, default: DEFAULT_LOCALE
+      setting :available_locales, default: DEFAULT_AVAILABLE_LOCALES
+      setting :backend
+      setting :load_path, default: DEFAULT_LOAD_PATH
+      setting :shared_load_path, default: DEFAULT_SHARED_LOAD_PATH
+      setting :fallbacks
+
+      def prepare
+        require "i18n"
+
+        SLICE_CONFIGURED_SETTINGS.each do |setting|
+          next if config.configured?(setting)
+
+          config.public_send(:"#{setting}=", slice.config.i18n.public_send(setting))
+        end
+      end
+
+      # rubocop:disable Metrics/AbcSize
+      def start
+        backend = config.backend || ::I18n::Backend::Simple.new
+
+        # Configure fallbacks if enabled (only for default backend, not custom backends)
+        fallbacks_config = nil
+        if config.fallbacks && !config.backend
+          fallbacks_config =
+            case config.fallbacks
+            when true
+              # Use default_locale as the only fallback
+              fallbacks = ::I18n::Locale::Fallbacks.new
+              fallbacks.defaults = [config.default_locale]
+              fallbacks
+            when Hash
+              # Use explicit per-locale fallback mapping
+              ::I18n::Locale::Fallbacks.new(config.fallbacks)
+            when Array
+              # Use the given fallbacks for all locales
+              fallbacks = ::I18n::Locale::Fallbacks.new
+              fallbacks.defaults = config.fallbacks
+              fallbacks
+            else
+              ::I18n::Locale::Fallbacks.new(config.fallbacks)
+            end
+        end
+
+        # Only load translation files if using the default backend. Custom backends are expected to
+        # handle their own initialization.
+        unless config.backend
+          translation_files = [
+            BUNDLED_DEFAULTS_PATH,
+            *resolve_load_paths(Array(config.shared_load_path), root: slice.app.root),
+            *resolve_load_paths(Array(config.load_path), root: slice.root)
+          ].uniq
+
+          backend.load_translations(*translation_files)
+        end
+
+        register "i18n", Backend.new(
+          backend,
+          locale: config.default_locale,
+          default_locale: config.default_locale,
+          available_locales: config.available_locales,
+          fallbacks: fallbacks_config
+        )
+      end
+      # rubocop:enable Metrics/AbcSize
+
+      private
+
+      # Resolves load path patterns to actual file paths. Relative patterns are resolved against
+      # the given `root`. Absolute paths are used as-is.
+      def resolve_load_paths(patterns, root:)
+        patterns.flat_map do |pattern|
+          if absolute_path?(pattern)
+            # Absolute path or already-globbed absolute paths
+            File.exist?(pattern) ? [pattern] : Dir.glob(pattern)
+          else
+            Dir.glob(root.join(pattern))
+          end
+        end
+      end
+
+      def absolute_path?(path)
+        Pathname.new(path).absolute?
+      end
+    end
+
+    Dry::System.register_provider_source(
+      :i18n,
+      source: I18n,
+      group: :hanami
+    )
+  end
+end
+
+require_relative "i18n/backend"

data/lib/hanami/providers/mailers.rb

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+module Hanami
+  module Providers
+    # Registers the `"mailers.delivery_method"` component. This is an SMTP delivery method built
+    # from SMTP environment variables when present, otherwise the test delivery method.
+    #
+    # SMTP env vars may take a per-slice prefix derived from the slice name (e.g. an "admin" slice
+    # reads `ADMIN__SMTP_ADDRESS`, falling back to `SMTP_ADDRESS`). Register your own `:mailers`
+    # provider if you need to use another delivery method or different setup logic.
+    #
+    # In the test env, environment variables are ignored, and the test delivery method is always
+    # used, so the test suite can never send real email.
+    #
+    # In the production env, warns noisily when there is no SMTP configuration, before falling back
+    # to the test delivery method. This ensures an app whose mail setup is a work in progress can
+    # still boot.
+    #
+    # @api private
+    class Mailers < Hanami::Provider::Source
+      # Maps SMTP environment variable names to their compatible delivery option keys.
+      #
+      # Example values:
+      #
+      #   SMTP_ADDRESS=smtp.example.com
+      #   SMTP_PORT=587
+      #   SMTP_USERNAME=postmaster@example.com
+      #   SMTP_PASSWORD=s3cr3t
+      #   SMTP_AUTHENTICATION=plain
+      SMTP_ENV_VARS = {
+        "SMTP_ADDRESS" => :address,
+        "SMTP_PORT" => :port,
+        "SMTP_USERNAME" => :user_name,
+        "SMTP_PASSWORD" => :password,
+        "SMTP_AUTHENTICATION" => :authentication
+      }.freeze
+
+      # Coercions applied to SMTP env var values, keyed by option. Options not listed here are
+      # passed through unchanged (as strings).
+      SMTP_COERCIONS = Hash.new(:itself.to_proc).update(
+        port: ->(value) { Integer(value) },
+        authentication: ->(value) { value.to_sym }
+      ).freeze
+
+      def start
+        require "hanami/mailer"
+
+        register "delivery_method", build_delivery_method
+      end
+
+      private
+
+      def build_delivery_method
+        return Hanami::Mailer::Delivery::Test.new if Hanami.env?(:test)
+
+        smtp_options = smtp_options_from_env
+
+        return Hanami::Mailer::Delivery::SMTP.new(**smtp_options) if smtp_options.key?(:address)
+
+        warn_missing_smtp if Hanami.env?(:production)
+
+        Hanami::Mailer::Delivery::Test.new
+      end
+
+      def smtp_options_from_env
+        SMTP_ENV_VARS.each_with_object({}) do |(var, option), options|
+          value = env_value(var)
+          next if value.nil?
+
+          coercion = SMTP_COERCIONS[option]
+          options[option] = coercion ? coercion.call(value) : value
+        end
+      end
+
+      # Reads an SMTP env var, preferring a per-slice prefixed name (e.g. `ADMIN__SMTP_ADDRESS`)
+      # and falling back to the unprefixed name shared across slices.
+      def env_value(var)
+        return ENV[var] if slice.app?
+
+        slice_prefixed_var = "#{slice.slice_name.name.gsub("/", "__").upcase}__#{var}"
+        ENV[slice_prefixed_var] || ENV[var]
+      end
+
+      def warn_missing_smtp
+        message = \
+          "No SMTP configuration found for #{slice.slice_name.name} in production; " \
+          "falling back to the test delivery method — mail will NOT be sent. " \
+          "Set SMTP_ADDRESS (and related SMTP_* variables), or register a custom :mailers provider."
+
+        slice.app["logger"].warn(message)
+      end
+    end
+
+    Dry::System.register_provider_source(
+      :mailers,
+      source: Mailers,
+      group: :hanami,
+      provider_options: {namespace: true}
+    )
+  end
+end

data/lib/hanami/routes.rb

@@ -137,6 +137,7 @@ module Hanami
       # @api private
       def method_missing(name, *args, **kwargs, &block)
         return super unless respond_to?(name)
+
         definitions << [name, args, kwargs, block]
         self
       end

data/lib/hanami/settings/composite_store.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+require "dry/core/constants"
+
+module Hanami
+  class Settings
+    # A settings store that chains multiple stores with fallback resolution.
+    #
+    # Each store is tried in order. The first store to return a value wins.
+    # Stores must implement `#fetch` with the same signature as `Hash#fetch`.
+    #
+    # @example
+    #   # config/app.rb
+    #   config.settings_store = Hanami::Settings::CompositeStore.new(
+    #     Hanami::Settings::EnvStore.new,
+    #     MyCustomStore.new
+    #   )
+    #
+    # @api public
+    # @since x.x.x
+    class CompositeStore
+      # @api private
+      Undefined = Dry::Core::Constants::Undefined
+
+      # @param stores [Array<#fetch>] ordered list of stores to query
+      def initialize(*stores)
+        @stores = stores
+      end
+
+      # Fetches a value by trying each store in order.
+      #
+      # @param name [String, Symbol] the setting name
+      # @param args [Array] optional default value
+      # @yield [name] optional block for default value
+      # @return [Object] the setting value
+      # @raise [KeyError] if no store has the key and no default is given
+      #
+      # @api public
+      # @since x.x.x
+      def fetch(name, *args, &block)
+        @stores.each do |store|
+          value = store.fetch(name, Undefined)
+          return value unless value.equal?(Undefined)
+        end
+
+        return args.first unless args.empty?
+        return yield(name) if block
+
+        raise KeyError, "key not found: #{name.inspect}"
+      end
+    end
+  end
+end