scimitar 1.2.1 → 1.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 69cae1bb9cbd4ddcdf7914e35b4ac23ad7359c2d566d99071dfb346ae8b2f9d2
-  data.tar.gz: c1636e01e98e1938a1f62ffd27b8aa0c00a787860f93a95f445158cb8e7e6064
+  metadata.gz: 9faabfad9cae931ab19f765393d9f307fa5d44773f943d2286fbd92302c2e9e1
+  data.tar.gz: 2bc23d4e3b123103efd0fa87375547dcdf9e3684ea272a1e4941c43e7845937b
 SHA512:
-  metadata.gz: 321cf5943bf587c925c827d909cb8dda138be977a03e211b1a7496e0c608da1055a0e4fb9aaa1d8f9877d5631a34dbba5f16c00b50098ca08b5bdfa6fed2cff2
-  data.tar.gz: 910f2e4f85c7722f71229cdbd680af6af64aa7d1186e8464ad6050b338f97bf6849042407b241acfc409a63ce8fe48023f1f251d3712d1ec8298cb91d911ce0f
+  metadata.gz: bb74810f72d7b806b7e6aef1a02d363be1135dbf190e2ae0e88a727f94ec9b90e643a13883cd64951d4879fe542fb5936621ec96c44d0f192050f9f6453b58ef
+  data.tar.gz: b8ea496f490696379236a971070f6e04188fbfcff27f0dd484e18c01416193c625173c72618e123cbc39b1521ef4e6137553396d981db6366861f98f172cee2c

data/app/controllers/scimitar/application_controller.rb

@@ -25,10 +25,12 @@ module Scimitar
       #
       # ...to "globally" invoke this handler if you wish.
       #
-      # +_exception+:: Exception instance (currently unused).
       #
-      def handle_resource_not_found(_exception)
-        handle_scim_error(NotFoundError.new(params[:id]))
+      # +exception+:: Exception instance, used for a configured error reporter
+      #               via #handle_scim_error (if present).
+      #
+      def handle_resource_not_found(exception)
+        handle_scim_error(NotFoundError.new(params[:id]), exception)
       end
 
       # This base controller uses:
@@ -38,9 +40,22 @@ module Scimitar
       # ...to "globally" invoke this handler for all Scimitar errors (including
       # subclasses).
       #
+      # Mandatory parameters are:
+      #
       # +error_response+:: Scimitar::ErrorResponse (or subclass) instance.
       #
-      def handle_scim_error(error_response)
+      # Optional parameters are:
+      #
+      # *exception+:: If a Ruby exception was the reason this method is being
+      #               called, pass it here. Any configured exception reporting
+      #               mechanism will be invokved with the given parameter.
+      #               Otherwise, the +error_response+ value is reported.
+      #
+      def handle_scim_error(error_response, exception = error_response)
+        unless Scimitar.engine_configuration.exception_reporter.nil?
+          Scimitar.engine_configuration.exception_reporter.call(exception)
+        end
+
         render json: error_response, status: error_response.status
       end
 
@@ -55,7 +70,7 @@ module Scimitar
       # +exception+:: Exception instance.
       #
       def handle_bad_json_error(exception)
-        handle_scim_error(ErrorResponse.new(status: 400, detail: "Invalid JSON - #{exception.message}"))
+        handle_scim_error(ErrorResponse.new(status: 400, detail: "Invalid JSON - #{exception.message}"), exception)
       end
 
       # This base controller uses:
@@ -68,7 +83,7 @@ module Scimitar
       #
       def handle_unexpected_error(exception)
         Rails.logger.error("#{exception.message}\n#{exception.backtrace}")
-        handle_scim_error(ErrorResponse.new(status: 500, detail: exception.message))
+        handle_scim_error(ErrorResponse.new(status: 500, detail: exception.message), exception)
       end
 
     # =========================================================================

data/app/models/scimitar/engine_configuration.rb

@@ -9,13 +9,17 @@ module Scimitar
 
     attr_accessor :basic_authenticator,
                   :token_authenticator,
-                  :application_controller_mixin
+                  :application_controller_mixin,
+                  :exception_reporter,
+                  :optional_value_fields_required
 
     def initialize(attributes = {})
 
