audiences 1.1.1 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 76331d54059446a90b80c23d1c861254acecbeacd2724b9ecf7db435637b8386
-  data.tar.gz: c17b4fa514d26dbc3f1bf8083df0adee99deedb0afd8356d61505188e86c7ad4
+  metadata.gz: a764dbb90f7727e7b0054227fedb0d8eee691ab7e65a5c0007413121de492965
+  data.tar.gz: f4c0fc7843aae456f8df4e2aed78615fc3169257cdebe9a28578443ad32c0949
 SHA512:
-  metadata.gz: d49dd1a67058d2f9f87aaaff313592237824dba4f94065d42a3e64e74f6261da94b350a845f2e0942ac88bcfa922e4c90b26e94d376b21898819df81e3a7b063
-  data.tar.gz: '0814d1f51e253f0f266bdc113bd72893dea24efe50db09ea5e7da78f44e3f1c82554c1cb85019f69eb00a747c677737af2aa704624c2581cf63946d9cbefe1a6'
+  metadata.gz: 4b04b83f5314e11bdd03d373632683bfe59e39eb2ded010c8b49ccbaf914904f4a05dc9788589488a670ae168df19293a175bc9ade59044568d0f27b8e1769d1
+  data.tar.gz: a4abbd7408fceb3cc6349000003cddc78ceb564f2824d93dfbb27e340373603dc6cb9c844136954a95e12a374e1439216cd0d202cb75c6dd8b4feb9f91441545

data/app/controllers/audiences/contexts_controller.rb

@@ -3,7 +3,7 @@
 module Audiences
   class ContextsController < ApplicationController
     def show
-      render_context Audiences.load(params.require(:key))
+      render_context Audiences::Context.load(params.require(:key))
     end
 
     def update
@@ -23,7 +23,7 @@ module Audiences
   private
 
     def current_context
-      @current_context ||= Audiences.load(params.require(:key))
+      @current_context ||= Audiences::Context.load(params.require(:key))
     end
 
     def current_criterion
@@ -44,7 +44,7 @@ module Audiences
       params.permit(
         :match_all,
         criteria: [groups: {}],
-        extra_users: [:id, :displayName, { photos: %i[type value] }]
+        extra_users: [:externalId, :displayName, { photos: %i[type value] }]
       ).to_h.symbolize_keys
     end
   end

data/app/controllers/audiences/scim_proxy_controller.rb

@@ -3,10 +3,8 @@
 module Audiences
   class ScimProxyController < ApplicationController
     def get
-      resources = Audiences::Scim.resources(
-        type: params[:scim_path].to_sym,
-        filter: params[:filter]
-      )
+      resources = Audiences::Scim.resource(params[:scim_path].to_sym)
+                                 .query(filter: params[:filter])
 
       render json: resources
     end

data/app/models/audiences/context/locating.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Audiences
+  class Context
+    module Locating
+      extend ActiveSupport::Concern
+
+      SIGNED_GID_RESOURCE = "audiences"
+
+      class_methods do
+        # Finds or creates a context for the given owner/relation
+        #
+        # @private
+        # @param owner [Class<ActiveRecord::Base>] an active record owning the context
+        # @Param relation [String,Symbol] a context relation (i.e.: :members)
+        # @return [Audiences::Context]
+        def for(owner, relation: nil)
+          where(owner: owner, relation: relation).first_or_create!
+        end
+
+        # Loads a context given a signed GlobalID key
+        #
+        # @private
+        # @param key [String] signed GlobalID key
+        # @return [Audiences::Context]
+        # @yield [Audiences::Context]
+        def load(key)
+          GlobalID::Locator.locate_signed(key, for: SIGNED_GID_RESOURCE).tap do |ctx|
+            yield ctx if block_given?
+          end
+        end
+      end
+
+      def signed_key
+        to_sgid(for: SIGNED_GID_RESOURCE)
+      end
+    end
+  end
+end

data/app/models/audiences/context.rb

@@ -6,6 +6,7 @@ module Audiences
   # users (#criteria, #match_all, #extra_users).
   #
   class Context < ApplicationRecord
