audiences 0.1.0 → 1.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 301017a77754bc9639d80ae7cf2a5260c1a6811e9bec5c49daefaca3b9833220
-  data.tar.gz: bd65ad4e4baf6577420716c58b75921700cd866d43514cf7c18978d564b0d5e7
+  metadata.gz: d908257a2da48f7c59f74138a5e92c160682d929826267aad9095f99510f2f3c
+  data.tar.gz: 313ff13a58a5e64827e4e52cf36b9f214913d9ce0aeb64f23962246552853f87
 SHA512:
-  metadata.gz: 0af804e8e6e477a2248b80339721897e3dd48ba27aa34f3524dbef8e5fd0cf09de9feaee0093fa2208030b7a194385e2313157a20f64cc3b536e719ac35d1b5d
-  data.tar.gz: '08b631ec00c43818f1537ee222df54e196df0f6cb918e6cd45eb23c552a70b9d953a3a25c8774bf3d842360be406cdee4d9ffd89e54d33bd0760d8182348b637'
+  metadata.gz: 2849064c0ded8cca2a083b3f4aca9d8cbcf1ea6ab10102c96f6de76ffedd23439cbbe2fe2e8743988e5cb97cd375c0ccff69988376361fc5c305e3e75878e250
+  data.tar.gz: c0af5d5b298135abb4d362f277f2eb7f69855346be5ec262c223c42c71647c33f113b91902b3323191ede6e5787c87a26355b7c1b7387cc154171cd030196b55

data/app/controllers/audiences/contexts_controller.rb

@@ -3,13 +3,49 @@
 module Audiences
   class ContextsController < ApplicationController
     def show
-      render json: current_context.as_json(only: %w[match_all], methods: %w[key criteria])
+      render_context Audiences.load(params.require(:key))
+    end
+
+    def update
+      render_context Audiences.update(params.require(:key), **context_params)
+    end
+
+    def users
+      users = (current_criterion || current_context).users
+      search = UsersSearch.new(scope: users,
+                               query: params[:search],
+                               limit: params[:limit],
+                               offset: params[:offset])
+
+      render json: search
     end
 
   private
 
     def current_context
-      @current_context ||= Audiences.load(params[:key])
+      @current_context ||= Audiences.load(params.require(:key))
+    end
+
+    def current_criterion
+      return unless params[:criterion_id]
+
+      @current_criterion ||= current_context.criteria.find(params[:criterion_id])
+    end
+
+    def render_context(context)
+      render json: context.as_json(
+        only: %i[match_all extra_users],
+        methods: %i[count],
+        include: { criteria: { only: %i[id groups], methods: %i[count] } }
+      )
+    end
+
+    def context_params
+      params.permit(
+        :match_all,
+        criteria: [groups: {}],
+        extra_users: [:id, :displayName, { photos: %i[type value] }]
+      ).to_h.symbolize_keys
     end
   end
 end

data/app/controllers/audiences/scim_proxy_controller.rb

@@ -1,19 +1,14 @@
 # frozen_string_literal: true
 
-require "audiences/scim_proxy"
-
 module Audiences
   class ScimProxyController < ApplicationController
     def get
-      status, body = ScimProxy.get(params[:scim_path], scim_params)
-
-      render body: body, status: status, content_type: "application/json"
-    end
-
-  private
+      resources = Audiences::Scim.resources(
+        type: params[:scim_path].to_sym,
+        filter: params[:filter]
+      )
 
-    def scim_params
-      params.except(:scim_path, :controller, :action).permit!.to_h
+      render json: resources
     end
   end
 end

data/app/models/audiences/context.rb

@@ -1,15 +1,35 @@
 # frozen_string_literal: true
 
 module Audiences
+  # Represents a context where the group of users (audience) is relevant.
+  # It includes the current matching users and the criteria to match these
+  # users (#criteria, #match_all, #extra_users).
+  #
   class Context < ApplicationRecord
+    include ::Audiences::MembershipGroup
+
     belongs_to :owner, polymorphic: true
+    has_many :criteria, class_name: "Audiences::Criterion",
+                        autosave: true,
+                        dependent: :destroy
+
+    before_save if: :match_all do
+      self.criteria = []
+      self.extra_users = []
+    end
 
