haveapi 0.28.4 → 0.29.0

data/lib/haveapi/server.rb

@@ -6,9 +6,10 @@ require 'haveapi/hooks'
 
 module HaveAPI
   class Server
-    attr_accessor :default_version, :action_state, :validation_error_http_status
+    attr_accessor :default_version, :action_state, :validation_error_http_status,
+                  :default_locale, :parameter_i18n_scope
     attr_reader :root, :routes, :module_name, :auth_chain, :versions, :extensions,
-                :action_state_auth
+                :action_state_auth, :locale_header, :available_locales
 
     include Hookable
 
@@ -57,6 +58,50 @@ module HaveAPI
              }
 
     module ServerHelpers
+      def setup_request_locale
+        return if @haveapi_locale_setup
+
+        server = settings.api_server
+        @haveapi_previous_locale = ::I18n.locale
+        locale_header_value = server.locale_header_value(request)
+        @haveapi_locale_requested = !locale_header_value.nil?
+        @haveapi_explicit_locale = server.request_locale(request)
+        @haveapi_locale = if @haveapi_locale_requested
+                            @haveapi_explicit_locale || server.default_locale
+                          else
+                            server.resolved_locale(
+                              request:,
+                              current_user: nil
+                            )
+                          end
+        server.activate_locale(@haveapi_locale)
+        add_vary_header(server.locale_header) if server.locale_header
+        @haveapi_locale_setup = true
+      end
+
+      def resolve_request_locale(user = current_user)
+        setup_request_locale
+        return @haveapi_locale if @haveapi_locale_requested
+
+        @haveapi_locale = settings.api_server.resolved_locale(
+          request:,
+          current_user: user
+        )
+        settings.api_server.activate_locale(@haveapi_locale)
+      end
+
+      def restore_request_locale
+        return unless @haveapi_locale_setup
+
+        settings.api_server.activate_locale(@haveapi_previous_locale)
+      end
+
+      def add_vary_header(name)
+        values = response['Vary'].to_s.split(/\s*,\s*/).reject(&:empty?)
+        values << name unless values.include?(name)
+        headers 'Vary' => values.join(', ')
+      end
+
       def setup_formatter
         return if @formatter
 
@@ -64,7 +109,7 @@ module HaveAPI
         accept = request.accept
       rescue ArgumentError, EncodingError
         @formatter.supports?([])
-        report_error(400, {}, 'Bad Accept header')
+        report_error(400, {}, HaveAPI.message('haveapi.errors.bad_accept_header'))
       else
         unless @formatter.supports?(accept)
           @halted = true
@@ -79,7 +124,10 @@ module HaveAPI
       end
 
       def authenticated?(v)
-        return @current_user if @current_user
+        if @current_user
+          resolve_request_locale
+          return @current_user
+        end
 
         begin
           @current_user = settings.api_server.send(:do_authenticate, v, request)
@@ -92,12 +140,13 @@ module HaveAPI
           report_error(400, {}, e.message)
         end
         settings.api_server.call_hooks_for(:post_authenticated, args: [@current_user])
+        resolve_request_locale
         @current_user
       end
 
       def authenticated_versions
-        settings.api_server.versions.each_with_object({}) do |v, ret|
-          ret[v] = settings.api_server.send(:do_authenticate, v, request)
+        ret = settings.api_server.versions.each_with_object({}) do |v, users|
+          users[v] = settings.api_server.send(:do_authenticate, v, request)
         rescue HaveAPI::Authentication::TokenConflict => e
           unless @formatter
             @formatter = OutputFormatter.new
@@ -106,6 +155,9 @@ module HaveAPI
 
           report_error(400, {}, e.message)
         end
+
+        resolve_request_locale(ret[settings.api_server.default_version] || ret.values.compact.first)
+        ret
       end
 
       def access_control
@@ -133,7 +185,7 @@ module HaveAPI
         report_error(
           401,
           { 'www-authenticate' => 'Basic realm="Restricted Area"' },
-          'Action requires user to authenticate'
+          HaveAPI.message('haveapi.authentication.required')
         )
       end
 
@@ -170,7 +222,7 @@ module HaveAPI
         report_error(
           tmp[:http_status] || 500,
           {},
-          tmp[:message] || 'Server error occurred'
+          tmp[:message] || HaveAPI.message('haveapi.errors.server_error')
         )
       end
 
@@ -260,6 +312,62 @@ module HaveAPI
       @extensions = []
       @action_state_auth = :backend
       @validation_error_http_status = nil
