monkrb 0.21.1 → 0.22.1

data/lib/monk/jobs/cron.rb

@@ -0,0 +1,180 @@
+require_relative "errors"
+
+module Monk
+  module Jobs
+    # A recurring task's schedule (docs/history/plan-scheduled-jobs.md decision 3):
+    # five fields -- minute, hour, day of month, month, day of week -- each
+    # `*`, numbers, lists (`,`), ranges (`-`) and steps (`/`), plus the
+    # shortcuts in SHORTCUTS. No seconds, no names, no time zones: every
+    # time is UTC.
+    #
+    # When both day fields are restricted, a day matching either counts; a
+    # field starting with `*` (`*/2` too) doesn't restrict, as in Vixie
+    # cron. Day of week 7 is Sunday, like 0.
+    #
+    # Frozen Arrays of Integers all the way down, so a parsed expression is
+    # shareable with every Ractor.
+    Cron = Data.define(:expression, :minutes, :hours, :days, :months, :weekdays, :any_day, :any_weekday)
+
+    class Cron
+      SHORTCUTS = {
+        "@hourly" => "0 * * * *", "@daily" => "0 0 * * *", "@weekly" => "0 0 * * 0",
+        "@monthly" => "0 0 1 * *", "@yearly" => "0 0 1 1 *",
+      }.freeze
+
+      FIELDS = [["minute", 0..59], ["hour", 0..23], ["day of month", 1..31], ["month", 1..12],
+                ["day of week", 0..7],].freeze
+
+      PART = %r{\A(\*|\d+(?:-\d+)?)(?:/(\d+))?\z}
+
+      # The longest month each month can have: February counts its 29th.
+      MONTH_DAYS = [nil, 31, 29, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31].freeze
+
+      MINUTE = 60
+      HOUR = 3600
+      DAY = 86_400
+
+      # Neither lookup can go further than this without having found an
+      # occurrence: February 29th is at most 8 years away.
+      MAX_YEARS = 9
+
+      def self.parse(expression)
+        unless expression.is_a?(String)
+          raise InvalidCronError, "a cron expression is a String, got #{expression.inspect}"
+        end
+
+        normalized = expression.split.join(" ")
+        fields = shortcut(normalized).split
+        unless fields.size == 5
+          raise InvalidCronError,
+            "#{expression.inspect} has #{fields.size} field(s); a cron expression has 5 fields " \
+            "(minute hour day-of-month month day-of-week) or is one of #{SHORTCUTS.keys.join(", ")}"
+        end
+
+        minutes, hours, days, months, weekdays = fields.zip(FIELDS).map do |text, (name, range)|
+          parse_field(text, name, range, expression)
+        end
+        cron = new(
+          expression: normalized.freeze, minutes:, hours:, days:, months:,
+          weekdays: weekdays.map { |day| day % 7 }.uniq.sort.freeze,
+          any_day: fields[2].start_with?("*"), any_weekday: fields[4].start_with?("*"),
+        )
+        cron.check_matches!
+        Ractor.make_shareable(cron)
+      end
+
+      def self.shortcut(normalized)
+        return normalized unless normalized.start_with?("@")
+
+        SHORTCUTS.fetch(normalized) do
+          raise InvalidCronError, "unknown cron shortcut #{normalized.inspect}; known: #{SHORTCUTS.keys.join(", ")}"
+        end
+      end
+
+      def self.parse_field(text, name, range, expression)
+        invalid = ->(problem) { raise InvalidCronError, "#{expression.inspect}: #{name} #{problem}" }
+
+        text.split(",", -1).flat_map do |part|
+          match = PART.match(part) || invalid.call("#{part.inspect} isn't a number, range or step")
+          base, step = match.captures
+          invalid.call("#{part.inspect}: a step goes on * or a range (a-b/n)") if step && !base.match?(/[*-]/)
+          invalid.call("#{part.inspect}: the step is 0") if step&.to_i&.zero?
+
+          from, to = base == "*" ? range.minmax : base.split("-").map(&:to_i).then { |a, b| [a, b || a] }
+          [from, to].reject { |value| range.cover?(value) }.each do |value|
+            invalid.call("#{value} is out of range (#{range.min}-#{range.max})")
+          end
+          invalid.call("range #{part.inspect} runs backwards") if from > to
+
+          (from..to).step(step ? step.to_i : 1).to_a
+        end.uniq.sort.freeze
+      end
+      private_class_method :shortcut, :parse_field
+
+      def to_s = expression
+
+      # The latest occurrence at or before `time`, as a UTC Time on a whole
+      # minute. Steps field by field, so a yearly expression takes a handful
+      # of steps, not a year of minutes.
+      def previous(time)
+        time = minute_of(time)
+        limit = time.year - MAX_YEARS
+        loop do
+          raise InvalidCronError, "#{expression.inspect}: no occurrence found" if time.year < limit
+
+          time =
+            if !months.include?(time.month)
+              month = months.rfind { |m| m < time.month }
+              month ? end_of_month(time.year, month) : end_of_month(time.year - 1, months.last)
+            elsif !day?(time)
+              day_of(time) - MINUTE
+            elsif !hours.include?(time.hour)
+              hour = hours.rfind { |h| h < time.hour }
+              hour ? day_of(time) + (hour * HOUR) + (59 * MINUTE) : day_of(time) - MINUTE
+            elsif !minutes.include?(time.min)
+              minute = minutes.rfind { |m| m < time.min }
+              minute ? hour_of(time) + (minute * MINUTE) : hour_of(time) - MINUTE
+            else
+              return time
+            end
+        end
+      end
+
+      # The first occurrence after `time`, as a UTC Time on a whole minute.
+      def next_after(time)
+        time = minute_of(time) + MINUTE
+        limit = time.year + MAX_YEARS
+        loop do
+          raise InvalidCronError, "#{expression.inspect}: no occurrence found" if time.year > limit
+
+          time =
+            if !months.include?(time.month)
+              month = months.find { |m| m > time.month }
+              month ? Time.utc(time.year, month) : Time.utc(time.year + 1, months.first)
+            elsif !day?(time)
+              day_of(time) + DAY
+            elsif !hours.include?(time.hour)
+              hour = hours.find { |h| h > time.hour }
+              hour ? day_of(time) + (hour * HOUR) : day_of(time) + DAY
+            elsif !minutes.include?(time.min)
+              minute = minutes.find { |m| m > time.min }
+              minute ? hour_of(time) + (minute * MINUTE) : hour_of(time) + HOUR
+            else
+              return time
+            end
+        end
+      end
+
+      # A day of month on its own (day of week *) must exist in one of the
+      # months, or the expression never matches: `0 0 30 2 *`. With day of
+      # week restricted, some week always has a matching day.
+      def check_matches!
+        return unless any_weekday && !any_day
+        return if months.any? { |month| days.first <= MONTH_DAYS[month] }
+
+        raise InvalidCronError, "#{expression.inspect} never matches: none of its months has day #{days.first}"
+      end
+
+      private
+
+      def minute_of(time)
+        utc = time.getutc
+        Time.utc(utc.year, utc.month, utc.day, utc.hour, utc.min)
+      end
+
+      def day_of(time) = Time.utc(time.year, time.month, time.day)
+
+      def hour_of(time) = Time.utc(time.year, time.month, time.day, time.hour)
+
+      def end_of_month(year, month)
+        (month == 12 ? Time.utc(year + 1, 1, 1) : Time.utc(year, month + 1, 1)) - MINUTE
+      end
+
+      def day?(time)
+        in_month = days.include?(time.day)
+        in_week = weekdays.include?(time.wday)
+        any_day || any_weekday ? in_month && in_week : in_month || in_week
+      end
+    end
+  end
+end

