audiences 3.2.1 → 3.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: ca6dae8a08e2e2703e139555772d0a1143cb8511b0cd4c5820d6f3f2c3c91581
4
- data.tar.gz: 6327e89cd3a1970bb8cffb02ebaef89b5e71d48dfb8d6321758aa3159484cec1
3
+ metadata.gz: 3de12c53ff70290a3ff0815a1510f3a5458f422e2accfc027e19d8a985bff4bf
4
+ data.tar.gz: 77b45aea62041440bf14b9d0be64c368e461cf2b865f1f9846629f1510c4cd6a
5
5
  SHA512:
6
- metadata.gz: 390dff4c5768d1a7e7d6745e5f4af302cdd6c6c9f55bb675edd246408bd59daa4221ded9878360fc03ecf078f20a5fba9ae23d5401c5f3fc956863e4950e2679
7
- data.tar.gz: b669cd8ff6d4ccc7a1b3c70b4c761b888b84c13ee6f4ff7c89498cf864e8d010a662992049f56173b4eca844777402728167c78c67ef58cf23b9fae28dc7459c
6
+ metadata.gz: a947384404366d63ae5e7ebf5d783c430ea80a5a442fc7b47b7beef1d608ea795b0c5f14ce3238c8ebe357189337be259c8ef638bf6478093efe18f3b52d8fb4
7
+ data.tar.gz: a4929071c327e928e8c3d631a6e9846d8f322969d11d68a710ca59f5c8c4682c82e16b292472fdac77fa00fb74846a1d94d416d88b289ef59f0aa724a5aac71c
@@ -2,12 +2,12 @@
2
2
 
3
3
  module Audiences
4
4
  class ScimProxyController < ApplicationController
5
- # Reads resources through the configured read source. The source is
6
- # swappable via Audiences.config.read_source (defaults to the legacy
5
+ # Reads resources through the configured source. The source is
6
+ # swappable via Audiences.config.source (defaults to the legacy
7
7
  # source that reads Audiences' own projection), so the controller stays
8
8
  # agnostic to where the data comes from.
9
9
  def get
10
- render json: Audiences.read_source.fetch(
10
+ render json: Audiences.source.fetch(
11
11
  resource_type: params[:scim_path],
12
12
  query: params[:query],
13
13
  start_index: params[:startIndex],
@@ -14,9 +14,9 @@ module Audiences
14
14
  dependent: :destroy
15
15
 
16
16
  has_many :context_extra_users, class_name: "Audiences::ContextExtraUser"
17
- has_many :extra_users, class_name: "Audiences::ExternalUser",
18
- through: :context_extra_users,
19
- source: :external_user
17
+ has_many :legacy_extra_users, class_name: "Audiences::ExternalUser",
18
+ through: :context_extra_users,
19
+ source: :external_user
20
20
 
21
21
  scope :relevant_to, ->(group) do
22
22
  joins(:criteria).merge(Criterion.relevant_to(group))
@@ -29,18 +29,33 @@ module Audiences
29
29
 
30
30
  after_commit :notify_subscriptions, on: :update
31
31
 
32
- def users
33
- matching_external_users.instance_exec(&Audiences.default_users_scope)
32
+ def users(groups_by_criterion: {})
33
+ matching_external_users(groups_by_criterion).instance_exec(&Audiences.default_users_scope)
34
34
  end
35
35
 
36
36
  delegate :count, to: :users
37
37
 
38
+ # The extra users, inactive ones included, as the source calculates them.
39
+ def extra_users
40
+ Audiences.source.extra_users_of(self)
41
+ end
42
+
43
+ def extra_users=(users)
44
+ self.legacy_extra_users = users
45
+ end
46
+
47
+ def source_user_ids
48
+ context_extra_users.map(&:source_user_id)
49
+ end
50
+
38
51
  def as_json(...)
52
+ groups_by_criterion = criteria.index_with { |criterion| Audiences.source.groups_of(criterion).to_a }
53
+
39
54
  {
40
55
  match_all: match_all,
41
- count: count,
42
- extra_users: extra_users.instance_exec(&Audiences.default_users_scope),
43
- criteria: criteria,
56
+ count: users(groups_by_criterion: groups_by_criterion).count,
57
+ extra_users: Audiences.source.present(extra_users.instance_exec(&Audiences.default_users_scope)),
58
+ criteria: groups_by_criterion.map { |criterion, groups| criterion.as_json(groups: groups) },
44
59
  }.as_json(...)
45
60
  end
46
61
 
@@ -50,16 +65,17 @@ module Audiences
50
65
  Notifications.publish(self)
51
66
  end
52
67
 
53
- def matching_external_users
54
- match_all ? ExternalUser.all : matching_extra_users.or(matching_criteria)
55
- end
68
+ def matching_external_users(groups_by_criterion)
69
+ return Audiences.source.all_users if match_all
56
70
 
57
- def matching_extra_users
58
- ExternalUser.where(id: extra_users.select(:id))
71
+ extra_users.or(matching_criteria(groups_by_criterion))
59
72
  end
60
73
 
61
- def matching_criteria
62
- criteria.any? ? ExternalUser.matching_any(*criteria) : ExternalUser.none
74
+ def matching_criteria(groups_by_criterion)
75
+ criteria = self.criteria.to_a
76
+ return Audiences.source.all_users.none if criteria.empty?
77
+
78
+ criteria.map { |criterion| criterion.matching_users(groups: groups_by_criterion[criterion]) }.reduce(:or)
63
79
  end
64
80
  end
65
81
  end
@@ -4,5 +4,7 @@ module Audiences
4
4
  class ContextExtraUser < ApplicationRecord
5
5
  belongs_to :context
6
6
  belongs_to :external_user
7
+
8
+ before_save { self.source_user_id = external_user.scim_id }
7
9
  end
8
10
  end
@@ -38,15 +38,31 @@ module Audiences
38
38
  end
39
39
  end
40
40
 
41
- def as_json(...)
42
- groups = self.groups.group_by(&:resource_type)
41
+ def as_json(*args, groups: nil, **kwargs)
42
+ source = Audiences.source
43
+ groups ||= source.groups_of(self).to_a
44
+ presented_groups = groups.group_by(&:resource_type).transform_values { |of_type| source.present(of_type) }
43
45
 
44
- { id: id, count: count, groups: groups }.as_json(...)
46
+ { id: id, count: users(groups: groups).count, groups: presented_groups }.as_json(*args, **kwargs)
45
47
  end
46
48
 
47
- def users
48
- Audiences::ExternalUser.matching(self)
49
- .instance_exec(&Audiences.default_users_scope)
49
+ # The users matching the criterion's groups, before the default users scope.
50
+ def matching_users(groups: nil)
51
+ # Load the groups once: checking emptiness and loading separately lets a
52
+ # concurrent criteria update empty the groups in between, and matching
53
+ # no groups would match every user (PR #572).
54
+ groups ||= Audiences.source.groups_of(self).to_a
55
+ return Audiences.source.all_users.none if groups.empty?
56
+
57
+ Audiences.source.users_matching(groups: groups)
58
+ end
59
+
60
+ def users(groups: nil)
61
+ matching_users(groups: groups).instance_exec(&Audiences.default_users_scope)
62
+ end
63
+
64
+ def source_group_ids
65
+ criterion_groups.map(&:source_group_id)
50
66
  end
51
67
 
52
68
  delegate :count, to: :users
@@ -4,5 +4,7 @@ module Audiences
4
4
  class CriterionGroup < ApplicationRecord
5
5
  belongs_to :group
6
6
  belongs_to :criterion
7
+
8
+ before_save { self.source_group_id = group.scim_id }
7
9
  end
8
10
  end
@@ -44,23 +44,6 @@ module Audiences
44
44
  where(scim_id: ids).or(where(user_id: external_ids))
45
45
  end
46
46
 
47
- scope :matching, ->(criterion) do
48
- return none if criterion.groups.empty?
49
-
50
- criterion.groups
51
- .group_by(&:resource_type)
52
- .values
53
- .reduce(self) do |scope, groups|
54
- scope.members_of(groups)
55
- end
56
- end
57
-
58
- scope :matching_any, ->(first, *others) do
59
- others.reduce(matching(first)) do |scope, criterion|
60
- scope.or matching(criterion)
61
- end
62
- end
63
-
64
47
  def picture_urls = [picture_url]
65
48
 
66
49
  def picture_urls=(urls)
@@ -0,0 +1,49 @@
1
+ # frozen_string_literal: true
2
+
3
+ module Audiences
4
+ # Finds the application's identity record for each of a set of users.
5
+ #
6
+ # The users are matched to identities by the keys the source reports
7
+ # (Audiences.source.identity_keys), so the gem never assumes the key is a
8
+ # column of the users themselves.
9
+ class IdentityLookup
10
+ def initialize(identity_class: Audiences.config.identity_class.constantize,
11
+ identity_key: Audiences.config.identity_key,
12
+ source: Audiences.source)
13
+ @identity_class = identity_class
14
+ @identity_key = identity_key
15
+ @source = source
16
+ end
17
+
18
+ # @return [Array<ApplicationRecord, nil>] one identity per user, in the users'
19
+ # order, nil for a user without one
20
+ def identities_of(users)
21
+ keys = keys_of(users)
22
+
23
+ identities_by_key(keys.compact).values_at(*keys)
24
+ end
25
+
26
+ private
27
+
28
+ # The source reports its own values, for example the String "12" from a
29
+ # `user_id` string column, while the identity class holds the key typed, for
30
+ # example the Integer 12. The identities are matched to the keys in Ruby, where
31
+ # "12" and 12 are different hash keys, so each key is cast to the type of the
32
+ # identity's key column. Only lossless casts are accepted: "12abc" and "012"
33
+ # must not match identity 12.
34
+ def keys_of(users)
35
+ type = @identity_class.type_for_attribute(@identity_key.to_s)
36
+
37
+ @source.identity_keys(users).map do |key|
38
+ next if key.nil?
39
+
40
+ cast_key = type.cast(key)
41
+ cast_key if cast_key.to_s == key.to_s
42
+ end
43
+ end
44
+
45
+ def identities_by_key(keys)
46
+ @identity_class.where(@identity_key => keys).index_by { |identity| identity.public_send(@identity_key) }
47
+ end
48
+ end
49
+ end
@@ -4,7 +4,7 @@ module Audiences
4
4
  class UsersSearch
5
5
  DEFAULT_LIMIT = 20
6
6
 
7
- def initialize(query:, limit: nil, offset: 0, scope: ExternalUser)
7
+ def initialize(query:, limit: nil, offset: 0, scope: Audiences.source.all_users)
8
8
  @scope = scope
9
9
  @query = query
10
10
  @limit = limit || DEFAULT_LIMIT
@@ -13,7 +13,7 @@ module Audiences
13
13
 
14
14
  def as_json(...)
15
15
  {
16
- users: users.as_json(...),
16
+ users: Audiences.source.present(users),
17
17
  count: count,
18
18
  }
19
19
  end
@@ -27,12 +27,7 @@ module Audiences
27
27
  private
28
28
 
29
29
  def result
30
- sql = if @scope.connection.adapter_name == "PostgreSQL"
31
- "CAST(data AS TEXT) LIKE ?"
32
- else
33
- "CAST(data AS CHAR) LIKE ?"
34
- end
35
- @result ||= @scope.where(sql, "%#{@query}%")
30
+ @result ||= Audiences.source.search_users(@scope, @query)
36
31
  end
37
32
  end
38
33
  end
@@ -0,0 +1,11 @@
1
+ # frozen_string_literal: true
2
+
3
+ class AddSourceGroupIdToAudiencesCriterionGroups < ActiveRecord::Migration[7.1]
4
+ disable_ddl_transaction!
5
+
6
+ def change
7
+ add_column :audiences_criterion_groups, :source_group_id, :string
8
+ options = connection.adapter_name == "PostgreSQL" ? { algorithm: :concurrently } : {}
9
+ add_index :audiences_criterion_groups, :source_group_id, **options
10
+ end
11
+ end
@@ -0,0 +1,11 @@
1
+ # frozen_string_literal: true
2
+
3
+ class AddSourceUserIdToAudiencesContextExtraUsers < ActiveRecord::Migration[7.1]
4
+ disable_ddl_transaction!
5
+
6
+ def change
7
+ add_column :audiences_context_extra_users, :source_user_id, :string
8
+ options = connection.adapter_name == "PostgreSQL" ? { algorithm: :concurrently } : {}
9
+ add_index :audiences_context_extra_users, :source_user_id, **options
10
+ end
11
+ end
data/docs/CHANGELOG.md CHANGED
@@ -1,3 +1,26 @@
1
+ # Version 3.3.0 (2026-11-13)
2
+
3
+ **Breaking Changes:**
4
+ - Rename `Audiences.config.read_source` to `Audiences.config.source`, the `Audiences.read_source` accessor to `Audiences.source`, and `Audiences::ReadSources::Legacy` to `Audiences::Sources::Legacy`. There is no alias for the old names.
5
+ - Audience calculation, the context endpoints, and the `has_audience` readers now go through `Audiences.source`, not only `GET /scim(/*scim_path)`. A custom adapter has to implement `groups_of`, `users_matching`, `all_users`, `extra_users_of`, `find_users`, `present`, `search_users`, and `identity_keys` as well as `fetch`. `find_users(references)` looks users up by `id` and/or `externalId`; `Sources::Legacy` returns `ExternalUser.from_scim(*references)`.
6
+ - `Context#users` returns the adapter's own records, and Audiences promises no attributes on them (for example, no `user_id`). With the default `Legacy` adapter nothing changes. To get identity keys with any adapter, call `Audiences.source.identity_keys(context.users)`.
7
+ - Remove `ExternalUser.matching` and `ExternalUser.matching_any`. Their behavior moved into `Sources::Legacy#users_matching(groups:)` and `Context`.
8
+ - `Context#extra_users` is now an explicit reader that goes through `Audiences.source`. The association behind it is renamed `legacy_extra_users`; the `extra_users=` writer keeps its name.
9
+
10
+ **Improvements:**
11
+ - Add the nullable string columns `audiences_criterion_groups.source_group_id` and `audiences_context_extra_users.source_user_id`, each with an index. The legacy foreign keys are still written on every save, next to the new columns. The migrations leave existing rows with `NULL` source IDs. Before enabling the replacement adapter for audience calculation, the host application must populate these columns on existing join rows and verify that the IDs resolve to the intended groups and users.
12
+ - `UsersSearch#as_json` renders through `Audiences.source.present`.
13
+ - `UsersSearch.new(query:)` without a `scope:` searches `Audiences.source.all_users` instead of `ExternalUser`.
14
+ - Document the port, the stored references, the scope requirements, and the identity-key rule in the README.
15
+
16
+ **Development:**
17
+ - Add `db-query-matchers` as a development dependency.
18
+
19
+ # Version 3.2.2 (2026-11-04)
20
+
21
+ **Bug Fixes:**
22
+ - Fix a race where a criterion could match every user when a concurrent context update replaced the criteria while the audience was being resolved. `ExternalUser.matching` now loads a criterion's groups once, so a criterion with no groups always matches no one.
23
+
1
24
  # Version 3.2.1 (2026-10-22)
2
25
 
3
26
  **Compatibility:**
data/docs/README.md CHANGED
@@ -4,7 +4,7 @@
4
4
 
5
5
  ## Installation
6
6
 
7
- 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.
7
+ Requires Ruby 3.1 or newer and Rails 7.1 or newer. Rails versions may impose a higher Ruby requirement; the Rails 8.1 development bundle requires Ruby 3.2 or newer.
8
8
 
9
9
  Add this line to your application's Gemfile:
10
10
 
@@ -44,12 +44,12 @@ For more details, refer to [editor_helper](../lib/audiences/editor_helper.rb).
44
44
 
45
45
  ### Configuring Audiences
46
46
 
47
- #### Read Source
47
+ #### Source
48
48
 
49
- The read source backs the resource endpoint, `GET /scim(/*scim_path)`. `ScimProxyController#get` renders whatever the configured source returns:
49
+ `Audiences.source` is the one seam through which Audiences reads users and groups. It backs the resource endpoint (`GET /scim(/*scim_path)`), the context endpoints (`GET /:key` and `GET /:key/users`), audience calculation, and the `has_audience` readers. `ScimProxyController#get` renders whatever `#fetch` returns:
50
50
 
51
51
  ```ruby
52
- render json: Audiences.read_source.fetch(
52
+ render json: Audiences.source.fetch(
53
53
  resource_type: params[:scim_path],
54
54
  query: params[:query],
55
55
  start_index: params[:startIndex],
@@ -57,15 +57,13 @@ render json: Audiences.read_source.fetch(
57
57
  )
58
58
  ```
59
59
 
60
- `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.
61
-
62
- 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.
60
+ `Audiences.config.source` holds the adapter, the object that implements the port below, and `Audiences.source` returns it. It defaults to `Audiences::Sources::Legacy`, which reads Audiences' own `ExternalUser` and `Group` projection. Replacing it with another adapter lets reads come from another store without Audiences depending on that store.
63
61
 
64
62
  Assign a replacement from an initializer:
65
63
 
66
64
  ```ruby
67
65
  Audiences.configure do |config|
68
- config.read_source = MyReadSource.new
66
+ config.source = MySource.new
69
67
  end
70
68
  ```
71
69
 
@@ -74,11 +72,42 @@ When the implementation is an autoloaded constant, assign it inside a `to_prepar
74
72
  ```ruby
75
73
  Audiences.configure do |config|
76
74
  Rails.application.config.to_prepare do
77
- config.read_source = MyReadSource.new
75
+ config.source = MySource.new
78
76
  end
79
77
  end
80
78
  ```
81
79
 
80
+ ##### The port
81
+
82
+ The port is the set of methods Audiences calls on `Audiences.source`. An adapter implements them: `Audiences::Sources::Legacy` is the default adapter, and a host application can supply its own.
83
+
84
+ | Method | Arguments | Returns |
85
+ | --- | --- | --- |
86
+ | `fetch` | `resource_type:`, `query:`, `start_index:`, `count:` (each a `String` or `nil`) | A collection `render json:` can serialize. See the `#fetch` contract below. |
87
+ | `groups_of` | `criterion`, an `Audiences::Criterion` | An `Enumerable` of the criterion's groups. Each group must respond to `resource_type`. |
88
+ | `users_matching` | `groups:`, an `Array` of groups (never empty) | An `ActiveRecord::Relation` of the users who belong to at least one group of each resource type among `groups`. |
89
+ | `all_users` | none | An `ActiveRecord::Relation` of every user. |
90
+ | `extra_users_of` | `context`, an `Audiences::Context` | An `ActiveRecord::Relation` of the context's extra users, inactive ones included. |
91
+ | `find_users` | `references`, an `Array` of `Hash`es with `id` and/or `externalId` (string or symbol keys) | The users matching any reference, as an `ActiveRecord::Relation` where the adapter can. An empty `Array` returns no users. |
92
+ | `present` | `records`, a relation or `Array` of users or groups | An `Array` of `Hash`es in the client contract shape. |
93
+ | `search_users` | `users`, a relation, and `query`, a `String` or `nil` | `users` narrowed by `query`, as a relation. |
94
+ | `identity_keys` | `users`, a relation | An `Array` of identity-key values. |
95
+
96
+ Details an adapter has to follow:
97
+
98
+ - `groups_of` and `extra_users_of` find their records from the stored references (see [Stored references](#stored-references)): `criterion.source_group_ids` and `context.source_user_ids`.
99
+ - `users_matching` receives groups already loaded into an `Array`. Audiences never calls it with no groups; it uses `all_users.none` instead. The relation it returns has no default users scope; Audiences applies that.
100
+ - The stored ids are strings, and the adapter derives `resource_type` itself from its own group records. Audiences stores no resource type for a reference.
101
+ - `present` receives a collection, so an adapter can preload associations for that collection. It may be called multiple times per response: criterion groups are presented separately for each resource type within each criterion. There is no response-wide batching guarantee. The `id` of every element must be an integer or an integer string (`42` or `"42"`). Group elements have `id`, `externalId` and `displayName`. `Legacy` limits user elements to the keys in `exposed_user_attributes`; whether another adapter honors that setting is up to the adapter.
102
+ - `find_users` is a lookup for consumers, for example an endpoint that adds extra users by reference. The adapter matches `id` and `externalId` itself. Audiences does not call it when saving a context.
103
+ - `Audiences.update` reads each `extra_users` entry as `{ "id" => <scim_id>, "externalId" => ... }`, so its payload has to be in the client contract shape. A consumer passes `Audiences.source.present(records)`, not `records.as_json`: for an adapter other than `Legacy`, a record's own `as_json` can put the database primary key in `"id"`.
104
+ - `search_users` must return a relation, because Audiences applies `limit`, `offset` and `count` to the result.
105
+ - `identity_keys` returns exactly one key per user, in the order of the relation it was given, with `nil` for a user that has none. An adapter that removes duplicates, drops `nil` or reorders makes the `has_audience` readers stop lining up with the users, and Audiences cannot cheaply detect that.
106
+
107
+ Audiences applies `Audiences.default_users_scope` during audience calculation and extra-user serialization, not to every relation returned by a source (see [Scopes](#scopes)). It combines the criteria of a context with ActiveRecord's `.or`, so every user relation an adapter returns for one context has to be an `ActiveRecord::Relation` of the same model. `#fetch` applies the configured users and groups scopes itself; no other port method applies the groups scope.
108
+
109
+ Audiences calls the port from `Context#users`, `#count`, `#extra_users` and `#as_json`, from `Criterion#as_json`, from the users search behind `GET /:key/users`, and from the `has_audience` readers.
110
+
82
111
  ##### The `#fetch` contract
83
112
 
84
113
  ```ruby
@@ -89,11 +118,11 @@ All four arguments come straight from request params with no casting or defaulti
89
118
 
90
119
  - `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`.
91
120
  - `query` is a substring to match against the display name. `nil` applies no filter.
92
- - `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.
121
+ - `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. An adapter doing arithmetic on either has to call `to_i` first.
93
122
 
94
- ##### The return contract
123
+ ##### The return contract (`#fetch` and `#present`)
95
124
 
96
- 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.
125
+ `#fetch` returns a collection `render json:` can serialize: an `ActiveRecord::Relation`, serialized through each record's `as_json`, or an array of hashes rendered as given. `#present` returns the same element shapes, always as an `Array` of `Hash`es.
97
126
 
98
127
  Every resource type except `"Users"` returns elements of this shape, where `id` is the SCIM id rather than the primary key:
99
128
 
@@ -116,7 +145,7 @@ A `"Users"` element is the stored SCIM data plus these keys, derived from the us
116
145
  }
117
146
  ```
118
147
 
119
- 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`.
148
+ 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 adapter emits them. Legacy builds all of this in `ExternalUser#as_scim`.
120
149
 
121
150
  ##### Scopes
122
151
 
@@ -130,9 +159,30 @@ else
130
159
  end
131
160
  ```
132
161
 
133
- 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.
162
+ Both default to `-> { active }`. A replacement adapter's `#fetch` has to apply them itself; skipping them serves inactive records and bypasses whatever membership restriction the application configured.
163
+
164
+ What an adapter has to support:
134
165
 
135
- 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.
166
+ - **Users scope.** `Context#users` and `Criterion#users` apply `default_users_scope`, as do their counts. `Context#as_json` also applies it when serializing extra users. The `Context#extra_users` reader itself remains unscoped, including inactive users. The adapter therefore returns `all_users`, `users_matching` and `extra_users_of` without applying this scope. The default is `-> { active }`, which calls `active` on the adapter's user model. Either define `active` on that model, or set `default_users_scope` to a proc the model supports, such as `-> { all }`. In `#fetch`, the adapter applies the users scope itself.
167
+ - **Search scope.** The context users endpoints pass an already-scoped relation to `UsersSearch`. `UsersSearch` does not add `default_users_scope`: it searches the supplied `scope:`, or `Audiences.source.all_users` when no scope is supplied. `search_users` must narrow that relation, not replace it with a broader one.
168
+ - **Groups scope.** The adapter's `#fetch` applies `default_groups_scope` itself. Outside `#fetch`, Audiences does not apply it; `groups_of` returns groups with no scope applied.
169
+
170
+ Each proc is `instance_exec`'d against whatever relation the calling code holds, and there is one `default_users_scope` for the whole gem. A proc may therefore only call scopes that exist on every model it reaches, and an adapter backed by another model needs equivalent scopes defined there.
171
+
172
+ ##### Stored references
173
+
174
+ Saving a context stores which groups and extra users it refers to, in two nullable string columns, each with a plain index and no foreign key:
175
+
176
+ | Column | Holds |
177
+ | --- | --- |
178
+ | `audiences_criterion_groups.source_group_id` | The id of a criterion's group, as a string. |
179
+ | `audiences_context_extra_users.source_user_id` | The id of an extra user, as a string. |
180
+
181
+ They sit beside the legacy foreign keys (`group_id` and `external_user_id`), which are still written on every save. A `before_save` callback copies the legacy record's `scim_id` into the new column, so an adapter has to be able to find its own records by that `scim_id` value, as a string. Existing join rows hold `NULL` when the columns are added; the gem's migrations do not backfill them.
182
+
183
+ Before switching audience calculation to the replacement source, the host application must populate `source_group_id` and `source_user_id` on existing join rows and verify that those IDs resolve to the intended groups and users.
184
+
185
+ Saving a context (`Audiences.update`) still resolves each picked group and user in Audiences' own tables (`Group` and `ExternalUser`), whatever the adapter. A host therefore keeps those tables filled until a later release replaces this lookup with one through the adapter.
136
186
 
137
187
  #### Adding Audiences to a Model
138
188
 
@@ -147,6 +197,8 @@ end
147
197
 
148
198
  The `identity_class` represents the SCIM user within the app domain, and the `identity_key` maps directly to the SCIM User's `externalId`.
149
199
 
200
+ `Context#users` returns the adapter's own records, and Audiences promises no attributes on them (for example, no `user_id`). The default `Legacy` adapter returns `ExternalUser` records, which have `user_id`, but a replacement adapter's records may not. To get identity keys, call `Audiences.source.identity_keys(context.users)`; that is the supported way, and it works with any adapter.
201
+
150
202
  Once configured, add audience contexts to a model:
151
203
 
152
204
  ```ruby
@@ -79,23 +79,25 @@ module Audiences
79
79
  ->(*) { active }
80
80
  end
81
81
 
82
- # The source that backs the read endpoint (ScimProxyController#get).
82
+ # The source Audiences reads users and groups through: the read endpoint
83
+ # (ScimProxyController#get), the context endpoints, audience calculation and
84
+ # the has_audience readers.
83
85
  #
84
- # Defaults to Audiences::ReadSources::Legacy, which reads Audiences' own
86
+ # Defaults to Audiences::Sources::Legacy, which reads Audiences' own
85
87
  # projection (ExternalUser / Group). Applications can inject an alternative
86
- # source (e.g. one backed by an external store) as long as it responds to
87
- # `#fetch(resource_type:, query:, start_index:, count:)` and returns records
88
- # renderable as the client-facing contract. The controller never references
89
- # the source's backing models directly, so the read source is swappable
90
- # without coupling Audiences to any particular provider.
88
+ # source (e.g. one backed by an external store) as long as it implements the
89
+ # port: #fetch, #groups_of, #users_matching, #all_users, #extra_users_of,
90
+ # #find_users, #present, #search_users and #identity_keys (see docs/README.md). Audiences
91
+ # never references the source's backing models directly, so the source is
92
+ # swappable without coupling Audiences to any particular provider.
91
93
  #
92
94
  # I.e.:
93
95
  #
94
96
  # Audiences.configure do |config|
95
- # config.read_source = MyExternalReadSource.new
97
+ # config.source = MyExternalSource.new
96
98
  # end
97
99
  #
98
- config_accessor(:read_source) { Audiences::ReadSources::Legacy.new }
100
+ config_accessor(:source) { Audiences::Sources::Legacy.new }
99
101
 
100
102
  # These are the user attributes that will be exposed in the audiences endpoints.
101
103
  # They're required by the UI to display the user information.
@@ -19,8 +19,7 @@ module Audiences
19
19
  delegate :users, to: :"#{name}_context", prefix: :"#{name}_external"
20
20
 
21
21
  define_method(name) do
22
- send(:"#{name}_context").users.includes(:identity)
23
- .map(&:identity)
22
+ Audiences::IdentityLookup.new.identities_of(send(:"#{name}_context").users)
24
23
  end
25
24
 
26
25
  scope :"with_#{name}_context", -> { includes(:"#{name}_context") }
@@ -0,0 +1,87 @@
1
+ # frozen_string_literal: true
2
+
3
+ module Audiences
4
+ module Sources
5
+ # Default source.
6
+ #
7
+ # Reads Audiences' own projection (ExternalUser / Group / GroupMembership),
8
+ # preserving the exact scoping, search, pagination and matching behavior the
9
+ # gem has always had. Records are returned as they are stored; #present turns
10
+ # them into the client-facing contract.
11
+ class Legacy
12
+ def fetch(resource_type:, query:, start_index:, count:)
13
+ scope(resource_type)
14
+ .search(query)
15
+ .offset(start_index)
16
+ .limit(count)
17
+ end
18
+
19
+ # @return [Enumerable<Group>] the groups of a criterion
20
+ def groups_of(criterion)
21
+ criterion.groups
22
+ end
23
+
24
+ # @param groups [Array<Group>] nonempty; a user must belong to at least one group
25
+ # of each resource type among these
26
+ # @return [ActiveRecord::Relation<ExternalUser>] without the default users scope
27
+ def users_matching(groups:)
28
+ groups.group_by(&:resource_type)
29
+ .values
30
+ .reduce(ExternalUser.all) do |users, of_type|
31
+ users.members_of(of_type)
32
+ end
33
+ end
34
+
35
+ # @return [ActiveRecord::Relation<ExternalUser>] every user
36
+ def all_users
37
+ ExternalUser.all
38
+ end
39
+
40
+ # @return [ActiveRecord::Relation<ExternalUser>] the context's extra users,
41
+ # inactive ones included
42
+ def extra_users_of(context)
43
+ ExternalUser.where(id: context.context_extra_users.select(:external_user_id))
44
+ end
45
+
46
+ # @param references [Array<Hash>] hashes with "id" and/or "externalId"
47
+ # (string or symbol keys)
48
+ # @return [ActiveRecord::Relation<ExternalUser>] the users matching any
49
+ # reference, inactive ones included; none for an empty list
50
+ def find_users(references)
51
+ ExternalUser.from_scim(*references)
52
+ end
53
+
54
+ # @param records [ActiveRecord::Relation, Array] users or groups
55
+ # @return [Array<Hash>] the records in the client-facing contract
56
+ def present(records)
57
+ records.map(&:as_json)
58
+ end
59
+
60
+ # @return [ActiveRecord::Relation<ExternalUser>] the users whose data match the query
61
+ def search_users(users, query)
62
+ pattern = "%#{query}%"
63
+
64
+ if users.connection.adapter_name == "PostgreSQL"
65
+ users.where("CAST(data AS TEXT) LIKE ?", pattern)
66
+ else
67
+ users.where("CAST(data AS CHAR) LIKE ?", pattern)
68
+ end
69
+ end
70
+
71
+ # @return [Array<String, nil>] the identity key of each user, in the relation's order
72
+ def identity_keys(users)
73
+ users.pluck(:user_id)
74
+ end
75
+
76
+ private
77
+
78
+ def scope(resource_type)
79
+ if resource_type == "Users"
80
+ ExternalUser.instance_exec(&Audiences.default_users_scope)
81
+ else
82
+ Group.where(resource_type: resource_type).instance_exec(&Audiences.default_groups_scope)
83
+ end
84
+ end
85
+ end
86
+ end
87
+ end
@@ -1,5 +1,5 @@
1
1
  # frozen_string_literal: true
2
2
 
3
3
  module Audiences
4
- VERSION = "3.2.1"
4
+ VERSION = "3.3.0"
5
5
  end
data/lib/audiences.rb CHANGED
@@ -12,8 +12,8 @@ module Audiences
12
12
  autoload :Integrations, "audiences/integrations"
13
13
  autoload :VERSION, "audiences/version"
14
14
 
15
- module ReadSources
16
- autoload :Legacy, "audiences/read_sources/legacy"
15
+ module Sources
16
+ autoload :Legacy, "audiences/sources/legacy"
17
17
  end
18
18
 
19
19
  module_function
metadata CHANGED
@@ -1,14 +1,14 @@
1
1
  --- !ruby/object:Gem::Specification
2
2
  name: audiences
3
3
  version: !ruby/object:Gem::Version
4
- version: 3.2.1
4
+ version: 3.3.0
5
5
  platform: ruby
6
6
  authors:
7
7
  - Carlos Palhares
8
8
  autorequire:
9
9
  bindir: bin
10
10
  cert_chain: []
11
- date: 2026-10-22 00:00:00.000000000 Z
11
+ date: 2026-11-19 00:00:00.000000000 Z
12
12
  dependencies:
13
13
  - !ruby/object:Gem::Dependency
14
14
  name: aether_observatory
@@ -60,6 +60,7 @@ files:
60
60
  - app/models/audiences/external_user.rb
61
61
  - app/models/audiences/group.rb
62
62
  - app/models/audiences/group_membership.rb
63
+ - app/models/audiences/identity_lookup.rb
63
64
  - app/models/audiences/membership.rb
64
65
  - app/models/audiences/users_search.rb
65
66
  - app/models/concerns/audiences/membership_group.rb
@@ -86,6 +87,8 @@ files:
86
87
  - db/migrate/20250624171706_rename_audiences_context_extra_users_to_extra_users_json.rb
87
88
  - db/migrate/20250701173946_move_extra_users_to_context_extra_users.rb
88
89
  - db/migrate/20260506150000_add_unique_index_to_group_memberships.rb
90
+ - db/migrate/20261110153026_add_source_group_id_to_audiences_criterion_groups.rb
91
+ - db/migrate/20261110153031_add_source_user_id_to_audiences_context_extra_users.rb
89
92
  - docs/CHANGELOG.md
90
93
  - docs/README.md
91
94
  - lib/audiences.rb
@@ -100,7 +103,7 @@ files:
100
103
  - lib/audiences/integrations/upsert_users_observer.rb
101
104
  - lib/audiences/model.rb
102
105
  - lib/audiences/notifications.rb
103
- - lib/audiences/read_sources/legacy.rb
106
+ - lib/audiences/sources/legacy.rb
104
107
  - lib/audiences/version.rb
105
108
  - lib/tasks/audiences_tasks.rake
106
109
  homepage: https://github.com/powerhome/audiences
@@ -126,7 +129,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
126
129
  - !ruby/object:Gem::Version
127
130
  version: '0'
128
131
  requirements: []
129
- rubygems_version: 3.5.16
132
+ rubygems_version: 3.5.22
130
133
  signing_key:
131
134
  specification_version: 4
132
135
  summary: Audiences system
@@ -1,30 +0,0 @@
1
- # frozen_string_literal: true
2
-
3
- module Audiences
4
- module ReadSources
5
- # Default read source.
6
- #
7
- # Reads Audiences' own projection (ExternalUser / Group), preserving the exact
8
- # scoping, search and pagination behavior the read endpoint has always had.
9
- # Records are returned as-is so the controller's `render json:` uses each
10
- # model's `as_json` to produce the client-facing contract.
11
- class Legacy
12
- def fetch(resource_type:, query:, start_index:, count:)
13
- scope(resource_type)
14
- .search(query)
15
- .offset(start_index)
16
- .limit(count)
17
- end
18
-
19
- private
20
-
21
- def scope(resource_type)
22
- if resource_type == "Users"
23
- ExternalUser.instance_exec(&Audiences.default_users_scope)
24
- else
25
- Group.where(resource_type: resource_type).instance_exec(&Audiences.default_groups_scope)
26
- end
27
- end
28
- end
29
- end
30
- end