+      @default_locale = :en
+      self.available_locales = HaveAPI::I18n.available_locales
+      self.locale_header = 'Accept-Language'
+    end
+
+    def available_locales=(locales)
+      @available_locales = Array(locales)
+      allow_i18n_locales(@available_locales)
+    end
+
+    def locale_header=(header)
+      @locale_header = header
+      allow_header(header) if header
+    end
+
+    def activate_locale(locale)
+      allow_i18n_locales([locale])
+      ::I18n.locale = locale
+    end
+
+    def allow_i18n_locales(locales)
+      requested = Array(locales).compact.map { |locale| locale.to_s.to_sym }
+      current = ::I18n.available_locales
+      missing = requested.reject do |locale|
+        current.any? { |available| available.to_s == locale.to_s }
+      end
+
+      ::I18n.available_locales = current + missing unless missing.empty?
+    end
+
+    def locale(&block)
+      @locale_resolver = block if block
+      @locale_resolver
+    end
+
+    def request_locale(request)
+      HaveAPI::I18n.accept_language(
+        locale_header_value(request),
+        available_locales
+      )
+    end
+
+    def locale_header_value(request)
+      request.env["HTTP_#{locale_header.to_s.upcase.tr('-', '_')}"]
+    end
+
+    def resolved_locale(request:, current_user:)
+      locale = if @locale_resolver
+                 @locale_resolver.call(
+                   request:,
+                   current_user:,
+                   default_locale:
+                 )
+               end
+
+      HaveAPI::I18n.normalize_locale(locale, available_locales) || default_locale
     end
 
     def action_state_auth=(mode)
@@ -321,6 +429,8 @@ module HaveAPI
         helpers DocHelpers
 
         before do
+          setup_request_locale
+
           if request.env['HTTP_ORIGIN']
             headers 'access-control-allow-origin' => '*',
                     'access-control-allow-credentials' => 'false'
@@ -329,7 +439,7 @@ module HaveAPI
 
         not_found do
           setup_formatter
-          report_error(404, {}, 'Action not found') unless @halted
+          report_error(404, {}, HaveAPI.message('haveapi.errors.action_not_found')) unless @halted
         end
 
         error do
@@ -337,6 +447,8 @@ module HaveAPI
         end
 
         after do
+          restore_request_locale
+
           if Object.const_defined?(:ActiveRecord)
             ActiveRecord::Base.connection_handler.clear_active_connections!
           end
@@ -534,6 +646,27 @@ module HaveAPI
       end
     end
 
+    def collect_parameter_metadata_i18n_items(resources, context)
+      resources.flat_map do |resource, children|
+        original_resource_path = context.resource_path
+        context.resource_path = context.resource_path + [resource.resource_name.underscore]
+
+        action_items = children[:actions].flat_map do |action, path|
+          context.action = action
+          context.path = path
+
+          action.parameter_metadata_i18n_items(context)
+        end
+
+        child_items = collect_parameter_metadata_i18n_items(children[:resources], context)
+
+        action_items + child_items
+      ensure
+        context.resource_path = original_resource_path
+      end
+    end
+    private :collect_parameter_metadata_i18n_items
+
     def mount_resource(prefix, v, resource, hash)
       hash[resource] = { resources: {}, actions: {} }
 
@@ -584,17 +717,17 @@ module HaveAPI
           body_method = !%i[get head options].include?(route.http_method.to_sym)
 
           if body_method && !raw_body.empty? && !settings.api_server.send(:json_content_type?, request)
-            report_error(415, {}, 'Unsupported Content-Type')
+            report_error(415, {}, HaveAPI.message('haveapi.errors.unsupported_content_type'))
           end
 
           begin
             body = raw_body.empty? ? nil : JSON.parse(raw_body)
           rescue JSON::ParserError
-            report_error(400, {}, 'Bad JSON syntax')
+            report_error(400, {}, HaveAPI.message('haveapi.errors.bad_json_syntax'))
           end
 
           if !raw_body.empty? && !body.is_a?(Hash)
-            report_error(400, {}, 'JSON body must be an object')
+            report_error(400, {}, HaveAPI.message('haveapi.errors.json_body_object'))
           end
 
           action_params = settings.api_server.send(:path_params, route, params)
@@ -616,7 +749,7 @@ module HaveAPI
           action = route.action.new(request, v, action_params, action_input, context)
 
           unless action.authorized?(current_user)
