monkrb 0.16.0 → 0.18.0

data/lib/monk/scaffold.rb

@@ -45,8 +45,52 @@ module Monk
       "config/auth.rb" => "auth/config/auth.rb",
       "db/migrate/00000000000001_create_auth_tables.up.sql" => "auth/db/migrate/00000000000001_create_auth_tables.up.sql",
       "db/migrate/00000000000001_create_auth_tables.down.sql" => "auth/db/migrate/00000000000001_create_auth_tables.down.sql",
+      # The magic link's HTML part -- config/auth.rb's AppMailer::DELIVER
+      # renders it and sends through Monk::Mail (MAIL_FILES, implied by --auth).
+      "views/mail/magic_link.erb" => "auth/views/mail/magic_link.erb",
     }.freeze
 
+    # --mail, or implied by --auth: Monk::Mail's config. Its Gemfile line
+    # (net-smtp) and MAIL_* env vars are added by #write! / #write_env_files!.
+    MAIL_FILES = {
+      "config/mail.rb" => "mail/config/mail.rb",
+    }.freeze
+
+    # --jobs: Monk::Jobs. The migration is the canonical one under
+    # templates/jobs/db/migrate -- the same file Monk's own tests apply --
+    # numbered after auth's so the two sort in order when both are present.
+    JOBS_FILES = {
+      "config/jobs.rb" => "jobs/config/jobs.rb",
+      "jobs/hello_job.rb" => "jobs/jobs/hello_job.rb",
+      "bin/jobs" => "jobs/bin/jobs",
+      "db/migrate/00000000000002_create_jobs_tables.up.sql" => "jobs/db/migrate/00000000000002_create_jobs_tables.up.sql",
+      "db/migrate/00000000000002_create_jobs_tables.down.sql" =>
+        "jobs/db/migrate/00000000000002_create_jobs_tables.down.sql",
+    }.freeze
+
+    # --auth --jobs: the magic link is created and sent inside a job, so the
+    # raw token is never stored (docs/adr/0014).
+    JOBS_AUTH_FILES = {
+      "jobs/send_login_link.rb" => "jobs/jobs/send_login_link.rb",
+    }.freeze
+
+    # --mail --jobs (or --auth --jobs): Monk::Mail.deliver_later, loaded in
+    # config/jobs.rb right after Monk::Jobs itself.
+    JOBS_REQUIRE_ANCHOR = %(require "monk/jobs"\n).freeze
+    JOBS_MAIL_REQUIRE = %(require "monk/mail/later"\n).freeze
+
+    # --jobs's demo route, added right after this line in config.ru (the
+    # base and the --live one both end their routes with it), so the
+    # round trip -- enqueue from a request, run in bin/jobs -- works out of
+    # the box.
+    JOBS_ROUTE_ANCHOR = %(  get("/api/hello") { json(message: "hello from monk") }\n).freeze
+    JOBS_ROUTE = <<~RUBY.gsub(/^(?!$)/, "  ").freeze
+
+      # Enqueues the demo job (jobs/hello_job.rb) for bin/jobs to run:
+      #   curl -X POST "http://localhost:9292/jobs/hello?name=Ann"
+      post("/jobs/hello") { json(enqueued: HelloJob.enqueue(params[:name] || "world")) }
+    RUBY
+
     # --live: Monk::Live's demo (a counter whose open tabs update when
     # another request changes it). These replace three base files outright
     # rather than patching them -- a live config.ru and index are different
@@ -80,7 +124,7 @@ module Monk
       <script type="module" src="<%= asset_path "/js/monk_live/monk_live.js" %>"></script>
     HTML
 
-    EXECUTABLE_FILES = %w[bin/server bin/websocket_server bin/console bin/setup_db bin/migrate].freeze
+    EXECUTABLE_FILES = %w[bin/server bin/websocket_server bin/console bin/setup_db bin/migrate bin/jobs].freeze
 
     # auth: implies postgres -- Monk::Auth is Postgres-only (lib/monk/auth.rb
     # subclasses Monk::Persistence::Pg::Model), so there's no combination
