monkrb 0.15.0

data/lib/monk/websocket/redis_fanout.rb

@@ -0,0 +1,103 @@
+require "redis"
+require "securerandom"
+
+module Monk
+  module WebSocket
+    # Cross-process fan-out for Registry, opt-in: require
+    # "monk/websocket/redis_fanout" explicitly -- "monk/websocket" alone
+    # does not load this (docs/history/plan-websocket.md Phase 6, chosen over Postgres
+    # LISTEN/NOTIFY per docs/design/websocket.md Open Question 3).
+    #
+    # Wraps a Registry with the same public interface (#register,
+    # #unregister, #count, #broadcast), so an app swaps which object it
+    # holds and nothing else changes. #broadcast still delivers to this
+    # process's local Registry directly -- same latency and reliability as
+    # a plain Registry if Redis is briefly unavailable -- and additionally
+    # publishes to Redis so sibling WS processes' subscriber Ractors
+    # deliver it to their own local connections.
+    #
+    # Every published payload is tagged with this instance's origin id so
+    # the subscriber ignores messages that are this process's own
+    # broadcast echoed back over Redis -- without the tag, a broadcast
+    # would reach local connections twice (once directly, once via the
+    # round trip through Redis).
+    #
+    # #broadcast/#register keys must be Symbols. A Redis channel name is
+    # always a String, so the subscriber has to pick one Ruby type to
+    # convert the recovered channel back into -- Symbol, matching every
+    # existing caller (Registry's own tests, the websocket_server
+    # scaffold's :chat channel). A String-keyed #register(...) would still
+    # get this process's own direct/local deliveries but never a relayed
+    # one, since the relayed call always uses a Symbol.
+    class RedisFanout
+      # Frozen explicitly, not just left as a String literal -- the
+      # subscriber Ractor below reads this constant from a non-main
+      # Ractor, which raises Ractor::IsolationError unless its value is
+      # already shareable.
+      CHANNEL_PREFIX = "monk:ws:".freeze
+
+      def initialize(registry, redis_url:)
+        @registry = registry
+        @redis_url = redis_url.dup.freeze
+        @origin = SecureRandom.uuid.freeze
+
+        # Ractor.new's block args must be shareable: registry is (Registry
+        # freezes itself around a Ractor, which is inherently shareable),
+        # redis_url and @origin are plain frozen Strings. The Redis client
+        # itself is built inside the block, never passed in -- mirrors
+        # PG::Connection's per-Ractor pattern (persistence/pg.rb).
+        @subscriber = Ractor.new(registry, @redis_url, @origin) do |registry, url, origin|
+          Redis.new(url: url).psubscribe("#{Monk::WebSocket::RedisFanout::CHANNEL_PREFIX}*") do |on|
+            on.pmessage do |_pattern, channel, envelope|
+              sender, payload = envelope.split("\0", 2)
+              next if sender == origin
+
+              # Redis channel names are always Strings, but Registry's own
+              # keys are ordinary Hash keys the app chooses -- every
+              # existing caller (Registry's own tests, the websocket_server
+              # scaffold's :chat channel) uses a Symbol. #to_sym here is
+              # what makes registry.broadcast(:chat, ...) land on the same
+              # Hash key #register(:chat, port) used -- without it this
+              # silently broadcasts to an unrelated "chat" String key that
+              # nothing is ever registered under, and #broadcast still
+              # returns true either way (Registry#broadcast succeeds
+              # whether or not any port is registered for a key).
+              key = channel.delete_prefix(Monk::WebSocket::RedisFanout::CHANNEL_PREFIX).to_sym
+              registry.broadcast(key, payload)
+            end
+          end
+        end
+
+        # No live connection lives on this object -- #publisher below opens
+        # one per Ractor, lazily -- so there's nothing left unshareable and
+        # this instance can freeze itself the same way Registry does. That
+        # matters for real use: an app holds this behind a module constant
+        # (e.g. ChatServer::REGISTRY, mirroring Registry's own existing
+        # usage) read from every connection's own Ractor, which raises
+        # Ractor::IsolationError unless the constant's value is shareable.
+        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)
+        @registry.broadcast(key, payload)
+        publisher.publish("#{CHANNEL_PREFIX}#{key}", "#{@origin}\0#{payload}")
+      end
+
+      private
+
+      # A single shared Redis client called concurrently from every
+      # connection Ractor's #broadcast wouldn't be safe -- redis-rb clients
+      # aren't documented safe for concurrent commands from multiple
+      # threads, let alone Ractors. One client per calling Ractor, opened
+      # on first use and cached there, mirrors
+      # Monk::Persistence::Registry's #ractor_local/#entry exactly.
+      def publisher
+        Ractor.current[:monk_redis_fanout_publisher] ||= Redis.new(url: @redis_url)
+      end
+    end
+  end
+end

