where_is_waldo 0.1.3 → 0.1.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b49938f0c49191db60463517da2d41115da11af0f7bb1c62f27065bb4598afc5
-  data.tar.gz: a247e74c4c86bb2e3188ad1f6b1b057d890b5daba01442ae0b2fd4b25786b60a
+  metadata.gz: 9caee3a6cb5747d9ce5ab460315fdaca5a9f05f7521dbe07f36a6d9fe5de48d9
+  data.tar.gz: f7e293f87b04039c7a2dbc21e6a80ef574a773438800588a9f87255b9336497a
 SHA512:
-  metadata.gz: 740783e4a9a19df3895bb62f113ff711f2d1815101e086388d604194beec71fe996803de241e0370f5685aa3d07f0ec5f1b4eff90fe654d19dd3f4cf9ac70436
-  data.tar.gz: be170741d609ae6d904c2f29a73637139d71f17bd4d54dfed6a2a8c6c9a3662f0624131c690d5af11a8c6676774bff4c149f9a17134b5bb72080f676c475e7bb
+  metadata.gz: 95e63474cdbfff6c224b4bc4882bba3fb96cb157bf73a7769a1755f8b6326cba60e19aee6b06fc8fb58fc483496a68f8aa3e6bd03513a1782802ca123f8b9cb7
+  data.tar.gz: 9abb3e965ddf1a13722e5700c2c3c8927c9b6b43593801e592670ec4ab09483ce2a3cf2da6a764dfbfb204e238a0107cbd9628067c5e06b0d7920a24412a0726

data/CHANGELOG.md

@@ -3,6 +3,98 @@
 Notable changes to where_is_waldo. Format loosely follows
 [Keep a Changelog](https://keepachangelog.com/).
 
+## 0.1.5
+
+### Security / correctness
+
+- **Session keys are now namespaced by subject_id.** Both adapters previously
+  keyed session rows by `session_id` alone (`waldo:session:<sid>` in Redis;
+  `unique_by: session_column` upsert in the DB). If two authenticated
+  subjects independently supplied the same `session_id` — client-supplied
+  values, JWT `jti` reuse across users, etc. — one subject's `connect`
+  would overwrite the other's row, and subsequent `heartbeat`/`disconnect`
+  calls could reach into the wrong subject's presence. Now:
+  - **RedisAdapter**: session key is `waldo:session:<subject_id>:<session_id>`.
+    The reverse-map key `waldo:session_subject:<session_id>` is removed —
+    callers must pass `subject_id` to `heartbeat`, `session_status`, and
+    session-scoped `disconnect`, so the disambiguation is at the API
+    boundary rather than a lookup that could return the wrong subject.
+  - **DatabaseAdapter**: `Presence.upsert(unique_by: [subject_column,
+    session_column])`. `heartbeat` / `session_status` / session-scoped
+    `disconnect` all scope by both keys. The install generator's migration
+    template now creates a composite unique index on `(subject_column,
+    session_column)` instead of a unique index on `session_column` alone.
+
+### Breaking API changes
+
+- `heartbeat` — `subject_id:` is now a required kwarg
+  (`heartbeat(session_id:, subject_id:, ...)`).
+- `session_status` — signature is `session_status(session_id, subject_id)`
+  (previously `session_status(session_id)`).
+- `disconnect(session_id:)` — now raises `ArgumentError` when called with
+  `session_id:` but no `subject_id:`. Subject-only `disconnect(subject_id:)`
+  and paired `disconnect(session_id:, subject_id:)` are the two supported
+  shapes.
+- `Broadcaster.broadcast_to_session(session_id, subject_id, message_type, data)`
+  — `subject_id` inserted as the second positional argument (previously
+  `broadcast_to_session(session_id, message_type, data)`).
+
+### DB migration
+
+Hosts on the `:database` adapter must swap the unique index on the presences
+table:
+```ruby
+remove_index :presences, :<session_column>
+add_index :presences, [:<subject_column>, :<session_column>], unique: true
+```
+
+## 0.1.4
+
+### Fixed
+
+- **Roster reads now route through the configured adapter.** Previously
+  `Roster.states_for` (which powers `state_for`, `snapshot`, `members_for`,
+  every roster delta) queried the `Presence` ActiveRecord model directly.
+  Under `adapter = :redis`, writes went to Redis but reads hit an empty (or
+  absent) database table — presence dots stayed grey no matter how many
+  heartbeats came in. `Roster` now calls `PresenceService.sessions_for_subjects`
+  which delegates to whichever adapter is configured, so writes and reads
+  share one store on every adapter.
+
+### Added
+
+- `Adapters::Base#sessions_for_subjects(subject_ids, timeout:)` — bulk-read
+  live sessions grouped by subject id, with a correct-but-unoptimized default
+  implementation that fans out over `sessions_for_subject`. `DatabaseAdapter`
+  overrides it with a single bulk query (`Presence.where(subject_col => ids)`
+  + `includes(:subject)`); `RedisAdapter` overrides with per-subject reads
+  filtered by heartbeat threshold. Timeout defaults to `config.timeout`.
+- `PresenceService.sessions_for_subjects` — public delegate so callers stay
+  off the adapter directly.
+- `Configuration#suppress_presence_proc` — callable that decides, per
+  connection, whether to skip presence registration for that subscriber.
+  Receives the ActionCable connection; returns truthy to suppress. A
+  suppressed subscriber still subscribes normally (streams from
+  `where_is_waldo:subject:<id>`, receives broadcasts, can invoke channel
+  actions) — they just don't register a Presence row / heartbeat / roster
+  transition. Use for cases where the WebSocket session is legitimate but
+  shouldn't be counted as "the subject is present" (e.g. support-user
+  impersonation tabs).
+
+  ```ruby
+  config.suppress_presence_proc = ->(connection) {
+    connection.request.session[:su_user].present?
+  }
+  ```
+
+### Changed
+
+- `Roster.aggregate` / `session_level` / `platform` now consume presence
+  hashes (`session[:tab_visible]`, `session[:metadata]`) — matching the
+  shape every adapter already returned — instead of ActiveRecord `Presence`
+  method calls. No behavior change for callers; existing per-device and
+  per-subject aggregation semantics preserved.
+
 ## 0.1.3
 
 ### Fixed

data/README.md

@@ -120,6 +120,16 @@ WhereIsWaldo.configure do |config|
   config.roster_org = ->(user) { user.account }
   config.roster_members = ->(org) { org.users.active }
 
+  # Optional: skip presence registration for specific connections while
+  # keeping them subscribed for broadcasts. Return truthy to suppress. The
+  # subscriber still streams from where_is_waldo:subject:<id> and receives
+  # WhereIsWaldo.broadcast_to messages — they just don't count as present.
+  # Typical use: support-user impersonation tabs shouldn't light up as the
+  # impersonated user in teammates' rosters.
+  config.suppress_presence_proc = ->(connection) {
+    connection.request.session[:su_user].present?
+  }
+
   # Redis adapter
   # config.redis_client = Redis.new(url: ENV["REDIS_URL"])
 end

data/VERSION

@@ -1 +1 @@
-0.1.3
+0.1.5

data/app/channels/where_is_waldo/presence_channel.rb

@@ -5,6 +5,13 @@ module WhereIsWaldo
     def subscribed
       stream_from subject_stream
 
+      # The subject_stream subscription above is unconditional: even when the
+      # subscriber's presence is suppressed (see suppress_presence_proc), the
+      # tab is a legitimate consumer of WhereIsWaldo.broadcast_to signaling
+      # and shouldn't be cut off from messages just because it doesn't count
+      # as "present."
+      return if presence_suppressed?
+
       register_presence
 
       # Seed the local transition gate, resolve the roster delivery strategy for
@@ -16,7 +23,9 @@ module WhereIsWaldo
     end
 
     def unsubscribed
-      WhereIsWaldo.disconnect(session_id: waldo_session_id)
+      return if presence_suppressed?
+
+      WhereIsWaldo.disconnect(session_id: waldo_session_id, subject_id: waldo_subject_id)
 
       # Recompute the subject's aggregate (they may still be present in another
       # tab/device) and announce the change to the org roster.
@@ -24,6 +33,8 @@ module WhereIsWaldo
     end
 
     def heartbeat(data)
+      return if presence_suppressed?
+
       data = data.with_indifferent_access
 
       tab_visible = data[:tab_visible] != false
