where_is_waldo 0.1.9 → 0.1.11

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 96f9fb4253fa91bfaa947711aff7e9de6cf6511029c34fe4d24bcaa92be9958d
-  data.tar.gz: f441dacf17ca081d1974d08e3eb3460dce8ca5423772689c72e730c58746b8e9
+  metadata.gz: 5bd28c86d109c69fc976eaab788972106493a78b3fbd8e8e2370bae5dc936986
+  data.tar.gz: fd49e94bf3a08dd4350fdc1b8b413ec5d66916ef1ada8c74162044b3ccbdc428
 SHA512:
-  metadata.gz: df11e85496b2ae55c928695e1dad936a82b0d0b3abbcf8df7160932cf221f0ab4ab7c1cb8830cc5b710bbbab029cb82dfdb6d719292b0dc1863767151baf406c
-  data.tar.gz: 3412d9fd5475df5fe17a29c8dbd910f3c920db8260971492aa479ab23797d98d0c726549328aa27bdbef675646ae750f948c30ac810c96eaadddf6d8e1badcdf
+  metadata.gz: 620c8ce6c899937a25ab39f2858e45c5fa6ac68dc3510cf0e47a5739b36a8f95c24bb3daf385974600ffa652ad32f176a79ac0389286520af7a291bc48cda1e7
+  data.tar.gz: 0ecf65ed538cbffc439428ed3f5acc690e178430ba62a9568fb1b4a1d4cb48f33303aaa9724979f8c1c0ebfc44da5eb35133665345a2dfc2d4a3a224373784d7

data/CHANGELOG.md