data/lib/monk/jobs/errors.rb

@@ -6,6 +6,17 @@ module Monk
     class NotFrozenError < StandardError
     end
 
+    # Declaring a recurring task after Monk.freeze! has sealed the
+    # registry: it would never be seen by the scheduler.
+    class RegistryFrozenError < StandardError
+    end
+
+    # bin/jobs starting with recurring tasks declared but no
+    # monk_recurring_tasks table: an app that has jobs from before 0.22
+    # and hasn't added the migration yet.
+    class MissingRecurringTableError < StandardError
+    end
+
     # A job_class name that isn't a Monk::Job subclass this process knows
     # about: a job enqueued by a newer deploy, a renamed class, or a name
     # that was never a job at all.
@@ -21,9 +32,19 @@ module Monk
     class ClearOutsideTestsError < StandardError
     end
 
+    # Monk::Jobs.run_scheduler! outside MONK_ENV=test: it would fire a real
+    # app's schedules at a made-up time.
+    class RunSchedulerOutsideTestsError < StandardError
+    end
+
     # An ArgumentError, like Monk::Mail::InvalidMessageError: it's always
     # the caller's input that's wrong.
     class InvalidArgumentsError < ArgumentError
     end
+
+    # A recurring task's cron expression that doesn't parse, or never
+    # matches a minute. Raised when the task is declared, at boot.
+    class InvalidCronError < ArgumentError
+    end
   end
 end

