monkrb 0.23.1 → 0.24.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: ef86c4755d55dba598019b3964d0c9abd29176f4a6bf2807a699e1ac883202e5
4
- data.tar.gz: 6b7082937eb3b58f03ebe309df0ad6a2eed1722347d38ffce2e4d24cfdd4a92a
3
+ metadata.gz: 6ba1b5d02f6332ab70269629bb7f89cc92e4e9432a0f91c90e8ada63a41160f6
4
+ data.tar.gz: cd559890f53c4916b124d49eeb446cbaf97bcae3b11a2fb29354e0938b912194
5
5
  SHA512:
6
- metadata.gz: 65464f1edfc7ec5edcb77a4f2fed00b0a94ba4e51f534b7e3f089b9e90b578a352d58d32b58f77e9657aa1329ca26d2446beb118bce311652fbe25c0ff220d9c
7
- data.tar.gz: 9801a314ff3b7a299626fd4085752a87079bfd6b1a4110021f117906a5e4c4c5040fb82c0ea3dad74510dd34491ae71211124cd6ba9b0db5bdea35285b3622db
6
+ metadata.gz: d0518384328513e6731f4f2d7530a106747aa7062ec34bc8f91da4b1c330b4750baaa4f9fe25ea664be559f5d8288dd3be37a9bb98c0cbeb3a0a133ddccb4d15
7
+ data.tar.gz: 33f04fcbd58dc8551ea5243f1beacf5df3711e854872f5bef602872548c0769dd0ed8f526c19ac865dd8c6f83929c0db9842e86d0247d1a83dddb3edc9d4b1de
data/CHANGELOG.md CHANGED
@@ -4,6 +4,59 @@ All notable changes to this project are documented here. Format is loosely
4
4
  [Keep a Changelog](https://keepachangelog.com/); versions are as released
5
5
  in `lib/monk/version.rb`.
6
6
 
7
+ ## 0.24.0 - 2026-11-13
8
+
9
+ ### Added
10
+
11
+ - **Presence: who is online (`monk add presence`).** Whether a signed-in
12
+ person has a page open and visible (`:online`), only hidden ones
13
+ (`:away`), or none (`:offline`, with `last_seen_at`), across tabs,
14
+ devices and WebSocket processes: `Monk::Presence.status(subjects)` and
15
+ `online?(subject)`, one query from any process. Each
16
+ `bin/websocket_server` process counts its signed-in sockets in memory
17
+ and writes what changed once a second to Postgres; a person stays as
18
+ they were for a 20 s grace after their last page closes, so a deploy
19
+ or a phone changing networks changes nobody's status. Every transition
20
+ is settled once across processes, and `Monk::Presence.on_change` runs
21
+ in `bin/server` with each batch of changes, in one process at a time,
22
+ elected through a Postgres lock, with another taking over when it
23
+ stops. The generator writes `config/presence.rb`, the migration, a dot
24
+ partial and an example pushing changes to pages through Live. ADR 0019;
25
+ [`presence.md`](docs/guides/presence.md).
26
+
27
+ ### Changed
28
+
29
+ - **`ping_interval:` closes silent connections.** A WebSocket connection
30
+ that sends nothing, not even a pong, for two ping intervals is closed:
31
+ a peer that vanished without closing (a phone that changed network)
32
+ used to hold its socket and its subscriptions until the kernel gave
33
+ up, about 15 minutes on Linux. The heartbeat sleeps until its next
34
+ ping or that deadline, whichever is first, and a ping that can't go
35
+ out at once is skipped, so a write blocked on a dead peer's full
36
+ buffer can't keep the close from happening. `ping_interval:` must now
37
+ be at least 5 s (`Server::MIN_PING_INTERVAL`). The scaffolded
38
+ `bin/websocket_server` sets `ping_interval: 25`. A ping that fails
39
+ with a network error (`EHOSTDOWN`, seen on a phone turning Wi-Fi off)
40
+ no longer ends the heartbeat, and with it that close.
41
+ - **The Live client on real networks.** While its page is visible it
42
+ sends a ping in Live's protocol (`{"op":"ping"}`, answered with
43
+ `{"op":"pong"}`) every 25 s, and gives up on a socket that answers
44
+ nothing within 10 s instead of waiting for the browser to close it;
45
+ new `monk-live:stale` event, and `disconnected` now carries a
46
+ `reason` (`closed` with its `code`, `timeout`, `restored`). It
47
+ reconnects at once, not after the backoff, when the page is shown
48
+ again, comes back online, resumes or is restored from the
49
+ back/forward cache; it doesn't try while offline, and a hidden page
50
+ tries once, then waits to be shown. Events from a socket it gave up
51
+ on are ignored, so a late close can't start a second connection.
52
+ When its page is hidden it stops pinging and sends `{"op":"hidden"}`
53
+ once (no reply), which presence reads as away at once; on open, a
54
+ visible page pings at once.
55
+ - **`config.ru`, `config/load.rb` and `bin/websocket_server`** start
56
+ presence when `config/presence.rb` exists, and do nothing otherwise.
57
+ Existing apps that want presence update them first
58
+ ([`upgrading.md`](docs/guides/upgrading.md), 0.24).
59
+
7
60
  ## 0.23.1 - 2026-11-10
8
61
 
9
62
  ### Changed