@@ -31,6 +42,7 @@ module WhereIsWaldo
 
       WhereIsWaldo.heartbeat(
         session_id: waldo_session_id,
+        subject_id: waldo_subject_id,
         tab_visible: tab_visible,
         subject_active: subject_active,
         last_activity_at: data[:last_activity_at],
@@ -48,6 +60,22 @@ module WhereIsWaldo
 
     private
 
+    # Memoized per-subscription. Host apps configure suppress_presence_proc
+    # to gate WHICH subscriptions register presence — e.g. a support-user
+    # impersonation tab is a legitimate WS consumer but shouldn't count as
+    # the impersonated subject being "here." Nil proc → default behavior
+    # (presence always registered).
+    def presence_suppressed?
+      # Ivars are @wiw_-prefixed throughout this channel to avoid clobbering
+      # host-app ActionCable state; keep the prefix over the cop's rename.
+      # rubocop:disable Naming/MemoizedInstanceVariableName
+      return @wiw_presence_suppressed if defined?(@wiw_presence_suppressed)
+
+      proc = WhereIsWaldo.config.suppress_presence_proc
+      @wiw_presence_suppressed = proc ? !!proc.call(connection) : false
+      # rubocop:enable Naming/MemoizedInstanceVariableName
+    end
+
     def register_presence
       WhereIsWaldo.connect(
         session_id: waldo_session_id,

data/app/services/where_is_waldo/adapters/base_adapter.rb

@@ -12,9 +12,11 @@ module WhereIsWaldo
         raise NotImplementedError
       end
 
-      # Remove a presence
-      # @param session_id [String] Session identifier (optional if subject_id provided)
-      # @param subject_id [Integer/String] Subject identifier (optional)
+      # Remove a presence. Session-scoped disconnect requires both keys so
+      # a caller-supplied session_id can't disconnect another subject's row.
+      # Subject-only disconnect removes every session for that subject.
+      # @param session_id [String] Session identifier (requires subject_id when set)
+      # @param subject_id [Integer/String] Subject identifier
       # @return [Boolean] success
       def disconnect(session_id: nil, subject_id: nil)
         raise NotImplementedError
@@ -22,11 +24,14 @@ module WhereIsWaldo
 
       # Update heartbeat
       # @param session_id [String] Session identifier
+      # @param subject_id [Integer/String] Subject identifier (required —
+      #   pairs with session_id to disambiguate colliding session ids across
+      #   subjects)
       # @param tab_visible [Boolean] Is tab in foreground
       # @param subject_active [Boolean] Recent activity
       # @param metadata [Hash] Additional data
       # @return [Boolean] success
-      def heartbeat(session_id:, tab_visible: true, subject_active: true, metadata: {})
+      def heartbeat(session_id:, subject_id:, tab_visible: true, subject_active: true, metadata: {})
         raise NotImplementedError
       end
 
@@ -44,10 +49,31 @@ module WhereIsWaldo
         raise NotImplementedError
       end
 
+      # Get live sessions for many subjects in one call, grouped by subject id.
+      # Subjects with no live sessions are omitted from the returned hash.
+      # Adapters should override for efficiency; this default is a correct but
+      # unoptimized fan-out over `sessions_for_subject`.
+      # @param subject_ids [Array<Integer/String>] Subject identifiers
+      # @param timeout [Integer, nil] Seconds threshold; sessions with
+      #   `last_heartbeat` older than `Time.current - timeout` are excluded
+      # @return [Hash{Integer/String => Array<Hash>}] subject_id => sessions
+      def sessions_for_subjects(subject_ids, timeout: nil)
+        ids = Array(subject_ids).compact.uniq
+        return {} if ids.empty?
+
+        threshold = Time.current - (timeout || default_timeout)
+        ids.each_with_object({}) do |sid, memo|
+          live = sessions_for_subject(sid).select { |s| s[:last_heartbeat] && s[:last_heartbeat] >= threshold }
+          memo[sid] = live if live.any?
+        end
+      end
+
       # Get session status
       # @param session_id [String] Session identifier
+      # @param subject_id [Integer/String] Subject identifier — required
+      #   for the same reason as heartbeat (see above)
       # @return [Hash, nil] Presence record or nil
-      def session_status(session_id)
+      def session_status(session_id, subject_id)
         raise NotImplementedError
       end
 

data/app/services/where_is_waldo/adapters/database_adapter.rb

@@ -19,8 +19,12 @@ module WhereIsWaldo
           updated_at: now
         }
 
+        # (subject, session) is the unique key — see the install migration
+        # template. Keying on session alone would let a caller-supplied
+        # session_id colliding across two subjects upsert onto each other's
+        # row.
         # rubocop:disable Rails/SkipsModelValidations -- intentional for performance
-        Presence.upsert(attrs, unique_by: session_column)
+        Presence.upsert(attrs, unique_by: [subject_column, session_column])
         # rubocop:enable Rails/SkipsModelValidations
         true
       rescue StandardError => e
@@ -29,15 +33,21 @@ module WhereIsWaldo
       end
 
       def disconnect(session_id: nil, subject_id: nil)
+        raise ArgumentError, "disconnect(session_id:) requires subject_id:" if session_id && !subject_id
+
         scope = build_lookup_scope(session_id: session_id, subject_id: subject_id)
         scope.delete_all
         true
+      rescue ArgumentError
+        raise
       rescue StandardError => e
         Rails.logger.error "[WhereIsWaldo] Disconnect failed: #{e.message}"
         false
       end
 
-      def heartbeat(session_id:, tab_visible: true, subject_active: true, last_activity_at: nil, metadata: {})
+      # rubocop:disable Metrics/ParameterLists, Layout/LineLength
+      def heartbeat(session_id:, subject_id:, tab_visible: true, subject_active: true, last_activity_at: nil, metadata: {})
+        # rubocop:enable Metrics/ParameterLists, Layout/LineLength
         now = Time.current
         updates = {
           last_heartbeat: now,
@@ -53,7 +63,9 @@ module WhereIsWaldo
         end
         updates[:metadata] = metadata if metadata.present?
 
-        scope = Presence.where(session_column => session_id)
+        # Scope by both — a caller-supplied session_id shouldn't be able to
+        # heartbeat another subject's row.
+        scope = Presence.where(session_column => session_id, subject_column => subject_id)
 
         # rubocop:disable Rails/SkipsModelValidations -- intentional for performance
         scope.update_all(updates).positive?
@@ -77,8 +89,19 @@ module WhereIsWaldo
         scope.map(&:as_presence_hash)
       end
 
-      def session_status(session_id)
-        scope = Presence.where(session_column => session_id)
+      def sessions_for_subjects(subject_ids, timeout: nil)
+        ids = Array(subject_ids).compact.uniq
+        return {} if ids.empty?
+
+        threshold = (timeout || default_timeout).seconds.ago
+        scope = Presence.where(subject_column => ids).where("last_heartbeat > ?", threshold)
+        scope = scope.includes(:subject) if config.subject_class_constant
+        scope.group_by { |row| row[subject_column] }
+             .transform_values { |rows| rows.map(&:as_presence_hash) }
+      end
+
+      def session_status(session_id, subject_id)
+        scope = Presence.where(session_column => session_id, subject_column => subject_id)
         scope = scope.includes(:subject) if config.subject_class_constant
         scope.first&.as_presence_hash
       end
@@ -91,8 +114,8 @@ module WhereIsWaldo
       private
 
       def build_lookup_scope(session_id: nil, subject_id: nil)
-        if session_id
-          Presence.where(session_column => session_id)
+        if session_id && subject_id
+          Presence.where(session_column => session_id, subject_column => subject_id)
         elsif subject_id
           Presence.where(subject_column => subject_id)
         else

data/app/services/where_is_waldo/adapters/redis_adapter.rb

@@ -2,7 +2,9 @@
 
 module WhereIsWaldo
   module Adapters
-    class RedisAdapter < BaseAdapter
+    # Redis backing needs more plumbing (keying, TTLs, pipelines) than the
+    # DB adapter, so it legitimately runs past the default class-length limit.
+    class RedisAdapter < BaseAdapter # rubocop:disable Metrics/ClassLength
       def connect(session_id:, subject_id:, metadata: {})
         now = Time.current.to_i
 
@@ -18,17 +20,15 @@ module WhereIsWaldo
         }
 
         redis.multi do |tx|
-          # Store session data
-          tx.set(session_key(session_id), presence_data.to_json, ex: ttl)
+          # Session key includes subject_id so two subjects with the same
+          # caller-supplied session_id can't overwrite each other's row.
+          tx.set(session_key(subject_id, session_id), presence_data.to_json, ex: ttl)
 
           # Add to online subjects sorted set with timestamp as score
           tx.zadd(online_subjects_key, now, subject_id)
 
           # Add to subject's sessions set
           tx.sadd(subject_sessions_key(subject_id), session_id)
-
-          # Map session to subject for reverse lookup
-          tx.set(session_subject_key(session_id), subject_id, ex: ttl)
         end
 
         true
@@ -39,19 +39,25 @@ module WhereIsWaldo
 
       def disconnect(session_id: nil, subject_id: nil)
         if session_id
-          disconnect_session(session_id)
+          raise ArgumentError, "disconnect(session_id:) requires subject_id:" unless subject_id
+
+          disconnect_session(subject_id, session_id)
         elsif subject_id
           disconnect_subject(subject_id)
         end
 
         true
+      rescue ArgumentError
+        raise
       rescue StandardError => e
         Rails.logger.error "[WhereIsWaldo] Redis disconnect failed: #{e.message}"
         false
       end
 
-      def heartbeat(session_id:, tab_visible: true, subject_active: true, last_activity_at: nil, metadata: {})
-        data = get_presence_data(session_id)
+      # rubocop:disable Metrics/ParameterLists, Layout/LineLength
+      def heartbeat(session_id:, subject_id:, tab_visible: true, subject_active: true, last_activity_at: nil, metadata: {})
+        # rubocop:enable Metrics/ParameterLists, Layout/LineLength
+        data = get_presence_data(subject_id, session_id)
         return false unless data
 
         now = Time.current.to_i
@@ -67,7 +73,7 @@ module WhereIsWaldo
         data["metadata"] = data["metadata"].merge(metadata) if metadata.present?
 
         redis.multi do |tx|
-          tx.set(session_key(session_id), data.to_json, ex: ttl)
+          tx.set(session_key(subject_id, session_id), data.to_json, ex: ttl)
           tx.zadd(online_subjects_key, now, data["subject_id"])
         end
 
@@ -88,13 +94,30 @@ module WhereIsWaldo
         session_ids = redis.smembers(subject_sessions_key(subject_id))
 
         session_ids.filter_map do |sid|
-          data = get_presence_data(sid)
+          data = get_presence_data(subject_id, sid)
           build_presence_hash(data) if data
         end
       end
 
-      def session_status(session_id)
-        data = get_presence_data(session_id)
+      def sessions_for_subjects(subject_ids, timeout: nil)
+        ids = Array(subject_ids).compact.uniq
+        return {} if ids.empty?
+
+        threshold = Time.current.to_i - (timeout || default_timeout)
+        ids.each_with_object({}) do |sid, memo|
+          session_ids = redis.smembers(subject_sessions_key(sid))
+          live = session_ids.filter_map do |cid|
+            data = get_presence_data(sid, cid)
+            next unless data && data["last_heartbeat"].to_i >= threshold
+
+            build_presence_hash(data)
+          end
+          memo[sid] = live if live.any?
+        end
+      end
+
+      def session_status(session_id, subject_id)
+        data = get_presence_data(subject_id, session_id)
         return nil unless data
 
         build_presence_hash(data)
@@ -111,7 +134,7 @@ module WhereIsWaldo
           # Check if any sessions are still active
           session_ids = redis.smembers(subject_sessions_key(subject_id))
           all_stale = session_ids.all? do |sid|
-            data = get_presence_data(sid)
+            data = get_presence_data(subject_id, sid)
             !data || data["last_heartbeat"].to_i < threshold
           end
 
@@ -141,8 +164,11 @@ module WhereIsWaldo
         config.redis_prefix || "where_is_waldo"
       end
 
-      def session_key(session_id)
-        "#{key_prefix}:session:#{session_id}"
+      # Session data key. Namespaced by subject_id so a caller-supplied
+      # session_id colliding across two authenticated subjects doesn't let one
+      # clobber the other's presence row (see CHANGELOG 0.1.5).
+      def session_key(subject_id, session_id)
+        "#{key_prefix}:session:#{subject_id}:#{session_id}"
       end
 
       def online_subjects_key
@@ -153,27 +179,17 @@ module WhereIsWaldo
         "#{key_prefix}:subject:#{subject_id}:sessions"
       end
 
-      def session_subject_key(session_id)
-        "#{key_prefix}:session_subject:#{session_id}"
-      end
-
-      def get_presence_data(session_id)
-        json = redis.get(session_key(session_id))
+      def get_presence_data(subject_id, session_id)
+        json = redis.get(session_key(subject_id, session_id))
         return nil unless json
 
         JSON.parse(json)
       end
 
-      def disconnect_session(session_id)
-        data = get_presence_data(session_id)
-        return unless data
-
-        subject_id = data["subject_id"]
-
+      def disconnect_session(subject_id, session_id)
         redis.multi do |tx|
-          tx.del(session_key(session_id))
+          tx.del(session_key(subject_id, session_id))
           tx.srem(subject_sessions_key(subject_id), session_id)
-          tx.del(session_subject_key(session_id))
         end
 
         # If no more sessions for this subject, remove from online set
@@ -183,7 +199,7 @@ module WhereIsWaldo
 
       def disconnect_subject(subject_id)
         session_ids = redis.smembers(subject_sessions_key(subject_id))
-        session_ids.each { |sid| disconnect_session(sid) }
+        session_ids.each { |sid| disconnect_session(subject_id, sid) }
         redis.zrem(online_subjects_key, subject_id)
       end
 

data/app/services/where_is_waldo/broadcaster.rb

@@ -35,14 +35,16 @@ module WhereIsWaldo
 
       # Broadcast to a specific session
       # @param session_id [String] Session identifier
+      # @param subject_id [Integer/String] Subject identifier — required
+      #   to disambiguate colliding session ids across subjects
       # @param message_type [String, Symbol] Message type
       # @param data [Hash] Message payload
-      def broadcast_to_session(session_id, message_type, data = {})
-        status = PresenceService.session_status(session_id)
+      def broadcast_to_session(session_id, subject_id, message_type, data = {})
+        status = PresenceService.session_status(session_id, subject_id)
         return false unless status
 
         message = build_message(message_type, data, target_session: session_id)
-        ActionCable.server.broadcast(subject_stream(status[:subject_id]), message)
+        ActionCable.server.broadcast(subject_stream(subject_id), message)
         true
       end
 

data/app/services/where_is_waldo/presence_service.rb

@@ -29,14 +29,20 @@ module WhereIsWaldo
 
       # Update heartbeat for a session
       # @param session_id [String] Session identifier
+      # @param subject_id [Integer/String] Subject identifier (required —
+      #   pairs with session_id to disambiguate colliding session ids across
+      #   subjects)
       # @param tab_visible [Boolean] Is tab in foreground
       # @param subject_active [Boolean] Recent activity
       # @param last_activity_at [Integer] Unix timestamp (ms) of last user activity
       # @param metadata [Hash] Additional data to merge
       # @return [Boolean] success
-      def heartbeat(session_id:, tab_visible: true, subject_active: true, last_activity_at: nil, metadata: {})
+      # rubocop:disable Metrics/ParameterLists, Layout/LineLength
+      def heartbeat(session_id:, subject_id:, tab_visible: true, subject_active: true, last_activity_at: nil, metadata: {})
+        # rubocop:enable Metrics/ParameterLists, Layout/LineLength
         adapter.heartbeat(
           session_id: session_id,
+          subject_id: subject_id,
           tab_visible: tab_visible,
           subject_active: subject_active,
           last_activity_at: last_activity_at,
@@ -74,8 +80,19 @@ module WhereIsWaldo
       # @return [Array<Hash>] Presence records
       delegate :sessions_for_subject, to: :adapter
 
+      # Get live sessions for many subjects in one call, grouped by subject id.
+      # Preferred over calling `sessions_for_subject` per id when the caller
+      # already has an id list (e.g. roster aggregation) — adapters can (and do)
+      # implement this as a bulk read.
+      # @param subject_ids [Array<Integer/String>] Subject identifiers
+      # @param timeout [Integer, nil] Seconds threshold (defaults to config.timeout)
+      # @return [Hash{Integer/String => Array<Hash>}] subject_id => sessions
+      delegate :sessions_for_subjects, to: :adapter
+
       # Get status of a specific session
       # @param session_id [String] Session identifier
+      # @param subject_id [Integer/String] Subject identifier — required
+      #   for the same reason as heartbeat
       # @return [Hash, nil] Presence record or nil
       delegate :session_status, to: :adapter
 

data/app/services/where_is_waldo/roster.rb

@@ -165,25 +165,24 @@ module WhereIsWaldo
 
       private
 
-      # Aggregate state for many subjects in one query, keyed by subject id.
+      # Aggregate state for many subjects in one adapter call, keyed by
+      # subject id. Routes through PresenceService so it matches whichever
+      # adapter is configured — reading Presence directly would only work on
+      # `:database`, but the roster snapshot needs to see whatever the writer
+      # sees under `:redis` too.
       def states_for(subject_ids, timeout: nil)
         ids = Array(subject_ids).compact.uniq
         return {} if ids.empty?
 
-        threshold = (timeout || WhereIsWaldo.config.timeout).seconds.ago
-        subject_col = Presence.subject_column
-
-        rows = Presence.where(subject_col => ids)
-                       .where("last_heartbeat > ?", threshold)
-                       .to_a
-
-        rows.group_by { |row| row[subject_col] }
-            .transform_values { |sessions| aggregate(sessions) }
+        WhereIsWaldo::PresenceService
+          .sessions_for_subjects(ids, timeout: timeout)
+          .transform_values { |sessions| aggregate(sessions) }
       end
 
       # Reduce a subject's live sessions to per-device statuses plus an overall
       # roll-up. Sessions are grouped by platform (so several browser tabs form
       # one "web" status); the overall status is the highest across platforms.
+      # @param sessions [Array<Hash>] presence hashes from the adapter
       # @return [Hash] { status: "active", devices: { "web" => "active", ... } }
       def aggregate(sessions)
         devices = sessions.group_by { |s| platform(s) }
@@ -204,13 +203,13 @@ module WhereIsWaldo
       # a hidden tab / backgrounded app is :background; a visible/foreground
       # session is :active when working, else :idle.
       def session_level(session)
-        return :background unless session.tab_visible
+        return :background unless session[:tab_visible]
 
-        session.subject_active ? :active : :idle
+        session[:subject_active] ? :active : :idle
       end
 
       def platform(session)
-        meta = session.metadata
+        meta = session[:metadata]
         value = meta && (meta["platform"] || meta[:platform])
         (value.presence || DEFAULT_PLATFORM).to_s
       end

data/lib/generators/where_is_waldo/install/templates/create_presences.rb.tt

@@ -22,10 +22,15 @@ class Create<%= table_name.camelize %> < ActiveRecord::Migration[7.0]
       t.timestamps
     end
 
-    # Session must be unique
-    add_index :<%= table_name %>, :<%= session_column %>, unique: true
-
-    # Query by subject
+    # (subject, session) must be unique together. Keying by session alone
+    # would let two authenticated subjects that happen to collide on a
+    # session id (client-supplied values, JWT jti reuse, etc.) upsert onto
+    # each other's row.
+    add_index :<%= table_name %>, [:<%= subject_column %>, :<%= session_column %>], unique: true
+
+    # Session lookups (heartbeat, disconnect, session_status) always scope
+    # by (subject, session); the composite unique index above serves those.
+    # Query by subject alone
     add_index :<%= table_name %>, :<%= subject_column %>
 
     # Cleanup old records

data/lib/where_is_waldo/configuration.rb

@@ -32,6 +32,23 @@ module WhereIsWaldo
     # :authenticate_proc - proc to authenticate connection, receives request
     attr_accessor :channel_name, :authenticate_proc
 
+    # :suppress_presence_proc - callable that decides, per connection, whether
+    #   to SKIP presence registration for that subscriber. Receives the
+    #   ActionCable connection (host apps can read session/cookies/env off it,
+    #   e.g. via `connection.request`). Returns truthy to suppress.
+    #
+    # A suppressed subscriber still subscribes normally — they receive
+    # broadcasts to `where_is_waldo:subject:<id>` (WhereIsWaldo.broadcast_to*
+    # signaling) and any other Waldo capability — they just don't register a
+    # Presence row / heartbeat / roster transition. Use for cases where the
+    # WebSocket session is legitimate but shouldn't be counted as "the subject
+    # is present", e.g. support-user impersonation tabs.
+    #
+    #   config.suppress_presence_proc = ->(connection) {
+    #     connection.request.session[:su_user].present?
+    #   }
+    attr_accessor :suppress_presence_proc
+
     # Default audience resolver for the Broadcastable concern. A lambda that,
     # given a record, returns the AR scope to broadcast to (e.g. that record's
     # account members). Set once per app to match its container, e.g.:
@@ -106,6 +123,7 @@ module WhereIsWaldo
       # ActionCable defaults
       @channel_name = "WhereIsWaldo::PresenceChannel"
       @authenticate_proc = nil
+      @suppress_presence_proc = nil
 
       # Broadcastable default audience (set per app)
       @broadcast_audience = nil

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: where_is_waldo
 version: !ruby/object:Gem::Version
-  version: 0.1.3
+  version: 0.1.5
 platform: ruby
 authors:
 - Scott Gibson
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-07-23 00:00:00.000000000 Z
+date: 2026-07-24 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails