easy-jsonapi 1.0.0

data/lib/easy/jsonapi/exceptions/headers_exceptions.rb

@@ -0,0 +1,156 @@
+# frozen_string_literal: true
+
+require 'easy/jsonapi/exceptions/user_defined_exceptions'
+require 'easy/jsonapi/parser/headers_parser'
+require 'easy/jsonapi/utility'
+
+module JSONAPI
+  module Exceptions
+    # Validates that Headers comply with the JSONAPI specification
+    module HeadersExceptions 
+
+      # Media types that are complient with the spec if no parameters are included
+      JSONAPI_MEDIA_TYPES = ['application/vnd.api+json', '*/*', 'application/*'].freeze
+      
+      # A more specific standard error to raise when an exception is found
+      class InvalidHeader < StandardError
+        attr_accessor :status_code
+
+        # Init w a status code, so that it can be accessed when rescuing an exception
+        def initialize(status_code)
+          @status_code = status_code
+          super
+        end
+      end
+
+      # Check http verb vs included headers
+      # @param env [Hash] The rack environment variable
+      def self.check_request(env, config_manager = nil, opts = {})
+        check_compliance(env, config_manager, opts)
+        check_http_method_against_headers(env)
+      end
+
+      # Check jsonapi compliance
+      # @param (see #check_request)
+      def self.check_compliance(env, config_manager = nil, opts = {})
+        check_content_type(env)
+        check_accept(env)
+
+        hdrs = JSONAPI::Parser::HeadersParser.parse(env)
+        usr_opts = { http_method: opts[:http_method], path: opts[:path] }
+        err_msg = JSONAPI::Exceptions::UserDefinedExceptions.check_user_header_requirements(hdrs, config_manager, usr_opts)
+        return err_msg unless err_msg.nil?
+      end
+
+      class << self
+        private
+
+        # Checks the content type of the request to see if it is jsonapi.
+        # @param (see #compliant?)
+        # @return nil Returns nil if no error found
+        # @raise InvalidHeader if not jsonapi compliant
+        def check_content_type(env)
+          return if content_type_not_included_or_is_compliant?(env['CONTENT_TYPE'])
+          
+          raise_error('Clients MUST send all JSON:API data in request documents with the header ' \
+                      'Content-Type: application/vnd.api+json without any media type parameters.',
+                      415)
+        end
+
+        # Checks to see the Accept header includes jsonapi without params
+        # @param (see #compliant?)
+        def check_accept(env)
+          return if env['HTTP_ACCEPT'].nil? || # no accept header means compliant
+                    contains_at_least_one_jsonapi_media_type_without_params?(env['HTTP_ACCEPT'])
+
+          raise_error('Clients that include the JSON:API media type in their Accept header MUST ' \
+                      'specify the media type there at least once without any media type parameters.',
+                      406)
+        end
+
+        # @param content_type [String | NilClass] The http content-type header
+        # @return [TrueClass | FalseClass]
+        def content_type_not_included_or_is_compliant?(content_type)
+          content_type.nil? || content_type == 'application/vnd.api+json'
+        end
+        
+        # Check the http verb against the content_type and accept header and raise
+        #   error if the combination doesn't make sense
+        # @param (see #compliant?)
+        # @raise InvalidHeader the invalid header incombination with the http verb
+        def check_http_method_against_headers(env)
+          case env['REQUEST_METHOD']
+          when 'GET'
+            check_get_against_hdrs(env)
+          when 'POST' || 'PATCH' || 'PUT'
+            check_post_against_hdrs(env)
+          when 'DELETE'
+            check_delete_against_hdrs(env)
+          end
+        end
+
+        # Raise error if a GET request has a body or a content type header
+        # @param (see #compliant?)
+        def check_get_against_hdrs(env)
+          raise_error('GET requests cannot have a body.') unless env['rack.input'].nil?
+          raise_error("GET request cannot have a 'CONTENT_TYPE' http header.") unless env['CONTENT_TYPE'].nil?
+        end
+
+        # POST, PUT, and PATCH request must have a content type header,
+        #   a body, and a content-type and accept header that accepts jsonapi
+        # @param (see #compliant?)
+        def check_post_against_hdrs(env)
+          raise_error("POST, PUT, and PATCH requests must have a 'CONTENT_TYPE' header.") unless env['CONTENT_TYPE']
+          raise_error('POST, PUT, and PATCH requests must have a body.') unless env['rack.input']
+          
+          return if env['CONTENT_TYPE'] == 'application/vnd.api+json' && accepts_jsonapi?(env)
+          
+          raise_error('POST, PUT, and PATCH requests must have an ACCEPT header that includes the ' \
+                      "JSON:API media type, if they include a JSON:API 'CONTENT_TYPE' header")
+        end
+
+        # Check the accept header to see if any of the provided media types indicate that
+        #   jsonapi is accepted
+        # @param (see #compliant?)
+        def accepts_jsonapi?(env)
+          return true if env['HTTP_ACCEPT'].nil?
+          
+          env['HTTP_ACCEPT'].split(',').each do |mt|
+            return true if JSONAPI_MEDIA_TYPES.include?(mt)
+          end
+          false
+        end
+
+        # Raise error if DELETE hdr has a body or a content type header
+        def check_delete_against_hdrs(env)
+          raise_error('DELETE requests cannot have a body.') unless env['rack.input'].nil?
+          raise_error("DELETE request cannot have a 'CONTENT_TYPE' http header.") unless env['CONTENT_TYPE'].nil?
+        end
+
+        # @param accept_hdr [String] The value of the http accept header
+        def contains_at_least_one_jsonapi_media_type_without_params?(accept_hdr)
+          accept_hdr.split(',').each do |mt|
+            if mt == 'application/vnd.api+json'
+              return true
+            end
+          end
+          false
+        end
+
+        # Is the media type jsonapi and does it have included parameters
+        # @param media_type [String] One of the accepted media types
+        # @return [TrueClass | FalseClass]
+        def jsonapi_and_has_params?(media_type)
+          media_type_split = media_type.split(';')
+          JSONAPI_MEDIA_TYPES.include?(media_type_split.first) && \
+            contains_media_type_params?(media_type_split)
+        end
+
+        # @param msg [String]  The message to raise InvalidHeader with.
+        def raise_error(msg, status_code = 400)
+          raise InvalidHeader.new(status_code), msg
+        end
+      end
+    end
+  end
+end

