skooma 0.1.0

data/lib/skooma/objects/path_item/keywords/delete.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Skooma
+  module Objects
+    class PathItem
+      module Keywords
+        class Delete < BaseOperation
+          self.key = "options"
+          self.depends_on = %w[parameters]
+          self.value_schema = :schema
+          self.schema_value_class = Objects::Operation
+        end
+      end
+    end
+  end
+end

data/lib/skooma/objects/path_item/keywords/get.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Skooma
+  module Objects
+    class PathItem
+      module Keywords
+        class Get < BaseOperation
+          self.key = "get"
+          self.depends_on = %w[parameters]
+          self.value_schema = :schema
+          self.schema_value_class = Objects::Operation
+        end
+      end
+    end
+  end
+end

data/lib/skooma/objects/path_item/keywords/head.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Skooma
+  module Objects
+    class PathItem
+      module Keywords
+        class Head < BaseOperation
+          self.key = "head"
+          self.depends_on = %w[parameters]
+          self.value_schema = :schema
+          self.schema_value_class = Objects::Operation
+        end
+      end
+    end
+  end
+end

data/lib/skooma/objects/path_item/keywords/options.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Skooma
+  module Objects
+    class PathItem
+      module Keywords
+        class Options < BaseOperation
+          self.key = "options"
+          self.depends_on = %w[parameters]
+          self.value_schema = :schema
+          self.schema_value_class = Objects::Operation
+        end
+      end
+    end
+  end
+end

data/lib/skooma/objects/path_item/keywords/parameters.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Skooma
+  module Objects
+    class PathItem
+      module Keywords
+        class Parameters < JSONSkooma::Keywords::Base
+          self.key = "parameters"
+          self.value_schema = :array_of_schemas
+          self.schema_value_class = Objects::Parameter
+
+          def evaluate(instance, result)
+            result.skip_assertion
+          end
+        end
+      end
+    end
+  end
+end

data/lib/skooma/objects/path_item/keywords/patch.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Skooma
+  module Objects
+    class PathItem
+      module Keywords
+        class Patch < BaseOperation
+          self.key = "patch"
+          self.depends_on = %w[parameters]
+          self.value_schema = :schema
+          self.schema_value_class = Objects::Operation
+        end
+      end
+    end
+  end
+end

data/lib/skooma/objects/path_item/keywords/post.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Skooma
+  module Objects
+    class PathItem
+      module Keywords
+        class Post < BaseOperation
+          self.key = "post"
+          self.depends_on = %w[parameters]
+          self.value_schema = :schema
+          self.schema_value_class = Objects::Operation
+        end
+      end
+    end
+  end
+end

data/lib/skooma/objects/path_item/keywords/put.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Skooma
+  module Objects
+    class PathItem
+      module Keywords
+        class Put < BaseOperation
+          self.key = "put"
+          self.depends_on = %w[parameters]
+          self.value_schema = :schema
+          self.schema_value_class = Objects::Operation
+        end
+      end
+    end
+  end
+end

data/lib/skooma/objects/path_item/keywords/trace.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Skooma
+  module Objects
+    class PathItem
+      module Keywords
+        class Trace < BaseOperation
+          self.key = "trace"
+          self.depends_on = %w[parameters]
+          self.value_schema = :schema
+          self.schema_value_class = Objects::Operation
+        end
+      end
+    end
+  end
+end

data/lib/skooma/objects/path_item.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Skooma
+  module Objects
+    # Describes the operations available on a single path.
+    # https://spec.openapis.org/oas/v3.1.0#path-item-object
+    class PathItem < RefBase
+      def kw_classes
+        [
+          Base::Keywords::Summary,
+          Base::Keywords::Description,
+
+          Keywords::Get,
+          Keywords::Put,
+          Keywords::Post,
+          Keywords::Delete,
+          Keywords::Options,
+          Keywords::Head,
+          Keywords::Patch,
+          Keywords::Trace,
+
+          Base::Keywords::Servers,
+          Keywords::Parameters
+        ]
+      end
+    end
+  end
+end

data/lib/skooma/objects/ref_base.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Skooma
+  module Objects
+    # A simple object to allow referencing other components in the OpenAPI document.
+    # https://spec.openapis.org/oas/v3.1.0#referenceObject
+    class RefBase < Base
+      # This object cannot be extended with additional properties
+      # and any properties added SHALL be ignored.
+      def resolve_keywords(value)
+        return super unless value.key?("$ref")
+
+        resolve_ref_keywords(value)
+      end
+
+      def ref_kw_classes
+        [
+          JSONSkooma::Keywords::Core::Ref,
+          Base::Keywords::Summary,
+          Base::Keywords::Description
+        ]
+      end
+
+      def resolve_ref_keywords(value)
+        ref_kw_classes.each do |kw_class|
+          next unless value.key?(kw_class.key)
+
+          add_keyword(kw_class.new(self, value[kw_class.key]))
+        end
+      end
+    end
+  end
+end

data/lib/skooma/objects/request_body/keywords/required.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Skooma
+  module Objects
+    class RequestBody
+      module Keywords
+        class Required < JSONSkooma::Keywords::Base
+          self.key = "required"
+
+          def evaluate(instance, result)
+            if json.value && instance["body"].value.nil?
+              result.failure("Body is required")
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/skooma/objects/request_body.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Skooma
+  module Objects
+    # Describes a single request body.
+    # https://spec.openapis.org/oas/v3.1.0#request-body-object
+    class RequestBody < RefBase
+      def kw_classes
+        [
+          Base::Keywords::Description,
+          Skooma::Objects::Response::Keywords::Content,
+          Keywords::Required
+        ]
+      end
+    end
+  end
+end

data/lib/skooma/objects/response/keywords/content.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module Skooma
+  module Objects
+    class Response
+      module Keywords
+        class Content < JSONSkooma::Keywords::Base
+          self.key = "content"
+          self.value_schema = :object_of_schemas
+          self.schema_value_class = Objects::MediaType
+
+          def evaluate(instance, result)
+            return result.discard unless instance["body"].value
+
+            media_type = instance["headers"]&.[]("Content-Type")&.split(";")&.first&.strip&.downcase
+            media_type_object, matched_media_type = find_media_type(media_type)
+
+            return result.failure("Media type #{media_type} not found") unless media_type_object
+
+            result.annotate(matched_media_type)
+            result.call(instance, matched_media_type) do |media_type_result|
+              media_type_object.evaluate(instance["body"], media_type_result)
+
+              result.failure("Invalid content") unless media_type_result.passed?
+            end
+          end
+
+          private
+
+          # The key is a media type or media type range and the value describes it.
+          # For requests that match multiple keys, only the most specific key is applicable.
+          # e.g. text/plain overrides text/*
+          def find_media_type(media_type)
+            matched_media_type =
+              if json.key?(media_type)
+                media_type
+              elsif media_type &&
+                  (key = "#{media_type.split("/").first}/*") &&
+                  json.key?(key)
+                key
+              elsif json.key?("*/*")
+                "*/*"
+              end
+
+            [json[matched_media_type], matched_media_type]
+          end
+        end
+      end
+    end
+  end
+end

data/lib/skooma/objects/response/keywords/headers.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module Skooma
+  module Objects
+    class Response
+      module Keywords
+        class Headers < JSONSkooma::Keywords::Base
+          self.key = "headers"
+          self.value_schema = :object_of_schemas
+          self.schema_value_class = Objects::Header
+
+          def evaluate(instance, result)
+            errors = []
+            json.each do |key, schema|
+              next if ignored_key?(key)
+
+              result.call(instance["headers"], key) do |subresult|
+                schema.evaluate(instance["headers"][key], subresult)
+
+                errors << key unless subresult.passed?
+              end
+            end
+            return if errors.empty?
+
+            result.failure("The following headers are invalid: #{errors}")
+          end
+
+          private
+
+          def ignored_key?(key)
+            %w[accept content-type authorization].include?(key.downcase)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/skooma/objects/response/keywords/links.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Skooma
+  module Objects
+    class Response
+      module Keywords
+        class Links < JSONSkooma::Keywords::BaseAnnotation
+          self.key = "links"
+        end
+      end
+    end
+  end
+end

