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.
@@ -0,0 +1,111 @@
1
+ require "socket"
2
+
3
+ module Monk
4
+ module Presence
5
+ # A WebSocket process's presence tick, once a second on a thread of the
6
+ # main Ractor (ADR 0019): take what changed from the counts, write it
7
+ # as this process's rows, and settle transitions, signalling them with
8
+ # notify: for bin/server's reactor. The heartbeat rides the same tick.
9
+ # No app code runs here.
10
+ #
11
+ # Errors are logged and never end the process. A tick that failed may
12
+ # have lost the counts' changes it took, so the next one writes this
13
+ # process's whole state again instead.
14
+ class Tracker
15
+ TICK = 1
16
+ HEARTBEAT_INTERVAL = 5
17
+ RECONCILE_INTERVAL = 60
18
+
19
+ attr_reader :process_id
20
+
21
+ def initialize(store:, counts:, notify: false, hostname: Socket.gethostname, pid: Process.pid)
22
+ @store = store
23
+ @counts = counts
24
+ @notify = notify
25
+ @hostname = hostname
26
+ @pid = pid
27
+ @rewrite = false
28
+ end
29
+
30
+ # Registers this process. Raises if the database can't be reached,
31
+ # so a WS process with presence fails at boot, not silently.
32
+ def start
33
+ @process_id = @store.register_process(hostname: @hostname, pid: @pid)
34
+ @last_heartbeat = @last_reconcile = monotonic
35
+ self
36
+ end
37
+
38
+ def run
39
+ @thread = Thread.new do
40
+ loop do
41
+ sleep TICK
42
+ tick
43
+ end
44
+ end
45
+ self
46
+ end
47
+
48
+ # A stop (TERM): this process's rows count for the grace, while its
49
+ # pages reconnect to another process, so a deploy changes nobody's
50
+ # status.
51
+ def stop
52
+ @thread&.kill
53
+ @store.mark_all_gone(@process_id) if @process_id
54
+ rescue StandardError => e
55
+ Monk::Log.error("Monk::Presence: couldn't mark this process's rows gone: #{describe(e)}")
56
+ end
57
+
58
+ # Returns the transitions this tick settled (none after an error).
59
+ def tick
60
+ heartbeat if @rewrite || monotonic - @last_heartbeat >= HEARTBEAT_INTERVAL
61
+ subjects = @rewrite ? rewrite : flush
62
+ @rewrite = false
63
+ settle(subjects)
64
+ rescue StandardError => e
65
+ @rewrite = true
66
+ Monk::Log.error("Monk::Presence: tick failed, writing all of this process's rows next time: #{describe(e)}")
67
+ []
68
+ end
69
+
70
+ # The next tick heartbeats whatever the interval: for tests.
71
+ def heartbeat_now!
72
+ @last_heartbeat = -Float::INFINITY
73
+ end
74
+
75
+ private
76
+
77
+ def heartbeat
78
+ @rewrite = true if @store.heartbeat(@process_id, hostname: @hostname, pid: @pid)
79
+ @last_heartbeat = monotonic
80
+ end
81
+
82
+ def flush
83
+ diff = @counts.take
84
+ return [] if diff.values.all?(&:empty?)
85
+
86
+ @store.flush(@process_id, **diff)
87
+ diff.values.flatten
88
+ end
89
+
90
+ # take before all: a change between the two is in all's state and
91
+ # still marked changed, so the next take writes it again, harmlessly.
92
+ def rewrite
93
+ diff = @counts.take
94
+ state = @counts.all
95
+ @store.rewrite(@process_id, **state)
96
+ (state.values + [diff[:gone]]).flatten.uniq
97
+ end
98
+
99
+ def settle(subjects)
100
+ reconcile = monotonic - @last_reconcile >= RECONCILE_INTERVAL
101
+ transitions = @store.settle(subjects, reconcile: reconcile, notify: @notify)
102
+ @last_reconcile = monotonic if reconcile
103
+ transitions
104
+ end
105
+
106
+ def describe(error) = "#{error.class}: #{error.message.lines.first&.chomp}"
107
+
108
+ def monotonic = Process.clock_gettime(Process::CLOCK_MONOTONIC)
109
+ end
110
+ end
111
+ end
@@ -0,0 +1,129 @@
1
+ require_relative "errors"
2
+ require_relative "log"
3
+ require_relative "presence/store"
4
+ require_relative "presence/counts"
5
+ require_relative "presence/tracker"
6
+ require_relative "presence/reactor"
7
+
8
+ module Monk
9
+ # Whether a person is online, from the WebSocket processes' sockets
10
+ # (docs/adr/0019-presence-per-process-rows-in-postgres-settled-once-per-transition.md).
11
+ # Opt-in: require "monk/presence". Only Monk::Auth subjects are tracked.
12
+ #
13
+ # Monk::Presence.configure(db_name: :primary)
14
+ # Monk::Presence.status(["user:1", "user:2"])
15
+ # # => {"user:1" => {status: :online, last_seen_at: nil},
16
+ # # "user:2" => {status: :offline, last_seen_at: 2026-11-13 10:02:11 UTC}}
17
+ # Monk::Presence.on_change(&AppPresence::CHANGED) # bin/server reacts
18
+ #
19
+ # :online is a page open and visible, :away only hidden ones, :offline
20
+ # none, after the grace (20 s by default): a phone switching networks or
21
+ # a deploy reconnecting every page doesn't read as going offline.
22
+ module Presence
23
+ class NotConfiguredError < StandardError
24
+ end
25
+
26
+ DEFAULT_GRACE = 20
27
+ PROCESS_TIMEOUT = 30
28
+ # Seconds a web process's reactor waits before trying again for the
29
+ # lock, or after losing its connection.
30
+ REACTOR_RETRY = 5
31
+
32
+ class << self
33
+ # The status of each of subjects, from any process, in one query.
34
+ # last_seen_at is when an offline subject was last online or away
35
+ # (nil if never, or if not offline).
36
+ def status(subjects)
37
+ store.status(Array(subjects).map(&:to_s))
38
+ end
39
+
40
+ def online?(subject)
41
+ status([subject]).fetch(subject.to_s)[:status] == :online
42
+ end
43
+
44
+ # grace: seconds a subject stays as it was after its last socket
45
+ # closed, before it counts as offline.
46
+ def configure(db_name:, grace: DEFAULT_GRACE)
47
+ unless grace.is_a?(Numeric) && grace >= 0
48
+ raise ArgumentError, "grace must be a number of seconds, 0 or more, got #{grace.inspect}"
49
+ end
50
+
51
+ @store = Ractor.make_shareable(Store.new(db_name: db_name, grace: grace, process_timeout: PROCESS_TIMEOUT))
52
+ end
53
+
54
+ def configured? = !@store.nil?
55
+
56
+ # Called in bin/server with the subjects whose status changed, as
57
+ # #status returns them: {subject => {status:, last_seen_at:}}. At
58
+ # most once per change: a change signalled while no web process
59
+ # listens is missed, and a page catches up on its next resync. The
60
+ # block runs in the reactor's own Ractor, so it must be shareable:
61
+ # build it in a module, as Monk::Live.authorize rules are. An error
62
+ # in it is logged.
63
+ #
64
+ # Set in config/presence.rb, which the WebSocket processes load too:
65
+ # with an on_change, they signal each change.
66
+ def on_change(&block)
67
+ raise ArgumentError, "on_change needs a block: { |changes| ... }" unless block
68
+
69
+ @on_change = shareable(block)
70
+ end
71
+
72
+ # In a WebSocket process: starts counting its sockets and the tick
73
+ # that writes them, signalling changes when there's an on_change.
74
+ # Returns the counts, for Server.new(presence:). start_visible: false
75
+ # for Live, whose sockets count as hidden until their page's first
76
+ # ping.
77
+ def start!(start_visible:)
78
+ counts = Counts.new(start_visible: start_visible)
79
+ @tracker = Tracker.new(store: store, counts: counts, notify: !@on_change.nil?).start.run
80
+ counts
81
+ end
82
+
83
+ # In bin/server, after Monk.boot: starts the reactor that calls
84
+ # on_change. Nil, and nothing started, without an on_change.
85
+ def start_reactor!(retry_interval: REACTOR_RETRY)
86
+ return unless @on_change
87
+
88
+ return @reactor if @reactor
89
+
90
+ @reactor = Reactor.start(Monk::Persistence::Pg.connection_options(store.db_name), @on_change,
91
+ retry_interval: retry_interval,)
92
+ end
93
+
94
+ def stop_reactor!
95
+ Reactor.stop(@reactor) if @reactor
96
+ @reactor = nil
97
+ end
98
+
99
+ # On TERM: this process's subjects count for the grace while its
100
+ # pages reconnect elsewhere.
101
+ def stop!
102
+ @tracker&.stop
103
+ @tracker = nil
104
+ end
105
+
106
+ # Raises unless configured.
107
+ def store
108
+ @store || raise(NotConfiguredError, "Monk::Presence isn't configured -- call Monk::Presence.configure first")
109
+ end
110
+
111
+ def shareable(block)
112
+ Ractor.make_shareable(block)
113
+ rescue ArgumentError, Ractor::IsolationError => e
114
+ raise Monk::UnshareableBlockError,
115
+ "Monk::Presence.on_change block is not Ractor-shareable: #{e.message} " \
116
+ "(build it where self is shareable, e.g. in a module body)"
117
+ end
118
+ private :shareable
119
+
120
+ # Tests only.
121
+ def reset!
122
+ stop!
123
+ stop_reactor!
124
+ @store = nil
125
+ @on_change = nil
126
+ end
127
+ end
128
+ end
129
+ end
@@ -1,6 +1,6 @@
1
1
  source "https://rubygems.org"