data/README.md CHANGED
@@ -21,7 +21,7 @@ bin/server # -> http://localhost:9292/hello
21
21
  monk add --list # the modules you can add: postgres, auth, jobs, live...
22
22
  ```
23
23
 
24
- `monk new` scaffolds the app's own `Gemfile` with `gem "monkrb", "~> 0.23", require: "monk"`.
24
+ `monk new` scaffolds the app's own `Gemfile` with `gem "monkrb", "~> 0.24", require: "monk"`.
25
25
 
26
26
  `monk new` writes a working skeleton (an HTML home page, a `/hello` route, a `/api/hello` JSON route, `public/`, its tests, a `SETUP.md` and an `AGENTS.md` for coding agents), with the app's own code under `app/`: `app/app.rb` and `app/routes/` for routes, `app/views/`, and one directory per role (`models/`, `presenters/`, `helpers/`, `mailers/`, `broadcasts/`, `jobs/`). `monk add` adds Postgres, Redis, email, auth, background jobs, WebSocket and live updates, to a new app or an old one, each with its wiring, commented examples of how to use it, and a test (`monk new my_app --with auth,jobs` does both at once): see [`docs/guides/scaffolding.md`](docs/guides/scaffolding.md), which also says where each kind of code goes.
27
27
 
@@ -65,6 +65,7 @@ Everything beyond the core is opt-in (`require "monk"` alone loads none of it).
65
65
  | Background jobs | `Monk::Jobs`: a queue in Postgres, run by `bin/jobs` on worker Ractors; retries with backoff, scheduled jobs, recurring jobs on a cron schedule (UTC), enqueue inside the app's own transaction, `drain!` for tests | `require "monk/jobs"` (+ `require "monk/jobs/runtime"` in the job process); needs the `pg` gem and a registered Postgres connection | [`jobs.md`](docs/guides/jobs.md) |
66
66
  | WebSocket | `Monk::WebSocket`: RFC 6455 server as its own process, Redis or Postgres fan-out | `require "monk/websocket"`; fan-out: `require "monk/websocket/redis_fanout"` (+ the `redis` gem) or `require "monk/websocket/pg_fanout"` (+ the `pg` gem) | [`websocket.md`](docs/guides/websocket.md) |
67
67
  | Live updates | `Monk::Live`: server-rendered HTML patches pushed to open tabs | `require "monk/live"`; needs the WebSocket server and, across processes, Redis or Postgres | [`live.md`](docs/guides/live.md) |
68
+ | Presence | `Monk::Presence`: whether a signed-in person has a page open and visible (online), only hidden ones (away), or none (offline, with when they were last seen), across tabs, devices and WebSocket processes; an `on_change` hook in `bin/server` | `require "monk/presence"`; needs auth, the WebSocket server and Postgres; away needs Live | [`presence.md`](docs/guides/presence.md) |
68
69
  | File storage | `Monk::Storage`: files by key in any S3-compatible bucket (Hetzner, R2, B2, AWS), local files in development and test; browser uploads and downloads through signed links, never through a worker Ractor | `require "monk/storage"`; no gem needed | [`storage.md`](docs/guides/storage.md) |
69
70
  | Scaffolding | `monk new` and `monk add`: one generator per module, for a new app or an existing one; text or `--json` output | — (the `monk` command: `monk new NAME --with ...`, `monk add MODULE`, `monk add --list`) | [`scaffolding.md`](docs/guides/scaffolding.md) |
70
71
 
@@ -89,6 +90,6 @@ More (server modes, Docker) in [`docs/development.md`](docs/development.md).
89
90
 
90
91
  ## Status
91
92
 
92
- Monk is **pre-1.0** (see `lib/monk/version.rb` and the [changelog](CHANGELOG.md)): the API may still change between minor versions. The core is described in [`docs/history/core-plan.md`](docs/history/core-plan.md). Features to add are listed in [`docs/roadmap.md`](docs/roadmap.md). Done so far, each with its own design doc and plan: persistence, migrations, HTML templating and static assets, auth and sessions, WebSocket with Redis fan-out, log levels, live updates (`Monk::Live`, as of 2026-09-19), deployment support (Dockerfile scaffolding, `docs/guides/deploying.md`), the RubyGems release as `monkrb` (both 2026-09-22), and `Monk::WebSocket::PgFanout`/`monk new --live --postgres` — the same cross-process fan-out over Postgres `LISTEN`/`NOTIFY` instead of Redis, for an app that doesn't want a second piece of infrastructure (`docs/design/live-pg-fanout.md`, 2026-09-24), the built-in mailer `Monk::Mail` (0.17, 2026-09-26, ADR 0012), and background jobs on Postgres, `Monk::Jobs`, with mail sent from jobs (0.18, 2026-09-29, ADRs 0013 and 0014). In 0.19 (2026-10-01): `monk new` lays the app out under `app/`, one directory per role (ADR 0015); a WebSocket fanout listens only in the process that holds the sockets (`#listen!`); `authenticate: :optional` lets visitors' sockets in anonymously, for Live's rules to decide; and the WebSocket server stops cleanly on `TERM` (`docs/design/websocket.md`). In 0.20 (2026-10-05): Monk recovers from a dropped database connection (a Postgres restart, a failover) without a process restart. `checkout` reconnects a dead connection before running its block, never retrying the block itself; both fanouts' listeners reconnect and then make every open page resync; and a route that raises logs why (`docs/history/plan-pg-reconnect.md`). Also new: connection pools for Ractors that shouldn't each hold a connection (`Monk::Persistence::Pg.pool`). The WebSocket server's session checks, Live's subscribe rules and `PgFanout`'s publisher can run through one, so open pages share a few connections instead of holding one each: 1,000 open sockets on 4 connections (`docs/guides/persistence.md`, "Pools"; `docs/history/plan-pg-pool.md`). In 0.21 (2026-10-09): scaffolding by module. `monk new` makes the core app, and `monk add` adds a module (Postgres, Redis, mail, auth, jobs, WebSocket, Live) to any app, new or existing, with its wiring, commented examples, a test, and its sections of `SETUP.md` and an `AGENTS.md` for coding agents; `--json` for agents and scripts. Redis and WebSocket become modules of their own, the WebSocket transport is chosen once per app, and `monk new`'s module flags are gone (ADR 0017, `docs/guides/scaffolding.md`, `docs/history/plan-scaffold.md`). In 0.22 (2026-10-13): recurring jobs on a cron schedule, `Monk::Jobs.recurring` in `config/recurring.rb`, enqueued once per occurrence however many `bin/jobs` run (ADR 0016, `docs/guides/jobs.md`); auth housekeeping, with a login-email rate limit in the database, an index on `sessions (subject)` and a nightly cleanup job (`docs/guides/auth.md`); and an upgrade guide for apps made with an earlier Monk (`docs/guides/upgrading.md`). In 0.22.1 (2026-10-20): the WebSocket server queues a connect burst instead of collapsing under it, refuses a handshake it can't check with a `503`, and takes more connects a second with thousands of sockets open: fewer allocations a connect, GC settings in `bin/websocket_server`, and `WS_PROCESSES` for several server processes on one port (`docs/guides/websocket.md`, `docs/plan-ws-connect-ceiling.md`). In 0.22.2 (2026-10-22): a fix for a handshake that could die when two connections were the first after boot (`docs/plan-digest-preload.md`). In 0.23 (2026-10-26): file storage, `Monk::Storage`, in any S3-compatible bucket (Hetzner, R2, B2, AWS) through Monk's own SigV4 signer, with local files in development and test that behave like a bucket. Browsers upload straight to the bucket and download through a redirect to a signed link, so no worker Ractor waits on the bytes, and `monk add storage` scaffolds the flow (ADR 0018, `docs/guides/storage.md`, `docs/history/plan-storage.md`). In 0.23.1 (2026-11-10): fewer allocations per request in models and views, about half as many objects for a page of 50 rows through a partial, so less GC on Ruby 4.0, where every GC stops every worker; responses are byte-identical. Route blocks also run as methods of `Monk::Context` instead of through `instance_exec`, the same on 4.0 and what lets Ruby 4.1's per-Ractor GC work.
93
+ Monk is **pre-1.0** (see `lib/monk/version.rb` and the [changelog](CHANGELOG.md)): the API may still change between minor versions. The core is described in [`docs/history/core-plan.md`](docs/history/core-plan.md). Features to add are listed in [`docs/roadmap.md`](docs/roadmap.md). Done so far, each with its own design doc and plan: persistence, migrations, HTML templating and static assets, auth and sessions, WebSocket with Redis fan-out, log levels, live updates (`Monk::Live`, as of 2026-09-19), deployment support (Dockerfile scaffolding, `docs/guides/deploying.md`), the RubyGems release as `monkrb` (both 2026-09-22), and `Monk::WebSocket::PgFanout`/`monk new --live --postgres` — the same cross-process fan-out over Postgres `LISTEN`/`NOTIFY` instead of Redis, for an app that doesn't want a second piece of infrastructure (`docs/design/live-pg-fanout.md`, 2026-09-24), the built-in mailer `Monk::Mail` (0.17, 2026-09-26, ADR 0012), and background jobs on Postgres, `Monk::Jobs`, with mail sent from jobs (0.18, 2026-09-29, ADRs 0013 and 0014). In 0.19 (2026-10-01): `monk new` lays the app out under `app/`, one directory per role (ADR 0015); a WebSocket fanout listens only in the process that holds the sockets (`#listen!`); `authenticate: :optional` lets visitors' sockets in anonymously, for Live's rules to decide; and the WebSocket server stops cleanly on `TERM` (`docs/design/websocket.md`). In 0.20 (2026-10-05): Monk recovers from a dropped database connection (a Postgres restart, a failover) without a process restart. `checkout` reconnects a dead connection before running its block, never retrying the block itself; both fanouts' listeners reconnect and then make every open page resync; and a route that raises logs why (`docs/history/plan-pg-reconnect.md`). Also new: connection pools for Ractors that shouldn't each hold a connection (`Monk::Persistence::Pg.pool`). The WebSocket server's session checks, Live's subscribe rules and `PgFanout`'s publisher can run through one, so open pages share a few connections instead of holding one each: 1,000 open sockets on 4 connections (`docs/guides/persistence.md`, "Pools"; `docs/history/plan-pg-pool.md`). In 0.21 (2026-10-09): scaffolding by module. `monk new` makes the core app, and `monk add` adds a module (Postgres, Redis, mail, auth, jobs, WebSocket, Live) to any app, new or existing, with its wiring, commented examples, a test, and its sections of `SETUP.md` and an `AGENTS.md` for coding agents; `--json` for agents and scripts. Redis and WebSocket become modules of their own, the WebSocket transport is chosen once per app, and `monk new`'s module flags are gone (ADR 0017, `docs/guides/scaffolding.md`, `docs/history/plan-scaffold.md`). In 0.22 (2026-10-13): recurring jobs on a cron schedule, `Monk::Jobs.recurring` in `config/recurring.rb`, enqueued once per occurrence however many `bin/jobs` run (ADR 0016, `docs/guides/jobs.md`); auth housekeeping, with a login-email rate limit in the database, an index on `sessions (subject)` and a nightly cleanup job (`docs/guides/auth.md`); and an upgrade guide for apps made with an earlier Monk (`docs/guides/upgrading.md`). In 0.22.1 (2026-10-20): the WebSocket server queues a connect burst instead of collapsing under it, refuses a handshake it can't check with a `503`, and takes more connects a second with thousands of sockets open: fewer allocations a connect, GC settings in `bin/websocket_server`, and `WS_PROCESSES` for several server processes on one port (`docs/guides/websocket.md`, `docs/plan-ws-connect-ceiling.md`). In 0.22.2 (2026-10-22): a fix for a handshake that could die when two connections were the first after boot (`docs/plan-digest-preload.md`). In 0.23 (2026-10-26): file storage, `Monk::Storage`, in any S3-compatible bucket (Hetzner, R2, B2, AWS) through Monk's own SigV4 signer, with local files in development and test that behave like a bucket. Browsers upload straight to the bucket and download through a redirect to a signed link, so no worker Ractor waits on the bytes, and `monk add storage` scaffolds the flow (ADR 0018, `docs/guides/storage.md`, `docs/history/plan-storage.md`). In 0.23.1 (2026-11-10): fewer allocations per request in models and views, about half as many objects for a page of 50 rows through a partial, so less GC on Ruby 4.0, where every GC stops every worker; responses are byte-identical. Route blocks also run as methods of `Monk::Context` instead of through `instance_exec`, the same on 4.0 and what lets Ruby 4.1's per-Ractor GC work. In 0.24 (2026-11-13): Live on real networks and presence. The WebSocket server closes a connection silent for two ping intervals, and the Live client pings while its page is visible, gives up on a silent socket after 10 s, and reconnects when the page is shown or back online, measured on iPhone and Android as well as desktop. `Monk::Presence` says who is online, away or offline, with an `on_change` hook to push it to pages, and `monk add presence` scaffolds it (ADR 0019, `docs/guides/presence.md`, `docs/plan-live-networks-presence.md`).
93
94
 