data/lib/easy/jsonapi/exceptions/naming_exceptions.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module JSONAPI
+  module Exceptions
+    
+    # Checking for JSONAPI naming rules compliance
+    module NamingExceptions
+      
+      # JSONAPI member names can only contain a-z, A-Z, 0-9, '-', '_', and the last two cannot be used
+      #   at the start or end of a member name.
+      # @param name [String]  The string to check for member name rule compliance
+      # @return 
+      def self.check_member_constraints(name)
+        name = name.to_s
+        return 'Member names MUST contain at least one character' if name == ''
+        unless (name =~ /[^a-zA-Z0-9_-]/).nil?
+          return 'Member names MUST contain only the allowed characters: ' \
+                  "a-z, A-Z, 0-9, '-', '_'"
+        end
+        unless (name[0] =~ /[-_]/).nil? && (name[-1] =~ /[-_]/).nil?
+          return 'Member names MUST start and end with a globally allowed character'
+        end
+        nil
+      end
+
+      # JSONAPI implementation specific query parameters follow the same constraints as member names
+      #   with the additional requirement that they must also contain at least one non a-z character.
+      # @param name [String]  The string to check for 
+      def self.check_additional_constraints(name)
+        name = name.to_s
+        return nil unless (name =~ /[^a-z]/).nil?
+        'Implementation specific query parameters MUST contain at least one non a-z character'
+      end
+    end
+  end
+end

