jsapi 1.4 → 2.0

data/lib/jsapi/controller/methods.rb

@@ -1,8 +1,63 @@
 # frozen_string_literal: true
 
+require_relative 'methods/callbacks'
+
 module Jsapi
   module Controller
+    # Raised when no operation with the specified name could be found.
+    class OperationNotFound < StandardError
+      def initialize(operation_name)
+        super("operation not found: #{operation_name}")
+      end
+    end
+
+    # Raised when no suitable response could be found.
+    class ResponseNotFound < StandardError
+      def initialize(operation, status)
+        super(
+          if operation.responses.none?
+            "#{operation.name.inspect} has no responses"
+          else
+            "#{operation.name.inspect} has no response for status #{status}"
+          end
+        )
+      end
+    end
+
+    # Raised when the current request could not be authenticated.
+    class Unauthorized < StandardError
+      def initialize # :nodoc:
+        super('request could not be authenticated')
+      end
+    end
+
+    # Raised when the request parameters are invalid.
+    class ParametersInvalid < StandardError
+
+      # The parameters.
+      attr_reader :params
+
+      def initialize(params)
+        @params = params
+        super('')
+      end
+
+      # Returns the errors encountered.
+      def errors
+        @params.errors.errors
+      end
+
+      # Overrides <code>Exception#message</code> to lazily generate the error message.
+      def message
+        "#{@params.errors.full_messages.map { |m| m.delete_suffix('.') }.join('. ')}."
+      end
+    end
+
     module Methods
+      def self.included(base) # :nodoc:
+        base.include(Callbacks)
+      end
+
       # Returns the Meta::Definitions instance associated with the controller class. In
       # particular, this method can be used to create an OpenAPI document, for example:
       #
@@ -12,18 +67,36 @@ module Jsapi
         self.class.api_definitions
       end
 
-      # Performs an API operation by calling the given block. The request parameters are
-      # passed as an instance of the operation's model class to the block. The object
-      # returned by the block is implicitly rendered according to the appropriate +response+
-      # specification when the content type is a JSON MIME type. When content type is
-      # <code>application/json-seq</code>, the object returned by the block is streamed in
-      # JSON sequence text format.
+      ##
+      # :method: api_operation
+      # :args: operation_name = nil, omit: nil, status: nil, strong: false, &block
+      #
+      # Performs an API operation by calling the given block.
+      #
+      # The request parameters are passed as an instance of the operation's model class to the
+      # block. Parameter names are converted to snake case.
+      #
+      # The object returned by the block is implicitly rendered or streamed according to the
+      # most appropriate +response+ specification if the media type of that response is one of:
+      #
+      # - <code>"application/json"</code>, <code>"text/json"</code>, <code>"\*/\*+json"</code> -
+      #   The \JSON representation of the object is rendered.
+      # - <code>"application/json-seq"</code> - The object is streamed in \JSON sequence
+      #   text format.
+      # - <code>"text/plain"</code> - The +to_s+ representation of the object is rendered.
+      #
+      # Example:
       #
       #   api_operation('foo') do |api_params|
       #     # ...
       #   end
       #
-      # +operation_name+ can be +nil+ if the controller handles one operation only.
+      # +operation_name+ can be omitted if the controller handles one operation only.
+      #
+      # If no operation could be found for +operation_name+, an OperationNotFound exception
+      # is raised.
+      #
+      # +:status+ specifies the HTTP status code of the response to be produced.
       #
       # If +:strong+ is +true+, parameters that can be mapped are accepted only. That means
       # that the model passed to the block is invalid if there are any request parameters
@@ -35,42 +108,106 @@ module Jsapi
       # - +:empty+ - All of the  properties whose value is empty are omitted.
       # - +:nil+ - All of the properties whose value is +nil+ are omitted.
       #
-      # Raises an +ArgumentError+ when +:omit+ is other than +:empty+, +:nil+ or +nil+.
-      def api_operation(operation_name = nil,
-                        omit: nil,
-                        status: nil,
-                        strong: false,
-                        &block)
-        _api_operation(
-          operation_name,
-          bang: false,
-          omit: omit,
-          status: status,
-          strong: strong,
-          &block
-        )
-      end
+      # Raises an Unauthorized exception if the Authentication module is included and the
+      # current request could not be authenticated.
+      #
+      # See Callbacks::ClassMethods for possible callbacks.
 