+    include Locating
     include ::Audiences::MembershipGroup
 
     belongs_to :owner, polymorphic: true
@@ -18,14 +19,6 @@ module Audiences
       self.extra_users = []
     end
 
-    # Finds or creates a context for the given owner
-    #
-    # @private
-    # @return [Audiences::Context]
-    def self.for(owner)
-      where(owner: owner).first_or_create!
-    end
-
     def refresh_users!
       criteria.each(&:refresh_users!)
       update!(users: ContextUsers.new(self).to_a)

data/app/models/audiences/context_users.rb

@@ -20,7 +20,7 @@ module Audiences
   private
 
     def all_users
-      users = Scim.resources(type: :Users)
+      users = Scim.resource(:Users).query
       ExternalUser.wrap(users.all)
     end
 

data/app/models/audiences/criterion_users.rb

@@ -11,6 +11,7 @@ module Audiences
 
     def each(...)
       @groups.values
+             .reject(&:empty?)
              .map { |groups| groups_users(groups.pluck("id")) }
              .reduce(&:&)
              &.each(...)
@@ -20,7 +21,7 @@ module Audiences
 
     def groups_users(group_ids)
       filter = group_ids.map { "groups.value eq #{_1}" }.join(" OR ")
-      users = Audiences::Scim.resources(type: :Users, filter: filter)
+      users = Audiences::Scim.resource(:Users).query(filter: filter)
       ExternalUser.wrap(users.all)
     end
   end

data/app/models/audiences/external_user.rb

@@ -2,13 +2,19 @@
 
 module Audiences
   class ExternalUser < ApplicationRecord
-    has_many :memberships
+    if Audiences.config.identity_class
+      belongs_to :identity, class_name: Audiences.config.identity_class, # rubocop:disable Rails/ReflectionClassName
+                            primary_key: Audiences.config.identity_key,
+                            foreign_key: :user_id,
+                            optional: true,
+                            inverse_of: false
+    end
 
     def self.wrap(resources)
       return [] unless resources&.any?
 
       attrs = resources.map do |data|
-        { user_id: data["id"], data: data, created_at: Time.current, updated_at: Time.current }
+        { user_id: data["externalId"], data: data, created_at: Time.current, updated_at: Time.current }
       end
       unique_by = :user_id if connection.supports_insert_conflict_target?
       upsert_all(attrs, unique_by: unique_by) # rubocop:disable Rails/SkipsModelValidations

data/config/routes.rb

@@ -8,13 +8,12 @@ Audiences::Engine.routes.draw do
 end
 
 Rails.application.routes.draw do
-  mount Audiences::Engine, at: "/audiences", as: :audiences
-
-  direct :audience_context do |owner, options|
-    audiences.route_for(:signed_context, key: Audiences.sign(owner), **options)
+  direct :audience_context do |owner, relation = nil|
+    context = Audiences::Context.for(owner, relation: relation)
+    Audiences::Engine.routes.url_helpers.route_for(:signed_context, key: context.signed_key, **url_options)
   end
 
   direct :audience_scim_proxy do |options|
-    audiences.route_for(:scim_proxy, **options)
+    Audiences::Engine.routes.url_helpers.route_for(:scim_proxy, **url_options, **options)
   end
 end

data/db/migrate/20240722025634_add_relation_to_context.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+class AddRelationToContext < ActiveRecord::Migration[6.1]
+  def change
+    add_column :audiences_contexts, :relation, :string, null: true
+    remove_index :audiences_contexts, %w[owner_type owner_id], unique: true
+    add_index :audiences_contexts, %w[owner_type owner_id relation],
+              unique: true,
+              name: "index_audiences_contexts_on_owner_type_owner_id_relation"
+  end
+end

data/docs/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Unreleased
 