data/lib/easy/jsonapi/exceptions/query_params_exceptions.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+require 'easy/jsonapi/exceptions/naming_exceptions'
+require 'easy/jsonapi/exceptions/user_defined_exceptions'
+
+module JSONAPI
+  module Exceptions
+    
+    # Validates that the Query Parameters comply with the JSONAPI specification
+    module QueryParamsExceptions
+      
+      # A more specific Standard Error to raise
+      class InvalidQueryParameter < StandardError
+        attr_accessor :status_code
+
+        # Init w a status code, so that it can be accessed when rescuing an exception
+        def initialize(status_code)
+          @status_code = status_code
+          super
+        end
+      end
+
+      # The jsonapi specific query parameters.
+      SPECIAL_QUERY_PARAMS = %i[include fields page sort filter].freeze
+
+      # Checks to see if the query paramaters conform to the JSONAPI spec and raises InvalidQueryParameter
+      #   if any parts are found to be non compliant
+      # @param rack_req_params [Hash]  The hash of the query parameters given by Rack::Request
+      def self.check_compliance(rack_req_params, config_manager = nil, opts = {})
+        impl_spec_names = rack_req_params.keys - %w[include fields page sort filter]
+        impl_spec_names.each do |name|
+          check_param_name(name)
+        end
+        
+        err_msg = JSONAPI::Exceptions::UserDefinedExceptions.check_user_query_param_requirements(rack_req_params, config_manager, opts)
+        return err_msg unless err_msg.nil?
+
+        nil
+      end
+
+      # Checks an implementation specific param name to see if it complies to the spec.
+      def self.check_param_name(name)
+        should_return =  
+          NamingExceptions.check_member_constraints(name).nil? && \
+          NamingExceptions.check_additional_constraints(name).nil? && \
+          !name.include?('-')
+        return if should_return
+        
+        raise_error(
+          'Implementation specific query parameters MUST adhere to the same constraints ' \
+          'as member names. Allowed characters are: a-z, A-Z, 0-9 for beginning, middle, or end characters, ' \
+          "and '_' is allowed for middle characters. (While the JSON:API spec also allows '-', it is not " \
+          'recommended, and thus is prohibited in this implementation). ' \
+          'Implementation specific query members MUST contain at least one non a-z character as well. ' \
+          "Param name given: \"#{name}\""
+        )
+      end
+
+      # @param msg [String]  The message to raise InvalidQueryParameter with.
+      def self.raise_error(msg, status_code = 400)
+        raise InvalidQueryParameter.new(status_code), msg
+      end
+
+      private_class_method :raise_error
+    end
+  end
+end

data/lib/easy/jsonapi/exceptions/user_defined_exceptions.rb

