hanami 2.3.2 → 3.0.0.rc1

data/lib/hanami/helpers/i18n_helper.rb

@@ -0,0 +1,176 @@
+# frozen_string_literal: true
+
+require "hanami/view"
+
+module Hanami
+  module Helpers
+    # Helper methods for translating and localizing content using the slice's i18n backend.
+    #
+    # These helpers will be automatically available in your view templates, part classes, and scope
+    # classes when the `i18n` gem is bundled.
+    #
+    # @api public
+    # @since x.x.x
+    module I18nHelper
+      # Matches keys whose final segment is `html` or whose final segment ends in `_html`. These
+      # translated values are treated as HTML-safe and any string interpolation values are
+      # HTML-escaped before substitution.
+      #
+      # @api private
+      HTML_SAFE_TRANSLATION_KEY = /(\b|_)html\z/
+
+      # Translates the given key using the slice's i18n backend.
+      #
+      # When the key's final segment is `html` or ends in `_html`, the result is marked HTML-safe
+      # and any string interpolation values are HTML-escaped first.
+      #
+      # When a translation is missing and neither `:default` nor `:raise` was supplied, returns a
+      # `<span class="translation_missing">` element containing the missing key, useful for
+      # spotting missing translations during development.
+      #
+      # When the key begins with a `.`, it is treated as relative to the currently-rendering
+      # template and expanded against its name (slashes become dots; partial basenames keep
+      # their leading underscore). For example, `translate(".title")` inside
+      # `users/index.html.erb` resolves to `users.index.title`, and `translate(".label")`
+      # inside `users/_form.html.erb` resolves to `users._form.label`. Raises
+      # `I18n::ArgumentError` if called outside a template render.
+      #
+      # @param key [String, Symbol] the translation key to look up
+      # @param options [Hash] translation options forwarded to the backend (`:locale`, `:scope`,
+      #   `:default`, `:count`, `:raise`, etc.), plus any interpolation values
+      #
+      # @return [String, Hanami::View::HTML::SafeString] the translated string
+      #
+      # @example Basic translation
+      #   <%= translate("messages.welcome") %>
+      #   # => "Welcome"
+      #
+      # @example HTML-safe translation
+      #   # en.yml
+      #   #   greeting_html: "Hello, <strong>%{name}</strong>!"
+      #   <%= translate("greeting_html", name: "<script>") %>
+      #   # => "Hello, <strong>&lt;script&gt;</strong>!" (marked HTML-safe)
+      #
+      # @example Missing translation
+      #   <%= translate("missing.key") %>
+      #   # => '<span class="translation_missing" title="...">missing.key</span>'
+      #
+      # @example Relative key lookup
+      #   # In app/templates/users/index.html.erb:
+      #   <%= translate(".title") %>
+      #   # Looks up "users.index.title"
+      #
+      #   # In app/templates/users/_form.html.erb (a partial):
+      #   <%= translate(".label") %>
+      #   # Looks up "users._form.label"
+      #
+      # @api public
+      # @since x.x.x
+      def translate(key, **options)
+        key = _resolve_i18n_key(key)
+
+        html_safe = _html_safe_translation_key?(key)
+
+        options = _escape_translation_options(options) if html_safe
+
+        result =
+          if options.key?(:default) || options[:raise]
+            _context.i18n.translate(key, **options)
+          else
+            begin
+              _context.i18n.translate(key, **options, raise: true)
+            rescue ::I18n::MissingTranslationData => exception
+              return _missing_translation_markup(key, exception)
+            end
+          end
+
+        html_safe ? result.to_s.html_safe : result
+      end
+
+      # @api public
+      # @since x.x.x
+      alias_method :t, :translate
+
+      # Translates the given key, raising an exception if the translation is missing.
+      #
+      # @param (see #translate)
+      #
+      # @return [String, Hanami::View::HTML::SafeString] the translated string
+      #
+      # @raise [I18n::MissingTranslationData] if the translation is missing
+      #
+      # @example
+      #   <%= translate!("messages.welcome") %>
+      #
+      # @api public
+      # @since x.x.x
+      def translate!(key, **options)
+        translate(key, **options, raise: true)
+      end
+
+      # @api public
+      # @since x.x.x
+      alias_method :t!, :translate!
+
+      # Localizes the given object (e.g. a date, time, or number) using the slice's i18n backend.
+      #
+      # @param object [Date, Time, DateTime, Numeric] the object to localize
+      # @param options [Hash] localization options forwarded to the backend (`:locale`, `:format`,
+      #   etc.)
+      #
+      # @return [String] the localized string
+      #
+      # @example
+      #   <%= localize(Date.today, format: :long) %>
+      #
+      # @api public
+      # @since x.x.x
+      def localize(object, **options)
+        _context.i18n.localize(object, **options)
+      end
+
+      # @api public
+      # @since x.x.x
+      alias_method :l, :localize
+
+      private
+
+      def _resolve_i18n_key(key)
+        return key unless key.to_s.start_with?(".")
+
+        template_name = _context.current_template_name
+
+        unless template_name
+          raise(
+            ::I18n::ArgumentError,
+            "Cannot use relative translation key #{key.inspect} outside of a template render. " \
+            "Use an absolute key (without a leading dot) instead."
+          )
+        end
+
+        "#{template_name.tr("/", ".")}#{key}"
+      end
+
+      def _html_safe_translation_key?(key)
+        HTML_SAFE_TRANSLATION_KEY.match?(key.to_s)
+      end
+
+      def _escape_translation_options(options)
+        options.each_with_object({}) do |(key, value), result|
+          result[key] =
+            if ::I18n::RESERVED_KEYS.include?(key) || !value.is_a?(String) || value.html_safe?
+              value
+            else
+              escape_html(value)
+            end
+        end
+      end
+
+      def _missing_translation_markup(key, error)
+        title = escape_html(error.message)
+        body = escape_html(key.to_s)
+        %(<span class="translation_missing" title="#{title}">#{body}</span>).html_safe
+      end
+    end
+  end
+end

data/lib/hanami/logger/rack_formatter.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+require "dry/logger"
+
+module Hanami
+  module Logger
+    # Rack request log formatter for Dry Logger.
+    #
+    # Formats rack request log entries with colorized output for HTTP verbs, status codes, and
+    # request paths, making it easier to visually scan logs in development.
+    #
+    # HTTP verbs each have a distinct color. Status codes follow traffic-light coloring (2xx green,
+    # 3xx cyan, 4xx yellow, 5xx red), and the request path echoes the status color so both signals
+    # reinforce each other at a glance.
+    #
+    # Colorization is only active when `colorize: true` is set in the logger options (the default
+    # in development).
+    #
+    # @api private
+    class RackFormatter < Dry::Logger::Formatters::String
+      RACK_TEMPLATE = <<~TEXT
+        [%<progname>s] [%<severity>s] [%<time>s] \
+        %<verb>s %<status>s %<elapsed>s %<ip>s %<path>s %<length>s %<payload>s
+          %<params>s
+      TEXT
+
+      VERB_COLORS = {
+        "GET" => :green,
+        "POST" => :yellow,
+        "PUT" => :blue,
+        "PATCH" => :blue,
+        "DELETE" => :red,
+        "HEAD" => :cyan
+      }.freeze
+
+      Colors = Dry::Logger::Formatters::Colors
+      private_constant :Colors
+
+      def initialize(**options)
+        super
+        @template = Dry::Logger::Formatters::Template[RACK_TEMPLATE]
+      end
+
+      private
+
+      def format_values(entry)
+        return super unless colorize?
+
+        status_color = status_color(entry.to_h[:status])
+
+        super.merge(
+          verb: Colors.call(VERB_COLORS.fetch(entry.to_h[:verb].to_s.upcase, :gray), entry.to_h[:verb]),
+          status: Colors.call(status_color, entry.to_h[:status]),
+          path: Colors.call(status_color, entry.to_h[:path])
+        )
+      end
+
+      def format_params(value)
+        value unless value.empty?
+      end
+
+      def status_color(status)
+        case status.to_i
+        when 200..299 then :green
+        when 300..399 then :cyan
+        when 400..499 then :yellow
+        when 500..599 then :red
+        else :gray
+        end
+      end
+    end
+  end
+end

data/lib/hanami/logger/sql_formatter.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+require "dry/logger"
+
+module Hanami
+  module Logger
+    # SQL query log formatter for Dry Logger.
+    #
+    # Formats SQL query log entries with a template that mirrors the structure of the built-in rack
+    # log formatter, providing consistent visual formatting across both HTTP request and database
+    # query logs.
+    #
+    # For example, in development, SQL logs alongside Rack logs:
+    #
+    #   [my_app] [INFO] [2026-03-04 10:15:32] SQL sqlite 1.234ms SELECT * FROM users
+    #   [my_app] [INFO] [2026-03-04 10:15:32] GET 200 1ms 127.0.0.1 /users -
+    #
+    # In production, the default JSON formatter handles SQL entries automatically via the structured
+    # payload.
+    #
+    # Supports colorization via Dry Logger's template color tags. When `colorize: true` is set in
+    # the logger options (the default in development), the "SQL" label is colorized, and severity
+    # is colorized per-level by the parent formatter (e.g. INFO => magenta, ERROR => red).
+    #
+    # When colorization is enabled and the "rouge" gem is available, SQL queries are syntax
+    # highlighted using Rouge's SQL lexer. This is a soft dependency; if Rouge is not installed,
+    # queries output as plain, unhighlighted text.
+    #
+    # The Rouge theme defaults to Gruvbox and can be customized by setting the `HANAMI_SQL_THEME`
+    # environment variable to any Rouge theme name (e.g. "github.dark", "monokai", "gruvbox.light").
+    # See `Rouge::Theme.registry` for available themes.
+    #
+    # @see Hanami::Logger::SQLLogger
+    #
+    # @api private
+    class SQLFormatter < Dry::Logger::Formatters::String
+      SQL_TEMPLATE = <<~TEXT
+        [%<progname>s] [%<severity>s] [%<time>s] SQL %<db>s %<elapsed>s%<elapsed_unit>s %<query>s
+      TEXT
+
+      SQL_TEMPLATE_COLORIZED = <<~TEXT
+        [%<progname>s] [%<severity>s] [%<time>s] <blue>SQL</blue> %<db>s %<elapsed>s%<elapsed_unit>s %<query>s
+      TEXT
+
+      def initialize(**options)
+        super
+        @template = Dry::Logger::Formatters::Template[
+          colorize? ? SQL_TEMPLATE_COLORIZED : SQL_TEMPLATE
+        ]
+        @sql_colorizer = build_sql_colorizer if colorize?
+      end
+
+      private
+
+      def format_query(value)
+        if @sql_colorizer
+          @sql_colorizer.call(value)
+        else
+          value
+        end
+      end
+
+      def build_sql_colorizer
+        begin
+          require "rouge"
+        rescue LoadError
+          return nil
+        end
+
+        theme_name = ENV.fetch("HANAMI_SQL_THEME", "gruvbox")
+        theme_class = Rouge::Theme.find(theme_name) || Rouge::Themes::Gruvbox
+        formatter = Rouge::Formatters::Terminal256.new(theme_class.new)
+
+        lexer = Rouge::Lexers::SQL.new
+
+        ->(sql) { formatter.format(lexer.lex(sql)) }
+      end
+    end
+  end
+end

data/lib/hanami/logger/sql_logger.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module Hanami
+  module Logger
+    # SQL query logger that integrates with the Hanami logger using structured, tagged logging.
+    #
+    # Subscribes to `:sql` notification events (emitted by ROM via the Hanami app's
+    # `"notifications"` component) and logs each query as a structured payload. The log entries are
+    # tagged as `:sql`, which allows Dry Logger backends to route them to a dedicated formatter (see
+    # {SQLFormatter}), in the same way that rack log entries are routed using the `:rack` tag.
+    #
+    # @see SQLFormatter
+    # @see Hanami::Providers::DBLogging
+    #
+    # @api private
+    class SQLLogger
+      attr_reader :logger, :level
+
+      # @param logger [#tagged, #info] a Hanami-compatible logger (typically a
+      #   Dry::Logger::Dispatcher or a {Hanami::UniversalLogger}-wrapped logger)
+      def initialize(logger, level: :debug)
+        @logger = logger
+        @level = level
+      end
+
+      # Subscribes to `:sql` notification events.
+      #
+      # @param notifications [Dry::Monitor::Notifications] the notifications bus
+      # @return [void]
+      def subscribe(notifications)
+        notifications.subscribe(:sql) { |params| log_query(**params) }
+      end
+
+      # Log a SQL query with structured data.
+      #
+      # @param time [Numeric] elapsed time in milliseconds
+      # @param name [Symbol] database adapter name (e.g. `:sqlite`, `:postgres`)
+      # @param query [String] the SQL query string
+      def log_query(time:, name:, query:)
+        logger.tagged(:sql) do
+          logger.public_send(@level) do
+            {query:, db: name, elapsed: time.round(3), elapsed_unit: "ms"}
+          end
+        end
+      end
+    end
+  end
+end

data/lib/hanami/middleware/render_errors.rb

@@ -72,9 +72,9 @@ module Hanami
         request.set_header(Rack::REQUEST_METHOD, "GET")
 
         @errors_app.call(request.env)
-      rescue Exception => failsafe_error
+      rescue Exception => exception
         # rubocop:disable Style/StderrPuts
-        $stderr.puts "Error during exception rendering: #{failsafe_error}\n  #{failsafe_error.backtrace * "\n  "}"
+        $stderr.puts "Error during exception rendering: #{exception}\n  #{exception.backtrace * "\n  "}"
         # rubocop:enable Style/StderrPuts
 
         [

data/lib/hanami/providers/db.rb

@@ -7,6 +7,8 @@ require_relative "../constants"
 
 module Hanami
   module Providers
+    # rubocop:disable Metrics/AbcSize, Metrics/PerceivedComplexity
+
     # @api private
     # @since 2.2.0
     class DB < Hanami::Provider::Source
@@ -250,7 +252,7 @@ module Hanami
           end
 
         # Set the default gateway from ENV var without suffix
-        if !database_urls.key?(:default)
+        unless database_urls.key?(:default)
           fallback_vars = ["#{env_var_prefix}DATABASE_URL", "DATABASE_URL"].uniq
 
           fallback_vars.each do |var|
@@ -290,7 +292,9 @@ module Hanami
 
         return if Hanami.bundled?(database_gem)
 
-        raise Hanami::ComponentLoadError, %(The "#{database_gem}" gem is required to connect to #{database_url}. Please add it to your Gemfile.)
+        raise Hanami::ComponentLoadError, <<~STR
+          The "#{database_gem}" gem is required to connect to #{database_url}. Please add it to your Gemfile.
+        STR
       end
 
       def register_rom_components(component_type, path)
@@ -309,6 +313,7 @@ module Hanami
         end
       end
     end
+    # rubocop:enable Metrics/AbcSize, Metrics/PerceivedComplexity
 
     Dry::System.register_provider_source(
       :db,

data/lib/hanami/providers/db_logging.rb

@@ -3,19 +3,16 @@
 module Hanami
   module Providers
     # @api private
-    # @since 2.2.0
     class DBLogging < Hanami::Provider::Source
-      # @api private
-      # @since 2.2.0
       def prepare
-        require "dry/monitor/sql/logger"
         slice["notifications"].register_event :sql
       end
 
-      # @api private
-      # @since 2.2.0
       def start
-        Dry::Monitor::SQL::Logger.new(slice["logger"]).subscribe(slice["notifications"])
+        require "hanami/logger/sql_logger"
+        Hanami::Logger::SQLLogger
+          .new(slice["logger"], level: slice.config.db.log_level)
+          .subscribe(slice["notifications"])
       end
     end
   end