monkrb 0.15.0

data/lib/monk/live/renderer.rb

@@ -0,0 +1,47 @@
+module Monk
+  module Live
+    # Renders a Monk::Views template to a String fragment, for pushing to
+    # open browsers (ADR 0010) -- no HTTP response, no layout, and no
+    # request behind it: a detached Monk::Context, so a live partial can
+    # only see what it's given as locals. Callable from any Ractor once
+    # views are frozen (Phase 0 spike: ~3us per render).
+    module Renderer
+      def self.render(partial, **locals)
+        # Context#render's own `layout:` keyword would swallow this
+        # silently and render the wrong thing (a layout around a
+        # fragment), so it's rejected rather than treated as a local.
+        if locals.key?(:layout)
+          raise ArgumentError, "`layout` is reserved: a live fragment is never wrapped in a layout"
+        end
+
+        ensure_frozen!
+        html = Monk::Context.new({}).render(partial, layout: false, **locals)
+        # A plain, frozen String, not Views::Raw: frozen means Ractor-
+        # shareable, so a broadcast hands every port a reference instead
+        # of a copy (ADR 0010, measured in the Phase 0 fan-out spike).
+        String.new(html).freeze
+      end
+
+      # Views are compiled and sealed by Monk.freeze! in the main Ractor.
+      # Unfrozen, a render from a non-main Ractor dies with an opaque
+      # Ractor::IsolationError from inside Monk::Views, and in the main
+      # Ractor it would work by accident and then fail in production --
+      # so both cases fail here, with the fix in the message (ADR 0003).
+      def self.ensure_frozen!
+        return if Ractor.shareable?(Monk::Views.registry)
+
+        raise_not_frozen
+      rescue Ractor::IsolationError
+        raise_not_frozen
+      end
+      private_class_method :ensure_frozen!
+
+      def self.raise_not_frozen
+        raise Monk::Live::NotFrozenError,
+          "Monk::Live can't render before views are frozen -- call Monk.freeze! (or Monk.boot(app)) " \
+          "in the main Ractor first"
+      end
+      private_class_method :raise_not_frozen
+    end
+  end
+end

data/lib/monk/live/session.rb