data/lib/monk/websocket/registry.rb

@@ -0,0 +1,92 @@
+module Monk
+  module WebSocket
+    # A dedicated Ractor holding the live set of connection handles keyed by
+    # an app-assigned channel/subject -- mirrors StateRactor's shape
+    # (docs/design/ractor.md): the mutable Hash stays hidden inside this one
+    # Ractor, and every call is a synchronous "ask" via a fresh
+    # Ractor::Port, so registration/broadcast can never race each other.
+    class Registry
+      def initialize
+        @ractor = Ractor.new do
+          keys = Hash.new { |h, k| h[k] = [] }
+
+          loop do
+            op, key, arg, reply_port = Ractor.receive
+            result =
+              case op
+              when :register
+                keys[key] << arg unless keys[key].include?(arg)
+                true
+              when :unregister
+                keys[key].delete(arg)
+                true
+              when :broadcast
+                # A port can be closed out from under this loop without
+                # ever going through #unregister -- e.g. the owning
+                # connection Ractor dies before its own cleanup runs.
+                # port.send on a closed port raises Ractor::ClosedError;
+                # left unguarded, that exception would propagate out of
+                # this single-threaded loop and kill the *registry*
+                # Ractor, taking down delivery for every key, not just
+                # this one. Rescuing it here, per port, keeps the
+                # broadcast going for every other subscriber and also
+                # drops the dead port from keys[key] -- self-healing the
+                # stale entry #unregister was supposed to have caught.
+                keys[key].reject! do |port|
+                  port.send(arg)
+                  false
+                rescue Ractor::ClosedError
+                  true
+                end
+                true
+              when :count
+                keys[key].size
+              end
+            reply_port.send(result)
+          end
+        end
+        freeze
+      end
+
+      def register(key, port)
+        ask(:register, key, port)
+      end
+
+      def unregister(key, port)
+        ask(:unregister, key, port)
+      end
+
+      def broadcast(key, payload)
+        ask(:broadcast, key, payload)
+      end
+
+      # Not part of Phase 4's own plan bullets, but needed to actually
+      # observe step 17's "a crashed handler never leaks a stale registry
+      # entry" claim from outside the registry, rather than trusting it.
+      def count(key)
+        ask(:count, key, nil)
+      end
+
+      private
+
+      def ask(op, key, arg)
+        reply_port = Ractor::Port.new
+        @ractor.send([op, key, arg, reply_port])
+        reply_port.receive
+      rescue Ractor::ClosedError
+        # The registry Ractor itself can be gone by the time this runs --
+        # e.g. process-wide shutdown (Ctrl+C) tearing down Ractors in
+        # whatever order, with a connection's own cleanup (Connection#
+        # unsubscribe!, called from Server.serve's ensure) losing the race
+        # against the registry's. Nothing on the other end to reply to a
+        # dead call anyway; nil is indistinguishable from "the process is
+        # already exiting" to every caller here (register/unregister/
+        # broadcast ignore their return value, and #count is never read
+        # this late).
+        nil
+      ensure
+        reply_port&.close
+      end
+    end
+  end
+end

data/lib/monk/websocket/server.rb

