praxis 2.0.pre.19 → 2.0.pre.22

data/lib/praxis/mapper/resources/callbacks.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Praxis
+  module Mapper
+    module Resources
+      module Callbacks
+        extend ::ActiveSupport::Concern
+
+        included do
+          class_attribute :before_callbacks, :after_callbacks, :around_callbacks
+          self.before_callbacks = Hash.new { |h, method| h[method] = [] }
+          self.after_callbacks = Hash.new { |h, method| h[method] = [] }
+          self.around_callbacks = Hash.new { |h, method| h[method] = [] }
+        end
+
+        module ClassMethods
+          def before(method, function = nil, &block)
+            target = function ? function.to_sym : block
+            before_callbacks[method] << target
+          end
+
+          def after(method, function = nil, &block)
+            target = function ? function.to_sym : block
+            after_callbacks[method] << target
+          end
+
+          def around(method, function = nil, &block)
+            target = function ? function.to_sym : block
+            around_callbacks[method] << target
+          end
+        end
+      end
+    end
+  end
+end

data/lib/praxis/mapper/resources/query_methods.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Praxis
+  module Mapper
+    module Resources
+      module QueryMethods
+        extend ::ActiveSupport::Concern
+
+        # Includes some limited, but handy query methods so we can transparently
+        # use them from the resource layer, and get wrapped resources from it
+        module ClassMethods
+          def including(args)
+            QueryProxy.new(klass: self).including(args)
+          end
+
+          def all(args = {})
+            QueryProxy.new(klass: self).all(args)
+          end
+
+          def get(args)
+            QueryProxy.new(klass: self).get(args)
+          end
+
+          def get!(args)
+            QueryProxy.new(klass: self).get!(args)
+          end
+
+          def first
+            QueryProxy.new(klass: self).first
+          end
+
+          def last
+            QueryProxy.new(klass: self).last
+          end
+        end
+      end
+    end
+  end
+end

data/lib/praxis/mapper/resources/query_proxy.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module Praxis
+  module Mapper
+    module Resources
+      class QueryProxy
+        attr_reader :klass
+
+        def initialize(klass:)
+          @klass = klass
+        end
+
+        def including(includes)
+          @_includes = includes
+          self
+        end
+
+        # Can pass extra includes through :_includes
+        # TODO: We should not use the AR includes, but first pass them through the properties, cause
+        #  we need to expand based on the resource methods, not the model methods
+        def get(condition)
+          base = klass.model._add_includes(klass.model, @_includes) # includes(nil) seems to have no effect
+          record = base._get(condition)
+
+          record.nil? ? nil : klass.wrap(record)
+        end
+
+        def get!(condition)
+          resource = get(condition)
+          # TODO: passing the :id if there is one in the condition...but can be more complex...think if we want to expose more
+          raise Praxis::Mapper::ResourceNotFound.new(type: @klass, id: condition[:id]) unless resource
+
+          resource
+        end
+
+        # Retrieve all or many wrapped resources
+        # .all -> returns them all
+        # .all(name: 'foo') -> returns all that match the name
+        def all(condition = {})
+          base = klass.model._add_includes(klass.model, @_includes) # includes(nil) seems to have no effect
+          records = base._all(condition)
+
+          klass.wrap(records)
+        end
+
+        def first
+          record = klass.model._first
+          record.nil? ? nil : klass.wrap(record)
+        end
+
+        def last
+          record = klass.model._last
+          record.nil? ? nil : klass.wrap(record)
+        end
+      end
+    end
+  end
+end

data/lib/praxis/mapper/resources/typed_methods.rb