2
2
 
3
- gem "monkrb", "~> 0.23", require: "monk"
3
+ gem "monkrb", "~> 0.24", require: "monk"
4
4
  gem "rackup"
5
5
  gem "webrick"
6
6
  gem "kino"
@@ -6,7 +6,7 @@ require_relative "settings"
6
6
  # Each Monk module's config, if this app has it (`monk add <module>` writes
7
7
  # it), in Monk's fixed order: a module's config may rely on the ones
8
8
  # before it. Nothing to edit here when a module is added.
9
- %w[persistence redis auth mail jobs websocket live storage].each do |name|
9
+ %w[persistence redis auth mail jobs websocket live presence storage].each do |name|
10
10
  path = File.expand_path("#{name}.rb", __dir__)
11
11
  require path if File.exist?(path)
12
12
  end
@@ -1,4 +1,11 @@
1
1
  require_relative "config/load" # the configs and app/ (config/load.rb)
2
2
  require_relative "app/app"
3
3
 
4
- run Monk.boot(App) # Boot: freezes the app and serves it
4
+ app = Monk.boot(App) # Boot: freezes the app
5
+
6
+ # With presence (monk add presence) and an on_change in
7
+ # config/presence.rb, this process competes to be the one that calls it.
8
+ # Here, not in config/load.rb: the tests and bin/console don't react.
9
+ Monk::Presence.start_reactor! if defined?(Monk::Presence) && Monk::Presence.configured?
10
+
11
+ run app # serves it
@@ -0,0 +1,29 @@
1
+ ## presence
2
+
3
+ **Where:** `config/presence.rb` (`Monk::Presence.configure`, `on_change`),
4
+ the dot partial in `app/views/presence/_dot.erb`. Counted in
5
+ `bin/websocket_server`, reacted to in `bin/server` (`config.ru`).
6
+
7
+ **Main calls:** `Monk::Presence.status(subjects)` →
8
+ `{subject => {status: :online | :away | :offline, last_seen_at:}}`, one
9
+ query for all of them; `Monk::Presence.online?(subject)`. Subjects are
10
+ Monk::Auth's (the user's email). `Monk::Presence.on_change { |changes| ... }`
11
+ with a block built in a module, receiving the same hash for the people
12
+ whose status changed.
13
+
14
+ **Test:** `test/presence_test.rb` reads the status of someone with no page
15
+ open.
16
+
17
+ **Pitfalls:**
18
+ - Only signed-in sockets count; a visitor is never online.
19
+ - `on_change` runs in its own Ractor in `bin/server`: build its block in a
20
+ module body; it sees no request, params or session.
21
+ - `on_change` gets a batch: push one Live message per batch (or per 50),
22
+ not one per person, or a burst fills the `:notify` pool and drops
23
+ patches.
24
+ - A change is reported at most once: one that happens while no
25
+ `bin/server` runs is never reported. Render the current status when a
26
+ page loads, and use `on_change` only to update it.
27
+ - Status is read from the primary database, not a replica.
28
+
29
+ **Examples:** `presence-dots` in `config/presence.rb`.
@@ -0,0 +1 @@
1
+ <span class="presence presence-<%= locals[:status] %>" data-presence="<%= locals[:subject] %>" title="<%= locals[:status] %>"></span>
@@ -0,0 +1,52 @@
1
+ require "monk"
2
+ require "monk/presence"
3
+ require_relative "persistence"
4
+
5
+ # Monk::Presence (monk add presence): whether a signed-in person (a
6
+ # Monk::Auth subject) has a page open. bin/websocket_server counts its
7
+ # sockets and writes them to Postgres; any process reads them. Loaded by
8
+ # config/load.rb and by bin/websocket_server. Monk's
9
+ # docs/guides/presence.md says how it works.
10
+ #
11
+ # Monk::Presence.status(["ann@example.com"])
12
+ # # => {"ann@example.com" => {status: :online, last_seen_at: nil}}
13
+ # Monk::Presence.online?("ann@example.com")
14
+ #
15
+ # :online is a page open and visible, :away only hidden ones (a phone in a
16
+ # pocket), :offline none; last_seen_at is when an offline person was last
17
+ # there. grace: seconds after a person's last page closes before they
18
+ # read as offline, so a phone changing network or a deploy reconnecting
19
+ # every page changes nobody's status.
20
+ Monk::Presence.configure(db_name: :primary, grace: 20)
21
+
22
+ # on_change runs in bin/server (config.ru starts it) each time some
23
+ # people's status changes, with all of them at once:
24
+ # {subject => {status:, last_seen_at:}}. At most once per change: one
25
+ # missed while no bin/server runs isn't sent later, and a Live page
26
+ # catches up when it reconnects. Its block must be Ractor-shareable, so
27
+ # it's built in a module (self at the top of this file is not).
28
+ #
29
+ # monk:example presence-dots -- push each change to the pages showing those people (needs live).
30
+ # # A page wraps its people in <div <%= live_topic "presence" %>> and shows
31
+ # # each with <%= render "presence/_dot", subject: email, status: ..., layout: false %>.
32
+ # # One message per 50 changes, not one per person: a burst stays within
33
+ # # the WebSocket transport's limits (8 KB a message over Postgres).
34
+ # module AppPresence
35
+ # CHANGED = proc do |changes|
36
+ # changes.each_slice(50) do |slice|
37
+ # Monk::Live.batch("presence") do |batch|
38
+ # slice.each do |subject, change|
39
+ # batch.patch(to: AppPresence.dots(subject), partial: "presence/_dot", subject: subject,
40
+ # status: change[:status],)
41
+ # end
42
+ # end
43
+ # end
44
+ # end
45
+ #
46
+ # # Every dot of one person on a page, as a CSS selector.
47
+ # def self.dots(subject) = %([data-presence="#{subject.gsub(/["\\]/) { "\\#{it}" }}"])
48
+ # end
49
+ # Monk::Presence.on_change(&AppPresence::CHANGED)
50
+ # # Signed-in people may see everyone's dots: narrow it to what your pages show.
51
+ # Monk::Live.authorize("presence", &Monk::Live::ALLOW_ALL)
52
+ # monk:end
@@ -0,0 +1,3 @@
1
+ DROP TABLE monk_presence_status;
2
+ DROP TABLE monk_presence;
3
+ DROP TABLE monk_presence_processes;
@@ -0,0 +1,36 @@
1
+ -- Monk::Presence: who has a socket open, per WebSocket process, and each
2
+ -- subject's settled status. Why this shape:
3
+ -- docs/adr/0019-presence-per-process-rows-in-postgres-settled-once-per-transition.md.
4
+
5
+ -- One row per bin/websocket_server process, heartbeat every few seconds:
6
+ -- a process whose heartbeat stops stops counting its subjects. UNLOGGED,
7
+ -- as monk_presence: after a Postgres crash both come back empty, and
8
+ -- each process writes its own again.
9
+ CREATE UNLOGGED TABLE monk_presence_processes (
10
+ id BIGINT GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
11
+ hostname TEXT NOT NULL,
12
+ pid INTEGER NOT NULL,
13
+ heartbeat_at TIMESTAMPTZ NOT NULL DEFAULT now()
14
+ );
15
+
16
+ -- One row per (process, subject) with a socket open there, or closed
17
+ -- less than the grace ago (gone_at). Rewritten all the time, so not
18
+ -- worth the WAL. No foreign key: a process row pruned first just means
19
+ -- its rows stop counting.
20
+ CREATE UNLOGGED TABLE monk_presence (
21
+ process_id BIGINT NOT NULL,
22
+ subject TEXT NOT NULL,
23
+ status TEXT NOT NULL CHECK (status IN ('online', 'away')),
24
+ gone_at TIMESTAMPTZ,
25
+ PRIMARY KEY (process_id, subject)
26
+ );
27
+ CREATE INDEX monk_presence_subject ON monk_presence (subject);
28
+
29
+ -- Each subject's last settled status, written once per transition, and
30
+ -- when it was last seen: shown to users, so logged.
31
+ CREATE TABLE monk_presence_status (
32
+ subject TEXT PRIMARY KEY,
33
+ status TEXT NOT NULL CHECK (status IN ('online', 'away', 'offline')),
34
+ changed_at TIMESTAMPTZ NOT NULL DEFAULT now(),
35
+ last_seen_at TIMESTAMPTZ
36
+ );
@@ -0,0 +1,51 @@
1
+ ## presence
2
+
3
+ Whether a signed-in person has a page open: online, away (only hidden
4
+ pages, like a phone in a pocket) or offline. `bin/websocket_server`
5
+ counts its sockets and writes them to Postgres every few seconds;
6
+ `Monk::Presence.status` reads them from any process. A migration
7
+ creates the `monk_presence*` tables: run `bin/setup_db` and
8
+ `DB_NAME={{app}}_test bin/setup_db` (postgres, above).
9
+
10
+ Only signed-in sockets count (auth, above). With live, a page counts as
11
+ away until its first ping, a moment after it opens.
12
+
13
+ ### Reacting to a change
14
+
15
+ `Monk::Presence.on_change` in `config/presence.rb` runs in `bin/server`
16
+ each time some people's status changes: `config.ru` starts it. Among
17
+ several `bin/server` processes, one reacts at a time; if it stops,
18
+ another takes over within seconds. The example `presence-dots` pushes
19
+ each change to the pages showing those people, with live.
20
+
21
+ ### Before production
22
+
23
+ - The process reacting to changes holds its own Postgres connection,
24
+ and needs a direct one: not through PgBouncer in transaction mode.
25
+ Each `bin/server` process opens one more, plus one for reading the
26
+ statuses when it reacts.
27
+ - A person stays as they were for `grace:` seconds (20) after their last
28
+ page closes, so a deploy restarting `bin/websocket_server` changes
29
+ nobody's status.
30
+
31
+ ### Check it works
32
+
33
+ 1. `bundle exec rake test` runs `test/presence_test.rb`: someone with no
34
+ page open reads as offline.
35
+ 2. By hand, with `bin/server` and `bin/websocket_server` running: log in
36
+ (auth, above) and open a page that connects to the WebSocket (with
37
+ live, any page with `live_topic`). Then, in `bin/console`:
38
+
39
+ ```ruby
40
+ Monk::Presence.status(["you@example.com"])
41
+ # => {"you@example.com" => {status: :online, last_seen_at: nil}}
42
+ ```
43
+
44
+ Hide the tab (or lock the phone) and it reads `:away` within a
45
+ second or two; close it and, after the grace, `:offline` with
46
+ `last_seen_at`. A locked iPhone goes `:offline` too, about 25 s after
47
+ locking: iOS drops a locked page's connection.
48
+ 3. The example: uncomment `presence-dots` in `config/presence.rb`, put
49
+ `<div <%= live_topic "presence" %>><%= render "presence/_dot", subject: "you@example.com", status: :offline, layout: false %></div>`
50
+ in a page, and restart both servers. Open it in one browser, and log
51
+ in as that person in another: the dot changes by itself.
@@ -0,0 +1,13 @@
1
+ require_relative "test_helper"
2
+
3
+ # Monk::Presence reads each person's status from the tables its migration
4
+ # made (bin/setup_db). Someone with no page open is offline, never seen.
5
+ # SETUP.md, presence.
6
+ class PresenceTest < Minitest::Test
7
+ def test_someone_with_no_page_open_is_offline
8
+ subject = "presence-check-#{rand(1_000_000)}@example.test"
9
+
10
+ assert_equal({ subject => { status: :offline, last_seen_at: nil } }, Monk::Presence.status([subject]))
11
+ refute Monk::Presence.online?(subject)
12
+ end
13
+ end
@@ -22,8 +22,8 @@ Monk::Bin.run(__FILE__) do
22
22
  require_relative "../config/websocket"
