monkrb 0.15.0

data/lib/monk/templates/postgres/bin/migrate

@@ -0,0 +1,22 @@
+#!/usr/bin/env ruby
+require "bundler/setup"
+require_relative "../config/settings"
+require_relative "../config/persistence"
+require "monk/persistence/pg/migrator"
+
+migrator = Monk::Persistence::Pg::Migrator.new(db_name: :primary, dir: File.expand_path("../db/migrate", __dir__))
+
+case ARGV[0]
+when nil, "migrate"
+  applied = migrator.migrate!
+  puts applied.empty? ? "Nothing to migrate." : "Applied: #{applied.join(", ")}"
+when "rollback"
+  reverted = migrator.rollback!(steps: (ARGV[1] || 1).to_i)
+  puts reverted.empty? ? "Nothing to roll back." : "Reverted: #{reverted.join(", ")}"
+when "status"
+  puts "Applied: #{migrator.applied.join(", ")}"
+  puts "Pending: #{migrator.pending.join(", ")}"
+else
+  warn "Usage: bin/migrate [migrate|rollback [N]|status]"
+  exit 1
+end

data/lib/monk/templates/postgres/bin/setup_db

@@ -0,0 +1,9 @@
+#!/usr/bin/env ruby
+require "bundler/setup"
+require_relative "../config/settings"
+require_relative "../config/persistence"
+require "monk/persistence/pg/migrator"
+
+Monk::Persistence::Pg::Migrator.new(db_name: :primary, dir: File.expand_path("../db/migrate", __dir__)).migrate!
+
+puts "Migrated #{ENV.fetch("DB_NAME", "app_development")}."

data/lib/monk/templates/postgres/config/persistence.rb

@@ -0,0 +1,10 @@
+require "monk"
+require "monk/persistence/pg"
+
+Monk::Persistence::Pg.register(:primary,
+  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"),
+)

data/lib/monk/templates/redis/Gemfile.extra

@@ -0,0 +1 @@
+gem "redis"

data/lib/monk/version.rb

@@ -0,0 +1,9 @@
+module Monk
+  # Frozen, not just a plain literal: reading a String constant from a
+  # non-main Ractor raises Ractor::IsolationError unless it's shareable,
+  # and a frozen String with no unshareable ivars qualifies -- the same
+  # 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
+end

data/lib/monk/views.rb