@@ -0,0 +1,133 @@
+# frozen_string_literal: true
+
+module Praxis
+  module Mapper
+    module Resources
+      # Error raised when trying to call a typed method and the validation of arguments fails
+      class IncompatibleTypeForMethodArguments < ::StandardError
+        attr_reader :errors, :method
+
+        def initialize(errors:, method:, klass:)
+          @errors = errors
+          super "Error validating/coercing arguments for call to method #{method} of class #{klass}:\n#{errors}"
+        end
+      end
+
+      module TypedMethods
+        extend ::ActiveSupport::Concern
+
+        included do
+          include Praxis::Mapper::Resources::Callbacks
+
+          class << self
+            attr_reader :signatures
+
+            def _finalize!
+              if @signatures
+                # Build the around callbacks for coercing the params for the methods with types defined
+                # Also, this needs to be before, so that we hit the coercion code before any other around callback
+                const_set(:MethodSignatures, Module.new)
+                @signatures.each do |method, type|
+                  # Also add a constant pointing to the signature type inside Signatures (and substitute ! for Bang, as that's not allowed in a constant)
+                  # For class Methods, also substitute .self for Self
+                  # This helps with debugging, as we won't get anonymous struct classes, but we'll see these better names
+                  cleaned_name = method.to_s.gsub(/!/, '_bang').to_s.gsub(/^self./, 'self_')
+                  self::MethodSignatures.const_set(cleaned_name.camelize.to_sym, type)
+                  coerce_params_for method, type
+                end
+              end
+
+              super
+            end
+
+            def signature(method_name, &block)
+              method = method_name.to_sym
+              @signatures ||= {}
+              if block_given?
+                type =
+                  Class.new(Attributor::Struct) do
+                    attributes do
+                      instance_eval(&block)
+                    end
+                  end
+                @signatures[method] = type
+              else
+                @signatures[method]
+              end
+            end
+
+            # Sets up a specific around callback to a given method, where it'd pass the loaded/coerced type from the input
+            def coerce_params_for(method, type)
+              raise "Argument type for #{method} could not be found. Did you define a `signature` stanza for it?" unless type
+
+              if method.start_with?('self.')
+                simple_name = method.to_s.gsub(/^self./, '').to_sym
+                # Look for a Class method
+                raise "Error building typed method signature: Method #{method} is not defined in class #{name}" unless methods.include?(simple_name)
+
+                coerce_params_for_class(method(simple_name), type)
+              else
+                # Look for an instance method
+                raise "Error building typed method signature: Method #{method} is not defined in class #{name}" unless method_defined?(method)
+
+                coerce_params_for_instance(instance_method(method), type)
+              end
+            end
+
+            def coerce_params_for_instance(method, type)
+              around_method_name = "_coerce_params_for_#{method.name}"
+              instance_exec around_method_name: around_method_name,
+                            orig_method: method,
+                            type: type,
+                            ctx: [to_s, method.name].freeze,
+                            &CREATE_LOADER_METHOD
+
+              # Set an around callback to call the defined method above
+              around method.name, around_method_name
+            end
+
+            def coerce_params_for_class(method, type)
+              around_method_name = "_coerce_params_for_class_#{method.name}"
+              # Define an instance method in the eigenclass
+              singleton_class.instance_exec around_method_name: around_method_name,
+                                            orig_method: method,
+                                            type: type,
+                                            ctx: [to_s, method.name].freeze,
+                                            &CREATE_LOADER_METHOD
+
+              # Set an around callback to call the defined method above (the callbacks need self. for class interceptors)
+              class_method_name = "self.#{method.name}"
+              around class_method_name.to_sym, around_method_name
+            end
+
+            CREATE_LOADER_METHOD = proc do |around_method_name:, orig_method:, type:, ctx:|
+              has_args = orig_method.parameters.any? { |(argtype, _)| %i[req opt rest].include?(argtype) }
+              has_kwargs = orig_method.parameters.any? { |(argtype, _)| %i[keyreq keyrest].include?(argtype) }
+              raise "Typed signatures aren't supported for methods that have both kwargs and normal args: #{orig_method.name} of #{self.class}" if has_args && has_kwargs
+
+              if has_args
+                define_method(around_method_name) do |arg, &block|
+                  loaded = type.load(arg, ctx)
+                  errors = type.validate(loaded, ctx, nil)
+                  raise IncompatibleTypeForMethodArguments.new(errors: errors, method: orig_method.name, klass: self) unless errors.empty?
+
+                  # pass the struct object as a single arg
+                  block.yield(loaded)
+                end
+              else
+                define_method(around_method_name) do |**args, &block|
+                  loaded = type.load(args, ctx)
+                  errors = type.validate(loaded, ctx, nil)
+                  raise IncompatibleTypeForMethodArguments.new(errors: errors, method: orig_method.name, klass: self) unless errors.empty?
+
+                  # Splat the args if it's a kwarg type method
+                  block.yield(**loaded)
+                end
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+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.22'
 end

data/lib/praxis.rb

@@ -136,6 +136,13 @@ module Praxis
   module Mapper
     autoload :Resource, 'praxis/mapper/resource'
     autoload :SelectorGenerator, 'praxis/mapper/selector_generator'
+
+    module Resources
+      autoload :Callbacks, 'praxis/mapper/resources/callbacks'
+      autoload :QueryMethods, 'praxis/mapper/resources/query_methods'
+      autoload :TypedMethods, 'praxis/mapper/resources/typed_methods'
+      autoload :QueryProxy, 'praxis/mapper/resources/query_proxy'
+    end
   end
 
   # Avoid loading responses (and templates) lazily as they need to be registered in time

data/praxis.gemspec

@@ -23,7 +23,7 @@ Gem::Specification.new do |spec|
   spec.executables << 'praxis'
 
   spec.add_dependency 'activesupport', '>= 3'
