monkrb 0.15.1 → 0.17.0

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
@@ -58,11 +67,18 @@ module Monk
       "views/index.erb" => "live/views/index.erb",
     }.freeze
 
+    # config/live.rb itself isn't here -- #write_live! picks between
+    # LIVE_CONFIG_TEMPLATES[@live_transport] instead, since which one gets
+    # written depends on --redis vs --postgres, not a fixed mapping.
     LIVE_FILES = {
-      "config/live.rb" => "live/config/live.rb",
       "views/live/_hits.erb" => "live/views/live/_hits.erb",
     }.freeze
 
+    LIVE_CONFIG_TEMPLATES = {
+      redis: "live/config/live.rb",
+      postgres: "live/config/live_pg.rb",
+    }.freeze
+
     # Where the client runtime lands in the app's public root (an app serves
     # it like any other static file; its files import each other by relative
     # path, so they stay together in one directory).
@@ -87,15 +103,45 @@ module Monk
     # and only then requires "redis", so the gem has to already be in the
     # bundle for that to work.
     #
-    # live: implies redis: -- bin/server and bin/websocket_server are separate
-    # processes, so an update published by one only reaches a socket held by
-    # the other through Redis.
-    def initialize(dir, postgres: false, auth: false, redis: false, live: false)
+    # live: bin/server and bin/websocket_server are always separate
+    # processes, so *something* has to carry a publish between them --
+    # --redis (Monk::WebSocket::RedisFanout) or --postgres
+    # (Monk::WebSocket::PgFanout, reusing --postgres's own DB_* settings,
+    # no Redis to run). --live no longer silently defaults to one: with
+    # neither flag, there's no way to tell whether this app has Postgres
+    # available at all, so guessing would be as likely to hand back a
+    # template that can't connect as one that can. --live --redis wins
+    # over --postgres if both are passed (an explicit ask beats an
+    # implied default); --live --postgres alone (or via --auth, which
+    # 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.
+    #
+    # 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
-      @redis = redis || live
+
+      if @live
+        @redis = redis || false
+        @live_transport = if redis
+          :redis
+        elsif @postgres
+          :postgres
+        else
+          raise Monk::AmbiguousLiveTransportError,
+            "monk new --live needs --redis or --postgres to pick Monk::Live's cross-process " \
+            "transport (bin/server and bin/websocket_server are always separate processes) -- " \
+            "pass one explicitly, e.g. `--live --postgres` (docs/guides/live.md's " \
+            "\"Without Redis\" section has the tradeoffs)"
+        end
+      else
+        @redis = redis
+      end
     end
 
     def write!
@@ -112,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
@@ -136,6 +187,7 @@ module Monk
     private
 
     def write_live!
+      write_file("config/live.rb", LIVE_CONFIG_TEMPLATES.fetch(@live_transport))
       LIVE_FILES.each { |relative, template| write_file(relative, template) }
       copy_live_client!
       add_live_to_layout!
@@ -190,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
@@ -218,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.
@@ -253,12 +324,17 @@ module Monk
     end
 
     def live_setup_md_content
+      @live_transport == :postgres ? live_setup_md_content_postgres : live_setup_md_content_redis
+    end
+
+    def live_setup_md_content_redis
       <<~MARKDOWN
 
         ## Live updates (Monk::Live)
 
-        `monk new --live` wired a demo: a counter whose open tabs update by
-        themselves. It needs three things running, each in its own terminal:
+        `monk new --live --redis` wired a demo: a counter whose open tabs
+        update by themselves. It needs three things running, each in its own
+        terminal:
 
         ```bash
         docker run --rm -d -p 6379:6379 --name #{File.basename(@dir)}_redis redis:7   # skip if one is already up
@@ -272,8 +348,45 @@ module Monk
         (`REDIS_URL`, already in `.env`) is what carries an update from one to
         the other. Where things are:
 
-        - `config/live.rb` -- the Redis wiring and the subscribe rules (nothing
-          is allowed unless a rule says so).
+        - `config/live.rb` -- the Redis wiring (`Monk::WebSocket::RedisFanout`)
+          and the subscribe rules (nothing is allowed unless a rule says so).
+        - `config.ru` -- `POST /hit` changes state and calls `Monk::Live.patch`.
+        - `views/index.erb` -- `live_topic "hits"` marks what to subscribe to.
+        - `views/live/_hits.erb` -- the fragment that gets pushed. Partials
+          used this way see only their locals (`locals[:hits]`), never
+          `params` or the session.
+        - `public/js/monk_live/` -- the browser runtime, copied from the gem.
+          The layout points at it and at `LIVE_WS_URL` (default
+          `ws://localhost:9293`; use `wss://` in production).
+
+        `WS_ALLOWED_ORIGINS` (default `http://localhost:9292`) must list the
+        origin your pages are served from, or the browser's socket is refused.
+      MARKDOWN
+    end
+
+    def live_setup_md_content_postgres
+      <<~MARKDOWN
+
+        ## Live updates (Monk::Live)
+
+        `monk new --live --postgres` wired a demo: a counter whose open tabs
+        update by themselves. It needs two things running, each in its own
+        terminal -- no Redis, since Postgres `LISTEN`/`NOTIFY` carries the
+        update instead:
+
+        ```bash
+        bin/server              # the HTTP app on :9292, which publishes updates
+        bin/websocket_server    # the sockets on :9293, which deliver them
+        ```
+
+        Open http://localhost:9292 in two tabs and press the button in one.
+
+        `bin/server` and `bin/websocket_server` are separate processes, so
+        Postgres `LISTEN`/`NOTIFY` (the same `DB_*` settings already in `.env`)
+        is what carries an update from one to the other. Where things are:
+
+        - `config/live.rb` -- the Postgres wiring (`Monk::WebSocket::PgFanout`)
+          and the subscribe rules (nothing is allowed unless a rule says so).
         - `config.ru` -- `POST /hit` changes state and calls `Monk::Live.patch`.
         - `views/index.erb` -- `live_topic "hits"` marks what to subscribe to.
         - `views/live/_hits.erb` -- the fragment that gets pushed. Partials