94
95
  [Made with Love ❤️, Ruby 💎 and AI 🤖](docs/ai_usage_disclaimer.md)
@@ -0,0 +1,22 @@
1
+ # Whether a signed-in person has a page open (Monk::Presence), counted by
2
+ # bin/websocket_server and reacted to in bin/server.
3
+ Monk::Generator.define(:presence) do
4
+ summary "Who is online, from the WebSocket's sockets"
5
+ installed_if "config/presence.rb"
6
+ depends_on :auth, :websocket
7
+
8
+ copy "config/presence.rb", role: :wiring
9
+ copy "app/views/presence/_dot.erb", role: :view
10
+ copy "test/presence_test.rb", role: :test
11
+ migration "create_presence_tables"
12
+
13
+ setup_section "presence/setup.md"
14
+ agents_section "presence/agents.md"
15
+ example "presence-dots", todo: lambda { |installed|
16
+ if installed.include?("live")
17
+ "uncomment to push each change to the pages showing those people"
18
+ else
19
+ "needs live (monk add live) to push each change to open pages; or write your own on_change"
20
+ end
21
+ }
22
+ end
@@ -2,6 +2,6 @@ require_relative "generator"
2
2
 
3
3
  # Monk's own modules, one generator each (docs/adr/0017), in dependency
