audiences 3.1.0 → 3.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 298fbad100f5af1295e605b5f1d82f92fd0a807b6278c96c4515dd4e82da124c
-  data.tar.gz: 4c08ece17beeb6944ee5f503780d3d7a18a1e55d95d63eeb4ba4c70841bdfa96
+  metadata.gz: ca6dae8a08e2e2703e139555772d0a1143cb8511b0cd4c5820d6f3f2c3c91581
+  data.tar.gz: 6327e89cd3a1970bb8cffb02ebaef89b5e71d48dfb8d6321758aa3159484cec1
 SHA512:
-  metadata.gz: 98dc2b2dcdc121b15c92c494c5d0dfec7a41a431b21908b2ce09319abf39058ae3743e7aa59b2ef88eeeb3f3cadb2ce759a66d078d5672a6b7515f4c05390e69
-  data.tar.gz: 5c227cdbef5540de3b592591fb3bdf9d251c95773c88e59fd4d94d7bc6c094c58e71fe1bf956dc00018d94979de3733859105195b78a9873c0e9d5c827934334
+  metadata.gz: 390dff4c5768d1a7e7d6745e5f4af302cdd6c6c9f55bb675edd246408bd59daa4221ded9878360fc03ecf078f20a5fba9ae23d5401c5f3fc956863e4950e2679
+  data.tar.gz: b669cd8ff6d4ccc7a1b3c70b4c761b888b84c13ee6f4ff7c89498cf864e8d010a662992049f56173b4eca844777402728167c78c67ef58cf23b9fae28dc7459c

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,25 @@
-# Unreleased
+# Version 3.2.1 (2026-10-22)
+
+**Compatibility:**
+- Restore Rails 7.1 support so applications can adopt the pluggable read source while transitioning to Rails 7.2. Audiences development remains on Rails 8.1, and Rails 7.1 is covered by the compatibility test matrix.
+
+# 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.1"
 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.1
 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.1'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '6.0'
+        version: '7.1'
 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:
   - - ">="