23
23
 
24
24
  # Each only if this app has it: auth says whose a socket is, live what it
25
- # may subscribe to.
26
- %w[auth live].each do |name|
25
+ # may subscribe to, presence whether this process counts who is online.
26
+ %w[auth live presence].each do |name|
27
27
  path = File.expand_path("../config/#{name}.rb", __dir__)
28
28
  require path if File.exist?(path)
29
29
  end
@@ -61,16 +61,32 @@ Monk::Bin.run(__FILE__) do
61
61
  db_pool = (:auth if authenticate)
62
62
  Monk::Persistence::Pg.start_pools!(db_pool) if db_pool
63
63
 
64
- port = ENV.fetch("WS_PORT", "9293").to_i
65
- # Defaults to public_url (config/settings.rb): one PUBLIC_URL keeps both
66
- # in sync. More than one origin: comma-separated.
67
- allowed_origins = ENV.fetch("WS_ALLOWED_ORIGINS", Monk::Settings[:public_url]).split(",")
64
+ # With presence (monk add presence), this process counts its signed-in
65
+ # sockets and writes them to Postgres every few seconds, through a
66
+ # connection of its own. With live, a socket counts as a hidden page
67
+ # until its page's first ping.
68
+ presence = (Monk::Presence.start!(start_visible: !live) if defined?(Monk::Presence) && authenticate)
69
+ begin
70
+ port = ENV.fetch("WS_PORT", "9293").to_i
71
+ # Defaults to public_url (config/settings.rb): one PUBLIC_URL keeps both
72
+ # in sync. More than one origin: comma-separated.
73
+ allowed_origins = ENV.fetch("WS_ALLOWED_ORIGINS", Monk::Settings[:public_url]).split(",")
68
74
 