data/lib/skooma/objects/response.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Skooma
+  module Objects
+    # Describes a single response from an API Operation.
+    # https://spec.openapis.org/oas/v3.1.0#responseObject
+    class Response < RefBase
+      def kw_classes
+        [
+          Base::Keywords::Description,
+          Keywords::Headers,
+          Keywords::Content,
+          Keywords::Links
+        ]
+      end
+    end
+  end
+end

data/lib/skooma/output_format.rb

@@ -0,0 +1,35 @@
+module Skooma
+  module OutputFormat
+    class << self
+      def call(result, **_options)
+        return {"valid" => true} if result.valid?
+
+        node_data(result, true)
+      end
+
+      private
+
+      def node_data(node, first = false)
+        data = {
+          "instanceLocation" => node.instance.path.to_s,
+          "relativeKeywordLocation" => node.relative_path.to_s,
+          "keywordLocation" => node.path.to_s
+        }
+
+        child_data = node.children.filter_map do |_, child|
+          node_data(child) unless child.valid?
+        end
+
+        if first || child_data.length > 1
+          data["errors"] = child_data
+        elsif child_data.length == 1
+          data = child_data[0]
+        elsif node.error
+          data["error"] = node.error
+        end
+
+        data
+      end
+    end
+  end
+end

data/lib/skooma/rspec.rb

@@ -0,0 +1,166 @@
+# frozen_string_literal: true
+
+require "yaml"
+
+module Skooma
+  # RSpec matchers for OpenAPI schema validation
+  # @example
+  #   require "skooma/rspec"
+  #   # ...
+  #   RSpec.configure do |config|
+  #     # ...
+  #     config.include Skooma::RSpec[Rails.root.join("docs", "openapi.yml")], type: :request
+  #   end
+  class RSpec < Module
+    class << self
+      alias_method :[], :new
+    end
+
+    module Mapper
+      PLAIN_HEADERS = %w[CONTENT_LENGTH CONTENT_TYPE].freeze
+      REGEXP_HTTP = /^HTTP_/.freeze
+
+      def mapped_response(response: true, request: true)
+        result = {
+          "method" => env["REQUEST_METHOD"].downcase,
+          "path" => env["PATH_INFO"]
+        }
+
+        if response
+          result["response"] = {
+            "status" => response_data[0],
+            "headers" => response_data[1],
+            "body" => response_data[2]
+          }
+        end
+
+        if request
+          result["request"] = {
+            "query" => env["rack.request.query_string"] || env["QUERY_STRING"],
+            "headers" => env.select { |k, _| k.start_with?("HTTP_") || PLAIN_HEADERS.include?(k) }.transform_keys { |k| k.sub(REGEXP_HTTP, "").split("_").map(&:capitalize).join("-") },
+            "body" => env["RAW_POST_DATA"]
+          }
+        end
+
+        result
+      end
+
+      def env
+        request.env
+      end
+
+      def response_data
+        [response.status, response.headers.to_h, response.body]
+      end
+    end
+
+    def initialize(openapi_path, base_uri: "https://skoomarb.dev/")
+      super()
+
+      pathname = Pathname.new(openapi_path)
+
+      registry = Skooma.create_registry
+      registry.add_source(
+        base_uri,
+        JSONSkooma::Sources::Local.new(pathname.dirname.to_s)
+      )
+      schema = registry.schema(URI.parse("#{base_uri}#{pathname.basename}"), schema_class: Skooma::Objects::OpenAPI)
+
+      include Mapper
+
+      define_method :skooma_openapi_schema do
+        schema
+      end
+    end
+  end
+
+  ::RSpec::Matchers.define(:conform_schema) do |expected_status|
+    match do
+      next false unless response.status == expected_status
+
+      @result = skooma_openapi_schema.evaluate(mapped_response)
+      @result.valid?
+    end
+
+    description do
+      "conform schema with #{expected_status} response code"
+    end
+
+    failure_message do
+      <<~MSG
+        ENV:
+        #{PP.pp(mapped_response, +"")}
+        
+        Validation Result:
+        #{@result ? PP.pp(@result.output(:skooma), +"") : "Expected #{expected_status} status code"}
+      MSG
+    end
+  end
+
+  ::RSpec::Matchers.define(:conform_request_schema) do
+    match do
+      @result = skooma_openapi_schema.evaluate(mapped_response(response: false))
+      @result.valid?
+    end
+
+    description do
+      "conform request schema"
+    end
+
+    failure_message do
+      <<~MSG
+        ENV:
+        #{PP.pp(mapped_response, +"")}
+        
+        Validation Result:
+        #{@result ? PP.pp(@result.output(:skooma), +"") : "Expected #{expected_status} status code"}
+      MSG
+    end
+  end
+
+  ::RSpec::Matchers.define(:conform_response_schema) do |expected_status|
+    match do
+      next false unless response.status == expected_status
+
+      @result = skooma_openapi_schema.evaluate(mapped_response(request: false))
+      @result.valid?
+    end
+
+    description do
+      "conform response schema with #{expected_status} response code"
+    end
+
+    failure_message do
+      <<~MSG
+        ENV:
+        #{PP.pp(mapped_response, +"")}
+        
+        Validation Result:
+        #{@result ? PP.pp(@result.output(:skooma), +"") : "Expected #{expected_status} status code"}
+      MSG
+    end
+  end
+
+  ::RSpec::Matchers.define(:be_valid_document) do
+    match do |actual|
+      @actual = actual
+      next false unless comparable?
+
+      @result = actual.validate
+      @result.valid?
+    end
+
+    description { "be a valid OpenAPI document" }
+
+    failure_message do
+      next "expected value to be an OpenAPI object" unless comparable?
+
+      pretty_output = PP.pp(@result.output(:detailed), +"")
+      "must valid against OpenAPI specification:\n#{pretty_output}"
+    end
+
+    def comparable?
+      actual.is_a?(Skooma::Objects::OpenAPI)
+    end
+  end
+end