-      # Like +api_operation+, except that a ParametersInvalid exception is raised on
-      # invalid request parameters.
+      ##
+      # :method: api_operation!
+      # :args: operation_name = nil, omit: nil, status: nil, strong: false, &block
+      #
+      # Like +api_operation+, except that a ParametersInvalid exception is raised
+      # when request parameters are invalid.
       #
       #   api_operation!('foo') do |api_params|
       #     # ...
       #   end
-      #
-      def api_operation!(operation_name = nil,
-                         omit: nil,
-                         status: nil,
-                         strong: false,
-                         &block)
-        _api_operation(
-          operation_name,
-          bang: true,
-          omit: omit,
-          status: status,
-          strong: strong,
-          &block
-        )
+
+      [true, false].each do |bang|
+        define_method(bang ? :api_operation! : :api_operation) \
+        do |operation_name = nil, omit: nil, status: nil, strong: false, &block|
+          operation = _api_operation(operation_name)
+          response_model = nil
+
+          result = begin
+            # Authenticate request first if Authentication is included
+            if respond_to?(:_api_authenticated?, true)
+              raise Unauthorized unless _api_authenticated?(operation)
+
+              _api_callback(:after_authentication, operation_name)
+            end
+
+            status = Status::Code.from(status)
+            response_model = _api_response_model(operation, status)
+
+            api_params = _api_params(operation, strong: strong)
+
+            if bang
+              raise ParametersInvalid.new(api_params) if api_params.invalid?
+
+              _api_callback(:after_validation, operation_name, api_params)
+            end
+
+            block&.call(api_params)
+          rescue StandardError => e
+            definitions = api_definitions
+
+            # Lookup a rescue handler
+            rescue_handler = definitions.rescue_handler_for(e)
+            raise e if rescue_handler.nil?
+
+            # Replace the status code and response model
+            status = rescue_handler.status_code
+            response_model = operation.find_response(status)
+            raise e if response_model.nil?
+
+            # Call on_rescue callbacks
+            definitions.on_rescue_callbacks.each do |callback|
+              callback.respond_to?(:call) ? callback.call(e) : send(callback, e)
+            end
+
+            Error.new(e, status: status)
+          end
+          # Return if response body has already been rendered
+          return if response_body
+
+          # Produce response
+          media_type, content_model = _api_media_type_and_content_model(response_model)
+          status = status&.to_i
+          return head(status) unless content_model
+
+          result = _api_before_rendering(operation_name, result, api_params)
+
+          api_response = Response.new(
+            result,
+            content_model,
+            omit: omit,
+            locale: response_model.locale
+          )
+          if media_type.json?
+            render(
+              json: api_response,
+              status: status,
+              content_type: media_type.to_s
+            )
+          elsif media_type == Media::Type::TEXT_PLAIN
+            render(
+              plain: result,
+              status: status,
+              content_type: media_type.to_s
+            )
+          elsif media_type == Media::Type::APPLICATION_JSON_SEQ
+            self.content_type = media_type.to_s
+            response.status = status
+
+            response.stream.tap do |stream|
+              api_response.write_json_seq_to(stream)
+            ensure
+              stream.close
+            end
+          end
+        end
       end
 
       # Returns the request parameters as an instance of the operation's model class.
@@ -78,7 +215,10 @@ module Jsapi
       #
       #   params = api_params('foo')
       #
-      # +operation_name+ can be +nil+ if the controller handles one operation only.
+      # +operation_name+ can be omitted if the controller handles one operation only.
+      #
+      # If no operation could be found for +operation_name+, an OperationNotFound exception
+      # is raised.
       #
       # If +strong+ is +true+, parameters that can be mapped are accepted only. That means
       # that the model returned is invalid if there are any request parameters that can't be
@@ -86,12 +226,7 @@ module Jsapi
       #
       # Note that each call of +api_params+ returns a newly created instance.
       def api_params(operation_name = nil, strong: false)
-        definitions = api_definitions
-        _api_params(
-          _find_api_operation(operation_name, definitions),
-          definitions,
-          strong: strong
-        )
+        _api_params(_api_operation(operation_name), strong: strong)
       end
 
       # Returns a Response to serialize the JSON representation of +result+ according to the
@@ -99,104 +234,62 @@ module Jsapi
       #
       #   render(json: api_response(bar, 'foo', status: 200))
       #