69
- server = Monk::WebSocket::Server.new(
70
- port: port, authenticate: authenticate, allowed_origins: allowed_origins, db_pool: db_pool,
71
- reuse_port: processes > 1,
72
- )
73
- puts "Monk::WebSocket::Server listening on ws://0.0.0.0:#{port} " \
74
- "(#{live ? "live" : "app/sockets"}, transport: #{AppWebSocket::TRANSPORT}, authenticate: #{authenticate})"
75
- server.run(&handler)
75
+ # A ping every 25 s keeps a quiet socket open through a proxy's idle
76
+ # timeout (nginx's is 60 s), and a socket that answers nothing for two
77
+ # of them (a phone that changed network) is closed instead of held.
78
+ server = Monk::WebSocket::Server.new(
79
+ port: port, authenticate: authenticate, allowed_origins: allowed_origins, db_pool: db_pool,
80
+ ping_interval: 25, reuse_port: processes > 1, presence: presence,
81
+ )
82
+ puts "Monk::WebSocket::Server listening on ws://0.0.0.0:#{port} " \
83
+ "(#{live ? "live" : "app/sockets"}, transport: #{AppWebSocket::TRANSPORT}, authenticate: #{authenticate}" \
84
+ "#{", presence" if presence})"
85
+ server.run(&handler)
86
+ ensure
87
+ # On TERM (a deploy): this process's people stay as they were for the
88
+ # grace, while their pages reconnect to another process. Also when the
89
+ # server couldn't start (its port in use), so presence stops with it.
90
+ Monk::Presence.stop! if presence
91
+ end
76
92
  end