-    def key
-      Audiences.sign(owner)
+    # 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 criteria
-      []
+    def refresh_users!
+      criteria.each(&:refresh_users!)
+      update!(users: ContextUsers.new(self).to_a)
+      Notifications.publish(self)
     end
   end
 end

data/app/models/audiences/context_users.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Audiences
+  # @private
+  class ContextUsers
+    include Enumerable
+
+    def initialize(context)
+      @context = context
+    end
+
+    def each(...)
+      if @context.match_all
+        all_users.each(...)
+      else
+        matching_users.each(...)
+      end
+    end
+
+  private
+
+    def all_users
+      users = Scim.resources(type: :Users)
+      ExternalUser.wrap(users.all)
+    end
+
+    def matching_users
+      extras = ExternalUser.wrap(@context.extra_users)
+      [*extras, *@context.criteria.flat_map(&:users)].uniq
+    end
+  end
+end

data/app/models/audiences/criterion.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Audiences
+  class Criterion < ApplicationRecord
+    include ::Audiences::MembershipGroup
+
+    belongs_to :context, class_name: "Audiences::Context"
+
+    def self.map(criteria)
+      Array(criteria).map { new(_1) }
+    end
+
+    def refresh_users!
+      update!(
+        users: CriterionUsers.new(groups || {}).to_a,
+        refreshed_at: Time.current
+      )
+    end
+  end
+end

data/app/models/audiences/criterion_users.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Audiences
+  # @private
+  class CriterionUsers
+    include Enumerable
+
+    def initialize(groups)
+      @groups = groups
+    end
+
+    def each(...)
+      @groups.values
+             .map { |groups| groups_users(groups.pluck("id")) }
+             .reduce(&:&)
+             &.each(...)
+    end
+
+  private
+
+    def groups_users(group_ids)
+      filter = group_ids.map { "groups.value eq #{_1}" }.join(" OR ")
+      users = Audiences::Scim.resources(type: :Users, filter: filter)
+      ExternalUser.wrap(users.all)
+    end
+  end
+end

data/app/models/audiences/external_user.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Audiences
+  class ExternalUser < ApplicationRecord
+    has_many :memberships
+
+    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 }
+      end
+      upsert_all(attrs, unique_by: :user_id) # rubocop:disable Rails/SkipsModelValidations
+      where(user_id: attrs.pluck(:user_id))
+    end
+
+    def as_json(*)
+      data.as_json
+    end
+  end
+end

data/app/models/audiences/membership.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module Audiences
+  class Membership < ApplicationRecord
+    belongs_to :external_user
+    belongs_to :group, polymorphic: true
+  end
+end

data/app/models/audiences/users_search.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Audiences
+  class UsersSearch
+    DEFAULT_LIMIT = 20
+
+    def initialize(query:, limit: nil, offset: 0, scope: ExternalUser)
+      @scope = scope
+      @query = query
+      @limit = limit || DEFAULT_LIMIT
+      @offset = offset
+    end
+
+    def as_json(*)
+      {
+        users: users,
+        count: count,
+      }
+    end
+
+    delegate :count, to: :result
+
+    def users
+      @users ||= result.limit(@limit).offset(@offset)
+    end
+
+  private
+
+    def result
+      @result ||= @scope.where("data LIKE ?", "%#{@query}%")
+    end
+  end
+end

data/app/models/concerns/audiences/membership_group.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Audiences
+  module MembershipGroup
+    extend ActiveSupport::Concern
+
+    included do
+      has_many :memberships, as: :group, dependent: :delete_all
+      has_many :users, through: :memberships, source: :external_user, dependent: :delete_all
+
+      delegate :count, to: :users
+    end
+  end
+end

data/config/routes.rb

@@ -3,6 +3,8 @@
 Audiences::Engine.routes.draw do
   get "/scim(/*scim_path)" => "scim_proxy#get", as: :scim_proxy
   get "/:key" => "contexts#show", as: :signed_context
+  get "/:key/users(/:criterion_id)" => "contexts#users", as: :users
+  put "/:key" => "contexts#update"
 end
 
 Rails.application.routes.draw do

data/db/migrate/20230725194934_create_audiences_contexts.rb

@@ -5,8 +5,9 @@ class CreateAudiencesContexts < ActiveRecord::Migration[6.0]
     create_table :audiences_contexts do |t|
       t.references :owner, polymorphic: true, null: false, index: { unique: true }
       t.boolean :match_all, default: false, null: false