-            report_error(403, {}, 'Access denied. Insufficient permissions.')
+            report_error(403, {}, HaveAPI.message('haveapi.authorization.insufficient_permissions'))
           end
 
           status, reply, errors, http_status = action.safe_exec
@@ -671,16 +804,16 @@ module HaveAPI
             desc = route.action.describe(ctx)
 
             unless desc
-              report_error(403, {}, 'Access denied. Insufficient permissions.')
+              report_error(403, {}, HaveAPI.message('haveapi.authorization.insufficient_permissions'))
             end
           rescue ValidationError => e
-            report_error(400, e.to_hash, e.message)
+            report_error(400, e.to_hash, e.message_value)
           rescue StandardError => e
             tmp = settings.api_server.call_hooks_for(:description_exception, args: [ctx, e])
             report_error(
               tmp[:http_status] || 500,
               {},
-              tmp[:message] || 'Server error occured'
+              tmp[:message] || HaveAPI.message('haveapi.errors.server_error')
             )
           end
 
@@ -742,6 +875,13 @@ module HaveAPI
       r.describe(hash, context)
     end
 
+    def parameter_metadata_i18n_items(version: @default_version)
+      routes = @routes.fetch(version)
+      context = Context.new(self, version:, doc: true)
+
+      collect_parameter_metadata_i18n_items(routes[:resources], context)
+    end
+
     def path_for_action(version, action)
       routes = @routes && @routes[version]
       return unless routes

data/lib/haveapi/spec/api_builder.rb

@@ -64,6 +64,31 @@ module HaveAPI::Spec
       opt(:validation_error_http_status, status)
     end
 
+    # Set default response locale.
+    def default_locale(locale)
+      opt(:default_locale, locale)
+    end
+
+    # Set locales available to the API server.
+    def available_locales(locales)
+      opt(:available_locales, locales)
+    end
+
+    # Set request header used to negotiate the response locale.
+    def locale_header(header)
+      opt(:locale_header, header)
+    end
+
+    # Set custom locale resolver.
+    def locale(&block)
+      opt(:locale, block)
+    end
+
+    # Set the translation scope for action parameter labels/descriptions.
+    def parameter_i18n_scope(scope)
+      opt(:parameter_i18n_scope, scope)
+    end
+
     # Set a custom mount path.
     def mount_to(path)
       opt(:mount, path)

data/lib/haveapi/spec/spec_methods.rb

@@ -19,6 +19,16 @@ module HaveAPI::Spec
       @api.action_state_auth = asa if asa
       ves = get_opt(:validation_error_http_status)
       @api.validation_error_http_status = ves if ves
+      dl = get_opt(:default_locale)
+      @api.default_locale = dl if dl
+      al = get_opt(:available_locales)
+      @api.available_locales = al if al
+      lh = get_opt(:locale_header)
+      @api.locale_header = lh if lh
+      locale = get_opt(:locale)
+      @api.locale(&locale) if locale
+      parameter_i18n_scope = get_opt(:parameter_i18n_scope)
+      @api.parameter_i18n_scope = parameter_i18n_scope if parameter_i18n_scope
       @api.mount(get_opt(:mount) || '/')
       @api.app
     end

data/lib/haveapi/tasks/i18n.rb

