monkrb 0.23.0 → 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: b284b12a8bb2491dd6d50c14d0d1db8cb0f2bf2d62a19dc525fc6ecbec81fb30
4
- data.tar.gz: 6251d1fe25530d954df4a65f6d22a2b339cb55b87b97a8587259f8b16dbbbb24
3
+ metadata.gz: 6ba1b5d02f6332ab70269629bb7f89cc92e4e9432a0f91c90e8ada63a41160f6
4
+ data.tar.gz: cd559890f53c4916b124d49eeb446cbaf97bcae3b11a2fb29354e0938b912194
5
5
  SHA512:
6
- metadata.gz: 586f9d0355b353a5e18f638059e0636f447c4aa104ceff395efa7dc81b05529019c9fdabbeb10c489eb360ecbc6d9d5d864ef4b5b48323769c3796c7757f3b4c
7
- data.tar.gz: b03b5885c324e698b2b10946ea9289e61bbf89253fa225ab96c89d8039a8553e991c3f3158ad7f2caacc8c072c518bd752cb75e33fe6c45e645a9eecd0c2fda3
6
+ metadata.gz: d0518384328513e6731f4f2d7530a106747aa7062ec34bc8f91da4b1c330b4750baaa4f9fe25ea664be559f5d8288dd3be37a9bb98c0cbeb3a0a133ddccb4d15
7
+ data.tar.gz: 33f04fcbd58dc8551ea5243f1beacf5df3711e854872f5bef602872548c0769dd0ed8f526c19ac865dd8c6f83929c0db9842e86d0247d1a83dddb3edc9d4b1de
data/CHANGELOG.md CHANGED
@@ -4,6 +4,91 @@ 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
+
60
+ ## 0.23.1 - 2026-11-10
61
+
62
+ ### Changed
63
+
64
+ - **Fewer allocations per request in models and views.** On Ruby 4.0
65
+ every GC stops every worker Ractor, so allocations are what limit a
66
+ process's scaling. A board page (50 messages through a partial) goes
67
+ from 2,157 objects to 1,063, and a JSON read of the same messages
68
+ from 998 to 748, with byte-identical responses; GC time per request
69
+ falls about 30%.
70
+ - `Pg::Model` asks pg for Symbol-keyed rows (`field_name_type`)
71
+ instead of transforming String keys: one Hash per row, not two.
72
+ - An Array condition in `where` (and `find_all`) is one array
73
+ parameter, `col = ANY($1)`, instead of `col IN ($1, ..., $n)`;
74
+ a list of Integers is encoded without a String per id. Same rows,
75
+ nil items included.
76
+ - `<%= %>` escapes with `ERB::Escape.html_escape`, which returns
77
+ text with nothing to escape as is, and appends the result without
78
+ wrapping it in `Raw`; a template's buffer is a `Raw` from the start
79
+ rather than copied into one. `h` uses `ERB::Escape` too.
80
+ - `Context#render` no longer allocates its header key per template.
81
+ - **Route blocks run as methods.** `freeze!` defines each route and
82
+ `error` block as a private method of `Monk::Context`, once, and a
83
+ request calls it instead of `instance_exec`-ing the block. Same `self`,
84
+ ivars and return value; a block taking the context (`|c|`) still gets
85
+ it, and one needing two or more arguments keeps `instance_exec`. On
86
+ Ruby 4.1.0-preview1, `instance_exec` in a worker Ractor stops that
87
+ Ractor's own GCs: the heap grew to 1–3.8 GB between global,
88
+ stop-the-world GCs, and 4 workers served 64K req/s. As methods: 148K
89
+ req/s at 225 MB, against 120K at 86 MB on 4.0.7 (`GET /health`, 4
90
+ cores, locally). No change on 4.0.
91
+
7
92
  ## 0.23.0 - 2026-10-26
8
93
 