+      t.json :criteria
 
-      t.timestamps
+      t.timestamps precision: 0
     end
   end
 end

data/db/migrate/20231114210454_add_extra_users_to_audiences_context.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+class AddExtraUsersToAudiencesContext < ActiveRecord::Migration[6.0]
+  def change
+    add_column :audiences_contexts, :extra_users, :json
+  end
+end

data/db/migrate/20231114210633_remove_criteria_from_audiences_context.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+class RemoveCriteriaFromAudiencesContext < ActiveRecord::Migration[6.0]
+  def change
+    remove_column :audiences_contexts, :criteria, :json
+  end
+end

data/db/migrate/20231114215843_create_audiences_criterions.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+class CreateAudiencesCriterions < ActiveRecord::Migration[6.0]
+  def change
+    create_table :audiences_criterions do |t|
+      t.json :groups
+      t.references :context, null: false, foreign_key: false
+
+      t.timestamps precision: 0
+    end
+  end
+end

data/db/migrate/20231115204932_add_users_to_audiences_criterion.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+class AddUsersToAudiencesCriterion < ActiveRecord::Migration[6.0]
+  def change
+    add_column :audiences_criterions, :users, :json
+    add_column :audiences_criterions, :refreshed_at, :datetime
+  end
+end

data/db/migrate/20231130165945_create_audiences_external_users.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+class CreateAudiencesExternalUsers < ActiveRecord::Migration[6.0]
+  def change
+    create_table :audiences_external_users do |t|
+      t.string :user_id, null: false
+      t.json :data
+
+      t.timestamps precision: 0
+      t.index :user_id, unique: true
+    end
+  end
+end

data/db/migrate/20231130172718_create_audiences_memberships.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+class CreateAudiencesMemberships < ActiveRecord::Migration[6.0]
+  def change
+    create_table :audiences_memberships do |t|
+      t.references :external_user, null: false, foreign_key: false
+      t.references :group, null: false, foreign_key: false, polymorphic: true
+
+      t.timestamps precision: 0
+    end
+  end
+end

data/db/migrate/20231205140046_remove_serialized_users_from_criterion.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+class RemoveSerializedUsersFromCriterion < ActiveRecord::Migration[6.0]
+  def change
+    remove_column :audiences_criterions, :users, :json
+  end
+end

data/docs/CHANGELOG.md

@@ -0,0 +1,3 @@
+# Version 1.0 (2024-04-25)
+
+* Inaugural release of Audiences

data/docs/README.md

@@ -13,30 +13,45 @@ That can be done with a unobstrusive JS renderer like react-rails, or a custom o
 - 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.
 
-### Listening to audience changes
+### Configuring the SCIM backend
 
-**TBD**
+The Audience::Scim should point to the real SCIM endpoint. The service allows you to configure the endpoint and the credentials/headers:
 
-### Configuring the SCIM proxy
+I.e.:
 
-The Audience::ScimProxy should point to the real SCIM endpoint. The proxy allows you to configure the endpoint and the credentials/headers:
+```ruby
+Audiences::Scim.client = Audiences::Scim::Client.new(
+  uri: ENV.fetch("SCIM_V2_API"),
+  headers: { "Authorization" => "Bearer #{ENV.fetch('SCIM_V2_TOKEN')}" }
+)
+```
 
-I.e.:
+### Listening to audience changes
+
+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:
 
 ```ruby
-# frozen_string_literal: true
+Rails.application.config.to_prepare do
+  Audiences::Notifications.subscribe Team do |context|
+    team.update_memberships(context.users)
+  end
+end
+```
 
-require "audiences/scim_proxy"
+or scheduling an AcitiveJob:
 
-Audiences::ScimProxy.config = {
-  uri: "http://super-secret-scim.com/scim/v2/",
-  headers: {
-    "Authorization": "Beaer very-secret"
-  }
-  debug: $stdout,
-}
+```ruby
+Rails.application.config.to_prepare do
+  Audiences::Notifications.subscribe Group, job: UpdateGroupMembershipsJob
+  Audiences::Notifications.subscribe Team, job: UpdateTeamMembershipsJob.set(queue: "low")
+end
 ```
 