@@ -0,0 +1,121 @@
+require "json"
+
+module Monk
+  module Live
+    # One WebSocket connection's live state, running inside its own
+    # connection Ractor: the subscribe/unsubscribe protocol, the topic
+    # authorization check, and the relay that stamps each published
+    # envelope with this connection's own `seq` before writing it.
+    #
+    # Client -> server: {"op":"subscribe"|"unsubscribe","topics":[...]}.
+    # Replies: subscribed (+ denied), unsubscribed, or error/bad_message.
+    # A denial never says why or whether the topic exists.
+    #
+    # `connection` is anything with #read, #write and #subject.
+    class Session
+      # No `*`, no whitespace or NUL, ASCII only: a client can't smuggle a
+      # glob or a delimiter into a topic, and only a topic that passed this
+      # and the policy is ever turned into a Symbol.
+      TOPIC_FORMAT = %r{\A[\w:.\-/@]{1,200}\z}
+      MAX_TOPICS_PER_MESSAGE = 100
+
+      def initialize(connection, registry:, rules:, max_topics:)
+        @connection = connection
+        @registry = registry
+        @rules = rules
+        @max_topics = max_topics
+        @topics = {} # String topic => the Symbol it is registered under
+      end
+
+      def run
+        @port = Ractor::Port.new
+        @relay = Thread.new { relay }
+        while (raw = @connection.read)
+          dispatch(raw)
+        end
+      ensure
+        cleanup
+      end
+
+      private
+
+      def dispatch(raw)
+        message = JSON.parse(raw, max_nesting: 5)
+        topics = message.is_a?(Hash) ? message["topics"] : nil
+        return reply(op: "error", reason: "bad_message") unless valid_topics?(topics)
+
+        case message["op"]
+        when "subscribe" then subscribe(topics)
+        when "unsubscribe" then unsubscribe(topics)
+        else reply(op: "error", reason: "bad_message")
+        end
+      rescue JSON::ParserError
+        reply(op: "error", reason: "bad_message")
+      end
+
+      def valid_topics?(topics)
+        topics.is_a?(Array) && topics.size <= MAX_TOPICS_PER_MESSAGE &&
+          topics.all? { |topic| topic.is_a?(String) && topic.valid_encoding? }
+      end
+
+      def subscribe(topics)
+        allowed, denied = topics.partition { |topic| try_subscribe?(topic) }
+        reply(op: "subscribed", topics: allowed, denied: denied)
+      end
+
+      def try_subscribe?(topic)
+        return true if @topics.key?(topic)
+        return false unless permitted?(topic) && @topics.size < @max_topics
+
+        key = topic.to_sym
+        @registry.register(key, @port)
+        @topics[topic] = key
+        true
+      end
+
+      def permitted?(topic)
+        TOPIC_FORMAT.match?(topic) && Policy.allowed?(@rules, @connection.subject, topic)
+      end
+
+      def unsubscribe(topics)
+        removed = topics.select { |topic| @topics.key?(topic) }
+        removed.each { |topic| @registry.unregister(@topics.delete(topic), @port) }
+        reply(op: "unsubscribed", topics: removed)
+      end
+
+      def reply(message)
+        @connection.write(JSON.generate(message))
+      end
+
+      # Runs on its own thread: each published envelope gets the next
+      # per-connection seq spliced in after its opening `{`. The
+      # publisher's frozen string is shared by every subscriber (ADR
+      # 0010), so the stamp has to be a per-connection copy made here.
+      def relay
+        seq = 0
+        loop do
+          payload = @port.receive
+          seq += 1
+          @connection.write(payload.start_with?("{") ? "{\"seq\":#{seq},#{payload.byteslice(1..)}" : payload)
+        end
+      rescue Ractor::ClosedError, IOError, SystemCallError
+        # cleanup closed the port, or the socket went away first.
+      rescue StandardError => e
+        # Anything else would leave a connected client silently receiving
+        # nothing: a stale page nobody knows is stale. Closing makes the
+        # client reconnect and resync (ADR 0011), which is the recovery.
+        warn "monk-live: relay failed, closing connection: #{e.class}: #{e.message}"
+        @connection.close(code: 1011, reason: "relay failed")
+      end
+
+      # On every exit path -- clean hang-up, close handshake, a crashed
+      # read -- so a connection never leaves a stale registry entry.
+      def cleanup
+        @relay&.kill
+        @topics.each_value { |key| @registry.unregister(key, @port) }
+        @topics.clear
+        @port&.close
+      end
+    end
+  end
+end

data/lib/monk/live.rb