4
4
  # order only for readability: the registry resolves dependencies itself.
5
- %w[base postgres redis mail auth jobs websocket live storage].each do |name|
5
+ %w[base postgres redis mail auth jobs websocket live presence storage].each do |name|
6
6
  require_relative "generators/#{name}"
7
7
  end
@@ -4,6 +4,13 @@
4
4
  // may have missed something (ADR 0007, 0011). No JS API: it reports what it
5
5
  // does through `monk-live:*` DOM events on `document`.
6
6
  //
7
+ // On real networks (docs/plan-live-networks-presence.md, A2-A3): while the
8
+ // page is visible it pings the server and gives up on a socket that doesn't
9
+ // answer (`stale`, then `disconnected` with reason "timeout"); it comes back
10
+ // at once when the page is shown again, the network returns, the page
11
+ // resumes or is restored from the back/forward cache; and it doesn't keep
12
+ // reconnecting while hidden or offline.
13
+ //
7
14
  // <meta name="monk-live-url" content="ws://localhost:9293">
8
15
  // <script type="module" src="/js/monk_live.js"></script>
9
16
  //
@@ -11,7 +18,8 @@
11
18
 
12
19
  import { Idiomorph } from "./idiomorph.js";
13
20
  import {
14
- INITIAL_DELAY, nextDelay, jittered, topicsFrom, diffTopics, subscribeMessage, unsubscribeMessage, parseMessage, checkSeq, resyncVerdict,
21
+ INITIAL_DELAY, HEARTBEAT, PONG_TIMEOUT, nextDelay, jittered, topicsFrom, diffTopics, subscribeMessage, unsubscribeMessage,
22
+ pingMessage, hiddenMessage, parseMessage, checkSeq, resyncVerdict, reconnectDecision, returnAction,
15
23
  } from "./protocol.js";
