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 +4 -4
- data/app/controllers/audiences/scim_proxy_controller.rb +3 -3
- data/app/models/audiences/context.rb +31 -15
- data/app/models/audiences/context_extra_user.rb +2 -0
- data/app/models/audiences/criterion.rb +22 -6
- data/app/models/audiences/criterion_group.rb +2 -0
- data/app/models/audiences/external_user.rb +0 -17
- data/app/models/audiences/identity_lookup.rb +49 -0
- data/app/models/audiences/users_search.rb +3 -8
- data/db/migrate/20261110153026_add_source_group_id_to_audiences_criterion_groups.rb +11 -0
- data/db/migrate/20261110153031_add_source_user_id_to_audiences_context_extra_users.rb +11 -0
- data/docs/CHANGELOG.md +23 -0
- data/docs/README.md +67 -15
- data/lib/audiences/configuration.rb +11 -9
- data/lib/audiences/model.rb +1 -2
- data/lib/audiences/sources/legacy.rb +87 -0
- data/lib/audiences/version.rb +1 -1
- data/lib/audiences.rb +2 -2
- metadata +7 -4
- data/lib/audiences/read_sources/legacy.rb +0 -30
checksums.yaml
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
---
|
|
2
2
|
SHA256:
|
|
3
|
-
metadata.gz:
|
|
4
|
-
data.tar.gz:
|
|
3
|
+
metadata.gz: 3de12c53ff70290a3ff0815a1510f3a5458f422e2accfc027e19d8a985bff4bf
|
|
4
|
+
data.tar.gz: 77b45aea62041440bf14b9d0be64c368e461cf2b865f1f9846629f1510c4cd6a
|
|
5
5
|
SHA512:
|
|
6
|
-
metadata.gz:
|
|
7
|
-
data.tar.gz:
|
|
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
|
|
6
|
-
# swappable via Audiences.config.
|
|
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.
|
|
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 :
|
|
18
|
-
|
|
19
|
-
|
|
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:
|
|
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
|
-
|
|
55
|
-
end
|
|
68
|
+
def matching_external_users(groups_by_criterion)
|
|
69
|
+
return Audiences.source.all_users if match_all
|
|
56
70
|
|
|
57
|
-
|
|
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
|
|
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
|
|
@@ -38,15 +38,31 @@ module Audiences
|
|
|
38
38
|
end
|
|
39
39
|
end
|
|
40
40
|
|
|
41
|
-
def as_json(
|
|
42
|
-
|
|
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:
|
|
46
|
+
{ id: id, count: users(groups: groups).count, groups: presented_groups }.as_json(*args, **kwargs)
|
|
45
47
|
end
|
|
46
48
|
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
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
|
|
@@ -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:
|
|
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:
|
|
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
|
-
|
|
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.
|
|
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
|
-
####
|
|
47
|
+
#### Source
|
|
48
48
|
|
|
49
|
-
|
|
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.
|
|
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.
|
|
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.
|
|
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.
|
|
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.
|
|
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
|
-
|
|
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
|
|
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
|
|
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
|
-
|
|
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
|
|
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::
|
|
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
|
|
87
|
-
#
|
|
88
|
-
#
|
|
89
|
-
# the source's backing models directly, so the
|
|
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.
|
|
97
|
+
# config.source = MyExternalSource.new
|
|
96
98
|
# end
|
|
97
99
|
#
|
|
98
|
-
config_accessor(:
|
|
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.
|
data/lib/audiences/model.rb
CHANGED
|
@@ -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
|
|
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
|
data/lib/audiences/version.rb
CHANGED
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
|
|
16
|
-
autoload :Legacy, "audiences/
|
|
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.
|
|
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-
|
|
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/
|
|
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.
|
|
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
|