monkrb 0.15.1 → 0.17.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4dff53a61a5894d736707c11c3fc9f3b8ee8b096e180e34e070fb1cd98c3cf61
-  data.tar.gz: 0ca1e853e672436cc717ccad3059f360dcd31cee83d99622a0f0f6aafc78f100
+  metadata.gz: b983d19c7b6de8509f55f50c796d00d90c2d5d345cbe2a9e0f30e8f1349fe7be
+  data.tar.gz: 0fc9a16f56f69aafd1f3937268d337054399c7de34dd1a9a4986d3a6ae3e1bd5
 SHA512:
-  metadata.gz: b0350a71969e23f530a51a281fe824c8f5448fc27e2e957dea78f0ea3eb1f60a2ee89a31bfe7cb474ae342539b511d3f9f2beed7b52c72b50832f149ec4b5e6b
-  data.tar.gz: b59f8860ea7686d5eb284b307db91ad094c58ffdcbf4b35aaec534c8e803c86e75ec9c46f274e861d4dc5f5cd6d17cc5e4e3650489ae634d2e8eeee9229c025c
+  metadata.gz: 582398dd16f93f3d352ed51edfb79904a0e494c98daba3230abce233901b468a5e482d5fa97dfe29832293d79e85e340a491d5899cda327a298b120108008f1a
+  data.tar.gz: 1bde7799803407e6b41c52040e6fa3893a4fd8c2ebb9cca5324cfeb6a1ac291b8a5eaabd7f591204c835179985d14887b009610ebab82f650a6b3d528355f901

data/CHANGELOG.md