-      # +operation_name+ can be +nil+ if the controller handles one operation only.
+      # +operation_name+ can be omitted if the controller handles one operation only.
+      #
+      # If no operation could be found for +operation_name+, an OperationNotFound exception
+      # is raised.
+      #
+      # +:status+ specifies the HTTP status code of the response to be produced.
       #
       # The +:omit+ option specifies on which conditions properties are omitted.
       # Possible values are:
       #
       # - +:empty+ - All of the  properties whose value is empty are omitted.
       # - +:nil+ - All of the properties whose value is +nil+ are omitted.
-      #
-      # Raises an +ArgumentError+ when +:omit+ is other than +:empty+, +:nil+ or +nil+.
       def api_response(result, operation_name = nil, omit: nil, status: nil)
-        definitions = api_definitions
-        operation = _find_api_operation(operation_name, definitions)
-        response_model = _api_response(operation, status, definitions)
+        status = Status::Code.from(status)
+        operation = _api_operation(operation_name)
+        response_model = _api_response_model(operation, status)
 
-        Response.new(result, response_model, api_definitions, omit: omit)
+        Response.new(
+          result,
+          _api_media_type_and_content_model(response_model).second,
+          omit: omit,
+          locale: response_model.locale
+        )
       end
 
       private
 
-      def _api_operation(operation_name, bang:, omit:, status:, strong:, &block)
-        definitions = api_definitions
-        operation = _find_api_operation(operation_name, definitions)
-
-        # Perform operation
-        response_model = _api_response(operation, status, definitions)
-        head(status) && return unless block
-
-        params = _api_params(operation, definitions, strong: strong)
-
-        result = begin
-          raise ParametersInvalid.new(params) if bang && params.invalid?
-
-          block.call(params)
-        rescue StandardError => e
-          # Lookup a rescue handler
-          rescue_handler = definitions.rescue_handler_for(e)
-          raise e if rescue_handler.nil?
-
-          # Change the HTTP status code and response model
-          status = rescue_handler.status
-          response_model = operation.response(status)&.resolve(definitions)
-          raise e if response_model.nil?
-
-          # Call on_rescue callbacks
-          definitions.on_rescue_callbacks.each do |callback|
-            if callback.respond_to?(:call)
-              callback.call(e)
-            else
-              send(callback, e)
-            end
-          end
-
-          Error.new(e, status: status)
-        end
-
-        # Write response
-        return unless response_model.json_type? || response_model.json_seq_type?
-
-        response = Response.new(result, response_model, definitions, omit: omit)
-        self.content_type = response_model.content_type
+      def _api_media_type_and_content_model(response_model)
+        response_model.media_type_and_content_for(
+          *(request.headers['Accept']&.split(',').presence || [Media::Range::ALL])
+        )
+      end
 
-        if response_model.json_seq_type?
-          self.response.status = status
+      def _api_operation(operation_name)
+        operation = api_definitions.find_operation(operation_name)
+        return operation if operation
 
-          self.response.stream.tap do |stream|
-            response.write_json_seq_to(stream)
-          ensure
-            stream.close
-          end
-        else
-          render(json: response, status: status)
-        end
+        raise OperationNotFound.new(operation_name)
       end
 
-      def _api_params(operation, definitions, strong:)
+      def _api_params(operation, strong:)
         (operation.model || Model::Base).new(
           Parameters.new(
             params.except(:action, :controller, :format).permit!,
             request,
             operation,
-            definitions,
             strong: strong
           )
         )
       end
 
-      def _api_response(operation, status, definitions)
-        response = operation.response(status)
-        return response.resolve(definitions) if response
-
-        raise "status code not defined: #{status}"
-      end
-
-      def _find_api_operation(operation_name, definitions)
-        operation = definitions.find_operation(operation_name)
-        return operation if operation
+      def _api_response_model(operation, status)
+        response_model = operation.find_response(status)
+        return response_model if response_model
 
-        raise "operation not defined: #{operation_name}"
+        raise ResponseNotFound.new(operation, status)
       end
     end
   end

data/lib/jsapi/controller/parameters.rb

@@ -8,25 +8,23 @@ module Jsapi
 
       attr_reader :raw_additional_attributes, :raw_attributes
 
-      # Creates a new instance that wraps +params+ according to +operation+. References are
-      # resolved to API components in +definitions+.
+      # Creates a new instance that wraps +params+ according to +operation+.
       #
       # If +strong+ is true+ parameters that can be mapped are accepted only. That means that
       # the instance created is invalid if +params+ contains any parameters that can't be
       # mapped to a parameter or a request body property of +operation+.
