haveapi 0.28.3 → 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
 
@@ -45,7 +46,62 @@ module HaveAPI
                message: 'error message sent to the client'
              }
 
+    has_hook :request_exception,
+             desc: 'Called when an exception occurs outside action execution',
+             args: {
+               context: 'HaveAPI::Context',
+               exception: 'exception instance'
+             },
+             ret: {
+               http_status: 'HTTP status code to send to client',
+               message: 'error message sent to the client'
+             }
+
     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
 
@@ -53,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
@@ -68,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)
@@ -81,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
@@ -95,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
@@ -122,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
 
@@ -137,6 +200,32 @@ module HaveAPI
         halt code, headers, @formatter.format(false, nil, msg, version: false)
       end
 
+      def report_exception(exception, context = nil)
+        context ||= Context.new(
+          settings.api_server,
+          request: self,
+          params:,
+          endpoint: true
+        )
+
+        tmp =
+          begin
+            settings.api_server.call_hooks_for(
+              :request_exception,
+              args: [context, exception]
+            )
+          rescue StandardError => e
+            warn "HaveAPI request exception hook failed: #{e.class}: #{e.message}"
+            {}
+          end
+
+        report_error(
+          tmp[:http_status] || 500,
+          {},
+          tmp[:message] || HaveAPI.message('haveapi.errors.server_error')
+        )
+      end
+
       def root
         settings.api_server.root
       end
@@ -223,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)
@@ -284,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'
@@ -292,10 +439,16 @@ 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
+          report_exception(env['sinatra.error'])
         end
 
         after do
+          restore_request_locale
+
           if Object.const_defined?(:ActiveRecord)
             ActiveRecord::Base.connection_handler.clear_active_connections!
           end
@@ -493,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: {} }
 
@@ -528,113 +702,125 @@ module HaveAPI
 
     def mount_action(v, route)
       @sinatra.method(route.http_method).call(route.sinatra_path) do
-        setup_formatter
+        context = nil
 
-        if route.action.auth || settings.api_server.action_state_auth_required?(route)
-          authenticate!(v)
-        else
-          authenticated?(v)
-        end
+        begin
+          setup_formatter
 
-        raw_body = request.body.read
-        body_method = !%i[get head options].include?(route.http_method.to_sym)
+          if route.action.auth || settings.api_server.action_state_auth_required?(route)
+            authenticate!(v)
+          else
+            authenticated?(v)
+          end
 
-        if body_method && !raw_body.empty? && !settings.api_server.send(:json_content_type?, request)
-          report_error(415, {}, 'Unsupported Content-Type')
-        end
+          raw_body = request.body ? request.body.read : ''
+          body_method = !%i[get head options].include?(route.http_method.to_sym)
 
-        begin
-          body = raw_body.empty? ? nil : JSON.parse(raw_body)
-        rescue JSON::ParserError
-          report_error(400, {}, 'Bad JSON syntax')
-        end
+          if body_method && !raw_body.empty? && !settings.api_server.send(:json_content_type?, request)
+            report_error(415, {}, HaveAPI.message('haveapi.errors.unsupported_content_type'))
+          end
 
-        if !raw_body.empty? && !body.is_a?(Hash)
-          report_error(400, {}, 'JSON body must be an object')
-        end
+          begin
+            body = raw_body.empty? ? nil : JSON.parse(raw_body)
+          rescue JSON::ParserError
+            report_error(400, {}, HaveAPI.message('haveapi.errors.bad_json_syntax'))
+          end
 
-        action_params = settings.api_server.send(:path_params, route, params)
-        action_input = body_method ? (body || {}) : request.GET
+          if !raw_body.empty? && !body.is_a?(Hash)
+            report_error(400, {}, HaveAPI.message('haveapi.errors.json_body_object'))
+          end
 
-        context = Context.new(
-          settings.api_server,
-          version: v,
-          request: self,
-          action: route.action,
-          path: route.path,
-          path_params: action_params,
-          input: action_input,
-          user: current_user,
-          endpoint: true,
-          resource_path: route.resource_path
-        )
+          action_params = settings.api_server.send(:path_params, route, params)
+          action_input = body_method ? (body || {}) : request.GET
+
+          context = Context.new(
+            settings.api_server,
+            version: v,
+            request: self,
+            action: route.action,
+            path: route.path,
+            path_params: action_params,
+            input: action_input,
+            user: current_user,
+            endpoint: true,
+            resource_path: route.resource_path
+          )
 
-        action = route.action.new(request, v, action_params, action_input, context)
+          action = route.action.new(request, v, action_params, action_input, context)
 
-        unless action.authorized?(current_user)
-          report_error(403, {}, 'Access denied. Insufficient permissions.')
-        end
+          unless action.authorized?(current_user)
+            report_error(403, {}, HaveAPI.message('haveapi.authorization.insufficient_permissions'))
+          end
 
-        status, reply, errors, http_status = action.safe_exec
-        @halted = true
+          status, reply, errors, http_status = action.safe_exec
+          @halted = true
 
-        [
-          http_status || 200,
-          @formatter.format(
-            status,
-            status ? reply : nil,
-            status ? nil : reply,
-            errors,
-            version: false
-          )
-        ]
+          [
+            http_status || 200,
+            @formatter.format(
+              status,
+              status ? reply : nil,
+              status ? nil : reply,
+              errors,
+              version: false
+            )
+          ]
+        rescue Exception => e # rubocop:disable Lint/RescueException
+          report_exception(e, context)
+        end
       end
 
       @sinatra.options route.sinatra_path do |*args|
-        setup_formatter
-        access_control
-        route_method = route.http_method.to_s.upcase
+        ctx = nil
 
-        pass if params[:method] && params[:method] != route_method
+        begin
+          setup_formatter
+          access_control
+          route_method = route.http_method.to_s.upcase
 
-        if route.action.auth || settings.api_server.action_state_auth_required?(route)
-          authenticate!(v)
-        else
-          authenticated?(v)
-        end
+          pass if params[:method] && params[:method] != route_method
 
-        ctx = Context.new(
-          settings.api_server,
-          version: v,
-          request: self,
-          action: route.action,
-          path: route.path,
-          args:,
-          params:,
-          user: current_user,
-          endpoint: true,
-          resource_path: route.resource_path,
-          doc: true
-        )
+          if route.action.auth || settings.api_server.action_state_auth_required?(route)
+            authenticate!(v)
+          else
+            authenticated?(v)
+          end
 
-        begin
-          desc = route.action.describe(ctx)
+          ctx = Context.new(
+            settings.api_server,
+            version: v,
+            request: self,
+            action: route.action,
+            path: route.path,
+            args:,
+            params:,
+            user: current_user,
+            endpoint: true,
+            resource_path: route.resource_path,
+            doc: true
+          )
 
-          unless desc
-            report_error(403, {}, 'Access denied. Insufficient permissions.')
+          begin
+            desc = route.action.describe(ctx)
+
+            unless desc
+              report_error(403, {}, HaveAPI.message('haveapi.authorization.insufficient_permissions'))
+            end
+          rescue ValidationError => e
+            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] || HaveAPI.message('haveapi.errors.server_error')
+            )
           end
-        rescue ValidationError => e
-          report_error(400, e.to_hash, e.message)
-        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'
-          )
-        end
 
-        @formatter.format(true, desc)
+          @formatter.format(true, desc)
+        rescue Exception => e # rubocop:disable Lint/RescueException
+          report_exception(e, ctx)
+        end
       end
     end
 
@@ -689,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