@@ -0,0 +1,175 @@
+require "erb"
+require "cgi/escape"
+
+require_relative "freeze_hooks"
+require_relative "errors"
+
+module Monk
+  # ERB templates, compiled once at Boot into real instance methods on a
+  # module that Context includes, then frozen. Never compiled at request
+  # time -- see docs/design/views.md for why that isn't a preference: a worker
+  # Ractor can't hold a template cache (shared mutable state) and mustn't
+  # install methods on a shared module, so the lazy-compile-and-cache
+  # design every other Ruby template engine uses is unavailable here.
+  #
+  # What that buys, beyond safety: a template's syntax error fails the
+  # boot naming file and line (ADR 0003's posture, applied to views), and
+  # a render is a plain method call (~2.6us for a small template) rather
+  # than an eval.
+  module Views
+    # An already-safe fragment: `h` passes it through instead of escaping
+    # it. #to_s must return self, because ERB::Compiler hardcodes
+    # `insert_cmd((expr).to_s)` and String#to_s downgrades a subclass
+    # instance to a plain String -- which would silently strip the marker.
+    class Raw < String
+      def to_s
+        self
+      end
+    end
+
+    # Compiled template methods land here; Monk::Context includes it, so
+    # `self` inside a template is the request's Context and bare `params`,
+    # `render`, ivars set by the route, and every other Context helper
+    # resolve exactly as they do in a route block.
+    module Compiled
+    end
+
+    DEFAULT_ROOT = "views".freeze
+
+    class << self
+      # Every reader here is a plain attr_reader over an ivar initialized
+      # eagerly below, never `@x ||= ...`: a lazy reader *writes* on first
+      # access, and writing a module ivar from a non-main Ractor is an
+      # isolation error. The request path only ever reads.
+      attr_reader :root, :layout, :registry
+      attr_writer :root, :layout
+
+      # Escapes unless the value is already Raw, and returns Raw either
+      # way -- so an explicit `<%= h(x) %>` isn't escaped twice by the
+      # implicit `h` the compiler wraps every `<%= %>` in.
+      # CGI.escapeHTML, not ERB::Util.html_escape, though they produce
+      # byte-identical output: ERB's is not flagged Ractor-safe, so a
+      # worker calling it raises Ractor::UnsafeError ("ractor unsafe
+      # method called from not main ractor"). Found by
+      # test/ractor_integration_test.rb, in a real worker, not by reading
+      # either implementation.
+      def h(value)
+        return value if value.is_a?(Raw)
+
+        Raw.new(CGI.escapeHTML(value.to_s))
+      end
+
+      def compile(name, source, path = "(erb)")
+        method_name = method_name_for(name)
+        # method_name_for deliberately reuses the same method name across
+        # repeated boots of the same template path (see its comment), so a
+        # second freeze in one process -- a second app, or the test suite --
+        # redefines this method rather than growing a new one. Ruby warns
+        # ("method redefined; discarding old ...") whenever a `def`
+        # overwrites an existing method, but not when the old one was
+        # explicitly removed first -- so remove it ourselves to keep that
+        # warning from firing on a redefinition this module intends.
+        Compiled.remove_method(method_name) if Compiled.method_defined?(method_name)
+        Compiled.module_eval("def #{method_name}(locals = {}); #{compiled_source(source)}; end", path, 0)
+        registry[name] = method_name
+        name
+      rescue SyntaxError => e
+        raise Monk::TemplateSyntaxError, e.message.lines.first.to_s.chomp
+      end
+
+      def render(context, name, locals, layout: :default)
+        outer = !context.rendering
+        context.rendering = true
+        inner = invoke(context, name, locals)
+        wrapper = layout == :default ? (outer ? self.layout : nil) : layout
+        wrapper ? invoke(context, wrapper, locals) { inner } : inner
+      ensure
+        context.rendering = false if outer
+      end
+
+      # Called from Base#freeze! (Seam B), via Monk.freeze_hooks: compile
+      # every template under `root`, then seal the registry so worker
+      # Ractors can read it. #dup first, so booting twice in one process
+      # (two apps, or a test suite) doesn't hit the frozen hash.
+      def freeze_registry!
+        @registry = registry.dup
+        compile_all!
+
+        if @layout && !@registry.key?(@layout)
+          raise Monk::TemplateNotFoundError,
+            "layout #{@layout.inspect} doesn't exist (looked under #{root.inspect}; " \
+            "known: #{@registry.keys.sort.inspect})"
+        end
+
+        @registry = Ractor.make_shareable(@registry)
+        # #root and #layout are read on the request path (the not-found
+        # message, layout resolution), and an unfrozen String in a module
+        # ivar is unreadable from a worker Ractor at all -- the same
+        # restriction Persistence::Registry#freeze_registry! exists for.
+        @root = root.freeze
+        @layout = layout.freeze
+      end
+
+      # Test-only: forgets every compiled template. The methods stay
+      # defined on Compiled (harmless -- they're unreachable once the
+      # registry no longer names them), since a module can't undefine
+      # itself back to a clean slate cheaply.
+      def reset!
+        @registry = {}
+        @root = DEFAULT_ROOT
+        @layout = nil
+      end
+
+      private
+
+      def compile_all!
+        return unless root && Dir.exist?(root)
+
+        Dir.glob("**/*.erb", base: root).sort.each do |relative|
+          path = File.join(root, relative)
+          compile(relative.delete_suffix(".erb"), File.read(path), path)
+        end
+      end
+
+      def invoke(context, name, locals, &block)
+        method_name = registry.fetch(name) do
+          raise Monk::TemplateNotFoundError,
+            "no template #{name.inspect} (looked under #{root.inspect}; " \
+            "known: #{registry.keys.sort.inspect})"
+        end
+
+        context.send(method_name, locals, &block)
+      end
+
+      # `<%= %>` escapes by default -- a deliberate break from stock ERB,
+      # where it doesn't. ERB::Compiler emits `insert_cmd((expr).to_s)`
+      # for every insertion, so pointing insert_cmd at Views.h is the
+      # whole implementation; `raw(x)` opts back out.
+      def compiled_source(source)
+        compiler = ERB::Compiler.new("-")
+        compiler.pre_cmd = ["_erbout = +''"]
+        compiler.post_cmd = ["Monk::Views::Raw.new(_erbout)"]
+        compiler.put_cmd = "_erbout.<<"
+        compiler.insert_cmd = "_erbout.<< Monk::Views.h"
+        compiler.compile(source).first
+      end
+
+      def method_name_for(name)
+        return registry[name] if registry.key?(name)
+
+        base = "__monk_view_#{name.gsub(/[^A-Za-z0-9_]/, "_")}"
+        return base unless Compiled.method_defined?(base)
+
+        suffix = 2
+        suffix += 1 while Compiled.method_defined?("#{base}_#{suffix}")
+        "#{base}_#{suffix}"
+      end
+    end
+
+    @registry = {}
+    @root = DEFAULT_ROOT
+    @layout = nil
+
+    Monk.freeze_hooks << self
+  end
+end