-      def initialize(params, request, operation, definitions, strong: false)
+      def initialize(params, request, operation, strong: false)
         params = params.to_h
         unassigned_params = params.dup
 
         @params_to_be_validated = strong == true ? params.dup : {}
-        @raw_attributes = {}
 
         # Parameters
-        operation.resolved_parameters(definitions).each do |name, parameter_model|
-          @raw_attributes[name] = JSON.wrap(
+        @raw_attributes = operation.parameters.transform_values do |parameter_model|
+          JSON.wrap(
             case parameter_model.in
             when 'header'
-              request.headers[name]
+              request.headers[parameter_model.name]
             when 'querystring'
               query_params = request.query_parameters
               keys = query_params.keys
@@ -36,27 +34,23 @@ module Jsapi
 
               parameter_model.object? ? params.slice(*keys) : query_params.to_query
             else
-              unassigned_params.delete(name)
+              unassigned_params.delete(parameter_model.name)
             end,
-            parameter_model.schema.resolve(definitions),
-            definitions,
+            parameter_model.schema,
             context: :request
           )
         end
 
         # Request body
-        request_body_schema = operation.request_body&.resolve(definitions)
-                                       &.schema&.resolve(definitions)
+        request_body_schema = operation.request_body&.content_for(request.media_type)&.schema
         if request_body_schema&.object?
           request_body = JSON.wrap(
             unassigned_params,
             request_body_schema,
-            definitions,
             context: :request
           )
           @raw_attributes.merge!(request_body.raw_attributes)
           @raw_additional_attributes = request_body.raw_additional_attributes
-          @params_to_be_validated.except!(*@raw_additional_attributes.keys)
         else
           @raw_additional_attributes = {}
         end
@@ -66,18 +60,24 @@ module Jsapi
       # otherwise. Detected errors are added to +errors+.
       def validate(errors)
         validate_attributes(errors) &&
-          validate_parameters(@params_to_be_validated, attributes, errors)
+          validate_parameters(@params_to_be_validated, self, errors)
       end
 
       private
 
-      def validate_parameters(params, attributes, errors, path = [])
+      def validate_parameters(params, model, errors, path = [])
         params.each.map do |key, value|
-          if attributes.key?(key)
-            # Validate nested parameters
-            !value.respond_to?(:keys) || validate_parameters(
+          if model.raw_attributes.key?(key)
+            validate_parameter(
               value,
-              attributes[key].try(:attributes) || {},
+              model.raw_attributes[key],
+              errors,
+              path + [key]
+            )
+          elsif model.raw_additional_attributes.key?(key)
+            validate_parameter(
+              value,
+              model.raw_additional_attributes[key],
               errors,
               path + [key]
             )
@@ -94,6 +94,10 @@ module Jsapi
           end
         end.all?
       end
+
+      def validate_parameter(value, model, errors, path)
+        !model.schema.object? || validate_parameters(value, model, errors, path)
+      end
     end
   end
 end

data/lib/jsapi/controller/response.rb

@@ -15,8 +15,34 @@ module Jsapi
         end
       end
 
-      # Creates a new instance to jsonify +object+ according to +response+. References
-      # are resolved to API components in +definitions+.
+      class HashReader # :nodoc:
+        delegate_missing_to :@hash
+
+        def initialize(hash)
+          @hash = hash
+        end
+
+        def [](key)
+          return unless @hash.key?(key)
+
+          (@read_keys ||= []) << key
+          @hash[key]
+        end
+
+        def additional_properties
+          if @hash.key?('additional_properties')
+            @hash['additional_properties']
+          elsif @hash.key?(:additional_properties)
+            @hash[:additional_properties]
+          elsif @read_keys
+            @hash.except(*@read_keys)
+          else
+            @hash
+          end
+        end
+      end
+
+      # Creates a new instance to jsonify +object+ according to +content_model+.
       #
       # The +:omit+ option specifies on which conditions properties are omitted.
       # Possible values are:
@@ -25,10 +51,9 @@ module Jsapi
       # - +:nil+ - All of the properties whose value is +nil+ are omitted.
       #
       # Raises an +ArgumentError+ when +:omit+ is other than +:empty+, +:nil+ or +nil+.
-      def initialize(object, response, definitions, omit: nil)
+      def initialize(object, content_model, omit: nil, locale: nil)
         @object = object
-        @response = response
-        @definitions = definitions
+        @content_model = content_model
 
         @omittable_check =
           case omit
@@ -39,8 +64,14 @@ module Jsapi
           when :empty
             ->(value, schema) { schema.omittable? && value.try(:empty?) }
           else
-            raise InvalidArgumentError.new('omit', omit, valid_values: %i[empty nil])
+            raise ArgumentError, Messages.invalid_value(
+              name: 'omit',
+              value: omit,
+              valid_values: %i[empty nil]
+            )
           end
+
+        @locale = locale
       end
 
       def inspect # :nodoc:
@@ -49,17 +80,16 @@ module Jsapi
 
       # Returns the \JSON representation of the response as a string.
       def to_json(*)
-        schema = @response.schema.resolve(@definitions)
-        with_locale { jsonify(@object, schema) }.to_json
+        with_locale { jsonify(@object, @content_model.schema) }.to_json
       end
 
       # Writes the response in \JSON sequence text format to +stream+.
       def write_json_seq_to(stream)
-        schema = @response.schema.resolve(@definitions)
+        schema = @content_model.schema
         with_locale do
           items, item_schema =
             if schema.array? && @object.respond_to?(:each)
-              [@object, schema.items.resolve(@definitions)]
+              [@object, schema.items]
             else
               [[@object], schema]
             end
@@ -76,7 +106,7 @@ module Jsapi
       private
 
       def jsonify(object, schema)
-        object = schema.default_value(@definitions, context: :response) if object.nil?
+        object = schema.default_value(context: :response) if object.nil?
 
         if object.nil?
           raise JsonifyError, "can't be nil" unless schema.nullable?
@@ -112,7 +142,7 @@ module Jsapi
       end
 
       def jsonify_array(array, schema)
-        item_schema = schema.items.resolve(@definitions)
+        item_schema = schema.items
         index = 0
 
         Array(array).map do |item|
@@ -125,39 +155,41 @@ module Jsapi
       end
 
       def jsonify_object(object, schema)
-        schema = schema.resolve_schema(object, @definitions, context: :response)
-        properties = {}
-
-        # Add properties
-        schema.resolve_properties(@definitions, context: :response).each_value do |property|
-          property_schema = property.schema.resolve(@definitions)
-          property_value = property.reader.call(object)
-          property_value = property_schema.default if property_value.nil?
-          next if @omittable_check&.call(property_value, property_schema)
-
-          properties[property.name] = jsonify(property_value, property_schema)
-        rescue JsonifyError => e
-          raise e.prepend(".#{property.name}")
-        end
-        # Add additional properties
-        if (additional_properties = schema.additional_properties)
-          additional_properties_schema = additional_properties.schema.resolve(@definitions)
-
-          additional_properties.source.call(object)&.each do |key, value|
-            next if properties.key?(key = key.to_s)
-
-            properties[key] = jsonify(value, additional_properties_schema)
+        schema = schema.resolve_schema(object, context: :response)
+        additional_properties = schema.additional_properties
+        object = HashReader.new(object) if additional_properties && object.is_a?(Hash)
+
+        {}.tap do |properties|
+          # Add properties
+          schema.resolve_properties(context: :response).each_value do |property|
+            property_schema = property.schema
+            property_value = property.reader.call(object)
+            property_value = property_schema.default if property_value.nil?
+            next if @omittable_check&.call(property_value, property_schema)
+
+            properties[property.name] = jsonify(property_value, property_schema)
           rescue JsonifyError => e
-            raise e.prepend(".#{key}")
+            raise e.prepend(".#{property.name}")
           end
-        end
+          # Add additional properties
+          if additional_properties
+            additional_properties_schema = additional_properties.schema
+
+            additional_properties.source.call(object)&.each do |key, value|
+              key = key.to_s
+              next if properties.key?(key)
 
-        properties.presence
+              properties[key] = jsonify(value, additional_properties_schema)
+            rescue JsonifyError => e
+              raise e.prepend(".#{key}")
+            end
+          end
+        end.presence
       end
 
       def with_locale(&block)
-        if @response.locale
-          I18n.with_locale(@response.locale, &block)
+        if @locale
+          I18n.with_locale(@locale, &block)
         else
           yield
         end