praxis 2.0.pre.19 → 2.0.pre.20

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 58ae0c1f92272e7fd0aaaa779fb679db4b14f6e8d2f9df08efaec211bd3cc4f0
-  data.tar.gz: 19b73ba6239911b4b0f6d3097e58671f556f7835514b7fa52269c1a81f47d837
+  metadata.gz: 0ade185970597f7537bf75a761bb1e1a01739f2e696ad006f8421037320051c3
+  data.tar.gz: fd9e948ba2f7d48c0abc94f70bec9cad3f594b41d82f9ce9445df28be010fe14
 SHA512:
-  metadata.gz: f488d80d4e1495b3574bce59a20826c418ac663d6417838a24f7ef92770e73dd789fe3b9d432a5663b4e6cd5abe665be5d4fc96919c20d93dac0cd981732b4ec
-  data.tar.gz: b8ffc24d28567d4b00a83c8b03bfd00539791af3a675ec315858a800d9e7890bf5bbcb1b811cd91ef8a13c9edc10be96eefb605e34139c789b5ec174b6975342
+  metadata.gz: 66e64aafead42894ca61670c3a1ec3411d274d8d6cd80111d28088efd33f4c9641ed88d031cb308d0f0a7896264d877d4aa38a33a7f4944abc56aeb86dac2b81
+  data.tar.gz: e98a655a44a2e0d43b384e14d03ede406ace7ac79a41805e5b31178a07c902ac118e70e8ea8ef26d3cbfb70eca7404e53dd5a636f98b543c91dd90b1385926f0

data/CHANGELOG.md

@@ -2,6 +2,14 @@
 
 ## next
 