data/lib/monk/websocket/connection.rb

@@ -0,0 +1,226 @@
+module Monk
+  module WebSocket
+    # Monk's Context-equivalent for a WS connection (docs/history/plan-websocket.md step
+    # 10): the socket and frame machinery are never exposed directly to app
+    # code. Lives entirely inside its own connection Ractor -- never itself
+    # crosses a Ractor boundary, so it needs no shareability of its own.
+    class Connection
+      # 1 MiB -- generous for chat-sized text, cheap insurance against a
+      # hostile length claim on a public endpoint (gap 5,
+      # docs/history/chat-gap-analysis.md). Enforced twice: against a single
+      # frame's declared length (#read_frame, before the payload is ever
+      # read off the wire) and against a fragmented message's reassembled
+      # total (#read) -- otherwise chunking a message into many frames
+      # each just under the per-frame cap would silently bypass it.
+      DEFAULT_MAX_PAYLOAD_SIZE = 1 * 1024 * 1024
+
+      # subject is whatever Monk::Auth.verify returned when
+      # Server.new(authenticate: true) verified this handshake
+      # (docs/history/plan-websocket.md Phase 5) -- nil for an unauthenticated server.
+      attr_reader :subject
+
+      def initialize(socket, subject: nil, max_payload_size: DEFAULT_MAX_PAYLOAD_SIZE)
+        @socket = socket
+        @subject = subject
+        @write_mutex = Mutex.new
+        @max_payload_size = max_payload_size
+      end
+
+      # Reassembles a fragmented message per RFC 6455 5.4: a frame with
+      # fin: false starts one, opcode 0x0 continues it, and the frame
+      # carrying fin: true ends it. Previously `fin` was decoded and then
+      # ignored entirely, so a continuation frame fell straight through
+      # the `else` branch below and reached app code as if it were its
+      # own complete message (gap 5). A continuation frame with nothing
+      # to continue, or a new fragmented message started before the
+      # current one finished, are both protocol violations -- closed with
+      # 1002 rather than silently misinterpreted.
+      def read
+        fragments = nil
+        fragments_size = 0
+
+        loop do
+          frame = read_frame
+          return nil unless frame
+
+          case frame[:opcode]
+          when 0x8
+            # The RFC 6455 closing handshake, not a bare TCP close (step
+            # 13): echo a close frame back, close the socket, and report
+            # this to app code the same way any other disconnect is
+            # reported -- #read returning nil (step 15).
+            write_frame(frame[:payload], 0x8)
+            @socket.close
+            return nil
+          when 0x9
+            # Answered automatically, without reaching app code (step
+            # 24): keeps a long-lived authenticated connection alive
+            # through idle reverse-proxy timeouts. Echoes the ping's own
+            # payload back, per RFC 6455 5.5.3.
+            write_frame(frame[:payload], 0xA)
+          when 0xA
+            # An unsolicited pong -- nothing to do yet (no pending-ping
+            # tracking exists), but still not a message for app code.
+          when 0x0
+            return close_with(1002, "unexpected continuation frame") unless fragments
+
+            fragments << frame[:payload]
+            fragments_size += frame[:payload].bytesize
+            return close_with(1009, "message too large") if fragments_size > @max_payload_size
+
+            return fragments.join if frame[:fin]
+          else
+            return close_with(1002, "expected a continuation frame") if fragments
+            return frame[:payload] if frame[:fin]
+
+            fragments = [frame[:payload]]
+            fragments_size = frame[:payload].bytesize
+          end
+        end
+      end
+
+      def write(payload, opcode: 0x1)
+        write_frame(payload, opcode)
+      end
+
+      # The server-initiated close path (step 14): send a close frame
+      # carrying the 2-byte status code + reason RFC 6455 expects, then
+      # close the socket outright -- no wait for the client's own close
+      # frame in reply.
+      def close(code: 1000, reason: "")
+        write_frame([code].pack("n") + reason.to_s, 0x8)
+        @socket.close
+      end
+
+      # Registers this connection's own Ractor::Port -- the "connection
+      # handle" a Monk::WebSocket::Registry holds (docs/history/plan-websocket.md step
+      # 17) -- under key, and relays whatever the registry broadcasts onto
+      # this socket via a background Thread inside this connection's own
+      # Ractor (safe: a Ractor may freely spawn ordinary Threads within
+      # itself, same as the main Ractor already does elsewhere in Monk).
+      def subscribe(registry, key)
+        @registry = registry
+        @key = key
+        @port = Ractor::Port.new
+        registry.register(key, @port)
+        @relay_thread = Thread.new { relay_broadcasts }
+      end
+
+      # Called unconditionally from Server.serve's ensure on every exit
+      # path -- normal completion, the close handshake, and a crashed
+      # handler alike -- so a subscribed connection never leaves a stale
+      # entry in the registry (step 17). A no-op if #subscribe was never
+      # called.
+      def unsubscribe!
+        return unless @registry
+
+        @relay_thread.kill
+        @registry.unregister(@key, @port)
+        @port.close
+      end
+
+      # Sends an unsolicited ping frame every `interval` seconds for as
+      # long as the connection stays open (gap 3,
+      # docs/history/chat-gap-analysis.md): answering a client's own ping keeps a
+      # connection alive only if the client ever sends one, and browser
+      # JavaScript has no API to send WS ping frames at all -- so a truly
+      # idle browser connection still gets dropped by a reverse proxy's
+      # idle timeout without this. A spec-compliant client (including
+      # every browser's own WebSocket implementation, transparently, with
+      # no app-level JS involved) answers a server-sent ping with a pong
+      # automatically; #read already discards an incoming pong silently
+      # either way, so nothing app-visible changes.
+      def start_heartbeat(interval)
+        @heartbeat_thread = Thread.new do
+          loop do
+            sleep interval
+            write("", opcode: 0x9)
+          end
+        rescue IOError, Errno::EPIPE, Errno::ECONNRESET
+          # The socket closed out from under this loop -- #close or a
+          # real disconnect racing the next scheduled ping. #stop_heartbeat!
+          # still runs from Server.serve's ensure regardless; this just
+          # keeps the thread from surfacing the expected teardown race as
+          # a Thread.report_on_exception warning.
+        end
+      end
+
+      # Called unconditionally from Server.serve's ensure, alongside
+      # #unsubscribe! -- a no-op if #start_heartbeat was never called.
+      def stop_heartbeat!
+        @heartbeat_thread&.kill
+      end
+
+      private
+
+      def relay_broadcasts
+        loop { write(@port.receive) }
+      rescue Ractor::ClosedError
+        # #unsubscribe! closed the port out from under a pending #receive.
+      end
+
+      def write_frame(payload, opcode)
+        @write_mutex.synchronize { @socket.write(Monk::WebSocket::Frame.encode(payload, opcode: opcode)) }
+      end
+
+      # Sends a close frame carrying `code`/`reason`, closes the socket,
+      # and returns nil -- the shared exit path for both gap-5 violations
+      # (an oversized declared length, an out-of-sequence fragment),
+      # always returned via `return close_with(...)` so the nil correctly
+      # propagates out of #read the same way any other disconnect does.
+      def close_with(code, reason)
+        write_frame([code].pack("n") + reason, 0x8)
+        @socket.close
+        nil
+      end
+
+      def read_frame
+        header = read_exactly(2)
+        return nil unless header
+
+        byte1 = header.getbyte(1)
+        masked = byte1.anybits?(0x80)
+        length_indicator = byte1 & 0x7F
+
+        extended =
+          case length_indicator
+          when 126 then read_exactly(2)
+          when 127 then read_exactly(8)
+          else ""
+          end
+        return nil if extended.nil?
+
+        mask_key = masked ? read_exactly(4) : ""
+        return nil if mask_key.nil?
+
+        length = extended_length(length_indicator, extended)
+        # Checked before the payload is read off the wire, not after --
+        # the whole point is to never attempt to buffer a hostile
+        # multi-gigabyte claim in the first place (gap 5).
+        return close_with(1009, "payload too large") if length > @max_payload_size
+
+        payload = read_exactly(length)
+        return nil unless payload
+
+        Monk::WebSocket::Frame.decode(header + extended + mask_key + payload)
+      end
+
+      def extended_length(length_indicator, extended)
+        case length_indicator
+        when 126 then extended.unpack1("n")
+        when 127 then extended.unpack1("Q>")
+        else length_indicator
+        end
+      end
+
+      def read_exactly(n)
+        return "" if n.zero?
+
+        data = @socket.read(n)
+        return nil if data.nil? || data.bytesize < n
+
+        data
+      end
+    end
+  end
+end

data/lib/monk/websocket/errors.rb

@@ -0,0 +1,9 @@
+module Monk
+  module WebSocket
+    class HandshakeError < StandardError
+    end
+
+    class ProtocolError < StandardError
+    end
+  end
+end

data/lib/monk/websocket/frame.rb

@@ -0,0 +1,71 @@
+module Monk
+  module WebSocket
+    module Frame
+      def self.decode(bytes)
+        raise Monk::WebSocket::ProtocolError, "frame header too short" if bytes.bytesize < 2
+
+        byte0, byte1 = bytes.unpack("C2")
+        fin = byte0.anybits?(0x80)
+        opcode = byte0 & 0x0F
+        masked = byte1.anybits?(0x80)
+        length = byte1 & 0x7F
+
+        offset = 2
+        case length
+        when 126
+          require_bytes!(bytes, offset, 2, "extended 16-bit length")
+          length = bytes[offset, 2].unpack1("n")
+          offset += 2
+        when 127
+          require_bytes!(bytes, offset, 8, "extended 64-bit length")
+          length = bytes[offset, 8].unpack1("Q>")
+          offset += 8
+        end
+
+        if masked
+          require_bytes!(bytes, offset, 4, "mask key")
+          mask_key = bytes[offset, 4]
+          offset += 4
+        end
+
+        require_bytes!(bytes, offset, length, "payload")
+        payload = bytes[offset, length]
+        payload = unmask(payload, mask_key) if masked
+
+        { fin: fin, opcode: opcode, masked: masked, payload: payload }
+      end
+
+      def self.require_bytes!(bytes, offset, needed, what)
+        return if bytes.bytesize - offset >= needed
+
+        raise Monk::WebSocket::ProtocolError, "truncated frame: #{what} missing or incomplete"
+      end
+      private_class_method :require_bytes!
+
+      # Server frames are never masked, per RFC 6455 -- masking is a
+      # client-to-server-only requirement.
+      def self.encode(payload, opcode:)
+        byte0 = 0x80 | opcode
+
+        length_bytes =
+          if payload.bytesize <= 125
+            [payload.bytesize].pack("C")
+          elsif payload.bytesize <= 0xFFFF
+            [126].pack("C") + [payload.bytesize].pack("n")
+          else
+            [127].pack("C") + [payload.bytesize].pack("Q>")
+          end
+
+        # payload.b: the header is BINARY and holds non-ASCII bytes, so a
+        # UTF-8 payload with non-ASCII characters can't be concatenated to it
+        # (Encoding::CompatibilityError). Frames are bytes on the wire.
+        [byte0].pack("C") + length_bytes + payload.b
+      end
+
+      def self.unmask(payload, mask_key)
+        payload.each_byte.with_index.map { |byte, i| byte ^ mask_key.getbyte(i % 4) }.pack("C*")
+      end
+      private_class_method :unmask
+    end
+  end
+end

