monkrb 0.16.0 → 0.17.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7e6286fdc2af1003d176142f6d7b7410c1f924f78466f28ff1bd4b95709c6230
-  data.tar.gz: 1c5030467a67e80f57e4f10ad939c06392d5d80cff0cc732692589f207173a66
+  metadata.gz: b983d19c7b6de8509f55f50c796d00d90c2d5d345cbe2a9e0f30e8f1349fe7be
+  data.tar.gz: 0fc9a16f56f69aafd1f3937268d337054399c7de34dd1a9a4986d3a6ae3e1bd5
 SHA512:
-  metadata.gz: 204709f8e01de1f7d13e3223daff2a875979b1fd93ed5fa51663e5750f1fab6046f3ac9827712204864d2d6f50b309088f2262fa66533715b0ab486e33e330e5
-  data.tar.gz: 727e5d900941e860ae491bff2e7042a4d9ac7be13131707435361aca990021cc8fcd4b580421bfe10b0ebbe7c12430f461629449b18f49098437fa17097d72ad
+  metadata.gz: 582398dd16f93f3d352ed51edfb79904a0e494c98daba3230abce233901b468a5e482d5fa97dfe29832293d79e85e340a491d5899cda327a298b120108008f1a
+  data.tar.gz: 1bde7799803407e6b41c52040e6fa3893a4fd8c2ebb9cca5324cfeb6a1ac291b8a5eaabd7f591204c835179985d14887b009610ebab82f650a6b3d528355f901

data/CHANGELOG.md

@@ -4,6 +4,41 @@ 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.17.0 - 2026-09-26
+
+### Added
+
+- `Monk::Mail` (`require "monk/mail"`): text and/or HTML email, sent
+  synchronously from inside whichever worker Ractor serves the request.
+  The `mail` gem, and so Action Mailer, raises `Ractor::IsolationError`
+  there, so Monk builds the MIME itself: multipart/alternative, UTF-8,
+  base64 bodies, RFC 2047 headers, and header-injection checks on every
+  address and subject. `Monk::Mail.configure(url:, from:)` takes one
+  `MAIL_URL` (`smtp://`, `smtps://` or `log://`), parsed and sealed at
+  boot; an unset one means `log://` in development and a boot error
+  elsewhere. `Monk::Mail.deliver(to:, subject:, text:, html:, ...)` sends.
+  SMTP needs the app's own `gem "net-smtp"`. No attachments, inline
+  images or bulk sending. See `docs/guides/mail.md` and ADR 0012, which
+  reverses the earlier "email stays outside the framework" decision.
+- `Monk::Mail.render(template, **locals)`: renders a view (e.g.
+  `views/mail/magic_link.erb`) to the `html:` String, locals only, no page
+  layout, callable from any worker Ractor after boot.
+
+- `monk new --mail`: scaffolds `Monk::Mail` on its own, no Postgres needed:
+  `config/mail.rb` (required by `config.ru`), `gem "net-smtp"`, `MAIL_FROM`
+  in the env files, `MAIL_URL=log://` in `.env.test`, and a SETUP.md whose
+  test helper loads `.env.test` before `config/mail`.
+
+### Changed
+
+- **`monk new --auth` now sends the magic link by email**, and implies
+  `--mail` the same way it implies `--postgres`. On top of `--mail` it
+  adds `views/mail/magic_link.erb` and a working `AppMailer::DELIVER` wired into
+  `config/auth.rb`'s `deliver:`. `.env.test` sets `MAIL_URL=log://`; in
+  development an unset `MAIL_URL` prints the message to the console
+  (`log_dev_link`'s line and QR code still appear); elsewhere it must be
+  set, or the boot fails.
+
 ## 0.16.0 - 2026-09-24
 
 ### Added

data/README.md

@@ -60,6 +60,7 @@ Everything beyond the core is opt-in (`require "monk"` alone loads none of it).
 | 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) |
