where_is_waldo 0.1.11 → 0.1.13

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5bd28c86d109c69fc976eaab788972106493a78b3fbd8e8e2370bae5dc936986
-  data.tar.gz: fd49e94bf3a08dd4350fdc1b8b413ec5d66916ef1ada8c74162044b3ccbdc428
+  metadata.gz: d06a950b27e51d7506062dc38518912b7b631a91be886eb29801f01e0ac438ac
+  data.tar.gz: fb1f82a4742a5099eee4d7a70f9d5445010dc52bd17408cfe2451363c04051a2
 SHA512:
-  metadata.gz: 620c8ce6c899937a25ab39f2858e45c5fa6ac68dc3510cf0e47a5739b36a8f95c24bb3daf385974600ffa652ad32f176a79ac0389286520af7a291bc48cda1e7
-  data.tar.gz: 0ecf65ed538cbffc439428ed3f5acc690e178430ba62a9568fb1b4a1d4cb48f33303aaa9724979f8c1c0ebfc44da5eb35133665345a2dfc2d4a3a224373784d7
+  metadata.gz: 5bfd8270b07bed9227be801b90b1f354a30a1eeaf748a3b7b7ff0d1a551bb0f3d6685792862f7c8e5676d411ea263b14fe64c67a76be422b0e55055a01672900
+  data.tar.gz: '053823564618b09793ded991cf679d9017eb3be14c8069bf1d33ee0fbe50d8872b0e004a7d0ab8ac0969a08e3eb4c7b427c562800e2c002fa9ec8c1cc9bd3e22'

data/CHANGELOG.md

@@ -5,6 +5,60 @@ Notable changes to where_is_waldo. Format loosely follows
 
 ## Unreleased
 
+## 0.1.13 - 2026-11-04
+
+### Documentation
+
+No code changes. This release exists to get the README onto the npm page, which
+only refreshes its rendered README on a new version.
+
+- **The README now says where this came from.** It previously mentioned
+  byscott.io zero times in 543 lines, so the one public, indexed page the
+  project owns pointed back at nothing. Adds a line under the tagline and an
+  About section naming the suite and three sibling tools.
+- **States plainly what the gem requires, and what it does not.** No account, no
+  API key, and no outbound calls of any kind — verified against the shipped
+  code, which contains no HTTP client and no hostnames. The sibling tools linked
+  in that section are hosted services and do require accounts; this does not,
+  and the distinction is now explicit rather than left to the reader.
+- **States that presence data is transient and lives in the consumer's own
+  store.** One table, or Redis keys with a TTL; a session's row is removed once
+  it stops heartbeating. This answers the question a developer actually asks of
+  a presence library — whether it quietly accumulates rows they then have to
+  manage.
+- `homepage` now points at byscott.io. `repository` and `bugs` still point at
+  this public repo, so source and issues stay one click away from the npm page.
+
+## 0.1.12 - 2026-10-27
+
+### Fixed
+
+- **A subject in more than one org could be put on the wrong roster.**
+  `roster_org` receives only the subject, so an app whose users belong to
+  several orgs had to guess, and the obvious guess (`accounts.first`) is
+  association order rather than the org the person is actually working in.
+  They were then invisible to the teammates they were with, and shown to an
+  org they were not in.
+
+  New `roster_org_for` receives `(subject, container)`, where the container is
+  the one the CONNECTION is scoped to -- the only place that answer exists. It
+  applies on BOTH sides: the presence row stores the resolved org at connect
+  and later broadcasts read it back, and the roster subscription resolves the
+  same way, so a viewer and the broadcasts meant for them can no longer land
+  on different streams. `container` comes from your connection's
+  `identified_by :current_container`; without that it is nil and behaviour is
+  unchanged. A subject present in two
+  orgs now appears in both rosters rather than one arbitrary one.
+
+  Stored in the existing `metadata` column, so **no migration is required**.
+  `roster_org` is untouched and still works for single-org apps.
+
+- **A presence transition read a subject's sessions twice.** Publishing needs
+  both the org keys and the aggregate state, and both come from the same rows;
+  they are now derived from one read. This is the hottest path in the library,
+  so the second read was pure overhead.
+
+
 ## 0.1.11 - 2026-10-27
 
 ### Fixed

data/README.md

@@ -2,6 +2,9 @@
 
 Real-time presence tracking for Rails + React using ActionCable.
 