data/lib/monk/websocket/handshake.rb

@@ -0,0 +1,77 @@
+require "digest"
+require "base64"
+
+module Monk
+  module WebSocket
+    module Handshake
+      # An unfrozen constant here is exactly the bug Phase 0's spike hit
+      # (docs/design/websocket.md) -- Ractor::IsolationError the first time this is
+      # read from a connection Ractor. .freeze is not optional.
+      MAGIC = "258EAFA5-E914-47DA-95CA-C5AB0DC85B11".freeze
+
+      def self.accept_key(client_key)
+        Base64.strict_encode64(Digest::SHA1.digest(client_key + MAGIC))
+      end
+
+      def self.parse_request(raw_request)
+        headers = raw_request.split("\r\n").drop(1).each_with_object({}) do |line, h|
+          next if line.empty?
+
+          name, value = line.split(":", 2)
+          h[name.strip.downcase] = value.strip if name && value
+        end
+
+        unless headers["upgrade"]&.downcase == "websocket"
+          raise Monk::WebSocket::HandshakeError, "missing or invalid Upgrade header"
+        end
+        unless headers["connection"]&.downcase&.split(/\s*,\s*/)&.include?("upgrade")
+          raise Monk::WebSocket::HandshakeError, "missing or invalid Connection header"
+        end
+        raise Monk::WebSocket::HandshakeError, "missing Sec-WebSocket-Key header" unless headers["sec-websocket-key"]
+
+        headers
+      end
+
+      # docs/history/plan-websocket.md step 21: (a) Authorization: Bearer -- the
+      # non-browser/S2S path -- takes priority; (b) otherwise the
+      # session_token cookie, arriving automatically because cookies
+      # aren't port-scoped. Mirrors Monk::Auth::Helpers' identical
+      # bearer_token/session_cookie_token logic, reimplemented here since
+      # this runs from parsed handshake headers, not a Context.
+      def self.credential_from(headers)
+        if (token = bearer_token(headers))
+          { token: token, via: :bearer }
+        elsif (token = session_cookie_token(headers))
+          { token: token, via: :cookie }
+        end
+      end
+
+      def self.bearer_token(headers)
+        auth_header = headers["authorization"]
+        return nil unless auth_header&.start_with?("Bearer ")
+
+        token = auth_header.delete_prefix("Bearer ")
+        token.empty? ? nil : token
+      end
+      private_class_method :bearer_token
+
+      def self.session_cookie_token(headers)
+        headers["cookie"].to_s.split(";").each_with_object({}) do |pair, cookies|
+          name, value = pair.strip.split("=", 2)
+          cookies[name] = value if name
+        end["session_token"]
+      end
+      private_class_method :session_cookie_token
+
+      def self.response_for(raw_request)
+        headers = parse_request(raw_request)
+
+        "HTTP/1.1 101 Switching Protocols\r\n" \
+        "Upgrade: websocket\r\n" \
+        "Connection: Upgrade\r\n" \
+        "Sec-WebSocket-Accept: #{accept_key(headers["sec-websocket-key"])}\r\n" \
+        "\r\n"
+      end
+    end
+  end
+end