+| Email | `Monk::Mail`: text/HTML email over SMTP or a local relay, one `MAIL_URL`, sent from any worker Ractor | `require "monk/mail"`; SMTP needs the `net-smtp` gem | [`mail.md`](docs/guides/mail.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 its flags; retrofitting Postgres, Auth or Redis | — (the `monk` command; flags `--postgres`, `--auth`, `--redis`, `--live`) | [`scaffolding.md`](docs/guides/scaffolding.md) |

data/exe/monk

@@ -1,7 +1,7 @@
 #!/usr/bin/env ruby
 require_relative "../lib/monk/scaffold"
 
-USAGE = "Usage: monk new APP_NAME [--postgres] [--auth] [--redis] [--live]".freeze
+USAGE = "Usage: monk new APP_NAME [--postgres] [--auth] [--mail] [--redis] [--live]".freeze
 
 HELP = <<~TEXT.freeze
   #{USAGE}
@@ -41,7 +41,18 @@ HELP = <<~TEXT.freeze
                        requires config/auth instead of config/persistence
                        (config/auth.rb itself requires persistence), and
                        .env/.env.test/.env.example get an AUTH_SECRET line.
-      --redis         Add the redis gem to the Gemfile, for
+                       Also implies --mail, below: config/auth.rb sends the
+                       magic link through Monk::Mail, with an HTML part in
+                       views/mail/magic_link.erb.
+      --mail          Also scaffold Monk::Mail (text/HTML email over SMTP),
+                       no Postgres needed: config/mail.rb, required by
+                       config.ru, plus gem "net-smtp" in the Gemfile.
+                       .env/.env.test/.env.example get MAIL_FROM, and
+                       MAIL_URL where it matters: log:// in .env.test, an
+                       smtp:// placeholder in .env.example. Unset in
+                       development, MAIL_URL means log:// (messages printed,
+                       not sent); anywhere else it must be set.
+      --redis        Add the redis gem to the Gemfile, for
                        bin/websocket_server's cross-process fan-out. Fully
                        independent -- doesn't imply, and isn't implied by,
                        --postgres or --auth. Writes/extends .env and
@@ -109,15 +120,19 @@ when "new"
   usage_error! if app_name.nil?
 
   auth = rest.include?("--auth")
+  mail = rest.include?("--mail") || auth
   redis = rest.include?("--redis")
   live = rest.include?("--live")
-  Monk::Scaffold.new(app_name, postgres: rest.include?("--postgres"), auth: auth, redis: redis, live: live).write!
+  Monk::Scaffold.new(
+    app_name, postgres: rest.include?("--postgres"), auth: auth, mail: mail, redis: redis, live: live,
+  ).write!
 
   puts "Created #{app_name}. Next steps:"
   puts "  cd #{app_name}"
   puts "  bundle install"
   puts "  see SETUP.md for the full dev-then-test walkthrough"
   puts "  change the placeholder AUTH_SECRET in .env/.env.test before relying on it" if auth
+  puts "  set MAIL_URL and MAIL_FROM outside development (see config/mail.rb)" if mail
   if live
     if redis
       puts "  Monk::Live needs Redis running, bin/server and bin/websocket_server (see SETUP.md)"

data/lib/monk/auth.rb

@@ -90,9 +90,9 @@ module Monk
       # (see below), and raises everywhere else: a silent no-op here would
       # mean an app that forgot to wire delivery finds out only when a
       # user reports never receiving their link, in production, which is
-      # the wrong place to fail (docs/design/auth-sessions.md's "Email
-      # delivery stays outside the framework" -- Monk still needs to know
-      # it was told to send *something*).
+      # the wrong place to fail. deliver: stays a plain callable even now
+      # that Monk::Mail exists (docs/adr/0012-minimal-built-in-mailer.md):
+      # it's usually a one-line Monk::Mail.deliver, but can be any channel.
       #
       # `link` is the app's own job to build (Monk doesn't own routing, so
       # it can't know the callback path) -- from a trusted origin, e.g.

data/lib/monk/mail/address.rb

@@ -0,0 +1,41 @@
+module Monk
+  module Mail
+    # Just enough address handling for what Monk::Mail sends: split
+    # "Name <addr>" into its parts, and render one back into a header
+    # value. Not an RFC 5322 parser -- groups, comments and quoted local
+    # parts are out of scope (docs/adr/0012-minimal-built-in-mailer.md).
+    module Address
+      ANGLE = /\A\s*(.*?)\s*<([^<>]*)>\s*\z/
+      # A display name made only of these goes out as-is; anything else
+      # ASCII gets quoted, so a comma in "Doe, John" can't split one
+      # recipient into two.
+      PLAIN_PHRASE = %r{\A[A-Za-z0-9!#$%&'*+\-/=?^_`{|}~ ]+\z}
+
+      module_function
+
+      # "App <a@app.test>" -> ["App", "a@app.test"]; "a@app.test" -> [nil, "a@app.test"]
+      def split(value)
+        match = ANGLE.match(value)
+        return [nil, value.strip] unless match
+
+        name = match[1]
+        [name.empty? ? nil : name, match[2].strip]
+      end
+
+      def bare(value) = split(value).last
+
+      def header(value)
+        name, address = split(value)
+        name ? "#{phrase(name)} <#{address}>" : address
+      end
+
+      def phrase(name)
+        return name if name.length >= 2 && name.start_with?('"') && name.end_with?('"')
+        return MIME.encode_words(name) unless name.ascii_only?
+        return name if name.match?(PLAIN_PHRASE)
+
+        %("#{name.gsub(/["\\]/) { |char| "\\#{char}" }}")
+      end
+    end
+  end
+end

data/lib/monk/mail/errors.rb

@@ -0,0 +1,28 @@
+module Monk
+  module Mail
+    # An ArgumentError: it's always the caller's input that's wrong, never
+    # the transport or the network.
+    class InvalidMessageError < ArgumentError
+    end
+
+    class InvalidMailUrlError < StandardError
+    end
+
+    class MissingMailUrlError < StandardError
+    end
+
+    class MissingDependencyError < StandardError
+    end
+
+    class ViewsNotFrozenError < StandardError
+    end
+
+    class NotConfiguredError < StandardError
+    end
+
+    # A send that failed on the way out -- network, TLS, or the server
+    # refusing it. The transport's own exception is the #cause.
+    class DeliveryError < StandardError
+    end
+  end
+end

data/lib/monk/mail/message.rb

@@ -0,0 +1,66 @@
+module Monk
+  module Mail
+    # One email, as a frozen value: built per request inside whichever
+    # worker Ractor serves it, then handed to a transport without a copy
+    # (docs/adr/0012-minimal-built-in-mailer.md). Deeply frozen on
+    # construction, so it's Ractor.shareable? even when the caller passed
+    # mutable Strings or Arrays -- and later mutating those can't change it.
+    #
+    # Addresses are kept as given ("Name <addr>" or a bare "addr"); nothing
+    # here parses them. `to` is always an Array, however it was passed.
+    Message = Data.define(:from, :to, :subject, :text, :html, :reply_to) do
+      def initialize(from:, to:, subject:, text: nil, html: nil, reply_to: nil)
+        to = Array(to) unless to.nil?
+        to&.each { |address| Fields.header!(:to, address) }
+        raise InvalidMessageError, "to: needs at least one recipient" if to.nil? || to.empty?
+
+        Fields.header!(:from, from)
+        Fields.header!(:subject, subject)
+        Fields.header!(:reply_to, reply_to) unless reply_to.nil?
+        Fields.body!(:text, text)
+        Fields.body!(:html, html)
+        raise InvalidMessageError, "a message needs a text: or html: body (or both)" if text.nil? && html.nil?
+
+        super(**Ractor.make_shareable(
+          { from: from, to: to, subject: subject, text: text, html: html, reply_to: reply_to },
+          copy: true,
+        ))
+      end
+
+      # RFC 5322 wire format, ready for SMTP DATA or a raw-MIME API. date:,
+      # message_id: and boundary: are generated when omitted; tests pin them.
+      def to_mime(**) = MIME.build(self, **)
+
+      # The bare addresses, for the SMTP envelope (MAIL FROM / RCPT TO).
+      def envelope_from = Address.bare(from)
+      def envelope_to = to.map { |address| Address.bare(address) }
+    end
+
+    # Field checks shared by Message and Monk::Mail.configure(from:).
+    module Fields
+      module_function
+
+      # A CR or LF in a header value would let whoever controls it (say, a
+      # user typing their email into a login form) inject headers of their
+      # own -- a Bcc: to anyone. Rejected outright rather than stripped:
+      # silently rewriting a recipient is worse than refusing it.
+      def header!(field, value)
+        string!(field, value)
+        raise InvalidMessageError, "#{field}: can't be blank" if value.strip.empty?
+        return unless value.match?(/[\r\n]/)
+
+        raise InvalidMessageError, "#{field}: can't contain a line break (#{value.inspect})"
+      end
+
+      def body!(field, value)
+        string!(field, value) unless value.nil?
+      end
+
+      def string!(field, value)
+        return if value.is_a?(String)
+
+        raise InvalidMessageError, "#{field}: must be a String, got #{value.inspect}"
+      end
+    end
+  end
+end

data/lib/monk/mail/mime.rb

@@ -0,0 +1,124 @@
+require "securerandom"
+
+module Monk
+  module Mail
+    # Renders a Message to RFC 5322 wire format -- what the `mail` gem
+    # would do, cut down to Monk::Mail's scope: a text part, an HTML part,
+    # or both as multipart/alternative. Bodies are UTF-8 and always base64
+    # (never 7bit/quoted-printable), so any content survives any relay and
+    # no line ever gets near the 998-octet limit. Header values that
+    # aren't plain ASCII are RFC 2047 encoded words. Plain module
+    # functions over frozen input, so it runs in any Ractor.
+    module MIME
+      CRLF = "\r\n".freeze
+      MAX_LINE = 78
+      # 42 bytes base64-encode to 56 chars; with the "=?UTF-8?B?" / "?="
+      # wrapper that's a 68-char encoded word, under RFC 2047's 75, and
+      # "Subject: " plus one of them still fits a 78-char line.
+      WORD_BYTES = 42
+
+      module_function
+
+      def build(message, date: Time.now, message_id: nil, boundary: nil)
+        message_id ||= "<#{SecureRandom.uuid}@#{domain(message.envelope_from)}>"
+        headers = [
+          "From: #{address_list([message.from], "From")}",
+          "To: #{address_list(message.to, "To")}",
+          ("Reply-To: #{address_list([message.reply_to], "Reply-To")}" if message.reply_to),
+          "Subject: #{unstructured(message.subject, "Subject")}",
+          "Date: #{date.strftime("%a, %d %b %Y %H:%M:%S %z")}",
+          "Message-ID: #{message_id}",
+          "MIME-Version: 1.0",
+        ].compact
+
+        parts = [
+          (["text/plain", message.text] if message.text),
+          (["text/html", message.html] if message.html),
+        ].compact
+
+        if parts.size == 1
+          (headers + part(*parts.first)).join(CRLF)
+        else
+          boundary ||= "monk-#{SecureRandom.hex(16)}"
+          head = headers + [%(Content-Type: multipart/alternative; boundary="#{boundary}"), "", ""]
+          body = parts.map { |type, content| "--#{boundary}#{CRLF}#{part(type, content).join(CRLF)}" }
+          head.join(CRLF) + body.join + "--#{boundary}--#{CRLF}"
+        end
+      end
+
+      # A part's own headers, a blank line, then its base64 body (which
+      # ends in CRLF).
+      def part(type, content)
+        body = utf8(content, type).gsub(/\r?\n/, CRLF)
+        [
+          "Content-Type: #{type}; charset=UTF-8",
+          "Content-Transfer-Encoding: base64",
+          "",
+          [body].pack("m").gsub("\n", CRLF),
+        ]
+      end
+
+      def address_list(addresses, name)
+        rendered = addresses.map { |address| Address.header(utf8(address, name)) }
+        one_line = rendered.join(", ")
+        name.length + 2 + one_line.length <= MAX_LINE ? one_line : rendered.join(",#{CRLF} ")
+      end
+
+      # ASCII stays readable (folded at spaces when long); anything else,
+      # or anything that could be mistaken for an encoded word, is encoded.
+      def unstructured(value, name)
+        value = utf8(value, name)
+        return encode_words(value) if !value.ascii_only? || value.include?("=?")
+
+        fold(value, name.length + 2)
+      end
+
+      # RFC 2047 "B" encoded words, split so none exceeds WORD_BYTES of
+      # input -- and never inside a multibyte character, which would leave
+      # both halves undecodable. Joined by folding whitespace, which
+      # decoders drop between adjacent encoded words.
+      def encode_words(value)
+        chunks = value.each_char.with_object([+""]) do |char, acc|
+          acc << +"" if acc.last.bytesize + char.bytesize > WORD_BYTES
+          acc.last << char
+        end
+        chunks.map { |chunk| "=?UTF-8?B?#{[chunk].pack("m0")}?=" }.join("#{CRLF} ")
+      end
+
+      # Greedy wrap at spaces; a continuation line starts with one space.
+      # A value that already fits is returned untouched, spacing and all.
+      def fold(value, offset)
+        return value if offset + value.length <= MAX_LINE
+
+        lines = []
+        current = nil
+        value.split.each do |word|
+          width = lines.empty? ? offset : 1
+          if current && width + current.length + 1 + word.length > MAX_LINE
+            lines << current
+            current = word
+          else
+            current = current ? "#{current} #{word}" : word
+          end
+        end
+        lines << current if current
+        lines.join("#{CRLF} ")
+      end
+
+      def domain(address)
+        address.include?("@") ? address.split("@").last : "localhost"
+      end
+
+      # Every piece of text goes out as UTF-8. A binary String is assumed
+      # to be UTF-8 bytes; any other encoding is transcoded.
+      def utf8(value, name)
+        string = value.encoding == Encoding::BINARY ? value.dup.force_encoding(Encoding::UTF_8) : value.encode(Encoding::UTF_8)
+        return string if string.valid_encoding?
+
+        raise InvalidMessageError, "#{name} isn't valid UTF-8"
+      rescue EncodingError
+        raise InvalidMessageError, "#{name} can't be converted to UTF-8"
+      end
+    end
+  end
+end

data/lib/monk/mail/transports.rb

@@ -0,0 +1,115 @@
+module Monk
+  module Mail
+    # Where a Message goes. Each transport is a frozen Data value holding
+    # only its settings -- never a connection or client object -- so it
+    # can sit in Monk::Mail's boot-frozen config and be read from any
+    # worker Ractor; the client is built fresh on every send, inside the
+    # Ractor doing the sending, the same pattern as PG::Connection
+    # (docs/adr/0012-minimal-built-in-mailer.md).
+    module Transports
+      # starttls: :always (fail if the server doesn't offer it), :auto (use
+      # it if offered) or :never. tls: true is implicit TLS from the first
+      # byte (smtps://, usually port 465), where STARTTLS doesn't apply.
+      #
+      # net-smtp is the app's dependency, not Monk's (a bundled gem since
+      # Ruby 3.1, like pg/redis are opt-in): required when an smtp:// URL
+      # is configured, so a missing gem fails the boot, not the first send.
+      SMTP = Data.define(:host, :port, :user, :password, :tls, :starttls, :open_timeout, :read_timeout) do
+        def self.require_library!
+          require "net/smtp"
+        rescue LoadError
+          raise MissingDependencyError,
+            "MAIL_URL is smtp:// or smtps://, which needs the net-smtp gem -- a bundled, not default, " \
+            "gem since Ruby 3.1. Add `gem \"net-smtp\"` to your Gemfile."
+        end
+
+        # Called at boot, in the main Ractor, from Monk::Mail.freeze_registry!.
+        # Net::SMTP keeps its AUTH mechanisms ({PLAIN: AuthPlain, ...}) in a
+        # class-level Hash, filled once when net/smtp is required; unfrozen,
+        # a worker Ractor reading it raises Ractor::IsolationError on every
+        # authenticated send. Sealing it is the same move as
+        # Monk::Auth.freeze_rqrcode!. The cost: an auth mechanism registered
+        # after boot would raise FrozenError -- nothing in net-smtp does that.
+        def self.prepare!
+          require_library!
+          Ractor.make_shareable(Net::SMTP::Authenticator.auth_classes)
+        end
+
+        def initialize(host:, port:, user: nil, password: nil, tls: false, starttls: :auto, open_timeout: 5,
+                       read_timeout: 10)
+          super
+        end
+
+        # One connection per message, built here, inside whichever Ractor
+        # is sending. Any network, TLS or SMTP-level failure becomes a
+        # Monk::Mail::DeliveryError (the original is its #cause), so a
+        # caller rescues one class whatever went wrong.
+        def deliver(message)
+          smtp = Net::SMTP.new(host, port, tls: tls, starttls: starttls == :never ? false : starttls)
+          smtp.open_timeout = open_timeout
+          smtp.read_timeout = read_timeout
+          smtp.start(helo: MIME.domain(message.envelope_from), user: user, secret: password) do |session|
+            session.send_message(message.to_mime, message.envelope_from, *message.envelope_to)
+          end
+          message
+        rescue Net::SMTPError, IOError, SystemCallError, SocketError, Timeout::Error, OpenSSL::SSL::SSLError => e
+          raise DeliveryError, "SMTP delivery via #{host}:#{port} failed: #{e.class}: #{e.message.strip}"
+        end
+
+        # Never print the password -- a transport ends up in logs and
+        # exception messages more easily than anyone intends.
+        def inspect
+          "#<#{self.class.name} #{tls ? "smtps" : "smtp"}://#{"#{user}:***@" if user}#{host}:#{port} " \
+            "starttls=#{starttls}>"
+        end
+        alias_method :to_s, :inspect
+      end
+
+      # Writes each message to Monk::Log instead of sending it: the
+      # development default when MAIL_URL is unset, and an explicit
+      # log:// anywhere else. One line per message in log/<env>.log (the
+      # text body escaped with #inspect so it stays one line; the HTML
+      # only by size), plus, in development only, the whole readable
+      # message on $stdout -- where a developer is looking, and where a
+      # magic link gets clicked. Same stdout posture as Base#log_request
+      # and Monk::Auth.log_dev_link.
+      Log = Data.define do
+        def deliver(message)
+          Monk::Log.info("[mail] #{summary(message)}")
+          if Monk.env.development?
+            $stdout.puts(readable(message))
+            $stdout.flush
+          end
+          message
+        end
+
+        private
+
+        def summary(message)
+          fields = [
+            "from=#{message.from.inspect}",
+            "to=#{message.to.join(", ").inspect}",
+            ("reply_to=#{message.reply_to.inspect}" if message.reply_to),
+            "subject=#{message.subject.inspect}",
+            ("text=#{message.text.inspect}" if message.text),
+            ("html=#{message.html.bytesize} bytes" if message.html),
+          ]
+          fields.compact.join(" ")
+        end
+
+        def readable(message)
+          lines = [
+            "[mail] ----------------------------------------",
+            "From: #{message.from}",
+            "To: #{message.to.join(", ")}",
+            ("Reply-To: #{message.reply_to}" if message.reply_to),
+            "Subject: #{message.subject}",
+          ]
+          lines += ["", "--- text ---", message.text] if message.text
+          lines += ["", "--- html ---", message.html] if message.html
+          (lines.compact + ["[mail] ----------------------------------------"]).join("\n")
+        end
+      end
+    end
+  end
+end

data/lib/monk/mail/url.rb

@@ -0,0 +1,76 @@
+require "uri"
+
+module Monk
+  module Mail
+    # MAIL_URL -> a transport value. Runs once, from Monk::Mail.configure
+    # in the main Ractor at boot, so a malformed URL fails the boot rather
+    # than the first send (docs/adr/0003-boot-time-fail-fast-shareability.md's
+    # posture). Error messages redact the password: the URL is a secret.
+    module URL
+      SUPPORTED = "smtp://, smtps://, log://".freeze
+      STARTTLS_MODES = %w[auto always never].freeze
+
+      module_function
+
+      def parse(url)
+        uri = URI.parse(url)
+        case uri.scheme&.downcase
+        when "log" then Transports::Log.new
+        when "smtp" then smtp(uri, url, tls: false)
+        when "smtps" then smtp(uri, url, tls: true)
+        else invalid!(url, "unsupported scheme #{uri.scheme.inspect}; supported: #{SUPPORTED}")
+        end
+      rescue URI::InvalidURIError
+        invalid!(url, "not a valid URL; expected e.g. smtp://user:pass@smtp.example.com:587")
+      end
+
+      def smtp(uri, url, tls:)
+        invalid!(url, "missing host") if uri.host.nil? || uri.host.empty?
+
+        Transports::SMTP.require_library!
+        user = decode(uri.user)
+        Transports::SMTP.new(
+          host: uri.host,
+          port: uri.port || (tls ? 465 : 587),
+          user: user,
+          password: decode(uri.password),
+          tls: tls,
+          starttls: starttls(uri, url, tls: tls, credentials: !user.nil?),
+        )
+      end
+
+      # Default :always with credentials (a stripped STARTTLS would
+      # otherwise send the password in clear), :auto without (a local
+      # relay usually has no TLS set up).
+      def starttls(uri, url, tls:, credentials:)
+        options = URI.decode_www_form(uri.query || "").to_h
+        unknown = options.keys - ["starttls"]
+        invalid!(url, "unknown option(s) #{unknown.join(", ")}; the only one is starttls=") if unknown.any?
+
+        mode = options["starttls"]
+        if tls
+          invalid!(url, "starttls= doesn't apply to smtps://, which is TLS from the start") if mode
+          return :never
+        end
+        return credentials ? :always : :auto if mode.nil?
+
+        invalid!(url, "starttls= must be one of #{STARTTLS_MODES.join(", ")}") unless STARTTLS_MODES.include?(mode)
+        mode.to_sym
+      end
+
+      def decode(component)
+        return nil if component.nil? || component.empty?
+
+        URI.decode_uri_component(component)
+      end
+
+      def invalid!(url, reason)
+        raise InvalidMailUrlError, "MAIL_URL #{redact(url).inspect}: #{reason}"
+      end
+
+      def redact(url)
+        url.to_s.sub(%r{(://[^:/@]*:)[^@/]*@}, '\1***@')
+      end
+    end
+  end
+end

data/lib/monk/mail.rb

@@ -0,0 +1,121 @@
+require_relative "freeze_hooks"
+require_relative "environment"
+require_relative "log"
+require_relative "views"
+require_relative "context"
+require_relative "mail/errors"
+require_relative "mail/address"
+require_relative "mail/mime"
+require_relative "mail/message"
+require_relative "mail/transports"
+require_relative "mail/url"
+
+module Monk
+  # Sending email. Opt-in: require "monk/mail" explicitly -- `require
+  # "monk"` alone does not load this. Text and/or HTML messages only, MIME
+  # built by Monk itself, since the `mail` gem can't run inside a worker
+  # Ractor (docs/adr/0012-minimal-built-in-mailer.md).
+  module Mail
+    class << self
+      # Typically, in config/mail.rb:
+      #
+      #   Monk::Mail.configure(url: ENV["MAIL_URL"], from: ENV["MAIL_FROM"])
+      #
+      # url: picks the transport (smtp://, smtps://, log://) and is parsed
+      # here, so a bad one fails the boot. Unset or empty means log:// in
+      # development and raises everywhere else -- same posture as
+      # Monk::Auth.deliver_link: an app that forgot to wire mail should
+      # find out at boot, not when a user never gets their login link.
+      # from: is the default sender, optional since each send can pass its own.
+      def configure(url:, from: nil)
+        Fields.header!(:from, from) unless from.nil?
+
+        @config = { transport: transport_for(url), from: from }
+      end
+
+      attr_reader :config
+
+      # Builds a Message and sends it through the configured transport,
+      # synchronously -- the calling worker Ractor waits for the send
+      # (docs/adr/0012-minimal-built-in-mailer.md accepts that cost; a
+      # local relay or a fast HTTPS provider keeps it short). Returns the
+      # Message. Invalid input raises InvalidMessageError before anything
+      # is sent; a failed send raises DeliveryError.
+      #
+      #   Monk::Mail.deliver(to: email, subject: "Your login link", text: "Log in: #{link}")
+      def deliver(to:, subject:, text: nil, html: nil, reply_to: nil, from: nil)
+        raise NotConfiguredError, "call Monk::Mail.configure(url:, from:) before Monk::Mail.deliver" unless config
+
+        from ||= config[:from]
+        if from.nil?
+          raise InvalidMessageError, "no from: given, and Monk::Mail.configure has no default from: (MAIL_FROM)"
+        end
+
+        message = Message.new(from: from, to: to, subject: subject, text: text, html: html, reply_to: reply_to)
+        config[:transport].deliver(message)
+      end
+
+      # Renders a Monk::Views template to an HTML String for deliver's
+      # html: -- e.g. views/mail/magic_link.erb:
+      #
+      #   html: Monk::Mail.render("mail/magic_link", link: link)
+      #
+      # The same detached-Context render Monk::Live::Renderer does: no
+      # request behind it, so the template sees only its locals, never
+      # params or the session. The app's page layout is skipped (layout:
+      # false); pass layout: "mail/layout" for an email-specific one.
+      # `<%= %>` escapes as usual, which is right for HTML and wrong for a
+      # plain-text body -- build text: as a Ruby String instead.
+      def render(template, layout: false, **locals)
+        ensure_views_frozen!
+        String.new(Monk::Context.new({}).render(template, layout: layout, **locals)).freeze
+      end
+
+      # Called from Base#freeze! (Seam B), via Monk.freeze_hooks. Freezes
+      # the value, not the module, same as Monk::Auth.freeze_registry! --
+      # an unfrozen config Hash can't be read from a worker Ractor at all.
+      def freeze_registry!
+        transport = @config&.fetch(:transport)
+        transport.class.prepare! if transport.class.respond_to?(:prepare!)
+        @config = Ractor.make_shareable(@config)
+      end
+
+      # Test-only: drops the current config. Not part of the app-facing API.
+      def reset!
+        @config = nil
+      end
+
+      private
+
+      # Unfrozen, a render from a worker Ractor dies with an opaque
+      # Ractor::IsolationError inside Monk::Views, and one from the main
+      # Ractor works by accident and then fails in production -- so both
+      # fail here, naming the fix (same check as Monk::Live::Renderer).
+      def ensure_views_frozen!
+        return if Ractor.shareable?(Monk::Views.registry)
+
+        raise_views_not_frozen
+      rescue Ractor::IsolationError
+        raise_views_not_frozen
+      end
+
+      def raise_views_not_frozen
+        raise ViewsNotFrozenError,
+          "Monk::Mail.render can't render before views are compiled and frozen -- call Monk.boot(app) " \
+          "(or Monk.freeze!) in the main Ractor first"
+      end
+
+      def transport_for(url)
+        return URL.parse(url) unless url.nil? || url.empty?
+        return Transports::Log.new if Monk.env.development?
+
+        raise MissingMailUrlError,
+          "Monk::Mail.configure(url:) is empty and this isn't development (MONK_ENV=#{Monk.env}) -- " \
+          "no email would ever be sent. Set MAIL_URL, e.g. smtp://user:pass@smtp.example.com:587, " \
+          "or log:// if logging messages instead of sending them is truly intended here."
+      end
+    end
+
+    Monk.freeze_hooks << self
+  end
+end

data/lib/monk/scaffold.rb

@@ -45,6 +45,15 @@ 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
 
     # --live: Monk::Live's demo (a counter whose open tabs update when
@@ -107,10 +116,14 @@ 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.
+    def initialize(dir, postgres: false, auth: false, redis: false, live: false, mail: false)
       @dir = dir
       @auth = auth
       @postgres = postgres || auth
+      @mail = mail || auth
       @live = live
 
       if @live
@@ -145,15 +158,20 @@ 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
+
+      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
@@ -224,12 +242,20 @@ 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
 
       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
 
     # .env/.env.test/.env.example are the other deliberate exception to
@@ -252,6 +278,17 @@ 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
+
       # 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 +430,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 +452,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**:
@@ -553,7 +590,7 @@ module Monk
         bin/server              # HTTP app on :9292
         bin/websocket_server    # WS chat process on :9293, in another terminal
         ```
-        #{auth_or_redis_confirmation_note}
+        #{auth_or_redis_confirmation_note}#{mail_setup_note}
         ## Test environment
 
         ### 1. Create the test database
@@ -600,7 +637,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}
         ```
 
         **Rakefile**:
@@ -657,6 +694,43 @@ 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
+
+    # 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(/^/, "  ")

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/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/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.16.0".freeze
+  VERSION = "0.17.0".freeze
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: monkrb
 version: !ruby/object:Gem::Version
-  version: 0.16.0
+  version: 0.17.0
 platform: ruby
 authors:
 - Matteo Folin
@@ -79,6 +79,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '3.2'
+- !ruby/object:Gem::Dependency
+  name: net-smtp
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.5'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.5'
 - !ruby/object:Gem::Dependency
   name: minitest
   requirement: !ruby/object:Gem::Requirement
@@ -175,6 +189,13 @@ files:
 - lib/monk/live/renderer.rb
 - lib/monk/live/session.rb
 - lib/monk/log.rb
+- lib/monk/mail.rb
+- lib/monk/mail/address.rb
+- lib/monk/mail/errors.rb
+- lib/monk/mail/message.rb
+- lib/monk/mail/mime.rb
+- lib/monk/mail/transports.rb
+- lib/monk/mail/url.rb
 - lib/monk/persistence.rb
 - lib/monk/persistence/errors.rb
 - lib/monk/persistence/model.rb
@@ -188,6 +209,7 @@ files:
 - lib/monk/templates/auth/config/auth.rb
 - lib/monk/templates/auth/db/migrate/00000000000001_create_auth_tables.down.sql
 - lib/monk/templates/auth/db/migrate/00000000000001_create_auth_tables.up.sql
+- lib/monk/templates/auth/views/mail/magic_link.erb
 - lib/monk/templates/base/.dockerignore
 - lib/monk/templates/base/.gitignore
 - lib/monk/templates/base/.ruby-version
@@ -207,6 +229,8 @@ files:
 - lib/monk/templates/live/config/live_pg.rb
 - lib/monk/templates/live/views/index.erb
 - lib/monk/templates/live/views/live/_hits.erb
+- lib/monk/templates/mail/Gemfile.extra
+- lib/monk/templates/mail/config/mail.rb
 - lib/monk/templates/postgres/Dockerfile
 - lib/monk/templates/postgres/Gemfile.extra
 - lib/monk/templates/postgres/bin/console