@@ -4,6 +4,67 @@ 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
+
+- `Monk::WebSocket::PgFanout`: a Postgres `LISTEN`/`NOTIFY`-backed
+  alternative to `RedisFanout`, implementing the identical
+  `#register`/`#unregister`/`#count`/`#broadcast` interface, for an app
+  that already runs Postgres and doesn't need Redis as a second
+  dependency. Caps a single broadcast at just under 8000 bytes
+  (Postgres's own `NOTIFY` limit) and, unlike `RedisFanout`, has no
+  horizontal-scaling story for many WS processes or a hot topic.
+  `monk new --live --postgres` (without `--redis`) wires it automatically,
+  reusing the app's existing `DB_*` settings — no new configuration, no
+  Redis to run. See `docs/design/live-pg-fanout.md` and
+  `docs/history/plan-live-pg-fanout.md`.
+
+### Changed
+
+- **`monk new --live` no longer silently defaults to Redis.** It now
+  requires `--redis` or `--postgres` explicitly, raising
+  `Monk::AmbiguousLiveTransportError` with neither — there's no way to
+  tell which cross-process transport an app actually has available, so
+  guessing would be as likely to hand back a template that can't connect
+  as one that can. A script that ran `monk new my_app --live` needs
+  `--redis` added to keep the previous behavior.
+
 ## 0.15.1 - 2026-09-24
 
 ### Fixed

data/README.md

@@ -2,7 +2,7 @@
 
 A light Ruby web framework designed to be fully `Ractor`-safe: every app it produces is a valid Rack 3 app that is also `Ractor.shareable?`, so it can be served in parallel across Ractor worker pools without silently losing that safety property. Named after Thelonious Sphere Monk, great and unique Jazz piano player and composer.
 
-**Built in** (loaded by `require "monk"`): routing, context and error handling, boot-time Ractor-shareability checks, `Monk::StateRactor` for shared state, settings, ERB views, static assets and logging. **Opt-in** (each needs its own `require`): Postgres persistence and migrations, passwordless auth and sessions, a WebSocket server with Redis fan-out, and `Monk::Live` server-pushed HTML updates. Details for each are in the [Features](#features) table below.
+**Built in** (loaded by `require "monk"`): routing, context and error handling, boot-time Ractor-shareability checks, `Monk::StateRactor` for shared state, settings, ERB views, static assets and logging. **Opt-in** (each needs its own `require`): Postgres persistence and migrations, passwordless auth and sessions, a WebSocket server with Redis or Postgres fan-out, and `Monk::Live` server-pushed HTML updates. Details for each are in the [Features](#features) table below.
 
 Monk is Kino-agnostic — it's built on stdlib `Ractor` primitives only, with no runtime dependency on any particular server. [Kino](https://github.com/yaroslav/kino) is the reference/development server (see `bin/server`), but any Ractor-aware Rack server, or a conventional one, can run a Monk app.
 
@@ -60,8 +60,9 @@ 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) |
-| WebSocket | `Monk::WebSocket`: RFC 6455 server as its own process, Redis fan-out | `require "monk/websocket"`; Redis fan-out: `require "monk/websocket/redis_fanout"` and the `redis` 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 | [`live.md`](docs/guides/live.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) |
 
 ## More documentation
@@ -70,7 +71,7 @@ Everything beyond the core is opt-in (`require "monk"` alone loads none of it).
 - [`docs/guides/deploying.md`](docs/guides/deploying.md): worked deployment examples.
 - [`docs/design/ractor.md`](docs/design/ractor.md): how Monk uses Ruby's `Ractor`.
 - [`docs/adr/`](docs/adr) and [`CONTEXT.md`](CONTEXT.md): architectural decisions and domain vocabulary.
-- Design docs and phase-by-phase plans behind each feature: [`docs/design/views.md`](docs/design/views.md), [`docs/design/auth-sessions.md`](docs/design/auth-sessions.md), [`docs/design/websocket.md`](docs/design/websocket.md), [`docs/design/persistence-ractor-connections.md`](docs/design/persistence-ractor-connections.md), and the phase-by-phase plans and archived notes in [`docs/history/`](docs/history).
+- Design docs and phase-by-phase plans behind each feature: [`docs/design/views.md`](docs/design/views.md), [`docs/design/auth-sessions.md`](docs/design/auth-sessions.md), [`docs/design/websocket.md`](docs/design/websocket.md), [`docs/design/persistence-ractor-connections.md`](docs/design/persistence-ractor-connections.md), [`docs/design/live-pg-fanout.md`](docs/design/live-pg-fanout.md), and the phase-by-phase plans and archived notes in [`docs/history/`](docs/history).
 - [`CHANGELOG.md`](CHANGELOG.md).
 
 ## Working on this repo
@@ -85,6 +86,6 @@ More (server modes, Docker) in [`docs/development.md`](docs/development.md).
 
 ## Status
 
-Monk is **pre-1.0** (see `lib/monk/version.rb` and the [changelog](CHANGELOG.md)): the API may still change between minor versions. The core is described in [`docs/history/core-plan.md`](docs/history/core-plan.md). There's no open roadmap issue at the moment; new work is proposed and tracked as it comes up. Done so far, each with its own design doc and plan: persistence, migrations, HTML templating and static assets, auth and sessions, WebSocket with Redis fan-out, log levels, live updates (`Monk::Live`, as of 2026-09-19), deployment support (Dockerfile scaffolding, `docs/guides/deploying.md`), and the RubyGems release as `monkrb` (both 2026-09-22).
+Monk is **pre-1.0** (see `lib/monk/version.rb` and the [changelog](CHANGELOG.md)): the API may still change between minor versions. The core is described in [`docs/history/core-plan.md`](docs/history/core-plan.md). There's no open roadmap issue at the moment; new work is proposed and tracked as it comes up. Done so far, each with its own design doc and plan: persistence, migrations, HTML templating and static assets, auth and sessions, WebSocket with Redis fan-out, log levels, live updates (`Monk::Live`, as of 2026-09-19), deployment support (Dockerfile scaffolding, `docs/guides/deploying.md`), the RubyGems release as `monkrb` (both 2026-09-22), and `Monk::WebSocket::PgFanout`/`monk new --live --postgres` — the same cross-process fan-out over Postgres `LISTEN`/`NOTIFY` instead of Redis, for an app that doesn't want a second piece of infrastructure (`docs/design/live-pg-fanout.md`, 2026-09-24).
 
 [Made with Love ❤️, Ruby 💎 and AI 🤖](docs/ai_usage_disclaimer.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
@@ -53,13 +64,21 @@ HELP = <<~TEXT.freeze
 
       --live          Also scaffold Monk::Live: a demo counter whose open tabs
                        update by themselves, pushed as HTML over a WebSocket.
-                       Implies --redis (bin/server and bin/websocket_server
-                       are separate processes, and Redis carries an update
-                       from one to the other). Adds config/live.rb,
-                       views/live/_hits.erb and the browser runtime under
-                       public/js/monk_live/, replaces config.ru, views/index.erb
-                       and bin/websocket_server with live versions, and adds
-                       the runtime's <meta>/<script> tags to the layout.
+                       Requires --redis or --postgres: bin/server and
+                       bin/websocket_server are always separate processes, so
+                       one of the two has to carry a publish between them --
+                       with --redis, the usual Redis wiring; with --postgres
+                       (and not --redis), Monk::WebSocket::PgFanout over
+                       LISTEN/NOTIFY instead, reusing --postgres's own DB_*
+                       settings, so there's no Redis to run. Passing both
+                       picks --redis; passing neither is an error, since
+                       there's no way to tell whether Postgres is available.
+                       Adds
+                       config/live.rb, views/live/_hits.erb and the browser
+                       runtime under public/js/monk_live/, replaces config.ru,
+                       views/index.erb and bin/websocket_server with live
+                       versions, and adds the runtime's <meta>/<script> tags
+                       to the layout.
 
   Commands:
       new APP_NAME    Create a new project (see Options above)
@@ -101,16 +120,26 @@ 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 "  Monk::Live needs Redis running, bin/server and bin/websocket_server (see SETUP.md)" if live
+  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)"
+    else
+      puts "  Monk::Live needs bin/server and bin/websocket_server running, sharing Postgres (see SETUP.md)"
+    end
+  end
 else
   usage_error!
 end

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/errors.rb

@@ -34,4 +34,7 @@ module Monk
 
   class ScaffoldExistsError < StandardError
   end
+
+  class AmbiguousLiveTransportError < StandardError
+  end
 end

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