monkrb 0.17.0 → 0.19.0

data/lib/monk/templates/auth/app/mailers/app_mailer.rb

@@ -0,0 +1,22 @@
+# The emails this app sends, through Monk::Mail (config/mail.rb). Module
+# constants and module methods rather than an instance, since Monk::Auth's
+# deliver: hook must be Ractor-shareable (a lambda built at a file's top
+# level, where self isn't, would fail) -- the same constraint as
+# Monk::Live.authorize blocks.
+module AppMailer
+  # Monk::Auth's deliver: hook (config/auth.rb), called by
+  # Monk::Auth.deliver_link. The HTML part is
+  # app/views/mail/magic_link.erb. Swap the body for SMS or any other
+  # channel; see docs/guides/auth.md.
+  MAGIC_LINK = 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

data/lib/monk/templates/auth/config/auth.rb

@@ -7,25 +7,12 @@ 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 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 = 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
+# Sends the magic link by email: AppMailer::MAGIC_LINK, in
+# app/mailers/app_mailer.rb. Required here, not left to config/load.rb:
+# Monk::Auth.configure checks deliver: right away, and bin/websocket_server
+# loads this file without config/load.rb. The mailer only touches
+# Monk::Mail when it's called, so that process needs no mail config.
+require_relative "../app/mailers/app_mailer"
 
 Monk::Auth.configure(
   db_name: :primary,
@@ -34,5 +21,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::MAGIC_LINK,
 )

data/lib/monk/templates/base/app/app.rb

@@ -0,0 +1,9 @@
+class App < Monk::Base
+  views "app/views"
+  layout "layouts/app"
+  assets "public"
+
+  get("/") { @title = "App"; render "index" }
+  get("/hello") { "hello from monk" }
+  get("/api/hello") { json(message: "hello from monk") }
+end

data/lib/monk/templates/base/bin/websocket_server

@@ -48,6 +48,12 @@ module ChatServer
   end
 end
 
+# This process holds the sockets, so it's the one that listens for other
+# processes' broadcasts: with REDIS_URL, a subscriber connection, opened
+# here at boot (an unreachable Redis fails right here). A plain Registry
+# has nothing to listen to, and listen! does nothing.
+ChatServer::REGISTRY.listen!
+
 authenticate = defined?(Monk::Auth) && !!Monk::Auth.config
 port = ENV.fetch("WS_PORT", "9293").to_i
 # Defaults to public_url (config/settings.rb) so one PUBLIC_URL env var

data/lib/monk/templates/base/config/load.rb

@@ -0,0 +1,18 @@
+# Loads everything the app runs on: the settings, each Monk module's config,
+# then the app's own code under app/. Required by config.ru and the tests;
+# it never boots the app itself (that's config.ru's Monk.boot).
+require_relative "settings"
+
+# The app's code, one directory per role, in the order they call each
+# other: presenters read models, helpers, mailers and broadcasts use both,
+# and jobs call all of them. Everything is loaded here, before Monk.boot
+# freezes the app -- nothing can be loaded later from a worker Ractor.
+#
+# The order only matters for code that runs while a file loads (a
+# superclass, a constant in a class body, a Monk::Context.include): such a
+# file require_relative's what it needs first. Code inside methods runs
+# later, so it may use any role, even one loaded after it. See Monk's
+# docs/guides/scaffolding.md, "Where code goes".
+%w[models presenters helpers mailers broadcasts jobs].each do |role|
+  Dir[File.expand_path("../app/#{role}/**/*.rb", __dir__)].sort.each { |file| require file }
+end

data/lib/monk/templates/base/config.ru

@@ -1,13 +1,4 @@
-require_relative "config/settings"
+require_relative "config/load" # the configs and app/ (config/load.rb)
+require_relative "app/app"
 
-class App < Monk::Base
-  views "views"
-  layout "layouts/app"
-  assets "public"
-
-  get("/") { @title = "App"; render "index" }
-  get("/hello") { "hello from monk" }
-  get("/api/hello") { json(message: "hello from monk") }
-end
-
-run Monk.boot(App)
+run Monk.boot(App) # Boot: freezes the app and serves it

data/lib/monk/templates/base/public/js/app.js

@@ -1,5 +1,5 @@
 // Served as-is and loaded as an ES module -- no build step. Import your
 // own files by relative path with a real extension
 // (import { x } from "./x.js"), and anything third-party through the
-// import map in views/layouts/app.erb.
+// import map in app/views/layouts/app.erb.
 console.log("monk");

data/lib/monk/templates/jobs/app/jobs/hello_job.rb

@@ -0,0 +1,9 @@
+# The demo job: POST /jobs/hello enqueues it, bin/jobs runs it, and its
+# line lands in log/<env>.log. A job's args must be plain JSON values (an
+# id, not a record), and a job may run more than once, so make it safe to
+# repeat. Replace this with the app's own jobs.
+class HelloJob < Monk::Job
+  def self.perform(name)
+    Monk::Log.info("Hello, #{name}, from a background job")
+  end
+end

data/lib/monk/templates/jobs/app/jobs/send_login_link.rb

@@ -0,0 +1,28 @@
+# Sends a magic link from bin/jobs instead of the login request. The token
+# is created here, right before it's sent, so the raw token is never
+# stored anywhere -- not even in the job queue, which a plain
+# Monk::Mail.deliver_later of the link would do (Monk's
+# docs/adr/0014-mail-from-jobs-and-login-links-created-in-the-job.md).
+# Enqueue it from your login route, after your own per-email rate limit
+# and with a redirect_to already checked against redirect_allowlist:
+#
+#   post("/auth/request") do
+#     SendLoginLink.enqueue(params[:email])
+#     json(sent: true)
+#   end
+class SendLoginLink < Monk::Job
+  queue "mailers"
+  # About 50 seconds of retries: a login email minutes late, after the
+  # user has likely asked for another, is worse than none.
+  max_attempts 3
+  never_retry Monk::InvalidRedirectError
+
+  def self.perform(email, redirect_to = nil)
+    token = Monk::Auth.request_login(email, redirect_to: redirect_to)
+    # Your callback route; config/settings.rb's public_url is the origin.
+    link = "#{Monk::Settings[:public_url]}/auth/callback/#{token}"
+    # Calls config/auth.rb's deliver: (AppMailer::MAGIC_LINK) -- a
+    # synchronous send, here in the job.
+    Monk::Auth.deliver_link(email: email, link: link, token: token)
+  end
+end

data/lib/monk/templates/jobs/bin/jobs

@@ -0,0 +1,18 @@
+#!/usr/bin/env ruby
+require "bundler/setup"
+# The configs and app/, as the web process loads them, so a job can use
+# the app's models and mailers, send mail, or push a Live update --
+# config/load.rb, never Monk.boot: this process serves no routes.
+require_relative "../config/load"
+require "monk/jobs/runtime"
+
+# The app's templates, so a job can render one (a mail's HTML part, say):
+# there's no App class here to point Monk::Views at them.
+Monk::Views.root = File.expand_path("../app/views", __dir__)
+
+workers = Integer(ENV.fetch("JOBS_WORKERS", "5"))
+queues = ENV.fetch("JOBS_QUEUES", "default").split(",").map(&:strip)
+puts "Monk::Jobs: #{workers} worker(s) on #{queues.join(", ")} -- TERM or Ctrl-C finishes the jobs in hand and stops"
+$stdout.flush
+
+Monk::Jobs::Runtime.new(workers: workers, queues: queues).run

data/lib/monk/templates/jobs/config/jobs.rb

@@ -0,0 +1,15 @@
+require "monk"
+require "monk/jobs"
+require_relative "persistence"
+
+# Background jobs (Monk::Jobs): enqueue from any route, e.g.
+# HelloJob.enqueue("world"); bin/jobs runs them. Every job is a class under
+# app/jobs/, which config/load.rb loads after this file, so the web process
+# can enqueue it and bin/jobs can run it.
+#
+# The queue lives in the app's own database, so a job can be enqueued
+# inside the app's own transaction: HelloJob.enqueue("world", conn: conn).
+# Once the app has long-running transactions or heavy load, give the queue
+# a database of its own -- register it in config/persistence.rb and pass
+# its name here (Monk's docs/guides/jobs.md, "Keeping the queue healthy").
+Monk::Jobs.configure(db_name: :primary)

data/lib/monk/templates/jobs/db/migrate/00000000000002_create_jobs_tables.down.sql

@@ -0,0 +1,3 @@
+DROP TABLE monk_processes;
+DROP TABLE monk_job_payloads;
+DROP TABLE monk_jobs;

data/lib/monk/templates/jobs/db/migrate/00000000000002_create_jobs_tables.up.sql

@@ -0,0 +1,48 @@
+-- Monk::Jobs: a narrow state table, a payload table, one row per job
+-- process. Why this shape: docs/adr/0013-jobs-narrow-state-table-plus-payloads.md.
+
+-- Scheduling and state only, about 70 bytes a row: claiming a job
+-- rewrites this row, never the payload.
+CREATE TABLE monk_jobs (
+  id BIGINT GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
+  queue TEXT NOT NULL DEFAULT 'default',
+  priority SMALLINT NOT NULL DEFAULT 0, -- lower runs sooner
+  state TEXT NOT NULL CHECK (state IN ('available', 'scheduled', 'running', 'failed')),
+  run_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+  attempts SMALLINT NOT NULL DEFAULT 0,
+  max_attempts SMALLINT NOT NULL DEFAULT 5,
+  locked_by BIGINT, -- monk_processes.id while running
+  locked_at TIMESTAMPTZ
+);
+
+-- One partial index per lookup, each holding only the rows it wants:
+-- workers claim from the first, the stager promotes due jobs from the
+-- second, pruning a dead process finds its jobs through the third.
+CREATE INDEX monk_jobs_available ON monk_jobs (queue, priority, run_at, id) WHERE state = 'available';
+CREATE INDEX monk_jobs_scheduled ON monk_jobs (run_at) WHERE state = 'scheduled';
+CREATE INDEX monk_jobs_running ON monk_jobs (locked_by) WHERE state = 'running';
+
+-- Every job's row is updated and deleted within seconds, so vacuum it
+-- sooner than Postgres's defaults would (1% of rows dead rather than 20%,
+-- and without cost-based throttling).
+ALTER TABLE monk_jobs SET (autovacuum_vacuum_scale_factor = 0.01, autovacuum_vacuum_cost_delay = 0);
+
+-- Written once at enqueue, deleted with its job, updated only to record
+-- an error.
+CREATE TABLE monk_job_payloads (
+  job_id BIGINT PRIMARY KEY REFERENCES monk_jobs (id) ON DELETE CASCADE,
+  job_class TEXT NOT NULL,
+  args JSONB NOT NULL,
+  last_error TEXT,
+  created_at TIMESTAMPTZ NOT NULL DEFAULT now()
+);
+
+-- One row per bin/jobs process: a heartbeat that stops means its
+-- running jobs go back to available.
+CREATE TABLE monk_processes (
+  id BIGINT GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
+  hostname TEXT NOT NULL,
+  pid INTEGER NOT NULL,
+  started_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+  last_heartbeat_at TIMESTAMPTZ NOT NULL DEFAULT now()
+);

data/lib/monk/templates/live/{config.ru → app/app.rb}

@@ -1,8 +1,5 @@
-require_relative "config/settings"
-require_relative "config/live"
-
 class App < Monk::Base
-  views "views"
+  views "app/views"
   layout "layouts/app"
   assets "public"
 
@@ -23,5 +20,3 @@ class App < Monk::Base
   get("/hello") { "hello from monk" }
   get("/api/hello") { json(message: "hello from monk") }
 end
-
-run Monk.boot(App)

data/lib/monk/templates/live/{views → app/views}/index.erb

@@ -12,7 +12,7 @@
 
 <p>
   The pieces: <code>live_topic</code> in this view, the partial
-  <code>views/live/_hits.erb</code>, <code>Monk::Live.patch</code> in
-  <code>POST /hit</code> (<code>config.ru</code>), and the rules and Redis
+  <code>app/views/live/_hits.erb</code>, <code>Monk::Live.patch</code> in
+  <code>POST /hit</code> (<code>app/app.rb</code>), and the rules and Redis
   wiring in <code>config/live.rb</code>.
 </p>

data/lib/monk/templates/live/bin/websocket_server

@@ -13,11 +13,23 @@ end
 
 # Monk::Live: the browsers' sockets end here. The handler takes their
 # subscribe/unsubscribe messages, checks each topic against the rules in
-# config/live.rb, and relays whatever config.ru's process publishes over
+# config/live.rb, and relays whatever bin/server's process publishes over
 # Redis.
 require_relative "../config/live"
 
-authenticate = defined?(Monk::Auth) && !!Monk::Auth.config
+# This process holds the browsers' sockets, so it's the only one that
+# listens for updates published elsewhere (bin/server, bin/jobs): the
+# fanout's subscriber connection is opened here, at boot, and an
+# unreachable Redis/Postgres fails right here.
+Monk::Live.listen!
+
+# With Monk::Auth (--auth), a socket with a valid session gets its user,
+# and one without -- a visitor, or a session since revoked -- comes in
+# anonymous instead of refused. The rules in config/live.rb decide what
+# each may subscribe to: a topic is open to visitors only if its rule says
+# `anonymous: true`, like the demo's "hits". Without Monk::Auth every
+# socket is anonymous.
+authenticate = defined?(Monk::Auth) && Monk::Auth.config ? :optional : false
 port = ENV.fetch("WS_PORT", "9293").to_i
 # Defaults to public_url (config/settings.rb) so one PUBLIC_URL env var
 # keeps this in sync with the app's actual origin instead of two vars

data/lib/monk/templates/live/config/live.rb

@@ -1,4 +1,4 @@
-# Monk::Live wiring, required by both processes: config.ru (this app
+# Monk::Live wiring, required by both processes: config/load.rb (this app
 # publishes updates, e.g. from a route) and bin/websocket_server (the browsers'
 # sockets terminate there and are handed the updates).
 #

data/lib/monk/templates/live/config/live_pg.rb

@@ -1,4 +1,4 @@
-# Monk::Live wiring, required by both processes: config.ru (this app
+# Monk::Live wiring, required by both processes: config/load.rb (this app
 # publishes updates, e.g. from a route) and bin/websocket_server (the browsers'
 # sockets terminate there and are handed the updates).
 #

data/lib/monk/templates/mail/config/mail.rb

@@ -2,8 +2,8 @@ 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
+# any route -- and, with --auth, the magic links AppMailer::MAGIC_LINK
+# (app/mailers/app_mailer.rb) delivers. See docs/guides/mail.md. Required from config/load.rb (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

data/lib/monk/templates/postgres/Dockerfile

@@ -25,6 +25,8 @@ COPY . .
 # platform that assigns its own). bin/websocket_server (WS_PORT default
 # 9293) is a separate process/deploy unit -- run this same image with
 # `bin/websocket_server` as the command instead of publishing another
-# port from this Dockerfile -- see docs/guides/deploying.md.
+# port from this Dockerfile -- see docs/guides/deploying.md. With --jobs,
+# bin/jobs is another one, the same way: this image, `bin/jobs` as the
+# command, no port at all.
 EXPOSE 9292
 CMD ["bin/server", "--bind", "0.0.0.0"]

data/lib/monk/templates/postgres/bin/console

@@ -1,7 +1,9 @@
 #!/usr/bin/env ruby
 require "bundler/setup"
-require_relative "../config/settings"
-require_relative "../config/persistence"
+# The configs and app/ (models, jobs, mailers...), as the app sees them --
+# config/load.rb, never Monk.boot, so nothing is frozen and you can poke at
+# anything.
+require_relative "../config/load"
 require "irb"
 
 IRB.start(__FILE__)

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.17.0".freeze
+  VERSION = "0.19.0".freeze
 end

data/lib/monk/websocket/errors.rb

@@ -12,5 +12,16 @@ module Monk
     # tradeoff.
     class PayloadTooLargeError < StandardError
     end
+
+    # A fanout's #register before its #listen!: a socket registered there
+    # would never get another process's broadcasts, so this says so at the
+    # first subscription instead of losing them silently.
+    class NotListeningError < StandardError
+    end
+
+    # #listen! couldn't open its subscriber connection (Redis or Postgres
+    # unreachable, bad credentials) -- raised in the WS process's boot.
+    class ListenError < StandardError
+    end
   end
 end

data/lib/monk/websocket/listeners.rb

@@ -0,0 +1,23 @@
+module Monk
+  module WebSocket
+    # Which fanouts in this process have called #listen!, by origin id.
+    # A fanout freezes itself (every connection Ractor reads it through a
+    # module constant), so it can't record this on itself; a frozen list
+    # in a module ivar is written from the main Ractor, where #listen! runs
+    # at boot, and read from any Ractor, where #register runs.
+    module Listeners
+      @origins = [].freeze
+
+      class << self
+        def listening?(origin) = @origins.include?(origin)
+
+        # Main Ractor only -- a module ivar write from another Ractor raises
+        # Ractor::IsolationError, which is the right answer for a boot-time
+        # call made from the wrong place.
+        def add(origin)
+          @origins = Ractor.make_shareable([*@origins, origin])
+        end
+      end
+    end
+  end
+end

data/lib/monk/websocket/pg_fanout.rb

@@ -1,5 +1,7 @@
 require "pg"
 require "securerandom"
+require_relative "errors"
+require_relative "listeners"
 
 module Monk
   module WebSocket
@@ -7,7 +9,7 @@ module Monk
     # "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,
+    # #broadcast, #listen!, 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
@@ -53,15 +55,11 @@ module Monk
       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.
+        # Checked upfront, on the argument -- 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. 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}"
@@ -79,20 +77,43 @@ module Monk
         @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
+        # #listen! starts, both of which raise Ractor::IsolationError on an
         # unfrozen value -- same reason RedisFanout freezes its own
         # @origin.
         @origin = SecureRandom.uuid.freeze
 
+        freeze
+      end
+
+      # Starts relaying other processes' broadcasts into this process's
+      # registry: a subscriber Ractor with its own LISTEN connection. Only
+      # the process that holds sockets calls this (bin/websocket_server, at
+      # boot, from the main Ractor) -- a publish-only process (bin/server,
+      # bin/jobs) never does, so it holds no LISTEN connection at all.
+      # Returns once the LISTEN is in effect, so nothing notified after it
+      # can be missed; raises ListenError if Postgres can't be reached.
+      # Calling it again is a no-op.
+      def listen!
+        return self if Listeners.listening?(@origin)
+
+        ready = Ractor::Port.new
         # 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}")
+        # shareable), @pg_opts and @origin are already made so, a Port
+        # always is. 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.
+        Ractor.new(@registry, @pg_opts, @origin, ready) do |registry, pg_opts, own_origin, ready|
+          begin
+            conn = PG.connect(**pg_opts)
+            conn.exec("LISTEN #{Monk::WebSocket::PgFanout::CHANNEL}")
+          rescue StandardError => e
+            ready.send("#{e.class}: #{e.message}")
+            next
+          end
+          ready.send(:ok)
+
           loop do
             conn.wait_for_notify do |_channel, _pid, raw|
               sender, key, payload = Monk::WebSocket::PgFanout.decode_envelope(raw)
@@ -103,10 +124,24 @@ module Monk
           end
         end
 
-        freeze
+        result = ready.receive
+        raise ListenError, "Monk::WebSocket::PgFanout#listen! couldn't LISTEN: #{result}" unless result == :ok
+
+        Listeners.add(@origin)
+        self
+      end
+
+      def register(key, port)
+        unless Listeners.listening?(@origin)
+          raise NotListeningError,
+            "Monk::WebSocket::PgFanout#register before #listen!: this socket would never get " \
+            "other processes' broadcasts -- call listen! once at boot in the process that holds " \
+            "sockets (bin/websocket_server: Monk::Live.listen!)"
+        end
+
+        @registry.register(key, port)
       end
 
-      def register(key, port) = @registry.register(key, port)
       def unregister(key, port) = @registry.unregister(key, port)
       def count(key) = @registry.count(key)