scimitar 2.6.1 → 2.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e763d8f162583b44983db37fe3d8f0e8c9fa4f39f841813e9c3df247ffcd8cf9
-  data.tar.gz: cfc7680b8f12d928a8975882109027f0c72f13884b438f04b90dcadc8d8a582c
+  metadata.gz: 63de55fe4d1ab41c577b2af07fafa7285fbee265d0dcc9d7b28f452739efd1fe
+  data.tar.gz: 130cbc6ceddbc5d867eff3f567f087e7345c6adb28231388a89a38cda72db9eb
 SHA512:
-  metadata.gz: 4a4d50b204fa662b9661d258686c22296c07bb88fd5cd2cbebfdbfef3455ca1385877ac66af5c3d6d22de6bfb6b43ae12ce74e21a9b5b279fa640b1042002a0b
-  data.tar.gz: 795e29ab7736f0e40fd3bc39e055146935427a13a4a2e10cbbee5b9ddd6980c164cc9d187131d43895a602b0c44a2d950e4cb3c87af3ed7f9959bd1f8dfbb6fa
+  metadata.gz: b7d1272b4540c082ff3ab0b2d7fdc79d8b1fd502f9f37a219d58fd185512daf2f3b77ddfa2a61ccf335fe994a8b141b31ab48012bf6674df8986b69bca1bce99
+  data.tar.gz: 710683faceb05f8402016a76b4991358928a6ab62cde698d5a88c02f5c842d9a4f109ab443ff1170dce83f5d187075622c398746cba3f8647ee8732eafab0eaf

data/README.md