data/lib/skooma/validators/double.rb

@@ -0,0 +1,13 @@
+module Skooma
+  module Validators
+    class Double < JSONSkooma::Validators::Base
+      self.instance_types = "number"
+
+      def call(instance)
+        return if instance.value.is_a?(::Float)
+
+        raise JSONSkooma::Validators::FormatError, "must be a valid double"
+      end
+    end
+  end
+end

data/lib/skooma/validators/float.rb

@@ -0,0 +1,13 @@
+module Skooma
+  module Validators
+    class Float < JSONSkooma::Validators::Base
+      self.instance_types = "number"
+
+      def call(instance)
+        return if instance.value.is_a?(::Float)
+
+        raise JSONSkooma::Validators::FormatError, "must be a valid float"
+      end
+    end
+  end
+end

data/lib/skooma/validators/int_32.rb

@@ -0,0 +1,15 @@
+module Skooma
+  module Validators
+    class Int32 < JSONSkooma::Validators::Base
+      def self.assert?(instance)
+        instance.type == "number" && instance == instance.to_i
+      end
+
+      def call(instance)
+        return if instance.value.bit_length <= 32
+
+        raise JSONSkooma::Validators::FormatError, "must be a valid int32"
+      end
+    end
+  end
+end

data/lib/skooma/validators/int_64.rb

@@ -0,0 +1,15 @@
+module Skooma
+  module Validators
+    class Int64 < JSONSkooma::Validators::Base
+      def self.assert?(instance)
+        instance.type == "number" && instance == instance.to_i
+      end
+
+      def call(instance)
+        return if instance.value.bit_length <= 64
+
+        raise JSONSkooma::Validators::FormatError, "must be a valid int64"
+      end
+    end
+  end
+end

data/lib/skooma/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Skooma
+  VERSION = "0.1.0"
+end

data/lib/skooma.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+require "json_skooma"
+require "zeitwerk"
+
+require_relative "skooma/inflector"
+
+loader = Zeitwerk::Loader.for_gem
+loader.inflector = Skooma::Inflector.new
+loader.setup
+
+module Skooma
+  DATA_DIR = File.join(__dir__, "..", "data")
+  REGISTRY_NAME = "skooma_registry"
+
+  class Error < StandardError; end
+
+  JSONSkooma.register_dialect("oas-3.1", Dialects::OAS31)
+  JSONSkooma::Formatters.register :skooma, OutputFormat
+
+  class << self
+    def create_registry
+      JSONSkooma.create_registry("2020-12", "oas-3.1", name: REGISTRY_NAME, assert_formats: true)
+    end
+  end
+end