+Open source, and built for and used in production by the [byscott.io](https://byscott.io)
+suite of tools for churches, educators, small businesses and families.
+
 [![CI](https://github.com/byscott-io/where_is_waldo/actions/workflows/ci.yml/badge.svg?branch=master)](https://github.com/byscott-io/where_is_waldo/actions/workflows/ci.yml)
 [![Gem Version](https://img.shields.io/gem/v/where_is_waldo)](https://rubygems.org/gems/where_is_waldo)
 [![npm version](https://img.shields.io/npm/v/@byscott-io/where-is-waldo)](https://www.npmjs.com/package/@byscott-io/where-is-waldo)
@@ -290,6 +293,32 @@ their live sessions (multiple browser tabs, mobile, etc.):
 WhereIsWaldo.configure do |config|
   # The org/account a subject belongs to. Required to enable the roster.
   config.roster_org = ->(subject) { subject.account }
+  #
+  # MULTI-ORG SUBJECTS: roster_org is handed only the subject, so it has to
+  # guess which org the person is in right now -- and `accounts.first` guesses
+  # by association order. Someone who has switched is then put on the wrong
+  # roster: invisible to the teammates they are with, shown to an org they are
+  # not in. Use roster_org_for instead, which also receives the container the
+  # CONNECTION is scoped to:
+  #
+  #   config.roster_org_for = ->(user, container) { container || user.accounts.first }
+  #
+  # `container` is read from your own ActionCable connection, so it is only
+  # ever non-nil if that connection identifies one:
+  #
+  #   module ApplicationCable
+  #     class Connection < ActionCable::Connection::Base
+  #       identified_by :current_user, :current_container, :session_id
+  #     end
+  #   end
+  #
+  # WhereIsWaldo::JwtConnection already does this. Without it `container` is
+  # always nil and the fallback above behaves exactly like plain roster_org --
+  # which is to say, like the bug.
+  #
+  # The resolved org is stored on the presence row at connect and read back by
+  # later broadcasts, so the subscriber and the broadcaster always agree on the
+  # stream. roster_org keeps working unchanged for single-org apps.
 
   # What a VIEWER may see (:poll/:nudge/:fanout). Any visibility rule,
   # server-enforced. Defaults to the viewer's whole org when unset.
@@ -512,6 +541,34 @@ gem guarantees, and what your app must do:
   are gated to transitions. For large or hostile deployments use the Redis
   adapter and consider rate-limiting.
 
+## About
+
+WhereIsWaldo is maintained by Scott Gibson and came out of a real need across
+[byscott.io](https://byscott.io) — a suite of software tools for churches,
+educators, small businesses and families, where several Rails and React apps
+each wanted "who is online right now" without paying for a hosted websocket
+service.
+
+**No account or API key is required, and nothing phones home.** This gem keeps
+no store of its own. Presence lives in one table in your own database, or as
+expiring keys in your own Redis, and it is transient either way — a session's
+row is removed once it stops heartbeating, and Redis keys carry a TTL. The only
+infrastructure it needs is the ActionCable you already run.
+
+The sibling tools below are hosted services and do require an account; this gem
+is a library and does not.
+
+Other tools from the same suite, if a shared backend is what you actually want
+rather than a library:
+
+- **[IssuesByScott](https://issues.byscott.io)** — error reporting, an issue
+  portal your users can file into, and deploy tracking
+- **[BillingByScott](https://billing.byscott.io)** — subscriptions, invoicing
+  and entitlement checks across several apps
+- **[MetricsByScott](https://metrics.byscott.io)** — events, page views and
+  time-varied metrics, with a data warehouse rather than a dashboard you cannot
+  query
+
 ## License
 
 MIT

data/VERSION

@@ -1 +1 @@
-0.1.11
+0.1.13

data/app/channels/where_is_waldo/presence_channel.rb

@@ -88,13 +88,43 @@ module WhereIsWaldo
     end
 
     def register_presence
+      # The org key is computed HERE and written over anything the client sent.
+      # params[:metadata] is client-supplied, so letting a tab name its own
+      # roster would let it subscribe itself into an org it has no business
+      # seeing.
+      #
+      # The client's value is REMOVED FIRST, unconditionally. Only overwriting
+      # it when the server resolves an org leaves the hole open in exactly the
+      # case that matters: a connection with no org of its own could name any
+      # org it liked, the value would persist on the presence row, and later
+      # broadcasts read it back verbatim and push that subject's presence into
+      # a stream they have no claim on.
+      metadata = (params[:metadata] || {}).to_h
+      metadata.delete(WhereIsWaldo::Roster::ORG_KEY)
+      metadata.delete(WhereIsWaldo::Roster::ORG_KEY.to_sym)
+
+      key = WhereIsWaldo::Roster.org_key(wiw_connection_org)
+      metadata[WhereIsWaldo::Roster::ORG_KEY] = key if key
+
       WhereIsWaldo.connect(
         session_id: waldo_session_id,
         subject_id: waldo_subject_id,
-        metadata: params[:metadata] || {}
+        metadata: metadata
       )
     end
 
+    # The org this CONNECTION is scoped to. The container comes from the host
+    # app's own cable connection, which is the only place that knows the org
+    # the person is actually working in -- a lambda given just the subject has
+    # to guess, and guesses by association order.
+    def wiw_connection_org
+      return @wiw_connection_org if defined?(@wiw_connection_org)
+
+      subject = WhereIsWaldo.config.subject_class_constant&.find_by(id: waldo_subject_id)
+      container = connection.try(:current_container)
+      @wiw_connection_org = subject && WhereIsWaldo.config.resolve_roster_org(subject, container: container)
+    end
+
     def roster_transition?(tab_visible, subject_active)
       tab_visible != @wiw_tab_visible || subject_active != @wiw_subject_active
     end
@@ -104,8 +134,7 @@ module WhereIsWaldo
     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)
+      org = wiw_connection_org
       return nil unless org
 
       WhereIsWaldo::RosterDelivery.for(WhereIsWaldo.config.resolve_mode(org))

data/app/channels/where_is_waldo/roster_channel.rb

@@ -13,12 +13,15 @@ module WhereIsWaldo
   class RosterChannel < ApplicationCable::Channel
     def subscribed
       subject = current_subject
-      mode = resolve_mode(subject)
+      org = resolve_org(subject)
+      return reject unless org
+
+      mode = WhereIsWaldo.config.resolve_mode(org)
       return reject unless mode
 
       @wiw_subject = subject
       @wiw_strategy = RosterDelivery.for(mode)
-      apply_plan(@wiw_strategy.subscribe_plan(subject, waldo_session_id))
+      apply_plan(@wiw_strategy.subscribe_plan(subject, waldo_session_id, org: org))
     end
 
     # Client-driven poll (pull/nudge modes). Transmits a filtered snapshot
@@ -31,11 +34,15 @@ module WhereIsWaldo
 
     private
 
-    def resolve_mode(subject)
-      org = WhereIsWaldo.config.resolve_roster_org(subject)
-      return nil unless org
+    # The org this VIEWER is watching. Resolved from the connection's container
+    # like the writer side, so the stream they subscribe to is the one deltas
+    # are actually broadcast into. Resolving from the subject alone here was
+    # the other half of the same bug: a viewer scoped to their second org sat
+    # on their first org's stream and simply never saw anything.
+    def resolve_org(subject)
+      return nil unless subject
 
-      WhereIsWaldo.config.resolve_mode(org)
+      WhereIsWaldo.config.resolve_roster_org(subject, container: connection.try(:current_container))
     end
 
     def apply_plan(plan)

data/app/services/where_is_waldo/roster/org_keys.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+module WhereIsWaldo
+  class Roster
+    # Which roster a session belongs to, and how that is stored.
+    #
+    # Extracted from Roster so the resolution rules sit together and can be
+    # read without the delivery machinery around them.
+    module OrgKeys
+      # WHICH ROSTER A SESSION BELONGS TO IS DECIDED ONCE, AT CONNECT, AND
+      # STORED ON THE PRESENCE ROW.
+      #
+      # It cannot be re-derived later. The connection knows the container the
+      # person is actually working in; a background broadcast an hour later has
+      # only a subject id, and a subject can belong to several orgs. Deriving
+      # it twice is how the subscriber ends up listening to one stream while
+      # the broadcaster writes to another -- which looks exactly like presence
+      # being broken, not like a resolution bug.
+      #
+      # Stored in metadata rather than a column so this needs no migration in
+      # any consuming app.
+      def org_key(org)
+        return nil unless org
+
+        klass = org.class.respond_to?(:base_class) ? org.class.base_class : org.class
+        "#{klass.name}:#{org.id}"
+      end
+
+      def org_from_key(key)
+        type, id = key.to_s.split(":", 2)
+        return nil if type.blank? || id.blank?
+
+        type.safe_constantize&.find_by(id: id)
+      rescue StandardError
+        nil
+      end
+
+      # Every org this subject is currently connected in -- usually one, but a
+      # person with two tabs in two accounts is present in both and must appear
+      # in both rosters. Falls back to resolving from the subject alone for
+      # rows written before this existed, and for apps with no container.
+      def org_keys_for_subject(subject_id, timeout: nil)
+        by_subject = WhereIsWaldo::PresenceService.sessions_for_subjects([subject_id], timeout: timeout)
+        org_keys_from(sessions_for(by_subject, subject_id), subject_id)
+      end
+
+      # The same answer from sessions the caller has ALREADY loaded. A presence
+      # transition needs both the org keys and the subject's aggregate state,
+      # and both are derived from one set of session rows -- reading them twice
+      # doubles the adapter traffic on the hottest path in the library.
+      def org_keys_from(sessions, subject_id)
+        keys = sessions.filter_map do |session|
+          session.dig(:metadata, ORG_KEY) || session.dig("metadata", ORG_KEY)
+        end.uniq
+        return keys if keys.any?
+
+        [org_key(WhereIsWaldo.config.resolve_roster_org(find_subject(subject_id)))].compact
+      end
+
+      private
+
+      # THE KEY TYPES ON THE TWO SIDES ARE NOT GUARANTEED TO MATCH.
+      #
+      # The database adapter keys its result by the AR-typecast column value,
+      # typically an Integer, while a subject id arriving from a cable
+      # connection is often a String -- authenticate_proc returns whatever the
+      # host app decides, and connection params are strings. A plain fetch then
+      # misses, and the caller falls back to resolving from the subject alone:
+      # silently, and straight back to the guess this exists to replace.
+      # Comparing as strings is what stops a type difference becoming a wrong
+      # roster.
+      def sessions_for(by_subject, subject_id)
+        return by_subject[subject_id] if by_subject.key?(subject_id)
+
+        wanted = subject_id.to_s
+        _, sessions = by_subject.find { |key, _| key.to_s == wanted }
+        sessions || []
+      end
+    end
+  end
+end

data/app/services/where_is_waldo/roster.rb

@@ -34,6 +34,13 @@ module WhereIsWaldo
     RANK = { active: 3, idle: 2, background: 1, offline: 0 }.freeze
     DEFAULT_PLATFORM = "web"
 
+    # The metadata key holding which roster a session belongs to. Defined on
+    # the class, not the singleton, so callers can reference
+    # WhereIsWaldo::Roster::ORG_KEY.
+    ORG_KEY = "wiw_org"
+
+    extend OrgKeys
+
     class << self
       # Shared stream name for an org record (nil when org is absent).
       def stream_name(org)
@@ -45,8 +52,8 @@ module WhereIsWaldo
 
       # 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))
+      def stream_for_subject(subject, container: nil)
+        stream_name(WhereIsWaldo.config.resolve_roster_org(subject, container: container))
       end
 
       # Full roster state for an org: every member subject with their current
@@ -118,12 +125,23 @@ module WhereIsWaldo
       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
+        # ONE read of the subject's sessions, used for both halves. The org
+        # keys and the aggregate state are derived from the same rows, and a
+        # transition is the hottest path here -- fetching twice doubled the
+        # adapter traffic for no new information.
+        by_subject = WhereIsWaldo::PresenceService.sessions_for_subjects([subject_id], timeout: timeout)
+        sessions = sessions_for(by_subject, subject_id)
 
-        member = build_member_by_id(subject, subject_id, timeout: timeout)
-        ActionCable.server.broadcast(stream, delta_message(member))
+        keys = org_keys_from(sessions, subject_id)
+        return false if keys.empty?
+
+        subject = find_subject(subject_id)
+        state = sessions.any? ? aggregate(sessions) : offline_state
+        member = merge_member(subject, state, id: subject_id)
+        keys.each do |key|
+          stream = "where_is_waldo:roster:#{key}"
+          ActionCable.server.broadcast(stream, delta_message(member))
+        end
         true
       rescue StandardError => e
         Rails.logger&.warn("[WhereIsWaldo::Roster] publish failed for #{subject_id}: #{e.class}: #{e.message}")
@@ -158,11 +176,10 @@ module WhereIsWaldo
       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
+        keys = org_keys_for_subject(subject_id)
+        return false if keys.empty?
 
-        ActionCable.server.broadcast(stream, nudge_message)
+        keys.each { |key| ActionCable.server.broadcast("where_is_waldo:roster:#{key}", nudge_message) }
         true
       rescue StandardError => e
         Rails.logger&.warn("[WhereIsWaldo::Roster] nudge failed for #{subject_id}: #{e.class}: #{e.message}")

data/app/services/where_is_waldo/roster_delivery.rb

@@ -28,7 +28,7 @@ module WhereIsWaldo
     # 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)
+      def subscribe_plan(_subject, _session_id, org: nil) # rubocop:disable Lint/UnusedMethodArgument
         { streams: [], messages: [] }
       end
 
@@ -50,8 +50,11 @@ module WhereIsWaldo
     # 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)
+      def subscribe_plan(subject, _session_id, org: nil)
+        # org comes from the channel, which knows the connection's container.
+        # Resolving it again here would reach a different answer for a subject
+        # in several orgs, and put the viewer on a stream nobody broadcasts to.
+        org ||= config.resolve_roster_org(subject)
         stream = Roster.stream_name(org)
         return { streams: [], messages: [] } unless stream
 
@@ -77,10 +80,13 @@ module WhereIsWaldo
         :poll
       end
 
-      def subscribe_plan(subject, session_id)
+      def subscribe_plan(subject, session_id, org: nil)
         current = current_members(subject)
         write_baseline(session_id, current)
-        { streams: subscribe_streams(subject), messages: [Roster.snapshot_message(current.values, mode: mode)] }
+        {
+          streams: subscribe_streams(subject, org: org),
+          messages: [Roster.snapshot_message(current.values, mode: mode)]
+        }
       end
 
       def poll_messages(subject, session_id)
@@ -101,7 +107,7 @@ module WhereIsWaldo
 
       # 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)
+      def subscribe_streams(_subject, org: nil) # rubocop:disable Lint/UnusedMethodArgument
         []
       end
 
@@ -156,8 +162,9 @@ module WhereIsWaldo
       private
 
       # Also subscribe the account stream so this client receives nudges.
-      def subscribe_streams(subject)
-        stream = Roster.stream_name(config.resolve_roster_org(subject))
+      def subscribe_streams(subject, org: nil)
+        org ||= config.resolve_roster_org(subject)
+        stream = Roster.stream_name(org)
         stream ? [stream] : []
       end
     end
@@ -168,7 +175,7 @@ module WhereIsWaldo
     # 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)
+      def subscribe_plan(subject, _session_id, org: nil) # rubocop:disable Lint/UnusedMethodArgument
         members = Roster.members_for(config.resolve_visible_to(subject))
         {
           streams: [Roster.viewer_stream(subject.id)],

data/lib/where_is_waldo/configuration.rb

@@ -83,6 +83,16 @@ module WhereIsWaldo
     # 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).
+    # roster_org_for: the container-aware form of roster_org. Receives
+    #   (subject, container) where container is the one the CONNECTION is
+    #   scoped to -- the account the person is actually working in, which a
+    #   subject-only lambda cannot know. Prefer this whenever subjects can
+    #   belong to more than one org; roster_org picks by association order,
+    #   which puts a switched user on the wrong roster: invisible to the
+    #   teammates they are with, visible to an org they are not.
+    #     config.roster_org_for = ->(user, container) { container || user.accounts.first }
+    attr_accessor :roster_org_for
+
     attr_accessor :roster_org, :roster_members, :roster_members_association
 
     # roster_visible_to: given a VIEWER, return the AR scope of subjects
@@ -142,6 +152,7 @@ module WhereIsWaldo
 
       # Presence roster (set per app to enable)
       @roster_org = nil
+      @roster_org_for = nil
       @roster_members = nil
       @roster_members_association = nil
       @roster_visible_to = nil
@@ -165,10 +176,17 @@ module WhereIsWaldo
     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)
+    # @param container [Object, nil] the connection's container, when known.
+    #   Only roster_org_for receives it; roster_org keeps its old arity so
+    #   existing apps are untouched.
+    def resolve_roster_org(subject, container: nil)
+      return nil unless subject
+
+      if roster_org_for
+        roster_org_for.call(subject, container)
+      elsif roster_org
+        roster_org.call(subject)
+      end
     end
 
     # Association name used to derive the default roster from an org when
@@ -193,7 +211,7 @@ module WhereIsWaldo
 
     # True when the live-presence roster feature is configured.
     def roster_enabled?
-      !roster_org.nil?
+      !roster_org.nil? || !roster_org_for.nil?
     end
 
     # Resolve the AR scope of subjects a VIEWER may see. Defaults to the

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: where_is_waldo
 version: !ruby/object:Gem::Version
-  version: 0.1.11
+  version: 0.1.13
 platform: ruby
 authors:
 - Scott Gibson
@@ -211,6 +211,7 @@ files:
 - app/services/where_is_waldo/broadcaster.rb
 - app/services/where_is_waldo/presence_service.rb
 - app/services/where_is_waldo/roster.rb
+- app/services/where_is_waldo/roster/org_keys.rb
 - app/services/where_is_waldo/roster_delivery.rb
 - lib/generators/where_is_waldo/install/install_generator.rb
 - lib/generators/where_is_waldo/install/templates/channel.rb.tt