where_is_waldo 0.1.1

data/app/services/where_is_waldo/roster_delivery.rb

@@ -0,0 +1,184 @@
+# frozen_string_literal: true
+
+module WhereIsWaldo
+  # Pluggable roster delivery strategies. Each app picks a mode per account (via
+  # config.roster_mode); the channels dispatch to the matching strategy. The
+  # data model (aggregation) and the wire message shapes are shared across all
+  # modes — only the *transport/trigger* differs, so the client reducer never
+  # forks.
+  #
+  # Strategies are pure/stateless (any state lives in Rails.cache): they COMPUTE
+  # streams + messages and perform cache/broadcast side effects, but the channel
+  # owns the actual ActionCable `transmit`/`stream_from`.
+  module RosterDelivery
+    module_function
+
+    # Resolve a strategy instance for a mode symbol.
+    def for(mode)
+      case mode.to_sym
+      when :broadcast then Broadcast.new
+      when :poll then Poll.new
+      when :nudge then Nudge.new
+      when :fanout then Fanout.new
+      else
+        raise ArgumentError, "Unknown roster_mode: #{mode.inspect}"
+      end
+    end
+
+    # Base contract. Channels call these; return values drive the channel's I/O.
+    class Base
+      # @return [Hash] { streams: [names], messages: [cable messages] }
+      def subscribe_plan(_subject, _session_id)
+        { streams: [], messages: [] }
+      end
+
+      # @return [Array<Hash>] cable messages to transmit to the polling client
+      def poll_messages(_subject, _session_id)
+        []
+      end
+
+      # Side effect on a presence transition (usually a broadcast). No return.
+      def on_transition(_subject_id); end
+
+      protected
+
+      def config
+        WhereIsWaldo.config
+      end
+    end
+
+    # Instant push to a single shared per-account stream. NO visibility
+    # filtering — everyone in the account sees everyone. O(1) per transition.
+    class Broadcast < Base
+      def subscribe_plan(subject, _session_id)
+        org = config.resolve_roster_org(subject)
+        stream = Roster.stream_name(org)
+        return { streams: [], messages: [] } unless stream
+
+        {
+          streams: [stream],
+          messages: [Roster.snapshot_message(Roster.snapshot(org), mode: :broadcast)]
+        }
+      end
+
+      def on_transition(subject_id)
+        Roster.publish(subject_id)
+      end
+    end
+
+    # Heartbeat/poll pull: the client polls; the server transmits a per-viewer,
+    # server-filtered snapshot (first poll / resync) or diff (subsequent). The
+    # diff baseline lives in Rails.cache keyed per session (tab), TTL'd so a
+    # stale/expired cursor self-heals into a full snapshot. Handles ANY
+    # visibility rule via config.roster_visible_to. No broadcasts.
+    class Poll < Base
+      # Overridden by :nudge so the snapshot advertises the right mode.
+      def mode
+        :poll
+      end
+
+      def subscribe_plan(subject, session_id)
+        current = current_members(subject)
+        write_baseline(session_id, current)
+        { streams: subscribe_streams(subject), messages: [Roster.snapshot_message(current.values, mode: mode)] }
+      end
+
+      def poll_messages(subject, session_id)
+        current = current_members(subject)
+        baseline = read_baseline(session_id)
+        write_baseline(session_id, current)
+
+        # Cache miss / expired cursor -> full snapshot (self-healing resync).
+        return [Roster.snapshot_message(current.values, mode: mode)] if baseline.nil?
+
+        diff_messages(baseline, current)
+      end
+
+      # No push work on transition — pull clients poll for changes.
+      def on_transition(_subject_id); end
+
+      private
+
+      # Streams to subscribe on connect. :poll needs none (data rides the poll
+      # transmit); :nudge overrides this to also receive the account nudge.
+      def subscribe_streams(_subject)
+        []
+      end
+
+      def current_members(subject)
+        Roster.members_for(config.resolve_visible_to(subject))
+      end
+
+      def diff_messages(baseline, current)
+        messages = []
+        current.each do |id, member|
+          prev = baseline[id]
+          messages << Roster.delta_message(member) if prev.nil? || presence_changed?(prev, member)
+        end
+        # Members that left the viewer's visible scope entirely (a visibility
+        # change) — tell the client to drop them.
+        (baseline.keys - current.keys).each do |gone_id|
+          messages << Roster.removed_message(gone_id)
+        end
+        messages
+      end
+
+      def presence_changed?(prev, member)
+        prev[:status] != member[:status] || prev[:devices] != member[:devices]
+      end
+
+      def read_baseline(session_id)
+        Rails.cache.read(baseline_key(session_id))
+      end
+
+      def write_baseline(session_id, members)
+        Rails.cache.write(baseline_key(session_id), members, expires_in: config.roster_cache_ttl)
+      end
+
+      def baseline_key(session_id)
+        "where_is_waldo:roster:baseline:#{session_id}"
+      end
+    end
+
+    # Poll, plus a content-free nudge broadcast on transition so clients re-poll
+    # immediately instead of waiting for the next interval — near-instant
+    # latency with the same server-filtered (arbitrary-visibility) delivery. The
+    # nudge carries no identity/state, so it only reveals "activity happened".
+    class Nudge < Poll
+      def mode
+        :nudge
+      end
+
+      def on_transition(subject_id)
+        Roster.publish_nudge(subject_id)
+      end
+
+      private
+
+      # Also subscribe the account stream so this client receives nudges.
+      def subscribe_streams(subject)
+        stream = Roster.stream_name(config.resolve_roster_org(subject))
+        stream ? [stream] : []
+      end
+    end
+
+    # Instant per-viewer push for arbitrary/asymmetric visibility. Each viewer
+    # streams only their own stream and gets a server-filtered snapshot on
+    # connect; on a transition the subject's delta is pushed to every viewer in
+    # its directional audience (config.roster_viewers_of). O(audience) per
+    # transition — the price of instant delivery under restricted visibility.
+    class Fanout < Base
+      def subscribe_plan(subject, _session_id)
+        members = Roster.members_for(config.resolve_visible_to(subject))
+        {
+          streams: [Roster.viewer_stream(subject.id)],
+          messages: [Roster.snapshot_message(members.values, mode: :fanout)]
+        }
+      end
+
+      def on_transition(subject_id)
+        Roster.publish_fanout(subject_id)
+      end
+    end
+  end
+end

