monkrb 0.21.1 → 0.22.0

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/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,
 )

data/lib/monk/templates/auth/db/migrate/00000000000004_create_login_requests.down.sql

@@ -0,0 +1,2 @@
+DROP INDEX sessions_subject;
+DROP TABLE login_requests;

data/lib/monk/templates/auth/db/migrate/00000000000004_create_login_requests.up.sql

@@ -0,0 +1,16 @@
+-- Monk::Auth housekeeping (Monk 0.22): the login-email rate limit's table
+-- and an index for finding a person's sessions.
+
+-- One row per address: when a login link was last requested for it, for
+-- Monk::Auth.allow_login_request?. Checked in the login route, before the
+-- link is sent or enqueued: with jobs the login token only exists once the
+-- job runs, so login_tokens can't tell a request is already queued.
+-- Monk::Auth.sweep! deletes rows older than login_request_interval.
+CREATE TABLE login_requests (
+  email TEXT PRIMARY KEY, -- stripped and downcased
+  requested_at TIMESTAMPTZ NOT NULL DEFAULT now()
+);
+
+-- A person's sessions by subject: Monk::Auth.revoke_all, or who is online.
+-- An app that already has an index on sessions (subject) can drop this line.
+CREATE INDEX sessions_subject ON sessions (subject);

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

@@ -1,8 +1,9 @@
 ## auth
 
 Logging in by email link. `config/auth.rb` configures Monk::Auth,
-`app/mailers/auth_mailer.rb` sends the link through mail, and a migration
-creates the `login_tokens` and `sessions` tables: run `bin/setup_db` and
+`app/mailers/auth_mailer.rb` sends the link through mail, and two
+migrations create the `login_tokens`, `sessions` and `login_requests`
+tables: run `bin/setup_db` and
 `DB_NAME={{app}}_test bin/setup_db` (postgres, above).
 
 ### Before production
@@ -12,6 +13,17 @@ one in production's environment, e.g. from
 `ruby -rsecurerandom -e 'puts SecureRandom.hex(32)'`. `config/auth.rb`
 reads it with `ENV.fetch`: unset, the app doesn't boot.
 