@@ -0,0 +1,253 @@
+# frozen_string_literal: true
+
+require 'easy/jsonapi/exceptions/document_exceptions'
+require 'easy/jsonapi/exceptions/headers_exceptions'
+require 'easy/jsonapi/exceptions/query_params_exceptions'
+
+module JSONAPI
+  module Exceptions
+    # Allows a user of the gem to define extra requirements they want the middlewar to check for.
+    module UserDefinedExceptions
+
+      # Invaliid Document Error when checking user defined restrictions
+      class InvalidComponent < StandardError
+        attr_accessor :status_code, :msg
+  
+        def initialize(err)
+          @msg = err[0]
+          @status_code = err[1] || 400
+          super
+        end
+      end
+
+      # The type of UserDefinedExceptions Error
+      class InvalidDocument < InvalidComponent
+      end
+      
+      # The type of UserDefinedExceptions Error
+      class InvalidHeader < InvalidComponent
+      end
+      
+      # The type of UserDefinedExceptions Error
+      class InvalidQueryParam < InvalidComponent
+      end
+
+      class << self
+
+        # Performs compliance checks on the document to see if it complies
+        #   to the user defined requirements
+        # @param document [Hash] The hash representation of the json body
+        # @param config_manager [JSONAPI::ConfigManager] The config_manager option to retreive user
+        #   requirements from
+        # @return [NilClass | String] Nil or the String Error Message
+        def check_user_document_requirements(document, config_manager, opts)
+          return if config_manager.nil?
+          
+          config = get_config(config_manager, opts[:http_method], opts[:path])
+          err = check_for_client_generated_id(document, config.allow_client_ids, opts[:http_method])
+          
+          return if config.default? && config_manager.size.positive?
+          
+          if err.nil?
+            err = check_for_required_document_members(document, config.required_document_members)
+          end
+          # To add more user requirement features, add more methods here
+          
+          JSONAPI::Exceptions::UserDefinedExceptions::InvalidDocument.new(err) unless err.nil?
+        end
+
+        # Performs compliance checks on the headers to see if it complies
+        #   to the user defined requirements
+        # @param headers [Hash | JSONAPI::HeaderCollection] The collection of provided headers. Keys should be upper case strings
+        #   with underscores instead of dashes.
+        # @param config (see #check_user_document_requirements)
+        def check_user_header_requirements(headers, config_manager, opts)
+          return if config_manager.nil? || config_manager.default?
+          config = get_config(config_manager, opts[:http_method], opts[:path])
+
+          err = 
+            check_for_required_headers(headers, config.required_headers)
+          # To add more user requirement features, add more methods here
+
+          JSONAPI::Exceptions::UserDefinedExceptions::InvalidHeader.new(err) unless err.nil?
+        end
+
+        # Performs compliance checks on the query params to see if it complies
+        #   to the user defined requirements
+        # @param rack_req_params [Hash]  The hash of the query parameters given by Rack::Request
+        # @param config (see #check_user_document_requirements)
+        def check_user_query_param_requirements(rack_req_params, config_manager, opts)
+          return if config_manager.nil? || config_manager.default?
+          config = get_config(config_manager, opts[:http_method], opts[:path])
+
+          err = 
+            check_for_required_params(rack_req_params, config.required_query_params)
+          # To add more user requirement features, add more methods here
+
+          JSONAPI::Exceptions::UserDefinedExceptions::InvalidQueryParam.new(err) unless err.nil?
+        end
+
+        private
+
+        # ***************************
+        # * Document Helper Methods *
+        # ***************************
+
+        # Checks to see whether the document conatians all the require members
+        #   See spec file for more examples.
+        #   Ex: 
+        #     { 
+        #       data:
+        #         [
+        #           { 
+        #             type: nil, 
+        #              attributes: { a1: nil, a2: nil }
+        #           }
+        #         ],
+        #       meta: 
+        #         { 
+        #           m1: nil
+        #         }
+        #     }
+        # @param document (see #check_user_document_requirements)
+        # @param req_mems[Hash] The hash representation of the user-defined required json members.
+        def check_for_required_document_members(document, req_mems)
+          if reached_value_to_check?(document, req_mems)
+            return check_values(document, req_mems)
+          end
+          
+          err = check_structure(document, req_mems)
+          return err unless err.nil?
+
+          case req_mems
+          when Hash
+            req_mems.each do |k, v|
+              err = check_for_required_document_members(document[k], v)
+              return err unless err.nil?
+            end
+          when Array
+            document.each do |m|
+              err = check_for_required_document_members(m, req_mems.first)
+              return err unless err.nil?
+            end
+          end
+          nil
+        end       
+
+        # Check if same class or if req_mems nil. If not it indicates the user has specified set
+        #   of required values for a given key. Check whether the current valueis within the set.
+        # @param (see #check_required_document_members)
+        # @return [NilClass | String] An error message if one found.
+        def check_structure(document, req_mems)
+          if both_are_hashes(document, req_mems)
+            doc_keys = document.keys
+            req_keys = req_mems.keys
+            return if doc_keys & req_keys == req_keys
+            ["Document is missing user-defined required keys: #{req_keys - doc_keys}"]
+          else 
+            return if document.instance_of?(req_mems.class) || req_mems.nil?
+            ["User-defined required members hash does not mimic structure of json document: #{document}"]
+          end
+        end
+
+        def both_are_hashes(first, second)
+          first.is_a?(Hash) && second.is_a?(Hash)
+        end
+
+        # @return [TrueClass | FalseClass]
+        def reached_value_to_check?(document, req_mems)
+          (req_mems.is_a?(Proc) || req_mems.nil?) && !document.is_a?(Hash) && !document.is_a?(Array)
+        end
+        
+        # Checks whether a value given is within the permitted values
+        # @param value_given [Any]
+        def check_values(value_given, permitted_values)
+          return if permitted_values.nil? || (permitted_values.is_a?(Proc) && permitted_values.call(value_given))
+          ["The user-defined Proc found at #{permitted_values.source_location}, evaluated the given value, #{value_given}, to be non compliant."]
+        end
+        
+        # Checks if a resource id was included in the primary resource sent in a POST request
+        # @param document (see# #check_required_document_members)
+        # @param allow_client_ids [TrueClass | FalseClass] Does the user allow client generated
+        #   ids
+        # @param http_method [String] Does the document belong to a POST request
+        def check_for_client_generated_id(document, allow_client_ids, http_method)
+          return unless http_method == 'POST' && !allow_client_ids
+          return unless JSONAPI::Utility.all_hash_path?(document, %i[data id])
+          
+          msg = 'Document MUST return 403 Forbidden in response to an unsupported request ' \
+                'to create a resource with a client-generated ID.'
+          [msg, 403]
+        end
+
+        # *************************
+        # * Header Helper Methods *
+        # *************************
+
+        # Checks to makes sure the headers conatin the user defined required headers
+        # @param headers [Hash] The provided headers
+        # @param req_headers [Hash] The required headers
+        def check_for_required_headers(headers, req_headers)
+          return if req_headers.nil?
+
+          req_headers.each do |hdr|
+            h_name = hdr.to_s.upcase.gsub(/-/, '_')
+            unless headers[h_name]
+              return ["Headers missing one of the user-defined required headers: #{h_name}"]
+            end
+          end
+          nil
+        end
+
+        # ******************************
+        # * Query Param Helper Methods *
+        # ******************************
+
+        # Checks to make sure the query params contain the user defined required params
+        #   Rack Request Params Ex:
+        #   {
+        #     'fields' => { 'articles' => 'title,body,author', 'people' => 'name' },
+        #     'include' => 'author,comments-likers,comments.users',
+        #     'josh_ua' => 'demoss,simpson',
+        #     'page' => { 'offset' => '5', 'limit' => '20' },
+        #     'filter' => { 'comments' => '(author/age > 21)', 'users' => '(age < 15)' },
+        #     'sort' => 'age,title'
+        #   }
+        #   Required Params Hash Ex:
+        #   {
+        #     fields: { articles: nil },
+        #     include: nil
+        #     page: nil
+        #   }
+        # @param rack_req_params [Hash] The Rack::Request.params hash
+        # @param required_params [Hash] The user defined required query params
+        def check_for_required_params(rack_req_params, required_params)
+          return if required_params.nil?
+          
+          case required_params
+          when Hash
+            required_params.each do |k, v|
+              return ["Query Params missing one of the user-defined required query params: #{k}"] unless rack_req_params[k.to_s]
+              err = check_for_required_params(rack_req_params[k.to_s], v)
+              return err unless err.nil?
+            end
+          when nil
+            return
+          else
+            return ['The user-defined required query params hash must contain keys with values either hash or nil']
+          end
+          nil
+        end
+
+        def get_config(config_manager, http_method, path)
+          if http_method
+            res_type = JSONAPI::Utility.path_to_res_type(path)
+            config_manager[res_type] || config_manager.global
+          else
+            config_manager.global
+          end
+        end
+      end
+    end
+  end
+end