@@ -0,0 +1,96 @@
+require_relative "../monk"
+# Live sits on top of the WebSocket layer (ADR 0008): loading one loads the
+# other, so a WS process or a publisher-only one needn't remember both.
+require_relative "websocket"
+require_relative "live/errors"
+require_relative "live/renderer"
+require_relative "live/envelope"
+require_relative "live/publisher"
+require_relative "live/policy"
+require_relative "live/session"
+require_relative "live/helpers"
+
+# Opt-in, like Monk::WebSocket and Monk::Auth: require "monk/live"
+# explicitly. `require "monk"` alone must not load this (ADR 0008).
+module Monk
+  Context.include(Live::Helpers)
+
+  module Live
+    # Eager, never `@x ||=`: a lazy reader writes on first access, which is
+    # an isolation error from a non-main Ractor (same rule as Monk::Views).
+    @publisher = nil
+    @registry = nil
+    @rules = [].freeze
+    @max_topics = 100
+
+    # Handed to Monk::WebSocket::Server#run in a WS process:
+    #   server.run(&Monk::Live::HANDLER)
+    # Built here, in the module body, where self is shareable, as the
+    # server requires.
+    HANDLER = proc do |connection|
+      registry = Monk::Live.registry || raise(Monk::Live::NotConfiguredError,
+        "Monk::Live isn't configured -- call Monk::Live.configure(registry: ...) at boot",)
+      Monk::Live::Session.new(
+        connection, registry: registry, rules: Monk::Live.rules, max_topics: Monk::Live.max_topics,
+      ).run
+    end
+
+    CLIENT_DIR = File.expand_path("live/client", __dir__).freeze
+
+    class << self
+      attr_reader :publisher, :registry, :rules, :max_topics
+
+      # Where the browser runtime ships inside the gem: monk_live.js,
+      # protocol.js and idiomorph.js (they import each other by relative
+      # path, so an app serves or copies the directory as a unit).
+      def client_dir = CLIENT_DIR
+
+      # Boot-time, main Ractor. `registry` is a Monk::WebSocket::Registry,
+      # or a RedisFanout wrapping one when publishing has to reach WS
+      # connections in another process. It must be Ractor-shareable (both
+      # are), since request workers read the publisher from their own
+      # Ractors -- checked here, at boot, rather than on a live request.
+      def configure(registry:, max_topics: 100)
+        publisher = Publisher.new(registry)
+        unless Ractor.shareable?(publisher)
+          raise ArgumentError,
+            "Monk::Live.configure(registry:) needs a Ractor-shareable registry, got #{registry.class}"
+        end
+
+        @publisher = publisher
+        @registry = registry
+        @max_topics = max_topics
+      end
+
+      # Boot-time, main Ractor. See Monk::Live::Policy for the semantics:
+      # deny by default, first matching rule wins, anonymous subjects need
+      # `anonymous: true`. The block must be Ractor-shareable.
+      def authorize(pattern, anonymous: false, &block)
+        @rules = Ractor.make_shareable([*@rules, Policy.build_rule(pattern, anonymous, block)])
+      end
+
+      def authorized?(subject, topic) = Policy.allowed?(rules, subject, topic)
+
+      # Test-only, like Monk::Views.reset!.
+      def reset!
+        @publisher = nil
+        @registry = nil
+        @rules = [].freeze
+        @max_topics = 100
+      end
+
+      def patch(topic, **) = current.patch(topic, **)
+      def append(topic, **) = current.append(topic, **)
+      def prepend(topic, **) = current.prepend(topic, **)
+      def remove(topic, **) = current.remove(topic, **)
+      def batch(topic, &) = current.batch(topic, &)
+
+      private
+
+      def current
+        publisher || raise(Monk::Live::NotConfiguredError,
+          "Monk::Live isn't configured -- call Monk::Live.configure(registry: ...) at boot",)
+      end
+    end
+  end
+end

data/lib/monk/log.rb

@@ -0,0 +1,130 @@
+require "fileutils"
+
+require_relative "freeze_hooks"
+require_relative "environment"
+require_relative "settings"
+
+module Monk
+  # One line per request, appended to log/<env>.log -- log/development.log,
+  # log/test.log, log/production.log, log/staging.log, Rails-style. Runs
+  # alongside Base#log_request's $stdout line, not instead of it: stdout
+  # stays development-only (a human tailing a dev console), but the file
+  # is unconditional -- every environment gets one, including production
+  # and test.
+  #
+  # A File isn't Ractor-shareable the way $stdout is: Ruby special-cases
+  # $stdout/$stderr/$stdin for cross-Ractor use, but a File this module
+  # opens itself gets no such treatment. So unlike Assets' one frozen
+  # manifest every worker reads, there's no single handle every worker can
+  # share, and a class ivar won't do either -- routes freezes solid at
+  # Boot, and a plain File isn't shareable enough to freeze into one.
+  # Instead, each worker Ractor opens its own append-mode handle to the
+  # same path, lazily, on its first write, and keeps it for the rest of
+  # its life in Ractor-local storage. Concurrent O_APPEND writers to the
+  # same path need no extra locking -- the same guarantee #log_request
+  # already relies on for several worker Ractors sharing $stdout.
+  module Log
+    DEFAULT_ROOT = "log".freeze
+    DEFAULT_LEVEL = "info".freeze
+
+    # Least to most severe -- the same list Settings validates LOG_LEVEL
+    # against, so a level Settings would reject can never reach #enabled?.
+    LEVELS = Settings::LOG_LEVEL_VALUES
+
+    class << self
+      attr_reader :root
+      attr_writer :root
+
+      # Called from Base#freeze! via Monk.freeze_hooks, the same seam
+      # Assets/Settings use. Creates log/ once, in the main Ractor, and
+      # freezes the path a worker will later append to -- unfrozen, a
+      # worker reading it back would raise Ractor::IsolationError before
+      # ever opening a handle.
+      #
+      # Runs after Settings' own freeze_registry! (registered first, in
+      # monk.rb's require order), so Settings[:log_level] is already the
+      # frozen, boot-validated value by the time this reads it.
+      def freeze_registry!
+        FileUtils.mkdir_p(root)
+        @path = File.join(root, "#{Monk.env}.log").freeze
+        @threshold = Settings[:log_level]
+      end
+
+      # Test-only. Also drops *this* Ractor's memoized handle -- tests
+      # all run in the main Ractor, so without this a second #with_log
+      # in the same process would keep writing into the first one's
+      # (by then torn-down) tmpdir instead of picking up the new @path.
+      def reset!
+        @root = DEFAULT_ROOT
+        @path = nil
+        @threshold = DEFAULT_LEVEL
+        if (handle = Ractor.current[:monk_log_handle])
+          handle.close
+          Ractor.current[:monk_log_handle] = nil
+        end
+      end
+
+      def write(line)
+        handle.write(line)
+        handle.flush
+      end
+
+      # UTC, millisecond precision, ISO 8601 -- sortable as plain text and
+      # unambiguous across machines/timezones. Shared by #log below and by
+      # Base#log_request, so the access log and app-level log lines carry
+      # the same stamp format.
+      def timestamp
+        Time.now.utc.strftime("%Y-%m-%dT%H:%M:%S.%3NZ")
+      end
+
+      # App-level logging, one line per call, gated by :log_level (default
+      # "info" -- see Settings::DEFAULT_DECLARATIONS). Below the configured
+      # threshold, a call is a no-op: cheap enough to leave debug logging
+      # in place rather than stripping it per environment. Unlike #write,
+      # never echoed to $stdout -- that's Base#log_request's own concern,
+      # gated on Monk.env instead.
+      #
+      # Four plain, hand-written methods, not one define_method(&block) per
+      # LEVELS entry -- a method backed by a Proc closure raises "defined
+      # with an un-shareable Proc in a different Ractor" the first time a
+      # worker Ractor other than the one that defined it calls it, same as
+      # Environment (see its comment) ran into for MONK_ENV_VALUES.
+      def debug(message)
+        log("debug", message)
+      end
+
+      def info(message)
+        log("info", message)
+      end
+
+      def warn(message)
+        log("warn", message)
+      end
+
+      def error(message)
+        log("error", message)
+      end
+
+      private
+
+      def log(level, message)
+        return unless enabled?(level)
+
+        write("#{timestamp} #{level.upcase} #{message}\n")
+      end
+
+      def enabled?(level)
+        LEVELS.index(level) >= LEVELS.index(@threshold)
+      end
+
+      def handle
+        Ractor.current[:monk_log_handle] ||= File.open(@path, "a")
+      end
+    end
+
+    @root = DEFAULT_ROOT
+    @threshold = DEFAULT_LEVEL
+
+    Monk.freeze_hooks << self
+  end
+end

data/lib/monk/persistence/errors.rb

