scimitar 2.14.0 → 2.15.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c5f63ca5b1572be0cb53a95a47280099713fd32be8f5650396a0db6a0c92550e
-  data.tar.gz: 2f1f2a7ec7a6877607875f6b86e7b9859ae9124f71d295541847940dd31c8b1f
+  metadata.gz: 7c705a0369ccfd6204da2dd2a0e5a17a15f2fa658703218404d7556c1568a891
+  data.tar.gz: cd8ab1a8fc432533a6a0e4ee6045f20677c9164dfd330c416a68b5728b58947f
 SHA512:
-  metadata.gz: '08626642f4b3e9dd29a6141c72bea784ab094ec197d9f3b9278957a59bfe230f4ef7ec84d52b1584127af647809351607bc01ef408d7269cc39dcf1f17180d49'
-  data.tar.gz: 53845ba684f54f8e2e90e696b769aadfe803809fa3004fa35f779794d6e04bfa034ee231847382591cdc5600cc7544bbad4c959e2031c0271e67e5632d431f6c
+  metadata.gz: 11846119f8df609b6f75f95a436a78e2ca9dceed1a9d236cd08c89df052e45677efcee573943feaee719b7fff6f648bd13622a47d32f493bb69d3b8a58415363
+  data.tar.gz: 32bdc2ba6b4613c498ed988bfb2a4397c26f1d0196341f071b52d4bdb13065b9a658654dba1666bbb75c6a185afa924d6b6aa60d2f4ef9784cc9af6df4395623

data/LICENSE.txt

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2024 RIPA Global
+Copyright (c) 2026 RIPA Global c/o Andrew Hodgkinson
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

data/Rakefile

@@ -1,7 +1,6 @@
 require 'rake'
 require 'rspec/core/rake_task'
 require 'rdoc/task'
-require 'sdoc'
 
 RSpec::Core::RakeTask.new(:default) do | t |
 end
@@ -12,5 +11,5 @@ Rake::RDocTask.new do | rd |
   rd.title     = 'Scimitar'
   rd.main      = 'README.md'
   rd.rdoc_dir  = 'docs/rdoc'
-  rd.generator = 'sdoc'
+  rd.generator = 'rdoc'
 end

data/app/controllers/scimitar/active_record_backed_resources_controller.rb

@@ -36,11 +36,17 @@ module Scimitar
 
       pagination_info = scim_pagination_info(query.count())
 
-      page_of_results = query
-        .order(@id_column => :asc)
-        .offset(pagination_info.offset)
-        .limit(pagination_info.limit)
-        .to_a()
+      # SCIM 2.0 RFC 7644: When count=0, return metadata only (no Resources).
+      # This avoids an unnecessary database query for record data.
+      page_of_results = if pagination_info.limit == 0
+        []
+      else
+        query
+          .order(@id_column => :asc)
+          .offset(pagination_info.offset)
+          .limit(pagination_info.limit)
+          .to_a()
+      end
 
       super(pagination_info, page_of_results) do | record |
         record_to_scim(record)

data/app/controllers/scimitar/application_controller.rb

@@ -48,7 +48,7 @@ module Scimitar
       #
       def handle_scim_error(error_response, exception = error_response)
         unless Scimitar.engine_configuration.exception_reporter.nil?
-          Scimitar.engine_configuration.exception_reporter.call(exception)
+          instance_exec(exception, &Scimitar.engine_configuration.exception_reporter)
         end
 
         render json: error_response, status: error_response.status

data/app/models/scimitar/engine_configuration.rb

@@ -16,6 +16,7 @@ module Scimitar
       :application_controller_mixin,
       :exception_reporter,
       :optional_value_fields_required,
+      :render_mapped_nil_values_in_response,
       :schema_list_from_attribute_mappings,
     )
 