data/lib/generators/where_is_waldo/install/install_generator.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+require "rails/generators/active_record"
+
+module WhereIsWaldo
+  module Generators
+    class InstallGenerator < Rails::Generators::Base
+      include ActiveRecord::Generators::Migration
+
+      source_root File.expand_path("templates", __dir__)
+
+      class_option :adapter, type: :string, default: "database",
+                             desc: "Storage adapter (database or redis)"
+      class_option :auth_method, type: :string, default: "jwt",
+                                 desc: "Authentication method (jwt, devise, custom)"
+      class_option :subject_class, type: :string, default: "User",
+                                   desc: "The model class being tracked (User, Member, etc.)"
+      class_option :subject_column, type: :string, default: "user_id",
+                                    desc: "Foreign key column name for the subject"
+      class_option :session_column, type: :string, default: "jti",
+                                    desc: "Column name for session identifier"
+
+      def create_initializer
+        template "initializer.rb.tt", "config/initializers/where_is_waldo.rb"
+      end
+
+      def generate_migration
+        return if adapter == "redis"
+
+        migration_template "migration.rb.tt", "db/migrate/create_presences.rb"
+      end
+
+      def create_channels
+        template "connection.rb.tt", "app/channels/application_cable/connection.rb"
+        template "channel.rb.tt", "app/channels/application_cable/channel.rb"
+        template "presence_channel.rb.tt", "app/channels/presence_channel.rb"
+      end
+
+      def show_post_install_message
+        say ""
+        say "WhereIsWaldo installed successfully!", :green
+        say ""
+        say "Next steps:"
+        say "  1. Review config/initializers/where_is_waldo.rb"
+        if adapter == "redis"
+          say "  2. Ensure REDIS_URL is configured"
+        else
+          say "  2. Run: rails db:migrate"
+        end
+        say "  3. Configure your frontend PresenceProvider:"
+        say ""
+        say "     <PresenceProvider config={{ channelName: 'PresenceChannel' }}>"
+        say "       <App />"
+        say "     </PresenceProvider>"
+        say ""
+      end
+
+      private
+
+      def migration_version
+        "[#{ActiveRecord::VERSION::STRING.to_f}]"
+      end
+
+      def subject_class
+        options[:subject_class]
+      end
+
+      def subject_column
+        options[:subject_column]
+      end
+
+      def session_column
+        options[:session_column]
+      end
+
+      def auth_method
+        options[:auth_method]
+      end
+
+      def adapter
+        options[:adapter]
+      end
+
+      # Detect database adapter and return appropriate JSON column type
+      def json_column_type
+        adapter_name = ActiveRecord::Base.connection.adapter_name.downcase
+        case adapter_name
+        when /postgresql/, /postgis/
+          :jsonb
+        when /mysql/, /trilogy/
+          :json
+        else
+          # SQLite and others - use text with serialization
+          :text
+        end
+      rescue StandardError
+        # If we can't detect, default to text (most portable)
+        :text
+      end
+    end
+  end
+end

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

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module ApplicationCable
+  class Channel < ActionCable::Channel::Base
+  end
+end

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

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module ApplicationCable
+  class Connection < ActionCable::Connection::Base
+<%- if auth_method == "jwt" -%>
+    # Turnkey corebyscott JWT auth: decodes the ?token= param, identifies the
+    # connection by current_user / current_container / session_id. Requires
+    # corebyscott. See WhereIsWaldo::JwtConnection to customize.
+    include WhereIsWaldo::JwtConnection
+<%- elsif auth_method == "devise" -%>
+    identified_by :current_<%= subject_column.sub(/_id$/, '') %>, :session_id
+
+    def connect
+      self.current_<%= subject_column.sub(/_id$/, '') %> = find_verified_subject
+      self.session_id = find_session_id
+    end
+
+    private
+
+    def find_verified_subject
+      # Find user from Devise session cookie
+      env["warden"].user || reject_unauthorized_connection
+    end
+
+    def find_session_id
+      # Use Warden session key or generate new one
+      request.session.id || SecureRandom.uuid
+    end
+<%- else -%>
+    identified_by :current_<%= subject_column.sub(/_id$/, '') %>, :session_id
+
+    def connect
+      self.current_<%= subject_column.sub(/_id$/, '') %> = find_verified_subject
+      self.session_id = find_session_id
+    end
+
+    private
+
+    def find_verified_subject
+      # TODO: Implement your authentication logic here
+      # Return the authenticated subject or call reject_unauthorized_connection
+      raise NotImplementedError, "Implement find_verified_subject in ApplicationCable::Connection"
+    end
+
+    def find_session_id
+      # TODO: Return a unique session identifier (unique per browser tab)
+      SecureRandom.uuid
+    end
+<%- end -%>
+  end
+end

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

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+class Create<%= table_name.camelize %> < ActiveRecord::Migration[7.0]
+  def change
+    create_table :<%= table_name %> do |t|
+      # Identifiers - column names are configurable
+      t.string :<%= session_column %>, null: false    # Unique session/connection identifier
+      t.bigint :<%= subject_column %>, null: false    # Who (user, member, student, etc.)
+
+      # Timestamps
+      t.datetime :connected_at, null: false
+      t.datetime :last_heartbeat, null: false
+      t.datetime :last_activity
+
+      # Activity state
+      t.boolean :tab_visible, default: true, null: false
+      t.boolean :subject_active, default: true, null: false
+
+      # Extensible metadata
+      t.<%= json_column_type %> :metadata
+
+      t.timestamps
+    end
+
+    # Session must be unique
+    add_index :<%= table_name %>, :<%= session_column %>, unique: true
+
+    # Query by subject
+    add_index :<%= table_name %>, :<%= subject_column %>
+
+    # Cleanup old records
+    add_index :<%= table_name %>, :last_heartbeat
+
+<% if subject_table.present? -%>
+    # Foreign key to subject table
+    add_foreign_key :<%= table_name %>, :<%= subject_table %>, column: :<%= subject_column %>
+<% end -%>
+  end
+end

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

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+WhereIsWaldo.configure do |config|
+  # Storage adapter: :database or :redis
+  config.adapter = :<%= adapter %>
+<% if adapter == "redis" %>
+  # Redis configuration
+  # config.redis_client = Redis.new(url: ENV["REDIS_URL"])
+  # config.redis_prefix = "where_is_waldo"
+<% else %>
+  # Table name for presence records
+  config.table_name = "presences"
+<% end %>
+
+  # Column names
+  config.session_column = :<%= session_column %>
+  config.subject_column = :<%= subject_column %>
+
+  # Subject model class
+  config.subject_class = "<%= subject_class %>"
+
+  # Build subject data for presence responses
+  config.subject_data_proc = ->(subject) {
+    return {} unless subject
+    {
+      id: subject.id,
+      # Add more fields as needed:
+      # first_name: subject.first_name,
+      # last_name: subject.last_name,
+      # email: subject.email,
+    }
+  }
+
+  # Timing
+  config.timeout = 90           # seconds until considered offline
+  config.heartbeat_interval = 30 # expected heartbeat frequency
+end

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

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+class CreatePresences < ActiveRecord::Migration<%= migration_version %>
+  def change
+    create_table :presences do |t|
+      t.string :<%= session_column %>, null: false
+      t.references :<%= subject_column.sub(/_id$/, '') %>, null: false, foreign_key: true
+      t.datetime :connected_at, null: false
+      t.datetime :last_heartbeat, null: false
+      t.datetime :last_activity
+      t.boolean :tab_visible, default: true, null: false
+      t.boolean :subject_active, default: true, null: false
+      t.<%= json_column_type %> :metadata
+      t.timestamps
+    end
+
+    add_index :presences, :<%= session_column %>, unique: true
+    add_index :presences, :last_heartbeat
+  end
+end

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

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+class PresenceChannel < ApplicationCable::Channel
+  def subscribed
+    stream_from subject_stream
+    register_presence
+  end
+
+  def unsubscribed
+    WhereIsWaldo.disconnect(session_id: connection.session_id)
+  end
+
+  def heartbeat(data)
+    data = data.with_indifferent_access
+
+    WhereIsWaldo.heartbeat(
+      session_id: connection.session_id,
+      tab_visible: data[:tab_visible] != false,
+      subject_active: data[:subject_active] != false,
+      metadata: data[:metadata] || {}
+    )
+  end
+
+  private
+
+  def register_presence
+    WhereIsWaldo.connect(
+      session_id: connection.session_id,
+      subject_id: connection.current_<%= subject_column.sub(/_id$/, '') %>.id,
+      metadata: params[:metadata] || {}
+    )
+  end
+
+  def subject_stream
+    "where_is_waldo:subject:#{connection.current_<%= subject_column.sub(/_id$/, '') %>.id}"
+  end
+end

data/lib/where_is_waldo/configuration.rb

@@ -0,0 +1,209 @@
+# frozen_string_literal: true
+
+module WhereIsWaldo
+  class Configuration
+    # Storage settings
+    # :adapter - :database or :redis
+    # :table_name - defaults to 'presences'
+    # :redis_client - custom Redis instance (optional)
+    # :redis_prefix - key prefix for Redis (for multi-app setups)
+    attr_accessor :adapter, :table_name, :redis_client, :redis_prefix
+
+    # Column names - fully configurable
+    # :session_column - unique identifier per connection/tab (e.g., :session_id, :jti)
+    # :subject_column - who is present (e.g., :user_id, :member_id, :student_id)
+    attr_accessor :session_column, :subject_column
+
+    # Subject model (e.g., 'User', 'Member', 'Student')
+    # Required for scope-based broadcasting and queries
+    attr_accessor :subject_class
+
+    # Optional: proc that returns hash of subject info for presence data
+    # Called with the subject record to build presence hash
+    attr_accessor :subject_data_proc
+
+    # Timing
+    # :timeout - seconds until considered offline (default: 90)
+    # :heartbeat_interval - expected heartbeat frequency (default: 30)
+    attr_accessor :timeout, :heartbeat_interval
+
+    # ActionCable settings
+    # :channel_name - defaults to 'WhereIsWaldo::PresenceChannel'
+    # :authenticate_proc - proc to authenticate connection, receives request
+    attr_accessor :channel_name, :authenticate_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.:
+    #   config.broadcast_audience = ->(rec) { rec.account.users }
+    # Models may override per-model via `broadcasts_realtime(scope: ...)`.
+    attr_accessor :broadcast_audience
+
+    # === Live presence roster ("who's around in my org/account") ===
+    #
+    # roster_org: given a subject, return the org/container record that
+    #   defines the roster boundary. Its class + id key the single shared roster
+    #   ActionCable stream, so every member of the same org subscribes to ONE
+    #   stream and a presence change is a single O(1) broadcast (not per-member
+    #   fan-out). Required to enable the roster feature — nil leaves it inert.
+    #     config.roster_org = ->(subject) { subject.account }
+    #
+    # roster_members: given that org, return the AR scope of member subjects
+    #   shown in the roster. Optional — defaults to org.public_send(<subjects>)
+    #   inferred from subject_class (User => :users). Provide it to scope the
+    #   list, e.g. only active members:
+    #     config.roster_members = ->(org) { org.users.active }
+    #
+    # roster_members_association: association used to build the default roster
+    #   from the org when roster_members is unset (defaults to the pluralized
+    #   subject_class, e.g. :users).
+    attr_accessor :roster_org, :roster_members, :roster_members_association
+
+    # roster_visible_to: given a VIEWER, return the AR scope of subjects
+    #   that viewer may see (for :poll/:nudge snapshots + diffs). Handles any
+    #   visibility rule server-side. Defaults to the viewer's whole org roster
+    #   (everyone-sees-everyone) when unset.
+    #     config.roster_visible_to = ->(viewer) { viewer.visible_users }
+    #
+    # roster_viewers_of: given a SUBJECT, return the AR scope of viewers allowed
+    #   to see it (ONLY used by :fanout, Phase 3). Must be the exact inverse of
+    #   roster_visible_to.
+    attr_accessor :roster_visible_to, :roster_viewers_of
+
+    # roster_mode: delivery strategy, per account. A symbol, or a callable
+    #   resolving an account -> mode. MUST be a function of the account (uniform
+    #   for all its members). Default :poll (safe: server-side filtered).
+    #     :poll       - heartbeat/poll, server-filtered, ~interval latency
+    #     :broadcast  - instant shared-stream push, NO filtering (open account)
+    #     :nudge      - :poll + content-free trigger (Phase 2)
+    #     :fanout     - per-viewer push (Phase 3)
+    #     config.roster_mode = ->(account) { account.everyone_admin? ? :broadcast : :poll }
+    attr_accessor :roster_mode
+
+    # Tuning (pull/nudge). roster_nudge_jitter (seconds) spreads clients' re-poll
+    # after a nudge so a change doesn't stampede every viewer at once.
+    attr_accessor :roster_poll_interval, :roster_cache_ttl, :roster_nudge_jitter
+
+    def initialize
+      # Storage defaults
+      @adapter = :database
+      @table_name = "presences"
+      @redis_client = nil
+      @redis_prefix = "where_is_waldo"
+
+      # Column defaults
+      @session_column = :session_id
+      @subject_column = :subject_id
+
+      # Subject model (required)
+      @subject_class = nil
+      @subject_data_proc = nil
+
+      # Timing defaults
+      @timeout = 90
+      @heartbeat_interval = 30
+
+      # ActionCable defaults
+      @channel_name = "WhereIsWaldo::PresenceChannel"
+      @authenticate_proc = nil
+
+      # Broadcastable default audience (set per app)
+      @broadcast_audience = nil
+
+      # Presence roster (set per app to enable)
+      @roster_org = nil
+      @roster_members = nil
+      @roster_members_association = nil
+      @roster_visible_to = nil
+      @roster_viewers_of = nil
+      @roster_mode = :poll
+      @roster_poll_interval = 15
+      @roster_cache_ttl = 90
+      @roster_nudge_jitter = 0.5
+    end
+
+    # Helper to get timeout as duration
+    def timeout_duration
+      timeout.is_a?(ActiveSupport::Duration) ? timeout : timeout.seconds
+    end
+
+    # Helper to get subject class constant
+    def subject_class_constant
+      return nil if subject_class.blank?
+
+      subject_class.is_a?(String) ? subject_class.safe_constantize : subject_class
+    end
+
+    # Resolve the org/container record for a subject (nil if unset/absent).
+    def resolve_roster_org(subject)
+      return nil unless roster_org && subject
+
+      roster_org.call(subject)
+    end
+
+    # Association name used to derive the default roster from an org when
+    # roster_members is not configured (e.g. subject_class "User" => :users).
+    def members_association
+      return roster_members_association if roster_members_association
+      return nil if subject_class.blank?
+
+      subject_class.to_s.demodulize.underscore.pluralize.to_sym
+    end
+
+    # Resolve the AR scope of member subjects for an org (nil if not resolvable).
+    def resolve_members(org)
+      return nil unless org
+
+      if roster_members
+        roster_members.call(org)
+      elsif (assoc = members_association) && org.respond_to?(assoc)
+        org.public_send(assoc)
+      end
+    end
+
+    # True when the live-presence roster feature is configured.
+    def roster_enabled?
+      !roster_org.nil?
+    end
+
+    # Resolve the AR scope of subjects a VIEWER may see. Defaults to the
+    # viewer's whole org roster (everyone-sees-everyone) when unset.
+    def resolve_visible_to(viewer)
+      return nil unless viewer
+
+      if roster_visible_to
+        roster_visible_to.call(viewer)
+      else
+        resolve_members(resolve_roster_org(viewer))
+      end
+    end
+
+    # Resolve the AR scope of viewers allowed to see a SUBJECT (:fanout only).
+    def resolve_viewers_of(subject)
+      return nil unless roster_viewers_of && subject
+
+      roster_viewers_of.call(subject)
+    end
+
+    # Resolve the delivery mode for an account. Callable roster_mode is invoked
+    # with the account; a bare symbol is returned as-is. Defaults to :poll.
+    def resolve_mode(account)
+      mode = roster_mode
+      mode = mode.call(account) if mode.respond_to?(:call)
+      (mode || :poll).to_sym
+    end
+
+    # Build subject data hash from a subject record
+    def build_subject_data(subject)
+      return {} unless subject
+
+      if subject_data_proc
+        subject_data_proc.call(subject)
+      elsif subject.respond_to?(:id)
+        { id: subject.id }
+      else
+        {}
+      end
+    end
+  end
+end