scorpio 0.4.2 → 0.5.0

data/lib/scorpio/openapi/document.rb

@@ -1,7 +1,7 @@
 module Scorpio
   module OpenAPI
     # A document that defines or describes an API.
-    # An OpenAPI definition uses and conforms to the OpenAPI Specification.
+    # An OpenAPI description document uses and conforms to the OpenAPI Specification.
     #
     # Scorpio::OpenAPI::Document is a module common to V2 and V3 documents.
     module Document
@@ -12,24 +12,18 @@ module Scorpio
         # @param instance [#to_hash] the document to represent as a Scorpio OpenAPI Document
         # @return [Scorpio::OpenAPI::V2::Document, Scorpio::OpenAPI::V3::Document]
         def from_instance(instance)
-          if instance.is_a?(Hash)
-            instance = JSI::JSON::Node.new_doc(instance)
-          end
-          if instance.is_a?(JSI::JSON::Node)
-            if instance['swagger'] =~ /\A2(\.|\z)/
-              instance = Scorpio::OpenAPI::V2::Document.new(instance)
-            elsif instance['openapi'] =~ /\A3(\.|\z)/
-              instance = Scorpio::OpenAPI::V3::Document.new(instance)
-            else
-              raise(ArgumentError, "instance does not look like a recognized openapi document")
-            end
-          end
           if instance.is_a?(Scorpio::OpenAPI::Document)
             instance
           elsif instance.is_a?(JSI::Base)
             raise(TypeError, "instance is unexpected JSI type: #{instance.class.inspect}")
           elsif instance.respond_to?(:to_hash)
-            from_instance(instance.to_hash)
+            if instance['swagger'] =~ /\A2(\.|\z)/
+              instance = Scorpio::OpenAPI::V2::Document.new_jsi(instance)
+            elsif instance['openapi'] =~ /\A3(\.|\z)/
+              instance = Scorpio::OpenAPI::V3::Document.new_jsi(instance)
+            else
+              raise(ArgumentError, "instance does not look like a recognized openapi document")
+            end
           else
             raise(TypeError, "instance does not look like a hash (json object)")
           end
@@ -89,7 +83,7 @@ module Scorpio
       # A document that defines or describes an API conforming to the OpenAPI Specification v3.
       #
       # https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#oasObject
-      class Document
+      module Document
         module Configurables
           def scheme
             nil
@@ -132,7 +126,7 @@ module Scorpio
       # A document that defines or describes an API conforming to the OpenAPI Specification v2 (aka Swagger).
       #
       # The root document is known as the Swagger Object.
-      class Document
+      module Document
         module Configurables
           attr_writer :scheme
           def scheme

data/lib/scorpio/openapi/operation.rb

@@ -55,18 +55,14 @@ module Scorpio
 
       # @return [Scorpio::OpenAPI::Document] the document whence this operation came
       def openapi_document
-        parents.detect { |p| p.is_a?(Scorpio::OpenAPI::Document) }
+        parent_jsis.detect { |p| p.is_a?(Scorpio::OpenAPI::Document) }
       end
 
       def path_template_str
         return @path_template_str if instance_variable_defined?(:@path_template_str)
-        @path_template_str = begin
-          parent_is_pathitem = parent.is_a?(Scorpio::OpenAPI::V2::PathItem) || parent.is_a?(Scorpio::OpenAPI::V3::PathItem)
-          parent_parent_is_paths = parent.parent.is_a?(Scorpio::OpenAPI::V2::Paths) || parent.parent.is_a?(Scorpio::OpenAPI::V3::Paths)
-          if parent_is_pathitem && parent_parent_is_paths
-            parent.instance.path.last
-          end
-        end
+        raise(Bug) unless parent_jsi.is_a?(Scorpio::OpenAPI::V2::PathItem) || parent_jsi.is_a?(Scorpio::OpenAPI::V3::PathItem)
+        raise(Bug) unless parent_jsi.parent_jsi.is_a?(Scorpio::OpenAPI::V2::Paths) || parent_jsi.parent_jsi.is_a?(Scorpio::OpenAPI::V3::Paths)
+        @path_template_str = parent_jsi.jsi_ptr.reference_tokens.last
       end
 
       # @return [Addressable::Template] the path as an Addressable::Template
@@ -91,12 +87,8 @@ module Scorpio
       #   for this operation from the parent PathItem
       def http_method
         return @http_method if instance_variable_defined?(:@http_method)
-        @http_method = begin
-          parent_is_pathitem = parent.is_a?(Scorpio::OpenAPI::V2::PathItem) || parent.is_a?(Scorpio::OpenAPI::V3::PathItem)
-          if parent_is_pathitem
-            instance.path.last
-          end
-        end
+        raise(Bug) unless parent_jsi.is_a?(Scorpio::OpenAPI::V2::PathItem) || parent_jsi.is_a?(Scorpio::OpenAPI::V3::PathItem)
+        @http_method = jsi_ptr.reference_tokens.last
       end
 
       # @return [String] a short identifier for this operation appropriate for an error message
@@ -182,7 +174,7 @@ module Scorpio
       # Describes a single API operation on a path.
       #
       # https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#operationObject
-      class Operation
+      module Operation
         module Configurables
           def scheme
             # not applicable; for OpenAPI v3, scheme is specified by servers.
@@ -246,7 +238,7 @@ module Scorpio
     end
     module V2
       raise(Bug, 'const_defined? Scorpio::OpenAPI::V2::Operation') unless const_defined?(:Operation)
-      class Operation
+      module Operation
         module Configurables
           attr_writer :scheme
           def scheme
@@ -272,7 +264,8 @@ module Scorpio
         end
         include Configurables
 
-        # there should only be one body parameter; this returns it
+        # @return [#to_hash] the body parameter
+        # @raise [Scorpio::OpenAPI::SemanticError] if there's more than one body param
         def body_parameter
           body_parameters = (parameters || []).select { |parameter| parameter['in'] == 'body' }
           if body_parameters.size == 0

data/lib/scorpio/openapi/operations_scope.rb

@@ -3,7 +3,7 @@ module Scorpio
     # OperationsScope acts as an Enumerable of the Operations for an openapi_document,
     # and offers subscripting by operationId.
     class OperationsScope
-      include JSI::Memoize
+      include JSI::Util::Memoize
 
       # @param openapi_document [Scorpio::OpenAPI::Document]
       def initialize(openapi_document)
@@ -25,9 +25,14 @@ module Scorpio
 
       # @param operationId
       # @return [Scorpio::OpenAPI::Operation] the operation with the given operationId
+      # @raise [::KeyError] if the given operationId does not exist
       def [](operationId)
-        memoize(:[], operationId) do |operationId_|
-          detect { |operation| operation.operationId == operationId_ }
+        jsi_memoize(:[], operationId) do |operationId_|
+          detect { |operation| operation.operationId == operationId_ }.tap do |op|
+            unless op
+              raise(::KeyError, "operationId not found: #{operationId_.inspect}")
+            end
+          end
         end
       end
     end

data/lib/scorpio/openapi/reference.rb

@@ -0,0 +1,19 @@
+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')
+      #
+      # see JSI::Base#initialize documentation at https://www.rubydoc.info/gems/jsi/JSI/Base
+      def [](token, *a, &b)
+        if respond_to?(:to_hash) && !key?(token)
+          deref do |deref_jsi|
+            return deref_jsi[token]
+          end
+        end
+        return super
+      end
+    end
+  end
+end

data/lib/scorpio/openapi/v3/server.rb

@@ -6,7 +6,7 @@ module Scorpio
       # An object representing a Server.
       #
       # https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#serverObject
-      class Server
+      module Server
         # expands this server's #url 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.

data/lib/scorpio/request.rb

@@ -1,6 +1,8 @@
 module Scorpio
   class Request
     SUPPORTED_REQUEST_MEDIA_TYPES = ['application/json', 'application/x-www-form-urlencoded']
+    FALLBACK_CONTENT_TYPE = 'application/x-www-form-urlencoded'
+
     def self.best_media_type(media_types)
       if media_types.size == 1
         media_types.first