data/lib/monk/version.rb CHANGED
@@ -5,5 +5,5 @@ module Monk
5
5
  # class of bug .freeze! guards against for routes/error handlers/models,
6
6
  # just on a top-level constant that every worker Ractor reads on boot
7
7
  # (found live under kino: GET /hello 500'd until this was frozen).
8
- VERSION = "0.23.0".freeze
8
+ VERSION = "0.24.0".freeze
9
9
  end
data/lib/monk/views.rb CHANGED
@@ -1,5 +1,5 @@
1
1
  require "erb"
2
- require "cgi/escape"
2
+ require "erb/escape"
3
3
 
4
4
  require_relative "freeze_hooks"
5
5
  require_relative "errors"
@@ -36,6 +36,9 @@ module Monk
36
36
 
37
37
  DEFAULT_ROOT = "views".freeze
38
38
 
39
+ # What every compiled template's buffer starts as a dup of.
40
+ EMPTY = Raw.new("").freeze
41
+
39
42
  class << self
40
43
  # Every reader here is a plain attr_reader over an ivar initialized
41
44
  # eagerly below, never `@x ||= ...`: a lazy reader *writes* on first
@@ -46,17 +49,27 @@ module Monk
46
49
 
47
50
  # Escapes unless the value is already Raw, and returns Raw either
