where_is_waldo 0.1.14 → 0.1.16

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 55b6e1ced7f3e93a1e415bc0e28d10b15a212ad134e3108f585bea84220a1f10
-  data.tar.gz: 6c068bbd05c86ea7c6ba9b2136295f5ef17c02bd19bf9211f8b4ee59a83b17f1
+  metadata.gz: c5bbdc6480c178670602c5f3749370dced0ef932e99d49c5a753eb3ceef3ed9e
+  data.tar.gz: e8b3d2db9b9179ae9828c7637b772f9f9b9dde5b82cfc1a756c524b8d701694f
 SHA512:
-  metadata.gz: 9d96b99856186d169d3e6c97f4a032f298158ecb9e8532238c40d98a0fc7388d2a3a4eaa195417fe21064d1babc389b1c083bf85dbdfc20a33f5fb50d223d076
-  data.tar.gz: 4f0a4167858defcc5403deb7fafeac5abdb7556af91017fc1e679c952bfb39e067609ca09320353d99663106dba8f0afc9c7740c28642aff3e231057681c6b5f
+  metadata.gz: d92709f8debef9199e51190a7a1952f132af7657faba25d1df174c58e7b841da9fdbd76ad5ef2c50cb922866f49c14306abbe78bfd86cff350564cf819a57715
+  data.tar.gz: 771c824d4eef5c3d02883389dc51ae8197342bb24196d18d00cc07bcba1ba971c654a98a7a285d5d81d574e78d550c28f8a9350212f3da65b38260c2510d7f80

data/CHANGELOG.md

@@ -5,6 +5,95 @@ Notable changes to where_is_waldo. Format loosely follows
 
 ## Unreleased
 
+## 0.1.16 - 2026-11-11
+
+### Fixed
+
+- **A client could stop reconnecting FOREVER, and nothing in ActionCable would
+  turn it back on.** ActionCable's `ConnectionMonitor` is the only thing that
+  reconnects a dropped socket, and it can be switched off permanently:
+
+  ```js
+  close({allowReconnect}) { if (!allowReconnect) { this.monitor.stop() } }
+  stop() { this.stopPolling(); removeEventListener("visibilitychange", ...) }
+  ```
+
+  `stop()` unregisters the very listener that would notice the tab being
+  focused again, and nothing re-registers it. The far end can trigger this
+  from outside the browser: Rails sends a disconnect with `reconnect: false`
+  for an unauthorized or remotely-disconnected connection.
+
+  Observed in production: a socket closed and the tab then ran for SEVEN AND A
+  HALF HOURS -- visible, focused, making ordinary HTTP requests -- without a
+  single further WebSocket attempt. Presence stayed empty the whole time and
+  anything broadcast to online subscribers missed it. Nothing was refused;
+  nothing was attempted.
+
+  There is now a watchdog: while a connection is wanted, waldo notices a
+  monitor that has stopped and starts it again, on a 10-second interval and on
+  its own `visibilitychange` listener. It deliberately does NOTHING while the
+  monitor is running, so it never opens a competing socket or interferes with
+  ActionCable's backoff, and it never undoes a deliberate `disconnectCable()`
+  or a teardown from `configureCable()`.
+
+### Added
+
+- `checkConnection()` is exported. It performs one watchdog pass and returns
+  what it did (`open`, `monitor-running`, `monitor-restarted`, `opened`,
+  `not-wanted`, `no-consumer`, `error`), which makes the recovery path
+  testable and gives an application a way to force a check -- after a resume
+  from sleep, say.
+
+### Changed
+
+- Every read of ActionCable's internals is guarded and returns `error` rather
+  than throwing, so a future rename inside ActionCable degrades the watchdog
+  instead of breaking a consumer's render or heartbeat.
+
+## 0.1.15 - 2026-11-10
+
+### Fixed
+
+- **A reconnecting client kept sending its ORIGINAL token, forever.** The auth
+  token was read once and baked into the consumer's URL string at first
+  connect. ActionCable's `Consumer` declares `get url()`, which re-runs
+  `createWebSocketURL` on every connection attempt -- so passing a string meant
+  each reconnect after a sleep, a network blip or a server restart reused the
+  token from page load.
+
+  With a short-lived access token that is a silent, permanent failure. The
+  first reconnect after expiry is rejected, every retry sends the same dead
+  token, and the client sits disconnected while looking merely idle. Presence
+  empties and anything broadcast to "online" subscribers reaches nobody. In
+  one case a tab opened a socket and the server closed it 74ms later, rejected,
+  while the application kept working and reported nothing.
+
+  `getConsumer` now hands `createConsumer` a FUNCTION, so the token is resolved
+  per attempt and a refreshed one is picked up by the next retry with no
+  intervention.
+
+### Added
+
+- **`getToken` may now return a promise.** A token provider that has to refresh
+  before it can answer could not be expressed before, because the URL callback
+  is invoked synchronously while opening a socket. An async provider is now
+  resolved in the background and its result cached for the next attempt, which
+  costs at most one refused attempt given ActionCable's backoff. Returning a
+  plain value still works exactly as before and stays synchronous.
+
+- A throwing `getToken` no longer takes the socket down with it. A storage
+  accessor can raise outright with cookies blocked or in a private window; the
+  connection now proceeds without a token and lets the server decide.
+
+### Changed
+
+- A **synchronous** `getToken` returning `null` is now taken at face value: the
+  socket connects with no token and the server decides. Previously the last
+  cached token was reused, so after a sign-out a client kept reconnecting with
+  the OLD token rather than being refused properly. A rejected or throwing
+  provider still falls back to the last known token, since those mean "could
+  not answer" rather than "there is no token".
+
 ## 0.1.14 - 2026-11-06
 
 ### Fixed