@@ -50,10 +52,9 @@ module Scorpio
       def body
         return @body if instance_variable_defined?(:@body)
         if instance_variable_defined?(:@body_object)
-          # TODO handle media types like `application/schema-instance+json`
-          if media_type == 'application/json'
+          if content_type && content_type.json?
             JSON.pretty_generate(JSI::Typelike.as_json(body_object))
-          elsif media_type == "application/x-www-form-urlencoded"
+          elsif content_type && content_type.form_urlencoded?
             URI.encode_www_form(body_object)
 
           # NOTE: the supported media types above should correspond to Request::SUPPORTED_REQUEST_MEDIA_TYPES
@@ -62,7 +63,7 @@ module Scorpio
             if body_object.respond_to?(:to_str)
               body_object
             else
-              raise(NotImplementedError, "Scorpio does not know how to generate the request body with media_type = #{media_type.respond_to?(:to_str) ? media_type : media_type.inspect} for operation: #{operation.human_id}. Scorpio supports media types: #{SUPPORTED_REQUEST_MEDIA_TYPES.join(', ')}. body_object was: #{body_object.pretty_inspect.chomp}")
+              raise(NotImplementedError, "Scorpio does not know how to generate the request body with content_type = #{content_type.respond_to?(:to_str) ? content_type : content_type.inspect} for operation: #{operation.human_id}. Scorpio supports media types: #{SUPPORTED_REQUEST_MEDIA_TYPES.join(', ')}. body_object was: #{body_object.pretty_inspect.chomp}")
             end
           end
         else
@@ -81,7 +82,7 @@ module Scorpio
       attr_writer :media_type
       def media_type
         return @media_type if instance_variable_defined?(:@media_type)
-        content_type_header ? content_type_attrs.media_type : operation.request_media_type
+        content_type_header ? content_type_header.media_type : operation.request_media_type
       end
 
       attr_writer :user_agent
@@ -190,23 +191,18 @@ module Scorpio
       Addressable::URI.parse(File.join(base_url, path))
     end
 
-    # @return [::Ur::ContentTypeAttrs] content type attributes for this request's Content-Type
-    def content_type_attrs
-      Ur::ContentTypeAttrs.new(content_type)
-    end
-
-    # @return [String] the value of the request Content-Type header
+    # @return [::Ur::ContentType] the value of the request Content-Type header
     def content_type_header
       headers.each do |k, v|
-        return v if k =~ /\Acontent[-_]type\z/i
+        return ::Ur::ContentType.new(v) if k =~ /\Acontent[-_]type\z/i
       end
       nil
     end
 
-    # @return [String] Content-Type for this request, taken from request headers if
+    # @return [::Ur::ContentType] Content-Type for this request, taken from request headers if
     #   present, or the request media_type.
     def content_type
-      content_type_header || media_type
+      content_type_header || (media_type ? ::Ur::ContentType.new(media_type) : nil)
     end
 
     # @return [::JSI::Schema]
@@ -214,11 +210,6 @@ module Scorpio
       operation.request_schema(media_type: media_type)
     end
 
-    # @return [Class subclassing JSI::Base]
-    def request_schema_class(media_type: self.media_type)
-      JSI.class_for_schema(request_schema(media_type: media_type))
-    end
-
     # builds a Faraday connection with this Request's faraday_builder and faraday_adapter.
     # passes a given proc yield_ur to middleware to yield an Ur for requests made with the connection.
     #
@@ -228,8 +219,9 @@ module Scorpio
       Faraday.new do |faraday_connection|
         faraday_builder.call(faraday_connection)
         if yield_ur
-          ::Ur::Faraday # autoload trigger
-          faraday_connection.response(:yield_ur, ur_class: Scorpio::Ur, logger: self.logger, &yield_ur)
+          -> { ::Ur::Faraday }.() # autoload trigger
+
+          faraday_connection.response(:yield_ur, schemas: Set[Scorpio::Ur.schema], logger: self.logger, &yield_ur)
         end
         faraday_connection.adapter(*faraday_adapter)
       end
@@ -328,8 +320,14 @@ module Scorpio
       if user_agent
         headers['User-Agent'] = user_agent
       end
-      if media_type && !content_type_header
-        headers['Content-Type'] = media_type
+      if !content_type_header
+        if media_type
+          headers['Content-Type'] = media_type
+        else
+          # I'd rather not have a default content-type, but if none is set then the HTTP adapter sets this to 
+          # application/x-www-form-urlencoded and issues a warning about it.
+          headers['Content-Type'] = FALLBACK_CONTENT_TYPE
+        end
       end
       if self.headers
         headers.update(self.headers)

data/lib/scorpio/resource_base.rb

@@ -6,18 +6,20 @@ module Scorpio
 
   class ResourceBase
     class << self
-      # a hash of accessor names (Symbol) to default getter methods (UnboundMethod), used to determine
-      # what accessors have been overridden from their defaults.
+      # ResourceBase.inheritable_accessor_defaults is a hash of accessor names (Symbol) mapped 
+      # to default getter methods (UnboundMethod), used to determine what accessors have been
+      # overridden from their defaults.
       (-> (x) { define_method(:inheritable_accessor_defaults) { x } }).({})
-      def define_inheritable_accessor(accessor, options = {})
-        if options[:default_getter]
-          # the value before the field is set (overwritten) is the result of the default_getter proc
-          define_singleton_method(accessor, &options[:default_getter])
-        else
-          # the value before the field is set (overwritten) is the default_value (which is nil if not specified)
-          default_value = options[:default_value]
-          define_singleton_method(accessor) { default_value }
-        end
+
+      # @param accessor [String, Symbol] the name of the accessor
+      # @param default_getter [#to_proc] a proc to provide a default value when no value
+      #   has been explicitly set
+      # @param default_value [Object] a default value to return when no value has been
+      #   explicitly set. do not pass both :default_getter and :default_value.
+      # @param on_set [#to_proc] callback proc, invoked when a value is assigned
+      def define_inheritable_accessor(accessor, default_value: nil, default_getter: -> { default_value }, on_set: nil)
+        # the value before the field is set (overwritten) is the result of the default_getter proc
+        define_singleton_method(accessor, &default_getter)
         inheritable_accessor_defaults[accessor] = self.singleton_class.instance_method(accessor)
         # field setter method. redefines the getter, replacing the method with one that returns the
         # setter's argument (that being inherited to the scope of the define_method(accessor) block
@@ -33,8 +35,8 @@ module Scorpio
             # getter method
             define_method(accessor) { value_ }
             # invoke on_set callback defined on the class
-            if options[:on_set]
-              klass.instance_exec(&options[:on_set])
+            if on_set
+              klass.instance_exec(&on_set)
             end
           end
         end
@@ -257,7 +259,7 @@ module Scorpio
       end
 
       def call_operation(operation, call_params: nil, model_attributes: nil)
-        call_params = JSI.stringify_symbol_keys(call_params) if call_params.is_a?(Hash)
+        call_params = JSI.stringify_symbol_keys(call_params) if call_params.respond_to?(:to_hash)
         model_attributes = JSI.stringify_symbol_keys(model_attributes || {})
 
         request = Scorpio::Request.new(operation)
@@ -312,7 +314,7 @@ module Scorpio
           # TODO deal with model_attributes / call_params better in nested whatever
           if call_params.nil?
             request.body_object = request_body_for_schema(model_attributes, operation.request_schema)
-          elsif call_params.is_a?(Hash)
+          elsif call_params.respond_to?(:to_hash)
             body = request_body_for_schema(model_attributes.merge(call_params), operation.request_schema)
             request.body_object = body.merge(call_params) # TODO
           else
@@ -323,7 +325,7 @@ module Scorpio
             if METHODS_WITH_BODIES.any? { |m| m.to_s == operation.http_method.downcase.to_s }
               request.body_object = other_params
             else
-              if other_params.is_a?(Hash)
+              if other_params.respond_to?(:to_hash)
                 # TODO pay more attention to 'parameters' api method attribute
                 request.query_params = other_params
               else