@@ -0,0 +1,234 @@
+require "socket"
+
+module Monk
+  module WebSocket
+    # Intended to be the entire body of a small standalone script (e.g.
+    # bin/websocket_server) -- never embedded in the same process as Kino
+    # (docs/history/plan-websocket.md Decision 1).
+    class Server
+      # allowed_origins: and authenticate: implement docs/history/plan-websocket.md
+      # Phase 5 (identity via Monk::Auth, reused unmodified -- Decision
+      # 5). authenticate: defaults false so a plain server (Phases 1-4)
+      # behaves exactly as before; turning it on requires Monk::Auth to
+      # already be configured, fail-fast the same way Monk::Auth's own
+      # methods do (ADR 0003) rather than failing obscurely on the first
+      # connection.
+      #
+      # ping_interval: (seconds) opts a connection into a server-sent
+      # heartbeat ping -- see Connection#start_heartbeat. Defaults to nil
+      # (disabled) for the same reason authenticate: defaults false: a
+      # server that doesn't ask for it behaves exactly as before.
+      #
+      # reverify_interval: (seconds) re-runs Monk::Auth.verify against the
+      # same credential on that cadence for as long as the connection
+      # stays open, closing it the moment verify comes back nil (gap 4,
+      # docs/history/chat-gap-analysis.md) -- authenticate: true only checks the
+      # credential once, at the handshake, so a session revoked or
+      # expired afterward would otherwise leave the socket live
+      # indefinitely. Requires authenticate: true (there's no credential
+      # to reverify without it) and defaults to nil (disabled), same as
+      # ping_interval:.
+      #
+      # max_payload_size: (bytes) -- see Connection::DEFAULT_MAX_PAYLOAD_SIZE
+      # for what it guards against (gap 5). Unlike ping_interval:/
+      # reverify_interval:, always on: this is insurance against a
+      # hostile client on a public endpoint, not an opt-in behavior
+      # change, so a server that doesn't mention it still gets the
+      # default cap rather than no cap at all.
+      def initialize(
+        port:, bind: "0.0.0.0", allowed_origins: nil, authenticate: false, ping_interval: nil,
+        reverify_interval: nil, max_payload_size: Connection::DEFAULT_MAX_PAYLOAD_SIZE
+      )
+        if ping_interval && !ping_interval.positive?
+          raise ArgumentError, "ping_interval must be positive, got #{ping_interval.inspect}"
+        end
+
+        if reverify_interval
+          unless reverify_interval.positive?
+            raise ArgumentError, "reverify_interval must be positive, got #{reverify_interval.inspect}"
+          end
+          raise ArgumentError, "reverify_interval requires authenticate: true" unless authenticate
+        end
+
+        unless max_payload_size.positive?
+          raise ArgumentError, "max_payload_size must be positive, got #{max_payload_size.inspect}"
+        end
+
+        if authenticate
+          unless defined?(Monk::Auth) && Monk::Auth.config
+            raise Monk::AuthNotConfiguredError,
+              "Monk::WebSocket::Server.new(authenticate: true) requires Monk::Auth to already be " \
+              "configured -- call Monk::Auth.configure first"
+          end
+
+          # Monk::Auth's config is a plain, unfrozen Hash until this runs
+          # (lib/monk/freeze_hooks.rb) -- without it, the first
+          # Monk::Auth.verify call from inside a connection Ractor raises
+          # Ractor::IsolationError (docs/history/plan-websocket.md Phase 5 step 20).
+          # Called here, not left to the boot script to remember, the same
+          # way Base.call already auto-freezes on first use rather than
+          # trusting every app to call Base.freeze! itself.
+          Monk.freeze!
+        end
+
+        @tcp_server = TCPServer.new(bind, port)
+        @allowed_origins = allowed_origins ? Ractor.make_shareable(allowed_origins.dup) : nil
+        @authenticate = authenticate
+        @ping_interval = ping_interval
+        @reverify_interval = reverify_interval
+        @max_payload_size = max_payload_size
+      end
+
+      def port
+        @tcp_server.addr[1]
+      end
+
+      def run(&block)
+        shareable_block =
+          begin
+            Ractor.make_shareable(block)
+          rescue ArgumentError, Ractor::IsolationError => e
+            raise Monk::UnshareableBlockError,
+              "Monk::WebSocket::Server#run block is not Ractor-shareable: #{e.message} " \
+              "(build it where self is shareable, e.g. at class-body scope, not inline in a script's " \
+              "top-level block -- mirrors StateRactor#update's own constraint)"
+          end
+
+        loop do
+          socket = @tcp_server.accept
+          ractor = Ractor.new(
+            shareable_block, @authenticate, @allowed_origins, @ping_interval, @reverify_interval, @max_payload_size
+          ) do |blk, authenticate, origins, ping_interval, reverify_interval, max_payload_size|
+            Monk::WebSocket::Server.serve(
+              Ractor.receive, blk,
+              authenticate: authenticate, allowed_origins: origins,
+              ping_interval: ping_interval, reverify_interval: reverify_interval, max_payload_size: max_payload_size
+            )
+          end
+          ractor.send(socket, move: true)
+        end
+      rescue Interrupt
+        # Ctrl+C's default Ruby behavior: raise Interrupt in the thread
+        # blocked in the syscall, here TCPServer#accept. Unrescued, that's
+        # an unhandled exception -- Ruby prints its backtrace and exits
+        # non-zero, which reads as a crash even though this is the normal,
+        # intended way to stop a long-running server. Registry#ask's
+        # Ractor::ClosedError rescue (registry.rb) guards a different
+        # failure point in this same shutdown -- a live connection's
+        # cleanup racing the registry Ractor's teardown -- not this one.
+        @tcp_server.close
+      end
+
+      # Runs entirely inside the connection's own dedicated Ractor
+      # (docs/history/plan-websocket.md Decision 3) -- a class method, not an instance
+      # method, since the Server instance itself (holding a live
+      # TCPServer) is never Ractor-shareable and can't cross into here.
+      def self.serve(
+        socket, block, authenticate: false, allowed_origins: nil, ping_interval: nil, reverify_interval: nil,
+        max_payload_size: Connection::DEFAULT_MAX_PAYLOAD_SIZE
+      )
+        request = read_handshake_request(socket)
+        return socket.close unless request
+
+        headers =
+          begin
+            Handshake.parse_request(request)
+          rescue Monk::WebSocket::HandshakeError
+            return socket.write("HTTP/1.1 400 Bad Request\r\n\r\n")
+          end
+
+        subject = nil
+        if authenticate
+          subject = authenticate!(socket, headers, allowed_origins)
+          return unless subject
+        end
+
+        socket.write(Handshake.response_for(request))
+
+        connection = Connection.new(socket, subject: subject, max_payload_size: max_payload_size)
+        connection.start_heartbeat(ping_interval) if ping_interval
+        reverify_thread =
+          if reverify_interval
+            start_reverify(connection, Handshake.credential_from(headers)[:token], reverify_interval)
+          end
+        begin
+          block.call(connection)
+        rescue StandardError
+          # Isolates this connection's failure to its own Ractor
+          # (docs/history/plan-websocket.md step 12): neither the accept loop nor any
+          # other connection's Ractor is affected. Deliberately swallowed,
+          # not re-raised -- there's no caller left to hand it to once
+          # we're inside this connection's own dedicated Ractor.
+        end
+      ensure
+        # Runs on every exit path -- normal completion, the close
+        # handshake, and a crashed handler alike -- so a subscribed
+        # connection never leaks a stale registry entry (step 17), a
+        # heartbeat thread, or a reverify thread outliving its socket.
+        reverify_thread&.kill
+        connection&.unsubscribe!
+        connection&.stop_heartbeat!
+        socket.close
+      end
+
+      # docs/history/plan-websocket.md steps 22-23: the Origin allowlist check runs
+      # before Monk::Auth.verify, and only for a cookie-derived
+      # credential -- a Bearer connection has no Origin header to check
+      # by construction (mirrors require_csrf!'s own Bearer exemption in
+      # docs/history/plan-auth.md). Returns the verified subject, or nil after writing
+      # the appropriate 403/401 response itself.
+      def self.authenticate!(socket, headers, allowed_origins)
+        credential = Handshake.credential_from(headers)
+
+        if credential&.fetch(:via) == :cookie && allowed_origins
+          origin = headers["origin"]
+          unless origin && allowed_origins.include?(origin)
+            socket.write("HTTP/1.1 403 Forbidden\r\n\r\n")
+            return nil
+          end
+        end
+
+        subject = credential && Monk::Auth.verify(credential[:token])
+        socket.write("HTTP/1.1 401 Unauthorized\r\n\r\n") unless subject
+        subject
+      end
+      private_class_method :authenticate!
+
+      # Sleeps in `interval`-sized steps, re-running Monk::Auth.verify
+      # against the same raw credential each time, until it comes back
+      # nil (revoked or expired) -- then closes the connection with the
+      # standard "policy violation" close code, the one bit of RFC 6455's
+      # registered code space that fits "this session is no longer
+      # authorized" without inventing an app-specific one. Runs in its
+      # own Thread rather than blocking the handler's own read loop,
+      # mirroring Connection#start_heartbeat's shape; killed from #serve's
+      # ensure the same way.
+      def self.start_reverify(connection, raw_token, interval)
+        Thread.new do
+          loop do
+            sleep interval
+            break unless Monk::Auth.verify(raw_token)
+          end
+          connection.close(code: 1008, reason: "session no longer valid")
+        rescue IOError, Errno::EPIPE, Errno::ECONNRESET
+          # The connection already closed via some other path (normal
+          # disconnect, the close handshake, a dead ping) -- nothing left
+          # to close.
+        end
+      end
+      private_class_method :start_reverify
+
+      def self.read_handshake_request(socket)
+        request = +""
+        until request.end_with?("\r\n\r\n")
+          chunk = socket.read(1)
+          return nil if chunk.nil?
+
+          request << chunk
+        end
+        request
+      end
+      private_class_method :read_handshake_request
+    end
+  end
+end

data/lib/monk/websocket.rb

@@ -0,0 +1,19 @@
+require_relative "errors"
+# Standalone, dependency-free -- required here so Server.new(authenticate:
+# true) always raises this precise error, per ADR 0003, rather than a bare
+# NameError when an app calls it without ever requiring "monk/auth" at all.
+require_relative "auth/errors"
+require_relative "websocket/errors"
+require_relative "websocket/handshake"
+require_relative "websocket/frame"
+require_relative "websocket/connection"
+require_relative "websocket/server"
+require_relative "websocket/registry"
+
+# Opt-in, like Monk::Persistence backends and Monk::Auth: require
+# "monk/websocket" explicitly. `require "monk"` alone must not load this
+# (docs/history/plan-websocket.md Decision 7).
+module Monk
+  module WebSocket
+  end
+end

data/lib/monk.rb

@@ -0,0 +1,45 @@
+require_relative "monk/version"
+require_relative "monk/settings"
+require_relative "monk/environment"
+require_relative "monk/errors"
+require_relative "monk/views"
+require_relative "monk/assets"
+require_relative "monk/log"
+require_relative "monk/context"
+require_relative "monk/persistence/errors"
+require_relative "monk/state_ractor"
+require_relative "monk/persistence"
+require_relative "monk/persistence/model"
+require_relative "monk/base"
+
+# Persistence backends (Monk::Persistence::Pg, and any future adapter) are
+# opt-in -- require them explicitly, e.g. `require "monk/persistence/pg"`.
+
+module Monk
+  def self.boot(app)
+    app.freeze!
+
+    app_class = app.is_a?(Class) ? app : app.class
+    parts = ['', "Monk #{VERSION} plays!", " - env=#{env}", " - routes=#{app_class.routes.size}"]
+    parts << " - auth=on" if defined?(Auth) && Auth.config
+    backends = persistence_backends
+    parts << " - persistence=#{backends.join(",")}" unless backends.empty?
+    parts << "\n"
+
+    $stdout.puts parts.join("\n")
+    app
+  end
+
+  # Backend module name (e.g. "pg") + its registered connection names
+  # (e.g. "primary"), for every Persistence::Registry backend actually in
+  # use -- Monk.freeze_hooks already lists every such module (each one
+  # extends Registry and adds itself there), so this just filters that
+  # list down to the ones with something registered, rather than keeping
+  # a second registry of backends.
+  def self.persistence_backends
+    freeze_hooks
+      .select { |hook| hook.is_a?(Module) && hook.singleton_class.include?(Persistence::Registry) }
+      .filter_map { |hook| "#{hook.name.split("::").last.downcase}:#{hook.names.join(",")}" if hook.names.any? }
+  end
+  private_class_method :persistence_backends
+end