data/README.md

@@ -81,6 +81,71 @@ configureCable({
 </PresenceProvider>
 ```
 
+### Reconnection
+
+ActionCable reconnects dropped sockets through its own `ConnectionMonitor`, and
+that is still what does the work here. But the monitor can be switched off
+permanently -- `close({allowReconnect: false})` calls `monitor.stop()`, which
+unregisters its `visibilitychange` listener, and nothing in ActionCable
+re-registers it. Rails sends a disconnect with `reconnect: false` for an
+unauthorized or remotely-disconnected connection, so the far end can put a
+browser tab permanently offline.
+
+Since 0.1.16 waldo watches for that: while a connection is wanted it notices a
+stopped monitor and starts it again, on a 10-second interval and on its own
+visibility listener. It does nothing while the monitor is running, so it never
+opens a competing socket, and it never undoes a deliberate `disconnectCable()`.
+
+`checkConnection()` runs one pass on demand and returns what it did, which is
+useful after a resume from sleep or any point an app knows more than a timer
+does:
+
+```jsx
+import { checkConnection } from '@byscott-io/where-is-waldo';
+
+// e.g. after regaining network
+window.addEventListener('online', () => checkConnection());
+```
+
+### `getToken` and short-lived tokens
+
+`getToken` is called **once per connection attempt**, not once at startup. That
+matters because ActionCable reconnects on its own -- after a sleep, a network
+blip, or a server restart -- and each attempt asks again. So returning the
+current token keeps a long-lived tab connected, while capturing one in a
+closure does not:
+
+```jsx
+// Good: read at call time, so a rotated token is picked up on reconnect.
+getToken: () => localStorage.getItem('token')
+
+// Broken: captured once; every reconnect resends the original token, and once
+// it expires the connection is refused for the life of the page.
+const token = localStorage.getItem('token');
+getToken: () => token
+```
+
+**It may also return a promise**, for a provider that has to refresh before it
+can answer:
+
+```jsx
+getToken: async () => (await auth.freshToken()) || null
+```
+
+The URL callback cannot await -- ActionCable invokes it synchronously while
+opening a socket -- so an async provider is resolved in the background and its
+result used from the next attempt. Given ActionCable's backoff that costs at
+most one refused attempt. The provider is not invoked again while a resolve is
+outstanding, so a reconnect storm will not fire a refresh request per attempt.
+
+Two smaller guarantees:
+
+- Returning `null` from a **synchronous** provider is taken at face value: the
+  socket connects with no token and the server decides. Use that on sign-out.
+- A provider that **throws** does not take the connection down. The last known
+  token is used instead, since a storage accessor can raise outright with
+  cookies blocked or in a private window.
+
 ```jsx
 // any component — subscribe to an event type and filter the payload yourself.
 // Auto-unsubscribes on unmount; no central handler config.

data/VERSION

@@ -1 +1 @@
-0.1.14
+0.1.16

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: where_is_waldo
 version: !ruby/object:Gem::Version
-  version: 0.1.14
+  version: 0.1.16
 platform: ruby
 authors:
 - Scott Gibson