+# Version 1.2.0 (2024-07-24)
+
+- Add `has_audience` and the ability to attach multiple audiences to the same owner [#363](https://github.com/powerhome/audiences/pull/363)
+- Audiences.config/configure helpers [#359](https://github.com/powerhome/audiences/pull/359)
+- Adjust user id to SCIM Protocol [#356](https://github.com/powerhome/audiences/pull/356)
+
+# Version 1.1.2 (2024-06-18)
+
+- Ignore empty groups in criterion [#354](https://github.com/powerhome/audiences/pull/354)
+
 # Version 1.1.1 (2024-06-18)
 
 - Fix default resource attributes [#342](https://github.com/powerhome/audiences/pull/342)

data/docs/README.md

@@ -2,80 +2,120 @@
 
 "Audiences" is a SCIM-integrated notifier for real-time Rails actions based on group changes.
 
-## Usage
+## Installation
 
-### Creating/Managing audiences
+Add this line to your application's Gemfile:
 
-An audience is tied to an owning model withing your application. For the rest of this document we're going to assume a model Team. To create audiences for a team, using `audiences-react`, you'll render an audiences editor for your model.
+```ruby
+gem "audiences"
+```
 
-That can be done with a unobstrusive JS renderer like react-rails, or a custom one as in [our dummy app](../audiences/spec/dummy/app/frontend/entrypoints/application.js). The editor will need two arguments:
+Then execute:
 
-- The context URI: `audience_context_url(owner)` helper
-- The SCIM endpoint: `audience_scim_proxy_url` helper if using the [proxy](#configuring-the-scim-proxy), or the SCIM endpoint.
+```bash
+$ bundle install
+```
 
-### Configuring the SCIM backend
+Or install it yourself with:
 
-The Audience::Scim should point to the real SCIM endpoint. The service allows you to configure the endpoint and the credentials/headers:
+```bash
+$ gem install audiences
+```
+
+## Usage
+
+### Creating/Managing Audiences
+
+An audience is tied to an owning model within your application. In this document, we'll use a `Team` model as an example. To create audiences for a team using `audiences-react`, render an audiences editor for your model.
 
-I.e.:
+This can be done with an unobtrusive JS renderer like `react-rails` or a custom one as shown in [our dummy app](../audiences/spec/dummy/app/frontend/entrypoints/application.js). The editor requires two arguments:
+
+- The context URI: `audience_context_url(owner, relation)` helper
+- The SCIM endpoint: `audience_scim_proxy_url` helper if using the [proxy](#configuring-the-scim-proxy), or the SCIM endpoint directly.
+
+### Configuring Audiences
+
+The `Audience.config.scim` should point to the SCIM endpoint. Configure the endpoint and the credentials/headers as follows:
 
 ```ruby
-Audiences::Scim.client = Audiences::Scim::Client.new(
-  uri: ENV.fetch("SCIM_V2_API"),
-  headers: { "Authorization" => "Bearer #{ENV.fetch('SCIM_V2_TOKEN')}" }
-)
+Audiences.configure do |config|
+  config.scim = {
+    uri: ENV.fetch("SCIM_V2_API"),
+    headers: { "Authorization" => "Bearer #{ENV.fetch('SCIM_V2_TOKEN')}" }
+  }
+end
 ```
 
-### Listening to audience changes
+### Adding Audiences to a Model
 
-The goal of audiences is to allow the app to keep up with a mutable group of people. To allow that, `Audiences` includes the `Audiences::Notifications` module, to allow the hosting app to subscribe to audiences related to a certain owner type, and react to that through a block:
+A model object can contain multiple audience contexts using the `has_audience` module helper, which is added to ActiveRecord automatically when configured:
 
 ```ruby
-Rails.application.config.to_prepare do
-  Audiences::Notifications.subscribe Team do |context|
-    team.update_memberships(context.users)
-  end
+Audiences.configure do |config|
+  config.identity_class = "User"
+  config.identity_key = "login"
 end
 ```
 
-or scheduling an AcitiveJob:
+The `identity_class` represents the SCIM user within the app domain, and the `identity_key` maps directly to the SCIM User's `externalId`.
+
+Once configured, add audience contexts to a model:
 
 ```ruby
-Rails.application.config.to_prepare do
-  Audiences::Notifications.subscribe Group, job: UpdateGroupMembershipsJob
-  Audiences::Notifications.subscribe Team, job: UpdateTeamMembershipsJob.set(queue: "low")
+class Survey < ApplicationRecord
+  has_audience :responders
+  has_audience :supervisors
 end
 ```
 
-You can find a working example in our dummy app:
+### Listening to Audience Changes
 
-- [initializer](../spec/dummy/config/initializers/audiences.rb)
-- [job class](../spec/dummy/app/jobs/update_memberships_job.rb)
+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:
 
-## Installation
+```ruby
+Audiences.configure do |config|
+  config.notifications do
+    subscribe Team do |context|
+      team.update_memberships(context.users)
+    end
+  end
+end
+```
 
-Add this line to your application's Gemfile:
+Or schedule an ActiveJob:
 
 ```ruby
-gem "audiences"
+Audiences.configure do |config|
+  config.notifications do
+    subscribe Group, job: UpdateGroupMembershipsJob
+    subscribe Team, job: UpdateTeamMembershipsJob.set(queue: "low")
+  end
+end
 ```
 
-And then execute:
+The notifications block is executed every time the app is loaded or reloaded through a `to_prepare` block, allowing autoloaded constants such as model and job classes to be referenced.
 
-```bash
-$ bundle
-```
+See a working example in our dummy app:
 
-Or install it yourself as:
+- [Initializer](../spec/dummy/config/initializers/audiences.rb)
+- [Job class](../spec/dummy/app/jobs/update_memberships_job.rb)
+- [Example owning model](../spec/dummy/app/models/example_owner.rb)
 
-```bash
-$ gem install audiences
+### SCIM Resource Attributes
+
+Configure which attributes are requested from the SCIM backend for each resource type. `Audiences` requires at least `id` and `displayName`, and also requests `photos` and `externalId` for users by default. To request additional attributes:
+
+```ruby
+Audiences.configure do |config|
+  config.resource :Users, attributes: "id,externalId,displayName,photos,name"
+  config.resource :Groups, attributes: "id,displayName,mfaRequired"
+end
 ```
 
 ## Contributing
 
-See [development guide](../../docs/development.md).
+For more information, see the [development guide](../../docs/development.md).
 
 ## License
 
-The 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

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+module Audiences
+  include ActiveSupport::Configurable
+
+  # Configuration options
+
+  #
+  # Identity model representing a SCIM User in the current application. I.e.: "User"
+  #
+  config_accessor :identity_class
+
+  #
+  # The key attribute on `identity_class` matching with the SCIM User externalId.
+  # This configuration defaults to `:id`
+  #
+  config_accessor(:identity_key) { :id }
+
+  #
+  # SCIM service configurations. This should be a Hash containint, at least, the URI.
+  #
+  # I.e.:
+  #
+  #   Audiences.configure do |config|
+  #     config.scim = { uri: "http://localhost/api/scim" }
+  #   end
+  #
+  # It can also contain HTTP headers, such as "Authorization":
+  #
+  # I.e.:
+  #
+  #   Audiences.configure do |config|
+  #     config.scim = {
+  #       uri: "http://localhost/api/scim",
+  #       headers: { "Authorization" => "Bearer auth-token" }
+  #     }
+  #   end
+  #
+  config_accessor :scim
+
+  #
+  # Resources defaults. Change this configuration via the `resource` helper.
+  # This configuration lists the current Audiences accessible resource defaults,
+  # and defaults to Users only. To add other resource types for criteria building.
+  #
+  # @see `resource`.
+  #
+  config_accessor :resources do
+    { Users: Scim::Resource.new(type: :Users, attributes: "id,externalId,displayName,photos") }
+  end
+
+  #
+  # Configures a resource default.
+  #
+  # @param type [Symbol] the resource type in plural, as in scim (i.e.: :Users)
+  # @param attributes [String] the list of attributes to fetch for the resource (i.e.: "id,externalId,displayName")
+  # @see [Audiences::Scim::Resource]
+  def config.resource(type:, **kwargs)
+    config.resources[type] = Scim::Resource.new(type: type, **kwargs)
+  end
+
+  #
+  # Notifications configurations.
+  # Within this block, you should be able to easily register job classes to execute as
+  # audiences are changed. Notice: this block is executed every time your app initializes
+  # or reloads. This allows you to reference reloaded constants, like job names:
+  #
+  # I.e.:
+  #
+  #   Audiences.configure do |config|
+  #     config.notifications do
+  #       subscribe CallQueue, job: CallQueueMembersSyncJob
+  #       subscribe ChatRoom, job: ChatRoomMembersSyncJob
+  #     end
+  #   end
+  #
+  # This block is executed
+  # @see [Audiences::Notifications]
+  def config.notifications(&block)
+    Rails.application.config.to_prepare do
+      Notifications.class_eval(&block)
+    end
+  end
+end

data/lib/audiences/engine.rb

@@ -9,5 +9,13 @@ module Audiences
   #
   class Engine < ::Rails::Engine
     isolate_namespace Audiences
+
+    initializer "audiences.model" do
+      if Audiences.config.identity_class
+        ActiveSupport.on_load(:active_record) do
+          include Audiences::Model
+        end
+      end
+    end
   end
 end

data/lib/audiences/model.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Audiences
+  module Model
+    extend ActiveSupport::Concern
+
+    class_methods do
+      #
+      # Adds relationships between the audience context and the owner object
+      #
+      # @param name [Symbol,String] the member relationship name
+      #
+      # rubocop:disable Naming/PredicateName,Metrics/MethodLength,Metrics/AbcSize
+      def has_audience(name)
+        has_one :"#{name}_context", -> { where(relation: name) },
+                as: :owner, dependent: :destroy,
+                class_name: "Audiences::Context"
+        has_many :"#{name}_external_users",
+                 through: :"#{name}_context", source: :users,
+                 class_name: "Audiences::ExternalUser"
+        has_many name, -> { readonly }, through: :"#{name}_external_users", source: :identity
+
+        scope :"with_#{name}", -> { includes(name) }
+        scope :"with_#{name}_context", -> { includes(:"#{name}_context") }
+        scope :"with_#{name}_external_users", -> { includes(:"#{name}_external_users") }
+
+        after_initialize if: :new_record? do
+          association(:"#{name}_context").build
+        end
+      end
+      # rubocop:enable Naming/PredicateName,Metrics/MethodLength,Metrics/AbcSize
+    end
+  end
+end

data/lib/audiences/scim/resource.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Audiences
+  module Scim
+    class Resource
+      attr_accessor :options, :type
+
+      def initialize(type:, attributes: "id,externalId,displayName", **options)
+        @type = type
+        @options = options
+        @options[:attributes] = attributes
+      end
+
+      def query(**options)
+        ResourcesQuery.new(Scim.client, resource: self, **@options, **options)
+      end
+    end
+  end
+end

data/lib/audiences/scim/resources_query.rb

@@ -9,12 +9,12 @@ module Audiences
     class ResourcesQuery
       include Enumerable
 
-      attr_reader :query_options
+      attr_reader :options, :resource
 
-      def initialize(client, resource_type:, **query_options)
+      def initialize(client, resource:, **options)
         @client = client
-        @resource_type = resource_type
-        @query_options = query_options
+        @resource = resource
+        @options = options
       end
 
       def all
@@ -53,14 +53,13 @@ module Audiences
       def next_page
         return unless next_page?
 
-        ResourcesQuery.new(@client, resource_type: @resource_type, **@query_options,
-                                    startIndex: next_index)
+        ResourcesQuery.new(@client, resource: @resource, **@options, startIndex: next_index)
       end
 
     private
 
       def response
-        @response ||= @client.perform_request(path: @resource_type, method: :Get, query: @query_options)
+        @response ||= @client.perform_request(path: @resource.type, method: :Get, query: @options)
       end
     end
   end

data/lib/audiences/scim.rb

@@ -1,19 +1,21 @@
 # frozen_string_literal: true
 
-require_relative "scim/client"
-require_relative "scim/resources_query"
-
 module Audiences
   module Scim
-    mattr_accessor :client
-    mattr_accessor :defaults, default: Hash.new(attributes: "id,displayName")
+    autoload :Client, "audiences/scim/client"
+    autoload :Resource, "audiences/scim/resource"
+    autoload :ResourcesQuery, "audiences/scim/resources_query"
 
   module_function
 
-    def resources(type:, client: Scim.client, **options)
-      options = (defaults[type] || {}).merge(options)
+    def client
+      Client.new(**Audiences.config.scim)
+    end
 
-      ResourcesQuery.new(client, resource_type: type, **options)
+    def resource(type, **options)
+      Audiences.config.resources.fetch(type) do
+        Resource.new(type: type, **options)
+      end
     end
   end
 end

data/lib/audiences/version.rb

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

data/lib/audiences.rb

@@ -1,37 +1,17 @@
 # frozen_string_literal: true
 
-require "audiences/version"
-require "audiences/scim"
-require "audiences/notifications"
-
 # Audiences system
 # Audiences pushes notifications to your rails app when a
 # SCIM backend updates a user, notifying matching audiences.
 #
 module Audiences
-  GID_RESOURCE = "audiences"
+  autoload :Model, "audiences/model"
+  autoload :Notifications, "audiences/notifications"
+  autoload :Scim, "audiences/scim"
+  autoload :VERSION, "audiences/version"
 
 module_function
 
-  # Provides a key to load an audience context for the given owner.
-  # An owner should implment GlobalID::Identification.
-  #
-  # @param owner [GlobalID::Identification] an owning model
-  # @return [String] context key
-  #
-  def sign(owner)
-    owner.to_sgid(for: GID_RESOURCE)
-  end
-
-  # Loads a context for the given context key
-  #
-  # @param token [String] a signed token (see #sign)
-  # @return Audience::Context
-  #
-  def load(key)
-    locate_context(key, &:readonly!)
-  end
-
   # Updates the given context
   #
   # Params might contain:
@@ -44,18 +24,14 @@ module_function
   # @return Audience::Context
   #
   def update(key, criteria: [], **attrs)
-    locate_context(key) do |context|
+    Audiences::Context.load(key) do |context|
       context.update!(
         criteria: ::Audiences::Criterion.map(criteria),
         **attrs
       )
       context.refresh_users!
-      context.readonly!
     end
   end
-
-  private_class_method def locate_context(key, &block)
-    owner = GlobalID::Locator.locate_signed(key, for: GID_RESOURCE)
-    ::Audiences::Context.for(owner).tap(&block)
-  end
 end
+
+require "audiences/configuration"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: audiences
 version: !ruby/object:Gem::Version
-  version: 1.1.1
+  version: 1.2.0
 platform: ruby
 authors:
 - Carlos Palhares
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-06-18 00:00:00.000000000 Z
+date: 2024-07-24 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -39,6 +39,7 @@ files:
 - app/jobs/audiences/application_job.rb
 - app/models/audiences/application_record.rb
 - app/models/audiences/context.rb
+- app/models/audiences/context/locating.rb
 - app/models/audiences/context_users.rb
 - app/models/audiences/criterion.rb
 - app/models/audiences/criterion_users.rb
@@ -55,13 +56,17 @@ files:
 - db/migrate/20231130165945_create_audiences_external_users.rb
 - db/migrate/20231130172718_create_audiences_memberships.rb
 - db/migrate/20231205140046_remove_serialized_users_from_criterion.rb
+- db/migrate/20240722025634_add_relation_to_context.rb
 - docs/CHANGELOG.md
 - docs/README.md
 - lib/audiences.rb
+- lib/audiences/configuration.rb
 - lib/audiences/engine.rb
+- lib/audiences/model.rb
 - lib/audiences/notifications.rb
 - lib/audiences/scim.rb
 - lib/audiences/scim/client.rb
+- lib/audiences/scim/resource.rb
 - lib/audiences/scim/resources_query.rb
 - lib/audiences/version.rb
 - lib/tasks/audiences_tasks.rake