@@ -25,8 +26,9 @@ module Scimitar
       # Set defaults that may be overridden by the initializer.
       #
       defaults = {
-        optional_value_fields_required:      true,
-        schema_list_from_attribute_mappings: []
+        optional_value_fields_required:       true,
+        render_mapped_nil_values_in_response: true,
+        schema_list_from_attribute_mappings:  []
       }
 
       super(defaults.merge(attributes))

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

@@ -15,9 +15,12 @@ module Scimitar
 
       # Set a limit (page size) value.
       #
-      # +value+:: Integer value held in a String. Must be >= 1.
+      # +value+:: Integer value held in a String. Must be >= 0.
+      #
+      # Per SCIM 2.0 RFC 7644 Section 3.4.2.4: "A value of '0' indicates that
+      # no resource results are to be returned except for 'totalResults'."
       #
-      # Raises exceptions if given non-numeric, zero or negative input.
+      # Raises exceptions if given non-numeric or negative input.
       #
       def limit=(value)
         value = value&.to_s
@@ -25,7 +28,7 @@ module Scimitar
 
         validate_numericality(value)
         input = value.to_i
-        raise if input < 1
+        raise if input < 0
         @limit = input
       end
 

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

@@ -612,7 +612,13 @@ module Scimitar
                   end
                 end
 
-                result.compact! if include_attributes.any?
+                if (
+                  include_attributes.any? or
+                  ! Scimitar.engine_configuration.render_mapped_nil_values_in_response
+                )
+                  result.compact!
+                end
+
                 result
 
               when Array # Static or dynamic mapping against lists in data source

data/config/initializers/scimitar.rb

@@ -102,7 +102,9 @@ Rails.application.config.to_prepare do # (required for >= Rails 7 / Zeitwerk)
     # 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:
+    # The Proc is called via 'instance_exec' in the controller context, so you
+    # have access to things like 'request', 'params' and 'action_name'. For
+    # example, a minimal sentry.io reporter might do this:
     #
     #     exception_reporter: Proc.new do | exception |
     #       Sentry.capture_exception(exception)
@@ -119,6 +121,12 @@ Rails.application.config.to_prepare do # (required for >= Rails 7 / Zeitwerk)
     #
     #     optional_value_fields_required: false
 
+    # When rendering responses, +nil+ values can either still be included via
+    # the attributes map with a JSON value of +null+, or omitted. By default,
+    # all attributes in your map are returned in responses.
+    #
+    #     render_mapped_nil_values_in_response: false
+
     # The SCIM standard `/Schemas` endpoint lists, by default, all known schema
     # definitions with the mutabilty (read-write, read-only, write-only) state
     # described by those definitions, and includes all defined attributes. For

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.14.0'
+  VERSION = '2.15.0'
 
   # Date for VERSION. If this changes, be sure to re-run "bundle install"
   # or "bundle update".
   #
-  DATE = '2025-11-14'
+  DATE = '2026-03-06'
 
 end

data/spec/controllers/scimitar/application_controller_spec.rb

@@ -352,8 +352,9 @@ RSpec.describe Scimitar::ApplicationController do
     context 'with an exception reporter' do
       around :each do | example |
         original_configuration = Scimitar.engine_configuration.exception_reporter
+        exceptions = @exceptions = []
         Scimitar.engine_configuration.exception_reporter = Proc.new do | exception |
-          @exception = exception
+          exceptions << exception
         end
         example.run()
       ensure
@@ -364,8 +365,8 @@ RSpec.describe Scimitar::ApplicationController do
         it 'is invoked' do
           get :index, params: { format: :scim }
 
-          expect(@exception).to be_a(RuntimeError)
-          expect(@exception.message).to eql('Bang')
+          expect(@exceptions.first).to be_a(RuntimeError)
+          expect(@exceptions.first.message).to eql('Bang')
         end
       end
 
@@ -379,8 +380,8 @@ RSpec.describe Scimitar::ApplicationController do
         it 'is invoked' do
           get :index, params: { format: :scim }
 