9
94
  ### Added
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`).
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)
data/lib/monk/base.rb CHANGED
@@ -111,6 +111,8 @@ module Monk
111
111
  end
112
112
  end
113
113
 
114
+ define_block_methods!
115
+
114
116
  Monk.freeze!
115
117
 
116
118
  # Settled once here, not read from ENV per request in
@@ -126,6 +128,7 @@ module Monk
126
128
  Ractor.make_shareable(@static_routes)
127
129
  Ractor.make_shareable(@dynamic_routes)
128
130
  Ractor.make_shareable(error_handlers)
131
+ Ractor.make_shareable(@block_methods)
129
132
  self
130
133
  end
131
134
 
@@ -168,14 +171,14 @@ module Monk
168
171
  context = Context.new(params, env)
169
172
  catch(:monk_halt) do
170
173
  begin
171
- body = context.instance_exec(context, &route[:block])
174
+ body = run_block(context, route[:block])
172
175
  [200, context.headers, [body]]
173
176
  rescue StandardError => e
174
177
  handler = error_handlers.find { |matcher, _| matcher.is_a?(Class) && e.is_a?(matcher) }
175
178
  log_exception(env, e, handled: !handler.nil?)
176
179
  if handler
177
180
  context.status = 500
178
- body = context.instance_exec(context, &handler.last)
181
+ body = run_block(context, handler.last)
179
182
  [500, context.headers, [body]]
180
183
  else
181
184
  [500, { "content-type" => "application/json" }, ['{"error":"Internal Server Error"}']]
@@ -184,6 +187,51 @@ module Monk
184
187
  end
185
188
  end
186
189
 
190
+ # Each route and error-handler block becomes a private method of
191
+ # Context, once, here, rather than running through instance_exec on
192
+ # every request. Same self, same ivars, same return value. On Ruby
193
+ # 4.1 (preview1) an instance_exec in a worker Ractor stops that
194
+ # Ractor's own, cheap GCs: its heap grows to GBs between global,
195
+ # stop-the-world ones, and adding workers makes the app slower. A
196
+ # method call doesn't, and on 4.0 the two cost the same. Blocks are
197
+ # made shareable before this, so the methods run in any Ractor.
198
+ #
199
+ # A method's arity is strict, as a lambda's: a block with no
200
+ # positional parameter is called with none, one that can take the
201
+ # context (|c|, |c = nil|, |*args|) with it. A block that needs two
202
+ # or more (instance_exec passes nil for the rest) keeps
203
+ # instance_exec.
204
+ def define_block_methods!
205
+ @block_methods = {}.compare_by_identity
206
+ blocks = routes.map { |route| route[:block] } + error_handlers.map(&:last)
207
+ blocks.each_with_index do |block, i|
208
+ name = :"__monk_block_#{object_id}_#{i}"
209
+ Context.define_method(name, &block)
210
+ Context.send(:private, name)
211
+
212
+ takes_context = block.parameters.any? { |type, _| %i[req opt rest].include?(type) }
213
+ arity = Context.instance_method(name).arity
214
+ if !takes_context
215
+ @block_methods[block] = [name, false].freeze
216
+ elsif arity == 1 || arity.between?(-2, -1)
217
+ @block_methods[block] = [name, true].freeze
218
+ else
219
+ Context.send(:remove_method, name)
220
+ end
221
+ end
222
+ end
223
+
224
+ def run_block(context, block)
225
+ name, with_context = @block_methods[block]
226
+ if name.nil?
227
+ context.instance_exec(context, &block)
228
+ elsif with_context
229
+ context.__send__(name, context)
230
+ else
231
+ context.__send__(name)
232
+ end
233
+ end
234
+
187
235
  # The request line alone ("GET /x -> 500") says nothing about why.
188
236
  # Unhandled: an error, with the first backtrace lines. Handled by an
189
237
  # `error` block: the app chose the response, so one info line --
@@ -218,7 +266,7 @@ module Monk
218
266
 
219
267
  context = Context.new({}, env, status: 404)
220
268
  catch(:monk_halt) do
221
- body = context.instance_exec(context, &handler.last)
269
+ body = run_block(context, handler.last)
222
270
  [404, context.headers, [body]]
223
271
  end
224
272
  end
data/lib/monk/context.rb CHANGED
@@ -17,6 +17,11 @@ module Monk
17
17
  include Monk::Views::Compiled
18
18
  include Monk::HeadTags
19
19
 
20
+ # Frozen once here: as literals in #render, the key was a new String
21
+ # for every template rendered, partials included.
22
+ CONTENT_TYPE = "content-type".freeze
23
+ HTML_CONTENT_TYPE = "text/html; charset=utf-8".freeze
24
+
20
25
  attr_reader :params, :env, :headers
21
26
  attr_accessor :status
22
27
 
@@ -60,7 +65,7 @@ module Monk
60
65
  # `self` bound to this same Context), and the `locals` hash passed
61
66
  # here, which is what a partial rendered inside a loop wants.
62
67
  def render(name, layout: :default, **locals)
63
- headers["content-type"] ||= "text/html; charset=utf-8"
68
+ headers[CONTENT_TYPE] ||= HTML_CONTENT_TYPE
64
69
  Monk::Views.render(self, name, locals, layout: layout)
65
70
  end
66
71
 
@@ -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
  }