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 +4 -4
- data/CHANGELOG.md +85 -0
- data/README.md +3 -2
- data/lib/monk/base.rb +51 -3
- data/lib/monk/context.rb +6 -1
- data/lib/monk/generators/presence.rb +22 -0
- data/lib/monk/generators.rb +1 -1
- data/lib/monk/live/client/monk_live.js +159 -7
- data/lib/monk/live/client/protocol.js +37 -0
- data/lib/monk/live/session.rb +59 -2
- data/lib/monk/persistence/pg/model.rb +19 -6
- data/lib/monk/presence/counts.rb +118 -0
- data/lib/monk/presence/reactor.rb +126 -0
- data/lib/monk/presence/store.rb +271 -0
- data/lib/monk/presence/tracker.rb +111 -0
- data/lib/monk/presence.rb +129 -0
- data/lib/monk/templates/base/Gemfile +1 -1
- data/lib/monk/templates/base/config/load.rb +1 -1
- data/lib/monk/templates/base/config.ru +8 -1
- data/lib/monk/templates/presence/agents.md +29 -0
- data/lib/monk/templates/presence/app/views/presence/_dot.erb +1 -0
- data/lib/monk/templates/presence/config/presence.rb +52 -0
- data/lib/monk/templates/presence/db/migrate/00000000000005_create_presence_tables.down.sql +3 -0
- data/lib/monk/templates/presence/db/migrate/00000000000005_create_presence_tables.up.sql +36 -0
- data/lib/monk/templates/presence/setup.md +51 -0
- data/lib/monk/templates/presence/test/presence_test.rb +13 -0
- data/lib/monk/templates/websocket/bin/websocket_server +29 -13
- data/lib/monk/version.rb +1 -1
- data/lib/monk/views.rb +28 -13
- data/lib/monk/websocket/connection.rb +108 -5
- data/lib/monk/websocket/server.rb +38 -12
- metadata +14 -1
|
@@ -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
|
|
@@ -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
|
-
|
|
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,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
|
-
|
|
65
|
-
#
|
|
66
|
-
#
|
|
67
|
-
|
|
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
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
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.
|
|
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 "
|
|
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
|
|
50
|
-
#
|
|
51
|
-
# byte-identical output: ERB's is not flagged
|
|
52
|
-
# worker calling it raises Ractor::UnsafeError
|
|
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(
|
|
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.
|
|
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 = ["
|
|
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.
|
|
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
|