@@ -107,10 +151,19 @@ module Monk
     # implies --postgres) picks PgFanout; --live with neither raises.
     # See docs/design/live-pg-fanout.md / docs/history/plan-live-pg-fanout.md
     # for the design this decision comes from.
-    def initialize(dir, postgres: false, auth: false, redis: false, live: false)
+    #
+    # mail: Monk::Mail on its own, no Postgres needed. auth: implies it, the
+    # same way it implies postgres: a magic link has to reach someone.
+    #
+    # jobs: implies postgres, since the queue lives there, and nothing else.
+    def initialize(dir, postgres: false, auth: false, redis: false, live: false, mail: false, jobs: false)
       @dir = dir
+      # As passed, before anything is implied -- #summary reports the difference.
+      @requested = { postgres: postgres, auth: auth, mail: mail, jobs: jobs, redis: redis, live: live }
       @auth = auth
-      @postgres = postgres || auth
+      @jobs = jobs
+      @postgres = postgres || auth || jobs
+      @mail = mail || auth
       @live = live
 
       if @live
@@ -131,6 +184,29 @@ module Monk
       end
     end
 
+    # The flags as resolved, for `monk new` to print: which flags were
+    # given, which ones they implied and why, and which combinations change
+    # what gets generated. The rule behind it, stated in `monk --help`: a
+    # flag is implied when there's only one right answer (--auth can only
+    # use Postgres), and required when there's a real choice (--live's
+    # transport).
+    def summary
+      given = FLAG_ORDER.select { |flag| @requested[flag] }
+      return ["Flags: none (the base skeleton)."] if given.empty?
+
+      implied = implied_flags
+      flags = given.map { |flag| "--#{flag}" }.join(" ")
+      lines = implied.empty? ? ["Flags: #{flags}."] : ["Flags: #{flags}, which also turned on:"]
+      implied.each do |flag, sources|
+        lines << "  #{"--#{flag}".ljust(12)}(needed by #{sources.map { |source| "--#{source}" }.join(", ")})"
+      end
+
+      together = combinations
+      lines << "Together they also generate:" unless together.empty?
+      width = together.map { |pair, _| pair.length }.max
+      lines.concat(together.map { |pair, what| "  #{pair.ljust(width)}  #{what}" })
+    end
+
     def write!
       raise Monk::ScaffoldExistsError, "#{@dir} already exists" if File.exist?(@dir)
 
@@ -145,15 +221,27 @@ module Monk
         POSTGRES_FILES.each { |relative, template| write_file(relative, template, executable: EXECUTABLE_FILES.include?(relative)) }
         FileUtils.mkdir_p(File.join(@dir, "db/migrate"))
         append_gemfile_extra("postgres/Gemfile.extra")
-        wire_config_ru!
       end
 
+      if @mail
+        MAIL_FILES.each { |relative, template| write_file(relative, template) }
+        append_gemfile_extra("mail/Gemfile.extra")
+      end
+
+      if @jobs
+        JOBS_FILES.each { |relative, template| write_file(relative, template, executable: EXECUTABLE_FILES.include?(relative)) }
+        JOBS_AUTH_FILES.each { |relative, template| write_file(relative, template) } if @auth
+        add_jobs_route!
+        add_deliver_later! if @mail
+      end
+
+      wire_config_ru! if @postgres || @mail
       append_gemfile_extra("redis/Gemfile.extra") if @redis
 
-      # --postgres and --redis are the two flags with anything worth
-      # putting in an env file (a database, a REDIS_URL) -- the base
-      # skeleton alone has nothing to configure this way.
-      if @postgres || @redis
+      # --postgres, --redis and --mail are the flags with anything worth
+      # putting in an env file (a database, a REDIS_URL, MAIL_*) -- the
+      # base skeleton alone has nothing to configure this way.
+      if @postgres || @redis || @mail
         write_env_files!
         uncomment_dotenv!
       end
@@ -166,8 +254,42 @@ module Monk
       write_setup_md!
     end
 