-          expect(@exception).to be_a(ActiveRecord::RecordNotFound)
-          expect(@exception.message).to eql('42')
+          expect(@exceptions.first).to be_a(ActiveRecord::RecordNotFound)
+          expect(@exceptions.first.message).to eql('42')
         end
       end
 
@@ -398,8 +399,8 @@ RSpec.describe Scimitar::ApplicationController do
         it 'is invoked' do
           get :index, params: { format: :scim }
 
-          expect(@exception).to be_a(ActionDispatch::Http::Parameters::ParseError)
-          expect(@exception.message).to eql('Hello')
+          expect(@exceptions.first).to be_a(ActionDispatch::Http::Parameters::ParseError)
+          expect(@exceptions.first.message).to eql('Hello')
         end
       end
 
@@ -412,8 +413,8 @@ RSpec.describe Scimitar::ApplicationController 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.')
+          expect(@exceptions.first).to be_a(Scimitar::ErrorResponse)
+          expect(@exceptions.first.message).to eql('Only application/scim+json type is accepted.')
         end
       end
 
@@ -423,16 +424,16 @@ RSpec.describe Scimitar::ApplicationController do
           request.headers['User-Agent'  ] = 'Google-Auto-Provisioning'
           get :index
 
-          expect(@exception).to be_a(RuntimeError)
-          expect(@exception.message).to eql('Bang')
+          expect(@exceptions.first).to be_a(RuntimeError)
+          expect(@exceptions.first.message).to eql('Bang')
         end
 
         it 'is invoked early for unrecognised agents' do
           request.headers['Content-Type'] = 'application/json'
           get :index
 
-          expect(@exception).to be_a(Scimitar::ErrorResponse)
-          expect(@exception.message).to eql('Only application/scim+json type is accepted.')
+          expect(@exceptions.first).to be_a(Scimitar::ErrorResponse)
+          expect(@exceptions.first.message).to eql('Only application/scim+json type is accepted.')
         end
       end # "context 'and with Google SCIM calls' do"
 
@@ -459,8 +460,8 @@ RSpec.describe Scimitar::ApplicationController do
             request.headers['Content-Type'] = 'application/json+success'
             get :index
 
-            expect(@exception).to be_a(RuntimeError)
-            expect(@exception.message).to eql('Bang')
+            expect(@exceptions.first).to be_a(RuntimeError)
+            expect(@exceptions.first.message).to eql('Bang')
 
             expect(request.format == :scim).to eql(true)
             expect(request.headers['CONTENT_TYPE']).to eql('application/scim+json')
@@ -472,8 +473,8 @@ RSpec.describe Scimitar::ApplicationController do
             request.headers['Content-Type'] = 'application/json+preserve'
             get :index
 
-            expect(@exception).to be_a(RuntimeError)
-            expect(@exception.message).to eql('Bang')
+            expect(@exceptions.first).to be_a(RuntimeError)
+            expect(@exceptions.first.message).to eql('Bang')
 
             expect(request.format == :html).to eql(true)
             expect(request.headers['CONTENT_TYPE']).to eql('application/json+preserve')
@@ -485,11 +486,28 @@ RSpec.describe Scimitar::ApplicationController do
             request.headers['Content-Type'] = 'application/json+fail'
             get :index
 
-            expect(@exception).to be_a(Scimitar::ErrorResponse)
-            expect(@exception.message).to eql('Only application/scim+json type is accepted.')
+            expect(@exceptions.first).to be_a(Scimitar::ErrorResponse)
+            expect(@exceptions.first.message).to eql('Only application/scim+json type is accepted.')
           end
         end # "context 'returning "fail"' do"
       end # "context 'and with a custom request sanitizer' do"
+
+      context 'evaluated in controller context' do
+        it 'has access to controller methods like request and params' do
+          reported_request_method = nil
+          reported_params = nil
+          Scimitar.engine_configuration.exception_reporter = Proc.new do | exception |
+            reported_request_method = request.method
+            reported_params = params
+          end
+
+          get :index, params: { format: :scim, foo: 'bar' }
+
+          expect(reported_request_method).to eql('GET')
+          expect(reported_params['format']).to eql('scim')
+          expect(reported_params['foo']).to eql('bar')
+        end
+      end
     end # "context 'exception reporter' do"
   end # "context 'error handling' do"
 end

data/spec/models/scimitar/lists/count_spec.rb

@@ -34,12 +34,17 @@ RSpec.describe Scimitar::Lists::Count do
         expect { @instance.limit = 'A' }.to raise_error(RuntimeError)
       end
 
-      it 'complains about attempts to set zero values' do
-        expect { @instance.limit = '0' }.to raise_error(RuntimeError)
+      it 'allows count=0 per SCIM 2.0 specification (RFC 7644)' do
+        expect { @instance.limit = '0' }.to_not raise_error
+        expect(@instance.limit).to eql(0)
       end
 
-      it 'complains about attempts to set zero values' do
+      it 'allows count=0 as integer' do
+        expect { @instance.limit = 0 }.to_not raise_error
+        expect(@instance.limit).to eql(0)
+      end
 
+      it 'complains about attempts to set negative values' do
         expect { @instance.limit = '-10' }.to raise_error(RuntimeError)
       end
     end # "context 'on-read error checking' do"

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

@@ -267,7 +267,7 @@ RSpec.describe Scimitar::Resources::Mixin do
           instance.first_name         = 'Foo'
           instance.last_name          = 'Bar'
           instance.work_email_address = 'foo.bar@test.com'
-          instance.home_email_address = nil
+          instance.home_email_address = 'foo.bar@example.com'
           instance.work_phone_number  = '+642201234567'
           instance.organization       = 'SOMEORG'
 
@@ -299,6 +299,49 @@ RSpec.describe Scimitar::Resources::Mixin do
             'urn:ietf:params:scim:schemas:extension:manager:1.0:User' => {},
           })
         end
+
+        it 'hides "nil" value attributes' do
+          uuid                        = SecureRandom.uuid
+
+          instance                    = MockUser.new
+          instance.primary_key        = uuid
+          instance.scim_uid           = 'AA02984'
+          instance.username           = nil
+          instance.password           = 'correcthorsebatterystaple'
+          instance.first_name         = nil
+          instance.last_name          = 'Bar'
+          instance.work_email_address = 'foo.bar@test.com'
+          instance.home_email_address = 'foo.bar@example.com'
+          instance.work_phone_number  = '+642201234567'
+          instance.organization       = 'SOMEORG'
+
+          g1 = MockGroup.create!(display_name: 'Group 1')
+          g2 = MockGroup.create!(display_name: 'Group 2')
+          g3 = MockGroup.create!(display_name: 'Group 3')
+
+          g1.mock_users << instance
+          g3.mock_users << instance
+
+          scim = instance.to_scim(location: "https://test.com/mock_users/#{uuid}", include_attributes: %w[id userName name groups.display groups.value organization])
+          json = scim.to_json()
+          hash = JSON.parse(json)
+
+          expect(hash).to eql({
+            'id'          => uuid,
+            'name'        => {'familyName'=>'Bar'},
+            'groups'      => [{'display'=>g1.display_name, 'value'=>g1.id.to_s}, {'display'=>g3.display_name, 'value'=>g3.id.to_s}],
+            'meta'        => {'location'=>"https://test.com/mock_users/#{uuid}", 'resourceType'=>'User'},
+            'schemas'     => [
+              'urn:ietf:params:scim:schemas:core:2.0:User',
+              'urn:ietf:params:scim:schemas:extension:enterprise:2.0:User',
+              'urn:ietf:params:scim:schemas:extension:manager:1.0:User',
+            ],
+            'urn:ietf:params:scim:schemas:extension:enterprise:2.0:User' => {
+              'organization' => 'SOMEORG',
+            },
+            'urn:ietf:params:scim:schemas:extension:manager:1.0:User' => {},
+          })
+        end
       end # "context 'with list of requested attributes' do"
 
       context 'with a UUID, renamed primary key column' do
@@ -332,7 +375,7 @@ RSpec.describe Scimitar::Resources::Mixin do
             'userName'    => 'foo',
             'name'        => {'givenName'=>'Foo', 'familyName'=>'Bar'},
             'active'      => true,
-            'emails'      => [{'type'=>'work', 'primary'=>true, 'value'=>'foo.bar@test.com'}, {"primary"=>false, "type"=>"home", "value"=>nil}],
+            'emails'      => [{'type'=>'work', 'primary'=>true, 'value'=>'foo.bar@test.com'}, {'primary'=>false, 'type'=>'home', 'value'=>nil}],
             'phoneNumbers'=> [{'type'=>'work', 'primary'=>false, 'value'=>'+642201234567'}],
             'id'          => uuid,
             'externalId'  => 'AA02984',
@@ -353,6 +396,71 @@ RSpec.describe Scimitar::Resources::Mixin do
             },
           })
         end
+
+        context 'and when configured to omit "nil" values in the response' do
+          around :each do | example |
+            original_configuration = Scimitar.engine_configuration.render_mapped_nil_values_in_response
+            Scimitar.engine_configuration.render_mapped_nil_values_in_response = false
+            example.run()
+          ensure
+            Scimitar.engine_configuration.render_mapped_nil_values_in_response = original_configuration
+          end
+
+          it 'omits "nil" values as expected' do
+            uuid                        = SecureRandom.uuid
+
+            instance                    = MockUser.new
+            instance.primary_key        = uuid
+            instance.scim_uid           = 'AA02984'
+            instance.username           = 'foo'
+            instance.password           = 'correcthorsebatterystaple'
+            instance.first_name         = nil
+            instance.last_name          = 'Bar'
+            instance.work_email_address = 'foo.bar@test.com'
+            instance.home_email_address = nil
+            instance.work_phone_number  = '+642201234567'
+            instance.organization       = 'SOMEORG'
+
+            g1 = MockGroup.create!(display_name: 'Group 1')
+            g2 = MockGroup.create!(display_name: 'Group 2')
+            g3 = MockGroup.create!(display_name: 'Group 3')
+
+            g1.mock_users << instance
+            g3.mock_users << instance
+
+            scim = instance.to_scim(location: "https://test.com/mock_users/#{uuid}")
+            json = scim.to_json()
+            hash = JSON.parse(json)
+
+            # Note currently limited implementation for things like static maps,
+            # where part of the returned value is included; in this case, the
+            # "primary" value is "false" for e-mail of type "home", so the
+            # structure for that *does* appear in the output array even though
+            # the source dynamic data field from the NockUser instance is "nil".
+            #
+            expect(hash).to eql({
+              'userName'    => 'foo',
+              'name'        => {'familyName'=>'Bar'},
+              'active'      => true,
+              'emails'      => [{'type'=>'work', 'primary'=>true, 'value'=>'foo.bar@test.com'}, {'primary' => false, 'type' => 'home'}],
+              'phoneNumbers'=> [{'type'=>'work', 'primary'=>false, 'value'=>'+642201234567'}],
+              'id'          => uuid,
+              'externalId'  => 'AA02984',
+              'groups'      => [{'display'=>g1.display_name, 'value'=>g1.id.to_s}, {'display'=>g3.display_name, 'value'=>g3.id.to_s}],
+              'meta'        => {'location'=>"https://test.com/mock_users/#{uuid}", 'resourceType'=>'User'},
+              'schemas'     => [
+                'urn:ietf:params:scim:schemas:core:2.0:User',
+                'urn:ietf:params:scim:schemas:extension:enterprise:2.0:User',
+                'urn:ietf:params:scim:schemas:extension:manager:1.0:User',
+              ],
+              'urn:ietf:params:scim:schemas:extension:enterprise:2.0:User' => {
+                'organization' => 'SOMEORG',
+                'primaryEmail' => instance.work_email_address,
+              },
+              'urn:ietf:params:scim:schemas:extension:manager:1.0:User' => {}
+            })
+          end
+        end # "context 'and when configured to omit "nil" values in the response'" do"
       end # "context 'with a UUID, renamed primary key column' do"
 
       context 'with an integer, conventionally named primary key column' do

data/spec/requests/active_record_backed_resources_controller_spec.rb

@@ -292,6 +292,92 @@ RSpec.describe Scimitar::ActiveRecordBackedResourcesController do
         usernames = result['Resources'].map { |resource| resource['userName'] }
         expect(usernames).to match_array(['2', '3'])
       end
+
+      # SCIM 2.0 RFC 7644 Section 3.4.2.4: count=0 support
+      context 'with count=0' do
+        it 'returns 200 OK' do
+          get '/Users', params: {
+            format: :scim,
+            count: 0
+          }
+
+          expect(response.status).to eql(200)
+          expect(response.headers['Content-Type']).to eql('application/scim+json; charset=utf-8')
+        end
+
+        it 'returns totalResults with actual count' do
+          get '/Users', params: {
+            format: :scim,
+            count: 0
+          }
+
+          result = JSON.parse(response.body)
+          expect(result['totalResults']).to eql(3)
+        end
+
+        it 'returns itemsPerPage as 0' do
+          get '/Users', params: {
+            format: :scim,
+            count: 0
+          }
+
+          result = JSON.parse(response.body)
+          expect(result['itemsPerPage']).to eql(0)
+        end
+
+        it 'returns empty Resources array' do
+          get '/Users', params: {
+            format: :scim,
+            count: 0
+          }
+
+          result = JSON.parse(response.body)
+          expect(result['Resources']).to eql([])
+        end
+
+        it 'respects startIndex parameter' do
+          get '/Users', params: {
+            format: :scim,
+            count: 0,
+            startIndex: 5
+          }
+
+          result = JSON.parse(response.body)
+          expect(result['startIndex']).to eql(5)
+        end
+
+        it 'applies filters when calculating totalResults' do
+          get '/Users', params: {
+            format: :scim,
+            count: 0,
+            filter: 'name.familyName eq "Bar"'
+          }
+
+          result = JSON.parse(response.body)
+          expect(result['totalResults']).to eql(1)
+          expect(result['Resources']).to eql([])
+        end
+
+        it 'does not query for records (performance optimization)' do
+          # We should get the count but not fetch records
+          query_double = instance_double(ActiveRecord::Relation)
+          allow(MockUser).to receive(:all).and_return(query_double)
+          allow(query_double).to receive(:count).and_return(3)
+
+          # Should NOT call order, offset, limit, or to_a when count=0
+          expect(query_double).not_to receive(:order)
+          expect(query_double).not_to receive(:offset)
+          expect(query_double).not_to receive(:limit)
+          expect(query_double).not_to receive(:to_a)
+
+          get '/Users', params: {
+            format: :scim,
+            count: 0
+          }
+
+          expect(response.status).to eql(200)
+        end
+      end # "context 'with count=0' do"
     end # "context 'with items' do"
 
     context 'with bad calls' do

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: scimitar
 version: !ruby/object:Gem::Version
-  version: 2.14.0
+  version: 2.15.0
 platform: ruby
 authors:
-- RIPA Global
 - Andrew David Hodgkinson
+- RIPA Global
 bindir: bin
 cert_chain: []
-date: 2025-11-14 00:00:00.000000000 Z
+date: 2026-03-06 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -86,14 +86,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '6.15'
+        version: '7.2'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '6.15'
+        version: '7.2'
 - !ruby/object:Gem::Dependency
   name: warden
   requirement: !ruby/object:Gem::Requirement
@@ -296,7 +296,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.2
+rubygems_version: 4.0.3
 specification_version: 4
 summary: SCIM v2 for Rails
 test_files: