monkrb 0.21.1 → 0.22.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fd1a1140ab4c223d2bdd9c10a226ea274e0051af1ab01444194cb4dc88ebb166
-  data.tar.gz: 9fab9365ba1a31224caf14038c2e36c0ba59c9cc70dd60c037f4dbfa78aec8c8
+  metadata.gz: ae98dd74608d293e7fdae3c428abae8d851f25e4a52d02d9d92aa499588d5182
+  data.tar.gz: ff9fb430178e748ea859c9c6ae8ef72b8d35851b297a7d38f39b9f36a8597f02
 SHA512:
-  metadata.gz: 36bf94be6268d9f12fbb703132f96b00a84c52e5eeb6b03d9b90b9e981d5c9be2ee89003ecc7952b2880d288454d4d6d1734ffb6cfd8bd70328dded0cbbc1e0e
-  data.tar.gz: 58c8a897231b31edcc82cfd0e3162c64633a2a121f2b3cc01dbbe3b2fa6ef7a7d9760eb2b623a4b6b8def85004322abba20b001758dadd291f8a2ada52b3d26b
+  metadata.gz: ffa8fe3639cca148a43d9bd308d2e5b7fe761d391d3687a709e82c2747ec0825184c2b3f10bafe3630a6f568733545ff8879ab0768f9f555256e83c0d0cc5f7e
+  data.tar.gz: 1a7ec63d1a87f9f31d931022889a1630dcd4b8c4e02316992650a72e2bc5114fe49c280ace2a638b43d9425a4460283fe295f10b6f27ce499649db8e4156ebe9

data/CHANGELOG.md

@@ -4,6 +4,100 @@ 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
+
+- **Recurring jobs.** `Monk::Jobs.recurring "purge_sessions",
+  PurgeSessions, cron: "0 3 * * *"`, declared in `config/recurring.rb`,
+  is enqueued by `bin/jobs` at each occurrence, once however many job
+  processes run. Five-field cron in UTC, plus `@hourly` to `@yearly`. A
+  new task first runs at its next occurrence, missed occurrences run
+  once, and `skip_if_pending: true` skips a run while the previous one
+  hasn't finished. `Monk::Jobs.run_scheduler!(at:)` runs the schedule in
+  tests. One checkpoint row per task in the new `monk_recurring_tasks`
+  table (ADR 0016, `docs/guides/jobs.md`, "Recurring jobs").
+  `monk add jobs` writes `config/recurring.rb` with a commented example
+  and the table's migration, and the base `config/load.rb` loads
+  `config/recurring.rb` after `app/`. An app that already has jobs:
+  `docs/guides/upgrading.md`, 0.22; until then its tests that call
+  `Monk::Jobs.clear!` fail on the missing table.
+- **A login-email rate limit in `Monk::Auth`.**
+  `Monk::Auth.allow_login_request?(email)` allows one login email per
+  address per `login_request_interval:` (60 seconds), counted in a new
+  `login_requests` table, so across every process. The scaffolded login
+  routes use it instead of the per-process `RateLimiter`.
+  `Monk::Auth.clear_login_requests!` resets it in tests.
+- **Auth cleans up after itself.** `Monk::Auth.sweep!` deletes in batches
+  and covers `login_requests`; the new `Monk::Auth::Sweep` job runs it,
+  and `monk add jobs`'s `config/recurring.rb` schedules it nightly
+  (`monk_auth_sweep`) when auth is installed.
+- **An index on `sessions (subject)`**, in the same new auth migration,
+  `create_login_requests`. An app that already has auth:
+  `docs/guides/upgrading.md`, 0.22, "Auth housekeeping".
+
 ## 0.21.1 - 2026-10-09
 
 ### Fixed

data/README.md

@@ -21,7 +21,7 @@ bin/server           # -> http://localhost:9292/hello
 monk add --list      # the modules you can add: postgres, auth, jobs, live...
 ```
 
-`monk new` scaffolds the app's own `Gemfile` with `gem "monkrb", "~> 0.21", require: "monk"`.
+`monk new` scaffolds the app's own `Gemfile` with `gem "monkrb", "~> 0.22", require: "monk"`.
 
 `monk new` writes a working skeleton (an HTML home page, a `/hello` route, a `/api/hello` JSON route, `public/`, its tests, a `SETUP.md` and an `AGENTS.md` for coding agents), with the app's own code under `app/`: `app/app.rb` and `app/routes/` for routes, `app/views/`, and one directory per role (`models/`, `presenters/`, `helpers/`, `mailers/`, `broadcasts/`, `jobs/`). `monk add` adds Postgres, Redis, email, auth, background jobs, WebSocket and live updates, to a new app or an old one, each with its wiring, commented examples of how to use it, and a test (`monk new my_app --with auth,jobs` does both at once): see [`docs/guides/scaffolding.md`](docs/guides/scaffolding.md), which also says where each kind of code goes.
 
@@ -60,9 +60,9 @@ Everything beyond the core is opt-in (`require "monk"` alone loads none of it).
 | Logging | request log per environment, `Monk::Log.debug`/`info`/`warn`/`error` | — | [`logging.md`](docs/guides/logging.md) |
 | Persistence | `Monk::Persistence::Pg`: raw `pg`, per-Ractor connections, hash-based `Model` | `require "monk/persistence/pg"` (+ `.../pg/model`); needs the `pg` gem | [`persistence.md`](docs/guides/persistence.md) |
 | Migrations | plain `.sql` up/down pairs, `Migrator` | `require "monk/persistence/pg/migrator"`; needs the `pg` gem | [`migrations.md`](docs/guides/migrations.md) |
-| Auth and sessions | `Monk::Auth`: passwordless tokens, Bearer or cookie + CSRF | `require "monk/auth"`; needs the `pg` gem and a registered Postgres connection | [`auth.md`](docs/guides/auth.md) |
+| Auth and sessions | `Monk::Auth`: passwordless tokens, Bearer or cookie + CSRF, a per-address login-email rate limit, nightly cleanup with jobs | `require "monk/auth"`; needs the `pg` gem and a registered Postgres connection | [`auth.md`](docs/guides/auth.md) |
 | Email | `Monk::Mail`: text/HTML email over SMTP or a local relay, one `MAIL_URL`, sent from any worker Ractor, or from a background job with `deliver_later` | `require "monk/mail"`; `deliver_later` is there once `monk/jobs` is loaded too; SMTP needs the `net-smtp` gem | [`mail.md`](docs/guides/mail.md) |
-| Background jobs | `Monk::Jobs`: a queue in Postgres, run by `bin/jobs` on worker Ractors; retries with backoff, scheduled jobs, enqueue inside the app's own transaction, `drain!` for tests | `require "monk/jobs"` (+ `require "monk/jobs/runtime"` in the job process); needs the `pg` gem and a registered Postgres connection | [`jobs.md`](docs/guides/jobs.md) |
+| Background jobs | `Monk::Jobs`: a queue in Postgres, run by `bin/jobs` on worker Ractors; retries with backoff, scheduled jobs, recurring jobs on a cron schedule (UTC), enqueue inside the app's own transaction, `drain!` for tests | `require "monk/jobs"` (+ `require "monk/jobs/runtime"` in the job process); needs the `pg` gem and a registered Postgres connection | [`jobs.md`](docs/guides/jobs.md) |
 | WebSocket | `Monk::WebSocket`: RFC 6455 server as its own process, Redis or Postgres fan-out | `require "monk/websocket"`; fan-out: `require "monk/websocket/redis_fanout"` (+ the `redis` gem) or `require "monk/websocket/pg_fanout"` (+ the `pg` gem) | [`websocket.md`](docs/guides/websocket.md) |
 | Live updates | `Monk::Live`: server-rendered HTML patches pushed to open tabs | `require "monk/live"`; needs the WebSocket server and, across processes, Redis or Postgres | [`live.md`](docs/guides/live.md) |
 | Scaffolding | `monk new` and `monk add`: one generator per module, for a new app or an existing one; text or `--json` output | — (the `monk` command: `monk new NAME --with ...`, `monk add MODULE`, `monk add --list`) | [`scaffolding.md`](docs/guides/scaffolding.md) |
@@ -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`).
+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/auth/errors.rb

@@ -13,4 +13,9 @@ module Monk
 
   class MissingAuthDeliveryError < StandardError
   end
+
+  # Monk::Auth.clear_login_requests! outside MONK_ENV=test: it would lift
+  # the login-email rate limit for every address.
+  class ClearLoginRequestsOutsideTestsError < StandardError
+  end
 end

data/lib/monk/auth/sweep.rb

@@ -0,0 +1,23 @@
+# Monk::Auth::Sweep. Loaded at the end of whichever of monk/auth and
+# monk/jobs is required second, once both are defined (docs/adr/0017), so
+# it requires neither itself.
+
+module Monk
+  module Auth
+    # Monk::Auth.sweep! as a job: deletes expired login tokens and sessions
+    # and old login requests. config/recurring.rb (monk add jobs) runs it
+    # nightly when auth is installed (docs/history/plan-auth-housekeeping.md
+    # decision 1):
+    #
+    #   Monk::Jobs.recurring "monk_auth_sweep", Monk::Auth::Sweep, cron: "17 3 * * *" if defined?(Monk::Auth::Sweep)
+    class Sweep < Monk::Job
+      def self.perform
+        counts = Monk::Auth.sweep!
+        Monk::Log.info(
+          "Monk::Auth::Sweep: deleted #{counts[:sessions]} sessions, #{counts[:login_tokens]} login tokens, " \
+          "#{counts[:login_requests]} login requests",
+        )
+      end
+    end
+  end
+end

data/lib/monk/auth.rb

@@ -16,6 +16,34 @@ module Monk
   module Auth
     REQUIRED_CONFIG_KEYS = %i[db_name secret login_ttl session_ttl].freeze
 
+    # The login-email rate limit (docs/history/plan-auth-housekeeping.md decision
+    # 5): records a request unless one was recorded for the address less
+    # than $2 seconds ago. One statement, so racing requests for one
+    # address let exactly one through; a refused request changes nothing.
+    LOGIN_REQUEST_SQL = <<~SQL.freeze
+      INSERT INTO login_requests (email) VALUES ($1)
+      ON CONFLICT (email) DO UPDATE SET requested_at = now()
+        WHERE login_requests.requested_at < now() - $2::int * interval '1 second'
+      RETURNING 1
+    SQL
+
+    SWEEP_BATCH_SIZE = 10_000
+
+    # sweep!'s statements, one batch each. Tokens and sessions expire by
+    # the app's clock, as redeem and verify check them; login requests by
+    # the database's, as allow_login_request? does.
+    SWEEP_LOGIN_TOKENS_SQL = <<~SQL.freeze
+      DELETE FROM login_tokens WHERE id IN (SELECT id FROM login_tokens WHERE expires_at < $1 LIMIT $2)
+    SQL
+    SWEEP_SESSIONS_SQL = <<~SQL.freeze
+      DELETE FROM sessions WHERE id IN (SELECT id FROM sessions WHERE expires_at < $1 LIMIT $2)
+    SQL
+    SWEEP_LOGIN_REQUESTS_SQL = <<~SQL.freeze
+      DELETE FROM login_requests WHERE email IN (
+        SELECT email FROM login_requests WHERE requested_at < now() - $1::int * interval '1 second' LIMIT $2
+      )
+    SQL
+
     class << self
       # Called from Base#freeze! (Seam B), via Monk.freeze_hooks. Freezes
       # the value, not the module -- Monk::Auth is always Ractor.shareable?
@@ -37,15 +65,17 @@ module Monk
       # callback_path: is where the app's own callback route redeems a
       # token (GET "#{callback_path}/:token"). Monk doesn't define that
       # route, but builds links to it: login_link below, and so
-      # Monk::Auth::SendLoginLink.
+      # Monk::Auth::SendLoginLink. login_request_interval: is the seconds
+      # allow_login_request? makes an address wait between login emails.
       def configure(
         db_name: nil, secret: nil, login_ttl: nil, session_ttl: nil, redirect_allowlist: [], secure: true,
-        deliver: nil, callback_path: "/auth/callback"
+        deliver: nil, callback_path: "/auth/callback", login_request_interval: 60
       )
         config = {
           db_name: db_name, secret: secret, login_ttl: login_ttl, session_ttl: session_ttl,
           redirect_allowlist: redirect_allowlist, secure: secure, deliver: deliver,
           callback_path: checked_callback_path(callback_path),
+          login_request_interval: checked_login_request_interval(login_request_interval),
         }
 
         REQUIRED_CONFIG_KEYS.each do |key|
@@ -86,6 +116,37 @@ module Monk
         raw
       end
 
+      # The login-email rate limit, for the login route to check before it
+      # sends or enqueues the link: true, and recorded, if no link was
+      # requested for this address in the last login_request_interval
+      # seconds; false otherwise. Per address, across every process. The
+      # address is stripped and downcased for the limit only.
+      #
+      #   halt(429) unless Monk::Auth.allow_login_request?(email)
+      def allow_login_request?(email)
+        ensure_configured!
+        unless email.is_a?(String) && !email.strip.empty?
+          raise ArgumentError, "Monk::Auth.allow_login_request? needs an email address, got #{email.inspect}"
+        end
+
+        params = [email.strip.downcase, config[:login_request_interval]]
+        Monk::Persistence::Pg.checkout(config[:db_name]) { |c| c.exec_params(LOGIN_REQUEST_SQL, params).ntuples == 1 }
+      end
+
+      # Test-only: forgets every login request, so the next test can log in
+      # again at once. Refuses unless MONK_ENV is test.
+      def clear_login_requests!
+        unless Monk.env.test?
+          raise Monk::ClearLoginRequestsOutsideTestsError,
+            "Monk::Auth.clear_login_requests! lifts the login-email rate limit for every address, so it only " \
+            "runs with MONK_ENV=test (this is #{Monk.env})"
+        end
+
+        ensure_configured!
+        Monk::Persistence::Pg.checkout(config[:db_name]) { |c| c.exec("DELETE FROM login_requests") }
+        nil
+      end
+
       # The magic link for a raw token: the app's public_url
       # (config/settings.rb, a trusted origin -- never request headers like
       # X-Forwarded-Host, which any direct client can spoof), then
@@ -214,15 +275,28 @@ module Monk
         rows.size
       end
 
+      # Deletes expired login tokens and sessions, and login requests older
+      # than login_request_interval; returns how many of each. At most
+      # batch_size rows per statement, so a large backlog (the first sweep
+      # of an app that never swept) holds no lock for long. Run nightly by
+      # Monk::Auth::Sweep (docs/history/plan-auth-housekeeping.md decision 3).
       # Deliberately not grown onto Model: a `<` comparison is real
       # query-DSL scope for a hygiene task (docs/design/auth-sessions.md).
-      def sweep!
+      def sweep!(batch_size: SWEEP_BATCH_SIZE)
         ensure_configured!
+        unless batch_size.is_a?(Integer) && batch_size.positive?
+          raise ArgumentError, "batch_size: must be a positive Integer, got #{batch_size.inspect}"
+        end
+
         Monk::Persistence::Pg.checkout(config[:db_name]) do |conn|
           now = Time.now
-          login_tokens_deleted = conn.exec_params("DELETE FROM login_tokens WHERE expires_at < $1", [now]).cmd_tuples
-          sessions_deleted = conn.exec_params("DELETE FROM sessions WHERE expires_at < $1", [now]).cmd_tuples
-          { login_tokens: login_tokens_deleted, sessions: sessions_deleted }
+          {
+            login_tokens: delete_in_batches(conn, SWEEP_LOGIN_TOKENS_SQL, [now], batch_size),
+            sessions: delete_in_batches(conn, SWEEP_SESSIONS_SQL, [now], batch_size),
+            login_requests: delete_in_batches(
+              conn, SWEEP_LOGIN_REQUESTS_SQL, [config[:login_request_interval]], batch_size,
+            ),
+          }
         end
       end
 
@@ -279,6 +353,26 @@ module Monk
         path.chomp("/").freeze
       end
 
+      # Runs a batched DELETE until one deletes less than a full batch; the
+      # batch size is its last parameter.
+      def delete_in_batches(conn, sql, params, batch_size)
+        total = 0
+        loop do
+          deleted = conn.exec_params(sql, params + [batch_size]).cmd_tuples
+          total += deleted
+          return total if deleted < batch_size
+        end
+      end
+
+      def checked_login_request_interval(seconds)
+        unless seconds.is_a?(Integer) && seconds.positive?
+          raise Monk::InvalidAuthConfigError,
+            "Monk::Auth.configure(login_request_interval:) must be a positive Integer of seconds, got #{seconds.inspect}"
+        end
+
+        seconds
+      end
+
       def hash_token(raw)
         Digest::SHA256.hexdigest(raw)
       end
@@ -328,3 +422,4 @@ end
 # Monk::Auth::SendLoginLink, when jobs are loaded too -- either order works
 # (lib/monk/jobs.rb ends the same way, docs/adr/0017).
 require_relative "auth/send_login_link" if Monk.const_defined?(:Jobs)
+require_relative "auth/sweep" if Monk.const_defined?(:Jobs)

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/generators/auth.rb

@@ -9,6 +9,7 @@ Monk::Generator.define(:auth) do
   copy "app/routes/auth.rb", role: :example
   copy "test/auth_test.rb", role: :test
   migration "create_auth_tables"
+  migration "create_login_requests"
 
   env :development, { "AUTH_SECRET" => "change-me-dev-secret" }
   env :test, { "AUTH_SECRET" => "change-me-test-secret" }

data/lib/monk/generators/jobs.rb

@@ -4,11 +4,12 @@ Monk::Generator.define(:jobs) do
   installed_if "config/jobs.rb"
   depends_on :postgres
 
-  copy "config/jobs.rb", role: :wiring
+  copy "config/jobs.rb", "config/recurring.rb", role: :wiring
   copy "bin/jobs", role: :wiring, executable: true
   copy "app/jobs/hello_job.rb", "app/routes/jobs.rb", role: :example
   copy "test/jobs_test.rb", role: :test
   migration "create_jobs_tables"
+  migration "create_recurring_tables"
 
   queues = { "JOBS_WORKERS" => "2", "JOBS_QUEUES" => "mailers,default" }
   env :development, queues
@@ -18,4 +19,5 @@ Monk::Generator.define(:jobs) do
   agents_section "jobs/agents.md"
   next_step "bin/jobs", note: "beside bin/server"
   example "jobs-enqueue", todo: "uncomment, or enqueue your own jobs from any route"
+  example "jobs-recurring", todo: "uncomment to run the demo job every hour"
 end

data/lib/monk/jobs/adapters/pg.rb

@@ -2,11 +2,13 @@ require "json"
 require "time"
 require_relative "../../persistence/pg"
 require_relative "../claim"
+require_relative "../firing"
 
 module Monk
   module Jobs
     module Adapters
-      # The queue on Postgres: monk_jobs + monk_job_payloads + monk_processes
+      # The queue on Postgres: monk_jobs + monk_job_payloads + monk_processes,
+      # plus monk_recurring_tasks for the scheduler
       # (docs/adr/0013-jobs-narrow-state-table-plus-payloads.md). Holds only
       # the registered database's name and freezes itself, so the one
       # instance is shareable with every Ractor; each Ractor reaches the
@@ -151,9 +153,70 @@ module Monk
           WHERE id = $1 AND state = 'running' AND locked_by = $2
         SQL
 
+        # The scheduler's one statement per occurrence (docs/history/plan-scheduled-jobs.md
+        # decisions 5-8). ins, reinit and advance touch the task's row in
+        # mutually exclusive cases; advance is a compare-and-set on the
+        # checkpoint, so of several processes firing the same occurrence
+        # exactly one moves it and enqueues. The job's id is drawn from the
+        # sequence first, so the same UPDATE records it as last_job_id;
+        # that burns an id on calls that don't enqueue, harmless on a
+        # BIGINT. The pending check sits inside advance, so READ
+        # COMMITTED's recheck sees the row a racing UPDATE left. $10 stands
+        # in for now() under Monk::Jobs.run_scheduler!(at:).
+        FIRE_RECURRING_SQL = <<~SQL.freeze
+          WITH gate AS (
+            SELECT $3::timestamptz <= COALESCE($10::timestamptz, now()) AS due
+          ), prev AS (
+            SELECT last_occurrence_at FROM monk_recurring_tasks WHERE key = $1
+          ), seq AS (
+            SELECT nextval(pg_get_serial_sequence('monk_jobs', 'id')) AS id
+          ), ins AS (
+            INSERT INTO monk_recurring_tasks (key, cron, last_occurrence_at)
+            SELECT $1, $2, $3 FROM gate WHERE due
+            ON CONFLICT (key) DO NOTHING
+            RETURNING key
+          ), reinit AS (
+            UPDATE monk_recurring_tasks t
+            SET cron = $2, last_occurrence_at = $3, last_job_id = NULL, updated_at = now()
+            FROM gate
+            WHERE gate.due AND t.key = $1 AND t.cron <> $2
+            RETURNING t.key
+          ), advance AS (
+            UPDATE monk_recurring_tasks t
+            SET last_occurrence_at = $3, updated_at = now(),
+              last_job_id = CASE
+                WHEN $4::boolean AND EXISTS (
+                  SELECT 1 FROM monk_jobs j WHERE j.id = t.last_job_id AND j.state <> 'failed'
+                ) THEN t.last_job_id
+                ELSE seq.id
+              END
+            FROM gate, seq
+            WHERE gate.due AND t.key = $1 AND t.cron = $2 AND t.last_occurrence_at < $3
+            RETURNING t.last_job_id IS DISTINCT FROM seq.id AS skipped, seq.id AS job_id
+          ), job AS (
+            INSERT INTO monk_jobs (id, queue, priority, max_attempts, run_at, state) OVERRIDING SYSTEM VALUE
+            SELECT job_id, $5::text, $6::smallint, $7::smallint, now(), 'available' FROM advance WHERE NOT skipped
+            RETURNING id
+          ), payload AS (
+            INSERT INTO monk_job_payloads (job_id, job_class, args)
+            SELECT id, $8::text, $9::jsonb FROM job
+          )
+          SELECT CASE
+              WHEN NOT (SELECT due FROM gate) THEN 'not_due'
+              WHEN EXISTS (SELECT 1 FROM ins) THEN 'initialized'
+              WHEN EXISTS (SELECT 1 FROM reinit) THEN 'reinitialized'
+              WHEN EXISTS (SELECT 1 FROM advance WHERE skipped) THEN 'skipped_pending'
+              WHEN EXISTS (SELECT 1 FROM advance) THEN 'enqueued'
+              ELSE 'already_handled'
+            END AS result,
+            (SELECT id FROM job) AS job_id,
+            (SELECT extract(epoch FROM last_occurrence_at)::float8 FROM prev) AS previous_checkpoint
+        SQL
+
         CLEAR_SQL = <<~SQL.freeze
           DELETE FROM monk_jobs;
           DELETE FROM monk_processes;
+          DELETE FROM monk_recurring_tasks;
         SQL
 
         attr_reader :db_name
@@ -197,6 +260,30 @@ module Monk
           row && row["state"].to_sym
         end
 
+        # Handles one occurrence of a recurring task: initializes its
+        # checkpoint, enqueues its job, or finds the occurrence handled or
+        # not yet due (Firing). occurrence and clock are Times; clock, set
+        # only by Monk::Jobs.run_scheduler!, replaces the database clock.
+        def fire_recurring(key:, cron:, occurrence:, skip_if_pending:, job_class:, queue:, priority:, max_attempts:,
+                           args:, clock: nil)
+          params = [
+            key, cron, occurrence.utc.iso8601(6), skip_if_pending, queue, priority, max_attempts, job_class, args,
+            clock&.utc&.iso8601(6),
+          ]
+          row = with_connection { |c| c.exec_params(FIRE_RECURRING_SQL, params).first }
+          checkpoint = row["previous_checkpoint"]
+          Firing.new(
+            result: row["result"].to_sym, job_id: row["job_id"] && Integer(row["job_id"]),
+            previous_checkpoint: checkpoint && Time.at(Float(checkpoint).to_r, in: "UTC"),
+          )
+        end
+
+        # Whether monk_recurring_tasks exists, checked once when bin/jobs
+        # starts (docs/history/plan-scheduled-jobs.md decision 9).
+        def recurring_table?
+          with_connection { |c| !c.exec("SELECT to_regclass('monk_recurring_tasks')::text").getvalue(0, 0).nil? }
+        end
+
         # Moves up to `limit` due scheduled jobs to available; returns how many.
         def stage_due(limit = 500)
           with_connection { |c| c.exec_params(STAGE_SQL, [limit]).cmd_tuples }
@@ -256,7 +343,8 @@ module Monk
           nil
         end
 
-        # Every job (payloads by cascade) and every process row. Behind
+        # Every job (payloads by cascade), every process row and every
+        # recurring task's checkpoint. Behind
         # Monk::Jobs.clear!, which only runs in tests.
         def clear!
           with_connection { |c| c.exec(CLEAR_SQL) }