audiences 3.1.0 → 3.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 298fbad100f5af1295e605b5f1d82f92fd0a807b6278c96c4515dd4e82da124c
-  data.tar.gz: 4c08ece17beeb6944ee5f503780d3d7a18a1e55d95d63eeb4ba4c70841bdfa96
+  metadata.gz: 772d8496fc779d86cc53c50e02bea87dfaeac00483d13a2bf301415160d8254d
+  data.tar.gz: 31d137e6332e906dba696ab61fba1ec7c35362b6b663c123ae1a87192e9cf3c5
 SHA512:
-  metadata.gz: 98dc2b2dcdc121b15c92c494c5d0dfec7a41a431b21908b2ce09319abf39058ae3743e7aa59b2ef88eeeb3f3cadb2ce759a66d078d5672a6b7515f4c05390e69
-  data.tar.gz: 5c227cdbef5540de3b592591fb3bdf9d251c95773c88e59fd4d94d7bc6c094c58e71fe1bf956dc00018d94979de3733859105195b78a9873c0e9d5c827934334
+  metadata.gz: fc0c07c9cd9a8a672b38d4a6be95e504a55ddc7d96a7644c24cc076bc72e2eab4e8462ef2b28e4e243ddadfca29016ea436be19cf6d298dd2d5725c18a64ed59
+  data.tar.gz: da35f519039d7932891b25925095f31cd4655f27ffd1274575b074f14084577d95f81fafd3196e6f0e83fd0b9646ab09d072717264ab27625a954e050fa0d2c1

data/app/controllers/audiences/scim_proxy_controller.rb

@@ -2,23 +2,17 @@
 
 module Audiences
   class ScimProxyController < ApplicationController
+    # Reads resources through the configured read source. The source is
+    # swappable via Audiences.config.read_source (defaults to the legacy
+    # source that reads Audiences' own projection), so the controller stays
+    # agnostic to where the data comes from.
     def get
-      resources = scope.search(params[:query])
-                       .offset(params[:startIndex])
-                       .limit(params[:count])
-
-      render json: resources
-    end
-
-  private
-
-    def scope
-      if params[:scim_path].eql?("Users")
-        Audiences::ExternalUser.instance_exec(&Audiences.default_users_scope)
-      else
-        Audiences::Group.where(resource_type: params[:scim_path])
-                        .instance_exec(&Audiences.default_groups_scope)
-      end
+      render json: Audiences.read_source.fetch(
+        resource_type: params[:scim_path],
+        query: params[:query],
+        start_index: params[:startIndex],
+        count: params[:count]
+      )
     end
   end
 end

data/app/models/audiences/users_search.rb

@@ -27,14 +27,12 @@ module Audiences
   private
 
     def result
-      @result ||= @scope.where("#{data_attribute_query} LIKE ?", "%#{@query}%")
-    end
-
-    def data_attribute_query
-      case @scope.connection.adapter_name
-      when "PostgreSQL" then "CAST(data AS TEXT)"
-      else "CAST(data AS CHAR)"
-      end
+      sql = if @scope.connection.adapter_name == "PostgreSQL"
+              "CAST(data AS TEXT) LIKE ?"
+            else
+              "CAST(data AS CHAR) LIKE ?"
+            end
+      @result ||= @scope.where(sql, "%#{@query}%")
     end
   end
 end

data/docs/CHANGELOG.md