+    FLAG_ORDER = %i[postgres auth mail jobs redis live].freeze
+
+    # Only these two imply anything, and only one flag each can need.
+    IMPLIED_BY = { postgres: %i[auth jobs], mail: %i[auth] }.freeze
+
     private
 
+    def implied_flags
+      resolved = { postgres: @postgres, mail: @mail }
+      IMPLIED_BY.filter_map do |flag, sources|
+        next if @requested[flag] || !resolved[flag]
+
+        [flag, sources.select { |source| @requested[source] }]
+      end
+    end
+
+    def combinations
+      pairs = []
+      pairs << ["--auth + --jobs", "jobs/send_login_link.rb: login links are sent from a job"] if @auth && @jobs
+      if @mail && @jobs
+        pairs << ["--mail + --jobs",
+                  "config/jobs.rb loads Monk::Mail.deliver_later; JOBS_QUEUES serves mailers first",]
+      end
+      pairs << live_combination if @live
+      pairs
+    end
+
+    def live_combination
+      if @live_transport == :redis
+        both = @postgres ? "; --redis wins over --postgres" : ""
+        ["--live + --redis", "config/live.rb fans out over Redis (Monk::WebSocket::RedisFanout#{both})"]
+      else
+        ["--live + --postgres", "config/live.rb fans out over Postgres (Monk::WebSocket::PgFanout)"]
+      end
+    end
+
     def write_live!
       write_file("config/live.rb", LIVE_CONFIG_TEMPLATES.fetch(@live_transport))
       LIVE_FILES.each { |relative, template| write_file(relative, template) }
@@ -224,12 +346,37 @@ module Monk
     def wire_config_ru!
       path = File.join(@dir, "config.ru")
       settings_require = %(require_relative "config/settings"\n)
-      target = @auth ? "config/auth" : "config/persistence" # config/auth.rb itself require_relative "persistence"
+      requires = +""
+      if @postgres
+        target = @auth ? "config/auth" : "config/persistence" # config/auth.rb itself require_relative "persistence"
+        requires << "require_relative \"#{target}\"\n"
+      end
+      # config/mail.rb from config.ru only, never from config/auth.rb:
+      # bin/websocket_server loads config/auth.rb too and never sends mail,
+      # so it shouldn't need MAIL_URL to boot.
+      requires << "require_relative \"config/mail\"\n" if @mail
+      requires << "require_relative \"config/jobs\"\n" if @jobs
 
       content = File.read(path)
       raise "config.ru wiring failed: #{settings_require.inspect} not found" unless content.include?(settings_require)
 
-      File.write(path, content.sub(settings_require, "#{settings_require}require_relative \"#{target}\"\n"))
+      File.write(path, content.sub(settings_require, "#{settings_require}#{requires}"))
+    end
+
+    def add_jobs_route!
+      path = File.join(@dir, "config.ru")
+      content = File.read(path)
+      raise "config.ru wiring failed: #{JOBS_ROUTE_ANCHOR.inspect} not found" unless content.include?(JOBS_ROUTE_ANCHOR)
+
+      File.write(path, content.sub(JOBS_ROUTE_ANCHOR, "#{JOBS_ROUTE_ANCHOR}#{JOBS_ROUTE}"))
+    end
+
+    def add_deliver_later!
+      path = File.join(@dir, "config/jobs.rb")
+      content = File.read(path)
+      raise "config/jobs.rb wiring failed: #{JOBS_REQUIRE_ANCHOR.inspect} not found" unless content.include?(JOBS_REQUIRE_ANCHOR)
+
+      File.write(path, content.sub(JOBS_REQUIRE_ANCHOR, "#{JOBS_REQUIRE_ANCHOR}#{JOBS_MAIL_REQUIRE}"))
     end
 
     # .env/.env.test/.env.example are the other deliberate exception to
@@ -252,6 +399,26 @@ module Monk
         example << "AUTH_SECRET=change-me"
       end
 
+      if @mail
+        # MAIL_URL is left out of .env on purpose: unset in development
+        # means log://, the message printed to the console. Tests boot
+        # outside development, where an unset one raises, hence log:// there.
+        dev << %(MAIL_FROM="#{app_name} <no-reply@localhost>")
+        test << "MAIL_URL=log://"
+        test << %(MAIL_FROM="#{app_name} <no-reply@localhost>")
+        example << "MAIL_URL=smtp://user:password@smtp.example.com:587"
+        example << %(MAIL_FROM="#{app_name} <no-reply@example.com>")
+      end
+
+      # bin/jobs's settings. Not in .env.test: tests run jobs with
+      # Monk::Jobs.drain!, never a job process.
+      # With mail, the mailers queue is served first, so a backlog of other
+      # work never delays a login email (docs/adr/0014).
+      if @jobs
+        queues = @mail ? "mailers,default" : "default"
+        [dev, example].each { |lines| lines.push("JOBS_WORKERS=2", "JOBS_QUEUES=#{queues}") }
+      end
+
       # REDIS_URL is deliberately absent from .env.test -- only a test that
       # actually exercises RedisFanout needs it, unlike DB_NAME/AUTH_SECRET
       # which every test touching persistence/auth needs.
@@ -393,7 +560,7 @@ module Monk
         bin/server              # HTTP app on :9292 -> http://localhost:9292/hello
         bin/websocket_server    # WS chat process on :9293, in another terminal
         ```
-        #{redis_only_note}
+        #{redis_only_note}#{mail_setup_note}
         ## Test environment
 
         `monk new` scaffolds no test framework at all -- this is the minimum to
@@ -415,9 +582,9 @@ module Monk
         $LOAD_PATH.unshift(File.expand_path("..", __dir__))
 
         ENV["MONK_ENV"] ||= "test"
-
+        #{base_test_dotenv_lines}
         require "minitest/autorun"
-        require_relative "../config/settings"
+        require_relative "../config/settings"#{%(\nrequire_relative "../config/mail") if @mail}
         ```
 
         **Rakefile**:
@@ -552,8 +719,8 @@ module Monk
         ```bash
         bin/server              # HTTP app on :9292
         bin/websocket_server    # WS chat process on :9293, in another terminal
-        ```
-        #{auth_or_redis_confirmation_note}
+        #{"bin/jobs                # background jobs (jobs/), in a third terminal\n" if @jobs}```
+        #{auth_or_redis_confirmation_note}#{mail_setup_note}#{jobs_setup_note}
         ## Test environment
 
         ### 1. Create the test database
@@ -600,7 +767,7 @@ module Monk
 
         require "minitest/autorun"
         require_relative "../config/settings"
-        require_relative "../config/#{@auth ? "auth" : "persistence"}"
+        require_relative "../config/#{@auth ? "auth" : "persistence"}"#{%(\nrequire_relative "../config/mail") if @mail}#{%(\nrequire_relative "../config/jobs") if @jobs}
         ```
 
         **Rakefile**:
@@ -626,7 +793,7 @@ module Monk
         #{sample_test_body}
         end
         ```
-
+        #{jobs_test_sample}
         Then:
 
         ```bash
@@ -657,6 +824,137 @@ module Monk
         "#{visible} visible to it -- that confirms everything's actually wired up.\n"
     end
 
+    # Interpolated into a squiggly heredoc, so no leading indentation of
+    # its own (interpolated text isn't dedented).
+    def mail_setup_note
+      return "" unless @mail
+
+      <<~MARKDOWN
+
+        ### Email
+
+        `config/mail.rb` configures `Monk::Mail`; send with
+        `Monk::Mail.deliver(to:, subject:, text:, html:)`.#{auth_mail_sentence} In
+        development `MAIL_URL` is unset, so messages are printed to the
+        console instead of sent. Outside
+        development set `MAIL_URL` (e.g. `smtp://user:pass@smtp.provider.com:587`)
+        and `MAIL_FROM` to a sender on a domain you've verified with your
+        provider -- an unset `MAIL_URL` fails the boot there. Provider
+        examples: `docs/guides/mail.md` in the monk repo.
+      MARKDOWN
+    end
+
+    # Interpolated into a squiggly heredoc, so no indentation of its own.
+    def jobs_setup_note
+      return "" unless @jobs
+
+      <<~MARKDOWN
+
+        ### Background jobs
+
+        `config/jobs.rb` configures `Monk::Jobs` on the app's own database --
+        its tables come from `db/migrate/00000000000002_create_jobs_tables`,
+        which `bin/setup_db` already applied -- and loads the job classes in
+        `jobs/`. With `bin/server` and `bin/jobs` both running, enqueue the
+        demo job and watch it run:
+
+        ```bash
+        curl -X POST "http://localhost:9292/jobs/hello?name=Ann"
+        tail -f log/development.log   # ... INFO Hello, Ann, from a background job
+        ```
+
+        `JOBS_WORKERS` and `JOBS_QUEUES` (in `.env`) set how many worker Ractors
+        `bin/jobs` runs and which queues they take jobs from, in order. A job
+        may run more than once (its process was killed mid-job, say), so make
+        each one safe to repeat. `TERM` or Ctrl-C lets the jobs in hand finish
+        before `bin/jobs` exits.#{jobs_mail_note}#{jobs_auth_note}
+      MARKDOWN
+    end
+
+    # Interpolated into a squiggly heredoc, so no indentation of its own.
+    def jobs_mail_note
+      return "" unless @mail
+
+      <<~MARKDOWN.chomp
+
+        To send an email from a job instead of the request, use
+        `Monk::Mail.deliver_later` -- the same arguments as `deliver` (render
+        HTML first with `Monk::Mail.render`), plus `wait:`/`at:`, or `conn:`
+        to enqueue inside your own transaction. It goes on the `mailers`
+        queue, which `JOBS_QUEUES` serves first. Temporary failures are
+        retried; a refusal the mail server made final is not.
+      MARKDOWN
+    end
+
+    # Interpolated into a squiggly heredoc, so no indentation of its own.
+    def jobs_auth_note
+      return "" unless @auth
+
+      <<~MARKDOWN.chomp
+
+        Magic links go through a job too, `jobs/send_login_link.rb`: it
+        creates the token and sends the link inside the job, so the raw
+        token is never stored, not even in the queue. Your login route,
+        after its own per-email rate limit, just enqueues it:
+
+        ```ruby
+        post("/auth/request") do
+          SendLoginLink.enqueue(params[:email])
+          json(sent: true)
+        end
+        ```
+
+        Don't point `config/auth.rb`'s `deliver:` at `deliver_later`: that
+        would store the link, token included, in the queue until it's sent.
+      MARKDOWN
+    end
+
+    # Interpolated into a squiggly heredoc, so no indentation of its own.
+    def jobs_test_sample
+      return "" unless @jobs
+
+      <<~MARKDOWN
+
+        **test/jobs_test.rb** -- `Monk::Jobs.drain!` runs every enqueued job
+        right in the test (each in its own Ractor, as `bin/jobs` would, so a
+        job that only works outside one fails here too), and
+        `Monk::Jobs.clear!` empties the queue between tests:
+
+        ```ruby
+        require_relative "test_helper"
+
+        class JobsTest < Minitest::Test
+          def teardown
+            Monk::Jobs.clear!
+          end
+
+          def test_the_demo_job_runs
+            HelloJob.enqueue("test")
+
+            assert_equal 1, Monk::Jobs.drain!
+          end
+        end
+        ```
+      MARKDOWN
+    end
+
+    # The no-Postgres test helper normally has nothing to load from
+    # .env.test -- but with --mail it has MAIL_URL=log://, which tests need:
+    # they boot outside development, where an unset MAIL_URL raises.
+    # Interpolated into a squiggly heredoc, so no indentation of its own.
+    def base_test_dotenv_lines
+      return "" unless @mail
+
+      %(\nrequire "dotenv"\nDotenv.load(File.expand_path(".env.test", __dir__ + "/.."))\n)
+    end
+
+    def auth_mail_sentence
+      return "" unless @auth
+
+      " `config/auth.rb`'s `AppMailer::DELIVER` sends each login link through it " \
+        "(HTML part: `views/mail/magic_link.erb`)."
+    end
+
     def sample_test_body
       if @auth
         <<~RUBY.chomp.gsub(/^/, "  ")
@@ -671,7 +969,7 @@ module Monk
         <<~RUBY.chomp.gsub(/^/, "  ")
           def test_connects_to_the_test_database
             Monk::Persistence::Pg.checkout(:primary) do |conn|
-              assert_equal "1", conn.exec("SELECT 1").getvalue(0, 0)
+              assert_equal 1, conn.exec("SELECT 1").getvalue(0, 0)
             end
           end
         RUBY

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

@@ -7,14 +7,24 @@ require_relative "persistence"
 # "#{Monk::Settings[:public_url]}/auth/callback/#{token}"), see its comment
 # there and auth.md's "Sending the magic link".
 
-# Sends the magic link once you have real delivery (email, SMS, ...) --
-# a module constant, not a lambda inline in Auth.configure below, since
-# self at this file's top level isn't Ractor-shareable (same constraint as
-# Monk::Live.authorize blocks). Until this is wired up for real,
-# Monk::Auth.deliver_link falls back to Monk::Auth.log_dev_link in
-# development and raises everywhere else -- see docs/guides/auth.md.
+# Sends the magic link by email, through Monk::Mail (config/mail.rb, which
+# config.ru requires) -- a module constant, not a lambda inline in
+# Auth.configure below, since self at this file's top level isn't
+# Ractor-shareable (same constraint as Monk::Live.authorize blocks). The
+# HTML part is views/mail/magic_link.erb. Swap the body for SMS or any
+# other channel; see docs/guides/auth.md.
 module AppMailer
-  # DELIVER = ->(email:, link:, token:) { YourMailer.magic_link(email, link) }
+  DELIVER = lambda do |email:, link:, token:|
+    # Development only (a no-op elsewhere): the link on the console, plus a
+    # QR code for a phone if rqrcode is in the Gemfile.
+    Monk::Auth.log_dev_link(link, subject: email)
+    Monk::Mail.deliver(
+      to: email,
+      subject: "Your login link",
+      text: "Here's your login link:\n\n#{link}\n\nIf you didn't ask for it, you can ignore this email.",
+      html: Monk::Mail.render("mail/magic_link", link: link),
+    )
+  end
 end
 
 Monk::Auth.configure(
@@ -24,5 +34,5 @@ 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
   secure: !Monk.env.development?, # Secure cookie flag; off in dev so plain-http testing works (Safari drops it)
-  # deliver: AppMailer::DELIVER,
+  deliver: AppMailer::DELIVER,
 )

data/lib/monk/templates/auth/views/mail/magic_link.erb

@@ -0,0 +1,3 @@
+<p>Here's your login link:</p>
+<p><a href="<%= locals[:link] %>">Log in</a></p>
+<p>If you didn't ask for it, you can ignore this email.</p>

data/lib/monk/templates/jobs/bin/jobs

@@ -0,0 +1,26 @@
+#!/usr/bin/env ruby
+require "bundler/setup"
+require_relative "../config/settings"
+
+# Loaded when this app has them, so jobs can send mail or use Monk::Auth --
+# a missing file is a harmless no-op, the same way bin/websocket_server
+# treats config/auth.rb.
+%w[mail auth].each do |name|
+  require_relative "../config/#{name}"
+rescue LoadError
+  nil
+end
+
+require_relative "../config/jobs"
+require "monk/jobs/runtime"
+
+# The app's templates, so a job can render one (a mail's HTML part, say):
+# there's no App class here to point Monk::Views at them.
+Monk::Views.root = File.expand_path("../views", __dir__)
+
+workers = Integer(ENV.fetch("JOBS_WORKERS", "5"))
+queues = ENV.fetch("JOBS_QUEUES", "default").split(",").map(&:strip)
+puts "Monk::Jobs: #{workers} worker(s) on #{queues.join(", ")} -- TERM or Ctrl-C finishes the jobs in hand and stops"
+$stdout.flush
+
+Monk::Jobs::Runtime.new(workers: workers, queues: queues).run

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