48
51
  # way -- so an explicit `<%= h(x) %>` isn't escaped twice by the
49
- # implicit `h` the compiler wraps every `<%= %>` in.
50
- # CGI.escapeHTML, not ERB::Util.html_escape, though they produce
51
- # byte-identical output: ERB's is not flagged Ractor-safe, so a
52
- # worker calling it raises Ractor::UnsafeError ("ractor unsafe
53
- # method called from not main ractor"). Found by
52
+ # implicit escape the compiler wraps every `<%= %>` in.
53
+ # ERB::Escape.html_escape, not ERB::Util.html_escape, though they
54
+ # produce byte-identical output: ERB::Util's is not flagged
55
+ # Ractor-safe, so a worker calling it raises Ractor::UnsafeError
56
+ # ("ractor unsafe method called from not main ractor"). Found by
54
57
  # test/ractor_integration_test.rb, in a real worker, not by reading
55
- # either implementation.
58
+ # either implementation. ERB::Escape's is, and unlike
59
+ # CGI.escapeHTML it returns its argument when there's nothing to
60
+ # escape instead of a copy.
56
61
  def h(value)
57
62
  return value if value.is_a?(Raw)
58
63
 
59
- Raw.new(CGI.escapeHTML(value.to_s))
64
+ Raw.new(ERB::Escape.html_escape(value.to_s))
65
+ end
66
+
67
+ # The implicit escape around every `<%= %>` (ERB has already called
68
+ # #to_s): #h without the Raw wrapper, since the result is appended
69
+ # to the buffer and dropped. For text with nothing to escape, the
70
+ # common case, it allocates nothing.
71
+ def escape(value)
72
+ value.is_a?(Raw) ? value : ERB::Escape.html_escape(value)
60
73
  end