data/lib/monk/jobs/firing.rb

@@ -0,0 +1,11 @@
+module Monk
+  module Jobs
+    # What one fire_recurring call did for a recurring task's occurrence
+    # (docs/history/plan-scheduled-jobs.md decision 5): result is :initialized,
+    # :enqueued, :skipped_pending, :already_handled, :not_due or
+    # :reinitialized; job_id is the enqueued job's, when there is one;
+    # previous_checkpoint is the task's checkpoint before the call (nil
+    # for a new task), for the "skipped N occurrences" log line.
+    Firing = Data.define(:result, :job_id, :previous_checkpoint)
+  end
+end

data/lib/monk/jobs/recurring_task.rb

@@ -0,0 +1,9 @@
+module Monk
+  module Jobs
+    # One declared schedule (Monk::Jobs.recurring): the key it's stored
+    # under in monk_recurring_tasks, the job class to enqueue, its parsed
+    # Cron and the args to enqueue with. Queue, priority and max_attempts
+    # come from the job class, as with any enqueue.
+    RecurringTask = Data.define(:key, :job_class, :cron, :args, :skip_if_pending)
+  end
+end

data/lib/monk/jobs/runtime.rb

@@ -1,6 +1,7 @@
 require "socket"
 require_relative "../jobs"
 require_relative "worker"
+require_relative "scheduler"
 
 module Monk
   module Jobs
@@ -53,6 +54,9 @@ module Monk
       def run(trap_signals: true)
         Monk.freeze!
         @adapter = Monk::Jobs.adapter
+        tasks = Monk::Jobs.recurring_tasks
+        check_recurring_table!(tasks)
+        @scheduler = Scheduler.new(@adapter, tasks)
         @hostname = Socket.gethostname
         @pid = Process.pid
         @process_id = @adapter.register_process(hostname: @hostname, pid: @pid)
@@ -65,7 +69,8 @@ module Monk
         @holding_port = Ractor::Port.new
         @worker_count.times { |index| spawn_worker(index) }
         Monk::Log.info(
-          "Monk::Jobs process #{@process_id} started: #{@worker_count} workers on #{@queues.join(", ")} (pid #{@pid})",
+          "Monk::Jobs process #{@process_id} started: #{@worker_count} workers on #{@queues.join(", ")}, " \
+          "#{tasks.size} recurring task#{"s" unless tasks.size == 1} (pid #{@pid})",
         )
 
         ticker, timer = start_ticker
@@ -104,10 +109,19 @@ module Monk
         end
       end
 
+      # The scheduler runs after the rest and under its own rescue, so an
+      # error that only it hits can't stop the heartbeat: other processes
+      # would take this one for dead.
+      def tick(last_heartbeat)
+        last_heartbeat = housekeeping(last_heartbeat)
+        schedule
+        last_heartbeat
+      end
+
       # A database error here (Postgres restarting, a dropped connection)
       # mustn't end the process: it's logged, this Ractor's connection is
       # reset, and the next tick tries again.
-      def tick(last_heartbeat)
+      def housekeeping(last_heartbeat)
         release_dead_workers_jobs
         @adapter.stage_due
         return last_heartbeat if monotonic - last_heartbeat < @heartbeat_interval
@@ -120,6 +134,28 @@ module Monk
         last_heartbeat
       end
 
+      # Recurring tasks (docs/history/plan-scheduled-jobs.md decision 1). An
+      # occurrence that errors isn't marked handled, so the next tick asks
+      # again.
+      def schedule
+        @scheduler.run
+      rescue StandardError => e
+        Monk::Log.error("Monk::Jobs scheduler: #{Monk::Jobs.describe_error(e)}; reconnecting")
+        reconnect
+      end
+
+      # Decision 9: a missing table is a deploy mistake, said once here
+      # rather than every second by the scheduler.
+      def check_recurring_table!(tasks)
+        return if tasks.empty? || @adapter.recurring_table?
+
+        raise MissingRecurringTableError,
+          "#{tasks.size} recurring task(s) declared (#{tasks.map(&:key).join(", ")}) but the database has no " \
+          "monk_recurring_tasks table. Add Monk's migration under a new timestamp in db/migrate/ " \
+          "(monk help jobs --file db/migrate/x_create_recurring_tables.up.sql, and .down.sql), then bin/migrate. " \
+          "The Monk 0.22 upgrade guide has the full steps"
+      end
+
       # A job stays on the list until its release has gone through (or found
       # the job no longer held), so a database error just retries it next tick.
       def release_dead_workers_jobs

data/lib/monk/jobs/scheduler.rb

@@ -0,0 +1,91 @@
+require "json"
+require_relative "../log"
+
+module Monk
+  module Jobs
+    # The supervisor's per-tick step for recurring tasks
+    # (docs/history/plan-scheduled-jobs.md decisions 5-7): asks the database about
+    # each task's most recent occurrence, which enqueues it at most once
+    # across every job process. Lives in the supervisor and isn't shared:
+    # the occurrence each task last handled is this process's own memory,
+    # so a tick reaches the database once per occurrence, not once a second.
+    class Scheduler
+      # Past this many, a catch-up log line stops counting.
+      MAX_SKIPPED_COUNT = 10_000
+
+      def initialize(adapter, tasks)
+        @adapter = adapter
+        @tasks = tasks
+        @handled = {} # task key => the occurrence last handled here
+      end
+
+      # One pass as if the clock read `now`. clock: replaces the database
+      # clock too (Monk::Jobs.run_scheduler!); without it, the database
+      # decides whether an occurrence has arrived. Returns each task asked
+      # about this pass, key => Firing#result.
+      def run(now = Time.now, clock: nil)
+        @tasks.each_with_object({}) do |task, results|
+          occurrence = task.cron.previous(now)
+          next if @handled[task.key] == occurrence
+
+          firing = fire(task, occurrence, clock)
+          @handled[task.key] = occurrence unless firing.result == :not_due
+          report(task, occurrence, firing)
+          results[task.key] = firing.result
+        end
+      end
+
+      private
+
+      def fire(task, occurrence, clock)
+        job = task.job_class
+        @adapter.fire_recurring(
+          key: task.key, cron: task.cron.expression, occurrence: occurrence, skip_if_pending: task.skip_if_pending,
+          job_class: job.name, queue: job.queue, priority: job.priority, max_attempts: job.max_attempts,
+          args: JSON.generate(task.args), clock: clock,
+        )
+      end
+
+      def report(task, occurrence, firing)
+        prefix = "Monk::Jobs recurring #{task.key}:"
+        case firing.result
+        when :initialized
+          Monk::Log.info("#{prefix} new task, first run at #{stamp(task.cron.next_after(occurrence))}")
+        when :reinitialized
+          Monk::Log.info("#{prefix} cron changed to #{task.cron.expression.inspect}, " \
+                         "first run at #{stamp(task.cron.next_after(occurrence))}")
+        when :enqueued
+          Monk::Log.info("#{prefix} enqueued job #{firing.job_id} for #{stamp(occurrence)}")
+        when :skipped_pending
+          Monk::Log.info("#{prefix} skipped #{stamp(occurrence)}, the previous run is still pending")
+        end
+        report_catch_up(task, occurrence, firing, prefix)
+      end
+
+      # Decision 6: after downtime only the latest occurrence fires.
+      def report_catch_up(task, occurrence, firing, prefix)
+        return unless %i[enqueued skipped_pending].include?(firing.result) && firing.previous_checkpoint
+
+        skipped = skipped_between(task.cron, firing.previous_checkpoint, occurrence)
+        return if skipped.zero?
+
+        count = skipped >= MAX_SKIPPED_COUNT ? "#{MAX_SKIPPED_COUNT}+" : skipped
+        Monk::Log.warn(
+          "#{prefix} caught up from #{stamp(firing.previous_checkpoint)}, skipped #{count} occurrences",
+        )
+      end
+
+      def skipped_between(cron, from, to)
+        count = 0
+        time = cron.next_after(from)
+        while time < to && count < MAX_SKIPPED_COUNT
+          count += 1
+          time = cron.next_after(time)
+        end
+        count
+      end
+
+      def stamp(time) = time.utc.iso8601
+    end
+  end
+end

data/lib/monk/jobs.rb

@@ -3,6 +3,9 @@
 require_relative "../monk"
 require_relative "jobs/errors"
 require_relative "jobs/args"
+require_relative "jobs/cron"
+require_relative "jobs/recurring_task"
+require_relative "jobs/scheduler"
 require "json"
 
 module Monk
@@ -53,7 +56,7 @@ module Monk
       #
       # SendReceipt.enqueue(order_id) is the same call.
       def enqueue(job_class, *args, wait: nil, at: nil, conn: nil)
-        check_enqueueable!(job_class)
+        check_enqueueable!(job_class, "Monk::Jobs.enqueue")
         Args.check!(args)
         check_schedule!(wait, at)
 
@@ -63,6 +66,51 @@ module Monk
         )
       end
 
+      # A job enqueued on a schedule by bin/jobs, typically in
+      # config/recurring.rb (loaded after app/jobs/, so the class exists):
+      #
+      #   Monk::Jobs.recurring "purge_sessions", PurgeExpiredSessions, cron: "0 3 * * *"
+      #   Monk::Jobs.recurring "weekly_digest", SendDigest, cron: "0 9 * * 1",
+      #     args: ["weekly"], skip_if_pending: true
+      #
+      # The key is the task's identity in monk_recurring_tasks, so renaming
+      # the job class keeps its place in the schedule. cron: is UTC (Cron).
+      # skip_if_pending: true skips an occurrence while the job enqueued for
+      # the previous one hasn't finished. Everything is checked here, so a
+      # mistake fails at boot (docs/history/plan-scheduled-jobs.md decision 2).
+      def recurring(key, job_class, cron:, args: [], skip_if_pending: false)
+        if @recurring_registry
+          raise RegistryFrozenError,
+            "Monk::Jobs.recurring(#{key.inspect}) after the job registry is frozen -- declare recurring " \
+            "tasks while the app loads (config/recurring.rb), before Monk.boot or bin/jobs starts"
+        end
+        unless key.is_a?(String) && !key.empty?
+          raise ArgumentError, "a recurring task's key must be a non-empty String, got #{key.inspect}"
+        end
+        if recurring_list.any? { |task| task.key == key }
+          raise ArgumentError, "recurring task #{key.inspect} is already declared"
+        end
+
+        check_enqueueable!(job_class, "Monk::Jobs.recurring")
+        Args.check!(args)
+        unless [true, false].include?(skip_if_pending)
+          raise ArgumentError, "skip_if_pending: must be true or false, got #{skip_if_pending.inspect}"
+        end
+
+        task = RecurringTask.new(
+          key: key.dup.freeze, job_class: job_class, cron: Cron.parse(cron),
+          args: Ractor.make_shareable(Marshal.load(Marshal.dump(args))), skip_if_pending: skip_if_pending,
+        )
+        recurring_list << task
+        task
+      end
+
+      # The declared recurring tasks, in declaration order. Once the
+      # registry is frozen, a shareable Array any Ractor can read.
+      def recurring_tasks
+        @recurring_registry || recurring_list.dup.freeze
+      end
+
       # Called by Monk::Job.inherited, in the main Ractor as the app's job
       # files load. Only recorded here: names are resolved when the
       # registry is frozen, so a class that gets its constant name after
@@ -94,6 +142,7 @@ module Monk
       # without a name a job can never be found again once enqueued.
       def freeze_registry!
         @registry = Ractor.make_shareable(classes.filter_map { |job| [job.name, job] if job.name }.to_h)
+        @recurring_registry = Ractor.make_shareable(recurring_list.dup)
       end
 
       # A failed job back to available, with its attempts reset; true if it
@@ -150,9 +199,32 @@ module Monk
         ran
       end
 
+      # Runs one scheduler pass as if the clock read `at`, for an app's
+      # tests of its recurring tasks; returns key => result (:initialized,
+      # :enqueued, ...). `at` stands in for the database clock as well, so
+      # it only runs with MONK_ENV=test. The first pass sets a task's
+      # checkpoint without enqueueing, as a deploy would:
+      #
+      #   Monk::Jobs.run_scheduler!(at: Time.utc(2026, 10, 12, 8, 59))
+      #   Monk::Jobs.run_scheduler!(at: Time.utc(2026, 10, 12, 9)) # => {"weekly_digest" => :enqueued}
+      #   Monk::Jobs.drain!
+      #
+      # Calls Monk.freeze! first, as bin/jobs does.
+      def run_scheduler!(at: Time.now)
+        unless Monk.env.test?
+          raise RunSchedulerOutsideTestsError,
+            "Monk::Jobs.run_scheduler! fires schedules at a made-up time, so it only runs with MONK_ENV=test " \
+            "(this is #{Monk.env})"
+        end
+
+        Monk.freeze!
+        Scheduler.new(adapter, recurring_tasks).run(at, clock: at)
+      end
+
       # Empties the queue: every job, failed ones included, and every job
-      # process row. For an app's tests, between one test and the next --
-      # and so it refuses to run unless MONK_ENV is test.
+      # process row, and every recurring task's checkpoint. For an app's
+      # tests, between one test and the next -- and so it refuses to run
+      # unless MONK_ENV is test.
       def clear!
         unless Monk.env.test?
           raise ClearOutsideTestsError,
@@ -162,12 +234,14 @@ module Monk
         adapter.clear!
       end
 
-      # Test-only: unfreezes the registry and forgets the configuration.
-      # Recorded classes stay recorded, the same way a Ruby class can't be
-      # undefined.
+      # Test-only: unfreezes the registry and forgets the configuration and
+      # the recurring tasks. Recorded classes stay recorded, the same way a
+      # Ruby class can't be undefined.
       def reset!
         @registry = nil
         @adapter = nil
+        @recurring_list = nil
+        @recurring_registry = nil
       end
 
       private
@@ -199,9 +273,9 @@ module Monk
         raise e.cause, cause: nil
       end
 
-      def check_enqueueable!(job_class)
+      def check_enqueueable!(job_class, caller_name)
         unless job_class.is_a?(Class) && job_class < Monk::Job
-          raise ArgumentError, "Monk::Jobs.enqueue needs a Monk::Job subclass, got #{job_class.inspect}"
+          raise ArgumentError, "#{caller_name} needs a Monk::Job subclass, got #{job_class.inspect}"
         end
         return if job_class.name
 
@@ -220,6 +294,10 @@ module Monk
       def classes
         @classes ||= []
       end
+
+      def recurring_list
+        @recurring_list ||= []
+      end
     end
 
     Monk.freeze_hooks << self
@@ -234,3 +312,4 @@ require_relative "jobs/job"
 # themselves (docs/adr/0017).
 require_relative "mail/deliver_later" if Monk.const_defined?(:Mail)
 require_relative "auth/send_login_link" if Monk.const_defined?(:Auth)
+require_relative "auth/sweep" if Monk.const_defined?(:Auth)

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/auth/agents.md

@@ -11,13 +11,20 @@
 `Monk::Auth.redeem(token)` returns a session or nil. In routes:
 `set_session_cookie(session)`, `current_subject` (nil when logged out),
 `require_user!` (halts 401), `require_csrf!`, `log_out!`. With jobs:
-`Monk::Auth::SendLoginLink.enqueue(email)`.
+`Monk::Auth::SendLoginLink.enqueue(email)`. Rate limit, in the login
+route before sending: `halt(429) unless Monk::Auth.allow_login_request?(email)`
+(one per address per `login_request_interval:`). `Monk::Auth.sweep!`
+deletes expired rows; with jobs, `Monk::Auth::Sweep` runs it nightly
+(`config/recurring.rb`).
 
 **Test:** `test/auth_test.rb` sends a link to `log/test.log` and redeems it.
+A test that asks for links calls `Monk::Auth.clear_login_requests!` in
+`teardown`, or its next request for the same address gets a 429.
 
 **Pitfalls:**
-- `/auth/request` needs a per-email rate limit before it goes live: without
-  one, anyone can make the app send mail to any address.
+- Keep `allow_login_request?` in `/auth/request`: without a rate limit,
+  anyone can make the app send mail to any address. It limits each
+  address, not a client asking for many.
 - Never point `deliver:` at `Monk::Mail.deliver_later`: the link, token
   included, would sit in the job queue. Use `SendLoginLink` instead.
 - Links come from `Monk::Settings[:public_url]`, never from request headers.

data/lib/monk/templates/auth/app/routes/auth.rb

@@ -3,14 +3,8 @@
 # its decisions: the rate limit, where to go after logging in, JSON or HTML.
 #
 # monk:example auth-routes -- log in by email link, log out, a page for logged-in users.
-# # Before going live: keep a rate limit (without one, anyone can make this
+# # Before going live: keep the rate limit (without one, anyone can make this
 # # app send mail to any address), and list your redirects in config/auth.rb.
-# module AuthRoutes
-#   # Per process and approximate: 5 links per address per 10 minutes. With
-#   # several bin/server processes, count in the database instead.
-#   LIMIT = Monk::Auth::RateLimiter.new(limit: 5, window: 600)
-# end
-#
 # class App
 #   get("/login") { @title = "Log in"; render "auth/login" }
 #
@@ -18,7 +12,9 @@
 #   post("/auth/request") do
 #     email = params[:email].to_s.strip.downcase
 #     halt(422) if email.empty?
-#     halt(429) if AuthRoutes::LIMIT.exceeded?(email)
+#     # One link per address per login_request_interval (config/auth.rb),
+#     # counted in the database, so across every bin/server process.
+#     halt(429) unless Monk::Auth.allow_login_request?(email)
 #
 #     # Sent here, in the request. With jobs, replace these two lines with
 #     # Monk::Auth::SendLoginLink.enqueue(email): the token is then made and

data/lib/monk/templates/auth/config/auth.rb

@@ -20,6 +20,7 @@ Monk::Auth.configure(
   session_ttl: 1_209_600,  # seconds a session stays valid (14 days)
   redirect_allowlist: [],  # paths request_login(redirect_to:) is allowed to target
   callback_path: "/auth/callback", # your route redeeming a token: GET "#{callback_path}/:token"
+  login_request_interval: 60, # seconds an address waits between login emails (allow_login_request?)
   secure: !Monk.env.development?, # Secure cookie flag; off in dev so plain-http testing works (Safari drops it)
   deliver: AuthMailer::MAGIC_LINK,
 )