@@ -262,6 +262,45 @@ end
 
 All data-layer actions are taken via `#find` or `#save!`, with exceptions such as `ActiveRecord::RecordNotFound`, `ActiveRecord::RecordInvalid` or generalised SCIM exceptions handled by various superclasses. For a real Rails example of this, see the [test suite's controllers](https://github.com/RIPAGlobal/scimitar/tree/main/spec/apps/dummy/app/controllers) which are invoked via its [routing declarations](https://github.com/RIPAGlobal/scimitar/blob/main/spec/apps/dummy/config/routes.rb).
 
+##### Overriding controller methods
+
+You can overwrite write-based controller methods `#create`, `#update`, `#replace` and `destroy` in your controller subclass, should you wish, wherein a call to `super` is passed a block. The block is invoked with the instance of a new unsaved record for `#create`, the updated record that needs to have its changes saved for `#update` and `#replace` and the record that should be destroyed for `#destroy`. This allows you to do things like applying business logic, default values, extra request-derived data and so-forth before then calling `record.save!`, or using some different method other than `record.destroy!` to discard a record (e.g. you might be using soft-delete, or want to skip all callbacks for some reason via `record.delete`).
+
+* The `#destroy` method just calls `record.destroy!` unless a block is given, with nothing much else to say about it.
+
+* The other methods all establish a database transaction and call through to the _controller's_ protected `#save!` method, passing it the record; it is _this_ method which then either calls `record.save!` or invokes a block. Using the exception-throwing versions of persistence methods is recommended, as there is exception handling within the controller's implementation which rescues things like `ActiveRecord::RecordInvalid` and builds an appropriate SCIM error response when they occur. You can change the list of exceptions handled in this way by overriding protected method `#scimitar_rescuable_exceptions'.
+
+* If you want to override saving behaviour for both new and modified records, overriding `#save!` in your controller subclass, rather than overriding all of `#create`, `#update` and `#replace`, is likely to be the better choice.
+
+* For more information, see the [RDoc output for `Scimitar::ActiveRecordBackedResourcesController`](https://www.rubydoc.info/github/RIPAGlobal/scimitar/main/Scimitar/ActiveRecordBackedResourcesController).
+
+Example:
+
+```ruby
+module Scim
+  class UsersController < Scimitar::ActiveRecordBackedResourcesController
+
+  # Create all new records with some special internal field set to a value
+  # determined by a bespoke-to-your-application mechanism.
+  #
+  def create
+    super do | user |
+      user.some_special_on_creation_field = method_that_calculates_value()
+      user.save!
+    end
+  end
+
+  # Use #discard! rather than #destroy! as an example of soft-delete via the
+  # 'discard' gem - https://rubygems.org/gems/discard.
+  #
+  def destroy
+    super do | user |
+      user.discard!
+    end
+  end
+end
+```
+
 #### Queries & Optimisations
 
 The scope can be optimised to eager load the data exposed by the SCIM interface, i.e.:

data/app/controllers/scimitar/active_record_backed_resources_controller.rb

@@ -60,12 +60,20 @@ module Scimitar
 
     # POST (create)
     #
-    def create
+    # Calls #save! on the new record if no block is given, else invokes the
+    # block, passing it the new ActiveRecord model instance to be saved. It
+    # is up to the block to make any further changes and persist the record.
+    #
+    # Blocks are invoked from within a wrapping database transaction.
+    # ActiveRecord::RecordInvalid exceptions are handled for you, rendering
+    # an appropriate SCIM error.
+    #
+    def create(&block)
       super do |scim_resource|
         self.storage_class().transaction do
           record = self.storage_class().new
           record.from_scim!(scim_hash: scim_resource.as_json())
-          self.save!(record)
+          self.save!(record, &block)
           record_to_scim(record)
         end
       end
@@ -73,12 +81,16 @@ module Scimitar
 
     # PUT (replace)
     #
-    def replace
+    # Calls #save! on the updated record if no block is given, else invokes the
+    # block, passing the updated record which the block must persist, with the
+    # same rules as for #create.
+    #
+    def replace(&block)
       super do |record_id, scim_resource|
         self.storage_class().transaction do
           record = self.find_record(record_id)
           record.from_scim!(scim_hash: scim_resource.as_json())
-          self.save!(record)
+          self.save!(record, &block)
           record_to_scim(record)
         end
       end
@@ -86,12 +98,16 @@ module Scimitar
 
     # PATCH (update)
     #
-    def update
+    # Calls #save! on the updated record if no block is given, else invokes the
+    # block, passing the updated record which the block must persist, with the
+    # same rules as for #create.
+    #
+    def update(&block)
       super do |record_id, patch_hash|
         self.storage_class().transaction do
           record = self.find_record(record_id)
           record.from_scim_patch!(patch_hash: patch_hash)
-          self.save!(record)
+          self.save!(record, &block)
           record_to_scim(record)
         end
       end
@@ -134,6 +150,17 @@ module Scimitar
         raise NotImplementedError
       end
 
+      # Return an Array of exceptions that #save! can rescue and handle with a
+      # SCIM error automatically.
+      #
+      def scimitar_rescuable_exceptions
+        [
+          ActiveRecord::RecordInvalid,
+          ActiveRecord::RecordNotSaved,
+          ActiveRecord::RecordNotUnique,
+        ]
+      end
+
       # Find a record by ID. Subclasses can override this if they need special
       # lookup behaviour.
       #
@@ -173,17 +200,25 @@ module Scimitar
         else
           record.save!
         end
-      rescue ActiveRecord::RecordInvalid => exception
-        handle_invalid_record(exception.record)
+      rescue *self.scimitar_rescuable_exceptions() => exception
+        handle_on_save_exception(record, exception)
       end
 
-      # Deal with validation errors by responding with an appropriate SCIM
-      # error.
+      # Deal with exceptions related to errors upon saving, by responding with
+      # an appropriate SCIM error. This is most effective if the record has
+      # validation errors defined, but falls back to the provided exception's
+      # message otherwise.
       #
-      # +record+:: The record with validation errors.
+      # +record+::    The record that provoked the exception. Mandatory.
+      # +exception+:: The exception that was raised. If omitted, a default of
+      #               'Unknown', in English with no I18n, is used.
       #
-      def handle_invalid_record(record)
-        joined_errors = record.errors.full_messages.join('; ')
+      def handle_on_save_exception(record, exception = RuntimeError.new('Unknown'))
+        details = if record.errors.present?
+          record.errors.full_messages.join('; ')
+        else
+          exception.message
+        end
 
         # https://tools.ietf.org/html/rfc7644#page-12
         #
@@ -193,14 +228,14 @@ module Scimitar
         #   status code 409 (Conflict) with a "scimType" error code of
         #   "uniqueness"
         #
-        if record.errors.any? { | e | e.type == :taken }
+        if exception.is_a?(ActiveRecord::RecordNotUnique) || record.errors.any? { | e | e.type == :taken }
           raise Scimitar::ErrorResponse.new(
             status:   409,
             scimType: 'uniqueness',
-            detail:   joined_errors
+            detail:   "Operation failed due to a uniqueness constraint: #{details}"
           )
         else
-          raise Scimitar::ResourceInvalidError.new(joined_errors)
+          raise Scimitar::ResourceInvalidError.new(details)
         end
       end
 

data/app/controllers/scimitar/application_controller.rb

@@ -139,11 +139,15 @@ module Scimitar
 
       def authenticated?
         result = if Scimitar.engine_configuration.basic_authenticator.present?
-          authenticate_with_http_basic(&Scimitar.engine_configuration.basic_authenticator)
+          authenticate_with_http_basic do |username, password|
+            instance_exec(username, password, &Scimitar.engine_configuration.basic_authenticator)
+          end
         end
 
         result ||= if Scimitar.engine_configuration.token_authenticator.present?
-          authenticate_with_http_token(&Scimitar.engine_configuration.token_authenticator)
+          authenticate_with_http_token do |token, options|
+            instance_exec(token, options, &Scimitar.engine_configuration.token_authenticator)
+          end
         end
 
         return result

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

@@ -7,12 +7,6 @@ module Scimitar
     #
     class Address < Base
       set_schema Scimitar::Schema::Address
-
-      # Returns the JSON representation of an Address.
-      #
-      def as_json(options = {})
-        {'type' => 'work'}.merge(super(options))
-      end
     end
   end
 end

data/app/models/scimitar/resource_invalid_error.rb

@@ -2,7 +2,7 @@ module Scimitar
   class ResourceInvalidError < ErrorResponse
 
     def initialize(error_message)
-      super(status: 400, scimType: 'invalidValue', detail:"Operation failed since record has become invalid: #{error_message}")
+      super(status: 400, scimType: 'invalidValue', detail: "Operation failed since record has become invalid: #{error_message}")
     end
 
   end

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

@@ -952,7 +952,10 @@ module Scimitar
 
                 when 'replace'
                   if path_component == 'root'
-                    altering_hash[path_component].merge!(value)
+                    dot_pathed_value = value.inject({}) do |hash, (k, v)|
+                      hash.deep_merge!(::Scimitar::Support::Utilities.dot_path(k.split('.'), v))
+                    end
+                    altering_hash[path_component].deep_merge!(dot_pathed_value)
                   else
                     altering_hash[path_component] = value
                   end

data/lib/scimitar/support/utilities.rb

@@ -0,0 +1,51 @@
+module Scimitar
+
+  # Namespace containing various chunks of Scimitar support code that don't
+  # logically fit into other areas.
+  #
+  module Support
+
+    # A namespace that contains various stand-alone utility methods which act
+    # as helpers for other parts of the code base, without risking namespace
+    # pollution by e.g. being part of a module loaded into a client class.
+    #
+    module Utilities
+
+      # Takes an array of components that usually come from a dotted path such
+      # as <tt>foo.bar.baz</tt>, along with a value that is found at the end of
+      # that path, then converts it into a nested Hash with each level of the
+      # Hash corresponding to a step along the path.
+      #
+      # This was written to help with edge case SCIM uses where (most often, at
+      # least) inbound calls use a dotted notation where nested values are more
+      # commonly accepted; converting to nesting makes it easier for subsequent
+      # processing code, which needs only handle nested Hash data.
+      #
+      # As an example, passing:
+      #
+      #     ['foo', 'bar', 'baz'], 'value'
+      #
+      # ...yields:
+      #
+      #     {'foo' => {'bar' => {'baz' => 'value'}}}
+      #
+      # Parameters:
+      #
+      # +array+:: Array containing path components, usually acquired from a
+      #           string with dot separators and a call to String#split.
+      #
+      # +value+:: The value found at the path indicated by +array+.
+      #
+      # If +array+ is empty, +value+ is returned directly, with no nesting
+      # Hash wrapping it.
+      #
+      def self.dot_path(array, value)
+        return value if array.empty?
+
+        {}.tap do | hash |
+          hash[array.shift()] = self.dot_path(array, value)
+        end
+      end
+    end
+  end
+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.6.1'
+  VERSION = '2.7.0'
 
   # Date for VERSION. If this changes, be sure to re-run "bundle install"
   # or "bundle update".
   #
-  DATE = '2023-11-15'
+  DATE = '2024-01-15'
 
 end

data/lib/scimitar.rb

@@ -1,5 +1,6 @@
 require 'scimitar/version'
 require 'scimitar/support/hash_with_indifferent_case_insensitive_access'
+require 'scimitar/support/utilities'
 require 'scimitar/engine'
 
 module Scimitar

data/spec/apps/dummy/app/controllers/custom_create_mock_users_controller.rb

@@ -0,0 +1,25 @@
+# For tests only - uses custom 'create' implementation which passes a block to
+# Scimitar::ActiveRecordBackedResourcesController#create.
+#
+class CustomCreateMockUsersController < Scimitar::ActiveRecordBackedResourcesController
+
+  OVERRIDDEN_NAME = SecureRandom.uuid
+
+  def create
+    super do | resource |
+      resource.first_name = OVERRIDDEN_NAME
+      resource.save!
+    end
+  end
+
+  protected
+
+    def storage_class
+      MockUser
+    end
+
+    def storage_scope
+      MockUser.all
+    end
+
+end

data/spec/apps/dummy/app/controllers/custom_replace_mock_users_controller.rb

@@ -0,0 +1,25 @@
+# For tests only - uses custom 'replace' implementation which passes a block to
+# Scimitar::ActiveRecordBackedResourcesController#create.
+#
+class CustomReplaceMockUsersController < Scimitar::ActiveRecordBackedResourcesController
+
+  OVERRIDDEN_NAME = SecureRandom.uuid
+
+  def replace
+    super do | resource |
+      resource.first_name = OVERRIDDEN_NAME
+      resource.save!
+    end
+  end
+
+  protected
+
+    def storage_class
+      MockUser
+    end
+
+    def storage_scope
+      MockUser.all
+    end
+
+end

data/spec/apps/dummy/app/controllers/custom_update_mock_users_controller.rb

@@ -0,0 +1,25 @@
+# For tests only - uses custom 'update' implementation which passes a block to
+# Scimitar::ActiveRecordBackedResourcesController#create.
+#
+class CustomUpdateMockUsersController < Scimitar::ActiveRecordBackedResourcesController
+
+  OVERRIDDEN_NAME = SecureRandom.uuid
+
+  def update
+    super do | resource |
+      resource.first_name = OVERRIDDEN_NAME
+      resource.save!
+    end
+  end
+
+  protected
+
+    def storage_class
+      MockUser
+    end
+
+    def storage_scope
+      MockUser.all
+    end
+
+end

data/spec/apps/dummy/config/routes.rb

@@ -17,10 +17,22 @@ Rails.application.routes.draw do
   get    'Groups/:id', to: 'mock_groups#show'
   patch  'Groups/:id', to: 'mock_groups#update'
 
-  # For testing blocks passed to ActiveRecordBackedResourcesController#destroy
+  # For testing blocks passed to ActiveRecordBackedResourcesController#create,
+  # #update, #replace and #destroy.
   #
+  post   'CustomCreateUsers',      to: 'custom_create_mock_users#create'
+  patch  'CustomUpdateUsers/:id',  to: 'custom_update_mock_users#update'
+  put    'CustomReplaceUsers/:id', to: 'custom_replace_mock_users#replace'
   delete 'CustomDestroyUsers/:id', to: 'custom_destroy_mock_users#destroy'
 
+  # Needed because the auto-render of most of the above includes a 'url_for'
+  # call for a 'show' action, so we must include routes (implemented in the
+  # base class) for the "show" endpoint.
+  #
+  get  'CustomCreateUsers/:id',  to: 'custom_create_mock_users#show'
+  get  'CustomUpdateUsers/:id',  to: 'custom_update_mock_users#show'
+  get  'CustomReplaceUsers/:id', to: 'custom_replace_mock_users#show'
+
   # For testing blocks passed to ActiveRecordBackedResourcesController#save!
   #
   post 'CustomSaveUsers',     to: 'custom_save_mock_users#create'

data/spec/controllers/scimitar/application_controller_spec.rb

@@ -107,6 +107,60 @@ RSpec.describe Scimitar::ApplicationController do
     end
   end
 
+  context 'authenticator evaluated within controller context' do
+
+    # Define a controller with a custom instance method 'valid_token'.
+    #
+    controller do
+      def index
+        render json: { 'message' => 'cool, cool!' }, format: :scim
+      end
+
+      def valid_token
+        'B'
+      end
+    end
+
+    # Call the above controller method from the token authenticator Proc,
+    # proving that it was executed in the controller's context.
+    #
+    before do
+      Scimitar.engine_configuration = Scimitar::EngineConfiguration.new(
+        token_authenticator: Proc.new do | token, options |
+          token == self.valid_token()
+        end
+      )
+    end
+
+    it 'renders success when valid creds are given' do
+      request.env['HTTP_AUTHORIZATION'] = 'Bearer B'
+
+      get :index, params: { format: :scim }
+      expect(response).to be_ok
+      expect(JSON.parse(response.body)).to eql({ 'message' => 'cool, cool!' })
+      expect(response.headers['WWW-Authenticate']).to eql('Bearer')
+    end
+
+    it 'renders failure with bad token' do
+      request.env['HTTP_AUTHORIZATION'] = 'Bearer Invalid'
+
+      get :index, params: { format: :scim }
+      expect(response).not_to be_ok
+    end
+
+    it 'renders failure with blank token' do
+      request.env['HTTP_AUTHORIZATION'] = 'Bearer'
+
+      get :index, params: { format: :scim }
+      expect(response).not_to be_ok
+    end
+
+    it 'renders failure with missing header' do
+      get :index, params: { format: :scim }
+      expect(response).not_to be_ok
+    end
+  end
+
   context 'authenticated' do
     controller do
       rescue_from StandardError, with: :handle_resource_not_found

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

@@ -2,8 +2,8 @@ require 'spec_helper'
 
 RSpec.describe Scimitar::ComplexTypes::Address do
   context '#as_json' do
-    it 'assumes a type of "work" as a default' do
-      expect(described_class.new.as_json).to eq('type' => 'work')
+    it 'assumes no defaults' do
+      expect(described_class.new.as_json).to eq({})
     end
 
     it 'allows a custom address type' do
@@ -11,9 +11,8 @@ RSpec.describe Scimitar::ComplexTypes::Address do
     end
 
     it 'shows the set address' do
-      expect(described_class.new(country: 'NZ').as_json).to eq('type' => 'work', 'country' => 'NZ')
+      expect(described_class.new(country: 'NZ').as_json).to eq('country' => 'NZ')
     end
   end
 
 end
-

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

@@ -2717,6 +2717,28 @@ RSpec.describe Scimitar::Resources::Mixin do
             expect(@instance.username).to eql('1234')
           end
 
+          it 'which updates nested values using root syntax' do
+            @instance.update!(first_name: 'Foo', last_name: 'Bar')
+
+            path = 'name.givenName'
+            path = path.upcase if force_upper_case
+
+            patch = {
+              'schemas'    => ['urn:ietf:params:scim:api:messages:2.0:PatchOp'],
+              'Operations' => [
+                {
+                  'op'    => 'replace',
+                  'value' => {
+                    path => 'Baz'
+                  }
+                }
+              ]
+            }
+
+            @instance.from_scim_patch!(patch_hash: patch)
+            expect(@instance.first_name).to eql('Baz')
+          end
+
           it 'which updates nested values' do
             @instance.update!(first_name: 'Foo', last_name: 'Bar')
 

data/spec/requests/active_record_backed_resources_controller_spec.rb

@@ -13,9 +13,9 @@ RSpec.describe Scimitar::ActiveRecordBackedResourcesController do
     lmt = Time.parse("2023-01-09 14:25:00 +1300")
     ids = 3.times.map { SecureRandom.uuid }.sort()
 
-    @u1 = MockUser.create(primary_key: ids.shift(), username: '1', first_name: 'Foo', last_name: 'Ark', home_email_address: 'home_1@test.com', scim_uid: '001', created_at: lmt, updated_at: lmt + 1)
-    @u2 = MockUser.create(primary_key: ids.shift(), username: '2', first_name: 'Foo', last_name: 'Bar', home_email_address: 'home_2@test.com', scim_uid: '002', created_at: lmt, updated_at: lmt + 2)
-    @u3 = MockUser.create(primary_key: ids.shift(), username: '3', first_name: 'Foo',                   home_email_address: 'home_3@test.com', scim_uid: '003', created_at: lmt, updated_at: lmt + 3)
+    @u1 = MockUser.create!(primary_key: ids.shift(), username: '1', first_name: 'Foo', last_name: 'Ark', home_email_address: 'home_1@test.com', scim_uid: '001', created_at: lmt, updated_at: lmt + 1)
+    @u2 = MockUser.create!(primary_key: ids.shift(), username: '2', first_name: 'Foo', last_name: 'Bar', home_email_address: 'home_2@test.com', scim_uid: '002', created_at: lmt, updated_at: lmt + 2)
+    @u3 = MockUser.create!(primary_key: ids.shift(), username: '3', first_name: 'Foo',                   home_email_address: 'home_3@test.com', scim_uid: '003', created_at: lmt, updated_at: lmt + 3)
 
     @g1 = MockGroup.create!(display_name: 'Group 1')
     @g2 = MockGroup.create!(display_name: 'Group 2')
@@ -315,7 +315,12 @@ RSpec.describe Scimitar::ActiveRecordBackedResourcesController do
           attributes = { userName: '4' } # Minimum required by schema
           attributes = spec_helper_hupcase(attributes) if force_upper_case
 
+          # Prove that certain known pathways are called; can then unit test
+          # those if need be and be sure that this covers #create actions.
+          #
           expect_any_instance_of(MockUsersController).to receive(:create).once.and_call_original
+          expect_any_instance_of(MockUsersController).to receive(:save! ).once.and_call_original
+
           expect {
             post "/Users", params: attributes.merge(format: :scim)
           }.to change { MockUser.count }.by(1)
@@ -442,23 +447,75 @@ RSpec.describe Scimitar::ActiveRecordBackedResourcesController do
       expect(result['detail']).to include('is reserved')
     end
 
-    it 'invokes a block if given one' do
-      mock_before = MockUser.all.to_a
-      attributes = { userName: '5' } # Minimum required by schema
+    context 'with a block' do
+      it 'invokes the block' do
+        mock_before = MockUser.all.to_a
 
-      expect_any_instance_of(CustomSaveMockUsersController).to receive(:create).once.and_call_original
-      expect {
-        post "/CustomSaveUsers", params: attributes.merge(format: :scim)
-      }.to change { MockUser.count }.by(1)
+        expect_any_instance_of(CustomCreateMockUsersController).to receive(:create).once.and_call_original
+        expect {
+          post "/CustomCreateUsers", params: {
+            format:   :scim,
+            userName: '4' # Minimum required by schema
+          }
+        }.to change { MockUser.count }.by(1)
 
-      mock_after = MockUser.all.to_a
-      new_mock = (mock_after - mock_before).first
+        mock_after = MockUser.all.to_a
+        new_mock = (mock_after - mock_before).first
 
-      expect(response.status                 ).to eql(201)
-      expect(response.headers['Content-Type']).to eql('application/scim+json; charset=utf-8')
+        expect(response.status                 ).to eql(201)
+        expect(response.headers['Content-Type']).to eql('application/scim+json; charset=utf-8')
 
-      expect(new_mock.username).to eql(CustomSaveMockUsersController::CUSTOM_SAVE_BLOCK_USERNAME_INDICATOR)
-    end
+        result = JSON.parse(response.body)
+
+        expect(result['id']).to eql(new_mock.id.to_s)
+        expect(result['meta']['resourceType']).to eql('User')
+        expect(new_mock.first_name).to eql(CustomCreateMockUsersController::OVERRIDDEN_NAME)
+      end
+
+      it 'returns 409 for duplicates (by Rails validation)' do
+        existing_user = MockUser.create!(
+          username:           '4',
+          first_name:         'Will Be Overridden',
+          last_name:          'Baz',
+          home_email_address: 'random@test.com',
+          scim_uid:           '999'
+        )
+
+        expect_any_instance_of(CustomCreateMockUsersController).to receive(:create).once.and_call_original
+        expect {
+          post "/CustomCreateUsers", params: {
+            format:   :scim,
+            userName: '4' # Already exists
+          }
+        }.to_not change { MockUser.count }
+
+        expect(response.status                 ).to eql(409)
+        expect(response.headers['Content-Type']).to eql('application/scim+json; charset=utf-8')
+
+        result = JSON.parse(response.body)
+
+        expect(result['scimType']).to eql('uniqueness')
+        expect(result['detail']).to include('already been taken')
+      end
+
+      it 'notes Rails validation failures' do
+        expect_any_instance_of(CustomCreateMockUsersController).to receive(:create).once.and_call_original
+        expect {
+          post "/CustomCreateUsers", params: {
+            format:   :scim,
+            userName: MockUser::INVALID_USERNAME
+          }
+        }.to_not change { MockUser.count }
+
+        expect(response.status                 ).to eql(400)
+        expect(response.headers['Content-Type']).to eql('application/scim+json; charset=utf-8')
+
+        result = JSON.parse(response.body)
+
+        expect(result['scimType']).to eql('invalidValue')
+        expect(result['detail']).to include('is reserved')
+      end
+    end # "context 'with a block' do"
   end # "context '#create' do"
 
   # ===========================================================================
@@ -469,7 +526,11 @@ RSpec.describe Scimitar::ActiveRecordBackedResourcesController do
         attributes = { userName: '4' }  # Minimum required by schema
         attributes = spec_helper_hupcase(attributes) if force_upper_case
 
+        # Prove that certain known pathways are called; can then unit test
+        # those if need be and be sure that this covers #replace actions.
+        #
         expect_any_instance_of(MockUsersController).to receive(:replace).once.and_call_original
+        expect_any_instance_of(MockUsersController).to receive(:save! ).once.and_call_original
         expect {
           put "/Users/#{@u2.primary_key}", params: attributes.merge(format: :scim)
         }.to_not change { MockUser.count }
@@ -525,7 +586,7 @@ RSpec.describe Scimitar::ActiveRecordBackedResourcesController do
 
     it 'notes Rails validation failures' do
       expect {
-        post "/Users", params: {
+        put "/Users/#{@u2.primary_key}", params: {
           format: :scim,
           userName: MockUser::INVALID_USERNAME
         }
@@ -562,6 +623,58 @@ RSpec.describe Scimitar::ActiveRecordBackedResourcesController do
 
       expect(result['status']).to eql('404')
     end
+
+    context 'with a block' do
+      it 'invokes the block' do
+        attributes = { userName: '4' }  # Minimum required by schema
+
+        expect_any_instance_of(CustomReplaceMockUsersController).to receive(:replace).once.and_call_original
+        expect {
+          put "/CustomReplaceUsers/#{@u2.primary_key}", params: {
+            format:   :scim,
+            userName: '4'
+          }
+        }.to_not change { MockUser.count }
+
+        expect(response.status                 ).to eql(200)
+        expect(response.headers['Content-Type']).to eql('application/scim+json; charset=utf-8')
+
+        result = JSON.parse(response.body)
+
+        expect(result['id']).to eql(@u2.primary_key.to_s)
+        expect(result['meta']['resourceType']).to eql('User')
+
+        @u2.reload
+
+        expect(@u2.username  ).to eql('4')
+        expect(@u2.first_name).to eql(CustomReplaceMockUsersController::OVERRIDDEN_NAME)
+      end
+
+      it 'notes Rails validation failures' do
+        expect_any_instance_of(CustomReplaceMockUsersController).to receive(:replace).once.and_call_original
+        expect {
+          put "/CustomReplaceUsers/#{@u2.primary_key}", params: {
+            format:   :scim,
+            userName: MockUser::INVALID_USERNAME
+          }
+        }.to_not change { MockUser.count }
+
+        expect(response.status                 ).to eql(400)
+        expect(response.headers['Content-Type']).to eql('application/scim+json; charset=utf-8')
+
+        result = JSON.parse(response.body)
+
+        expect(result['scimType']).to eql('invalidValue')
+        expect(result['detail']).to include('is reserved')
+
+        @u2.reload
+
+        expect(@u2.username).to eql('2')
+        expect(@u2.first_name).to eql('Foo')
+        expect(@u2.last_name).to eql('Bar')
+        expect(@u2.home_email_address).to eql('home_2@test.com')
+      end
+    end # "context 'with a block' do"
   end # "context '#replace' do"
 
   # ===========================================================================
@@ -586,7 +699,12 @@ RSpec.describe Scimitar::ActiveRecordBackedResourcesController do
 
         payload = spec_helper_hupcase(payload) if force_upper_case
 
+        # Prove that certain known pathways are called; can then unit test
+        # those if need be and be sure that this covers #update actions.
+        #
         expect_any_instance_of(MockUsersController).to receive(:update).once.and_call_original
+        expect_any_instance_of(MockUsersController).to receive(:save! ).once.and_call_original
+
         expect {
           patch "/Users/#{@u2.primary_key}", params: payload.merge(format: :scim)
         }.to_not change { MockUser.count }
@@ -916,12 +1034,178 @@ RSpec.describe Scimitar::ActiveRecordBackedResourcesController do
         it_behaves_like 'a user remover'
       end # context 'and using a Salesforce variant payload' do
     end # "context 'when removing users from groups' do"
+
+    context 'with a block' do
+      it 'invokes the block' do
+        payload = {
+          format: :scim,
+          Operations: [
+            {
+              op: 'add',
+              path: 'userName',
+              value: '4'
+            },
+            {
+              op: 'replace',
+              path: 'emails[type eq "work"]',
+              value: { type: 'work', value: 'work_4@test.com' }
+            }
+          ]
+        }
+
+        expect_any_instance_of(CustomUpdateMockUsersController).to receive(:update).once.and_call_original
+        expect {
+          patch "/CustomUpdateUsers/#{@u2.primary_key}", params: payload
+        }.to_not change { MockUser.count }
+
+        expect(response.status                 ).to eql(200)
+        expect(response.headers['Content-Type']).to eql('application/scim+json; charset=utf-8')
+
+        result = JSON.parse(response.body)
+
+        expect(result['id']).to eql(@u2.primary_key.to_s)
+        expect(result['meta']['resourceType']).to eql('User')
+
+        @u2.reload
+
+        expect(@u2.username          ).to eql('4')
+        expect(@u2.first_name        ).to eql(CustomUpdateMockUsersController::OVERRIDDEN_NAME)
+        expect(@u2.work_email_address).to eql('work_4@test.com')
+      end
+
+      it 'notes Rails validation failures' do
+        expect_any_instance_of(CustomUpdateMockUsersController).to receive(:update).once.and_call_original
+        expect {
+          patch "/CustomUpdateUsers/#{@u2.primary_key}", params: {
+            format: :scim,
+            Operations: [
+              {
+                op: 'add',
+                path: 'userName',
+                value: MockUser::INVALID_USERNAME
+              }
+            ]
+          }
+        }.to_not change { MockUser.count }
+
+        expect(response.status                 ).to eql(400)
+        expect(response.headers['Content-Type']).to eql('application/scim+json; charset=utf-8')
+
+        result = JSON.parse(response.body)
+
+        expect(result['scimType']).to eql('invalidValue')
+        expect(result['detail']).to include('is reserved')
+
+        @u2.reload
+
+        expect(@u2.username).to eql('2')
+        expect(@u2.first_name).to eql('Foo')
+        expect(@u2.last_name).to eql('Bar')
+        expect(@u2.home_email_address).to eql('home_2@test.com')
+      end
+    end # "context 'with a block' do"
   end # "context '#update' do"
 
+  # ===========================================================================
+  # In-passing parts of tests above show that #create, #replace and #update all
+  # route through #save!, so now add some unit tests for that and for exception
+  # handling overrides invoked via #save!.
+  # ===========================================================================
+
+  context 'overriding #save!' do
+    it 'invokes a block if given one' do
+      mock_before = MockUser.all.to_a
+      attributes = { userName: '5' } # Minimum required by schema
+
+      expect_any_instance_of(CustomSaveMockUsersController).to receive(:create).once.and_call_original
+      expect {
+        post "/CustomSaveUsers", params: attributes.merge(format: :scim)
+      }.to change { MockUser.count }.by(1)
+
+      mock_after = MockUser.all.to_a
+      new_mock = (mock_after - mock_before).first
+
+      expect(response.status                 ).to eql(201)
+      expect(response.headers['Content-Type']).to eql('application/scim+json; charset=utf-8')
+
+      expect(new_mock.username).to eql(CustomSaveMockUsersController::CUSTOM_SAVE_BLOCK_USERNAME_INDICATOR)
+    end
+  end # "context 'overriding #save!' do
+
+  context 'custom on-save exceptions' do
+    MockUsersController.new.send(:scimitar_rescuable_exceptions).each do | exception_class |
+      it "handles out-of-box exception #{exception_class}" do
+        expect_any_instance_of(MockUsersController).to receive(:create).once.and_call_original
+        expect_any_instance_of(MockUsersController).to receive(:save! ).once.and_call_original
+
+        expect_any_instance_of(MockUser).to receive(:save!).once { raise exception_class }
+
+        expect {
+          post "/Users", params: { format: :scim, userName: SecureRandom.uuid }
+        }.to_not change { MockUser.count }
+
+        expected_status, expected_prefix = if exception_class == ActiveRecord::RecordNotUnique
+          [409, 'Operation failed due to a uniqueness constraint: ']
+        else
+          [400, 'Operation failed since record has become invalid: ']
+        end
+
+        expect(response.status                 ).to eql(expected_status)
+        expect(response.headers['Content-Type']).to eql('application/scim+json; charset=utf-8')
+
+        result = JSON.parse(response.body)
+
+        # Check basic SCIM error rendering - good enough given other tests
+        # elsewhere. Exact message varies by exception.
+        #
+        expect(result['detail']).to start_with(expected_prefix)
+      end
+    end
+
+    it 'handles custom exceptions' do
+      exception_class = RuntimeError # (for testing only; usually, this would provoke a 500 response)
+
+      expect_any_instance_of(MockUsersController).to receive(:create).once.and_call_original
+      expect_any_instance_of(MockUsersController).to receive(:save! ).once.and_call_original
+
+      expect_any_instance_of(MockUsersController).to receive(:scimitar_rescuable_exceptions).once { [ exception_class ] }
+      expect_any_instance_of(MockUser           ).to receive(:save!                        ).once { raise exception_class }
+
+      expect {
+        post "/Users", params: { format: :scim, userName: SecureRandom.uuid }
+      }.to_not change { MockUser.count }
+
+      expect(response.status                 ).to eql(400)
+      expect(response.headers['Content-Type']).to eql('application/scim+json; charset=utf-8')
+
+      result = JSON.parse(response.body)
+
+      expect(result['detail']).to start_with('Operation failed since record has become invalid: ')
+    end
+
+    it 'reports other exceptions as 500s' do
+      expect_any_instance_of(MockUsersController).to receive(:create).once.and_call_original
+      expect_any_instance_of(MockUsersController).to receive(:save! ).once.and_call_original
+
+      expect_any_instance_of(MockUser).to receive(:save!).once { raise RuntimeError }
+
+      expect {
+        post "/Users", params: { format: :scim, userName: SecureRandom.uuid }
+      }.to_not change { MockUser.count }
+
+      expect(response.status                 ).to eql(500)
+      expect(response.headers['Content-Type']).to eql('application/scim+json; charset=utf-8')
+
+      result = JSON.parse(response.body)
+
+      expect(result['detail']).to eql('RuntimeError')
+    end
+  end
+
   # ===========================================================================
 
   context '#destroy' do
-    it 'deletes an item if given no blok' do
+    it 'deletes an item if given no block' do
       expect_any_instance_of(MockUsersController).to receive(:destroy).once.and_call_original
       expect_any_instance_of(MockUser).to receive(:destroy!).once.and_call_original
       expect {

data/spec/spec_helper.rb

@@ -30,14 +30,22 @@ RSpec.configure do | config |
   config.disable_monkey_patching!
   config.infer_spec_type_from_file_location!
   config.filter_rails_from_backtrace!
+  config.raise_errors_for_deprecations!
 
   config.color                      = true
   config.tty                        = true
   config.order                      = :random
-  config.fixture_path               = "#{::Rails.root}/spec/fixtures"
+  config.fixture_paths              = ["#{::Rails.root}/spec/fixtures"]
   config.use_transactional_fixtures = true
 
   Kernel.srand config.seed
+
+  config.around :each do | example |
+    original_engine_configuration = Scimitar.instance_variable_get('@engine_configuration')
+    example.run()
+  ensure
+    Scimitar.instance_variable_set('@engine_configuration', original_engine_configuration)
+  end
 end
 
 # ============================================================================

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: scimitar
 version: !ruby/object:Gem::Version
-  version: 2.6.1
+  version: 2.7.0
 platform: ruby
 authors:
 - RIPA Global
@@ -9,7 +9,7 @@ authors:
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2023-11-15 00:00:00.000000000 Z
+date: 2024-01-15 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -25,34 +25,48 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '7.0'
+- !ruby/object:Gem::Dependency
+  name: nokogiri
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 1.15.5
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 1.15.5
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '13.0'
+        version: '13.1'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '13.0'
+        version: '13.1'
 - !ruby/object:Gem::Dependency
   name: pg
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.4'
+        version: '1.5'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.4'
+        version: '1.5'
 - !ruby/object:Gem::Dependency
   name: simplecov-rcov
   requirement: !ruby/object:Gem::Requirement
@@ -73,28 +87,28 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '6.5'
+        version: '6.6'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '6.5'
+        version: '6.6'
 - !ruby/object:Gem::Dependency
   name: rspec-rails
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '6.0'
+        version: '6.1'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '6.0'
+        version: '6.1'
 - !ruby/object:Gem::Dependency
   name: byebug
   requirement: !ruby/object:Gem::Requirement
@@ -195,10 +209,14 @@ files:
 - lib/scimitar.rb
 - lib/scimitar/engine.rb
 - lib/scimitar/support/hash_with_indifferent_case_insensitive_access.rb
+- lib/scimitar/support/utilities.rb
 - lib/scimitar/version.rb
+- spec/apps/dummy/app/controllers/custom_create_mock_users_controller.rb
 - spec/apps/dummy/app/controllers/custom_destroy_mock_users_controller.rb
+- spec/apps/dummy/app/controllers/custom_replace_mock_users_controller.rb
 - spec/apps/dummy/app/controllers/custom_request_verifiers_controller.rb
 - spec/apps/dummy/app/controllers/custom_save_mock_users_controller.rb
+- spec/apps/dummy/app/controllers/custom_update_mock_users_controller.rb
 - spec/apps/dummy/app/controllers/mock_groups_controller.rb
 - spec/apps/dummy/app/controllers/mock_users_controller.rb
 - spec/apps/dummy/app/models/mock_group.rb
@@ -263,14 +281,17 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.4.10
+rubygems_version: 3.5.3
 signing_key:
 specification_version: 4
 summary: SCIM v2 for Rails
 test_files:
+- spec/apps/dummy/app/controllers/custom_create_mock_users_controller.rb
 - spec/apps/dummy/app/controllers/custom_destroy_mock_users_controller.rb
+- spec/apps/dummy/app/controllers/custom_replace_mock_users_controller.rb
 - spec/apps/dummy/app/controllers/custom_request_verifiers_controller.rb
 - spec/apps/dummy/app/controllers/custom_save_mock_users_controller.rb
+- spec/apps/dummy/app/controllers/custom_update_mock_users_controller.rb
 - spec/apps/dummy/app/controllers/mock_groups_controller.rb
 - spec/apps/dummy/app/controllers/mock_users_controller.rb
 - spec/apps/dummy/app/models/mock_group.rb