scorpio 0.6.4 → 0.7.0

data/lib/scorpio/openapi/operation.rb

@@ -25,6 +25,18 @@ module Scorpio
           openapi_document.user_agent
         end
 
+        attr_writer(:accept)
+        def accept
+          return @accept if instance_variable_defined?(:@accept)
+          openapi_document.accept
+        end
+
+        attr_writer(:authorization)
+        def authorization
+          return @authorization if instance_variable_defined?(:@authorization)
+          openapi_document.authorization
+        end
+
         attr_writer :faraday_builder
         def faraday_builder
           return @faraday_builder if instance_variable_defined?(:@faraday_builder)
@@ -44,37 +56,32 @@ module Scorpio
         end
       end
       include Configurables
+      include(Document::Descendent)
 
       # openapi v3?
       # @return [Boolean]
       def v3?
-        is_a?(V3::Operation)
+        is_a?(OpenAPI::Operation::V3Methods)
       end
 
       # openapi v2?
       # @return [Boolean]
       def v2?
-        is_a?(V2::Operation)
-      end
-
-      # the document whence this operation came
-      # @return [Scorpio::OpenAPI::Document]
-      def openapi_document
-        jsi_parent_nodes.detect { |p| p.is_a?(Scorpio::OpenAPI::Document) }
+        is_a?(OpenAPI::V2::Operation)
       end
 
       # @return [String]
       def path_template_str
         return @path_template_str if instance_variable_defined?(:@path_template_str)
-        raise(Bug) unless jsi_parent_node.is_a?(Scorpio::OpenAPI::V2::PathItem) || jsi_parent_node.is_a?(Scorpio::OpenAPI::V3::PathItem)
-        raise(Bug) unless jsi_parent_node.jsi_parent_node.is_a?(Scorpio::OpenAPI::V2::Paths) || jsi_parent_node.jsi_parent_node.is_a?(Scorpio::OpenAPI::V3::Paths)
-        @path_template_str = jsi_parent_node.jsi_ptr.tokens.last
+        path_item = jsi_ancestor_nodes.detect { |n| n.is_a?(Scorpio::OpenAPI::PathItem) }
+        @path_template_str = path_item && path_item.jsi_ptr.tokens.last
       end
 
       # the path as an Addressable::Template
       # @return [Addressable::Template]
       def path_template
         return @path_template if instance_variable_defined?(:@path_template)
+        return(@path_template = nil) if !path_template_str
         @path_template = Addressable::Template.new(path_template_str)
       end
 
@@ -83,7 +90,7 @@ module Scorpio
       # @return [Addressable::Template]
       def uri_template(base_url: self.base_url)
         unless base_url
-          raise(ArgumentError, "no base_url has been specified for operation #{self}")
+          raise(ArgumentError, -"no base_url has been specified for operation #{self}")
         end
         # we do not use Addressable::URI#join as the paths should just be concatenated, not resolved.
         # we use File.join just to deal with consecutive slashes.
@@ -95,38 +102,88 @@ module Scorpio
       # @return [String]
       def http_method
         return @http_method if instance_variable_defined?(:@http_method)
-        raise(Bug) unless jsi_parent_node.is_a?(Scorpio::OpenAPI::V2::PathItem) || jsi_parent_node.is_a?(Scorpio::OpenAPI::V3::PathItem)
+        return(@http_method = nil) unless jsi_parent_node.is_a?(Scorpio::OpenAPI::PathItem)
         @http_method = jsi_ptr.tokens.last
       end
 
+      def get?
+        'get'.casecmp?(http_method)
+      end
+
+      def put?
+        'put'.casecmp?(http_method)
+      end
+
+      def post?
+        'post'.casecmp?(http_method)
+      end
+
+      def delete?
+        'delete'.casecmp?(http_method)
+      end
+
+      def options?
+        'options'.casecmp?(http_method)
+      end
+
+      def head?
+        'head'.casecmp?(http_method)
+      end
+
+      def patch?
+        'patch'.casecmp?(http_method)
+      end
+
+      def trace?
+        'trace'.casecmp?(http_method)
+      end
+
+      # @param tag_name [String]
+      # @return [Boolean]
+      def tagged?(tag_name)
+        tags.respond_to?(:to_ary) && tags.include?(tag_name)
+      end
+
       # a short identifier for this operation appropriate for an error message
       # @return [String]
       def human_id