@@ -3,6 +3,93 @@
 Notable changes to where_is_waldo. Format loosely follows
 [Keep a Changelog](https://keepachangelog.com/).
 
+## Unreleased
+
+## 0.1.11 - 2026-10-27
+
+### Fixed
+
+- **The install generator emitted the pre-0.1.5 schema.** It wrote a unique
+  index on the session column alone, while 0.1.5 moved presence rows to being
+  keyed by `(subject, session)` precisely so two authenticated subjects who
+  collide on a session id cannot upsert onto each other's row — session ids are
+  client-supplied in some setups, and a reused JWT `jti` is enough. The adapter
+  has scoped every session lookup by both columns since; only the generator
+  lagged, so every app installed after 0.1.5 got a schema the library had
+  already moved away from and needed a follow-up migration to correct. An
+  unused second migration template carrying the right index (and a hardcoded
+  `Migration[7.0]`) has been removed rather than left as a second answer.
+
+- **The install generator overwrote an existing ActionCable connection.**
+  Installing into an app that already authenticates its own cable connection
+  replaced that file with the turnkey one, silently dropping whatever the app
+  did beyond what this library needs — container scoping and token bookkeeping
+  in the cases seen. Existing channel files are now kept, and the post-install
+  message names them and states what the channel requires of a connection
+  (`current_user` and `session_id`).
+
+### Changed
+
+- **The Redis adapter is now tested against a real server, on both redis-rb 5
+  and 6.** Its existing spec runs against `MockRedis`, a pure-Ruby fake with no
+  protocol layer, so it could not see wire-format changes at all. redis-rb 6
+  defaults to RESP3, which types several replies differently from RESP2 —
+  `SMEMBERS` among them, and this adapter feeds that result straight into
+  `filter_map` and `all?`. Nothing in the adapter's command set behaves
+  differently between the two, but that was previously unverified rather than
+  known.
+
+  - New integration spec drives the adapter against a live Redis. It skips when
+    no server is reachable, so contributors are not required to run one.
+  - CI adds an `rspec-redis` job with a Redis service, run as a matrix over
+    redis-rb 5.x and 6.x, and fails rather than skips if the service is missing
+    — a silent skip would read as a pass.
+  - Development dependency widened from `~> 5.0` to `>= 5.0, < 7`. The gem has
+    no runtime dependency on `redis` and never has, so this constrains nothing
+    for consumers; it only lets the library test what consumers actually use.
+  - README documents supported client versions, and that `protocol: 2` is not
+    needed.
+
+  The committed lockfile stays on redis 5.x, which keeps `mock_redis` at
+  0.53.0 for every existing spec. `mock_redis` 0.53.0 depends on `redis ~> 5`,
+  so resolving against redis 6 forces it down to 0.48.1 — that happens only
+  inside the redis 6 CI leg, which runs the real-server spec alone and never
+  touches MockRedis. No mock-based spec changed the double it runs against.
+
+  No runtime code changed.
+
+## 0.1.10
+
+### Added
+
+- **Presence heartbeats are kept out of APM as their own transactions.**
+  `WhereIsWaldo::PresenceChannel#heartbeat` now runs inside
+  `WhereIsWaldo::Apm.ignoring_transaction`, so when a host app runs New Relic
+  the per-tab-per-interval heartbeat — the highest-volume, least-interesting
+  cable action — no longer surfaces as an APM transaction. Left unhandled it
+  inflates throughput and flatters average response time (heartbeats are
+  uniformly fast) while telling operators nothing the presence store can't
+  already answer.
+
+  - Guarded, no new dependency: `Apm` no-ops unless a supported agent
+    (New Relic today) is loaded, so consumers without APM pay nothing.
+  - Failures stay visible: an ignored New Relic transaction skips `commit!`,
+    where exceptions are normally harvested, so the wrapper hands any heartbeat
+    exception straight to the error collector and re-raises. Ignoring the
+    routine transaction never hides a heartbeat failure.
+  - Opt out with `config.ignore_heartbeat_apm = false` to report heartbeats
+    like any other action.
+  - Scope: New Relic only. The underlying exposure is agent-general — any APM
+    that opens a transaction per `perform_action` sees the same heartbeat
+    volume — but New Relic is the only agent seen in production so far.
+    Detection is isolated in `Apm.agent` so another vendor can be added there
+    without touching callers.
+
+  Note: the companion New Relic issue — the agent pinning the WebSocket upgrade
+  transaction onto pooled ActionCable worker threads — is a general
+  newrelic_rpm × ActionCable defect and stays a host-app shim; it is not
+  something the gem patches.
+
 ## 0.1.9
 
 Security/maintenance release — dependency bumps only, no library code changes.

data/README.md

@@ -41,6 +41,13 @@ rails generate where_is_waldo:install --adapter=redis --subject_column=user_id
 npm install @byscott-io/where-is-waldo @rails/actioncable
 ```
 
+Installing into an app that already has `app/channels/application_cable/`?
+Those files are kept, never overwritten — the generator only adds what is
+missing, and says which it left alone. The presence channel needs the
+connection to identify **`current_user`** and **`session_id`**; add them to
+your own connection, or `include WhereIsWaldo::JwtConnection` (corebyscott
+apps) to get both from the JWT.
+
 ### 2. Configure
 
 ```ruby
@@ -113,6 +120,14 @@ WhereIsWaldo.configure do |config|
   config.timeout = 90                   # seconds until offline
   config.heartbeat_interval = 30
 
+  # Observability: when true (default) and the host app runs a supported APM
+  # agent (New Relic today), presence heartbeats are kept out of APM as their
+  # own transactions. Heartbeats are the highest-volume, least-interesting cable
+  # action, so reporting each one inflates throughput and flatters average
+  # response time without adding signal. Failures are still reported. Set false
+  # to report heartbeats like any other action.
+  config.ignore_heartbeat_apm = true
+
   # Optional: custom subject data in presence hash. NOTE: with the roster
   # enabled, these fields are broadcast to every member of the org — see
   # Security.
@@ -140,6 +155,20 @@ WhereIsWaldo.configure do |config|
 end
 ```
 
+#### Redis adapter and client versions
+
+The gem does not depend on `redis`. Choosing `:redis` means supplying your own
+client, so you pick the version.
+
+`redis-rb` 5.x and 6.x are both supported and both run in CI against a real
+server. Version 6 switched to RESP3 by default, which changes reply types for
+some commands; none of the commands this adapter uses behave differently, and
+the integration spec exists to keep that true. Nothing here needs `protocol: 2`.
+
+The adapter stores presence under keys prefixed by `config.redis_prefix`
+(default `where_is_waldo`) and sets a TTL on session keys, so it does not need a
+cleanup job the way the database adapter does.
+
 ### Querying Presence
 
 ```ruby

data/VERSION

@@ -1 +1 @@
-0.1.9
+0.1.11

data/app/channels/where_is_waldo/presence_channel.rb

@@ -32,7 +32,20 @@ module WhereIsWaldo
       publish_roster_change
     end
 
+    # Kept out of APM as its own transaction by default — heartbeats are the
+    # highest-volume, least-interesting cable action, so reporting each one
+    # distorts throughput and average response time without adding signal. The
+    # wrapper no-ops unless the host runs a supported agent; see
+    # WhereIsWaldo::Apm and config.ignore_heartbeat_apm. The real work lives in
+    # perform_heartbeat, which is private so a client can't invoke it directly
+    # as a channel action (only public methods are processable actions).
     def heartbeat(data)
+      WhereIsWaldo::Apm.ignoring_transaction { perform_heartbeat(data) }
+    end
+
+    private
+
+    def perform_heartbeat(data)
       return if presence_suppressed?
 
       data = data.with_indifferent_access
@@ -58,8 +71,6 @@ module WhereIsWaldo
       publish_roster_change
     end
 
-    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

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

@@ -32,9 +32,17 @@ module WhereIsWaldo
       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"
+        # NEVER overwrite an app's existing cable connection or channel base.
+        # A host app that already authenticates ActionCable has its auth,
+        # container scoping and session identity in those files, and the
+        # turnkey versions here provide only what this library needs -- so
+        # replacing them silently drops whatever else they did. Installing
+        # into an existing app is the common case, not the exception.
+        @kept_channels = []
+
+        copy_channel "connection.rb.tt", "app/channels/application_cable/connection.rb"
+        copy_channel "channel.rb.tt", "app/channels/application_cable/channel.rb"
+        copy_channel "presence_channel.rb.tt", "app/channels/presence_channel.rb"
       end
 
       def show_post_install_message
@@ -54,10 +62,34 @@ module WhereIsWaldo
         say "       <App />"
         say "     </PresenceProvider>"
         say ""
+        report_kept_channels
       end
 
       private
 
+      # Say plainly what was left alone. A silent skip is as confusing as a
+      # silent overwrite: the install looks complete and presence then fails
+      # because the app's own connection exposes no session identity.
+      def report_kept_channels
+        return if @kept_channels.blank?
+
+        say "Kept your existing files (not overwritten):", :yellow
+        @kept_channels.each { |f| say "  - #{f}" }
+        say ""
+        say "  WhereIsWaldo's channel reads connection.current_user and"
+        say "  connection.session_id. If your connection does not identify"
+        say "  both, add them -- or include WhereIsWaldo::JwtConnection."
+        say ""
+      end
+
+      def copy_channel(source, destination)
+        if File.exist?(File.join(destination_root, destination))
+          @kept_channels << destination
+        else
+          template source, destination
+        end
+      end
+
       def migration_version
         "[#{ActiveRecord::VERSION::STRING.to_f}]"
       end

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

@@ -14,7 +14,12 @@ class CreatePresences < ActiveRecord::Migration<%= migration_version %>
       t.timestamps
     end
 
-    add_index :presences, :<%= session_column %>, unique: true
+    # (subject, session) must be unique TOGETHER, never session alone. Session
+    # ids are not globally unique -- they are client-supplied in some setups,
+    # and a reused JWT jti is enough -- so keying on the session alone lets two
+    # authenticated subjects upsert onto each other's presence row. This is the
+    # keying the adapter uses: every session lookup scopes by both columns.
+    add_index :presences, [ :<%= subject_column %>, :<%= session_column %> ], unique: true
     add_index :presences, :last_heartbeat
   end
 end

data/lib/where_is_waldo/apm.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+module WhereIsWaldo
+  # APM (New Relic) integration seam.
+  #
+  # The gem takes NO hard dependency on newrelic_rpm. Every method here no-ops
+  # unless a supported agent is loaded in the host app, so a consumer without
+  # New Relic pays nothing and nothing breaks.
+  #
+  # Why this exists: ActionCable dispatches each client action through New
+  # Relic's ActionCableSubscriber, which starts one APM transaction per
+  # `perform_action`. Presence heartbeats are the highest-volume, least
+  # interesting action Waldo has — one per open tab per heartbeat interval,
+  # uniformly fast — so left alone they dominate transaction throughput and
+  # flatten the host app's average response time while telling operators nothing
+  # the presence store can't already answer. `ignoring_transaction` keeps them
+  # out of APM's headline numbers without hiding failures.
+  #
+  # (The companion half of this problem — the agent pinning the WebSocket
+  # upgrade transaction onto pooled ActionCable worker threads — is a general
+  # newrelic_rpm x ActionCable defect, not Waldo's to fix here. Host apps carry
+  # that shim until the agent resets pooled-thread state itself.)
+  #
+  # Scope: this handles New Relic ONLY. The underlying exposure is agent-general
+  # — any APM/tracer that opens a transaction per `perform_action` (Datadog,
+  # Scout, AppSignal, Skylight, Sentry, OpenTelemetry) sees the same heartbeat
+  # flood, and several share the same pooled-thread context-leak. Waldo doesn't
+  # cause that (it spawns no threads and patches nothing global); its heartbeat
+  # volume amplifies whatever the host's agent already does. Detection is
+  # isolated in `agent` so another vendor can be added there without touching
+  # callers.
+  module Apm
+    module_function
+
+    # The New Relic agent module, or nil when newrelic_rpm isn't loaded (or is
+    # too old to expose the API we use). Isolated behind one method so specs can
+    # drive both the present and absent paths without defining a global
+    # ::NewRelic constant.
+    def agent
+      return nil unless defined?(::NewRelic::Agent)
+      return nil unless ::NewRelic::Agent.respond_to?(:ignore_transaction)
+
+      ::NewRelic::Agent
+    end
+
+    # Run a unit of work without letting it surface as its own APM transaction,
+    # and return the block's value.
+    #
+    # A plain `yield` when there's no agent, or when the host has opted out via
+    # `config.ignore_heartbeat_apm = false` — in either case the transaction is
+    # reported normally.
+    #
+    # New Relic's `Transaction#ignore!` makes `#finish` skip `commit!`, and
+    # `commit!` is where transaction-attached exceptions are harvested
+    # (`record_exceptions`). So ignoring on its own would ALSO swallow a
+    # heartbeat failure. We hand any exception straight to the error collector —
+    # which reports immediately rather than at commit — and re-raise, so the
+    # caller's own error handling is unchanged.
+    def ignoring_transaction
+      nr = agent
+      return yield unless nr && WhereIsWaldo.config.ignore_heartbeat_apm
+
+      nr.ignore_transaction
+
+      begin
+        yield
+      rescue StandardError => e
+        nr.instance&.error_collector&.notice_error(e)
+        raise
+      end
+    end
+  end
+end

data/lib/where_is_waldo/configuration.rb

@@ -27,6 +27,15 @@ module WhereIsWaldo
     # :heartbeat_interval - expected heartbeat frequency (default: 30)
     attr_accessor :timeout, :heartbeat_interval
 
+    # Observability
+    # :ignore_heartbeat_apm - when true (default) and a supported APM agent
+    #   (New Relic) is loaded in the host app, presence heartbeats are kept out
+    #   of APM as their own transactions. Heartbeats are the highest-volume,
+    #   least-interesting cable action, so reporting each one distorts
+    #   throughput and average response time without adding signal. Set false
+    #   to report them like any other action. See WhereIsWaldo::Apm.
+    attr_accessor :ignore_heartbeat_apm
+
     # ActionCable settings
     # :channel_name - defaults to 'WhereIsWaldo::PresenceChannel'
     # :authenticate_proc - proc to authenticate connection, receives request
@@ -120,6 +129,9 @@ module WhereIsWaldo
       @timeout = 90
       @heartbeat_interval = 30
 
+      # Observability defaults
+      @ignore_heartbeat_apm = true
+
       # ActionCable defaults
       @channel_name = "WhereIsWaldo::PresenceChannel"
       @authenticate_proc = nil

data/lib/where_is_waldo.rb

@@ -2,6 +2,7 @@
 
 require "where_is_waldo/version"
 require "where_is_waldo/configuration"
+require "where_is_waldo/apm"
 require "where_is_waldo/engine" if defined?(Rails)
 
 module WhereIsWaldo

metadata

@@ -1,14 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: where_is_waldo
 version: !ruby/object:Gem::Version
-  version: 0.1.9
+  version: 0.1.11
 platform: ruby
 authors:
 - Scott Gibson
-autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-08-07 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -84,16 +83,22 @@ dependencies:
   name: redis
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
         version: '5.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '7'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
         version: '5.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '7'
 - !ruby/object:Gem::Dependency
   name: rspec-rails
   requirement: !ruby/object:Gem::Requirement
@@ -210,11 +215,11 @@ files:
 - lib/generators/where_is_waldo/install/install_generator.rb
 - lib/generators/where_is_waldo/install/templates/channel.rb.tt
 - lib/generators/where_is_waldo/install/templates/connection.rb.tt
-- lib/generators/where_is_waldo/install/templates/create_presences.rb.tt
 - lib/generators/where_is_waldo/install/templates/initializer.rb.tt
 - lib/generators/where_is_waldo/install/templates/migration.rb.tt
 - lib/generators/where_is_waldo/install/templates/presence_channel.rb.tt
 - lib/where_is_waldo.rb
+- lib/where_is_waldo/apm.rb
 - lib/where_is_waldo/configuration.rb
 - lib/where_is_waldo/engine.rb
 - lib/where_is_waldo/version.rb
@@ -227,7 +232,6 @@ metadata:
   changelog_uri: https://github.com/byscott-io/where_is_waldo/blob/master/CHANGELOG.md
   allowed_push_host: https://rubygems.org
   rubygems_mfa_required: 'true'
-post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -242,8 +246,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.22
-signing_key:
+rubygems_version: 4.0.16
 specification_version: 4
 summary: Real-time presence tracking for Rails + React applications
 test_files: []

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

@@ -1,44 +0,0 @@
-# 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
-
-    # (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
-    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