monkrb 0.15.0 → 0.16.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7fc84b47997c81eb2748a3326ae5adba796ae90eb143d3c537b2f718d41b4a33
-  data.tar.gz: 7f2072700db0787f7e9ee8bb0c28bf03e09b6194d2ad3c8aedcb89490c179ad8
+  metadata.gz: 7e6286fdc2af1003d176142f6d7b7410c1f924f78466f28ff1bd4b95709c6230
+  data.tar.gz: 1c5030467a67e80f57e4f10ad939c06392d5d80cff0cc732692589f207173a66
 SHA512:
-  metadata.gz: f55f23d4954fec6400c1976a00f203bbd4b17df3ab1c0b0150051fd64a85db5e8e5f43229593a4d23333e56a4051fb39a45e2e9a9ce20dd0f3780101e918427a
-  data.tar.gz: 94aad3a80714da837196a0c81d1191dd5c9e5490ebb7ed5094b2fb737dcb55615d4f187d13876acd125830ce14bf46ab9f6718654d7ff2b0435bfc108bd214ea
+  metadata.gz: 204709f8e01de1f7d13e3223daff2a875979b1fd93ed5fa51663e5750f1fab6046f3ac9827712204864d2d6f50b309088f2262fa66533715b0ab486e33e330e5
+  data.tar.gz: 727e5d900941e860ae491bff2e7042a4d9ac7be13131707435361aca990021cc8fcd4b580421bfe10b0ebbe7c12430f461629449b18f49098437fa17097d72ad

data/CHANGELOG.md

@@ -4,6 +4,48 @@ 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.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
+
+- ERB templates with a non-ASCII string literal inside Ruby code (e.g.
+  `<%= ok ? "✓" : "✗" %>`) no longer render as `ASCII-8BIT` and drag the
+  whole page — layout and other locals included — down with them. The
+  compiled template source is now retagged with the encoding
+  `ERB::Compiler#compile` returns instead of dropping it.
+
+### Added
+
+- `docs/ai_usage_disclaimer.md`, linked from the README.
+- `docs/deployment-options.md`: analysis of hosting options for Postgres,
+  Redis, and SMTP.
+
 ## 0.15.0 - 2026-09-22
 
 ### Changed

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,8 @@ 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) |
+| 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 +70,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,4 +85,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

@@ -53,13 +53,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)
@@ -110,7 +118,13 @@ when "new"
   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
+  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/errors.rb

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

data/lib/monk/scaffold.rb

@@ -58,11 +58,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 +94,41 @@ 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.
+    # 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.
     def initialize(dir, postgres: false, auth: false, redis: false, live: false)
       @dir = dir
       @auth = auth
       @postgres = postgres || 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!
@@ -136,6 +169,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!
@@ -253,12 +287,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 +311,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 +361,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
 

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

data/lib/monk/views.rb

@@ -151,7 +151,18 @@ module Monk
         compiler.post_cmd = ["Monk::Views::Raw.new(_erbout)"]
         compiler.put_cmd = "_erbout.<<"
         compiler.insert_cmd = "_erbout.<< Monk::Views.h"
-        compiler.compile(source).first
+        script, encoding, = compiler.compile(source)
+        # ERB::Compiler#compile scans the source as ASCII-8BIT (see its
+        # own String#b) and hands that tag straight through to any code
+        # inside <%= %>/<% %> -- template TEXT is safe (put_cmd dumps it
+        # to ASCII escapes), but a non-ASCII literal written in Ruby code,
+        # e.g. <%= ok ? "✓" : "✗" %>, comes back mistagged
+        # ASCII-8BIT even though the bytes are valid UTF-8. #compile's
+        # second return value is the encoding to retag it with; dropping
+        # that (as this used to) is what broke non-ASCII Ruby literals --
+        # the mistagged string then downgrades whatever UTF-8 content it's
+        # concatenated with (layouts, other locals) to ASCII-8BIT too.
+        encoding ? script.dup.force_encoding(encoding) : script
       end
 
       def method_name_for(name)

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

data/lib/monk/websocket/pg_fanout.rb

@@ -0,0 +1,174 @@
+require "pg"
+require "securerandom"
+
+module Monk
+  module WebSocket
+    # Cross-process fan-out for Registry, opt-in: require
+    # "monk/websocket/pg_fanout" explicitly -- "monk/websocket" alone does
+    # not load this. A second implementation of the exact interface
+    # RedisFanout wraps a Registry behind (#register, #unregister, #count,
+    # #broadcast, docs/design/live-pg-fanout.md,
+    # docs/history/plan-live-pg-fanout.md), so an app swaps which object it
+    # holds and nothing else changes. Uses Postgres LISTEN/NOTIFY instead
+    # of Redis pub/sub -- for an app that already runs Postgres
+    # (persistence, Monk::Auth) and doesn't need Redis's higher throughput
+    # or its lack of a payload cap (see the design doc's "Where this is
+    # worse than Redis").
+    class PgFanout
+      # Postgres has no pattern LISTEN (unlike Redis's own
+      # psubscribe("monk:ws:*")), so every key shares one fixed channel;
+      # the key rides inside the notification payload instead of the
+      # channel name -- see the subscriber Ractor in #initialize below
+      # for the other half of this.
+      CHANNEL = "monk_live".freeze
+
+      # Postgres's own hard limit on a single NOTIFY payload -- verified
+      # directly against a real server (not assumed from documentation):
+      # 7999 bytes succeeds, exactly 8000 fails with "payload string too
+      # long". #broadcast checks the full envelope (origin + key + app
+      # payload) against this *exclusive* bound before ever calling
+      # pg_notify, so an oversized broadcast fails with a clear
+      # PayloadTooLargeError instead of a raw PG::Error surfacing from
+      # inside the query.
+      MAX_NOTIFY_PAYLOAD_BYTES = 8000
+
+      # Inverse of #envelope_for. A class method, not a private instance
+      # method like its encode-side counterpart: the subscriber Ractor
+      # below has no `self` bound to a PgFanout instance to call an
+      # ordinary method on, only whatever it can reach off the class
+      # constant (mirrors Monk::WebSocket::Server.serve being a class
+      # method for the equivalent reason -- the Server instance itself
+      # never crosses into a connection's Ractor either).
+      def self.decode_envelope(raw)
+        bytes = raw.b
+        origin_len_str, rest = bytes.split(":", 2)
+        origin_len = origin_len_str.to_i
+        origin = rest[0, origin_len]
+        rest = rest[origin_len..]
+        key_len_str, rest = rest.split(":", 2)
+        key_len = key_len_str.to_i
+        key = rest[0, key_len]
+        payload = rest[key_len..]
+        [origin, key, payload]
+      end
+
+      def initialize(registry, pg_opts:)
+        # Checked upfront, on the argument, before anything below opens a
+        # real Postgres connection -- RedisFanout has no equivalent check
+        # (freezing self never raises on its own, even when an ivar isn't
+        # itself shareable), so a bad registry there only surfaces later
+        # as an opaque Ractor::IsolationError. Checking here first, rather
+        # than after spawning the subscriber below, means a bad registry
+        # never leaves a live LISTEN connection running past a failed
+        # construction. Mirrors Monk::Live.configure's own check of its
+        # registry argument.
+        unless Ractor.shareable?(registry)
+          raise ArgumentError,
+            "Monk::WebSocket::PgFanout.new needs a Ractor-shareable registry, got #{registry.class}"
+        end
+
+        @registry = registry
+        # Ractor.make_shareable, not a plain #freeze: pg_opts's values
+        # (host/user/password Strings from ENV.fetch, typically) aren't
+        # frozen individually just because the Hash itself is -- #freeze
+        # only locks the Hash against further key/value changes, it
+        # doesn't recurse. Without this, the shareability check below
+        # fails on this Hash's contents, not on the registry argument it's
+        # meant to guard, the same trap Server#initialize's
+        # allowed_origins already avoids the same way.
+        @pg_opts = Ractor.make_shareable(pg_opts.dup)
+        # Frozen explicitly, not just a String literal: read from every
+        # calling Ractor's own #broadcast and from the subscriber Ractor
+        # below, both of which raise Ractor::IsolationError on an
+        # unfrozen value -- same reason RedisFanout freezes its own
+        # @origin.
+        @origin = SecureRandom.uuid.freeze
+
+        # Ractor.new's block args must be shareable: registry is
+        # (Registry freezes itself around a Ractor, which is inherently
+        # shareable), @pg_opts and @origin are already made so above. The
+        # PG::Connection itself is never passed in -- opened fresh inside
+        # the block, mirroring RedisFanout's subscriber and
+        # Monk::Persistence::Pg's per-Ractor connection pattern.
+        @subscriber = Ractor.new(registry, @pg_opts, @origin) do |registry, pg_opts, own_origin|
+          conn = PG.connect(**pg_opts)
+          conn.exec("LISTEN #{Monk::WebSocket::PgFanout::CHANNEL}")
+          loop do
+            conn.wait_for_notify do |_channel, _pid, raw|
+              sender, key, payload = Monk::WebSocket::PgFanout.decode_envelope(raw)
+              next if sender == own_origin
+
+              registry.broadcast(key.to_sym, payload)
+            end
+          end
+        end
+
+        freeze
+      end
+
+      def register(key, port) = @registry.register(key, port)
+      def unregister(key, port) = @registry.unregister(key, port)
+      def count(key) = @registry.count(key)
+
+      def broadcast(key, payload)
+        # Delivers locally first, regardless of what happens next -- same
+        # latency and reliability as a plain Registry if Postgres is
+        # briefly unavailable or this payload is over the wire cap,
+        # mirroring RedisFanout#broadcast's own ordering.
+        @registry.broadcast(key, payload)
+
+        envelope = envelope_for(key, payload)
+        if envelope.bytesize >= MAX_NOTIFY_PAYLOAD_BYTES
+          raise Monk::WebSocket::PayloadTooLargeError,
+            "Monk::WebSocket::PgFanout#broadcast payload plus origin/key framing is " \
+            "#{envelope.bytesize} bytes; Postgres NOTIFY accepts a payload of at most " \
+            "#{MAX_NOTIFY_PAYLOAD_BYTES - 1} bytes -- shrink the fragment, or use " \
+            "Monk::WebSocket::RedisFanout instead, which has no such cap"
+        end
+
+        # pg_notify(channel, payload), not a string-built
+        # "NOTIFY channel, 'payload'" -- passing the envelope as a bound
+        # parameter sidesteps any quoting/injection concern for its bytes
+        # entirely, unlike Redis's PUBLISH, which never had that concern
+        # in the first place.
+        publisher.exec_params("SELECT pg_notify($1, $2)", [CHANNEL, envelope])
+      end
+
+      private
+
+      # Length-prefixes the origin and key (Netstring-style: "<bytesize>:"
+      # then that many bytes) instead of RedisFanout's NUL-separated
+      # "origin\0payload" -- discovered while building this that a NUL
+      # byte can't ride in a Postgres NOTIFY payload at all (a bound text
+      # parameter containing one raises "string contains null byte" from
+      # inside exec_params; text NOTIFY payloads simply don't carry one).
+      # A digit run followed by ':' can never be confused with content
+      # coming later: the header is always the *first* ':' in the whole
+      # string, no matter what colons, NULs or anything else an app's key
+      # or payload contains.
+      #
+      # Forces binary (.b) throughout so slicing by the recorded byte
+      # lengths lines up exactly -- the same fix Monk::WebSocket::Frame.encode
+      # needed for non-ASCII payloads (docs/history/plan-live.md Phase 7);
+      # a String#[] by character count on a UTF-8 string would misalign
+      # the moment origin/key/payload aren't pure ASCII.
+      def envelope_for(key, payload)
+        origin_bytes = @origin.b
+        key_bytes = key.to_s.b
+        "#{origin_bytes.bytesize}:".b + origin_bytes + "#{key_bytes.bytesize}:".b + key_bytes + payload.to_s.b
+      end
+
+      # One PG::Connection per calling Ractor, opened on first use and
+      # cached there -- a single client called concurrently from every
+      # connection Ractor's #broadcast wouldn't be safe, mirrors
+      # RedisFanout#publisher and Monk::Persistence::Pg's own per-Ractor
+      # pattern exactly. Never the connection Monk::Persistence::Pg hands
+      # out for app queries: NOTIFY issued on a connection mid-transaction
+      # wouldn't fire until that transaction commits, so this stays a
+      # connection of its own, used for nothing but one-off notifies.
+      def publisher
+        Ractor.current[:monk_pg_fanout_publisher] ||= PG.connect(**@pg_opts)
+      end
+    end
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: monkrb
 version: !ruby/object:Gem::Version
-  version: 0.15.0
+  version: 0.16.0
 platform: ruby
 authors:
 - Matteo Folin
@@ -204,6 +204,7 @@ files:
 - lib/monk/templates/live/bin/websocket_server
 - lib/monk/templates/live/config.ru
 - lib/monk/templates/live/config/live.rb
+- 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/postgres/Dockerfile
@@ -220,6 +221,7 @@ files:
 - lib/monk/websocket/errors.rb
 - lib/monk/websocket/frame.rb
 - lib/monk/websocket/handshake.rb
+- lib/monk/websocket/pg_fanout.rb
 - lib/monk/websocket/redis_fanout.rb
 - lib/monk/websocket/registry.rb
 - lib/monk/websocket/server.rb