@@ -0,0 +1,17 @@
+require "monk"
+require "monk/jobs"
+require_relative "persistence"
+
+# Background jobs (Monk::Jobs): enqueue from any route, e.g.
+# HelloJob.enqueue("world"); bin/jobs runs them. Every job is a class under
+# jobs/, loaded below so the web process can enqueue it and bin/jobs can
+# run it.
+#
+# The queue lives in the app's own database, so a job can be enqueued
+# inside the app's own transaction: HelloJob.enqueue("world", conn: conn).
+# Once the app has long-running transactions or heavy load, give the queue
+# a database of its own -- register it in config/persistence.rb and pass
+# its name here (Monk's docs/guides/jobs.md, "Keeping the queue healthy").
+Monk::Jobs.configure(db_name: :primary)
+
+Dir[File.expand_path("../jobs/*.rb", __dir__)].sort.each { |file| require file }

data/lib/monk/templates/jobs/db/migrate/00000000000002_create_jobs_tables.down.sql

@@ -0,0 +1,3 @@
+DROP TABLE monk_processes;
+DROP TABLE monk_job_payloads;
+DROP TABLE monk_jobs;

data/lib/monk/templates/jobs/db/migrate/00000000000002_create_jobs_tables.up.sql

@@ -0,0 +1,48 @@
+-- Monk::Jobs: a narrow state table, a payload table, one row per job
+-- process. Why this shape: docs/adr/0013-jobs-narrow-state-table-plus-payloads.md.
+
+-- Scheduling and state only, about 70 bytes a row: claiming a job
+-- rewrites this row, never the payload.
+CREATE TABLE monk_jobs (
+  id BIGINT GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
+  queue TEXT NOT NULL DEFAULT 'default',
+  priority SMALLINT NOT NULL DEFAULT 0, -- lower runs sooner
+  state TEXT NOT NULL CHECK (state IN ('available', 'scheduled', 'running', 'failed')),
+  run_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+  attempts SMALLINT NOT NULL DEFAULT 0,
+  max_attempts SMALLINT NOT NULL DEFAULT 5,
+  locked_by BIGINT, -- monk_processes.id while running
+  locked_at TIMESTAMPTZ
+);
+
+-- One partial index per lookup, each holding only the rows it wants:
+-- workers claim from the first, the stager promotes due jobs from the
+-- second, pruning a dead process finds its jobs through the third.
+CREATE INDEX monk_jobs_available ON monk_jobs (queue, priority, run_at, id) WHERE state = 'available';
+CREATE INDEX monk_jobs_scheduled ON monk_jobs (run_at) WHERE state = 'scheduled';
+CREATE INDEX monk_jobs_running ON monk_jobs (locked_by) WHERE state = 'running';
+
+-- Every job's row is updated and deleted within seconds, so vacuum it
+-- sooner than Postgres's defaults would (1% of rows dead rather than 20%,
+-- and without cost-based throttling).
+ALTER TABLE monk_jobs SET (autovacuum_vacuum_scale_factor = 0.01, autovacuum_vacuum_cost_delay = 0);
+
+-- Written once at enqueue, deleted with its job, updated only to record
+-- an error.
+CREATE TABLE monk_job_payloads (
+  job_id BIGINT PRIMARY KEY REFERENCES monk_jobs (id) ON DELETE CASCADE,
+  job_class TEXT NOT NULL,
+  args JSONB NOT NULL,
+  last_error TEXT,
+  created_at TIMESTAMPTZ NOT NULL DEFAULT now()
+);
+
+-- One row per bin/jobs process: a heartbeat that stops means its
+-- running jobs go back to available.
+CREATE TABLE monk_processes (
+  id BIGINT GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
+  hostname TEXT NOT NULL,
+  pid INTEGER NOT NULL,
+  started_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+  last_heartbeat_at TIMESTAMPTZ NOT NULL DEFAULT now()
+);

