where_is_waldo 0.1.1

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

@@ -0,0 +1,205 @@
+# frozen_string_literal: true
+
+module WhereIsWaldo
+  module Adapters
+    class RedisAdapter < BaseAdapter
+      def connect(session_id:, subject_id:, metadata: {})
+        now = Time.current.to_i
+
+        presence_data = {
+          session_id: session_id,
+          subject_id: subject_id,
+          connected_at: now,
+          last_heartbeat: now,
+          tab_visible: true,
+          subject_active: true,
+          last_activity: now,
+          metadata: metadata
+        }
+
+        redis.multi do |tx|
+          # Store session data
+          tx.set(session_key(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
+      rescue StandardError => e
+        Rails.logger.error "[WhereIsWaldo] Redis connect failed: #{e.message}"
+        false
+      end
+
+      def disconnect(session_id: nil, subject_id: nil)
+        if session_id
+          disconnect_session(session_id)
+        elsif subject_id
+          disconnect_subject(subject_id)
+        end
+
+        true
+      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)
+        return false unless data
+
+        now = Time.current.to_i
+        data["last_heartbeat"] = now
+        data["tab_visible"] = tab_visible
+        data["subject_active"] = subject_active
+        # Update last_activity: use JS timestamp if provided, otherwise use current time when active
+        if last_activity_at
+          data["last_activity"] = (last_activity_at / 1000.0).to_i
+        elsif subject_active
+          data["last_activity"] = now
+        end
+        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.zadd(online_subjects_key, now, data["subject_id"])
+        end
+
+        true
+      rescue StandardError => e
+        Rails.logger.error "[WhereIsWaldo] Redis heartbeat failed: #{e.message}"
+        false
+      end
+
+      def online_subject_ids(timeout: nil)
+        threshold = Time.current.to_i - (timeout || default_timeout)
+
+        # Get subject IDs with heartbeat after threshold
+        redis.zrangebyscore(online_subjects_key, threshold, "+inf").map(&:to_i)
+      end
+
+      def sessions_for_subject(subject_id)
+        session_ids = redis.smembers(subject_sessions_key(subject_id))
+
+        session_ids.filter_map do |sid|
+          data = get_presence_data(sid)
+          build_presence_hash(data) if data
+        end
+      end
+
+      def session_status(session_id)
+        data = get_presence_data(session_id)
+        return nil unless data
+
+        build_presence_hash(data)
+      end
+
+      def cleanup(timeout: nil)
+        threshold = Time.current.to_i - (timeout || default_timeout)
+        cleaned = 0
+
+        # Get stale subject IDs
+        stale_subject_ids = redis.zrangebyscore(online_subjects_key, "-inf", threshold)
+
+        stale_subject_ids.each do |subject_id|
+          # 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 || data["last_heartbeat"].to_i < threshold
+          end
+
+          if all_stale
+            disconnect_subject(subject_id)
+            cleaned += 1
+          end
+        end
+
+        # Remove stale entries from sorted set
+        redis.zremrangebyscore(online_subjects_key, "-inf", threshold)
+
+        cleaned
+      end
+
+      private
+
+      def redis
+        config.redis_client || raise("Redis client not configured")
+      end
+
+      def ttl
+        (config.timeout * 1.5).to_i # Give some buffer beyond timeout
+      end
+
+      def key_prefix
+        config.redis_prefix || "where_is_waldo"
+      end
+
+      def session_key(session_id)
+        "#{key_prefix}:session:#{session_id}"
+      end
+
+      def online_subjects_key
+        "#{key_prefix}:online_subjects"
+      end
+
+      def subject_sessions_key(subject_id)
+        "#{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))
+        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"]
+
+        redis.multi do |tx|
+          tx.del(session_key(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
+        remaining = redis.scard(subject_sessions_key(subject_id))
+        redis.zrem(online_subjects_key, subject_id) if remaining.zero?
+      end
+
+      def disconnect_subject(subject_id)
+        session_ids = redis.smembers(subject_sessions_key(subject_id))
+        session_ids.each { |sid| disconnect_session(sid) }
+        redis.zrem(online_subjects_key, subject_id)
+      end
+
+      def build_presence_hash(data)
+        {
+          session_id: data["session_id"],
+          subject_id: data["subject_id"],
+          connected_at: Time.zone.at(data["connected_at"]),
+          last_heartbeat: Time.zone.at(data["last_heartbeat"]),
+          last_activity: data["last_activity"] ? Time.zone.at(data["last_activity"]) : nil,
+          tab_visible: data["tab_visible"],
+          subject_active: data["subject_active"],
+          metadata: data["metadata"] || {},
+          subject: nil # Redis adapter doesn't eager load subjects
+        }
+      end
+    end
+  end
+end

data/app/services/where_is_waldo/broadcaster.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+module WhereIsWaldo
+  class Broadcaster
+    class << self
+      # Broadcast a message to subjects in an AR scope
+      # @param scope [ActiveRecord::Relation, ActiveRecord::Base] Subjects to broadcast to
+      # @param message_type [String, Symbol] Message type for client handler routing
+      # @param data [Hash] Message payload
+      def broadcast_to(scope, message_type, data = {})
+        subject_ids = extract_subject_ids(scope)
+        return if subject_ids.empty?
+
+        message = build_message(message_type, data)
+
+        subject_ids.each do |subject_id|
+          ActionCable.server.broadcast(subject_stream(subject_id), message)
+        end
+      end
+
+      # Broadcast to online subjects only (from an AR scope)
+      # @param scope [ActiveRecord::Relation] Scope to filter
+      # @param message_type [String, Symbol] Message type
+      # @param data [Hash] Message payload
+      def broadcast_to_online(scope, message_type, data = {})
+        online_ids = PresenceService.online_ids(scope)
+        return if online_ids.empty?
+
+        message = build_message(message_type, data)
+
+        online_ids.each do |subject_id|
+          ActionCable.server.broadcast(subject_stream(subject_id), message)
+        end
+      end
+
+      # Broadcast to a specific session
+      # @param session_id [String] Session identifier
+      # @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)
+        return false unless status
+
+        message = build_message(message_type, data, target_session: session_id)
+        ActionCable.server.broadcast(subject_stream(status[:subject_id]), message)
+        true
+      end
+
+      private
+
+      def extract_subject_ids(scope)
+        case scope
+        when ActiveRecord::Relation
+          scope.pluck(:id)
+        when ActiveRecord::Base
+          [scope.id]
+        when Array
+          scope.map { |s| s.respond_to?(:id) ? s.id : s }
+        else
+          Array(scope)
+        end
+      end
+
+      def build_message(message_type, data, target_session: nil)
+        msg = {
+          type: message_type.to_s,
+          data: data,
+          timestamp: Time.current.iso8601
+        }
+        msg[:_target_session] = target_session if target_session
+        msg
+      end
+
+      def subject_stream(subject_id)
+        "where_is_waldo:subject:#{subject_id}"
+      end
+    end
+  end
+end

data/app/services/where_is_waldo/presence_service.rb

@@ -0,0 +1,119 @@
+# frozen_string_literal: true
+
+module WhereIsWaldo
+  class PresenceService
+    class << self
+      # Register a new presence
+      # @param session_id [String] Unique session identifier
+      # @param subject_id [Integer/String] Subject identifier (user, member, etc.)
+      # @param metadata [Hash] Additional data
+      # @return [Boolean] success
+      def connect(session_id:, subject_id:, metadata: {})
+        adapter.connect(
+          session_id: session_id,
+          subject_id: subject_id,
+          metadata: metadata
+        )
+      end
+
+      # Remove a presence by session, or all presences for a subject
+      # @param session_id [String] Session identifier (optional)
+      # @param subject_id [Integer/String] Subject identifier (optional)
+      # @return [Boolean] success
+      def disconnect(session_id: nil, subject_id: nil)
+        adapter.disconnect(
+          session_id: session_id,
+          subject_id: subject_id
+        )
+      end
+
+      # Update heartbeat for a session
+      # @param session_id [String] Session identifier
+      # @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: {})
+        adapter.heartbeat(
+          session_id: session_id,
+          tab_visible: tab_visible,
+          subject_active: subject_active,
+          last_activity_at: last_activity_at,
+          metadata: metadata
+        )
+      end
+
+      # Get online subjects from an AR scope
+      # @param scope [ActiveRecord::Relation] Scope to filter
+      # @param timeout [Integer] Seconds threshold (defaults to config.timeout)
+      # @return [ActiveRecord::Relation] Online subjects from the scope
+      def online(scope, timeout: nil)
+        online_ids = adapter.online_subject_ids(timeout: timeout)
+        scope.where(id: online_ids)
+      end
+
+      # Get online subject IDs from an AR scope
+      # @param scope [ActiveRecord::Relation] Scope to filter
+      # @param timeout [Integer] Seconds threshold (defaults to config.timeout)
+      # @return [Array<Integer>] Online subject IDs
+      def online_ids(scope, timeout: nil)
+        online_ids = adapter.online_subject_ids(timeout: timeout)
+        scope.where(id: online_ids).pluck(:id)
+      end
+
+      # Get all online subject IDs (no scope filtering)
+      # @param timeout [Integer] Seconds threshold
+      # @return [Array<Integer>]
+      def all_online_ids(timeout: nil)
+        adapter.online_subject_ids(timeout: timeout)
+      end
+
+      # Get all sessions for a subject
+      # @param subject_id [Integer/String] Subject identifier
+      # @return [Array<Hash>] Presence records
+      delegate :sessions_for_subject, to: :adapter
+
+      # Get status of a specific session
+      # @param session_id [String] Session identifier
+      # @return [Hash, nil] Presence record or nil
+      delegate :session_status, to: :adapter
+
+      # Check if a subject is online
+      # @param subject_id [Integer/String] Subject identifier
+      # @return [Boolean]
+      def subject_online?(subject_id)
+        sessions_for_subject(subject_id).any?
+      end
+
+      # Cleanup stale records
+      # @param timeout [Integer] Seconds threshold (defaults to config.timeout)
+      # @return [Integer] Number of records removed
+      def cleanup(timeout: nil)
+        adapter.cleanup(timeout: timeout)
+      end
+
+      private
+
+      def adapter
+        @adapter ||= build_adapter
+      end
+
+      def build_adapter
+        case WhereIsWaldo.config.adapter
+        when :database
+          Adapters::DatabaseAdapter.new
+        when :redis
+          Adapters::RedisAdapter.new
+        else
+          raise ArgumentError, "Unknown adapter: #{WhereIsWaldo.config.adapter}"
+        end
+      end
+
+      # Reset adapter (useful for testing or config changes)
+      def reset_adapter!
+        @adapter = nil
+      end
+    end
+  end
+end

data/app/services/where_is_waldo/roster.rb

@@ -0,0 +1,246 @@
+# frozen_string_literal: true
+
+module WhereIsWaldo
+  # Live presence roster for an org/account: "who's around, and how present are
+  # they right now." Built for efficiency — a single shared ActionCable stream
+  # per org, an initial snapshot on subscribe, and compact deltas broadcast only
+  # on state transitions (never on steady-state heartbeats).
+  #
+  # A member's presence is reported per device AND as an overall roll-up:
+  #
+  #   { id: 7, status: "active", devices: { "web" => "active", "mobile" => "idle" } }
+  #
+  # `devices[platform]` is that platform's own aggregate status (several browser
+  # tabs roll up into one "web" status); `status` is the highest level across
+  # all platforms — the "is the user active anywhere?" answer, while
+  # `devices["mobile"]` answers "is the user active on mobile?". Each status is:
+  #
+  #   active      - a live session on that device is tab-visible AND working
+  #   idle        - a live session is tab-visible but not actively using
+  #   background  - only backgrounded/hidden sessions are live (tab hidden or
+  #                 mobile app backgrounded)
+  #   offline     - no live sessions (overall status only; absent from devices)
+  #
+  # Enable by configuring `roster_org` (and optionally `roster_members`).
+  class Roster
+    # Activity ranking used to pick a subject's aggregate status from the "most
+    # present" of their sessions.
+    RANK = { active: 3, idle: 2, background: 1, offline: 0 }.freeze
+    DEFAULT_PLATFORM = "web"
+
+    class << self
+      # Shared stream name for an org record (nil when org is absent).
+      def stream_name(org)
+        return nil unless org
+
+        klass = org.class.respond_to?(:base_class) ? org.class.base_class : org.class
+        "where_is_waldo:roster:#{klass.name}:#{org.id}"
+      end
+
+      # Shared stream name for the org a subject belongs to (nil when the roster
+      # is unconfigured or the subject has no org).
+      def stream_for_subject(subject)
+        stream_name(WhereIsWaldo.config.resolve_roster_org(subject))
+      end
+
+      # Full roster state for an org: every member subject with their current
+      # aggregate presence. Sent once, on subscribe.
+      # @return [Array<Hash>] member state hashes
+      def snapshot(org, timeout: nil)
+        members = WhereIsWaldo.config.resolve_members(org)
+        return [] unless members
+
+        members_for(members, timeout: timeout).values
+      end
+
+      # Member states for an arbitrary AR scope of subjects, keyed by id. Used
+      # by :poll to snapshot / diff a viewer's visible scope.
+      # @return [Hash{Object => Hash}] id => member hash
+      def members_for(scope, timeout: nil)
+        return {} unless scope
+
+        records = scope.to_a
+        states = states_for(records.map(&:id), timeout: timeout)
+        records.to_h { |record| [record.id, build_member(record, states[record.id])] }
+      end
+
+      # === Cable message builders — identical shapes across every delivery mode
+      # so the client reducer never forks ===
+
+      def snapshot_message(members, mode:)
+        message = { type: "roster_snapshot", mode: mode.to_s, members: members }
+        message[:poll_interval] = WhereIsWaldo.config.roster_poll_interval if %i[poll nudge].include?(mode.to_sym)
+        message[:nudge_jitter] = WhereIsWaldo.config.roster_nudge_jitter if mode.to_sym == :nudge
+        message
+      end
+
+      def delta_message(member)
+        { type: "roster_delta", member: member }
+      end
+
+      # Content-free "roster changed, re-poll" trigger (:nudge mode). Carries no
+      # identity/state, so it leaks nothing beyond "activity happened".
+      def nudge_message
+        { type: "roster_nudge" }
+      end
+
+      # Tells the client to drop a member who left the viewer's visible scope
+      # (distinct from going offline, which stays present with status "offline").
+      def removed_message(subject_id)
+        { type: "roster_delta", member: { id: subject_id, _removed: true } }
+      end
+
+      # Aggregate presence state for a single subject across all their sessions.
+      # @return [Hash] { status:, devices: { platform => status } }
+      def state_for(subject_id, timeout: nil)
+        states_for([subject_id], timeout: timeout).fetch(subject_id, offline_state)
+      end
+
+      # Presence status for a subject on a specific device/platform, e.g.
+      #   WhereIsWaldo::Roster.device_status(user.id, :mobile) # => "idle"
+      # Answers "is the user active on mobile?" vs the overall state_for.
+      # @return [String] "active" | "idle" | "background" | "offline"
+      def device_status(subject_id, platform, timeout: nil)
+        state_for(subject_id, timeout: timeout)[:devices][platform.to_s] || "offline"
+      end
+
+      # Broadcast a compact delta for one subject to their org roster stream.
+      # Intended to be called ONLY on transitions (connect/disconnect/active
+      # flip). No-ops safely when the roster is unconfigured or the subject has
+      # no org. Recomputes the subject's aggregate so multi-session state (e.g.
+      # a second tab still active) is always correct.
+      def publish(subject_id, timeout: nil)
+        return false if subject_id.blank?
+
+        subject = find_subject(subject_id)
+        stream = stream_name(WhereIsWaldo.config.resolve_roster_org(subject))
+        return false unless stream
+
+        member = build_member_by_id(subject, subject_id, timeout: timeout)
+        ActionCable.server.broadcast(stream, delta_message(member))
+        true
+      rescue StandardError => e
+        Rails.logger&.warn("[WhereIsWaldo::Roster] publish failed for #{subject_id}: #{e.class}: #{e.message}")
+        false
+      end
+
+      # Per-viewer stream (:fanout mode). Each viewer streams only their own.
+      def viewer_stream(viewer_id)
+        "where_is_waldo:roster:viewer:#{viewer_id}"
+      end
+
+      # Push a subject's delta to every viewer allowed to see them (:fanout
+      # mode). Directional audience (config.roster_viewers_of) makes this correct
+      # for arbitrary/asymmetric visibility, at O(audience) broadcasts.
+      def publish_fanout(subject_id, timeout: nil)
+        return false if subject_id.blank?
+
+        subject = find_subject(subject_id)
+        audience = subject && WhereIsWaldo.config.resolve_viewers_of(subject)
+        return false unless audience
+
+        message = delta_message(build_member_by_id(subject, subject_id, timeout: timeout))
+        audience.pluck(:id).each { |viewer_id| ActionCable.server.broadcast(viewer_stream(viewer_id), message) }
+        true
+      rescue StandardError => e
+        Rails.logger&.warn("[WhereIsWaldo::Roster] fanout failed for #{subject_id}: #{e.class}: #{e.message}")
+        false
+      end
+
+      # Broadcast a content-free nudge to a subject's org roster stream (:nudge
+      # mode). Tells watchers to re-poll; carries no protected data.
+      def publish_nudge(subject_id)
+        return false if subject_id.blank?
+
+        subject = find_subject(subject_id)
+        stream = stream_name(WhereIsWaldo.config.resolve_roster_org(subject))
+        return false unless stream
+
+        ActionCable.server.broadcast(stream, nudge_message)
+        true
+      rescue StandardError => e
+        Rails.logger&.warn("[WhereIsWaldo::Roster] nudge failed for #{subject_id}: #{e.class}: #{e.message}")
+        false
+      end
+
+      private
+
+      # Aggregate state for many subjects in one query, keyed by subject id.
+      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) }
+      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.
+      # @return [Hash] { status: "active", devices: { "web" => "active", ... } }
+      def aggregate(sessions)
+        devices = sessions.group_by { |s| platform(s) }
+                          .transform_values { |sess| platform_level(sess) }
+        overall = devices.values.max_by { |level| RANK[level] } || :offline
+        {
+          status: overall.to_s,
+          devices: devices.transform_values(&:to_s)
+        }
+      end
+
+      # Aggregate activity level for the sessions on one platform.
+      def platform_level(sessions)
+        sessions.map { |s| session_level(s) }.max_by { |level| RANK[level] } || :offline
+      end
+
+      # Activity level of one live session. Uniform across web and mobile:
+      # 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
+
+        session.subject_active ? :active : :idle
+      end
+
+      def platform(session)
+        meta = session.metadata
+        value = meta && (meta["platform"] || meta[:platform])
+        (value.presence || DEFAULT_PLATFORM).to_s
+      end
+
+      # Build a member hash from an already-loaded state map entry.
+      def build_member(record, state)
+        merge_member(record, state || offline_state)
+      end
+
+      # Build a member hash by recomputing the subject's aggregate state.
+      def build_member_by_id(record, subject_id, timeout: nil)
+        merge_member(record, state_for(subject_id, timeout: timeout), id: subject_id)
+      end
+
+      def merge_member(record, state, id: nil)
+        data = record ? WhereIsWaldo.config.build_subject_data(record) : {}
+        data.merge(
+          id: id || record&.id,
+          status: state[:status],
+          devices: state[:devices]
+        )
+      end
+
+      def offline_state
+        { status: "offline", devices: {} }
+      end
+
+      def find_subject(subject_id)
+        WhereIsWaldo.config.subject_class_constant&.find_by(id: subject_id)
+      end
+    end
+  end
+end