where_is_waldo 0.1.1

data/app/channels/where_is_waldo/presence_channel.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+module WhereIsWaldo
+  class PresenceChannel < ApplicationCable::Channel
+    def subscribed
+      stream_from subject_stream
+
+      register_presence
+
+      # Seed the local transition gate, resolve the roster delivery strategy for
+      # this subject's account once, and announce arrival.
+      @wiw_tab_visible = true
+      @wiw_subject_active = true
+      @wiw_roster_strategy = resolve_roster_strategy
+      publish_roster_change
+    end
+
+    def unsubscribed
+      WhereIsWaldo.disconnect(session_id: waldo_session_id)
+
+      # Recompute the subject's aggregate (they may still be present in another
+      # tab/device) and announce the change to the org roster.
+      publish_roster_change
+    end
+
+    def heartbeat(data)
+      data = data.with_indifferent_access
+
+      tab_visible = data[:tab_visible] != false
+      subject_active = data[:subject_active] != false
+
+      WhereIsWaldo.heartbeat(
+        session_id: waldo_session_id,
+        tab_visible: tab_visible,
+        subject_active: subject_active,
+        last_activity_at: data[:last_activity_at],
+        metadata: data[:metadata] || {}
+      )
+
+      # Efficiency: only touch the roster when THIS session's activity/visibility
+      # actually flips. Steady-state heartbeats (no change) cost zero broadcasts.
+      return unless roster_transition?(tab_visible, subject_active)
+
+      @wiw_tab_visible = tab_visible
+      @wiw_subject_active = subject_active
+      publish_roster_change
+    end
+
+    private
+
+    def register_presence
+      WhereIsWaldo.connect(
+        session_id: waldo_session_id,
+        subject_id: waldo_subject_id,
+        metadata: params[:metadata] || {}
+      )
+    end
+
+    def roster_transition?(tab_visible, subject_active)
+      tab_visible != @wiw_tab_visible || subject_active != @wiw_subject_active
+    end
+
+    # Resolve the roster delivery strategy for this subject's account, once, at
+    # subscribe. nil when the roster isn't configured or the subject has no org.
+    def resolve_roster_strategy
+      return nil unless WhereIsWaldo.config.roster_enabled?
+
+      subject = WhereIsWaldo.config.subject_class_constant&.find_by(id: waldo_subject_id)
+      org = subject && WhereIsWaldo.config.resolve_roster_org(subject)
+      return nil unless org
+
+      WhereIsWaldo::RosterDelivery.for(WhereIsWaldo.config.resolve_mode(org))
+    end
+
+    # Let the delivery strategy react to a presence transition. For :poll this
+    # is a no-op (clients poll); for :broadcast it pushes a delta to the account
+    # stream. Gated to actual transitions by the heartbeat handler.
+    def publish_roster_change
+      @wiw_roster_strategy&.on_transition(waldo_subject_id)
+    end
+
+    def subject_stream
+      "where_is_waldo:subject:#{waldo_subject_id}"
+    end
+  end
+end

data/app/channels/where_is_waldo/roster_channel.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module WhereIsWaldo
+  # Roster subscription. The delivery mode is resolved per account at subscribe
+  # time (config.roster_mode) and dispatched to the matching RosterDelivery
+  # strategy; the client is told the mode via the snapshot and adapts (listen
+  # vs. poll). A subject can only ever see their OWN account's roster (org is
+  # derived from the authenticated connection), so it's safe by construction.
+  #
+  # Modes:
+  #   :broadcast - stream_from the shared account stream; deltas are pushed.
+  #   :poll      - no stream; the client calls #poll and gets a filtered diff.
+  class RosterChannel < ApplicationCable::Channel
+    def subscribed
+      subject = current_subject
+      mode = resolve_mode(subject)
+      return reject unless mode
+
+      @wiw_subject = subject
+      @wiw_strategy = RosterDelivery.for(mode)
+      apply_plan(@wiw_strategy.subscribe_plan(subject, waldo_session_id))
+    end
+
+    # Client-driven poll (pull/nudge modes). Transmits a filtered snapshot
+    # (first call / resync) or diff since the last poll for this session.
+    def poll
+      return unless @wiw_strategy
+
+      @wiw_strategy.poll_messages(@wiw_subject, waldo_session_id).each { |message| transmit(message) }
+    end
+
+    private
+
+    def resolve_mode(subject)
+      org = WhereIsWaldo.config.resolve_roster_org(subject)
+      return nil unless org
+
+      WhereIsWaldo.config.resolve_mode(org)
+    end
+
+    def apply_plan(plan)
+      plan[:streams].each { |stream| stream_from(stream) }
+      plan[:messages].each { |message| transmit(message) }
+    end
+
+    def current_subject
+      return nil unless waldo_subject_id
+
+      WhereIsWaldo.config.subject_class_constant&.find_by(id: waldo_subject_id)
+    end
+  end
+end

data/app/jobs/where_is_waldo/application_job.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module WhereIsWaldo
+  class ApplicationJob < ActiveJob::Base
+  end
+end

data/app/jobs/where_is_waldo/presence_cleanup_job.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module WhereIsWaldo
+  class PresenceCleanupJob < ApplicationJob
+    queue_as :default
+
+    def perform(timeout: nil)
+      cleaned = PresenceService.cleanup(timeout: timeout)
+      Rails.logger.info "[WhereIsWaldo] Cleaned up #{cleaned} stale presence records"
+      cleaned
+    end
+  end
+end

data/app/models/concerns/where_is_waldo/broadcastable.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+module WhereIsWaldo
+  # Opt a model into real-time broadcasting. Include the concern and declare
+  # which lifecycle events should push over the cable:
+  #
+  #   class Person < ApplicationRecord
+  #     include WhereIsWaldo::Broadcastable
+  #     broadcasts_realtime                                   # create + update + destroy
+  #   end
+  #
+  #   broadcasts_realtime on: %i[create update]               # subset
+  #   broadcasts_realtime on: :update, if: -> { saved_change_to_status? }
+  #   broadcasts_realtime scope: ->(rec) { rec.organization.users }
+  #
+  # Event names follow "<model>_<verb>" — created / update / destroyed — e.g.
+  # person_created, person_update, person_destroyed (matching the convention
+  # issuesbyscott already uses). The client subscribes with useWaldoEvent.
+  #
+  # Audience defaults to `WhereIsWaldo.configuration.broadcast_audience` (set
+  # once per app, e.g. ->(rec) { rec.account.users }); override per model with
+  # `scope:`. Payload defaults to a minimal `{ id: }` (so clients refetch);
+  # override `realtime_payload` on the model to push a richer shape for
+  # patch-in-place rendering.
+  module Broadcastable
+    extend ActiveSupport::Concern
+
+    HOOKS = {
+      create: %i[after_create_commit created],
+      update: %i[after_update_commit update],
+      destroy: %i[after_destroy_commit destroyed]
+    }.freeze
+
+    class_methods do
+      def broadcasts_realtime(on: %i[create update destroy], scope: nil, **guard)
+        guard = guard.slice(:if, :unless)
+        Array(on).each do |event|
+          hook, verb = HOOKS.fetch(event.to_sym) do
+            raise ArgumentError, "broadcasts_realtime: unknown event #{event.inspect}"
+          end
+          # Block form runs in instance context; `verb`/`scope` are captured.
+          public_send(hook, **guard) { wiw_broadcast(verb, scope) }
+        end
+      end
+    end
+
+    # Override on the model to shape the payload (default: minimal { id: }).
+    def realtime_payload
+      { id: id }
+    end
+
+    private
+
+    def wiw_broadcast(verb, scope)
+      return unless defined?(::WhereIsWaldo)
+
+      audience = wiw_audience(scope)
+      return if audience.blank?
+
+      ::WhereIsWaldo.broadcast_to(audience, wiw_event_name(verb), wiw_payload(verb))
+    rescue StandardError => e
+      Rails.logger&.warn(
+        "[WhereIsWaldo::Broadcastable] #{self.class.name}##{id} #{verb} broadcast failed: #{e.class}: #{e.message}"
+      )
+    end
+
+    def wiw_audience(scope)
+      resolver = scope || ::WhereIsWaldo.configuration.broadcast_audience
+      return nil unless resolver
+
+      instance_exec(self, &resolver)
+    end
+
+    def wiw_event_name(verb)
+      # Use the STI base class so subclasses (e.g. Widget::Grid) broadcast the
+      # base event name ("widget_update"), not the subclass ("grid_update").
+      klass = self.class.respond_to?(:base_class) ? self.class.base_class : self.class
+      "#{klass.model_name.element}_#{verb}"
+    end
+
+    def wiw_payload(verb)
+      verb == :destroyed ? { id: id } : realtime_payload
+    end
+  end
+end

data/app/models/where_is_waldo/application_record.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module WhereIsWaldo
+  class ApplicationRecord < ActiveRecord::Base
+    self.abstract_class = true
+  end
+end

data/app/models/where_is_waldo/presence.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+module WhereIsWaldo
+  class Presence < ApplicationRecord
+    self.table_name = -> { WhereIsWaldo.config.table_name }
+
+    # Ensure metadata column works with any database (jsonb, json, or text)
+    # This makes the column portable across PostgreSQL, MySQL, and SQLite
+    attribute :metadata, :json
+
+    class << self
+      def table_name
+        tn = WhereIsWaldo.config.table_name
+        tn.respond_to?(:call) ? tn.call : tn
+      end
+
+      def configure_associations!
+        subject_class = WhereIsWaldo.config.subject_class_constant
+        return unless subject_class
+
+        subject_col = WhereIsWaldo.config.subject_column
+        # rubocop:disable Rails/InverseOf -- dynamic association, inverse not applicable
+        belongs_to :subject,
+                   class_name: subject_class.name,
+                   foreign_key: subject_col,
+                   optional: true
+        # rubocop:enable Rails/InverseOf
+      end
+
+      # Dynamic column accessors
+      def session_column
+        WhereIsWaldo.config.session_column
+      end
+
+      def subject_column
+        WhereIsWaldo.config.subject_column
+      end
+    end
+
+    # Scopes
+    scope :online, lambda { |timeout: nil|
+      threshold = (timeout || WhereIsWaldo.config.timeout).seconds.ago
+      where("last_heartbeat > ?", threshold)
+    }
+
+    scope :for_subject, lambda { |subject_id|
+      where(WhereIsWaldo.config.subject_column => subject_id)
+    }
+
+    scope :for_subjects, lambda { |subject_ids|
+      where(WhereIsWaldo.config.subject_column => subject_ids)
+    }
+
+    scope :visible_tab, -> { where(tab_visible: true) }
+    scope :active, -> { where(subject_active: true) }
+
+    # Convert to hash for API responses
+    def as_presence_hash
+      config = WhereIsWaldo.config
+
+      {
+        session_id: self[config.session_column],
+        subject_id: self[config.subject_column],
+        connected_at: connected_at&.iso8601,
+        last_heartbeat: last_heartbeat&.iso8601,
+        tab_visible: tab_visible,
+        subject_active: subject_active,
+        last_activity: last_activity&.iso8601,
+        metadata: metadata,
+        subject: subject_data
+      }
+    end
+
+    # Check if this presence is considered online
+    def online?(timeout: nil)
+      threshold = (timeout || WhereIsWaldo.config.timeout).seconds.ago
+      last_heartbeat && last_heartbeat > threshold
+    end
+
+    private
+
+    def subject_data
+      subject_record = try(:subject)
+      WhereIsWaldo.config.build_subject_data(subject_record)
+    end
+  end
+end

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

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+module WhereIsWaldo
+  module Adapters
+    class BaseAdapter
+      # Register a 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: {})
+        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)
+      # @return [Boolean] success
+      def disconnect(session_id: nil, subject_id: nil)
+        raise NotImplementedError
+      end
+
+      # Update heartbeat
+      # @param session_id [String] Session identifier
+      # @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: {})
+        raise NotImplementedError
+      end
+
+      # Get all online subject IDs
+      # @param timeout [Integer] Seconds threshold
+      # @return [Array<Integer>] Subject IDs
+      def online_subject_ids(timeout: nil)
+        raise NotImplementedError
+      end
+
+      # Get all sessions for a subject
+      # @param subject_id [Integer/String] Subject identifier
+      # @return [Array<Hash>] Presence records
+      def sessions_for_subject(subject_id)
+        raise NotImplementedError
+      end
+
+      # Get session status
+      # @param session_id [String] Session identifier
+      # @return [Hash, nil] Presence record or nil
+      def session_status(session_id)
+        raise NotImplementedError
+      end
+
+      # Remove stale records
+      # @param timeout [Integer] Seconds threshold
+      # @return [Integer] Number removed
+      def cleanup(timeout: nil)
+        raise NotImplementedError
+      end
+
+      protected
+
+      def config
+        WhereIsWaldo.config
+      end
+
+      def default_timeout
+        config.timeout
+      end
+
+      def session_column
+        config.session_column
+      end
+
+      def subject_column
+        config.subject_column
+      end
+    end
+  end
+end

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

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+module WhereIsWaldo
+  module Adapters
+    class DatabaseAdapter < BaseAdapter
+      def connect(session_id:, subject_id:, metadata: {})
+        now = Time.current
+
+        attrs = {
+          session_column => session_id,
+          subject_column => subject_id,
+          connected_at: now,
+          last_heartbeat: now,
+          tab_visible: true,
+          subject_active: true,
+          last_activity: now,
+          metadata: metadata,
+          created_at: now,
+          updated_at: now
+        }
+
+        # rubocop:disable Rails/SkipsModelValidations -- intentional for performance
+        Presence.upsert(attrs, unique_by: session_column)
+        # rubocop:enable Rails/SkipsModelValidations
+        true
+      rescue StandardError => e
+        Rails.logger.error "[WhereIsWaldo] Connect failed: #{e.message}"
+        false
+      end
+
+      def disconnect(session_id: nil, subject_id: nil)
+        scope = build_lookup_scope(session_id: session_id, subject_id: subject_id)
+        scope.delete_all
+        true
+      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: {})
+        now = Time.current
+        updates = {
+          last_heartbeat: now,
+          tab_visible: tab_visible,
+          subject_active: subject_active,
+          updated_at: now
+        }
+        # Update last_activity: use JS timestamp if provided, otherwise use current time when active
+        if last_activity_at
+          updates[:last_activity] = Time.zone.at(last_activity_at / 1000.0)
+        elsif subject_active
+          updates[:last_activity] = now
+        end
+        updates[:metadata] = metadata if metadata.present?
+
+        scope = Presence.where(session_column => session_id)
+
+        # rubocop:disable Rails/SkipsModelValidations -- intentional for performance
+        scope.update_all(updates).positive?
+        # rubocop:enable Rails/SkipsModelValidations
+      rescue StandardError => e
+        Rails.logger.error "[WhereIsWaldo] Heartbeat failed: #{e.message}"
+        false
+      end
+
+      def online_subject_ids(timeout: nil)
+        threshold = (timeout || default_timeout).seconds.ago
+
+        Presence.where("last_heartbeat > ?", threshold)
+                .distinct
+                .pluck(subject_column)
+      end
+
+      def sessions_for_subject(subject_id)
+        scope = Presence.where(subject_column => subject_id)
+        scope = scope.includes(:subject) if config.subject_class_constant
+        scope.map(&:as_presence_hash)
+      end
+
+      def session_status(session_id)
+        scope = Presence.where(session_column => session_id)
+        scope = scope.includes(:subject) if config.subject_class_constant
+        scope.first&.as_presence_hash
+      end
+
+      def cleanup(timeout: nil)
+        threshold = (timeout || default_timeout).seconds.ago
+        Presence.where(last_heartbeat: ...threshold).delete_all
+      end
+
+      private
+
+      def build_lookup_scope(session_id: nil, subject_id: nil)
+        if session_id
+          Presence.where(session_column => session_id)
+        elsif subject_id
+          Presence.where(subject_column => subject_id)
+        else
+          Presence.none
+        end
+      end
+    end
+  end
+end