data/lib/monk/templates/jobs/jobs/hello_job.rb

@@ -0,0 +1,9 @@
+# The demo job: POST /jobs/hello enqueues it, bin/jobs runs it, and its
+# line lands in log/<env>.log. A job's args must be plain JSON values (an
+# id, not a record), and a job may run more than once, so make it safe to
+# repeat. Replace this with the app's own jobs.
+class HelloJob < Monk::Job
+  def self.perform(name)
+    Monk::Log.info("Hello, #{name}, from a background job")
+  end
+end

data/lib/monk/templates/jobs/jobs/send_login_link.rb

@@ -0,0 +1,27 @@
+# Sends a magic link from bin/jobs instead of the login request. The token
+# is created here, right before it's sent, so the raw token is never
+# stored anywhere -- not even in the job queue, which a plain
+# Monk::Mail.deliver_later of the link would do (Monk's
+# docs/adr/0014-mail-from-jobs-and-login-links-created-in-the-job.md).
+# Enqueue it from your login route, after your own per-email rate limit
+# and with a redirect_to already checked against redirect_allowlist:
+#
+#   post("/auth/request") do
+#     SendLoginLink.enqueue(params[:email])
+#     json(sent: true)
+#   end
+class SendLoginLink < Monk::Job
+  queue "mailers"
+  # About 50 seconds of retries: a login email minutes late, after the
+  # user has likely asked for another, is worse than none.
+  max_attempts 3
+  never_retry Monk::InvalidRedirectError
+
+  def self.perform(email, redirect_to = nil)
+    token = Monk::Auth.request_login(email, redirect_to: redirect_to)
+    # Your callback route; config/settings.rb's public_url is the origin.
+    link = "#{Monk::Settings[:public_url]}/auth/callback/#{token}"
+    # Calls config/auth.rb's deliver: -- a synchronous send, here in the job.
+    Monk::Auth.deliver_link(email: email, link: link, token: token)
+  end
+end

data/lib/monk/templates/mail/Gemfile.extra

@@ -0,0 +1 @@
+gem "net-smtp" # Monk::Mail's smtp:// transport (config/mail.rb)

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

@@ -0,0 +1,19 @@
+require "monk"
+require "monk/mail"
+
+# Sends email with Monk::Mail.deliver(to:, subject:, text:, html:) from
+# any route -- and, with --auth, the magic links config/auth.rb's AppMailer
+# delivers. See docs/guides/mail.md. Required from config.ru (not from
+# config/auth.rb: bin/websocket_server loads that too, and never sends mail).
+Monk::Settings.configure do
+  # Where mail goes. Unset in development means log:// (printed to the
+  # console, nothing sent); anywhere else an unset one fails the boot.
+  # e.g. smtp://user:pass@smtp.provider.com:587 or smtp://localhost:25,
+  # provider examples in docs/guides/mail.md.
+  optional :mail_url, default: ""
+  # The sender of every message, e.g. "My App <no-reply@myapp.com>" --
+  # a domain you've verified with your mail provider (SPF, DKIM).
+  optional :mail_from, default: "App <no-reply@localhost>"
+end
+
+Monk::Mail.configure(url: Monk::Settings[:mail_url], from: Monk::Settings[:mail_from])

data/lib/monk/templates/postgres/Dockerfile

@@ -25,6 +25,8 @@ COPY . .
 # platform that assigns its own). bin/websocket_server (WS_PORT default
 # 9293) is a separate process/deploy unit -- run this same image with
 # `bin/websocket_server` as the command instead of publishing another
-# port from this Dockerfile -- see docs/guides/deploying.md.
+# port from this Dockerfile -- see docs/guides/deploying.md. With --jobs,
+# bin/jobs is another one, the same way: this image, `bin/jobs` as the
+# command, no port at all.
 EXPOSE 9292
 CMD ["bin/server", "--bind", "0.0.0.0"]