+### Housekeeping
+
+- **Rate limit.** The login route allows one email per address per
+  minute (`login_request_interval:` in `config/auth.rb`), counted in
+  `login_requests`, so across every `bin/server` process. A limit across
+  addresses (per IP, say) is up to the app.
+- **Cleanup.** With jobs (`monk add jobs`), `bin/jobs` deletes expired
+  sessions and login tokens every night (`monk_auth_sweep` in
+  `config/recurring.rb`). Without jobs, run `Monk::Auth.sweep!` on a
+  schedule of your own.
+
 ### Check it works
 
 1. `bundle exec rake test` runs `test/auth_test.rb`: a link is sent (to
@@ -33,5 +45,6 @@ reads it with `ENV.fetch`: unset, the app doesn't boot.
      ```
 
      and `/me` answers `401` again.
-3. Before going live: keep the rate limit, and list in `config/auth.rb`
+3. Before going live: keep the rate limit (the `allow_login_request?`
+   line in `app/routes/auth.rb`), and list in `config/auth.rb`
    (`redirect_allowlist`) the paths a login may send the user back to.

data/lib/monk/templates/auth/test/auth_test.rb

@@ -4,6 +4,12 @@ require_relative "test_helper"
 # sent by config/auth.rb's deliver: (AuthMailer, to log/test.log here), and
 # redeemed into a session. SETUP.md, auth.
 class AuthTest < Minitest::Test
+  # Lifts the login-email rate limit, so the next test can ask for a link
+  # for the same address at once.
+  def teardown
+    Monk::Auth.clear_login_requests!
+  end
+
   def test_a_login_link_is_sent_and_redeems_into_a_session
     email = "login-check-#{rand(1_000_000)}@example.test"
     token = Monk::Auth.request_login(email)

data/lib/monk/templates/base/Gemfile

@@ -1,6 +1,6 @@
 source "https://rubygems.org"
 
-gem "monkrb", "~> 0.21", require: "monk"
+gem "monkrb", "~> 0.22", require: "monk"
 gem "rackup"
 gem "webrick"
 gem "kino"

data/lib/monk/templates/base/config/load.rb

@@ -25,6 +25,11 @@ end
   Dir[File.expand_path("../app/#{role}/**/*.rb", __dir__)].sort.each { |file| require file }
 end
 
+# With jobs (monk add jobs), the schedules of recurring jobs. Last, because
+# each one names a job class from app/jobs/.
+recurring = File.expand_path("recurring.rb", __dir__)
+require recurring if File.exist?(recurring)
+
 # With websocket (monk add websocket), every process that loads this file
 # can broadcast (bin/server, bin/jobs, bin/console, the tests), so its
 # transport is started here, once everything above has declared its

data/lib/monk/templates/jobs/agents.md

@@ -1,18 +1,25 @@
 ## jobs
 
 **Where:** `config/jobs.rb` (the queue lives in the `:primary` database),
-job classes in `app/jobs/`, `bin/jobs` runs them.
+job classes in `app/jobs/`, schedules in `config/recurring.rb`, `bin/jobs`
+runs them.
 
 **Main calls:** `class SendInvoice < Monk::Job` with
 `def self.perform(id)`; `SendInvoice.enqueue(id)`, `wait: 300`, `at: time`,
 or `conn: conn` to enqueue inside your own transaction. Class settings:
 `queue "mailers"`, `max_attempts 5`, `never_retry SomeError`. With mail:
 `Monk::Mail.deliver_later(...)`; with auth:
-`Monk::Auth::SendLoginLink.enqueue(email)`.
+`Monk::Auth::SendLoginLink.enqueue(email)`. Recurring, in
+`config/recurring.rb` only:
+`Monk::Jobs.recurring "key", JobClass, cron: "0 3 * * *", args: [...]`
+(`skip_if_pending: true` to skip while the last run is pending). With
+auth, `config/recurring.rb` already schedules `monk_auth_sweep`.
 
 **Test:** `test/jobs_test.rb`. In tests, `Monk::Jobs.drain!` runs every
 enqueued job right away, each in a Ractor; `Monk::Jobs.clear!` in
-`teardown` empties the queue.
+`teardown` empties the queue. `Monk::Jobs.run_scheduler!(at: time)` runs
+the schedules as if the clock read `time` (call it once to set the
+checkpoint, then at the next occurrence).
 
 **Pitfalls:**
 - A job's arguments are stored as JSON: pass ids and plain values, never
@@ -20,6 +27,10 @@ enqueued job right away, each in a Ractor; `Monk::Jobs.clear!` in
 - A job may run more than once (its process was killed mid-job): make it
   safe to repeat.
 - Jobs run in Ractors: the same shareability rules as routes.
+- Cron is UTC. A new recurring task first fires at its next occurrence,
+  not on deploy, and a missed run fires once, not once per occurrence
+  missed. Keep a task's key when renaming its class.
 
-**Examples:** `jobs-enqueue` in `app/routes/jobs.rb`; `app/jobs/hello_job.rb`
+**Examples:** `jobs-enqueue` in `app/routes/jobs.rb`, `jobs-recurring` in
+`config/recurring.rb`; `app/jobs/hello_job.rb`
 is a real, deletable demo job.

data/lib/monk/templates/jobs/config/recurring.rb

@@ -0,0 +1,21 @@
+# Recurring jobs: bin/jobs enqueues each one on its schedule, once per
+# occurrence however many job processes are running. Loaded after app/,
+# since each names a job class.
+#
+#   Monk::Jobs.recurring "<key>", JobClass, cron: "<expression>", args: [...]
+#
+# The key is the task's identity in the database: keep it when renaming
+# the class. cron: is a five-field cron expression (minute hour
+# day-of-month month day-of-week, or @hourly, @daily, ...), always in UTC.
+# A new task first runs at its next occurrence, not on deploy; after
+# downtime only the latest missed occurrence runs.
+# skip_if_pending: true skips an occurrence while the previous run hasn't
+# finished. Monk's docs/guides/jobs.md, "Recurring jobs".
+
+# With auth (monk add auth): deletes expired sessions and login tokens, and
+# old login requests, every night at 03:17 UTC.
+Monk::Jobs.recurring "monk_auth_sweep", Monk::Auth::Sweep, cron: "17 3 * * *" if defined?(Monk::Auth::Sweep)
+
+# monk:example jobs-recurring -- the demo job (app/jobs/hello_job.rb) at the top of every hour.
+# Monk::Jobs.recurring "hello_hourly", HelloJob, cron: "@hourly", args: ["cron"]
+# monk:end

data/lib/monk/templates/jobs/db/migrate/00000000000003_create_recurring_tables.down.sql

@@ -0,0 +1 @@
+DROP TABLE monk_recurring_tasks;

data/lib/monk/templates/jobs/db/migrate/00000000000003_create_recurring_tables.up.sql

@@ -0,0 +1,13 @@
+-- Monk::Jobs.recurring: one checkpoint row per declared task, the latest
+-- occurrence it has been handled for. Why this shape:
+-- docs/adr/0016-recurring-jobs-on-the-job-process-tick-with-a-checkpoint-row.md.
+CREATE TABLE monk_recurring_tasks (
+  key TEXT PRIMARY KEY, -- the key given to Monk::Jobs.recurring
+  cron TEXT NOT NULL, -- the expression the checkpoint was set under
+  last_occurrence_at TIMESTAMPTZ NOT NULL, -- the checkpoint
+  -- The job enqueued for the checkpoint, for skip_if_pending. No foreign
+  -- key: ON DELETE SET NULL would add a write to every job's finish, and
+  -- a dangling id just means that job is done.
+  last_job_id BIGINT,
+  updated_at TIMESTAMPTZ NOT NULL DEFAULT now()
+);

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

@@ -1,7 +1,7 @@
 ## jobs
 
-Background jobs on the app's own Postgres. A migration creates the queue's
-tables: run `bin/setup_db` and `DB_NAME={{app}}_test bin/setup_db`
+Background jobs on the app's own Postgres. Two migrations create the
+queue's tables and the recurring jobs' one: run `bin/setup_db` and `DB_NAME={{app}}_test bin/setup_db`
 (postgres, above).
 
 ### Run them
@@ -18,6 +18,19 @@ first. `TERM` or Ctrl-C lets the jobs in hand finish before it exits. In
 production it's one more process from the same image, with `bin/jobs` as
 its command.
 
+### Recurring jobs
+
+Declare schedules in `config/recurring.rb`:
+
+```ruby
+Monk::Jobs.recurring "purge_sessions", PurgeSessions, cron: "0 3 * * *"
+```
+
+Cron times are UTC. A running `bin/jobs` enqueues each occurrence once,
+however many are running; with none running, nothing fires, and on
+restart only the latest missed occurrence runs. A new task first runs at
+its next occurrence, not on deploy.
+
 ### Check it works
 
 1. `bundle exec rake test` runs `test/jobs_test.rb`, which enqueues the
@@ -28,3 +41,8 @@ its command.
 3. The example: uncomment the `jobs-enqueue` block in `app/routes/jobs.rb`,
    restart `bin/server`, and
    `curl -X POST "http://localhost:9292/jobs/hello?name=Bob"`.
+4. A recurring job, in a test: `Monk::Jobs.run_scheduler!(at: time)` runs
+   the schedule as if the clock read `time`. The first call only records
+   where the task is; a second call at the next occurrence enqueues it,
+   and `Monk::Jobs.drain!` runs it. The `jobs-recurring` example in
+   `config/recurring.rb` schedules the demo job every hour.

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.21.1".freeze
+  VERSION = "0.22.0".freeze
 end