@@ -349,17 +351,15 @@ module Scorpio
         if object.is_a?(Scorpio::ResourceBase)
           # TODO request_schema_fail unless schema is for given model type 
           request_body_for_schema(object.attributes, schema)
-        elsif object.is_a?(JSI::Base)
-          request_body_for_schema(object.instance, schema)
-        elsif object.is_a?(JSI::JSON::Node)
-          request_body_for_schema(object.content, schema)
+        elsif object.is_a?(JSI::PathedNode)
+          request_body_for_schema(object.node_content, schema)
         else
-          if object.is_a?(Hash)
+          if object.respond_to?(:to_hash)
             object.map do |key, value|
               if schema
                 if schema['type'] == 'object'
                   # TODO code dup with response_object_to_instances
-                  if schema['properties'].respond_to?(:to_hash) && schema['properties'][key]
+                  if schema['properties'].respond_to?(:to_hash) && schema['properties'].key?(key)
                     subschema = schema['properties'][key]
                     include_pair = true
                   else
@@ -397,7 +397,7 @@ module Scorpio
                 {}
               end
             end.inject({}, &:update)
-          elsif object.is_a?(Array) || object.is_a?(Set)
+          elsif object.respond_to?(:to_ary) || object.is_a?(Set)
             object.map do |el|
               if schema
                 if schema['type'] == 'array'
@@ -423,7 +423,14 @@ module Scorpio
 
       def response_object_to_instances(object, initialize_options = {})
         if object.is_a?(JSI::Base)
-          model = models_by_schema[object.schema]
+          models = object.jsi_schemas.map { |schema| models_by_schema[schema] }
+          if models.size == 0
+            model = nil
+          elsif models.size == 1
+            model = models.first
+          else
+            raise(Scorpio::OpenAPI::Error, "multiple models indicated by response JSI. models: #{models.inspect}; jsi: #{jsi.pretty_inspect.chomp}")
+          end
         end
 
         if object.respond_to?(:to_hash)
@@ -431,8 +438,7 @@ module Scorpio
             mod = object.map do |key, value|
               {key => response_object_to_instances(value, initialize_options)}
             end.inject({}, &:update)
-            mod = mod.instance if mod.is_a?(JSI::Base)
-            mod = mod.content if mod.is_a?(JSI::JSON::Node)
+            mod = mod.node_content if mod.is_a?(JSI::PathedNode)
             mod
           end
           if model
@@ -520,9 +526,9 @@ module Scorpio
       end
     end
 
-    def fingerprint
+    def jsi_fingerprint
       {class: self.class, attributes: JSI::Typelike.as_json(@attributes)}
     end
-    include JSI::FingerprintHash
+    include JSI::Util::FingerprintHash
   end
 end

data/lib/scorpio/response.rb

@@ -1,5 +1,7 @@
 module Scorpio
-  class Response < ::Ur::Response
+  Response = Scorpio::Ur.properties['response']
+
+  module Response
     # @return [::JSI::Schema] the schema for this response according to its OpenAPI doc
     def response_schema
       ur.scorpio_request.operation.response_schema(status: status, media_type: media_type)
@@ -9,8 +11,7 @@ module Scorpio
     #   if supported (only application/json is currently supported) instantiated according to
     #   #response_schema
     def body_object
-      # TODO handle media types like `application/schema-instance+json` or vendor things like github's
-      if media_type == 'application/json'
+      if json?
         if body.empty?
           # an empty body isn't valid json, of course, but we'll just return nil for it.
           body_object = nil
@@ -23,11 +24,11 @@ module Scorpio
         end
 
         if response_schema && (body_object.respond_to?(:to_hash) || body_object.respond_to?(:to_ary))
-          body_object = JSI.class_for_schema(response_schema).new(JSI::JSON::Node.new_doc(body_object))
+          body_object = response_schema.new_jsi(body_object)
         end
 
         body_object
-      elsif media_type == 'text/plain'
+      elsif content_type && content_type.type_text? && content_type.subtype?('plain')
         body
       else
         # we will return the body if we do not have a supported parsing. for now.