-        operationId || "path: #{path_template_str}, method: #{http_method}"
+        operationId || -"path: #{path_template_str}, method: #{http_method}"
       end
 
       # @param status [String, Integer]
-      # @return [Scorpio::OpenAPI::V3::Response, Scorpio::OpenAPI::V2::Response]
+      # @return [OpenAPI::Response, nil]
       def oa_response(status: )
+        return nil if !responses
         status = status.to_s if status.is_a?(Numeric)
-        if responses
-          _, oa_response = responses.detect { |k, v| k.to_s == status }
-          oa_response ||= responses['default']
+        responses.each do |k, v|
+          return v if k.to_s == status
         end
-        oa_response
+        responses[-"#{status[0]}XX"] || responses['default']
       end
 
-      # the parameters specified for this operation, plus any others scorpio considers to be parameters.
+      # operation parameters + path item parameters
       #
-      # this method is not intended to be API-stable at the moment.
+      # @api private
+      # @return [#to_ary<#to_hash>]
+      def inherited_parameters
+        parameters = []
+        parameters.concat(self.parameters.to_ary) if self.parameters
+        path_item = jsi_ancestor_nodes.detect { |n| n.is_a?(OpenAPI::PathItem) }
+        parameters.concat((path_item && path_item.parameters || []).select do |pip|
+          parameters.none? { |p| p['in'] == pip['in'] && p['name'] == pip['name'] }
+        end)
+        parameters.freeze
+      end
+
+      # the parameters specified for this operation, plus any others scorpio considers to be parameters.
       #
       # @api private
-      # @return [#to_ary<#to_h>]
+      # @return [#to_ary<#to_hash>]
       def inferred_parameters
-        parameters = self.parameters ? self.parameters.to_a.dup : []
+        parameters = inherited_parameters.dup
         path_template.variables.each do |var|
           unless parameters.any? { |p| p['in'] == 'path' && p['name'] == var }
-            # we could instantiate this as a V2::Parameter or a V3::Parameter
+            # we could instantiate this as a V2::Parameter or a V3_0::Parameter
             # or a ParameterWithContentInPath or whatever. but I can't be bothered.
             parameters << {
               'name' => var,
@@ -136,85 +193,47 @@ module Scorpio
             }
           end
         end
-        parameters
-      end
-
-      # a module with accessor methods for unambiguously named parameters of this operation.
-      # @return [Module]
-      def request_accessor_module
-        return @request_accessor_module if instance_variable_defined?(:@request_accessor_module)
-        @request_accessor_module = begin
-          params_by_name = inferred_parameters.group_by { |p| p['name'] }
-          Module.new do
-            instance_method_modules = [Request, Request::Configurables]
-            instance_method_names = instance_method_modules.map do |mod|
-              (mod.instance_methods + mod.private_instance_methods).map(&:to_s)
-            end.inject(Set.new, &:merge)
-            params_by_name.each do |name, params|
-              next if instance_method_names.include?(name)
-              if params.size == 1
-                param = params.first
-                define_method("#{name}=") { |value| set_param_from(param['in'], param['name'], value) }
-                define_method(name) { get_param_from(param['in'], param['name']) }
-              end
-            end
-          end
-        end
+        parameters.freeze
       end
 
       # instantiates a {Scorpio::Request} for this operation.
-      # parameters are all passed to {Scorpio::Request#initialize}.
+      # configuration is passed to {Scorpio::Request#initialize}.
       # @return [Scorpio::Request]
-      def build_request(configuration = {}, &b)
-        @request_class ||= Scorpio::Request.request_class_by_operation(self)
-        @request_class.new(configuration, &b)
+      def build_request(**configuration, &b)
+        Scorpio::Request.new(self, **configuration, &b)
       end
 
       # runs a {Scorpio::Request} for this operation, returning a {Scorpio::Ur}.
-      # parameters are all passed to {Scorpio::Request#initialize}.
+      # configuration is passed to {Scorpio::Request#initialize}.
       # @return [Scorpio::Ur] response ur
-      def run_ur(configuration = {}, &b)
-        build_request(configuration, &b).run_ur
+      def run_ur(**configuration, &b)
+        build_request(**configuration, &b).run_ur
       end
 
       # runs a {Scorpio::Request} for this operation - see {Scorpio::Request#run}.
-      # parameters are all passed to {Scorpio::Request#initialize}.
+      # configuration is passed to {Scorpio::Request#initialize}.
       # @return response body object
-      def run(configuration = {}, &b)
-        build_request(configuration, &b).run
+      def run(mutable: false, **configuration, &b)
+        build_request(**configuration, &b).run(mutable: mutable)
       end
 
       # Runs this operation with the given request config, and yields the resulting {Scorpio::Ur}.
-      # If the response contains a `Link` header with a `next` link (and that link's URL
-      # corresponds to this operation), this operation is run again to that link's URL, that
-      # request's Ur yielded, and a `next` link in that response is followed.
+      # If the response contains a `Link` header with a `next` link, this operation is run again to
+      # that link's URL, that request's Ur yielded, and a `next` link in that response is followed.
       # This repeats until a response does not contain a `Link` header with a `next` link.
       #
       # @param configuration (see Scorpio::Request#initialize)
       # @yield [Scorpio::Ur]
       # @return [Enumerator, nil]
-      def each_link_page(configuration = {}, &block)
-        init_request = build_request(configuration)
+      def each_link_page(**configuration, &block)
+        init_request = build_request(**configuration)
         next_page = proc do |last_page_ur|
           nextlinks = last_page_ur.response.links.select { |link| link.rel?('next') }
           if nextlinks.size == 0
             # no next link; we are at the end
             nil
           elsif nextlinks.size == 1
-            nextlink = nextlinks.first
-            # we do not use Addressable::URI#join as the paths should just be concatenated, not resolved.
-            # we use File.join just to deal with consecutive slashes.
-            template = Addressable::Template.new(File.join(init_request.base_url, path_template_str))
-            target_uri = nextlink.absolute_target_uri
-            path_params = template.extract(target_uri.merge(query: nil))
-            unless path_params
-              raise("the URI of the link to the next page did not match the URI of this operation")
-            end
-            query_params = target_uri.query_values
-            run_ur(
-              path_params: path_params,
-              query_params: query_params,
-            )
+            run_ur(**configuration, url: nextlinks.first.absolute_target_uri)
           else
             # TODO better error class / context / message
             raise("response included multiple links with rel=next")
@@ -226,17 +245,12 @@ module Scorpio
       private
 
       def jsi_object_group_text
-        [*super, http_method, path_template_str].freeze
+        [*super, http_method, path_template_str].compact.freeze
       end
     end
 
-    module V3
-      raise(Bug, 'const_defined? Scorpio::OpenAPI::V3::Operation') unless const_defined?(:Operation)
-
-      # Describes a single API operation on a path.
-      #
-      # https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#operationObject
-      module Operation
+    module Operation
+      module V3Methods
         module Configurables
           def scheme
             # not applicable; for OpenAPI v3, scheme is specified by servers.
@@ -266,6 +280,7 @@ module Scorpio
           end
         end
         include Configurables
+        include(OpenAPI::Operation)
 
         # @return [JSI::Schema]
         def request_schema(media_type: self.request_media_type)
@@ -291,13 +306,15 @@ module Scorpio
           end
         end
 
-        # @return [JSI::Schema]
+        # @return [JSI::Schema, nil]
         def response_schema(status: , media_type: )
-          oa_response = self.oa_response(status: status)
-          oa_media_types = oa_response ? oa_response['content'] : nil # Scorpio::OpenAPI::V3::MediaTypes
-          oa_media_type = oa_media_types ? oa_media_types[media_type] : nil # Scorpio::OpenAPI::V3::MediaType
-          oa_schema = oa_media_type ? oa_media_type['schema'] : nil # Scorpio::OpenAPI::V3::Schema
-          oa_schema ? JSI::Schema.ensure_schema(oa_schema) : nil
+          oa_response = self.oa_response(status: status) || return
+          oa_media_types = oa_response['content'] || return # Scorpio::OpenAPI::V3_*::MediaTypes
+          oa_media_type = oa_media_types[media_type] # Scorpio::OpenAPI::V3_*::MediaType
+          oa_media_type ||= oa_media_types[-"#{::Ur::ContentType.new(media_type).type}/*"]
+          oa_media_type ||= oa_media_types['*/*'] || return
+          oa_schema = oa_media_type['schema'] || return # JSI::Schema, Scorpio::OpenAPI::V3_*::Schema
+          JSI::Schema.ensure_schema(oa_schema)
         end
 
         # @return [JSI::SchemaSet]
@@ -318,9 +335,9 @@ module Scorpio
         end
       end
     end
-    module V2
-      raise(Bug, 'const_defined? Scorpio::OpenAPI::V2::Operation') unless const_defined?(:Operation)
-      module Operation
+
+    module Operation
+      module V2Methods
         module Configurables
           attr_writer :scheme
           def scheme
@@ -345,19 +362,20 @@ module Scorpio
           end
         end
         include Configurables
+        include(OpenAPI::Operation)
 
         # the body parameter
         # @return [#to_hash]
         # @raise [Scorpio::OpenAPI::SemanticError] if there's more than one body param
         def body_parameter
-          body_parameters = (parameters || []).select { |parameter| parameter['in'] == 'body' }
+          body_parameters = inherited_parameters.select { |parameter| parameter['in'] == 'body' }
           if body_parameters.size == 0
             nil
           elsif body_parameters.size == 1
             body_parameters.first
           else
             # TODO blame
-            raise(OpenAPI::SemanticError, "multiple body parameters on operation #{operation.pretty_inspect.chomp}")
+            raise(OpenAPI::SemanticError, -"multiple body parameters on operation #{operation.pretty_inspect.chomp}")
           end
         end
 

data/lib/scorpio/openapi/operations_scope.rb

@@ -2,40 +2,56 @@
 
 module Scorpio
   module OpenAPI
-    # OperationsScope acts as an Enumerable of the Operations for an openapi_document,
+    # OperationsScope is an Enumerable for a collection of Operations,
     # and offers subscripting by operationId.
     class OperationsScope
-      # @param openapi_document [Scorpio::OpenAPI::Document]
-      def initialize(openapi_document)
-        @openapi_document = openapi_document
+      # @param enum [Enumerable]
+      def initialize(enum)
+        @enum = enum
         @operations_by_id = Hash.new do |h, operationId|
-          op = detect { |operation| operation.operationId == operationId }
-          unless op
-            raise(::KeyError, "operationId not found: #{operationId.inspect}")
-          end
-          h[operationId] = op
+          h[operationId] = enum.detect { |operation| operation.operationId == operationId }
         end
       end
       attr_reader :openapi_document
 
       # @yield [Scorpio::OpenAPI::Operation]
-      def each
-        openapi_document.paths.each do |path, path_item|
-          path_item.each do |http_method, operation|
-            if operation.is_a?(Scorpio::OpenAPI::Operation)
-              yield operation
-            end
-          end
-        end
+      def each(&block)
+        @enum.each(&block)
       end
+
       include Enumerable
 
+      # @return [Scorpio::OpenAPI::Operation, nil]
+      def by_id(operationId)
+        @operations_by_id[operationId]
+      end
+
       # finds an operation with the given `operationId`
       # @param operationId [String] the operationId of the operation to find
       # @return [Scorpio::OpenAPI::Operation]
       # @raise [::KeyError] if the given operationId does not exist
-      def [](operationId)
-        @operations_by_id[operationId]
+      def by_id!(operationId)
+        @operations_by_id[operationId] || raise(::KeyError, -"operationId not found: #{operationId.inspect}")
+      end
+
+      alias_method(:[], :by_id!)
+
+      # @return [OperationsScope]
+      def select(&block)
+        OperationsScope.new(@enum.select(&block))
+      end
+
+      # @return [OperationsScope]
+      def reject(&block)
+        OperationsScope.new(@enum.reject(&block))
+      end
+
+      # Operations with the indicated tag
+      # @param tag [String, OpenAPI::Tag]
+      # @return [OperationsScope]
+      def tagged(tag)
+        tag_name = tag.is_a?(OpenAPI::Tag) ? tag.name : tag
+        select { |op| op.tagged?(tag_name) }
       end
     end
   end

