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.
@@ -14,16 +14,27 @@ module Monk
14
14
  # each just under the per-frame cap would silently bypass it.
15
15
  DEFAULT_MAX_PAYLOAD_SIZE = 1 * 1024 * 1024
16
16
 
17
+ # With a heartbeat (#start_heartbeat), a connection that sends
18
+ # nothing for this many ping intervals is taken for gone and closed:
19
+ # one ping unanswered is allowed, two aren't.
20
+ IDLE_PINGS = 2
21
+
17
22
  # subject is whatever Monk::Auth.verify returned when
18
23
  # Server.new(authenticate: true) verified this handshake
19
24
  # (docs/history/plan-websocket.md Phase 5) -- nil for an unauthenticated server.
20
25
  attr_reader :subject
21
26
 
22
- def initialize(socket, subject: nil, max_payload_size: DEFAULT_MAX_PAYLOAD_SIZE)
27
+ def self.monotonic = Process.clock_gettime(Process::CLOCK_MONOTONIC)
28
+
29
+ # presence: is a Monk::Presence::Counts this connection reports to
30
+ # (Server.new(presence:)), used only for a connection with a subject.
31
+ def initialize(socket, subject: nil, max_payload_size: DEFAULT_MAX_PAYLOAD_SIZE, presence: nil)
23
32
  @socket = socket
24
33
  @subject = subject
34
+ @presence = presence if subject
25
35
  @write_mutex = Mutex.new
26
36
  @max_payload_size = max_payload_size
37
+ @last_read_at = Connection.monotonic
27
38
  end
28
39
 
29
40
  # Reassembles a fragmented message per RFC 6455 5.4: a frame with
@@ -59,8 +70,9 @@ module Monk
59
70
  # payload back, per RFC 6455 5.5.3.
60
71
  write_frame(frame[:payload], 0xA)
61
72
  when 0xA
62
- # An unsolicited pong -- nothing to do yet (no pending-ping
63
- # tracking exists), but still not a message for app code.
73
+ # A pong: read_frame has already noted that the peer is
74
+ # there (#start_heartbeat's idle deadline), and it's not a
75
+ # message for app code.
64
76
  when 0x0
65
77
  return close_with(1002, "unexpected continuation frame") unless fragments
66
78
 
@@ -141,11 +153,30 @@ module Monk
141
153
  # no app-level JS involved) answers a server-sent ping with a pong
142
154
  # automatically; #read already discards an incoming pong silently
143
155
  # either way, so nothing app-visible changes.
156
+ #
157
+ # The same thread closes a connection that has sent nothing, not even
158
+ # a pong, for IDLE_PINGS intervals (docs/plan-live-networks-presence.md,
159
+ # A1): a peer that vanished without a FIN or an RST (a phone that
160
+ # changed network) never ends the read on its own. With nothing to
161
+ # send, the kernel never notices; with a ping pending, Linux gives up
162
+ # after about 15 minutes. It sleeps until the earlier of its next ping
163
+ # and that deadline, so the close comes at IDLE_PINGS intervals, not
164
+ # up to one more.
144
165
  def start_heartbeat(interval)
166
+ idle_timeout = interval * IDLE_PINGS
145
167
  @heartbeat_thread = Thread.new do
168
+ next_ping = Connection.monotonic + interval
146
169
  loop do
147
- sleep interval
148
- write("", opcode: 0x9)
170
+ now = Connection.monotonic
171
+ deadline = @last_read_at + idle_timeout
172
+ break drop_silent_peer if now >= deadline
173
+
174
+ if now >= next_ping
175
+ send_ping
176
+ @on_heartbeat&.call
177
+ next_ping = now + interval
178
+ end
179
+ sleep [[next_ping, deadline].min - Connection.monotonic, 0].max
149
180
  end
150
181
  rescue IOError, Errno::EPIPE, Errno::ECONNRESET
151
182
  # The socket closed out from under this loop -- #close or a
@@ -156,14 +187,84 @@ module Monk
156
187
  end
157
188
  end
158
189
 
190
+ # A block run on the heartbeat thread after each ping, in this
191
+ # connection's Ractor: periodic work for a handler without a thread
192
+ # of its own per connection (Live::Session's check for a silent
193
+ # page). Never runs without ping_interval:.
194
+ def on_heartbeat(&block)
195
+ @on_heartbeat = block
196
+ end
197
+
159
198
  # Called unconditionally from Server.serve's ensure, alongside
160
199
  # #unsubscribe! -- a no-op if #start_heartbeat was never called.
161
200
  def stop_heartbeat!
162
201
  @heartbeat_thread&.kill
163
202
  end
164
203
 
204
+ # Presence (docs/adr/0019-...): whether this connection is counted
205
+ # for its subject. Server.serve reports the open after the 101 and
206
+ # the close in its ensure; a handler that knows whether its page is
207
+ # visible (Live::Session, from its client's pings) sets #visible=.
208
+ # Each is a send to the counts, never a wait, keyed by this
209
+ # connection's own Ractor.
210
+ def tracks_presence? = !@presence.nil?
211
+
212
+ def presence_open!
213
+ @presence&.open(Ractor.current, @subject.to_s)
214
+ end
215
+
216
+ def presence_close!
217
+ @presence&.close(Ractor.current)
218
+ end
219
+
220
+ # Reported only when it changes.
221
+ def visible=(visible)
222
+ return if @visible == visible
223
+
224
+ @visible = visible
225
+ @presence&.visible(Ractor.current, visible)
226
+ end
227
+
165
228
  private
166
229
 
230
+ # A ping that can't go out at once is skipped, not waited for: on a
231
+ # dead connection the kernel's send buffer fills, a writer (a relay
232
+ # with patches queued) blocks inside write_frame holding the mutex,
233
+ # and a heartbeat waiting behind it would never reach its deadline.
234
+ # A ping cut in half (the buffer had room for one byte) would corrupt
235
+ # the stream, so that connection is dropped instead.
236
+ #
237
+ # A ping that fails with a network error (Errno::EHOSTDOWN on macOS,
238
+ # EHOSTUNREACH on Linux, once the peer's network is gone) is skipped
239
+ # too: ending the heartbeat there would also end the close after
240
+ # IDLE_PINGS silent intervals, the one thing that still frees a
241
+ # connection whose peer vanished. A closed socket (IOError) still
242
+ # ends it.
243
+ def send_ping
244
+ return unless @write_mutex.try_lock
245
+
246
+ begin
247
+ ping = Monk::WebSocket::Frame.encode("", opcode: 0x9)
248
+ written = @socket.write_nonblock(ping, exception: false)
249
+ drop_silent_peer if written.is_a?(Integer) && written < ping.bytesize
250
+ rescue SystemCallError
251
+ # Skipped; the deadline decides.
252
+ ensure
253
+ @write_mutex.unlock
254
+ end
255
+ end
256
+
257
+ # Shut down, without a close frame and without the write mutex: the
258
+ # peer is taken for gone, and a writer may be blocked holding the
259
+ # mutex on its full send buffer. shutdown makes that write raise and
260
+ # the handler's read return nil, and Server.serve's ensure cleans up
261
+ # as after any other close.
262
+ def drop_silent_peer
263
+ @socket.shutdown(:RDWR)
264
+ rescue IOError, SystemCallError
265
+ # Already closed or gone.
266
+ end
267
+
167
268
  def relay_broadcasts
168
269
  loop do
169
270
  message = @port.receive
@@ -197,6 +298,8 @@ module Monk
197
298
  header = read_exactly(2)
198
299
  return nil unless header
199
300
 
301
+ # Any frame shows the peer is there: data, a ping, a pong.
302
+ @last_read_at = Connection.monotonic
200
303
  byte1 = header.getbyte(1)
201
304
  masked = byte1.anybits?(0x80)
202
305
  length_indicator = byte1 & 0x7F
@@ -17,7 +17,12 @@ module Monk
17
17
  # ping_interval: (seconds) opts a connection into a server-sent
18
18
  # heartbeat ping -- see Connection#start_heartbeat. Defaults to nil
19
19
  # (disabled) for the same reason authenticate: defaults false: a
20
- # server that doesn't ask for it behaves exactly as before.
20
+ # server that doesn't ask for it behaves exactly as before. It also
21
+ # closes a connection silent for Connection::IDLE_PINGS intervals,
22
+ # so it can't be under MIN_PING_INTERVAL: reads stall during a GC
23
+ # pause or a slow db_pool: rule, and a timeout near that would close
24
+ # healthy sockets in bulk and start a reconnect wave
25
+ # (docs/plan-live-networks-presence.md, open question 2).
21
26
  #
22
27
  # reverify_interval: (seconds) re-runs Monk::Auth.verify against the
23
28
  # same credential on that cadence for as long as the connection
@@ -81,8 +86,16 @@ module Monk
81
86
  # heap, so its own GC pauses, over a share of the sockets: on Ruby 4.0
82
87
  # K processes cut what GC costs a connect by about K squared
83
88
  # (item 8). A broadcast reaches all of them through the fan-out.
89
+ #
90
+ # presence: a Monk::Presence::Counts (Monk::Presence.start!), told
91
+ # when each connection with a subject opens (after the 101) and
92
+ # closes, with a send, so a connect never waits on it
93
+ # (docs/adr/0019-presence-per-process-rows-in-postgres-settled-once-per-transition.md).
94
+ # Requires authenticate:: only Monk::Auth subjects are tracked.
84
95
  AUTHENTICATE_MODES = [false, true, :optional].freeze
85
96
 
97
+ MIN_PING_INTERVAL = 5
98
+
86
99
  DEFAULT_MAX_HANDSHAKES = 128
87
100
  DEFAULT_HANDSHAKE_TIMEOUT = 10
88
101
 
@@ -97,10 +110,14 @@ module Monk
97
110
  def initialize(
98
111
  port:, bind: "0.0.0.0", allowed_origins: nil, authenticate: false, ping_interval: nil,
99
112
  reverify_interval: nil, max_payload_size: Connection::DEFAULT_MAX_PAYLOAD_SIZE, db_pool: nil,
100
- max_handshakes: DEFAULT_MAX_HANDSHAKES, handshake_timeout: DEFAULT_HANDSHAKE_TIMEOUT, reuse_port: false
113
+ max_handshakes: DEFAULT_MAX_HANDSHAKES, handshake_timeout: DEFAULT_HANDSHAKE_TIMEOUT, reuse_port: false,
114
+ presence: nil
101
115
  )
102
- if ping_interval && !ping_interval.positive?
103
- raise ArgumentError, "ping_interval must be positive, got #{ping_interval.inspect}"
116
+ if ping_interval && !(ping_interval.is_a?(Numeric) && ping_interval >= MIN_PING_INTERVAL)
117
+ raise ArgumentError,
118
+ "ping_interval must be at least #{MIN_PING_INTERVAL} (seconds), got #{ping_interval.inspect}: " \
119
+ "a connection silent for #{Connection::IDLE_PINGS} intervals is closed, and a shorter one would " \
120
+ "close healthy sockets during a GC pause"
104
121
  end
105
122
 
106
123
  unless AUTHENTICATE_MODES.include?(authenticate)
@@ -115,6 +132,11 @@ module Monk
115
132
  end
116
133
 
117
134
  raise ArgumentError, "db_pool requires authenticate: true or :optional" if db_pool && !authenticate
135
+ raise ArgumentError, "presence requires authenticate: true or :optional" if presence && !authenticate
136
+ # A Live page that went silent turns hidden on the heartbeat
137
+ # (Connection#on_heartbeat), and a socket whose peer vanished is
138
+ # only closed, and stops counting, through it.
139
+ raise ArgumentError, "presence requires ping_interval:" if presence && !ping_interval
118
140
 
119
141
  unless max_payload_size.positive?
120
142
  raise ArgumentError, "max_payload_size must be positive, got #{max_payload_size.inspect}"
@@ -158,6 +180,7 @@ module Monk
158
180
  @db_pool = db_pool
159
181
  @max_handshakes = max_handshakes
160
182
  @handshake_timeout = handshake_timeout
183
+ @presence = presence && Ractor.make_shareable(presence)
161
184
  end
162
185
 
163
186
  def port
@@ -217,13 +240,14 @@ module Monk
217
240
  socket = @tcp_server.accept
218
241
  ractor = Ractor.new(
219
242
  shareable_block, @authenticate, @allowed_origins, @ping_interval, @reverify_interval, @max_payload_size,
220
- @db_pool, handshake_done, @handshake_timeout
221
- ) do |blk, authenticate, origins, ping_interval, reverify_interval, max_payload_size, db_pool, done, timeout|
243
+ @db_pool, handshake_done, @handshake_timeout, @presence
244
+ ) do |blk, authenticate, origins, ping_interval, reverify_interval, max_payload_size, db_pool, done, timeout,
245
+ presence|
222
246
  Monk::WebSocket::Server.serve(
223
247
  Ractor.receive, blk,
224
248
  authenticate: authenticate, allowed_origins: origins, ping_interval: ping_interval,
225
249
  reverify_interval: reverify_interval, max_payload_size: max_payload_size, db_pool: db_pool,
226
- handshake_done: done, handshake_timeout: timeout
250
+ handshake_done: done, handshake_timeout: timeout, presence: presence
227
251
  )
228
252
  end
229
253
  ractor.send(socket, move: true)
@@ -261,7 +285,7 @@ module Monk
261
285
  def self.serve(
262
286
  socket, block, authenticate: false, allowed_origins: nil, ping_interval: nil, reverify_interval: nil,
263
287
  max_payload_size: Connection::DEFAULT_MAX_PAYLOAD_SIZE, db_pool: nil, handshake_done: nil,
264
- handshake_timeout: DEFAULT_HANDSHAKE_TIMEOUT
288
+ handshake_timeout: DEFAULT_HANDSHAKE_TIMEOUT, presence: nil
265
289
  )
266
290
  # A `return` in here (a refused handshake) ends serve, and its
267
291
  # ensure frees the slot.
@@ -297,7 +321,8 @@ module Monk
297
321
  end
298
322
  handshake_done = handshake_over(handshake_done)
299
323
 
300
- connection = Connection.new(socket, subject: subject, max_payload_size: max_payload_size)
324
+ connection = Connection.new(socket, subject: subject, max_payload_size: max_payload_size, presence: presence)
325
+ connection.presence_open!
301
326
  connection.start_heartbeat(ping_interval) if ping_interval
302
327
  if reverify_interval && subject
303
328
  reverify_thread = start_reverify(connection, credential[:token], reverify_interval, db_pool)
@@ -322,6 +347,7 @@ module Monk
322
347
  # A handshake that never reached its 101 still frees its slot.
323
348
  handshake_over(handshake_done)
324
349
  reverify_thread&.kill
350
+ connection&.presence_close!
325
351
  connection&.unsubscribe!
326
352
  connection&.stop_heartbeat!
327
353
  socket.close
@@ -464,10 +490,10 @@ module Monk
464
490
  break unless verify(raw_token, db_pool)
465
491
  end
466
492
  connection.close(code: 1008, reason: "session no longer valid")
467
- rescue IOError, Errno::EPIPE, Errno::ECONNRESET
493
+ rescue IOError, SystemCallError
468
494
  # The connection already closed via some other path (normal
469
- # disconnect, the close handshake, a dead ping) -- nothing left
470
- # to close.
495
+ # disconnect, the close handshake, a dead ping), or its peer's
496
+ # network is gone (Errno::EHOSTDOWN): nothing left to close.
471
497
  end
472
498
  end
473
499
  private_class_method :start_reverify
metadata CHANGED
@@ -1,7 +1,7 @@
1
1
  --- !ruby/object:Gem::Specification
2
2
  name: monkrb
3
3
  version: !ruby/object:Gem::Version
4
- version: 0.23.0
4
+ version: 0.24.0
5
5
  platform: ruby
6
6
  authors:
7
7
  - Matteo Folin
@@ -205,6 +205,7 @@ files:
205
205
  - lib/monk/generators/live.rb
206
206
  - lib/monk/generators/mail.rb
207
207
  - lib/monk/generators/postgres.rb
208
+ - lib/monk/generators/presence.rb
208
209
  - lib/monk/generators/redis.rb
209
210
  - lib/monk/generators/storage.rb
210
211
  - lib/monk/generators/websocket.rb
@@ -250,6 +251,11 @@ files:
250
251
  - lib/monk/persistence/pg/migrator.rb
251
252
  - lib/monk/persistence/pg/model.rb
252
253
  - lib/monk/persistence/pool.rb
254
+ - lib/monk/presence.rb
255
+ - lib/monk/presence/counts.rb
256
+ - lib/monk/presence/reactor.rb
257
+ - lib/monk/presence/store.rb
258
+ - lib/monk/presence/tracker.rb
253
259
  - lib/monk/settings.rb
254
260
  - lib/monk/state_ractor.rb
255
261
  - lib/monk/storage.rb
@@ -343,6 +349,13 @@ files:
343
349
  - lib/monk/templates/postgres/db/migrate/.keep
344
350
  - lib/monk/templates/postgres/setup.md
345
351
  - lib/monk/templates/postgres/test/persistence_test.rb
352
+ - lib/monk/templates/presence/agents.md
353
+ - lib/monk/templates/presence/app/views/presence/_dot.erb
354
+ - lib/monk/templates/presence/config/presence.rb
355
+ - lib/monk/templates/presence/db/migrate/00000000000005_create_presence_tables.down.sql
356
+ - lib/monk/templates/presence/db/migrate/00000000000005_create_presence_tables.up.sql
357
+ - lib/monk/templates/presence/setup.md
358
+ - lib/monk/templates/presence/test/presence_test.rb
346
359
  - lib/monk/templates/redis/agents.md
347
360
  - lib/monk/templates/redis/app/routes/redis.rb
348
361
  - lib/monk/templates/redis/config/redis.rb