monkrb 0.16.0 → 0.18.0

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,35 @@
+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
+
+    # A DeliveryError the server made final: an SMTP 5xx (no such mailbox,
+    # relaying refused) or refused credentials. Raised by
+    # Monk::Mail::DeliveryJob (require "monk/mail/later") so the job isn't
+    # retried; still a DeliveryError, so a rescue of that catches it too.
+    class PermanentDeliveryError < DeliveryError
+    end
+  end
+end

data/lib/monk/mail/later.rb

@@ -0,0 +1,53 @@
+require_relative "../mail"
+require_relative "../jobs"
+
+module Monk
+  module Mail
+    # Sends one message from a job process (docs/adr/0014-mail-from-jobs-and-login-links-created-in-the-job.md).
+    # Enqueued by Monk::Mail.deliver_later, never directly: its argument
+    # is the message's fields, already checked and with from: resolved.
+    class DeliveryJob < Monk::Job
+      queue "mailers"
+      never_retry PermanentDeliveryError
+
+      # The SMTP failures that are final, by class name so this file never
+      # loads net/smtp itself (the app's Gemfile decides that, ADR 0012):
+      # a 5xx reply, a malformed command, refused credentials. Everything
+      # else -- a 4xx "try later", a refused connection, TLS, a timeout --
+      # is worth retrying.
+      PERMANENT_SMTP_ERRORS = %w[Net::SMTPFatalError Net::SMTPSyntaxError Net::SMTPAuthenticationError].freeze
+
+      def self.perform(fields)
+        Monk::Mail.deliver(**fields.transform_keys(&:to_sym))
+      rescue DeliveryError => e
+        raise unless PERMANENT_SMTP_ERRORS.include?(e.cause&.class&.name)
+
+        raise PermanentDeliveryError, e.message
+      end
+    end
+
+    class << self
+      # deliver, later: the same arguments, plus enqueue's wait:, at: and
+      # conn: (the last one enqueues inside the caller's transaction, so the
+      # email commits or rolls back with the app's own writes). Returns the
+      # job's id. The message is built -- and so checked -- here, before
+      # anything is enqueued: bad input raises InvalidMessageError in the
+      # caller, exactly as deliver would, rather than failing later in the
+      # job process. Render HTML before calling (html: Monk::Mail.render(...)):
+      # the job stores the finished message and only sends it.
+      #
+      #   Monk::Mail.deliver_later(to: order[:email], subject: "Your receipt", text: receipt_text)
+      def deliver_later(to:, subject:, text: nil, html: nil, reply_to: nil, from: nil, wait: nil, at: nil, conn: nil)
+        raise NotConfiguredError, "call Monk::Mail.configure(url:, from:) before Monk::Mail.deliver_later" 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)
+        DeliveryJob.enqueue(message.to_h.transform_keys(&:to_s), wait: wait, at: at, conn: conn)
+      end
+    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/persistence/pg.rb

@@ -1,3 +1,4 @@
+require "json"
 require "pg"
 
 require_relative "../persistence"
@@ -16,12 +17,31 @@ module Monk
     module Pg
       extend Monk::Persistence::Registry
 
+      # json/jsonb columns, decoded with plain JSON.parse. pg's own
+      # PG::TextDecoder::JSON (1.6.3) calls JSON.parse(string, quirks_mode:
+      # true), and json 3 removed that keyword, so with pg's default every
+      # json/jsonb read raised ArgumentError. json 3 parses a bare scalar
+      # ("7", "\"text\"") without it.
+      class JsonDecoder < PG::SimpleDecoder
+        def decode(string, _tuple = nil, _field = nil)
+          JSON.parse(string)
+        end
+      end
+
+      # pg's default result types, with JsonDecoder for json and jsonb.
+      # Built once and made shareable, so every Ractor's #connect can use
+      # it rather than building its own.
+      RESULT_TYPES = Ractor.make_shareable(
+        PG::BasicTypeRegistry.new.register_default_types
+          .tap { |types| %w[json jsonb].each { |name| types.register_type(0, name, nil, JsonDecoder) } },
+      )
+
       class << self
         private
 
         def connect(**opts)
           conn = PG.connect(**opts)
-          conn.type_map_for_results = PG::BasicTypeMapForResults.new(conn)
+          conn.type_map_for_results = PG::BasicTypeMapForResults.new(conn, registry: RESULT_TYPES)
           conn
         end