data/lib/scorpio/openapi/reference.rb

@@ -3,41 +3,106 @@
 module Scorpio
   module OpenAPI
     module Reference
-      # overrides JSI::Base#[] to implicitly dereference this Reference, except when
-      # the given token is present in this Reference's instance (this should usually
-      # only apply to the token '$ref')
+      # @private
+      module IncludeRecursive
+        def included(mod)
+          super
+          return if mod.is_a?(Class)
+          document_subschemas_include_derefable(mod)
+          mod.send(:extend, IncludeRecursive)
+        end
+
+        # - when a schema module includes OpenAPI::Reference
+        # - then we go to the schema's root node (which describes an OpenAPI Document)
+        # - and for each descendent schema, describing a part of an OAD
+        # - if that schema _could_ describe a reference, because its in-place applicators
+        #   include the schema of the schema module including Reference
+        #   (e.g. it has a oneOf with a $ref: '#/definitions/Reference')
+        # - then its schema module includes Derefable
+        def document_subschemas_include_derefable(mod)
+          return unless mod.is_a?(JSI::SchemaModule)
+
+          mod.schema.jsi_root_node.jsi_each_descendent_schema do |schema|
+            if to_enum(:schema_all_inplace_applicator_schemas, schema).include?(mod.schema)
+              schema.jsi_schema_module.include(Derefable)
+            end
+          end
+        end
+
+        # yield all of the schema's in-place applicator schemas, recursively, following $ref.
+        # TODO find a better home for this code (it is not particular to OpenAPI::Reference)
+        def schema_all_inplace_applicator_schemas(schema, &block)
+          yield schema
+          if schema.keyword?('$ref')
+            schema_all_inplace_applicator_schemas(schema.schema_ref.resolve, &block)
+          end
+          ia_elements = schema.dialect.elements.select { |element| element.invokes?(:inplace_applicate) }
+          cxt = JSI::Schema::Cxt::Block.new(
+            schema: schema,
+            abort: false,
+            block: proc { |ptr| schema_all_inplace_applicator_schemas(schema.subschema(ptr), &block) },
+          )
+          ia_elements.each do |element|
+            # getting subschemas yielded from action :subschema on elements that invoke :inplace_applicate
+            # is a kind of hacky way to get _all_ inplace applicators.
+            # getting applicator schemas normally comes from invoking :inplace_applicate, but that
+            # requires an instance and yields just the applicators that apply to that instance, not all.
+            #
+            # this does not work when the schemas an element yields from :subschema do not match its in-place
+            # applicator schemas. the only element that does that is for $ref which is handled above.
+            element.actions[:subschema].each do |action|
+              cxt.instance_exec(&action)
+            end
+          end
+        end
+      end
+
+      extend(IncludeRecursive)
+
+      # Derefable is included on the schema module of any schema that describes a reference or has an
+      # in-place applicator that describes a reference. You can call #deref regardless whether an object
+      # is of an expected type, or a reference to one, or a reference to a reference to one.
+      module Derefable
+        # resolves references ({Reference#resolve}) recursively.
+        def deref
+          return self unless is_a?(Reference) && has_ref?
+          resolved = resolve
+          return resolved if !resolved.is_a?(Reference)
+          resolved.deref
+        end
+      end
+
+      # overrides JSI::Base#[] to implicitly resolve this Reference, except when
+      # the given token is present in this Reference's instance.
+      # the token '$ref' will always come from this reference, not its resolution.
+      # tokens 'summary' and 'description' may also be in some references.
       def [](token, **kw)
         if respond_to?(:to_hash) && !key?(token)
-          deref do |deref_jsi|
-            return(deref_jsi[token, **kw])
+          resolve do |resolved|
+            return(resolved[token, **kw])
           end
         end
         return super
       end
 