+You can find a working example in our dummy app:
+
+- [initializer](../spec/dummy/config/initializers/audiences.rb)
+- [job class](../spec/dummy/app/jobs/update_memberships_job.rb)
+
 ## Installation
 
 Add this line to your application's Gemfile:

data/lib/audiences/notifications.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Audiences
+  # Handles notification of audience context changes. The notifications handled
+  # by this module are related to the membership composition of a context.
+  #
+  # For instance, when a user leaves a group, the app will be notified of changes
+  # to the members of that context so it can react to that. When the audience
+  # configuration of a context changes, a notification will also be published
+  # through `Audiences::Notifications`.
+  #
+  module Notifications
+    mattr_reader :subscriptions, default: {}
+
+  module_function
+
+    # Subscribes to audience changes to a specific owner type, either with a
+    # background job or a callable block
+    #
+    # @param owner_type [Class] the type of owners handled by the job or block
+    # @param job [Class<ActiveJob::Base>] job that will respond to audience changes
+    # @yield block that will handle the audience change if a job is not given
+    #
+    def subscribe(owner_type, job: nil, &cbk)
+      subscriptions[owner_type] = job&.method(:perform_later) || cbk
+    end
+
+    # Notifies that a given audience context was changed
+    #
+    # @param context [Audiences::Context] updated context
+    #
+    def publish(context)
+      subscriptions[context.owner.class]&.call(context)
+    end
+  end
+end

data/lib/audiences/scim/client.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "json"
+require "uri"
+
+module Audiences
+  module Scim
+    class Client
+      def initialize(uri:, headers: {})
+        @uri = uri
+        @headers = headers
+      end
+
+      def perform_request(method:, path:, query: {})
+        uri = URI.join(@uri, path.to_s)
+        uri.query = URI.encode_www_form(query)
+        request = ::Net::HTTP.const_get(method).new(uri, @headers)
+
+        http = ::Net::HTTP.new(uri.host, uri.port)
+        http.use_ssl = uri.scheme == "https"
+
+        response = http.request(request)
+
+        JSON.parse(response.body)
+      end
+    end
+  end
+end

data/lib/audiences/scim/resources_query.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "json"
+require "uri"
+
+module Audiences
+  module Scim
+    class ResourcesQuery
+      include Enumerable
+
+      attr_reader :query_options
+
+      def initialize(client, resource_type:, **query_options)
+        @client = client
+        @resource_type = resource_type
+        @query_options = query_options
+      end
+
+      def all
+        to_enum(:each, all: true)
+      end
+
+      def each(all: false, &block)
+        resources.each(&block)
+        next_page&.each(all: true, &block) if all
+      end
+
+      def resources
+        @resources ||= response.fetch("Resources", [])
+      end
+
+      def next_page?
+        start_index = response.fetch("startIndex", 1)
+        per_page = response["itemsPerPage"].to_i
+        total_results = response["totalResults"].to_i
+
+        start_index + per_page <= total_results
+      end
+
+      def next_page
+        return unless next_page?
+
+        current_page = @query_options.fetch(:page, 1)
+        ResourcesQuery.new(@client, resource_type: @resource_type, **@query_options,
+                                    page: current_page + 1)
+      end
+
+    private
+
+      def response
+        @response ||= @client.perform_request(path: @resource_type, method: :Get, query: @query_options)
+      end
+    end
+  end
+end

data/lib/audiences/scim.rb

@@ -0,0 +1,19 @@
+# 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")
+
+  module_function
+
+    def resources(type:, client: Scim.client, **options)
+      options = defaults.fetch(type, {}).merge(options)
+
+      ResourcesQuery.new(client, resource_type: type, **options)
+    end
+  end
+end

data/lib/audiences/version.rb

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

data/lib/audiences.rb

@@ -1,6 +1,8 @@
 # frozen_string_literal: true
 
 require "audiences/version"
+require "audiences/scim"
+require "audiences/notifications"
 
 # Audiences system
 # Audiences pushes notifications to your rails app when a
@@ -27,7 +29,33 @@ module_function
   # @return Audience::Context
   #
   def load(key)