@@ -1,4 +1,20 @@
-# Unreleased
+# Version 3.2.0 (2026-10-21)
+
+**Breaking Changes:**
+- Require Rails 7.2 or newer and Ruby 3.1 or newer. Rails 6.1, 7.0, and 7.1 are no longer supported. [#567](https://github.com/powerhome/audiences/pull/567)
+
+**Improvements:**
+- Add `Audiences.config.read_source` and the `Audiences.read_source` accessor so applications can supply a custom source for `GET /scim(/*scim_path)` through a `fetch(resource_type:, query:, start_index:, count:)` interface. [#565](https://github.com/powerhome/audiences/pull/565)
+- Default to `Audiences::ReadSources::Legacy`, preserving local user/group reads, configured scopes, search, pagination, and JSON serialization. Context endpoints and audience calculations continue to use the local projection.
+- Document read-source configuration, reload-safe initialization, the request/response contract, and scope requirements.
+
+**Development:**
+- Update the development bundle to Rails 8.1 and cover Rails 7.2, 8.0, and 8.1 with both MySQL and PostgreSQL in CI. Refresh development and appraisal dependencies. [#567](https://github.com/powerhome/audiences/pull/567)
+
+# Version 3.1.0 (2026-09-23)
+
+**Development:**
+- Update the dummy application's Playbook UI dependency from a prerelease to the released 16.11.0 version. [#562](https://github.com/powerhome/audiences/pull/562)
 
 # Version 3.0.0 (2026-06-18)
 

data/docs/README.md

@@ -4,6 +4,8 @@
 
 ## Installation
 
+Requires Ruby 3.1 or newer and Rails 7.2 or newer. Rails versions may impose a higher Ruby requirement; the Rails 8.1 development bundle requires Ruby 3.2 or newer.
+
 Add this line to your application's Gemfile:
 
 ```ruby
@@ -42,7 +44,97 @@ For more details, refer to [editor_helper](../lib/audiences/editor_helper.rb).
 
 ### Configuring Audiences
 
-### Adding Audiences to a Model
+#### Read Source
+
+The read source backs the resource endpoint, `GET /scim(/*scim_path)`. `ScimProxyController#get` renders whatever the configured source returns:
+
+```ruby
+render json: Audiences.read_source.fetch(
+  resource_type: params[:scim_path],
+  query: params[:query],
+  start_index: params[:startIndex],
+  count: params[:count]
+)
+```
+
+`Audiences.config.read_source` defaults to `Audiences::ReadSources::Legacy`, which reads Audiences' own `ExternalUser` and `Group` projection. Replacing it with any object that satisfies the `#fetch` contract below lets reads come from another store without Audiences depending on that store.
+
+That covers only this endpoint. The context endpoints (`GET /:key` and `GET /:key/users`) and audience calculation keep reading the local projection no matter what the read source does.
+
+Assign a replacement from an initializer:
+
+```ruby
+Audiences.configure do |config|
+  config.read_source = MyReadSource.new
+end
+```
+
+When the implementation is an autoloaded constant, assign it inside a `to_prepare` block so each reload picks up the new class. Keep the block inside `configure` so `config` stays in scope:
+
+```ruby
+Audiences.configure do |config|
+  Rails.application.config.to_prepare do
+    config.read_source = MyReadSource.new
+  end
+end
+```
+
+##### The `#fetch` contract
+
+```ruby
+def fetch(resource_type:, query:, start_index:, count:)
+```
+
+All four arguments come straight from request params with no casting or defaulting, so each one is a `String` or `nil`.
+
+- `resource_type` is the wildcard path segment: `"Users"`, `"Groups"`, `"Departments"`, and so on. The segment is optional in the route, so `GET /scim` passes `nil`.
+- `query` is a substring to match against the display name. `nil` applies no filter.
+- `start_index` is an offset and `count` is a limit, both as strings such as `"2"`. `nil` means no restriction, so omitting `count` returns the whole catalogue. A source doing arithmetic on either has to call `to_i` first.
+
+##### The return contract
+
+Return a collection `render json:` can serialize: an `ActiveRecord::Relation`, serialized through each record's `as_json`, or an array of hashes rendered as given.
+
+Every resource type except `"Users"` returns elements of this shape, where `id` is the SCIM id rather than the primary key:
+
+```json
+{ "id": "<scim_id>", "externalId": "<external_id>", "displayName": "<display_name>" }
+```
+
+A `"Users"` element is the stored SCIM data plus these keys, derived from the user's group memberships:
+
+```json
+{
+  "groups": [{ "value": "<group scim_id>", "display": "<group display_name>" }],
+  "title": "<Titles group display name>",
+  "urn:ietf:params:scim:schemas:extension:authservice:2.0:User": {
+    "role": "<Roles group display name>",
+    "department": "<Departments group display name>",
+    "territory": "<Territories group display name>",
+    "territoryAbbr": "<territory_abbreviations lookup>"
+  }
+}
+```
+
+That payload is then filtered to the keys in `exposed_user_attributes`, which holds string keys and defaults to `id`, `externalId`, `displayName`, and `photos`. The filter drops any configured key the payload lacks, so listing `title`, `groups`, or the extension URN only works if the source emits them. Legacy builds all of this in `ExternalUser#as_scim`.
+
+##### Scopes
+
+Legacy applies the configured scopes inside `#fetch`. The controller does not:
+
+```ruby
+if resource_type == "Users"
+  ExternalUser.instance_exec(&Audiences.default_users_scope)
+else
+  Group.where(resource_type: resource_type).instance_exec(&Audiences.default_groups_scope)
+end
+```
+
+Both default to `-> { active }`. A replacement source has to apply them itself; skipping them serves inactive records and bypasses whatever membership restriction the application configured.
+
+Each proc is `instance_exec`'d against whatever relation the calling code holds, and there is one `default_users_scope` for the whole gem — the context endpoints always run it against `ExternalUser`. A proc may therefore only call scopes that exist on every model it reaches, and a source backed by another model needs equivalent scopes defined there.
+
+#### Adding Audiences to a Model
 
 A model object can contain multiple audience contexts using the `has_audience` module helper, which is added to ActiveRecord automatically when configured:
 
@@ -64,7 +156,7 @@ class Survey < ApplicationRecord
 end
 ```
 
-### Listening to Audience Changes
+#### Listening to Audience Changes
 
 Audiences allows your app to keep up with mutable groups of people. To react to audience changes, subscribe to audiences related to a certain owner type and handle changes through a block:
 
@@ -97,21 +189,10 @@ See a working example in our dummy app:
 - [Job class](../spec/dummy/app/jobs/update_memberships_job.rb)
 - [Example owning model](../spec/dummy/app/models/example_owner.rb)
 
-### SCIM Resource Attributes
-
-Configure which attributes are requested from the SCIM backend for each resource type. `Audiences` includes `id`, `externalId`, and `displayName` by default in every resource type. It also requests `photos.type` and `photos.value` for users by default. To request additional attributes:
-
-```ruby
-Audiences.configure do |config|
-  config.resource :Users, attributes: ["name" => %w[givenName familyName formatted]]
-  config.resource :Groups, attributes: %w[mfaRequired]
-end
-```
-
 ## Contributing
 
 For more information, see the [development guide](../../docs/development.md).
 
 ## License
 
-This gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+This gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/lib/audiences/configuration.rb

@@ -79,6 +79,24 @@ module Audiences
     ->(*) { active }
   end
 
+  # The source that backs the read endpoint (ScimProxyController#get).
+  #
+  # Defaults to Audiences::ReadSources::Legacy, which reads Audiences' own
+  # projection (ExternalUser / Group). Applications can inject an alternative
+  # source (e.g. one backed by an external store) as long as it responds to
+  # `#fetch(resource_type:, query:, start_index:, count:)` and returns records
+  # renderable as the client-facing contract. The controller never references
+  # the source's backing models directly, so the read source is swappable
+  # without coupling Audiences to any particular provider.
+  #
+  # I.e.:
+  #
+  #   Audiences.configure do |config|
+  #     config.read_source = MyExternalReadSource.new
+  #   end
+  #
+  config_accessor(:read_source) { Audiences::ReadSources::Legacy.new }
+
   # These are the user attributes that will be exposed in the audiences endpoints.
   # They're required by the UI to display the user information.
   #

data/lib/audiences/read_sources/legacy.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Audiences
+  module ReadSources
+    # Default read source.
+    #
+    # Reads Audiences' own projection (ExternalUser / Group), preserving the exact
+    # scoping, search and pagination behavior the read endpoint has always had.
+    # Records are returned as-is so the controller's `render json:` uses each
+    # model's `as_json` to produce the client-facing contract.
+    class Legacy
+      def fetch(resource_type:, query:, start_index:, count:)
+        scope(resource_type)
+          .search(query)
+          .offset(start_index)
+          .limit(count)
+      end
+
+    private
+
+      def scope(resource_type)
+        if resource_type == "Users"
+          ExternalUser.instance_exec(&Audiences.default_users_scope)
+        else
+          Group.where(resource_type: resource_type).instance_exec(&Audiences.default_groups_scope)
+        end
+      end
+    end
+  end
+end

data/lib/audiences/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Audiences
-  VERSION = "3.1.0"
+  VERSION = "3.2.0"
 end

data/lib/audiences.rb

@@ -12,6 +12,10 @@ module Audiences
   autoload :Integrations, "audiences/integrations"
   autoload :VERSION, "audiences/version"
 
+  module ReadSources
+    autoload :Legacy, "audiences/read_sources/legacy"
+  end
+
 module_function
 
   # Updates the given context

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: audiences
 version: !ruby/object:Gem::Version
-  version: 3.1.0
+  version: 3.2.0
 platform: ruby
 authors:
 - Carlos Palhares
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-09-23 00:00:00.000000000 Z
+date: 2026-10-22 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: aether_observatory
@@ -30,14 +30,14 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '6.0'
+        version: '7.2'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '6.0'
+        version: '7.2'
 description: Audiences notify the Rails app when a SCIM backend updates a user affecting
   matching audiences
 email:
@@ -100,6 +100,7 @@ files:
 - lib/audiences/integrations/upsert_users_observer.rb
 - lib/audiences/model.rb
 - lib/audiences/notifications.rb
+- lib/audiences/read_sources/legacy.rb
 - lib/audiences/version.rb
 - lib/tasks/audiences_tasks.rake
 homepage: https://github.com/powerhome/audiences
@@ -108,7 +109,7 @@ licenses:
 metadata:
   homepage_uri: https://github.com/powerhome/audiences
   source_code_uri: https://github.com/powerhome/audiences
-  changelog_uri: https://github.com/powerhome/audiences/blob/main/packages/audiences/docs/CHANGELOG.md
+  changelog_uri: https://github.com/powerhome/audiences/blob/main/audiences/docs/CHANGELOG.md
   rubygems_mfa_required: 'true'
 post_install_message:
 rdoc_options: []
@@ -118,7 +119,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '2.7'
+      version: '3.1'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="