+## 2.0.pre.20
+* Changed the behavior of dev-mode when validate_responses. Now they return a 500 status code (instead of a 400) but with the same validation error format body.
+  * validate_responses is meant to catch the application returning non-compliant responses for development only. As such, a 500 is much more appropriate and clear, as the validation is done on the behavior of the server, and not on the information sent by the client (i.e., it is a server problem, not reacting the way the API is defined)
+* Introduced a method to reload a Resouce (.reload), which will clear the memoized values and call record.reload as well
+* Open API Generation enhancements:
+  * Fixed type discovery (where some types wouldn't be included in the output)
+  * Changed the generation to output named types into components, and use `$ref` to point to them whenever appropriate
+  * Report nullable attributes
 ## 2.0.pre.19
 * Introduced a new DSL for the `FilteringParams` type that allows filters for common attributes in your Media Types:
   * The new `any` DSL allows you to define which final leaf attribute to always allow, and with which operators and/or fuzzy restrictions.

data/lib/praxis/blueprint.rb

@@ -38,6 +38,7 @@ module Praxis
       end
     end
     include Attributor::Type
+    include Attributor::Container
     include Attributor::Dumpable
 
     extend Finalizable

data/lib/praxis/collection.rb

@@ -37,7 +37,7 @@ module Praxis
       the_type = @attribute&.type || member_type
       {
         type: json_schema_type,
-        items: { '$ref': "#/components/schemas/#{the_type.id}" }
+        items: the_type.as_json_schema
       }
     end
   end

data/lib/praxis/docs/open_api/media_type_object.rb

@@ -27,9 +27,9 @@ module Praxis
           return {} if type.is_a? SimpleMediaType # NOTE: skip if it's a SimpleMediaType?? ... is that correct?
 
           the_schema = if type.anonymous? || !(type < Praxis::MediaType) # Avoid referencing  custom/simple Types? (i.e., just MTs)
-                         SchemaObject.new(info: type).dump_schema
+                         SchemaObject.new(info: type).dump_schema(shallow: false, allow_ref: false)
                        else
-                         { '$ref': "#/components/schemas/#{type.id}" }
+                         SchemaObject.new(info: type).dump_schema(shallow: true, allow_ref: true)
                        end
 
           if example_payload

data/lib/praxis/docs/open_api/operation_object.rb

@@ -23,7 +23,6 @@ module Praxis
           all_tags = tags + action.traits
           h = {
             summary: action.name.to_s,
-            description: action.description,
             # externalDocs: {}, # TODO/FIXME
             operationId: id,
             responses: ResponsesObject.new(responses: action.responses).dump
@@ -32,6 +31,7 @@ module Praxis
             # security: [{}]
             # servers: [{}]
           }
+          h[:description] = action.description if action.description
           h[:tags] = all_tags.uniq unless all_tags.empty?
           h[:parameters] = all_parameters unless all_parameters.empty?
           h[:requestBody] = RequestBodyObject.new(attribute: action.payload).dump if action.payload

data/lib/praxis/docs/open_api/schema_object.rb

@@ -5,33 +5,65 @@ module Praxis
     module OpenApi
       class SchemaObject
         # https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#schema-object
-        attr_reader :type, :attribute
+        attr_reader :type
 
         def initialize(info:)
-          # info could be an attribute ... or a type?
-          if info.is_a? Attributor::Attribute
-            @attribute = info
+          @attribute_options = {}
+
+          # info could be an attribute ... or a type
+          if info.is_a?(Attributor::Attribute)
+            @type = info.type
+            # Save the options that might be attached to the attribute, to add them to the type schema later
+            @attribute_options = info.options
           else
             @type = info
           end
+
+          # Mediatypes have the description method, lower types don't
+          @attribute_options[:description] = @type.description if @type.respond_to?(:description)
+          @collection = type.respond_to?(:member_type)
         end
 
         def dump_example
-          ex = \
-            if attribute
-              attribute.example
-            else
-              type.example
-            end
+          ex = type.example
           ex.respond_to?(:dump) ? ex.dump : ex
         end
 
-        def dump_schema
-          if attribute
-            attribute.as_json_schema(shallow: true, example: nil)
+        def dump_schema(shallow: false, allow_ref: false)
+          # We will dump schemas for mediatypes by simply creating a reference to the components' section
+          if type < Attributor::Container
+            if (type < Praxis::Blueprint || type < Attributor::Model) && allow_ref && !type.anonymous?
+              # TODO: Do we even need a description?
+              h = @attribute_options[:description] ? { 'description' => @attribute_options[:description] } : {}
+
+              Praxis::Docs::OpenApiGenerator.instance.register_seen_component(type)
+              h.merge('$ref' => "#/components/schemas/#{type.id}")
+            elsif @collection
+              items = OpenApi::SchemaObject.new(info: type.member_type).dump_schema(allow_ref: allow_ref, shallow: false)
+              h = @attribute_options[:description] ? { 'description' => @attribute_options[:description] } : {}
+              h.merge(type: 'array', items: items)
+            else
+              # Object
+              props = type.attributes.transform_values do |definition|
+                OpenApi::SchemaObject.new(info: definition).dump_schema(allow_ref: true, shallow: shallow)
+              end
+              { type: :object, properties: props } # TODO: Example?
+            end
           else
-            type.as_json_schema(shallow: true, example: nil)
+            # OpenApi::SchemaObject.new(info:target).dump_schema(allow_ref: allow_ref, shallow: shallow)
+            # TODO...we need to make sure we can use refs in the underlying components after the first level...
+            # ... maybe we need to loop over the attributes if it's an object/struct?...
+            h = type.as_json_schema(shallow: shallow, example: nil, attribute_options: @attribute_options)
+
+            # Tag on OpenAPI specific requirements that aren't already added in the underlying JSON schema model
+            # Nullable: (it seems we need to ensure there is a null option to the enum, if there is one)
+            if @attribute_options[:null]
+              h[:nullable] = @attribute_options[:null]
+              h[:enum] = h[:enum] + [nil] if h[:enum] && !h[:enum].include?(nil)
+            end
+            h
           end
+
           # # TODO: FIXME: return a generic object type if the passed info was weird.
           # return { type: :object } unless info
 

data/lib/praxis/docs/open_api/tag_object.rb

@@ -12,11 +12,11 @@ module Praxis
         end
 
         def dump
-          {
-            name: name,
-            description: description
+          h = description ? { description: description } : {}
+          h.merge(
+            name: name
             # externalDocs: ???,
-          }
+          )
         end
       end
     end

data/lib/praxis/docs/open_api_generator.rb

@@ -9,6 +9,7 @@ module Praxis
   module Docs
     class OpenApiGenerator
       require 'active_support/core_ext/enumerable' # For index_by
+      include Singleton
 
       API_DOCS_DIRNAME = 'docs/openapi'
       EXCLUDED_TYPES_FROM_OUTPUT = Set.new([
@@ -26,7 +27,7 @@ module Praxis
                                              Attributor::URI
                                            ]).freeze
 
-      attr_reader :resources_by_version, :types_by_id, :infos_by_version, :doc_root_dir
+      attr_reader :resources_by_version, :infos_by_version, :doc_root_dir
 
       # substitutes ":params_like_so" for {params_like_so}
       def self.templatize_url(string)
@@ -34,24 +35,37 @@ module Praxis
       end
 
       def save!
+        raise 'You need to configure the root directory before saving (configure_root(<dir>))' unless @root
+
         initialize_directories
         # Restrict the versions listed in the index file to the ones for which we have at least 1 resource
         write_index_file(for_versions: resources_by_version.keys)
         resources_by_version.each_key do |version|
+          @seen_components_for_current_version = Set.new
           write_version_file(version)
         end
       end
 
-      def initialize(root)
+      def initialize
         require 'yaml'
-        @root = root
+
         @resources_by_version = Hash.new do |h, k|
           h[k] = Set.new
         end
-
+        # List of types that we have seen/marked as necessary to list in the components/schemas section
+        # These should contain any mediatype define in the versioned controllers plus any type
+        # for which we've explicitly rendered a $ref schema
+        @seen_components_for_current_version = Set.new
         @infos = ApiDefinition.instance.infos
         collect_resources
-        collect_types
+      end
+
+      def configure_root(root)
+        @root = root
+      end
+
+      def register_seen_component(type)
+        @seen_components_for_current_version.add(type)
       end
 
       private
@@ -69,63 +83,16 @@ module Praxis
         end
       end
 
-      def collect_types
-        @types_by_id = ObjectSpace.each_object(Class).select do |obj|
-          obj < Attributor::Type
-        end.index_by(&:id)
-      end
-
       def write_index_file(for_versions:)
         # TODO. create a simple html file that can link to the individual versions available
       end
 
-      def scan_types_for_version(version, dumped_resources)
-        found_media_types = resources_by_version[version].select(&:media_type).collect { |r| r.media_type.describe }
-
+      # TODO: Change this function name to scan_default_mediatypes...
+      def collect_default_mediatypes(endpoints)
         # We'll start by processing the rendered mediatypes
-        processed_types = Set.new(resources_by_version[version].select do |r|
-          r.media_type && !r.media_type.is_a?(Praxis::SimpleMediaType)
+        Set.new(endpoints.select do |endpoint|
+          endpoint.media_type && !endpoint.media_type.is_a?(Praxis::SimpleMediaType)
         end.collect(&:media_type))
-
-        newfound = Set.new
-        found_media_types.each do |mt|
-          newfound += scan_dump_for_types({ type: mt }, processed_types)
-        end
-        # Then will process the rendered resources (noting)
-        newfound += scan_dump_for_types(dumped_resources, Set.new)
-
-        # At this point we've done a scan of the dumped resources and mediatypes.
-        # In that scan we've discovered a bunch of types, however, many of those might have appeared in the JSON
-        # rendered in just shallow mode, so it is not guaranteed that we've seen all the available types.
-        # For that we'll do a (non-shallow) dump of all the types we found, and scan them until the scans do not
-        # yield types we haven't seen before
-        until newfound.empty?
-          dumped = newfound.collect(&:describe)
-          processed_types += newfound
-          newfound = scan_dump_for_types(dumped, processed_types)
-        end
-        processed_types
-      end
-
-      def scan_dump_for_types(data, processed_types)
-        newfound_types = Set.new
-        case data
-        when Array
-          data.collect { |item| newfound_types += scan_dump_for_types(item, processed_types) }
-        when Hash
-          if data.key?(:type) && data[:type].is_a?(Hash) && (%i[id name family] - data[:type].keys).empty?
-            type_id = data[:type][:id]
-            unless type_id.nil? || type_id == Praxis::SimpleMediaType.id # SimpleTypes shouldn't be collected
-              unless types_by_id[type_id]
-                raise "Error! We have detected a reference to a 'Type' with id='#{type_id}' which is not derived from Attributor::Type" \
-                      ' Document generation cannot proceed.'
-              end
-              newfound_types << types_by_id[type_id] unless processed_types.include? types_by_id[type_id]
-            end
-          end
-          data.values.map { |item| newfound_types += scan_dump_for_types(item, processed_types) }
-        end
-        newfound_types
       end
 
       def write_version_file(version)
@@ -133,11 +100,11 @@ module Praxis
         # # Hack, let's "inherit/copy" all traits of a version from the global definition
         # # Eventually traits should be defined for a version (and inheritable from global) so we'll emulate that here
         # version_info[:traits] = infos_by_version[:traits]
-        dumped_resources = dump_resources(resources_by_version[version])
-        processed_types = scan_types_for_version(version, dumped_resources)
 
+        # We'll for sure include any of the default mediatypes in the endpoints for this version
+        @seen_components_for_current_version.merge(collect_default_mediatypes(resources_by_version[version]))
         # Here we have:
-        # processed types: which includes mediatypes and normal types...real classes
+        # processed types: which includes default mediatypes for the processed endpoints
         # processed resources for this version: resources_by_version[version]
 
         info_object = OpenApi::InfoObject.new(version: version, api_definition_info: @infos[version])
@@ -168,8 +135,8 @@ module Praxis
         end
         full_data[:tags] = full_data[:tags] + tags_for_traits unless tags_for_traits.empty?
 
-        # Include only MTs (i.e., not custom types or simple types...)
-        component_schemas = reusable_schema_objects(processed_types.select { |t| t < Praxis::MediaType })
+        # Include only MTs and Blueprints (i.e., no simple types...)
+        component_schemas = add_component_schemas(@seen_components_for_current_version.clone, {})
 
         # 3- Then adding all of the top level Mediatypes...so we can present them at the bottom, otherwise they don't show
         tags_for_mts = component_schemas.map do |(name, _info)|
@@ -251,16 +218,16 @@ module Praxis
         end
       end
 
-      def reusable_schema_objects(types)
-        types.each_with_object({}) do |(type), accum|
-          the_type = \
-            if type.respond_to? :as_json_schema
-              type
-            else # If it is a blueprint ... for now, it'd be through the attribute
-              type.attribute
-            end
-          accum[type.id] = the_type.as_json_schema(shallow: false)
+      def add_component_schemas(types_to_add, components_hash)
+        initial = @seen_components_for_current_version.dup
+        types_to_add.each_with_object(components_hash) do |(type), accum|
+          # For components, we want the first level to be fully dumped (only references below that)
+          accum[type.id] = OpenApi::SchemaObject.new(info: type).dump_schema(allow_ref: false, shallow: false)
         end
+        newfound = @seen_components_for_current_version - initial
+        # Process the new types if they have discovered
+        add_component_schemas(newfound, components_hash) unless newfound.empty?
+        components_hash
       end
 
       def convert_to_parameter_object(params)

data/lib/praxis/mapper/resource.rb

@@ -13,6 +13,8 @@ module Praxis
 
       class << self
         attr_reader :model_map, :properties
+        # Names of the memoizable things (without the @__ prefix)
+        attr_accessor :memoized_variables
       end
 
       # TODO: also support an attribute of sorts on the versioned resource module. ie, V1::Resources.api_version.
@@ -32,6 +34,7 @@ module Praxis
 
           @properties = superclass.properties.clone
           @_filters_map = {}
+          @memoized_variables = []
         end
       end
 
@@ -130,10 +133,13 @@ module Praxis
 
         return unless association_resource_class
 
+        memoized_variables << name
         module_eval <<-RUBY, __FILE__, __LINE__ + 1
         def #{name}
+          return @__#{name} if instance_variable_defined?("@__#{name}")
+
           records = record.#{name}
-            return nil if records.nil?
+          return nil if records.nil?
           @__#{name} ||= #{association_resource_class}.wrap(records)
         end
         RUBY
@@ -151,6 +157,7 @@ module Praxis
       end
 
       def self.define_delegation_for_related_attribute(resource_name, resource_attribute)
+        memoized_variables << resource_attribute
         module_eval <<-RUBY, __FILE__, __LINE__ + 1
         def #{resource_attribute}
           @__#{resource_attribute} ||= if (rec = self.#{resource_name})
@@ -164,6 +171,7 @@ module Praxis
         related_resource_class = model_map[related_association[:model]]
         return unless related_resource_class
 
+        memoized_variables << resource_attribute
         module_eval <<-RUBY, __FILE__, __LINE__ + 1
         def #{resource_attribute}
           @__#{resource_attribute} ||= if (rec = self.#{resource_name})
@@ -181,10 +189,10 @@ module Praxis
                     else
                       name.to_s
                     end
-
+        memoized_variables << ivar_name
         module_eval <<-RUBY, __FILE__, __LINE__ + 1
       def #{name}
-        return @__#{ivar_name} if defined? @__#{ivar_name}
+        return @__#{ivar_name} if instance_variable_defined?("@__#{ivar_name}")
         @__#{ivar_name} = record.#{name}
       end
         RUBY
@@ -239,6 +247,22 @@ module Praxis
         @record = record
       end
 
+      def reload
+        clear_memoization
+        reload_record
+      end
+
+      def clear_memoization
+        self.class.memoized_variables.each do |name|
+          ivar = "@__#{name}"
+          remove_instance_variable(ivar) if instance_variable_defined?(ivar)
+        end
+      end
+
+      def reload_record
+        record.reload
+      end
+
       def respond_to_missing?(name, *)
         @record.respond_to?(name) || super
       end

data/lib/praxis/response.rb

@@ -110,8 +110,18 @@ module Praxis
         raise Exceptions::Validation, "Attempting to return a response with name #{response_name} " \
           'but no response definition with that name can be found'
       end
-
       response_definition.validate(self, validate_body: validate_body)
+    rescue Exceptions::Validation => e
+      ve = Application.instance.validation_handler.handle!(
+        summary: 'Error validating response',
+        exception: e,
+        request: request,
+        stage: 'response',
+        errors: e.errors
+      )
+      body = ve.format!
+
+      Responses::InternalServerError.new(body: body)
     end
   end
 end

data/lib/praxis/tasks/api_docs.rb

@@ -7,7 +7,8 @@ namespace :praxis do
       require 'fileutils'
 
       Praxis::Blueprint.caching_enabled = false
-      generator = Praxis::Docs::OpenApiGenerator.new(Dir.pwd)
+      generator = Praxis::Docs::OpenApiGenerator.instance
+      generator.configure_root(Dir.pwd)
       generator.save!
     end
 

data/lib/praxis/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Praxis
-  VERSION = '2.0.pre.19'
+  VERSION = '2.0.pre.20'
 end

data/praxis.gemspec

@@ -51,6 +51,6 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency 'rspec-collection_matchers', '~> 1'
   spec.add_development_dependency 'rspec-its', '~> 1'
   # Just for the query selector extensions etc...
-  spec.add_development_dependency 'activerecord', '> 4','< 7'
+  spec.add_development_dependency 'activerecord', '> 4', '< 7'
   spec.add_development_dependency 'sequel', '~> 5'
 end

data/spec/functional_spec.rb

@@ -88,7 +88,7 @@ describe 'Functional specs' do
 
       it 'fails to validate the response' do
         get '/api/clouds/1/instances?response_content_type=somejunk&api_version=1.0', nil, 'HTTP_FOO' => 'bar', 'global_session' => session
-        expect(last_response.status).to eq(400)
+        expect(last_response.status).to eq(500)
         response = JSON.parse(last_response.body)
 
         expect(response['name']).to eq('ValidationError')
@@ -104,7 +104,7 @@ describe 'Functional specs' do
           expect(Praxis::Application.instance.config).to receive(:praxis).and_return(praxis_config)
         end
 
-        it 'fails to validate the response' do
+        it 'does not validate the response and succeeds' do
           expect do
             get '/api/clouds/1/instances?response_content_type=somejunk&api_version=1.0', nil, 'global_session' => session
           end.to_not raise_error
@@ -400,7 +400,7 @@ describe 'Functional specs' do
       its(['root_volume']) { should be(nil) }
     end
 
-    context 'with an invalid name' do
+    context 'returning an invalid name' do
       let(:request_payload) { { name: 'Invalid Name' } }
 
       its(['name']) { should eq 'ValidationError' }
@@ -408,7 +408,7 @@ describe 'Functional specs' do
       its(['errors']) { should match_array [/\$\.name value \(Invalid Name\) does not match regexp/] }
 
       it 'returns a validation error' do
-        expect(last_response.status).to eq(400)
+        expect(last_response.status).to eq(500)
       end
     end
   end

data/spec/praxis/mapper/resource_spec.rb

@@ -133,6 +133,19 @@ describe Praxis::Mapper::Resource do
       allow(record).to receive(:other_model).and_return(other_record)
       expect(resource.other_resource).to be(SimpleResource.new(record).other_resource)
     end
+
+    it 'memoizes result of related associations' do
+      expect(record).to receive(:parent).once.and_return(parent_record)
+      expect(resource.parent).to be(resource.parent)
+    end
+
+    it 'can clear memoization' do
+      expect(record).to receive(:parent).twice.and_return(parent_record)
+
+      expect(resource.parent).to be(resource.parent) # One time only calling the record parent method
+      resource.clear_memoization
+      expect(resource.parent).to be(resource.parent) # One time only time calling the record parent method after the reset
+    end
   end
 
   context '.wrap' do

data/spec/praxis/response_spec.rb

@@ -61,9 +61,15 @@ describe Praxis::Response do
       end
 
       it 'should raise an error' do
+        resp = nil
         expect do
-          response.validate(action)
-        end.to raise_error(Praxis::Exceptions::Validation, /response definition with that name can be found/)
+          resp = response.validate(action)
+        end.to_not raise_error
+
+        expect(resp.status).to eq(500)
+        expect(resp.body[:name]).to eq('ValidationError')
+        expect(resp.body[:summary]).to eq('Error validating response')
+        expect(resp.body[:errors]).to include(/response definition with that name can be found/)
       end
     end
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: praxis
 version: !ruby/object:Gem::Version
-  version: 2.0.pre.19
+  version: 2.0.pre.20
 platform: ruby
 authors:
 - Josep M. Blanquer
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2022-01-10 00:00:00.000000000 Z
+date: 2022-02-07 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport