monkrb 0.22.0 → 0.22.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fa788432dda8104f066b4230e406e690df36c72528f57de126001519576fa0e6
-  data.tar.gz: 36352b5fa73ff475ca37141e8d5aeca9f0cd487845f1521f62bc3048650a57a2
+  metadata.gz: ae98dd74608d293e7fdae3c428abae8d851f25e4a52d02d9d92aa499588d5182
+  data.tar.gz: ff9fb430178e748ea859c9c6ae8ef72b8d35851b297a7d38f39b9f36a8597f02
 SHA512:
-  metadata.gz: 03ecd1b575dcb40a8a1a35c4b5b0a2b1c8f867369ffda064d6138fbde7f8db8c586d9d4e302d2ee471a71a29b9c50133ee8a91eaf4c49dec88ca64e0158aecab
-  data.tar.gz: c14485432530c8e4f14ee1ff630208a191ebffb4ec6c1c1fd6326562aba05555a4173e865fe73b913027f896a530166ab0d115468d28dc15efdade92fc49d0c5
+  metadata.gz: ffa8fe3639cca148a43d9bd308d2e5b7fe761d391d3687a709e82c2747ec0825184c2b3f10bafe3630a6f568733545ff8879ab0768f9f555256e83c0d0cc5f7e
+  data.tar.gz: 1a7ec63d1a87f9f31d931022889a1630dcd4b8c4e02316992650a72e2bc5114fe49c280ace2a638b43d9425a4460283fe295f10b6f27ce499649db8e4156ebe9

data/CHANGELOG.md

@@ -4,6 +4,68 @@ All notable changes to this project are documented here. Format is loosely
 [Keep a Changelog](https://keepachangelog.com/); versions are as released
 in `lib/monk/version.rb`.
 
+## 0.22.1 - 2026-10-20
+
+### Added
+
+- **Several WebSocket processes on one port.** `Server.new(reuse_port:
+  true)` binds with `SO_REUSEPORT`, and the scaffold's
+  `bin/websocket_server` runs `WS_PROCESSES` processes (1 by default),
+  starting that many copies of itself through the new
+  `Monk::Bin.spawn_processes!` and passing `TERM`/`INT` on. Each has its
+  own heap and its own GC pauses over its share of the sockets, so on
+  Ruby 4.0 K processes take about K² times the connects a second
+  (`docs/guides/websocket.md`, "Several processes"; plan item 8). An
+  existing app copies the new script (`docs/guides/upgrading.md`,
+  0.22.1).
+
+### Fixed
+
+- **A WebSocket connect burst queues instead of collapsing.** The server
+  caps the handshakes in flight (`Server.new(max_handshakes:)`, 128 by
+  default); past the cap, connects wait in the kernel's listen backlog.
+  Before, every accepted socket started its handshake at once, and a
+  burst past what the process could verify (a restart's reconnect wave)
+  filled the `db_pool:` queue and timed most of them out
+  (`docs/plan-ws-connect-ceiling.md`, item 1).
+- **A WebSocket handshake has a deadline and a size limit.** A handshake
+  not over within `handshake_timeout:` (10 s by default) is dropped, and a request head past 16 KiB gets a
+  `431`. Before, a socket that connected and sent nothing held its
+  connection Ractor forever, and a request with no blank line grew
+  without limit (item 2).
+- **A WebSocket handshake whose session check fails is refused with
+  `503`**, and one line on stderr. Before, a `verify` that raised (the
+  `db_pool:` full or timed out, the database down) killed the
+  connection's Ractor with a backtrace and sent no response. Under
+  `authenticate: :optional` it is a `503` too, not an anonymous
+  connection. Clients without an `Origin` also get `Retry-After`
+  (item 3).
+
+### Changed
+
+- **A WebSocket handshake allocates less.** The request is read with one
+  `gets` instead of a String a byte, parsed once instead of twice, and
+  its credential worked out once instead of up to three times. Fewer
+  objects a connect means fewer GCs, which is what limits connects a
+  second once thousands of sockets are open (item 4).
+- **A Live subscribe is one registry ask, not one a topic.**
+  `Registry#register_many(keys, port)` and `#unregister_many` (on
+  `RedisFanout` and `PgFanout` too) take every key at once;
+  `Monk::Live`'s subscribe, unsubscribe and cleanup use them. Each fiber
+  also reuses one reply port for its asks instead of making one an ask,
+  and the registry survives answering an ask whose caller gave up
+  (item 5).
+- **`bin/websocket_server` runs with GC settings for many open sockets.**
+  It starts itself again, once at boot, with
+  `RUBY_GC_HEAP_FREE_SLOTS_MIN_RATIO=0.6`, `_GOAL_RATIO=0.8` and
+  `_MAX_RATIO=0.9` (`Monk::Bin::WEBSOCKET_GC_ENV`, through the new
+  `Monk::Bin.boot_with_env!`), unless the environment sets them. On Ruby
+  4.0, with 15K sockets held, 6–30× fewer GCs and p99 to ready at
+  300 connects/s from 6.3 s to 1.2 s, for ~30% more memory. An existing
+  app adds one line (`docs/guides/upgrading.md`, 0.22.1) (item 7).
+  Restarting with the settings carries the warning level (`-W0`) over;
+  other flags given to `ruby` itself aren't (`RUBYOPT` is).
+
 ## 0.22.0 - 2026-10-13
 
 ### Added

data/README.md

@@ -88,6 +88,6 @@ More (server modes, Docker) in [`docs/development.md`](docs/development.md).
 
 ## Status
 
-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`).
+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`).
 
 [Made with Love ❤️, Ruby 💎 and AI 🤖](docs/ai_usage_disclaimer.md)

data/lib/monk/bin.rb

@@ -1,3 +1,5 @@
+require "rbconfig"
+
 module Monk
   # What a scaffolded app's bin/ scripts run their work in:
   #
@@ -13,7 +15,60 @@ module Monk
   # is. Errors are recognized by class name, so this file loads neither pg
   # nor redis (docs/adr/0017).
   module Bin
+    # bin/websocket_server's GC settings: keep the heap 60-90% free. On Ruby
+    # 4.0 a GC runs whenever new connection Ractors have used up the free
+    # pages of the smallest heap (each takes one, however little it
+    # allocates), and every GC stops and marks every open socket: at 15K
+    # sockets held, these run 6-30x fewer GCs, for ~30% more memory
+    # (docs/plan-ws-connect-ceiling.md, "After items 1-5"). Measured to
+    # change nothing on 4.1, whose Ractors have heaps of their own.
+    WEBSOCKET_GC_ENV = {
+      "RUBY_GC_HEAP_FREE_SLOTS_MIN_RATIO" => "0.6",
+      "RUBY_GC_HEAP_FREE_SLOTS_GOAL_RATIO" => "0.8",
+      "RUBY_GC_HEAP_FREE_SLOTS_MAX_RATIO" => "0.9",
+    }.freeze
+
     class << self
+      # Ruby reads settings like these only when it boots, so a script
+      # that needs them starts itself again, once, with the ones the
+      # environment doesn't set; what it does set wins. Call it first,
+      # before the script loads the app. The same PID throughout. Of the
+      # flags given to ruby itself, only the warning level is carried over
+      # (RUBYOPT is, whole).
+      def boot_with_env!(script, env)
+        missing = env.reject { |name, _| ENV.key?(name) }
+        return if missing.empty?
+
+        # exec drops what's still buffered.
+        $stdout.flush
+        $stderr.flush
+        exec(missing, RbConfig.ruby, *warning_flags, script, *ARGV)
+      end
+
+      # Runs the script in `count` processes: this one starts that many
+      # copies of it, then only waits on them, passing INT and TERM on; in
+      # each copy (MONK_BIN_PROCESS set) it returns at once. Copies, not
+      # forks: on macOS a forked child that opens a Postgres connection
+      # crashes in the Objective-C runtime, and a fresh process inherits
+      # nothing. If one ends on its own (a crash, a service down at boot),
+      # the others are stopped too, and this process exits with its status,
+      # so whatever restarts the script restarts them all. With 1, returns
+      # at once, in this process.
+      def spawn_processes!(script, count)
+        unless count.is_a?(Integer) && count.positive?
+          raise ArgumentError, "the process count must be a positive Integer, got #{count.inspect}"
+        end
+        return if count == 1 || ENV.key?("MONK_BIN_PROCESS")
+
+        # Each in its own process group, so a Ctrl-C at the terminal
+        # reaches it once, passed on from here, and not twice.
+        pids = Array.new(count) do |index|
+          env = { "MONK_BIN_PROCESS" => (index + 1).to_s }
+          Process.spawn(env, RbConfig.ruby, *warning_flags, script, *ARGV, pgroup: true)
+        end
+        exit supervise(pids)
+      end
+
       def run(script)
         yield
       rescue StandardError => e
@@ -41,6 +96,45 @@ module Monk
 
       private
 
+      # The warning level this Ruby runs at, as flags for another: a script
+      # started with -W0 stays quiet when it starts again.
+      def warning_flags
+        flags = []
+        flags << "-W0" if $VERBOSE.nil?
+        flags << "-W:no-experimental" unless Warning[:experimental]
+        flags
+      end
+
+      # Waits until every pid has ended, and returns the first nonzero
+      # status among them, or 0.
+      def supervise(pids)
+        stop = -> { pids.each { |pid| terminate(pid) } }
+        stopping = false
+        %w[INT TERM].each do |name|
+          trap(name) do
+            stopping = true
+            stop.call
+          end
+        end
+        status = 0
+        until pids.empty?
+          pid, process_status = Process.wait2
+          pids.delete(pid)
+          status = process_status.exitstatus || 1 if status.zero? && !process_status.success?
+          next if stopping
+
+          stopping = true
+          stop.call
+        end
+        status
+      end
+
+      def terminate(pid)
+        Process.kill("TERM", pid)
+      rescue Errno::ESRCH
+        nil # already gone
+      end
+
       def postgres(error, context)
         host = error.message[/server at "([^"]+)"/, 1] || ENV.fetch("DB_HOST", "127.0.0.1")
         port = error.message[/port (\d+)/, 1] || ENV.fetch("DB_PORT", "5432")

data/lib/monk/live/session.rb

@@ -58,18 +58,24 @@ module Monk
           topics.all? { |topic| topic.is_a?(String) && topic.valid_encoding? }
       end
 
+      # The new topics go to the registry in one ask, not one each: at a
+      # reconnect wave's rate, one ask per topic is most of the registry
+      # Ractor's work (docs/plan-ws-connect-ceiling.md, item 5).
       def subscribe(topics)
-        allowed, denied = topics.partition { |topic| try_subscribe?(topic) }
+        added = {}
+        allowed, denied = topics.partition { |topic| try_subscribe?(topic, added) }
+        unless added.empty?
+          @registry.register_many(added.values, @port)
+          @topics.merge!(added)
+        end
         reply(op: "subscribed", topics: allowed, denied: denied)
       end
 
-      def try_subscribe?(topic)
-        return true if @topics.key?(topic)
-        return false unless permitted?(topic) && @topics.size < @max_topics
+      def try_subscribe?(topic, added)
+        return true if @topics.key?(topic) || added.key?(topic)
+        return false unless permitted?(topic) && @topics.size + added.size < @max_topics
 
-        key = topic.to_sym
-        @registry.register(key, @port)
-        @topics[topic] = key
+        added[topic] = topic.to_sym
         true
       end
 
@@ -79,7 +85,8 @@ module Monk
 
       def unsubscribe(topics)
         removed = topics.select { |topic| @topics.key?(topic) }
-        removed.each { |topic| @registry.unregister(@topics.delete(topic), @port) }
+        keys = removed.filter_map { |topic| @topics.delete(topic) }
+        @registry.unregister_many(keys, @port) unless keys.empty?
         reply(op: "unsubscribed", topics: removed)
       end
 
@@ -119,7 +126,7 @@ module Monk
       # read -- so a connection never leaves a stale registry entry.
       def cleanup
         @relay&.kill
-        @topics.each_value { |key| @registry.unregister(key, @port) }
+        @registry.unregister_many(@topics.values, @port) unless @topics.empty?
         @topics.clear
         @port&.close
       end

data/lib/monk/templates/websocket/bin/websocket_server

@@ -4,6 +4,19 @@ require "bundler/setup"
 # with what to fix (SETUP.md's commands), not a backtrace.
 require "monk/bin"
 
+# Fewer GC pauses while thousands of sockets are open, set the only way
+# Ruby takes them: at boot. Any already in the environment win.
+Monk::Bin.boot_with_env!(__FILE__, Monk::Bin::WEBSOCKET_GC_ENV)
+
+# WS_PROCESSES (1): this many server processes on WS_PORT, each with its own
+# heap and its own GC pauses over a share of the sockets
+# (docs/guides/websocket.md, "Several processes").
+processes = Integer(ENV.fetch("WS_PROCESSES", "1"), exception: false)
+unless processes&.positive?
+  abort "bin/websocket_server: WS_PROCESSES must be a whole number, 1 or more, got #{ENV["WS_PROCESSES"].inspect}."
+end
+Monk::Bin.spawn_processes!(__FILE__, processes)
+
 Monk::Bin.run(__FILE__) do
   require_relative "../config/settings"
   require_relative "../config/websocket"
@@ -55,6 +68,7 @@ Monk::Bin.run(__FILE__) do
 
   server = Monk::WebSocket::Server.new(
     port: port, authenticate: authenticate, allowed_origins: allowed_origins, db_pool: db_pool,
+    reuse_port: processes > 1,
   )
   puts "Monk::WebSocket::Server listening on ws://0.0.0.0:#{port} " \
     "(#{live ? "live" : "app/sockets"}, transport: #{AppWebSocket::TRANSPORT}, authenticate: #{authenticate})"

data/lib/monk/templates/websocket/setup.md

@@ -18,7 +18,8 @@ exits. In production it's one more process from the same image, with
 
 `WS_ALLOWED_ORIGINS` (default: `PUBLIC_URL`) must list every origin your
 pages are served from, or browsers' sockets are refused. Behind TLS, pages
-connect with `wss://`.
+connect with `wss://`. Past ~5K open sockets, `WS_PROCESSES` (default 1)
+runs several server processes on the port, on Linux.
 
 ### Switching transports
 

data/lib/monk/version.rb

@@ -5,5 +5,5 @@ module Monk
   # class of bug .freeze! guards against for routes/error handlers/models,
   # just on a top-level constant that every worker Ractor reads on boot
   # (found live under kino: GET /hello 500'd until this was frozen).
-  VERSION = "0.22.0".freeze
+  VERSION = "0.22.1".freeze
 end

data/lib/monk/websocket/handshake.rb

@@ -9,16 +9,35 @@ module Monk
       # read from a connection Ractor. .freeze is not optional.
       MAGIC = "258EAFA5-E914-47DA-95CA-C5AB0DC85B11".freeze
 
+      # The most a handshake request's head may be (Server.serve answers
+      # 431 past it): room for a large cookie, nowhere near a memory risk.
+      MAX_REQUEST_SIZE = 16 * 1024
+
       def self.accept_key(client_key)
         Base64.strict_encode64(Digest::SHA1.digest(client_key + MAGIC))
       end
 
+      # Two Strings a header line (its name and its value), plus the line:
+      # this runs once a connect, and every object it makes is one more
+      # towards the next GC (docs/plan-ws-connect-ceiling.md, item 4).
       def self.parse_request(raw_request)
-        headers = raw_request.split("\r\n").drop(1).each_with_object({}) do |line, h|
-          next if line.empty?
+        headers = {}
+        request_line = true
+        raw_request.each_line("\r\n", chomp: true) do |line|
+          if request_line
+            request_line = false
+            next
+          end
+
+          colon = line.index(":")
+          next unless colon
 
-          name, value = line.split(":", 2)
-          h[name.strip.downcase] = value.strip if name && value
+          name = line.byteslice(0, colon)
+          name.strip!
+          name.downcase!
+          value = line.byteslice(colon + 1, line.bytesize)
+          value.strip!
+          headers[name] = value
         end
 
         unless headers["upgrade"]&.downcase == "websocket"
@@ -55,17 +74,21 @@ module Monk
       end
       private_class_method :bearer_token
 
+      # The last session_token in the header wins, as when it was a Hash.
       def self.session_cookie_token(headers)
-        headers["cookie"].to_s.split(";").each_with_object({}) do |pair, cookies|
+        token = nil
+        headers["cookie"]&.split(";")&.each do |pair|
           name, value = pair.strip.split("=", 2)
-          cookies[name] = value if name
-        end["session_token"]
+          token = value if name == "session_token"
+        end
+        token
       end
       private_class_method :session_cookie_token
 
-      def self.response_for(raw_request)
-        headers = parse_request(raw_request)
+      def self.response_for(raw_request) = response(parse_request(raw_request))
 
+      # The 101 for headers parse_request already returned.
+      def self.response(headers)
         "HTTP/1.1 101 Switching Protocols\r\n" \
         "Upgrade: websocket\r\n" \
         "Connection: Upgrade\r\n" \

data/lib/monk/websocket/pg_fanout.rb

@@ -225,17 +225,17 @@ module Monk
       end
 
       def register(key, port)
-        unless Listeners.listening?(@origin)
-          raise NotListeningError,
-            "Monk::WebSocket::PgFanout#register before #listen!: this socket would never get " \
-            "other processes' broadcasts -- call listen! once at boot in the process that holds " \
-            "sockets (bin/websocket_server: Monk::Live.listen!)"
-        end
-
+        ensure_listening!(:register)
         @registry.register(key, port)
       end
 
+      def register_many(keys, port)
+        ensure_listening!(:register_many)
+        @registry.register_many(keys, port)
+      end
+
       def unregister(key, port) = @registry.unregister(key, port)
+      def unregister_many(keys, port) = @registry.unregister_many(keys, port)
       def count(key) = @registry.count(key)
 
       def broadcast(key, payload)
@@ -266,6 +266,15 @@ module Monk
 
       private
 
+      def ensure_listening!(method)
+        return if Listeners.listening?(@origin)
+
+        raise NotListeningError,
+          "Monk::WebSocket::PgFanout##{method} before #listen!: this socket would never get " \
+          "other processes' broadcasts -- call listen! once at boot in the process that holds " \
+          "sockets (bin/websocket_server: Monk::Live.listen!)"
+      end
+
       # The pool's database's connection options, for #listen!.
       def pooled_pg_opts(db_pool)
         config = Monk::Persistence::Pg.pool_config(db_pool)

data/lib/monk/websocket/redis_fanout.rb

@@ -161,17 +161,17 @@ module Monk
       end
 
       def register(key, port)
-        unless Listeners.listening?(@origin)
-          raise NotListeningError,
-            "Monk::WebSocket::RedisFanout#register before #listen!: this socket would never get " \
-            "other processes' broadcasts -- call listen! once at boot in the process that holds " \
-            "sockets (bin/websocket_server: Monk::Live.listen!)"
-        end
-
+        ensure_listening!(:register)
         @registry.register(key, port)
       end
 
+      def register_many(keys, port)
+        ensure_listening!(:register_many)
+        @registry.register_many(keys, port)
+      end
+
       def unregister(key, port) = @registry.unregister(key, port)
+      def unregister_many(keys, port) = @registry.unregister_many(keys, port)
       def count(key) = @registry.count(key)
 
       def broadcast(key, payload)
@@ -181,6 +181,15 @@ module Monk
 
       private
 
+      def ensure_listening!(method)
+        return if Listeners.listening?(@origin)
+
+        raise NotListeningError,
+          "Monk::WebSocket::RedisFanout##{method} before #listen!: this socket would never get " \
+          "other processes' broadcasts -- call listen! once at boot in the process that holds " \
+          "sockets (bin/websocket_server: Monk::Live.listen!)"
+      end
+
       # A single shared Redis client called concurrently from every
       # connection Ractor's #broadcast wouldn't be safe -- redis-rb clients
       # aren't documented safe for concurrent commands from multiple

data/lib/monk/websocket/registry.rb

@@ -8,8 +8,9 @@ module Monk
     # A dedicated Ractor holding the live set of connection handles keyed by
     # an app-assigned channel/subject -- mirrors StateRactor's shape
     # (docs/design/ractor.md): the mutable Hash stays hidden inside this one
-    # Ractor, and every call is a synchronous "ask" via a fresh
-    # Ractor::Port, so registration/broadcast can never race each other.
+    # Ractor, and every call is a synchronous "ask" answered on the
+    # caller's reply port, so registration/broadcast can never race each
+    # other.
     class Registry
       def initialize
         @ractor = Ractor.new do
@@ -25,6 +26,14 @@ module Monk
               when :unregister
                 keys[key].delete(arg)
                 true
+              when :register_many
+                # key is the Array of keys: a Live subscribe's topics in
+                # one ask, not one each.
+                key.each { |k| keys[k] << arg unless keys[k].include?(arg) }
+                true
+              when :unregister_many
+                key.each { |k| keys[k].delete(arg) }
+                true
               when :broadcast
                 # A port can be closed out from under this loop without
                 # ever going through #unregister -- e.g. the owning
@@ -58,7 +67,13 @@ module Monk
                 end
                 ports.size
               end
-            reply_port.send(result)
+            begin
+              reply_port.send(result)
+            rescue Ractor::ClosedError
+              # The caller gave up on this ask (its thread was killed while
+              # it waited) and closed its port: nobody to answer, and no
+              # reason to end the registry for every other caller.
+            end
           end
         end
         freeze
@@ -72,6 +87,16 @@ module Monk
         ask(:unregister, key, port)
       end
 
+      # register for each of keys, in one ask: one message and one reply
+      # instead of one each (docs/plan-ws-connect-ceiling.md, item 5).
+      def register_many(keys, port)
+        ask(:register_many, keys, port)
+      end
+
+      def unregister_many(keys, port)
+        ask(:unregister_many, keys, port)
+      end
+
       def broadcast(key, payload)
         ask(:broadcast, key, payload)
       end
@@ -99,10 +124,20 @@ module Monk
 
       private
 
+      # An ask is synchronous, so a fiber has at most one outstanding: its
+      # reply port is made once and reused (a Port is an allocation and a
+      # message each), taken out of fiber storage while the ask is in
+      # flight. An ask cut short (the thread killed while it waits) closes
+      # the port instead of putting it back, so its late reply can't be
+      # read as the next ask's.
       def ask(op, key, arg)
-        reply_port = Ractor::Port.new
+        reply_port = Thread.current[:monk_registry_reply_port] || Ractor::Port.new
+        Thread.current[:monk_registry_reply_port] = nil
         @ractor.send([op, key, arg, reply_port])
-        reply_port.receive
+        result = reply_port.receive
+        Thread.current[:monk_registry_reply_port] = reply_port
+        reply_port = nil
+        result
       rescue Ractor::ClosedError
         # The registry Ractor itself can be gone by the time this runs --
         # e.g. process-wide shutdown (Ctrl+C) tearing down Ractors in

data/lib/monk/websocket/server.rb

@@ -55,14 +55,49 @@ module Monk
       # hostile client on a public endpoint, not an opt-in behavior
       # change, so a server that doesn't mention it still gets the
       # default cap rather than no cap at all.
+      #
+      # max_handshakes: caps the connections still in their handshake (the
+      # HTTP upgrade and, with authenticate:, verifying the session). At the
+      # cap the accept loop stops accepting until one finishes, and new
+      # connects wait in the kernel's listen backlog. Without it, a burst
+      # past what the process can verify (a restart's reconnect wave) starts
+      # every handshake at once, fills db_pool:'s queue, and ends with most
+      # of them timing out instead of the rest queueing
+      # (docs/plan-ws-connect-ceiling.md, item 1). Kept well under the
+      # pool's queue (1,000 by default), so a full cap can't overfill it.
+      # Always on, like max_payload_size:.
+      #
+      # handshake_timeout: (seconds) bounds the whole handshake, from
+      # accept to the 101, and Handshake::MAX_REQUEST_SIZE its request; a
+      # client past the deadline is dropped, one past the size gets a 431.
+      # Without them, a socket that connects and sends nothing holds a
+      # max_handshakes: slot forever, so a few hundred of them would shut
+      # the server, and a request that never ends grows without limit
+      # (item 2). Off once the 101 is written: an idle socket is the
+      # handler's business, not the handshake's.
+      #
+      # reuse_port: true lets several processes listen on the one port, and
+      # on Linux the kernel spreads connects across them. Each has its own
+      # heap, so its own GC pauses, over a share of the sockets: on Ruby 4.0
+      # K processes cut what GC costs a connect by about K squared
+      # (item 8). A broadcast reaches all of them through the fan-out.
       AUTHENTICATE_MODES = [false, true, :optional].freeze
 
+      DEFAULT_MAX_HANDSHAKES = 128
+      DEFAULT_HANDSHAKE_TIMEOUT = 10
+
+      # What the handshake's verify returns when it raised instead of
+      # answering (the pool full or timed out, the database down): neither
+      # a subject nor "no session", so the connection gets a 503.
+      VERIFY_FAILED = Object.new.freeze
+
       # The signals #run treats as "stop": Ctrl+C and TERM.
       STOP_SIGNALS = [Signal.list.fetch("INT"), Signal.list.fetch("TERM")].freeze
 
       def initialize(
         port:, bind: "0.0.0.0", allowed_origins: nil, authenticate: false, ping_interval: nil,
-        reverify_interval: nil, max_payload_size: Connection::DEFAULT_MAX_PAYLOAD_SIZE, db_pool: nil
+        reverify_interval: nil, max_payload_size: Connection::DEFAULT_MAX_PAYLOAD_SIZE, db_pool: nil,
+        max_handshakes: DEFAULT_MAX_HANDSHAKES, handshake_timeout: DEFAULT_HANDSHAKE_TIMEOUT, reuse_port: false
       )
         if ping_interval && !ping_interval.positive?
           raise ArgumentError, "ping_interval must be positive, got #{ping_interval.inspect}"
@@ -85,6 +120,14 @@ module Monk
           raise ArgumentError, "max_payload_size must be positive, got #{max_payload_size.inspect}"
         end
 
+        unless max_handshakes.is_a?(Integer) && max_handshakes.positive?
+          raise ArgumentError, "max_handshakes must be a positive Integer, got #{max_handshakes.inspect}"
+        end
+
+        unless handshake_timeout.is_a?(Numeric) && handshake_timeout.positive?
+          raise ArgumentError, "handshake_timeout must be positive, got #{handshake_timeout.inspect}"
+        end
+
         if authenticate
           unless defined?(Monk::Auth) && Monk::Auth.config
             raise Monk::AuthNotConfiguredError,
@@ -106,19 +149,46 @@ module Monk
         # declared or isn't started in this process.
         Monk::Persistence::Pg.pool(db_pool) if db_pool
 
-        @tcp_server = TCPServer.new(bind, port)
+        @tcp_server = reuse_port ? Server.listen_reusing_port(bind, port) : TCPServer.new(bind, port)
         @allowed_origins = allowed_origins ? Ractor.make_shareable(allowed_origins.dup) : nil
         @authenticate = authenticate
         @ping_interval = ping_interval
         @reverify_interval = reverify_interval
         @max_payload_size = max_payload_size
         @db_pool = db_pool
+        @max_handshakes = max_handshakes
+        @handshake_timeout = handshake_timeout
       end
 
       def port
         @tcp_server.addr[1]
       end
 
+      # reuse_port:, for several processes on one port (bin/websocket_server's
+      # WS_PROCESSES): SO_REUSEPORT has to be set before the bind, which
+      # TCPServer.new does at once. On Linux the kernel spreads connects
+      # across the processes listening.
+      def self.listen_reusing_port(bind, port)
+        unless defined?(Socket::SO_REUSEPORT)
+          raise ArgumentError, "reuse_port: true needs SO_REUSEPORT, which this platform doesn't have"
+        end
+
+        address = Addrinfo.tcp(bind, port)
+        socket = Socket.new(address.afamily, :STREAM)
+        socket.setsockopt(:SOCKET, :REUSEADDR, true)
+        socket.setsockopt(:SOCKET, :REUSEPORT, true)
+        socket.bind(address)
+        socket.listen(Socket::SOMAXCONN)
+        # A TCPServer on the same descriptor, so accept returns a TCPSocket
+        # as without reuse_port:.
+        socket.autoclose = false
+        TCPServer.for_fd(socket.fileno)
+      rescue StandardError
+        socket&.autoclose = true
+        socket&.close
+        raise
+      end
+
       def run(&block)
         shareable_block =
           begin
@@ -130,16 +200,30 @@ module Monk
               "top-level block -- mirrors StateRactor#update's own constraint)"
           end
 
+        # One slot a handshake in flight (max_handshakes:). Each connection
+        # Ractor sends to handshake_done once its handshake is over, however
+        # it ended, and the releaser thread frees a slot for it.
+        slots = Thread::SizedQueue.new(@max_handshakes)
+        handshake_done = Ractor::Port.new
+        releaser = Thread.new do
+          loop do
+            handshake_done.receive
+            slots.pop
+          end
+        end
+
         loop do
+          slots.push(true)
           socket = @tcp_server.accept
           ractor = Ractor.new(
             shareable_block, @authenticate, @allowed_origins, @ping_interval, @reverify_interval, @max_payload_size,
-            @db_pool
-          ) do |blk, authenticate, origins, ping_interval, reverify_interval, max_payload_size, db_pool|
+            @db_pool, handshake_done, @handshake_timeout
+          ) do |blk, authenticate, origins, ping_interval, reverify_interval, max_payload_size, db_pool, done, timeout|
             Monk::WebSocket::Server.serve(
               Ractor.receive, blk,
               authenticate: authenticate, allowed_origins: origins, ping_interval: ping_interval,
-              reverify_interval: reverify_interval, max_payload_size: max_payload_size, db_pool: db_pool
+              reverify_interval: reverify_interval, max_payload_size: max_payload_size, db_pool: db_pool,
+              handshake_done: done, handshake_timeout: timeout
             )
           end
           ractor.send(socket, move: true)
@@ -161,45 +245,63 @@ module Monk
         # different failure point in this same shutdown -- a live
         # connection's cleanup racing the registry Ractor's teardown.
         @tcp_server.close
+      ensure
+        releaser&.kill
+        handshake_done&.close
       end
 
       # Runs entirely inside the connection's own dedicated Ractor
       # (docs/history/plan-websocket.md Decision 3) -- a class method, not an instance
       # method, since the Server instance itself (holding a live
       # TCPServer) is never Ractor-shareable and can't cross into here.
+      #
+      # handshake_done: is #run's port for max_handshakes:, told once the
+      # handshake is over: the 101 written, or the connection refused or
+      # dropped before it.
       def self.serve(
         socket, block, authenticate: false, allowed_origins: nil, ping_interval: nil, reverify_interval: nil,
-        max_payload_size: Connection::DEFAULT_MAX_PAYLOAD_SIZE, db_pool: nil
+        max_payload_size: Connection::DEFAULT_MAX_PAYLOAD_SIZE, db_pool: nil, handshake_done: nil,
+        handshake_timeout: DEFAULT_HANDSHAKE_TIMEOUT
       )
-        request = read_handshake_request(socket)
-        return socket.close unless request
-
-        headers =
-          begin
-            Handshake.parse_request(request)
-          rescue Monk::WebSocket::HandshakeError
-            return socket.write("HTTP/1.1 400 Bad Request\r\n\r\n")
+        # A `return` in here (a refused handshake) ends serve, and its
+        # ensure frees the slot.
+        credential, subject = with_deadline(socket, handshake_timeout) do
+          request = read_handshake_request(socket)
+          return unless request
+          return socket.write("HTTP/1.1 431 Request Header Fields Too Large\r\n\r\n") if request == :too_large
+
+          headers =
+            begin
+              Handshake.parse_request(request)
+            rescue Monk::WebSocket::HandshakeError
+              return socket.write("HTTP/1.1 400 Bad Request\r\n\r\n")
+            end
+
+          subject = nil
+          credential = Handshake.credential_from(headers) if authenticate
+          case authenticate
+          when true
+            subject = authenticate!(socket, headers, credential, allowed_origins, db_pool)
+            return unless subject
+          when :optional
+            return unless origin_allowed_for_optional?(socket, headers, credential, allowed_origins)
+
+            subject = identify(credential, db_pool)
+            # Not anonymous: that would quietly sign the user out of their
+            # topics until the next reconnect.
+            return unavailable!(socket, headers) if subject.equal?(VERIFY_FAILED)
           end
 
-        subject = nil
-        case authenticate
-        when true
-          subject = authenticate!(socket, headers, allowed_origins, db_pool)
-          return unless subject
-        when :optional
-          return unless origin_allowed_for_optional?(socket, headers, allowed_origins)
-
-          subject = identify(headers, db_pool)
+          socket.write(Handshake.response(headers))
+          [credential, subject]
         end
-
-        socket.write(Handshake.response_for(request))
+        handshake_done = handshake_over(handshake_done)
 
         connection = Connection.new(socket, subject: subject, max_payload_size: max_payload_size)
         connection.start_heartbeat(ping_interval) if ping_interval
-        reverify_thread =
-          if reverify_interval && subject
-            start_reverify(connection, Handshake.credential_from(headers)[:token], reverify_interval, db_pool)
-          end
+        if reverify_interval && subject
+          reverify_thread = start_reverify(connection, credential[:token], reverify_interval, db_pool)
+        end
         begin
           block.call(connection)
         rescue StandardError
@@ -209,11 +311,16 @@ module Monk
           # not re-raised -- there's no caller left to hand it to once
           # we're inside this connection's own dedicated Ractor.
         end
+      rescue IOError, SystemCallError
+        # The client went away, or was shut out by the deadline, before
+        # the handshake was over: nothing to answer.
       ensure
         # Runs on every exit path -- normal completion, the close
         # handshake, and a crashed handler alike -- so a subscribed
         # connection never leaks a stale registry entry (step 17), a
         # heartbeat thread, or a reverify thread outliving its socket.
+        # A handshake that never reached its 101 still frees its slot.
+        handshake_over(handshake_done)
         reverify_thread&.kill
         connection&.unsubscribe!
         connection&.stop_heartbeat!
@@ -221,6 +328,35 @@ module Monk
         disconnect_all
       end
 
+      # Runs the block with a watchdog that shuts the socket down once
+      # `seconds` have passed, which ends a read or write blocked on it (a
+      # read returns nil, a write raises). Not IO#timeout=: on Ruby 4.0,
+      # once an IO#timeout has fired in one Ractor, reads in Ractors made
+      # after it can raise IO::TimeoutError on sockets with no timeout set.
+      def self.with_deadline(socket, seconds)
+        watchdog = Thread.new do
+          sleep seconds
+          socket.shutdown(:RDWR)
+        rescue IOError, SystemCallError
+          # Already closed or gone.
+        end
+        yield
+      ensure
+        watchdog&.kill
+      end
+      private_class_method :with_deadline
+
+      # Frees this connection's max_handshakes: slot in #run; returns nil,
+      # so serve can mark it freed. The port is gone once #run has
+      # returned, and then there's no slot to free.
+      def self.handshake_over(handshake_done)
+        handshake_done&.send(true)
+        nil
+      rescue Ractor::ClosedError
+        nil
+      end
+      private_class_method :handshake_over
+
       # Closes the connections this socket's Ractor opened: its database
       # connection (verifying the session without db_pool:, or a block
       # that queries) and a fan-out's publisher (a block that broadcasts).
@@ -239,10 +375,9 @@ module Monk
       # credential -- a Bearer connection has no Origin header to check
       # by construction (mirrors require_csrf!'s own Bearer exemption in
       # docs/history/plan-auth.md). Returns the verified subject, or nil after writing
-      # the appropriate 403/401 response itself.
-      def self.authenticate!(socket, headers, allowed_origins, db_pool)
-        credential = Handshake.credential_from(headers)
-
+      # the appropriate 403/401 response itself -- or 503, when verify
+      # couldn't answer (docs/plan-ws-connect-ceiling.md, item 3).
+      def self.authenticate!(socket, headers, credential, allowed_origins, db_pool)
         if credential&.fetch(:via) == :cookie && allowed_origins
           origin = headers["origin"]
           unless origin && allowed_origins.include?(origin)
@@ -251,12 +386,26 @@ module Monk
           end
         end
 
-        subject = credential && verify(credential[:token], db_pool)
+        subject = credential && handshake_verify(credential[:token], db_pool)
+        return unavailable!(socket, headers) if subject.equal?(VERIFY_FAILED)
+
         socket.write("HTTP/1.1 401 Unauthorized\r\n\r\n") unless subject
         subject
       end
       private_class_method :authenticate!
 
+      # A handshake whose verify couldn't answer: 503, and nil. Browser JS
+      # never sees a failed handshake's status or headers (only onclose,
+      # 1006), so Retry-After is for the other clients, the ones without
+      # an Origin, and jittered, so a wave of them doesn't come back as
+      # one.
+      def self.unavailable!(socket, headers)
+        retry_after = headers["origin"] ? "" : "Retry-After: #{rand(1..10)}\r\n"
+        socket.write("HTTP/1.1 503 Service Unavailable\r\n#{retry_after}\r\n")
+        nil
+      end
+      private_class_method :unavailable!
+
       # authenticate: :optional's Origin check, before anything is verified.
       # A Bearer connection is exempt, as under true. A cookie needs an
       # allowed Origin, as under true. An anonymous connection that sends an
@@ -264,10 +413,9 @@ module Monk
       # stops another site's page from opening sockets here on its
       # visitors' behalf; one that sends none (not a browser) gets in.
       # Writes the 403 itself and returns false when refused.
-      def self.origin_allowed_for_optional?(socket, headers, allowed_origins)
+      def self.origin_allowed_for_optional?(socket, headers, credential, allowed_origins)
         return true unless allowed_origins
 
-        credential = Handshake.credential_from(headers)
         return true if credential&.fetch(:via) == :bearer
 
         origin = headers["origin"]
@@ -280,13 +428,26 @@ module Monk
       private_class_method :origin_allowed_for_optional?
 
       # The subject of a valid session, or nil -- no credential, or one
-      # Monk::Auth no longer accepts, both mean anonymous under :optional.
-      def self.identify(headers, db_pool)
-        credential = Handshake.credential_from(headers)
-        credential && verify(credential[:token], db_pool)
+      # Monk::Auth no longer accepts, both mean anonymous under :optional --
+      # or VERIFY_FAILED.
+      def self.identify(credential, db_pool)
+        credential && handshake_verify(credential[:token], db_pool)
       end
       private_class_method :identify
 
+      # verify, or VERIFY_FAILED with one line on stderr if it raised:
+      # under a burst, a backtrace per refused connection buries the log.
+      # The message's first line only (a PG error adds the query and a
+      # caret), and not Kernel#warn, which -W0 silences.
+      def self.handshake_verify(raw_token, db_pool)
+        verify(raw_token, db_pool)
+      rescue StandardError => e
+        reason = e.message.lines.first&.chomp
+        $stderr.puts "monk-websocket: handshake refused with 503, verify failed: #{e.class}: #{reason}" # rubocop:disable Style/StderrPuts
+        VERIFY_FAILED
+      end
+      private_class_method :handshake_verify
+
       # Sleeps in `interval`-sized steps, re-running Monk::Auth.verify
       # against the same raw credential each time, until it comes back
       # nil (revoked or expired) -- then closes the connection with the
@@ -319,15 +480,18 @@ module Monk
       end
       private_class_method :verify
 
+      # The request head, nil if the client went away or was too slow, or
+      # :too_large past Handshake::MAX_REQUEST_SIZE.
+      #
+      # One String, read through the socket's own buffer: Connection's
+      # reads use that buffer after it, so a frame the client sent right
+      # behind its request isn't lost (a readpartial would take it into
+      # the request and drop it). A read(1) loop made a String a byte.
       def self.read_handshake_request(socket)
-        request = +""
-        until request.end_with?("\r\n\r\n")
-          chunk = socket.read(1)
-          return nil if chunk.nil?
+        request = socket.gets("\r\n\r\n", Handshake::MAX_REQUEST_SIZE)
+        return request if request&.end_with?("\r\n\r\n")
 
-          request << chunk
-        end
-        request
+        :too_large if request && request.bytesize >= Handshake::MAX_REQUEST_SIZE
       end
       private_class_method :read_handshake_request
     end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: monkrb
 version: !ruby/object:Gem::Version
-  version: 0.22.0
+  version: 0.22.1
 platform: ruby
 authors:
 - Matteo Folin