@@ -285,6 +398,12 @@ module Monk
 
         `WS_ALLOWED_ORIGINS` (default `http://localhost:9292`) must list the
         origin your pages are served from, or the browser's socket is refused.
+
+        A single broadcast is capped at just under 8000 bytes
+        (`Monk::WebSocket::PgFanout::MAX_NOTIFY_PAYLOAD_BYTES`, Postgres's own
+        `NOTIFY` limit) -- far more than this demo ever sends, but worth
+        knowing before pushing much larger partials this way. Regenerate with
+        `--redis` instead of `--postgres` if that becomes a real constraint.
       MARKDOWN
     end
 
@@ -311,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
@@ -333,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**:
@@ -471,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
@@ -518,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**:
@@ -575,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/live/config/live_pg.rb

@@ -0,0 +1,60 @@
+# Monk::Live wiring, required by both processes: config.ru (this app
+# publishes updates, e.g. from a route) and bin/websocket_server (the browsers'
+# sockets terminate there and are handed the updates).
+#
+# They are separate processes, so *something* has to carry a publish from
+# one to the other. `monk new --live --postgres` (and not --redis) wired
+# this file instead of the Redis-based default -- Postgres LISTEN/NOTIFY
+# carries the publish instead, reusing the exact DB_* env vars
+# config/persistence.rb already reads, so there's no Redis to run. The
+# tradeoff: a single broadcast is capped at just under 8000 bytes
+# (Monk::WebSocket::PgFanout::MAX_NOTIFY_PAYLOAD_BYTES, Postgres's own
+# NOTIFY limit) -- regenerate with --redis instead if that becomes a real
+# constraint. Full design in the monk gem's own docs/design/live-pg-fanout.md.
+require_relative "settings"
+require "monk/live"
+require "monk/websocket/pg_fanout"
+
+# Where the browser opens its WebSocket (read by the layout). In
+# development there's no reverse proxy in front, so this is the direct WS
+# port; outside development it defaults to a /ws path under public_url
+# (config/settings.rb) -- matching the path-based proxy routing
+# docs/guides/deploying.md's "Adding Monk::WebSocket" section sets up, so
+# setting PUBLIC_URL alone keeps this in sync instead of two env vars
+# drifting apart. Override with LIVE_WS_URL directly if your setup doesn't
+# fit that shape.
+default_live_ws_url =
+  if Monk.env.development?
+    "ws://localhost:9293"
+  else
+    Monk::Settings[:public_url].sub(/\Ahttps:\/\//, "wss://").sub(/\Ahttp:\/\//, "ws://") + "/ws"
+  end
+
+Monk::Settings.configure do
+  optional :live_ws_url, default: default_live_ws_url
+end
+
+Monk::Live.configure(
+  registry: Monk::WebSocket::PgFanout.new(
+    Monk::WebSocket::Registry.new,
+    pg_opts: {
+      host: ENV.fetch("DB_HOST", "127.0.0.1"),
+      port: ENV.fetch("DB_PORT", "5432").to_i,
+      user: ENV.fetch("DB_USER", "postgres"),
+      password: ENV.fetch("DB_PASSWORD", "postgres"),
+      dbname: ENV.fetch("DB_NAME", "app_development"),
+    },
+  ),
+)
+
+# Who may subscribe to what. Nothing is allowed unless a rule says so, and an
+# anonymous connection is denied unless the rule opts in with `anonymous: true`.
+# The rule blocks live in a module because they have to be Ractor-shareable
+# (self at the top of this file is not).
+module AppLive
+  # The demo counter is public. A real rule looks at who is asking:
+  #   proc { |subject, topic| topic == "contacts:#{subject}" }
+  PUBLIC = proc { |_subject, _topic| true }
+end
+
+Monk::Live.authorize("hits", anonymous: true, &AppLive::PUBLIC)

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

data/lib/monk/websocket/errors.rb

@@ -5,5 +5,12 @@ module Monk
 
     class ProtocolError < StandardError
     end
+
+    # Raised by PgFanout#broadcast before ever calling pg_notify, rather
+    # than letting a raw PG::Error surface from inside it or silently
+    # truncating -- see docs/design/live-pg-fanout.md's payload-cap
+    # tradeoff.
+    class PayloadTooLargeError < StandardError
+    end
   end
 end