+    locate_context(key, &:readonly!)
+  end
+
+  # Updates the given context
+  #
+  # Params might contain:
+  #
+  # match_all: Boolean
+  # criteria: Array<{ <group_type>: Array<Integer> }>
+  #
+  # @param token [String] a signed token (see #sign)
+  # @param params [Hash] the updated params
+  # @return Audience::Context
+  #
+  def update(key, criteria: [], **attrs)
+    locate_context(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.where(owner: owner).first_or_create!.tap(&:readonly!)
+    ::Audiences::Context.for(owner).tap(&block)
   end
 end

data/lib/tasks/audiences_tasks.rake

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
+
 # desc "Explaining what the task does"
 # task :audiences do
 #   # Task goes here

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: audiences
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 1.0.1
 platform: ruby
 authors:
 - Carlos Palhares
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2023-08-16 00:00:00.000000000 Z
+date: 2024-04-25 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -39,23 +39,39 @@ files:
 - app/jobs/audiences/application_job.rb
 - app/models/audiences/application_record.rb
 - app/models/audiences/context.rb
-- app/views/layouts/audiences/application.html.erb
+- app/models/audiences/context_users.rb
+- app/models/audiences/criterion.rb
+- app/models/audiences/criterion_users.rb
+- app/models/audiences/external_user.rb
+- app/models/audiences/membership.rb
+- app/models/audiences/users_search.rb
+- app/models/concerns/audiences/membership_group.rb
 - config/routes.rb
 - db/migrate/20230725194934_create_audiences_contexts.rb
+- db/migrate/20231114210454_add_extra_users_to_audiences_context.rb
+- db/migrate/20231114210633_remove_criteria_from_audiences_context.rb
+- db/migrate/20231114215843_create_audiences_criterions.rb
+- db/migrate/20231115204932_add_users_to_audiences_criterion.rb
+- db/migrate/20231130165945_create_audiences_external_users.rb
+- db/migrate/20231130172718_create_audiences_memberships.rb
+- db/migrate/20231205140046_remove_serialized_users_from_criterion.rb
 - docs/CHANGELOG.md
 - docs/README.md
 - lib/audiences.rb
 - lib/audiences/engine.rb
-- lib/audiences/scim_proxy.rb
+- lib/audiences/notifications.rb
+- lib/audiences/scim.rb
+- lib/audiences/scim/client.rb
+- lib/audiences/scim/resources_query.rb
 - lib/audiences/version.rb
 - lib/tasks/audiences_tasks.rake
-homepage: https://github.com/powerhome/power-tools
+homepage: https://github.com/powerhome/audiences
 licenses:
 - MIT
 metadata:
-  homepage_uri: https://github.com/powerhome/power-tools
-  source_code_uri: https://github.com/powerhome/power-tools
-  changelog_uri: https://github.com/powerhome/power-tools/blob/main/packages/audiences/docs/CHANGELOG.md
+  homepage_uri: https://github.com/powerhome/audiences
+  source_code_uri: https://github.com/powerhome/audiences
+  changelog_uri: https://github.com/powerhome/audiences/blob/main/packages/audiences/docs/CHANGELOG.md
   rubygems_mfa_required: 'true'
 post_install_message:
 rdoc_options: []
@@ -72,7 +88,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.4.10
+rubygems_version: 3.5.9
 signing_key:
 specification_version: 4
 summary: Audiences system

data/app/views/layouts/audiences/application.html.erb

@@ -1,15 +0,0 @@
-<!DOCTYPE html>
-<html>
-<head>
-  <title>Audiences</title>
-  <%= csrf_meta_tags %>
-  <%= csp_meta_tag %>
-
-  <%= stylesheet_link_tag    "audiences/application", media: "all" %>
-</head>
-<body>
-
-<%= yield %>
-
-</body>
-</html>

data/lib/audiences/scim_proxy.rb

@@ -1,31 +0,0 @@
-# frozen_string_literal: true
-
-require "net/http"
-require "uri"
-
-module Audiences
-  module ScimProxy
-    mattr_accessor :config do
-      {}
-    end
-
-  module_function
-
-    def get(path, query)
-      response = perform_request(path: path, method: :Get, query: query)
-
-      [response.code, response.body]
-    end
-
-    private_class_method def perform_request(method:, path:, query: {})
-      uri = URI.join(config[:uri], path)
-      uri.query = URI.encode_www_form(query)
-      request = ::Net::HTTP.const_get(method).new(uri, config[:headers])
-
-      http = ::Net::HTTP.new(uri.host, uri.port)
-      http.use_ssl = uri.scheme == "https"
-
-      http.request(request)
-    end
-  end
-end