-      # No defaults yet - reserved for future use.
+      # Set defaults that may be overridden by the initializer.
       #
-      defaults = {}
+      defaults = {
+        optional_value_fields_required: true
+      }
 
       super(defaults.merge(attributes))
     end

data/app/models/scimitar/error_response.rb

@@ -16,5 +16,17 @@ module Scimitar
       data['scimType'] = scimType if scimType
       data
     end
+
+    # Originally Scimitar used attribute "detail" for exception text; it was
+    # only for JSON responses at the time, but in hindsight was a bad choice.
+    # It should have been "message" given inheritance from StandardError, which
+    # then works properly with e.g. error reporting services.
+    #
+    # The "detail" attribute is still present, for backwards compatibility with
+    # any client code that might be using this class.
+    #
+    def message
+      self.detail
+    end
   end
 end

data/app/models/scimitar/lists/query_parser.rb

@@ -633,7 +633,7 @@ module Scimitar
               when 'pr'
                 arel_table.grouping(arel_column.not_eq_all(['', nil]))
               else
-                raise Scimitar::FilterError
+                raise Scimitar::FilterError.new("Unsupported operator: '#{scim_operator}'")
             end
 
             if index == 0
@@ -656,10 +656,10 @@ module Scimitar
         # +scim_attribute+:: SCIM attribute from a filter string.
         #
         def activerecord_columns(scim_attribute)
-          raise Scimitar::FilterError if scim_attribute.blank?
+          raise Scimitar::FilterError.new("No scim_attribute provided") if scim_attribute.blank?
 
           mapped_attribute = self.attribute_map()[scim_attribute]
-          raise Scimitar::FilterError if mapped_attribute.blank?
+          raise Scimitar::FilterError.new("Unable to find domain attribute from SCIM attribute: '#{scim_attribute}'") if mapped_attribute.blank?
 
           if mapped_attribute[:ignore]
             return []

data/app/models/scimitar/resources/mixin.rb

@@ -902,7 +902,11 @@ module Scimitar
                     altering_hash[path_component] = value
                   end
                 when 'replace'
-                  altering_hash[path_component] = value
+                  if path_component == 'root'
+                    altering_hash[path_component].merge!(value)
+                  else
+                    altering_hash[path_component] = value
+                  end
                 when 'remove'
                   altering_hash.delete(path_component)
               end

data/app/models/scimitar/schema/address.rb

@@ -10,6 +10,7 @@ module Scimitar
       def self.scim_attributes
         @scim_attributes ||= [
           Attribute.new(name: 'type',          type: 'string'),
+          Attribute.new(name: 'primary',       type: 'boolean'),
           Attribute.new(name: 'formatted',     type: 'string'),
           Attribute.new(name: 'streetAddress', type: 'string'),
           Attribute.new(name: 'locality',      type: 'string'),

data/app/models/scimitar/schema/vdtp.rb

@@ -7,7 +7,7 @@ module Scimitar
     class Vdtp < Base
       def self.scim_attributes
         @scim_attributes ||= [
-          Attribute.new(name: 'value',   type: 'string', required: true),
+          Attribute.new(name: 'value',   type: 'string', required: Scimitar.engine_configuration.optional_value_fields_required),
           Attribute.new(name: 'display', type: 'string', mutability: 'readOnly'),
           Attribute.new(name: 'type',    type: 'string'),
           Attribute.new(name: 'primary', type: 'boolean'),

data/config/initializers/scimitar.rb

@@ -79,4 +79,24 @@ Scimitar.engine_configuration = Scimitar::EngineConfiguration.new({
   # Note that both basic and token authentication can be declared, with the
   # parameters in the inbound HTTP request determining which is invoked.
 
+  # Scimitar rescues certain error cases and exceptions, in order to return a
+  # JSON response to the API caller. If you want exceptions to also be
+  # reported to a third party system such as sentry.io or raygun.com, you can
+  # configure a Proc to do so. It is passed a Ruby exception subclass object.
+  # For example, a minimal sentry.io reporter might do this:
+  #
+  #     exception_reporter: Proc.new do | exception |
+  #       Sentry.capture_exception(exception)
+  #     end
+  #
+  # You will still need to configure your reporting system according to its
+  # documentation (e.g. via a Rails "config/initializers/<foo>.rb" file).
+
+  # Scimilar treats "VDTP" (Value, Display, Type, Primary) attribute values,
+  # used for e.g. e-mail addresses or phone numbers, as required by default.
+  # If you encounter a service which calls these with e.g. "null" value data,
+  # you can configure all values to be optional. You'll need to deal with
+  # whatever that means for you receiving system in your model code.
+  #
+  #     optional_value_fields_required: false
 })

data/lib/scimitar/version.rb

@@ -3,11 +3,11 @@ module Scimitar
   # Gem version. If this changes, be sure to re-run "bundle install" or
   # "bundle update".
   #
-  VERSION = '1.2.1'
+  VERSION = '1.3.1'
 
   # Date for VERSION. If this changes, be sure to re-run "bundle install"
   # or "bundle update".
   #
-  DATE = '2022-06-15'
+  DATE = '2022-11-04'
 
 end

data/spec/controllers/scimitar/application_controller_spec.rb

@@ -169,5 +169,74 @@ RSpec.describe Scimitar::ApplicationController do
       expect(parsed_body).to include('status' => '500')
       expect(parsed_body).to include('detail' => 'Bang')
     end
-  end
+
+    context 'with an exception reporter' do
+      around :each do | example |
+        original_configuration = Scimitar.engine_configuration.exception_reporter
+        Scimitar.engine_configuration.exception_reporter = Proc.new do | exception |
+          @exception = exception
+        end
+        example.run()
+      ensure
+        Scimitar.engine_configuration.exception_reporter = original_configuration
+      end
+
+      context 'and "internal server error"' do
+        it 'is invoked' do
+          get :index, params: { format: :scim }
+
+          expect(@exception).to be_a(RuntimeError)
+          expect(@exception.message).to eql('Bang')
+        end
+      end
+
+      context 'and "not found"' do
+        controller do
+          def index
+            handle_resource_not_found(ActiveRecord::RecordNotFound.new(42))
+          end
+        end
+
+        it 'is invoked' do
+          get :index, params: { format: :scim }
+
+          expect(@exception).to be_a(ActiveRecord::RecordNotFound)
+          expect(@exception.message).to eql('42')
+        end
+      end
+
+      context 'and bad JSON' do
+        controller do
+          def index
+            begin
+              raise 'Hello'
+            rescue
+              raise ActionDispatch::Http::Parameters::ParseError
+            end
+          end
+        end
+
+        it 'is invoked' do
+          get :index, params: { format: :scim }
+
+          expect(@exception).to be_a(ActionDispatch::Http::Parameters::ParseError)
+          expect(@exception.message).to eql('Hello')
+        end
+      end
+
+      context 'and a bad content type' do
+        controller do
+          def index; end
+        end
+
+        it 'is invoked' do
+          request.headers['Content-Type'] = 'text/plain'
+          get :index
+
+          expect(@exception).to be_a(Scimitar::ErrorResponse)
+          expect(@exception.message).to eql('Only application/scim+json type is accepted.')
+        end
+      end
+    end # "context 'exception reporter' do"
+  end # "context 'error handling' do"
 end

data/spec/models/scimitar/complex_types/email_spec.rb

@@ -18,6 +18,4 @@ RSpec.describe Scimitar::ComplexTypes::Email do
       expect(described_class.new(value: 'a@b.c').as_json).to eq('value' => 'a@b.c')
     end
   end
-
 end
-

data/spec/models/scimitar/resources/base_validation_spec.rb

@@ -1,7 +1,6 @@
 require 'spec_helper'
 
 RSpec.describe Scimitar::Resources::Base do
-
   context '#valid?' do
     MyCustomSchema = Class.new(Scimitar::Schema::Base) do
       def self.id
@@ -21,6 +20,9 @@ RSpec.describe Scimitar::Resources::Base do
           ),
           Scimitar::Schema::Attribute.new(
             name: 'complexNames', complexType: Scimitar::ComplexTypes::Name, multiValued:true, required: false
+          ),
+          Scimitar::Schema::Attribute.new(
+            name: 'vdtpTestByEmail', complexType: Scimitar::ComplexTypes::Email, required: false
           )
         ]
       end
@@ -57,5 +59,28 @@ RSpec.describe Scimitar::Resources::Base do
       expect(resource.valid?).to be(false)
       expect(resource.errors.full_messages).to match_array(["Complexnames has to follow the complexType format.", "Complexnames familyname has the wrong type. It has to be a(n) string."])
     end
-  end
+
+    context 'configuration of required values in VDTP schema' do
+      around :each do | example |
+        original_configuration = Scimitar.engine_configuration.optional_value_fields_required
+        Scimitar::Schema::Email.instance_variable_set('@scim_attributes', nil)
+        example.run()
+      ensure
+        Scimitar.engine_configuration.optional_value_fields_required = original_configuration
+        Scimitar::Schema::Email.instance_variable_set('@scim_attributes', nil)
+      end
+
+      it 'requires a value by default' do
+        resource = MyCustomResource.new(vdtpTestByEmail: { value: nil }, enforce: false)
+        expect(resource.valid?).to be(false)
+        expect(resource.errors.full_messages).to match_array(['Vdtptestbyemail value is required'])
+      end
+
+      it 'can be configured for optional values' do
+        Scimitar.engine_configuration.optional_value_fields_required = false
+        resource = MyCustomResource.new(vdtpTestByEmail: { value: nil }, enforce: false)
+        expect(resource.valid?).to be(true)
+      end
+    end # "context 'configuration of required values in VDTP schema' do"
+  end # "context '#valid?' do"
 end

data/spec/models/scimitar/resources/mixin_spec.rb

@@ -1747,6 +1747,24 @@ RSpec.describe Scimitar::Resources::Mixin do
                 expect(scim_hash['emails'][0]['type' ]).to eql('work')
                 expect(scim_hash['emails'][0]['value']).to eql('work@test.com')
               end
+
+              context 'when prior value already exists, and no path' do
+                it 'simple value: overwrites' do
+                  path      = [ 'root' ]
+                  scim_hash = { 'root' => { 'userName' => 'bar', 'active' => true } }.with_indifferent_case_insensitive_access()
+
+                  @instance.send(
+                    :from_patch_backend!,
+                    nature:        'replace',
+                    path:          path,
+                    value:         { 'active' => false }.with_indifferent_case_insensitive_access(),
+                    altering_hash: scim_hash
+                  )
+
+                  expect(scim_hash['root']['userName']).to eql('bar')
+                  expect(scim_hash['root']['active']).to eql(false)
+                end
+              end
             end # context 'when value is not present' do
           end # "context 'replace' do"
 

data/spec/models/scimitar/schema/base_spec.rb

@@ -11,7 +11,7 @@ RSpec.describe Scimitar::Schema::Base do
   end
 
   context '#initialize' do
-    it 'creates a meta' do
+    it 'creates "meta"' do
       schema = described_class.new
       expect(schema.meta.resourceType).to eql('Schema')
     end

data/spec/models/scimitar/schema/user_spec.rb

@@ -419,6 +419,16 @@ RSpec.describe Scimitar::Schema::User do
             "name": "type",
             "type": "string"
           },
+          {
+            "multiValued": false,
+            "required": false,
+            "caseExact": false,
+            "mutability": "readWrite",
+            "uniqueness": "none",
+            "returned": "default",
+            "name": "primary",
+            "type": "boolean"
+          },
           {
             "multiValued": false,
             "required": false,

metadata

@@ -1,15 +1,15 @@
 --- !ruby/object:Gem::Specification
 name: scimitar
 version: !ruby/object:Gem::Version
-  version: 1.2.1
+  version: 1.3.1
 platform: ruby
 authors:
 - RIPA Global
 - Andrew David Hodgkinson
-autorequire: 
+autorequire:
 bindir: bin
 cert_chain: []
-date: 2022-06-15 00:00:00.000000000 Z
+date: 2022-11-04 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -245,7 +245,7 @@ metadata:
   source_code_uri: https://github.com/RIPAGlobal/scimitar/
   bug_tracker_uri: https://github.com/RIPAGlobal/scimitar/issues/
   changelog_uri: https://github.com/RIPAGlobal/scimitar/blob/master/CHANGELOG.md
-post_install_message: 
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -261,7 +261,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubygems_version: 3.1.6
-signing_key: 
+signing_key:
 specification_version: 4
 summary: SCIM v2 for Rails
 test_files: