scorpio 0.5.0 → 0.6.0

data/lib/scorpio/resource_base.rb

@@ -1,6 +1,8 @@
+# frozen_string_literal: true
+
 module Scorpio
   # see also Faraday::Env::MethodsWithBodies
-  METHODS_WITH_BODIES = %w(post put patch options)
+  METHODS_WITH_BODIES = %w(post put patch options).map(&:freeze).freeze
   class RequestSchemaFailure < Error
   end
 
@@ -20,7 +22,7 @@ module Scorpio
       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)
+        inheritable_accessor_defaults[accessor] = 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
         define_singleton_method(:"#{accessor}=") do |value|
@@ -42,25 +44,18 @@ module Scorpio
         end
       end
     end
-    define_inheritable_accessor(:represented_schemas, default_value: [], on_set: proc do
-      unless represented_schemas.respond_to?(:to_ary)
-        raise(TypeError, "represented_schemas must be an array. received: #{represented_schemas.pretty_inspect.chomp}")
-      end
-      if represented_schemas.all? { |s| s.is_a?(JSI::Schema) }
+    define_inheritable_accessor(:represented_schemas, default_value: Set[].freeze, on_set: proc do
+      if represented_schemas.is_a?(JSI::SchemaSet)
         represented_schemas.each do |schema|
-          openapi_document_class.models_by_schema = openapi_document_class.models_by_schema.merge(schema => self)
+          new_mbs = openapi_document_class.models_by_schema.merge(schema => self).freeze
+          openapi_document_class.models_by_schema = new_mbs
         end
         update_dynamic_methods
       else
-        self.represented_schemas = self.represented_schemas.map do |schema|
-          unless schema.is_a?(JSI::Schema)
-            schema = JSI::Schema.new(schema)
-          end
-          schema
-        end
+        self.represented_schemas = JSI::SchemaSet.ensure_schema_set(represented_schemas)
       end
     end)
-    define_inheritable_accessor(:models_by_schema, default_value: {})
+    define_inheritable_accessor(:models_by_schema, default_value: {}.freeze)
     # a model overriding this MUST include the openapi document's basePath if defined, e.g.
     # class MyModel
     #   self.base_url = File.join('https://example.com/', openapi_document.basePath)
@@ -69,7 +64,7 @@ module Scorpio
       openapi_document.base_url(server: server, server_variables: server_variables)
     })
 
-    define_inheritable_accessor(:server_variables, default_value: {}, on_set: -> {
+    define_inheritable_accessor(:server_variables, default_value: {}.freeze, on_set: -> {
       if openapi_document && openapi_document.v2?
         raise(ArgumentError, "server variables are not supported for OpenAPI V2")
       end
@@ -113,9 +108,9 @@ module Scorpio
         define_singleton_method(:openapi_document_class) { openapi_document_class }
         define_singleton_method(:openapi_document=) do |_|
           if self == openapi_document_class
-            raise(ArgumentError, "openapi_document may only be set once on #{self.inspect}")
+            raise(ArgumentError, "openapi_document may only be set once on #{inspect}")
           else
-            raise(ArgumentError, "openapi_document may not be overridden on subclass #{self.inspect} after it was set on #{openapi_document_class.inspect}")
+            raise(ArgumentError, "openapi_document may not be overridden on subclass #{inspect} after it was set on #{openapi_document_class.inspect}")
           end
         end
         # TODO blame validate openapi_document
@@ -151,7 +146,7 @@ module Scorpio
       end
 
       def all_schema_properties
-        represented_schemas.map(&:described_object_property_names).inject(Set.new, &:|)
+        represented_schemas.map(&:described_object_property_names).inject(Set.new, &:merge)
       end
 
       def update_instance_accessors
@@ -170,13 +165,13 @@ module Scorpio
       end
 
       def operation_for_resource_class?(operation)
-        return false unless tag_name
+        return true if tag_name && operation.tags.respond_to?(:to_ary) && operation.tags.include?(tag_name)
 
-        return true if operation.tags.respond_to?(:to_ary) && operation.tags.include?(tag_name)
-
-        if (operation.request_schemas || []).any? { |s| represented_schemas.include?(s) }
-          return true
-        end
+        request_response_schemas = operation.request_schemas | operation.response_schemas
+        # TODO/FIX nil instance is wrong. works for $ref and allOf, not for others.
+        # use all inplace applicators, not conditional on instance
+        all_request_response_schemas = request_response_schemas.each_inplace_applicator_schema(nil)
+        return true if all_request_response_schemas.any? { |s| represented_schemas.include?(s) }
 
         return false
       end
@@ -184,61 +179,69 @@ module Scorpio
       def operation_for_resource_instance?(operation)
         return false unless operation_for_resource_class?(operation)
 
-        # define an instance method if the request schema is for this model 
-        request_resource_is_self = operation.request_schemas.any? do |request_schema|
-          represented_schemas.include?(request_schema)
-        end
-
-        # also define an instance method depending on certain attributes the request description 
-        # might have in common with the model's schema attributes
-        request_attributes = []
-        # if the path has attributes in common with model schema attributes, we'll define on 
-        # instance method
-        request_attributes |= operation.path_template.variables
-        # TODO if the method request schema has attributes in common with the model schema attributes,
-        # should we define an instance method?
-        #request_attributes |= request_schema && request_schema['type'] == 'object' && request_schema['properties'] ?
-        #  request_schema['properties'].keys : []
-        # TODO if the method parameters have attributes in common with the model schema attributes,
-        # should we define an instance method?
-        #request_attributes |= method_desc['parameters'] ? method_desc['parameters'].keys : []
-
-        schema_attributes = represented_schemas.map(&:described_object_property_names).inject(Set.new, &:|)
-
-        return request_resource_is_self || (request_attributes & schema_attributes.to_a).any?
-      end
-
-      def method_names_by_operation
-        @method_names_by_operation ||= Hash.new do |h, operation|
-          h[operation] = begin
-            raise(ArgumentError, operation.pretty_inspect) unless operation.is_a?(Scorpio::OpenAPI::Operation)
-
-            # if Pet is the Scorpio resource class
-            # and Pet.tag_name is "pet"
-            # and operation's operationId is "pet.add"
-            # then the operation's method name on Pet will be "add".
-            # if the operationId is just "addPet"
-            # then the operation's method name on Pet will be "addPet".
-            tag_name_match = tag_name &&
-              operation.tags.respond_to?(:to_ary) && # TODO maybe operation.tags.valid?
-              operation.tags.include?(tag_name) &&
-              operation.operationId &&
-              operation.operationId.match(/\A#{Regexp.escape(tag_name)}\.(\w+)\z/)
-
-            if tag_name_match
-              method_name = tag_name_match[1]
-            else
-              method_name = operation.operationId
+        # define an instance method if the operation's request schemas include any of our represented_schemas
+        #
+        # TODO/FIX nil instance is wrong. works for $ref and allOf, not for others.
+        # use all inplace applicators, not conditional on instance
+        all_request_schemas = operation.request_schemas.each_inplace_applicator_schema(nil)
+        return true if all_request_schemas.any? { |s| represented_schemas.include?(s) }
+
+        # the below only apply if the operation has this resource's tag
+        return false unless tag_name && operation.tags.respond_to?(:to_ary) && operation.tags.include?(tag_name)
+
+        # define an instance method if path or query params can be filled in from
+        # property names described by represented_schemas
+        schema_attributes = represented_schemas.map(&:described_object_property_names).inject(Set.new, &:merge)
+        operation.inferred_parameters.each do |param|
+          if param['in'] == 'path' || param['in'] == 'query'
+            if schema_attributes.include?(param['name'])
+              return true
             end
           end
         end
+
+        return false
+      end
+
+      # @private
+      # @param name [String]
+      # @return [Scorpio::OpenAPI::Operation, nil]
+      def operation_for_api_method_name(name)
+        openapi_document.operations.detect do |op|
+          operation_for_resource_class?(op) && api_method_name_by_operation(op) == name
+        end
+      end
+
+      # @private
+      # @param name [Scorpio::OpenAPI::Operation]
+      # @return [String, nil]
+      def api_method_name_by_operation(operation)
+        raise(ArgumentError, operation.pretty_inspect) unless operation.is_a?(Scorpio::OpenAPI::Operation)
+
+        # if Pet is the Scorpio resource class
+        # and Pet.tag_name is "pet"
+        # and operation's operationId is "pet.add" or "pet/add" or "pet:add"
+        # then the operation's method name on Pet will be "add".
+        # if the operationId is just "addPet"
+        # then the operation's method name on Pet will be "addPet".
+        tag_name_match = tag_name &&
+          operation.tags.respond_to?(:to_ary) && # TODO maybe operation.tags.valid?
+          operation.tags.include?(tag_name) &&
+          operation.operationId &&
+          operation.operationId.match(/\A#{Regexp.escape(tag_name)}[\.\/\:](\w+)\z/)
+
+        if tag_name_match
+          tag_name_match[1]
+        else
+          operation.operationId
+        end
       end
 
       def update_class_and_instance_api_methods
         openapi_document.paths.each do |path, path_item|
           path_item.each do |http_method, operation|
             next unless operation.is_a?(Scorpio::OpenAPI::Operation)
-            method_name = method_names_by_operation[operation]
+            method_name = api_method_name_by_operation(operation)
             if method_name
               # class method
               if operation_for_resource_class?(operation) && !respond_to?(method_name)
@@ -259,8 +262,8 @@ module Scorpio
       end
 
       def call_operation(operation, call_params: nil, model_attributes: nil)
-        call_params = JSI.stringify_symbol_keys(call_params) if call_params.respond_to?(:to_hash)
-        model_attributes = JSI.stringify_symbol_keys(model_attributes || {})
+        call_params = JSI::Util.stringify_symbol_keys(call_params) if call_params.respond_to?(:to_hash)
+        model_attributes = JSI::Util.stringify_symbol_keys(model_attributes || {})
 
         request = Scorpio::Request.new(operation)
 
@@ -276,7 +279,7 @@ module Scorpio
           #    Scorpio::ResourceBase.instance_method(:server_variables)
           #    => #<UnboundMethod: #<Class:Scorpio::ResourceBase>#server_variables>
           # even though they are really the same method (the #owner for both is Scorpio::ResourceBase)
-          inheritable_accessor_defaults[accessor] != self.singleton_class.instance_method(accessor).owner.instance_method(accessor)
+          inheritable_accessor_defaults[accessor] != singleton_class.instance_method(accessor).owner.instance_method(accessor)
         end
 
         # pretty ugly... may find a better way to do this.
@@ -311,11 +314,30 @@ module Scorpio
         end
 
         if operation.request_schema
+          request_body_for_schema = -> (o) do
+            if o.is_a?(JSI::Base)
+              # TODO check indicated schemas
+              if o.jsi_schemas.include?(operation.request_schema)
+                jsi = o
+              else
+                # TODO maybe better way than reinstantiating another jsi as request_schema
+                jsi = operation.request_schema.new_jsi(o.jsi_node_content)
+              end
+            else
+              jsi = operation.request_schema.new_jsi(o)
+            end
+            jsi.jsi_select_children_leaf_first do |node|
+              # we want to specifically reject only nodes described (only) by a false schema.
+              # note that for OpenAPI schemas, false is only a valid schema as a value
+              # of `additionalProperties`
+              node.jsi_schemas.empty? || !node.jsi_schemas.all? { |s| s.schema_content == false }
+            end
+          end
           # 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)
+            request.body_object = request_body_for_schema.(model_attributes)
           elsif call_params.respond_to?(:to_hash)
-            body = request_body_for_schema(model_attributes.merge(call_params), operation.request_schema)
+            body = request_body_for_schema.(model_attributes)
             request.body_object = body.merge(call_params) # TODO
           else
             request.body_object = call_params
@@ -347,140 +369,109 @@ module Scorpio
         response_object_to_instances(ur.response.body_object, initialize_options)
       end
 
-      def request_body_for_schema(object, schema)
-        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::PathedNode)
-          request_body_for_schema(object.node_content, schema)
-        else
-          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?(key)
-                    subschema = schema['properties'][key]
-                    include_pair = true
-                  else
-                    if schema['patternProperties'].respond_to?(:to_hash)
-                      _, pattern_schema = schema['patternProperties'].detect do |pattern, _|
-                        key =~ Regexp.new(pattern) # TODO map pattern to ruby syntax
-                      end
-                    end
-                    if pattern_schema
-                      subschema = pattern_schema
-                      include_pair = true
-                    else
-                      if schema['additionalProperties'] == false
-                        include_pair = false
-                      elsif [nil, true].include?(schema['additionalProperties'])
-                        include_pair = true
-                        subschema = nil
-                      else
-                        include_pair = true
-                        subschema = schema['additionalProperties']
-                      end
-                    end
-                  end
-                elsif schema['type']
-                  request_schema_fail(object, schema)
-                else
-                  # TODO not sure
-                  include_pair = true
-                  subschema = nil
-                end
-              end
-              if include_pair
-                {key => request_body_for_schema(value, subschema)}
-              else
-                {}
-              end
-            end.inject({}, &:update)
-          elsif object.respond_to?(:to_ary) || object.is_a?(Set)
-            object.map do |el|
-              if schema
-                if schema['type'] == 'array'
-                  # TODO index based subschema or whatever else works for array
-                  subschema = schema['items']
-                elsif schema['type']
-                  request_schema_fail(object, schema)
-                end
-              end
-              request_body_for_schema(el, subschema)
-            end
-          else
-            # TODO maybe raise on anything not serializable 
-            # TODO check conformance to schema, request_schema_fail if not
-            object
-          end
-        end
-      end
-
-      def request_schema_fail(object, schema)
-        # TODO blame
-      end
-
       def response_object_to_instances(object, initialize_options = {})
         if object.is_a?(JSI::Base)
-          models = object.jsi_schemas.map { |schema| models_by_schema[schema] }
+          models = object.jsi_schemas.map { |schema| models_by_schema[schema] }.compact
           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}")
+            raise(Scorpio::OpenAPI::Error, "multiple models indicated by response JSI. models: #{models.inspect}; object: #{object.pretty_inspect.chomp}")
           end
-        end
 
-        if object.respond_to?(:to_hash)
-          out = JSI::Typelike.modified_copy(object) do |_object|
-            mod = object.map do |key, value|
-              {key => response_object_to_instances(value, initialize_options)}
-            end.inject({}, &:update)
-            mod = mod.node_content if mod.is_a?(JSI::PathedNode)
-            mod
-          end
-          if model
-            model.new(out, initialize_options)
+          if model && object.respond_to?(:to_hash)
+            model.new(object, initialize_options)
           else
-            out
-          end
-        elsif object.respond_to?(:to_ary)
-          JSI::Typelike.modified_copy(object) do
-            object.map do |element|
-              response_object_to_instances(element, initialize_options)
-            end
+            Container.new_container(object, openapi_document_class, initialize_options)
           end
         else
           object
         end
       end
     end
+  end
+
+  class ResourceBase
+    module Containment
+      def [](key)
+        sub = contained_object[key]
+        if sub.is_a?(JSI::Base)
+          # TODO avoid reinstantiating the container only to throw it away if it matches the memo
+          sub_container = @openapi_document_class.response_object_to_instances(sub, options)
+
+          if @subscript_memos.key?(key) && @subscript_memos[key].class == sub_container.class
+            @subscript_memos[key]
+          else
+            @subscript_memos[key] = sub_container
+          end
+        else
+          sub
+        end
+      end
+
+      def []=(key, value)
+        @subscript_memos.delete(key)
+        if value.is_a?(Containment)
+          contained_object[key] = value.contained_object
+        else
+          contained_object[key] = value
+        end
+      end
+
+      def as_json(*opt)
+        JSI::Typelike.as_json(contained_object, *opt)
+      end
+
+      def inspect
+        "\#<#{self.class.inspect} #{contained_object.inspect}>"
+      end
+
+      def pretty_print(q)
+        q.instance_exec(self) do |obj|
+          text "\#<#{obj.class.inspect}"
+          group_sub {
+            nest(2) {
+              breakable ' '
+              pp obj.contained_object
+            }
+          }
+          breakable ''
+          text '>'
+        end
+      end
+
+      include JSI::Util::FingerprintHash
+
+      def jsi_fingerprint
+        {class: self.class, contained_object: as_json}
+      end
+    end
+  end
+
+  class ResourceBase
+    include Containment
 
     def initialize(attributes = {}, options = {})
-      @attributes = JSI.stringify_symbol_keys(attributes)
-      @options = JSI.stringify_symbol_keys(options)
+      @attributes = JSI::Util.stringify_symbol_keys(attributes)
+      @options = JSI::Util.stringify_symbol_keys(options)
       @persisted = !!@options['persisted']
+
+      @openapi_document_class = self.class.openapi_document_class
+      @subscript_memos = {}
     end
 
     attr_reader :attributes
     attr_reader :options
 
+    alias_method :contained_object, :attributes
+
     def persisted?
       @persisted
     end
 
-    def [](key)
-      @attributes[key]
-    end
-
-    def []=(key, value)
-      @attributes[key] = value
-    end
-
     def call_api_method(method_name, call_params: nil)
-      operation = self.class.method_names_by_operation.invert[method_name] || raise(ArgumentError)
+      operation = self.class.operation_for_api_method_name(method_name) || raise(ArgumentError)
       call_operation(operation, call_params: call_params)
     end
 
@@ -504,31 +495,73 @@ module Scorpio
 
       response
     end
+  end
 
-    def as_json(*opt)
-      JSI::Typelike.as_json(@attributes, *opt)
-    end
+  class ResourceBase
+    class Container
+      @container_classes = Hash.new do |h, modules|
+        container_class = Class.new(Container)
+        modules.each do |mod|
+          container_class.include(mod)
+        end
+        h[modules] = container_class
+      end
 
-    def inspect
-      "\#<#{self.class.inspect} #{attributes.inspect}>"
-    end
-    def pretty_print(q)
-      q.instance_exec(self) do |obj|
-        text "\#<#{obj.class.inspect}"
-        group_sub {
-          nest(2) {
-            breakable ' '
-            pp obj.attributes
-          }
-        }
-        breakable ''
-        text '>'
+      class << self
+        def new_container(object, openapi_document_class, options = {})
+          container_modules = Set[]
+
+          # TODO this is JSI internals that scorpio shouldn't really be using
+          if object.respond_to?(:to_hash)
+            container_modules << Enumerable # TODO change next JSI when PathedHashNode includes Enumerable
+            container_modules << JSI::PathedHashNode
+          end
+          if object.respond_to?(:to_ary)
+            container_modules << Enumerable # TODO change next JSI when PathedArrayNode includes Enumerable
+            container_modules << JSI::PathedArrayNode
+          end
+
+          container_modules += object.jsi_schemas.map do |schema|
+            JSI::SchemaClasses.accessor_module_for_schema(schema,
+              conflicting_modules: container_modules + [Container],
+            )
+          end
+
+          container_class = @container_classes[container_modules.freeze]
+
+          container_class.new(object, openapi_document_class, options)
+        end
       end
     end
 
-    def jsi_fingerprint
-      {class: self.class, attributes: JSI::Typelike.as_json(@attributes)}
+    class Container
+      include Containment
+
+      def initialize(contained_object, openapi_document_class, options = {})
+        @contained_object = contained_object
+        @openapi_document_class = openapi_document_class
+        @options = options
+        @subscript_memos = {}
+      end
+
+      attr_reader :contained_object
+
+      attr_reader :options
+
+      # @private
+      alias_method :jsi_node_content, :contained_object
+      private :jsi_node_content
+
+      # @private
+      # @return [Array<String>]
+      def jsi_object_group_text
+        schema_names = contained_object.jsi_schemas.map { |schema| schema.jsi_schema_module.name_from_ancestor || schema.schema_uri }.compact
+        if schema_names.empty?
+          [Container.to_s]
+        else
+          ["#{Container} (#{schema_names.join(', ')})"]
+        end
+      end
     end
-    include JSI::Util::FingerprintHash
   end
 end

data/lib/scorpio/response.rb

@@ -1,15 +1,17 @@
+# frozen_string_literal: true
+
 module Scorpio
   Response = Scorpio::Ur.properties['response']
 
   module Response
-    # @return [::JSI::Schema] the schema for this response according to its OpenAPI doc
+    # the schema for this response according to its OpenAPI doc
+    # @return [::JSI::Schema]
     def response_schema
       ur.scorpio_request.operation.response_schema(status: status, media_type: media_type)
     end
 
-    # @return [Object] the body (String) is parsed according to the response media type and
-    #   if supported (only application/json is currently supported) instantiated according to
-    #   #response_schema
+    # the body (String) is parsed according to the response media type, if supported (only JSON is
+    # currently supported), and instantiated as a JSI instance of {#response_schema} if that is defined.
     def body_object
       if json?
         if body.empty?

data/lib/scorpio/ur.rb

@@ -1,12 +1,16 @@
+# frozen_string_literal: true
+
 module Scorpio
-  # Scorpio::Ur is a JSI Schema module with which scorpio extends the ::Ur schema module
-  Ur = JSI::Schema.new({
+  # Scorpio::Ur is a JSI Schema module with which scorpio extends the ::Ur (toplevel)
+  # schema module from the Ur gem
+  Ur = JSI.new_schema_module({
+    '$schema' => 'http://json-schema.org/draft-07/schema#',
     '$id' => 'https://schemas.jsi.unth.net/ur',
     'properties' => {
       'request' => {},
       'response' => {},
     }
-  }).jsi_schema_module
+  })
 
   -> { Scorpio::Response }.() # invoke autoload
 

data/lib/scorpio/version.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Scorpio
-  VERSION = "0.5.0"
+  VERSION = "0.6.0".freeze
 end

data/lib/scorpio.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require "scorpio/version"
 require "jsi"
 require "ur"
@@ -20,12 +22,9 @@ module Scorpio
 
   proc { |v| define_singleton_method(:error_classes_by_status) { v } }.call({})
   # Scorpio::Error encompasses certain Scorpio-defined errors encountered in using Scorpio.
-  # at the moment this only includes HTTPError[^1], but will likely cover errors in schemas and
-  # other things in the future.
-  #
-  # [^1]: unless I have, since writing this, implemented other things but forgotten to update this
-  # comment, which does seem likely enough.
-  class Error < StandardError; end
+  class Error < StandardError
+  end
+
   class HTTPError < Error
     # for HTTPError subclasses representing a single status, sets and/or returns the represented status.
     #