16
24
 
17
25
  const emit = (name, detail = {}) => document.dispatchEvent(new CustomEvent(`monk-live:${name}`, { detail }));
@@ -45,6 +53,19 @@ let resyncAgain = false;
45
53
  let resyncRetryDelay = INITIAL_DELAY;
46
54
  let resyncRetryTimer = null;
47
55
  let stopped = false;
56
+ // Each connect() makes a new generation; events from an older socket (one
57
+ // given up on, whose onclose comes late) are ignored, so they can't
58
+ // schedule a second reconnect.
59
+ let generation = 0;
60
+ let reconnectTimer = null;
61
+ let heartbeatTimer = null;
62
+ let pongTimer = null;
63
+ // Reconnects tried since the page was last visible (reconnectDecision).
64
+ let hiddenAttempts = 0;
65
+
66
+ const isHidden = () => document.visibilityState === "hidden";
67
+ const isOpen = () => socket?.readyState === WebSocket.OPEN;
68
+ const reconnectState = () => ({ hidden: isHidden(), online: navigator.onLine !== false, hiddenAttempts });
48
69
 
49
70
  function applyOp({ target, mode, html }) {
50
71
  let nodes;
@@ -94,6 +115,8 @@ function onMessage(event) {
94
115
  case "error":
95
116
  console.warn("monk-live: server error", message.reason);
96
117
  break;
118
+ case "pong":
119
+ break;
97
120
  default:
98
121
  break;
99
122
  }
@@ -103,6 +126,8 @@ function stop(reason) {
103
126
  stopped = true;
104
127
  needsResync = false;
105
128
  clearTimeout(resyncRetryTimer);
129
+ clearTimeout(reconnectTimer);
130
+ stopHeartbeat();
106
131
  socket?.close();
107
132
  emit("stopped", { reason });
108
133
  }
@@ -168,8 +193,14 @@ function reconcileTopics() {
168
193
  }
169
194
 
170
195
  function connect() {
196
+ clearTimeout(reconnectTimer);
197
+ reconnectTimer = null;
198
+ if (socket) retire({ reason: "closed" });
199
+ if (isHidden()) hiddenAttempts += 1;
200
+ const current = ++generation;
171
201
  socket = new WebSocket(url);
172
202
  socket.onopen = () => {
203
+ if (current !== generation) return;
173
204
  delay = INITIAL_DELAY;
174
205
  lastSeq = 0;
175
206
  subscribed = [];
@@ -179,17 +210,137 @@ function connect() {
179
210
  needsResync = everConnected;
180
211
  everConnected = true;
181
212
  socket.send(subscribeMessage(currentTopics()));
213
+ startHeartbeat();
214
+ // Presence counts this socket as hidden until its first ping (ADR
215
+ // 0019): a visible page pings now, so it reads as online at once.
216
+ if (!isHidden()) ping();
182
217
  emit("connected");
183
218
  };
184
- socket.onmessage = onMessage;
185
- socket.onclose = () => {
186
- emit("disconnected");
187
- if (stopped) return;
188
- setTimeout(connect, jittered(delay));
189
- delay = nextDelay(delay);
219
+ socket.onmessage = (event) => {
220
+ if (current !== generation) return;
221
+ // Any frame shows the socket is alive, not only a pong.
222
+ clearTimeout(pongTimer);
223
+ pongTimer = null;
224
+ onMessage(event);
225
+ };
226
+ socket.onclose = (event) => {
227
+ if (current !== generation) return;
228
+ lost({ reason: "closed", code: event.code });
190
229
  };
191
230
  }
192
231
 
232
+ // The socket is gone, closed or given up on: report it once, then come back
233
+ // when reconnectDecision allows; otherwise a page event (visible, online)
234
+ // brings it back.
235
+ function lost(detail) {
236
+ retire(detail);
237
+ if (!stopped) scheduleReconnect();
238
+ }
239
+
240
+ function retire(detail) {
241
+ generation += 1;
242
+ const old = socket;
243
+ socket = null;
244
+ stopHeartbeat();
245
+ old.onopen = old.onmessage = old.onclose = null;
246
+ if (old.readyState <= WebSocket.OPEN) old.close();
247
+ emit("disconnected", detail);
248
+ }
249
+
250
+ function scheduleReconnect() {
251
+ if (reconnectTimer || reconnectDecision(reconnectState()) === "wait") return;
252
+ reconnectTimer = setTimeout(() => {
253
+ reconnectTimer = null;
254
+ if (!stopped && !socket && reconnectDecision(reconnectState()) === "connect") connect();
255
+ }, jittered(delay));
256
+ delay = nextDelay(delay);
257
+ }
258
+
259
+ // The page came back: no waiting out the backoff, which may have reached
260
+ // 30 s. Still jittered, from the first step.
261
+ function connectSoon() {
262
+ clearTimeout(reconnectTimer);
263
+ reconnectTimer = null;
264
+ delay = INITIAL_DELAY;
265
+ scheduleReconnect();
266
+ }
267
+
268
+ // Only while visible: a hidden page's timers are throttled, and the server's
269
+ // own ping covers it.
270
+ function startHeartbeat() {
271
+ stopHeartbeat();
272
+ if (isHidden() || !isOpen()) return;
273
+ heartbeatTimer = setInterval(ping, HEARTBEAT);
274
+ }
275
+
276
+ function stopHeartbeat() {
277
+ clearInterval(heartbeatTimer);
278
+ heartbeatTimer = null;
279
+ clearTimeout(pongTimer);
280
+ pongTimer = null;
281
+ }
282
+
283
+ // A network that went away under the socket can leave it "open" for minutes:
284
+ // no frame within PONG_TIMEOUT and it's given up on now, not when the
285
+ // browser gets round to onclose.
286
+ function ping() {
287
+ if (!isOpen()) return;
288
+ socket.send(pingMessage());
289
+ pongTimer ??= setTimeout(() => {
290
+ pongTimer = null;
291
+ emit("stale");
292
+ lost({ reason: "timeout" });
293
+ }, PONG_TIMEOUT);
294
+ }
295
+
296
+ // Hidden: no more pings, and the server is told at once (presence's Away).
297
+ function goneHidden() {
298
+ stopHeartbeat();
299
+ if (isOpen()) socket.send(hiddenMessage());
300
+ }
301
+
302
+ // Visible again, online again, resumed: probe or reconnect at once, and
303
+ // retry a resync that failed while away.
304
+ function comeBack() {
305
+ if (stopped) return;
306
+ if (!isHidden()) hiddenAttempts = 0;
307
+ switch (returnAction(socket?.readyState)) {
308
+ case "probe":
309
+ if (!isHidden()) {
310
+ startHeartbeat();
311
+ ping();
312
+ }
313
+ break;
314
+ case "connect":
315
+ if (socket) retire({ reason: "closed" });
316
+ connectSoon();
317
+ break;
318
+ }
319
+ if (needsResync && isOpen() && !resyncing) {
320
+ clearTimeout(resyncRetryTimer);
321
+ resyncRetryTimer = null;
322
+ resync();
323
+ }
324
+ }
325
+
326
+ function listen() {
327
+ document.addEventListener("visibilitychange", () => (isHidden() ? goneHidden() : comeBack()));
328
+ document.addEventListener("resume", comeBack);
329
+ window.addEventListener("online", comeBack);
330
+ // Nothing can get through: no reconnect loop until the network returns.
331
+ window.addEventListener("offline", () => {
332
+ clearTimeout(reconnectTimer);
333
+ reconnectTimer = null;
334
+ });
335
+ // Restored from the back/forward cache: the browser closed the socket
336
+ // when the page went in, and its close event may not have come yet.
337
+ window.addEventListener("pageshow", (event) => {
338
+ if (!event.persisted || stopped) return;
339
+ if (socket) retire({ reason: "restored" });
340
+ comeBack();
341
+ });
342
+ }
343
+
193
344
  function start() {
194
345
  url = document.querySelector('meta[name="monk-live-url"]')?.content;
195
346
  if (!url) {
@@ -197,6 +348,7 @@ function start() {
197
348
  return;
198
349
  }
199
350
  if (currentTopics().length === 0) return;
351
+ listen();
200
352
  connect();
201
353
  }
202
354
 
@@ -5,6 +5,15 @@
5
5
  export const INITIAL_DELAY = 500;
6
6
  export const MAX_DELAY = 30000;
7
7
 
8
+ // The client's heartbeat (docs/plan-live-networks-presence.md, A2): while
9
+ // the page is visible, a Live ping every HEARTBEAT; no frame at all within
10
+ // PONG_TIMEOUT after one means the socket is dead, though the browser may
11
+ // not say so for minutes (a network that went away under it). Not sent
12
+ // while hidden: browsers throttle a hidden page's timers, so a timeout
13
+ // there would fire late and wrongly, and the server's own ping covers it.
14
+ export const HEARTBEAT = 25000;
15
+ export const PONG_TIMEOUT = 10000;
16
+
8
17
  // Reconnect backoff: double, capped.
9
18
  export const nextDelay = (delay) => Math.min(delay * 2, MAX_DELAY);
10
19
 
@@ -33,6 +42,32 @@ export function diffTopics(current, wanted) {
33
42
 
34
43
  export const subscribeMessage = (topics) => JSON.stringify({ op: "subscribe", topics });
35
44
  export const unsubscribeMessage = (topics) => JSON.stringify({ op: "unsubscribe", topics });
45
+ export const pingMessage = () => JSON.stringify({ op: "ping" });
46
+ // Sent once as the page is hidden, so presence reads Away at once rather
47
+ // than after 2 x HEARTBEAT without a ping (which still covers a page
48
+ // frozen before this gets out).
49
+ export const hiddenMessage = () => JSON.stringify({ op: "hidden" });
50
+
51
+ // With no socket, whether to open one now or wait for the page to come back
52
+ // (visible, online). Offline, an attempt can't succeed. Hidden, one attempt
53
+ // is made: Android keeps a hidden page's socket, so a dropped one comes
54
+ // back without unlocking; iOS resets a socket opened by a hidden page
55
+ // within seconds, so after that one the page waits to be shown.
56
+ export function reconnectDecision({ hidden, online, hiddenAttempts }) {
57
+ if (!online) return "wait";
58
+ if (hidden && hiddenAttempts >= 1) return "wait";
59
+ return "connect";
60
+ }
61
+
62
+ // The page came back (visible, online, resumed), given the socket's
63
+ // readyState (undefined without one): an open socket may be dead without
64
+ // knowing it, so it's probed with a ping; a connecting one is left alone;
65
+ // otherwise connect now.
66
+ export function returnAction(readyState) {
67
+ if (readyState === 1) return "probe";
68
+ if (readyState === 0) return "none";
69
+ return "connect";
70
+ }
36
71
 
37
72
  const isString = (value) => typeof value === "string";
38
73
 
@@ -72,6 +107,8 @@ export function parseMessage(text) {
72
107
  return { kind: "unsubscribed", topics: message.topics ?? [] };
73
108
  case "error":
74
109
  return { kind: "error", reason: message.reason };
110
+ case "pong":
111
+ return { kind: "pong" };
75
112
  default:
76
113
  return { kind: "unknown", op: message.op };
77
114
  }
@@ -2,6 +2,11 @@ require "json"
2
2
 
3
3
  module Monk
4
4
  module Live
5
+ # Seconds between the client's pings while its page is visible:
6
+ # protocol.js's HEARTBEAT, which a test keeps equal. What Away means
7
+ # follows from it (ADR 0019), so the two are changed together.
8
+ HEARTBEAT = 25
9
+
5
10
  # One WebSocket connection's live state, running inside its own
6
11
  # connection Ractor: the subscribe/unsubscribe protocol, the topic
7
12
  # authorization check, and the relay that stamps each published
@@ -9,9 +14,21 @@ module Monk
9
14
  #
10
15
  # Client -> server: {"op":"subscribe"|"unsubscribe","topics":[...]}.
11
16
  # Replies: subscribed (+ denied), unsubscribed, or error/bad_message.
17
+ # And {"op":"ping"} -> {"op":"pong"}: the client's heartbeat, since
18
+ # browser JS can't see WebSocket pings. {"op":"hidden"}, with no
19
+ # reply: the client's page was just hidden.
12
20
  # A denial never says why or whether the topic exists.
13
21
  #
14
- # `connection` is anything with #read, #write and #subject.
22
+ # `connection` is anything with #read, #write and #subject. One that
23
+ # #tracks_presence? (Server.new(presence:)) is also told, through
24
+ # #visible=, whether its page is visible: while its client has pinged
25
+ # within visible_for, 2 x HEARTBEAT (ADR 0019). The client pings only
26
+ # while its page is visible, and at once on open, so this is Away. It
27
+ # also says when its page is hidden, so Away shows at once; the
28
+ # silence covers a page frozen before it could say so, checked on the
29
+ # connection's heartbeat (Connection#on_heartbeat), once per server
30
+ # ping: no thread of its own, which at 15K sockets cost more than
31
+ # everything else presence does (docs/plan-live-networks-presence.md).
15
32
  class Session
16
33
  # No `*`, no whitespace or NUL, ASCII only: a client can't smuggle a
17
34
  # glob or a delimiter into a topic, and only a topic that passed this
@@ -19,17 +36,23 @@ module Monk
19
36
  TOPIC_FORMAT = %r{\A[\w:.\-/@]{1,200}\z}
20
37
  MAX_TOPICS_PER_MESSAGE = 100
21
38
 
22
- def initialize(connection, registry:, rules:, max_topics:)
39
+ VISIBLE_FOR = 2 * HEARTBEAT
40
+
41
+ def initialize(connection, registry:, rules:, max_topics:, visible_for: VISIBLE_FOR)
23
42
  @connection = connection
24
43
  @registry = registry
25
44
  @rules = rules
26
45
  @max_topics = max_topics
27
46
  @topics = {} # String topic => the Symbol it is registered under
47
+ @visible_for = visible_for
48
+ @presence = connection.respond_to?(:tracks_presence?) && connection.tracks_presence?
49
+ @visibility = Mutex.new
28
50
  end
29
51
 
30
52
  def run
31
53
  @port = Ractor::Port.new
32
54
  @relay = Thread.new { relay }
55
+ @connection.on_heartbeat { check_visibility } if @presence
33
56
  while (raw = @connection.read)
34
57
  dispatch(raw)
35
58
  end
@@ -41,6 +64,9 @@ module Monk
41
64
 
42
65
  def dispatch(raw)
43
66
  message = JSON.parse(raw, max_nesting: 5)
67
+ return pinged if message.is_a?(Hash) && message["op"] == "ping"
68
+ return hidden if message.is_a?(Hash) && message["op"] == "hidden"
69
+
44
70
  topics = message.is_a?(Hash) ? message["topics"] : nil
45
71
  return reply(op: "error", reason: "bad_message") unless valid_topics?(topics)
46
72
 
@@ -94,6 +120,37 @@ module Monk
94
120
  @connection.write(JSON.generate(message))
95
121
  end
96
122
 
123
+ def pinged
124
+ if @presence
125
+ @visibility.synchronize do
126
+ @last_ping = Monk::WebSocket::Connection.monotonic
127
+ @connection.visible = true
128
+ end
129
+ end
130
+ reply(op: "pong")
131
+ end
132
+
133
+ def hidden
134
+ return unless @presence
135
+
136
+ @visibility.synchronize do
137
+ @last_ping = nil
138
+ @connection.visible = false
139
+ end
140
+ end
141
+
142
+ # On the connection's heartbeat, once per server ping: the page turns
143
+ # hidden once no ping has come for visible_for, so up to one ping
144
+ # interval late.
145
+ def check_visibility
146
+ @visibility.synchronize do
147
+ if @last_ping && Monk::WebSocket::Connection.monotonic - @last_ping >= @visible_for
148
+ @last_ping = nil
149
+ @connection.visible = false
150
+ end
151
+ end
152
+ end
153
+
97
154
  # Runs on its own thread: each published envelope gets the next
98
155
  # per-connection seq spliced in after its opening `{`. The
99
156
  # publisher's frozen string is shared by every subscriber (ADR
@@ -0,0 +1,118 @@
1
+ module Monk
2
+ module Presence
3
+ # One WebSocket process's sockets, per subject (ADR 0019, "Counting, no
4
+ # query per connect"): a Ractor holding them, told by each socket's own
5
+ # Ractor when it opens, closes, or turns visible or hidden, with a
6
+ # send, never an ask, so a connect never waits on it. The flusher reads
7
+ # what changed with #take, once a second.
8
+ #
9
+ # A socket is reported under a key of its own (Server.serve uses its
10
+ # connection's Ractor), so a late or repeated report changes nothing.
11
+ # start_visible: is what an opened socket counts as until told: true
12
+ # for app/sockets clients, which have no Away; false for Live, whose
13
+ # client pings at once when its page is visible.
14
+ class Counts
15
+ def initialize(start_visible:)
16
+ @ractor = Ractor.new(start_visible) { |visible_at_open| Counts.run(visible_at_open) }
17
+ freeze
18
+ end
19
+
20
+ # The Ractor's loop. sockets: key => [subject, visible];
21
+ # subjects: subject => [open sockets, visible sockets]; changed:
22
+ # subjects to report at the next take.
23
+ def self.run(visible_at_open)
24
+ sockets = {}
25
+ subjects = Hash.new { |h, k| h[k] = [0, 0] }
26
+ changed = {}
27
+ loop do
28
+ op, key, arg = Ractor.receive
29
+ case op
30
+ when :open
31
+ next if sockets.key?(key)
32
+
33
+ sockets[key] = [arg, visible_at_open]
34
+ counts = subjects[arg]
35
+ counts[0] += 1
36
+ counts[1] += 1 if visible_at_open
37
+ changed[arg] = true
38
+ when :close
39
+ subject, visible = sockets.delete(key)
40
+ next unless subject
41
+
42
+ counts = subjects[subject]
43
+ counts[0] -= 1
44
+ counts[1] -= 1 if visible
45
+ changed[subject] = true
46
+ when :visible
47
+ socket = sockets[key]
48
+ next if socket.nil? || socket[1] == arg
49
+
50
+ socket[1] = arg
51
+ subjects[socket[0]][1] += arg ? 1 : -1
52
+ changed[socket[0]] = true
53
+ when :take
54
+ arg.send(take(subjects, changed))
55
+ when :all
56
+ arg.send(all(subjects))
57
+ end
58
+ end
59
+ end
60
+
61
+ def self.take(subjects, changed)
62
+ result = { online: [], away: [], gone: [] }
63
+ changed.each_key do |subject|
64
+ open, visible = subjects[subject]
65
+ if open.zero?
66
+ subjects.delete(subject)
67
+ result[:gone] << subject
68
+ else
69
+ result[visible.positive? ? :online : :away] << subject
70
+ end
71
+ end
72
+ changed.clear
73
+ Ractor.make_shareable(result)
74
+ end
75
+
76
+ def self.all(subjects)
77
+ result = { online: [], away: [] }
78
+ subjects.each do |subject, (open, visible)|
79
+ result[visible.positive? ? :online : :away] << subject if open.positive?
80
+ end
81
+ Ractor.make_shareable(result)
82
+ end
83
+
84
+ def open(key, subject) = tell(:open, key, subject)
85
+
86
+ def close(key) = tell(:close, key, nil)
87
+
88
+ def visible(key, visible) = tell(:visible, key, visible)
89
+
90
+ # {online:, away:, gone:}: the subjects that changed since the last
91
+ # take, by where they are now. A subject can open and close between
92
+ # two takes and be reported gone without ever having been reported.
93
+ def take = ask(:take)
94
+
95
+ # {online:, away:}: every subject with a socket, for writing this
96
+ # process's rows again from scratch.
97
+ def all = ask(:all)
98
+
99
+ private
100
+
101
+ def tell(message, key, arg)
102
+ @ractor.send([message, key, arg])
103
+ nil
104
+ rescue Ractor::ClosedError
105
+ # The process is stopping: nothing left to count for.
106
+ nil
107
+ end
108
+
109
+ def ask(message)
110
+ port = Ractor::Port.new
111
+ @ractor.send([message, nil, port])
112
+ port.receive
113
+ ensure
114
+ port&.close
115
+ end
116
+ end
117
+ end
118
+ end