@@ -0,0 +1,198 @@
+require 'yaml'
+
+module HaveAPI
+  module Tasks
+    class I18nHealth
+      KEY_LITERAL_PATTERN = /['"](haveapi\.[a-z0-9_.]+)['"]/
+
+      RAW_MESSAGE_PATTERNS = [
+        /report_error\([^#\n]*,\s*['"]/,
+        /error!\(\s*['"]/,
+        /HaveAPI::ValidationError(?:\.new)?\(\s*['"]/,
+        /raise\s+HaveAPI::ValidationError,\s*['"]/,
+        /ret\[:message\]\s*=\s*['"]/,
+        /\|\|\s*['"][^'"]+(?:failed|error|denied|not found|invalid|requires|unsupported|missing)/,
+        /@message\s*=\s*take\(\s*:message\s*,\s*['"]/
+      ].freeze
+
+      PARAMETER_METHODS = %w[
+        bool custom datetime float id integer password resource string text
+      ].freeze
+      PARAMETER_CALL_PATTERN = /\A\s*(?:#{PARAMETER_METHODS.join('|')})\b/
+      RAW_PARAMETER_METADATA_PATTERN = /\b(?:label|desc):\s*['"]/
+
+      def initialize(root:)
+        @root = root
+      end
+
+      def check!
+        errors = []
+        errors.concat(missing_key_errors)
+        errors.concat(unused_key_errors)
+        errors.concat(raw_message_errors)
+
+        return true if errors.empty?
+
+        raise "i18n health check failed:\n#{errors.join("\n")}"
+      end
+
+      def normalize!
+        locale_data.each do |locale, data|
+          file = File.join(locale_dir, "#{locale}.yml")
+          File.write(file, YAML.dump(locale.to_s => deep_sort(data)))
+        end
+      end
+
+      private
+
+      def missing_key_errors
+        reference_locale = :en
+        reference_keys = locale_keys.fetch(reference_locale)
+
+        locale_keys.flat_map do |locale, keys|
+          next [] if locale == reference_locale
+
+          (reference_keys - keys).sort.map do |key|
+            "#{locale}: missing #{key}"
+          end
+        end
+      end
+
+      def unused_key_errors
+        keys = locale_keys.fetch(:en)
+        used = used_keys
+
+        (keys - used).sort.map { |key| "unused translation key #{key}" }
+      end
+
+      def raw_message_errors
+        source_files.flat_map do |file|
+          rel = relative_path(file)
+
+          File.readlines(file, chomp: true).each_with_index.filter_map do |line, index|
+            stripped = line.strip
+            next if stripped.empty? || stripped.start_with?('#')
+
+            if RAW_MESSAGE_PATTERNS.any? { |pattern| pattern.match?(line) }
+              "#{rel}:#{index + 1}: raw user-facing framework message"
+            end
+          end
+        end + raw_parameter_metadata_errors
+      end
+
+      def raw_parameter_metadata_errors
+        source_files.flat_map do |file|
+          rel = relative_path(file)
+          inside_parameter = false
+          remaining_lines = 0
+
+          File.readlines(file, chomp: true).each_with_index.filter_map do |line, index|
+            stripped = line.strip
+            next if stripped.empty? || stripped.start_with?('#')
+
+            if PARAMETER_CALL_PATTERN.match?(stripped)
+              inside_parameter = true
+              remaining_lines = 12
+            end
+
+            if inside_parameter && RAW_PARAMETER_METADATA_PATTERN.match?(line)
+              "#{rel}:#{index + 1}: raw action parameter label/description"
+            end
+          ensure
+            if inside_parameter
+              remaining_lines -= 1
+              inside_parameter = false if remaining_lines <= 0 || parameter_call_end?(stripped)
+            end
+          end
+        end
+      end
+
+      def parameter_call_end?(line)
+        return false if line.nil?
+
+        stripped = line.strip
+        return false if stripped.empty?
+        return false if stripped.end_with?(',', '\\')
+
+        true
+      end
+
+      def used_keys
+        @used_keys ||= source_files.each_with_object(Set.new) do |file, ret|
+          File.read(file).scan(KEY_LITERAL_PATTERN) do |match|
+            ret << match.first
+          end
+        end
+      end
+
+      def locale_keys
+        @locale_keys ||= locale_data.transform_values do |data|
+          flatten_keys(data)
+        end
+      end
+
+      def locale_data
+        @locale_data ||= Dir[File.join(locale_dir, '*.yml')].to_h do |file|
+          locale = File.basename(file, '.yml').to_sym
+          data = YAML.safe_load_file(file, aliases: true) || {}
+
+          [locale, data.fetch(locale.to_s)]
+        end
+      end
+
+      def flatten_keys(hash, prefix = nil)
+        hash.each_with_object(Set.new) do |(key, value), ret|
+          name = [prefix, key].compact.join('.')
+
+          if value.is_a?(Hash)
+            ret.merge(flatten_keys(value, name))
+          else
+            ret << name
+          end
+        end
+      end
+
+      def deep_sort(value)
+        case value
+        when Hash
+          value.keys.sort.to_h do |key|
+            [key, deep_sort(value[key])]
+          end
+        else
+          value
+        end
+      end
+
+      def source_files
+        @source_files ||= Dir[File.join(@root, 'lib/haveapi/**/*.rb')].reject do |file|
+          rel = relative_path(file)
+          rel.start_with?('lib/haveapi/public/') ||
+            rel.start_with?('lib/haveapi/views/') ||
+            rel.start_with?('lib/haveapi/client_examples/') ||
+            rel.start_with?('lib/haveapi/spec/') ||
+            rel.start_with?('lib/haveapi/tasks/i18n.rb')
+        end
+      end
+
+      def relative_path(file)
+        file.delete_prefix("#{@root}/")
+      end
+
+      def locale_dir
+        File.join(@root, 'lib/haveapi/locales')
+      end
+    end
+  end
+end
+
+namespace :i18n do
+  desc 'Check HaveAPI translation coverage and raw framework messages'
+  task :health do
+    HaveAPI::Tasks::I18nHealth.new(root: File.expand_path('../../..', __dir__)).check!
+  end
+
+  desc 'Normalize HaveAPI locale files'
+  task :normalize do
+    HaveAPI::Tasks::I18nHealth.new(root: File.expand_path('../../..', __dir__)).normalize!
+  end
+end

data/lib/haveapi/validator_chain.rb

@@ -72,7 +72,7 @@ module HaveAPI
         validator = validator.clone
         next if validator.validate(value, params)
 
-        ret << format(validator.message, value:)
+        ret << HaveAPI.localize(validator.message, value:)
       end
 
       ret.empty? ? true : ret

data/lib/haveapi/validators/acceptance.rb

@@ -23,13 +23,16 @@ module HaveAPI
                  take(:value)
                end
 
-      @message = take(:message, "has to be #{@value}")
+      @message = take(
+        :message,
+        HaveAPI.message('haveapi.validators.acceptance.accepted', value: @value)
+      )
     end
 
     def describe
       {
         value: @value,
-        message: @message
+        message: HaveAPI.localize(@message)
       }
     end
 

data/lib/haveapi/validators/confirmation.rb

@@ -24,7 +24,10 @@ module HaveAPI
       @equal = take(:equal, true)
       @message = take(
         :message,
-        @equal ? "must be the same as #{@param}" : "must be different from #{@param}"
+        HaveAPI.message(
+          @equal ? 'haveapi.validators.confirmation.same' : 'haveapi.validators.confirmation.different',
+          parameter: @param
+        )
       )
     end
 
@@ -32,7 +35,7 @@ module HaveAPI
       {
         equal: @equal ? true : false,
         parameter: @param,
-        message: @message
+        message: HaveAPI.localize(@message)
       }
     end
 

data/lib/haveapi/validators/exclusion.rb

@@ -23,13 +23,13 @@ module HaveAPI
         v.is_a?(::Symbol) ? v.to_s : v
       end
 
-      @message = take(:message, '%{value} cannot be used')
+      @message = take(:message, HaveAPI.message('haveapi.validators.exclusion.excluded'))
     end
 
     def describe
       {
         values: @values,
-        message: @message
+        message: HaveAPI.localize(@message)
       }
     end
 

data/lib/haveapi/validators/format.rb

@@ -20,7 +20,10 @@ module HaveAPI
       @rx = simple? ? take : take(:rx)
       @match = take(:match, true)
       @desc = take(:desc)
-      @message = take(:message, @desc || '%{value} is not in a valid format')
+      @message = take(
+        :message,
+        @desc || HaveAPI.message('haveapi.validators.format.invalid')
+      )
     end
 
     def describe
@@ -28,7 +31,7 @@ module HaveAPI
         rx: @rx.source,
         match: @match,
         description: @desc,
-        message: @message
+        message: HaveAPI.localize(@message)
       }
     end
 

data/lib/haveapi/validators/inclusion.rb

@@ -31,13 +31,13 @@ module HaveAPI
         @values = values.map { |v| v.is_a?(::Symbol) ? v.to_s : v }
       end
 
-      @message = take(:message, '%{value} cannot be used')
+      @message = take(:message, HaveAPI.message('haveapi.validators.inclusion.included'))
     end
 
     def describe
       {
         values: @values,
-        message: @message
+        message: HaveAPI.localize(@message)
       }
     end
 

data/lib/haveapi/validators/length.rb

@@ -30,16 +30,16 @@ module HaveAPI
       end
 
       msg = if @equals
-              "length has to be #{@equals}"
+              HaveAPI.message('haveapi.validators.length.equals', equals: @equals)
 
             elsif @min && !@max
-              "length has to be minimally #{@min}"
+              HaveAPI.message('haveapi.validators.length.min', min: @min)
 
             elsif !@min && @max
-              "length has to be maximally #{@max}"
+              HaveAPI.message('haveapi.validators.length.max', max: @max)
 
             else
-              "length has to be in range <#{@min}, #{@max}>"
+              HaveAPI.message('haveapi.validators.length.range', min: @min, max: @max)
             end
 
       @message = take(:message, msg)
@@ -47,7 +47,7 @@ module HaveAPI
 
     def describe
       ret = {
-        message: @message
+        message: HaveAPI.localize(@message)
       }
 
       if @equals