scimitar 2.0.2 → 2.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8a60a7aa88fe30a83bdf337787203b276a39e456c9818653fd30cdc256102318
-  data.tar.gz: 3d092d6ff249121c2414686f215c6530f0e4fc24addf921953f6d6010ead6d13
+  metadata.gz: d10a10d763c621e797fbe343a113a8610f9317a06455f177c60c42062663b4da
+  data.tar.gz: 251c1b73b7dd51ded63d85f7b0816163a9bd567099db9ce5f57e4929301d7a49
 SHA512:
-  metadata.gz: 85ad5d6b4b1613eab67380772389e5789478d64adcca7116a054c71c879c0ada502312982027cbf3dbfa2c833aec5cfd12eae3d4946fd30289678909b2e2d87b
-  data.tar.gz: dfd9259e908867af51bd751d559cc9a323861dad2b5313e295e92d7b527356fee39c6accaca3c26d88bed4fca006e98f01bc7954ae91ab8626316270c3c8c507
+  metadata.gz: 77accce401fb9f6fbb91a0ebf53294754286867cc2becce4f8acccbbd35f90c9062174d1da0e0ad4c80a92acc053c4a0b30898260fe95dc580bf3df33453f975
+  data.tar.gz: 9e64bad4582b54c988f612f9a0920b291431a79f62f9656bcad2658c5a0ded291e9cf96f47cac5f2b130c47a30edbf3b68b6f8abe96ca9cb8a7bb8dcaea83bd2

data/app/controllers/scimitar/application_controller.rb

@@ -25,10 +25,11 @@ module Scimitar
       #
       # ...to "globally" invoke this handler if you wish.
       #
-      # +_exception+:: Exception instance (currently unused).
+      # +_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]))
+      def handle_resource_not_found(exception)
+        handle_scim_error(NotFoundError.new(params[:id]), exception)
       end
 
       # This base controller uses:
@@ -38,9 +39,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 +69,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 +82,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
+
+    # From v1, Scimitar used attribute "detail" for the 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/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

@@ -81,6 +81,26 @@ Rails.application.config.to_prepare do # (required for >= Rails 7 / Zeitwerk)
     # 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
   })
 
 end

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 = '2.0.2'
+  VERSION = '2.1.0'
 
   # Date for VERSION. If this changes, be sure to re-run "bundle install"
   # or "bundle update".
   #
-  DATE = '2022-06-15'
+  DATE = '2022-07-14'
 
 end

data/spec/controllers/scimitar/application_controller_spec.rb

@@ -169,5 +169,70 @@ 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
+            raise ActionDispatch::Http::Parameters::ParseError.new("Hello")
+          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/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,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: scimitar
 version: !ruby/object:Gem::Version
-  version: 2.0.2
+  version: 2.1.0
 platform: ruby
 authors:
 - RIPA Global
@@ -9,7 +9,7 @@ authors:
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2022-06-15 00:00:00.000000000 Z
+date: 2022-07-14 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -260,7 +260,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.3.3
+rubygems_version: 3.3.7
 signing_key:
 specification_version: 4
 summary: SCIM v2 for Rails