@@ -0,0 +1,7 @@
+module Monk
+  class PersistenceTimeoutError < StandardError
+  end
+
+  class UnknownPersistenceError < StandardError
+  end
+end

data/lib/monk/persistence/model.rb

@@ -0,0 +1,41 @@
+module Monk
+  module Persistence
+    # Backend-agnostic base for persistence models: tracks subclasses and
+    # freezes their db_name/table_name at boot (Seam B), so they're
+    # readable from a worker Ractor -- freezing the class itself would do
+    # nothing, since Class/Module objects are always Ractor.shareable?
+    # regardless of their instance variables. A concrete backend (e.g.
+    # Monk::Persistence::Pg::Model, loaded separately) subclasses this and
+    # adds the actual CRUD methods; nothing here is CRUD-specific or
+    # backend-specific.
+    class Model
+      class << self
+        attr_accessor :db_name, :table_name
+
+        def inherited(subclass)
+          super
+          Model.subclasses << subclass
+        end
+
+        def subclasses
+          @subclasses ||= []
+        end
+
+        # Called from Base#freeze! (Seam B). Deliberately does NOT check
+        # whether db_name is registered with a backend -- that registry is
+        # process-global, not scoped to whichever Base subclass happens to
+        # be booting, so that check would produce false failures (e.g. a
+        # Model used by one app tripping another app's boot before its own
+        # db is registered).
+        def freeze_all!
+          Model.subclasses.each do |subclass|
+            subclass.db_name = Ractor.make_shareable(subclass.db_name)
+            subclass.table_name = Ractor.make_shareable(subclass.table_name)
+          rescue Ractor::Error => e
+            raise Monk::UnshareableModelError, "#{subclass} is not Ractor-shareable: #{e.message}"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/monk/persistence/pg/errors.rb

@@ -0,0 +1,4 @@
+module Monk
+  class MalformedMigrationError < StandardError
+  end
+end

data/lib/monk/persistence/pg/migrator.rb

@@ -0,0 +1,165 @@
+require_relative "../pg"
+require_relative "errors"
+
+module Monk
+  module Persistence
+    module Pg
+      # Applies/rolls back versioned .sql file pairs against a registered
+      # Monk::Persistence::Pg database. Deliberately not a DSL: each
+      # <version>_<name>.up.sql / .down.sql pair is sent to Postgres
+      # verbatim -- see docs/history/plan-migrations.md for the full rationale.
+      class Migrator
+        FILENAME = /\A(\d+)_(.+)\.(up|down)\.sql\z/
+
+        Migration = Struct.new(:version, :name, :up_path, :down_path)
+
+        attr_reader :migrations
+
+        def initialize(db_name:, dir: "db/migrate")
+          @db_name = db_name
+          @dir = dir
+          @migrations = load_migrations
+          @schema_migrations_ready = false
+        end
+
+        # Runs every pending .up.sql (its version absent from
+        # schema_migrations) in ascending order, each inside its own
+        # transaction, recording the version only after that transaction
+        # commits. A failing statement rolls back just that migration and
+        # halts the run -- later pending migrations are never attempted.
+        # Returns the versions actually applied.
+        def migrate!
+          applied = []
+
+          Monk::Persistence::Pg.checkout(@db_name) do |conn|
+            ensure_schema_migrations_table(conn)
+            already_applied = applied_versions(conn)
+
+            migrations.reject { |m| already_applied.include?(m.version) }.each do |m|
+              conn.transaction do
+                conn.exec(File.read(m.up_path))
+                conn.exec_params("INSERT INTO schema_migrations (version) VALUES ($1)", [m.version])
+              end
+              applied << m.version
+            end
+          end
+
+          applied
+        end
+
+        # Runs .down.sql for the `steps` most recently applied migrations,
+        # most-recent-first, each inside its own transaction, removing the
+        # version from schema_migrations only after that transaction
+        # commits. `steps` beyond the number actually applied rolls back
+        # everything and stops cleanly. Returns the versions reverted.
+        def rollback!(steps: 1)
+          reverted = []
+
+          Monk::Persistence::Pg.checkout(@db_name) do |conn|
+            ensure_schema_migrations_table(conn)
+
+            recently_applied(conn, steps).each do |version|
+              migration = migrations.find { |m| m.version == version }
+              unless migration
+                raise Monk::MalformedMigrationError,
+                  "applied migration #{version.inspect} has no matching .down.sql file on disk"
+              end
+
+              conn.transaction do
+                conn.exec(File.read(migration.down_path))
+                conn.exec_params("DELETE FROM schema_migrations WHERE version = $1", [version])
+              end
+              reverted << version
+            end
+          end
+
+          reverted
+        end
+
+        # Not-yet-applied versions, ascending, with no side effects.
+        def pending
+          Monk::Persistence::Pg.checkout(@db_name) do |conn|
+            ensure_schema_migrations_table(conn)
+            already_applied = applied_versions(conn)
+            migrations.reject { |m| already_applied.include?(m.version) }.map(&:version)
+          end
+        end
+
+        # Already-applied versions, in the order they were applied.
+        def applied
+          Monk::Persistence::Pg.checkout(@db_name) do |conn|
+            ensure_schema_migrations_table(conn)
+            applied_versions(conn)
+          end
+        end
+
+        private
+
+        def recently_applied(conn, steps)
+          conn.exec_params(
+            "SELECT version FROM schema_migrations ORDER BY applied_at DESC, version DESC LIMIT $1", [steps]
+          ).map { |row| row["version"] }
+        end
+
+        # Checks existence via information_schema first, rather than relying
+        # on CREATE TABLE IF NOT EXISTS's own "already exists, skipping"
+        # NOTICE -- confusing noise on every call once the table exists.
+        # Memoized per instance since a single Migrator's checks/commands
+        # often chain multiple calls together (e.g. bin/migrate status
+        # calling #applied then #pending).
+        def ensure_schema_migrations_table(conn)
+          return if @schema_migrations_ready
+
+          exists = conn.exec(
+            "SELECT 1 FROM information_schema.tables WHERE table_name = 'schema_migrations'"
+          ).ntuples.positive?
+
+          conn.exec(<<~SQL) unless exists
+            CREATE TABLE schema_migrations (
+              version TEXT PRIMARY KEY,
+              applied_at TIMESTAMPTZ NOT NULL DEFAULT now()
+            )
+          SQL
+
+          @schema_migrations_ready = true
+        end
+
+        def applied_versions(conn)
+          conn.exec("SELECT version FROM schema_migrations ORDER BY applied_at, version").map { |row| row["version"] }
+        end
+
+        def load_migrations
+          by_version = {}
+
+          Dir.glob(File.join(@dir, "*.sql")).sort.each do |path|
+            match = FILENAME.match(File.basename(path))
+            raise Monk::MalformedMigrationError,
+              "#{path.inspect} doesn't match the <version>_<name>.(up|down).sql convention" unless match
+
+            version, name, direction = match.captures
+            migration = (by_version[version] ||= Migration.new(version, name))
+
+            if migration.name != name
+              raise Monk::MalformedMigrationError,
+                "version #{version.inspect} names two different migrations " \
+                "(#{migration.name.inspect} vs #{name.inspect})"
+            end
+
+            direction == "up" ? migration.up_path = path : migration.down_path = path
+          end
+
+          ordered = by_version.values.sort_by { |m| m.version.to_i }
+          ordered.each do |m|
+            next if m.up_path && m.down_path
+
+            missing = m.up_path ? "down" : "up"
+            raise Monk::MalformedMigrationError,
+              "migration #{m.version}_#{m.name} is missing its .#{missing}.sql file"
+          end
+
+          ordered
+        end
+      end
+    end
+  end
+end