61
74
 
62
75
  def compile(name, source, path = "(erb)")
@@ -143,14 +156,16 @@ module Monk
143
156
 
144
157
  # `<%= %>` escapes by default -- a deliberate break from stock ERB,
145
158
  # where it doesn't. ERB::Compiler emits `insert_cmd((expr).to_s)`
146
- # for every insertion, so pointing insert_cmd at Views.h is the
147
- # whole implementation; `raw(x)` opts back out.
159
+ # for every insertion, so pointing insert_cmd at Views.escape is the
160
+ # whole implementation; `raw(x)` opts back out. The buffer is a Raw
161
+ # from the start (a dup of EMPTY), so the template returns it as is
162
+ # rather than copying it into one.
148
163
  def compiled_source(source)
149
164
  compiler = ERB::Compiler.new("-")
150
- compiler.pre_cmd = ["_erbout = +''"]
151
- compiler.post_cmd = ["Monk::Views::Raw.new(_erbout)"]
165
+ compiler.pre_cmd = ["_erbout = +Monk::Views::EMPTY"]
166
+ compiler.post_cmd = ["_erbout"]
152
167
  compiler.put_cmd = "_erbout.<<"
153
- compiler.insert_cmd = "_erbout.<< Monk::Views.h"
168
+ compiler.insert_cmd = "_erbout.<< Monk::Views.escape"
154
169
  script, encoding, = compiler.compile(source)
155
170
  # ERB::Compiler#compile scans the source as ASCII-8BIT (see its
156
171
  # own String#b) and hands that tag straight through to any code