-      # yields or returns the target of this reference
-      # @yield [JSI::Base] if a block is given
-      # @return [JSI::Base]
-      def deref
-        return unless respond_to?(:to_hash) && self['$ref'].respond_to?(:to_str)
-
-        ref_uri = Addressable::URI.parse(self['$ref'])
-        ref_uri_nofrag = ref_uri.merge(fragment: nil)
+      # @return [Boolean]
+      def has_ref?
+        jsi_child_token_present?('$ref')
+      end
 
-        if !ref_uri_nofrag.empty? || ref_uri.fragment.nil?
-          raise(NotImplementedError,
-            "Scorpio currently only supports fragment URIs as OpenAPI references. cannot find reference by uri: #{self['$ref']}"
-          )
-        end
+      # yields or returns the target of this reference. returns nil and does not yield if `$ref` is not present.
+      # @yield [JSI::Base] if a block is given
+      # @return [JSI::Base, nil]
+      def resolve
+        return unless has_ref?
 
-        ptr = JSI::Ptr.from_fragment(ref_uri.fragment)
-        deref_jsi = ptr.evaluate(jsi_root_node)
+        ref = @memos.fetch(:oa_ref) { @memos[:oa_ref] = JSI::Ref.new(jsi_node_content['$ref'], referrer: self) }
 
-        # TODO type check deref_jsi
+        # TODO type check resolved
 
-        yield deref_jsi if block_given?
+        yield ref.resolve if block_given?
 
-        deref_jsi
+        ref.resolve
       end
     end
   end

data/lib/scorpio/openapi/schema_elements/type_nullable.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Scorpio
+  module OpenAPI::SchemaElements
+    instance_types = {
+      'boolean' => proc { instance == true || instance == false },
+      'object' => proc { instance.respond_to?(:to_hash) },
+      'array' => proc { instance.respond_to?(:to_ary) },
+      'string' => proc { instance.respond_to?(:to_str) },
+      'number' => proc { instance.is_a?(Numeric) },
+      'integer' => proc { internal_integer?(instance) },
+    }.freeze
+
+    TYPE_NULLABLE = JSI::Schema::Element.new(keywords: ['type', 'nullable']) do |element|
+      element.add_action(:validate) do
+        next if !keyword?('type')
+        if instance.nil?
+          validate(
+            schema_content['nullable'] == true,
+            'validation.keyword.type.not_nullable',
+            "instance is null without `nullable` = true",
+            keyword: 'nullable',
+          )
+        else
+          if !instance_types.key?(schema_content['type'])
+            next # schema error; skip validation
+          end
+          validate(
+            instance_exec(&instance_types[schema_content['type']]),
+            'validation.keyword.type.not_match',
+            "instance type does not match `type` value",
+            keyword: 'type',
+          )
+        end
+      end
+    end
+  end
+end

data/lib/scorpio/openapi/schema_elements.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Scorpio
+  module OpenAPI::SchemaElements
+    autoload(:TYPE_NULLABLE, 'scorpio/openapi/schema_elements/type_nullable')
+  end
+end

data/lib/scorpio/openapi/server.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Scorpio
+  module OpenAPI
+      # An object representing a Server.
+      module Server
+        include(Document::Descendent)
+
+        # expands this server's #url template using the given_server_variables. any variables
+        # that are in the url but not in the given server variables are filled in
+        # using the default value for the variable.
+        #
+        # @param given_server_variables [Hash<String, String>]
+        # @return [Addressable::URI] the expanded url
+        def expanded_url(given_server_variables)
+          given_server_variables = JSI::Util.stringify_symbol_keys(given_server_variables)
+          if variables
+            server_variables = {}
+            (given_server_variables.keys | variables.keys).each do |key|
+              if given_server_variables.key?(key)
+                server_variables[key] = given_server_variables[key]
+              elsif variables[key].key?('default')
+                server_variables[key] = variables[key].default
+              end
+            end
+          else
+            server_variables = given_server_variables
+          end
+          template = Addressable::Template.new(url)
+          template.expand(server_variables).freeze
+        end
+      end
+  end
+end