-  spec.add_dependency 'attributor', '>= 6.0'
+  spec.add_dependency 'attributor', '>= 6.2'
   spec.add_dependency 'mime', '~> 0'
   spec.add_dependency 'mustermann', '>=1.1', '<=2'
   spec.add_dependency 'rack', '>= 1'
@@ -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

@@ -32,7 +32,9 @@ describe Praxis::Mapper::Resource do
   context 'retrieving resources' do
     context 'getting a single resource' do
       before do
-        expect(SimpleModel).to receive(:get).with(name: 'george xvi').and_return(record)
+        expect(SimpleModel).to receive(:get) do |args|
+          expect(**args).to match(name: 'george xvi')
+        end.and_return(record)
       end
 
       subject(:resource)  { SimpleResource.get(name: 'george xvi') }
@@ -44,7 +46,9 @@ describe Praxis::Mapper::Resource do
 
     context 'getting multiple resources' do
       before do
-        expect(SimpleModel).to receive(:all).with(name: ['george xvi']).and_return([record])
+        expect(SimpleModel).to receive(:all) do |args|
+          expect(**args).to eq(name: ['george xvi'])
+        end.and_return([record])
       end
 
       subject(:resource_collection) { SimpleResource.all(name: ['george xvi']) }
@@ -133,6 +137,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
@@ -163,4 +180,38 @@ describe Praxis::Mapper::Resource do
       expect(SimpleResource.wrap(record)).to be(OtherResource.wrap(record))
     end
   end
+
+  context 'calling typed methods' do
+    let(:resource) { TypedResource }
+    context 'class level ones' do
+      it 'kwarg methods get their args splatted in the top level' do
+        arg = resource.create(name: 'Praxis-licious', payload: { struct_param: { id: 1 } })
+        # Top level args are a hash (cause the typed methods will splat them before calling)
+        expect(arg).to be_kind_of Hash
+        # But structs beyond that are just the loaded types (which we can splat if we want to keep calling)
+        expect(arg[:payload]).to be_kind_of Attributor::Struct
+      end
+
+      it 'non-kwarg methods get a single arg' do
+        arg = resource.singlearg_create({ name: 'Praxis-licious', payload: { struct_param: { id: 1 } } })
+        # Single argument, instance of an Attributor Struct
+        expect(arg).to be_kind_of Attributor::Struct
+      end
+    end
+    context 'instance level ones' do
+      it 'kwarg methods get their args splatted in the top level' do
+        arg = resource.new({}).update!(string_param: 'Stringer', struct_param: { id: 1 })
+        # Top level args are a hash (cause the typed methods will splat them before calling)
+        expect(arg).to be_kind_of Hash
+        # But structs beyond that are just the loaded types (which we can splat if we want to keep calling)
+        expect(arg[:struct_param]).to be_kind_of Attributor::Struct
+      end
+
+      it 'non-kwarg methods get a single arg' do
+        arg = resource.new({}).singlearg_update!({ string_param: 'Stringer', struct_param: { id: 1 } })
+        # Single argument, instance of an Attributor Struct
+        expect(arg).to be_kind_of Attributor::Struct
+      end
+    end
+  end
 end

data/spec/praxis/mapper/resources/callbacks_spec.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+describe Praxis::Mapper::Resources::Callbacks do
+  context 'callbacks' do
+    let(:double_model) do
+      SimpleModel.new(before_count: 0, after_count: 0, around_count: 0, name: '', force: false)
+    end
+    let(:resource) { SimpleResource.new(double_model) }
+    context 'using functions with args and kwargs' do
+      subject { resource.change_name('hi', force: true) }
+      it 'before' do
+        expect(subject.record.before_count).to eq(1) # 1 before hook
+      end
+      it 'after' do
+        expect(subject.record.after_count).to eq(1) # 1 after hook
+      end
+      it 'around' do
+        # 50, just for the only filter
+        expect(subject.record.around_count).to eq(50)
+      end
+      after do
+        # one for the before, the around filter, the actual method and the after filter
+        expect(subject.record.name).to eq('hi-hi-hi-hi')
+        expect(subject.record.force).to be_truthy
+      end
+    end
+
+    context 'using functions with only kwargs' do
+      subject { resource.update!(number: 1000) }
+      it 'before' do
+        expect(subject.record.before_count).to eq(1) # 1 before hook
+      end
+      it 'after' do
+        expect(subject.record.after_count).to eq(1) # 1 after hook
+      end
+      it 'around' do
+        # 1000 for the orig update+1 from before_count + 50+100 for the 2 around filters
+        expect(subject.record.around_count).to eq(1151)
+      end
+    end
+
+    context 'using functions only args' do
+      subject { resource.argsonly('hi') }
+      it 'around' do
+        # 50, just for the only filter
+        expect(subject.record.around_count).to eq(50)
+      end
+      after do
+        # one for the the around filter and one for the actual methodr
+        expect(subject.record.name).to eq('hi-hi')
+      end
+    end
+  end
+end

data/spec/praxis/mapper/resources/query_proxy_spec.rb

@@ -0,0 +1,137 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+describe Praxis::Mapper::Resources::QueryProxy do
+  let(:instance) { described_class.new(klass: resource_class) }
+  let(:resource_class) { SimpleResource }
+  let(:the_includes) { nil }
+
+  context 'including' do
+    let(:the_includes) { %i[one two] }
+    it 'saves the includes' do
+      expect(instance.instance_variable_get(:@_includes)).to be_nil
+      result = instance.including(the_includes)
+      expect(instance.instance_variable_get(:@_includes)).to be(the_includes)
+      expect(result).to be instance
+    end
+  end
+
+  context 'get' do
+    subject { instance.get(id: 39) }
+    # Base responds to the underlying ORM method _get to retrieve a record given a condition
+    let(:base) { double('ORM Base', _get: model_instance) }
+
+    before do
+      expect(resource_class.model).to receive(:_add_includes) do |model, includes|
+        expect(model).to be SimpleModel
+        expect(includes).to be(the_includes)
+      end.and_return(base)
+    end
+    context 'when a model is not found' do
+      let(:model_instance) { nil }
+      it 'returns nil' do
+        expect(subject).to be nil
+      end
+    end
+
+    context 'with a found model' do
+      let(:model_instance) { SimpleModel.new }
+      it 'returns an instance of the resource, wrapping the record' do
+        expect(subject).to be_kind_of(SimpleResource)
+        expect(subject.record).to be(model_instance)
+      end
+    end
+  end
+
+  context 'all' do
+    subject { instance.all(id: 39, name: 'foo') }
+    # Base responds to the underlying ORM method _all to retrieve a list of records given a condition
+    let(:base) { double('ORM Base', _all: model_instances) }
+
+    before do
+      expect(resource_class.model).to receive(:_add_includes) do |model, includes|
+        expect(model).to be SimpleModel
+        expect(includes).to be(the_includes)
+      end.and_return(base)
+    end
+    context 'when no records found' do
+      let(:model_instances) { nil }
+      it 'returns nil' do
+        expect(subject).to be_empty
+      end
+    end
+
+    context 'with found records' do
+      let(:model_instances) { [SimpleModel.new(id: 1), SimpleModel.new(id: 2)] }
+      it 'returns an array of resource instances, each wrapping their record' do
+        expect(subject).to be_kind_of(Array)
+        expect(subject.map(&:record)).to eq(model_instances)
+      end
+    end
+  end
+
+  context 'first' do
+    subject { instance.first }
+    before do
+      expect(resource_class.model).to receive(:_first).and_return(model_instance)
+    end
+    context 'when a model is not found' do
+      let(:model_instance) { nil }
+      it 'returns nil' do
+        expect(subject).to be nil
+      end
+    end
+
+    context 'with a found model' do
+      let(:model_instance) { SimpleModel.new }
+      it 'returns an instance of the resource, wrapping the record' do
+        expect(subject).to be_kind_of(SimpleResource)
+        expect(subject.record).to be(model_instance)
+      end
+    end
+  end
+
+  context 'last' do
+    subject { instance.last }
+    before do
+      expect(resource_class.model).to receive(:_last).and_return(model_instance)
+    end
+    context 'when a model is not found' do
+      let(:model_instance) { nil }
+      it 'returns nil' do
+        expect(subject).to be nil
+      end
+    end
+
+    context 'with a found model' do
+      let(:model_instance) { SimpleModel.new }
+      it 'returns an instance of the resource, wrapping the record' do
+        expect(subject).to be_kind_of(SimpleResource)
+        expect(subject.record).to be(model_instance)
+      end
+    end
+  end
+
+  context 'get!' do
+    subject { instance.get!(id: 39) }
+    before do
+      # Expects to always call the normal get function for the result
+      expect(instance).to receive(:get) do |args|
+        expect(args[:id]).to eq(39)
+      end.and_return(resource_instance)
+    end
+    context 'when no record is found' do
+      let(:resource_instance) { nil }
+      it 'raises ResourceNotFound' do
+        expect { subject }.to raise_error(Praxis::Mapper::ResourceNotFound)
+      end
+    end
+    context 'with a record found' do
+      let(:resource_instance) { double('ResourceInstance') }
+      it 'simply returns the result of get' do
+        expect(subject).to be(resource_instance)
+      end
+    end
+  end
+end