monkrb 0.15.0

data/README.md

@@ -0,0 +1,88 @@
+# Monk
+
+A light Ruby web framework designed to be fully `Ractor`-safe: every app it produces is a valid Rack 3 app that is also `Ractor.shareable?`, so it can be served in parallel across Ractor worker pools without silently losing that safety property. Named after Thelonious Sphere Monk, great and unique Jazz piano player and composer.
+
+**Built in** (loaded by `require "monk"`): routing, context and error handling, boot-time Ractor-shareability checks, `Monk::StateRactor` for shared state, settings, ERB views, static assets and logging. **Opt-in** (each needs its own `require`): Postgres persistence and migrations, passwordless auth and sessions, a WebSocket server with Redis fan-out, and `Monk::Live` server-pushed HTML updates. Details for each are in the [Features](#features) table below.
+
+Monk is Kino-agnostic — it's built on stdlib `Ractor` primitives only, with no runtime dependency on any particular server. [Kino](https://github.com/yaroslav/kino) is the reference/development server (see `bin/server`), but any Ractor-aware Rack server, or a conventional one, can run a Monk app.
+
+Requires **Ruby 4.0+**. Runtime dependencies: `rack` and `base64`.
+
+## Quick start
+
+Install the gem — published as `monkrb` (the `monk` name on RubyGems belongs to an unrelated, long-abandoned project), the CLI and `require` stay `monk`:
+
+```
+gem install monkrb
+
+monk new my_app && cd my_app
+bundle install
+bin/server           # -> http://localhost:9292/hello
+```
+
+`monk new` scaffolds the app's own `Gemfile` with `gem "monkrb", require: "monk"`.
+
+`monk new` writes a working skeleton (an HTML home page, a `/hello` route, a `/api/hello` JSON route, `views/`, `public/`, a `SETUP.md`). Flags add Postgres, auth, Redis and live updates: see [`docs/guides/scaffolding.md`](docs/guides/scaffolding.md).
+
+All `monk` commands and flags are listed by:
+
+```
+monk --help
+```
+
+## A taste
+
+```ruby
+class App < Monk::Base
+  get("/hello") { "hello from monk" }
+  get("/users/:id") { json(id: params[:id]) }
+  get("/") { @title = "Home"; render "index", posts: Post.where(published: true) }
+
+  error(404) { json(error: "not found") }
+end
+
+run Monk.boot(App)   # seals routes into a Ractor.shareable? structure, or raises
+```
+
+Routes can't close over mutable state: `Monk.boot` raises `Monk::UnshareableRouteError` naming the offending route instead of failing on a live request. Shared mutable state goes through `Monk::StateRactor`.
+
+## Features
+
+Everything beyond the core is opt-in (`require "monk"` alone loads none of it).
+
+| Feature | What it is | Opt-in | Guide |
+|---|---|---|---|
+| Routing, context, errors | `get`/`post`/…, path params, `halt`, `json`, `error`, experimental `resources` | — | [`routing.md`](docs/guides/routing.md) |
+| Boot and shared state | `Monk.boot`, Ractor-shareability checks, `Monk::StateRactor` | — | [`boot-and-shared-state.md`](docs/guides/boot-and-shared-state.md) |
+| Settings | `Monk::Settings`, `MONK_ENV`, env-var config validated at boot | — | [`settings.md`](docs/guides/settings.md) |
+| Views and static assets | ERB compiled at boot, escaped by default, layouts/partials, frozen asset manifest | — | [`views.md`](docs/guides/views.md) |
+| Logging | request log per environment, `Monk::Log.debug`/`info`/`warn`/`error` | — | [`logging.md`](docs/guides/logging.md) |
+| Persistence | `Monk::Persistence::Pg`: raw `pg`, per-Ractor connections, hash-based `Model` | `require "monk/persistence/pg"` (+ `.../pg/model`); needs the `pg` gem | [`persistence.md`](docs/guides/persistence.md) |
+| Migrations | plain `.sql` up/down pairs, `Migrator` | `require "monk/persistence/pg/migrator"`; needs the `pg` gem | [`migrations.md`](docs/guides/migrations.md) |
+| Auth and sessions | `Monk::Auth`: passwordless tokens, Bearer or cookie + CSRF | `require "monk/auth"`; needs the `pg` gem and a registered Postgres connection | [`auth.md`](docs/guides/auth.md) |
+| WebSocket | `Monk::WebSocket`: RFC 6455 server as its own process, Redis fan-out | `require "monk/websocket"`; Redis fan-out: `require "monk/websocket/redis_fanout"` and the `redis` gem | [`websocket.md`](docs/guides/websocket.md) |
+| Live updates | `Monk::Live`: server-rendered HTML patches pushed to open tabs | `require "monk/live"`; needs the WebSocket server and, across processes, Redis | [`live.md`](docs/guides/live.md) |
+| Scaffolding | `monk new` and its flags; retrofitting Postgres, Auth or Redis | — (the `monk` command; flags `--postgres`, `--auth`, `--redis`, `--live`) | [`scaffolding.md`](docs/guides/scaffolding.md) |
+
+## More documentation
+
+- [`docs/framework-comparison.md`](docs/framework-comparison.md): Monk vs. Sinatra vs. Rails, with LOC per module.
+- [`docs/guides/deploying.md`](docs/guides/deploying.md): worked deployment examples.
+- [`docs/design/ractor.md`](docs/design/ractor.md): how Monk uses Ruby's `Ractor`.
+- [`docs/adr/`](docs/adr) and [`CONTEXT.md`](CONTEXT.md): architectural decisions and domain vocabulary.
+- Design docs and phase-by-phase plans behind each feature: [`docs/design/views.md`](docs/design/views.md), [`docs/design/auth-sessions.md`](docs/design/auth-sessions.md), [`docs/design/websocket.md`](docs/design/websocket.md), [`docs/design/persistence-ractor-connections.md`](docs/design/persistence-ractor-connections.md), and the phase-by-phase plans and archived notes in [`docs/history/`](docs/history).
+- [`CHANGELOG.md`](CHANGELOG.md).
+
+## Working on this repo
+
+```
+bundle install
+bundle exec rake test    # Minitest
+bin/server               # demo app from config.ru via kino
+```
+
+More (server modes, Docker) in [`docs/development.md`](docs/development.md).
+
+## Status
+
+Monk is **pre-1.0** (see `lib/monk/version.rb` and the [changelog](CHANGELOG.md)): the API may still change between minor versions. The core is described in [`docs/history/core-plan.md`](docs/history/core-plan.md). There's no open roadmap issue at the moment; new work is proposed and tracked as it comes up. Done so far, each with its own design doc and plan: persistence, migrations, HTML templating and static assets, auth and sessions, WebSocket with Redis fan-out, log levels, live updates (`Monk::Live`, as of 2026-09-19), deployment support (Dockerfile scaffolding, `docs/guides/deploying.md`), and the RubyGems release as `monkrb` (both 2026-09-22).

data/exe/monk

@@ -0,0 +1,116 @@
+#!/usr/bin/env ruby
+require_relative "../lib/monk/scaffold"
+
+USAGE = "Usage: monk new APP_NAME [--postgres] [--auth] [--redis] [--live]".freeze
+
+HELP = <<~TEXT.freeze
+  #{USAGE}
+
+  Creates a new Monk project at APP_NAME from a static skeleton -- refuses
+  to run if APP_NAME already exists.
+
+  Base skeleton: Gemfile, config.ru, .ruby-version, bin/server,
+  bin/websocket_server, SETUP.md -- WebSocket support needs no external
+  service, so unlike Postgres/Redis below it isn't gated behind a flag:
+  bin/websocket_server auto-authenticates if --auth's config/auth.rb is
+  present, and fans out across processes over Redis if --redis's
+  REDIS_URL is set, adapting at boot either way. SETUP.md is generated
+  for every flag combination, walking through dev-then-test setup for
+  this exact project -- including, since monk new scaffolds no test
+  framework itself, the minimum Minitest wiring to get a working
+  `bundle exec rake test`.
+
+  Options:
+      --postgres      Also scaffold Postgres persistence/migrations support:
+                       config/persistence.rb, bin/console, bin/setup_db,
+                       bin/migrate, db/migrate/. Also wires config.ru to
+                       require it, writes .env/.env.test/.env.example
+                       (DB_NAME defaulting to APP_NAME_development/_test,
+                       not the generic app_development fallback baked into
+                       config/persistence.rb itself), and uncomments
+                       gem "dotenv" in the Gemfile so .env actually loads
+                       (config/settings.rb's require "dotenv/load" is a
+                       no-op with it left commented). SETUP.md's dev/test
+                       steps grow to cover Postgres containers, database
+                       creation, and migrations.
+      --auth          Also scaffold Monk::Auth (passwordless token auth).
+                       Implies --postgres -- Auth is Postgres-only, so this
+                       always brings the persistence scaffold with it. Adds
+                       config/auth.rb and a migration creating the
+                       login_tokens/sessions tables it needs. config.ru
+                       requires config/auth instead of config/persistence
+                       (config/auth.rb itself requires persistence), and
+                       .env/.env.test/.env.example get an AUTH_SECRET line.
+      --redis         Add the redis gem to the Gemfile, for
+                       bin/websocket_server's cross-process fan-out. Fully
+                       independent -- doesn't imply, and isn't implied by,
+                       --postgres or --auth. Writes/extends .env and
+                       .env.example with a REDIS_URL line (deliberately
+                       never .env.test -- only a test that exercises
+                       RedisFanout needs it) and uncomments gem "dotenv"
+                       if it isn't already (same reasoning as --postgres
+                       above), same whether or not --postgres is also set.
+
+      --live          Also scaffold Monk::Live: a demo counter whose open tabs
+                       update by themselves, pushed as HTML over a WebSocket.
+                       Implies --redis (bin/server and bin/websocket_server
+                       are separate processes, and Redis carries an update
+                       from one to the other). Adds config/live.rb,
+                       views/live/_hits.erb and the browser runtime under
+                       public/js/monk_live/, replaces config.ru, views/index.erb
+                       and bin/websocket_server with live versions, and adds
+                       the runtime's <meta>/<script> tags to the layout.
+
+  Commands:
+      new APP_NAME    Create a new project (see Options above)
+      help            Show this help (also --help, -h)
+
+  After creating a project:
+      cd APP_NAME
+      bundle install
+
+  See the generated SETUP.md for a full dev-then-test walkthrough, tailored
+  to whichever flags were passed. With --postgres (or --auth, which implies
+  it), short version, once a reachable Postgres exists (.env/.env.test have
+  the connection details):
+      bin/setup_db    Apply pending migrations
+      bin/migrate     migrate | rollback [N] | status
+      bin/console     IRB with persistence loaded
+
+  With --auth, .env/.env.test ship a placeholder AUTH_SECRET -- change it
+  before relying on it; config/auth.rb reads it via ENV.fetch and raises
+  if it's missing entirely.
+
+  With --redis, .env ships a placeholder REDIS_URL to turn
+  bin/websocket_server's cross-process fan-out on; unset (as in .env.test),
+  it runs in-process only, same as without --redis.
+TEXT
+
+def usage_error!
+  warn USAGE
+  exit 1
+end
+
+command, *rest = ARGV
+
+case command
+when nil, "help", "--help", "-h"
+  puts HELP
+when "new"
+  app_name = rest.find { |arg| !arg.start_with?("-") }
+  usage_error! if app_name.nil?
+
+  auth = rest.include?("--auth")
+  redis = rest.include?("--redis")
+  live = rest.include?("--live")
+  Monk::Scaffold.new(app_name, postgres: rest.include?("--postgres"), auth: auth, redis: redis, live: live).write!
+
+  puts "Created #{app_name}. Next steps:"
+  puts "  cd #{app_name}"
+  puts "  bundle install"
+  puts "  see SETUP.md for the full dev-then-test walkthrough"
+  puts "  change the placeholder AUTH_SECRET in .env/.env.test before relying on it" if auth
+  puts "  Monk::Live needs Redis running, bin/server and bin/websocket_server (see SETUP.md)" if live
+else
+  usage_error!
+end

data/lib/monk/assets.rb

@@ -0,0 +1,197 @@
+require "digest"
+
+require_relative "freeze_hooks"
+require_relative "environment"
+
+module Monk
+  # Static files -- CSS, vanilla JS, images, fonts -- served by Monk
+  # itself out of a manifest built once at Boot and frozen, so a worker
+  # Ractor reads bodies and ETags by reference and never touches the
+  # filesystem or any mutable cache.
+  #
+  # One property worth naming: in production a lookup is an exact-match
+  # fetch of a path enumerated at boot, so path traversal isn't
+  # defended against, it's structurally impossible -- "/../../etc/passwd"
+  # simply isn't a key. Development does hit the disk (so an edited file
+  # shows up on the next request, no restart) and is the only mode that
+  # needs the containment check in #disk_entry.
+  module Assets
+    DEFAULT_ROOT = "public".freeze
+
+    # Ractor.make_shareable, not just #freeze: Hash#freeze only freezes the
+    # hash object itself, not the String keys/values inside it, so a plain
+    # `{ ... }.freeze` here is still rejected as unshareable the moment a
+    # worker Ractor reads it -- exactly what #content_type does from
+    # #disk_entry on every static-asset request in development.
+    TEXT_TYPES = Ractor.make_shareable({
+      ".css" => "text/css",
+      ".js" => "text/javascript",
+      ".mjs" => "text/javascript",
+      ".html" => "text/html",
+      ".json" => "application/json",
+      ".svg" => "image/svg+xml",
+      ".txt" => "text/plain",
+      ".xml" => "application/xml",
+      ".map" => "application/json",
+    })
+
+    BINARY_TYPES = Ractor.make_shareable({
+      ".png" => "image/png",
+      ".jpg" => "image/jpeg",
+      ".jpeg" => "image/jpeg",
+      ".gif" => "image/gif",
+      ".webp" => "image/webp",
+      ".avif" => "image/avif",
+      ".ico" => "image/x-icon",
+      ".woff" => "font/woff",
+      ".woff2" => "font/woff2",
+      ".ttf" => "font/ttf",
+      ".otf" => "font/otf",
+      ".pdf" => "application/pdf",
+      ".wasm" => "application/wasm",
+    })
+
+    FALLBACK_TYPE = "application/octet-stream".freeze
+    REVALIDATE = "public, max-age=0, must-revalidate".freeze
+    IMMUTABLE = "public, max-age=31536000, immutable".freeze
+    NO_CACHE = "no-cache".freeze
+
+    class << self
+      # Plain readers over eagerly-initialized ivars, never `@x ||= ...`:
+      # a lazy reader writes on first access, and writing a module ivar
+      # from a non-main Ractor is an isolation error. `production?` is
+      # settled once at Boot for the same family of reasons -- ENV is
+      # main-Ractor state, so a per-request read from a worker is a
+      # hazard (Monk.env resolves this the same way, through Settings'
+      # own frozen-at-Boot snapshot). `assets false` sets root to false
+      # and disables serving.
+      attr_reader :root, :manifest
+      attr_writer :root
+
+      def enabled?
+        !!root
+      end
+
+      def production?
+        @production
+      end
+
+      # A Rack response for a GET/HEAD of a known asset, or nil so the
+      # request falls through to routing. Called from Base#dispatch before
+      # route matching, which is the conventional order (it's where
+      # Rack::Static sits) and keeps a splat route from shadowing a
+      # stylesheet.
+      def response(env)
+        return nil unless enabled?
+
+        verb = env["REQUEST_METHOD"]
+        return nil unless verb == "GET" || verb == "HEAD"
+
+        entry = lookup(env["PATH_INFO"].to_s)
+        return nil unless entry
+
+        headers = {
+          "content-type" => entry[:type],
+          "etag" => entry[:etag],
+          "cache-control" => cache_control(env, entry),
+        }
+
+        return [304, headers, []] if fresh?(env, entry)
+        return [200, headers.merge("content-length" => entry[:body].bytesize.to_s), []] if verb == "HEAD"
+
+        [200, headers, [entry[:body]]]
+      end
+
+      # The URL to link an asset by. In production it carries a `?v=`
+      # digest, so a stamped request can be cached for a year; in
+      # development it doesn't, because the boot-time digest goes stale
+      # the moment the file is edited and a cached stylesheet is exactly
+      # what you don't want while editing one.
+      def path_for(path)
+        return path unless production?
+
+        entry = manifest[path]
+        entry ? "#{path}?v=#{entry[:digest]}" : path
+      end
+
+      # Called from Base#freeze! (Seam B), via Monk.freeze_hooks.
+      def freeze_registry!
+        @production = !Monk.env.development?
+        @manifest = Ractor.make_shareable(build_manifest)
+        # #root is read on every request (#enabled?, and the disk lookup
+        # in development). Left unfrozen, reading it from a worker Ractor
+        # raises Ractor::IsolationError before the manifest is even
+        # consulted.
+        @root = root.freeze
+      end
+
+      # Test-only.
+      def reset!
+        @root = DEFAULT_ROOT
+        @manifest = {}
+        @production = false
+      end
+
+      def content_type(path)
+        extension = File.extname(path).downcase
+        return "#{TEXT_TYPES[extension]}; charset=utf-8" if TEXT_TYPES.key?(extension)
+
+        BINARY_TYPES.fetch(extension, FALLBACK_TYPE)
+      end
+
+      private
+
+      def build_manifest
+        return {} unless enabled? && Dir.exist?(root)
+
+        Dir.glob("**/*", base: root).each_with_object({}) do |relative, manifest|
+          path = File.join(root, relative)
+          next unless File.file?(path)
+
+          manifest["/#{relative}"] = entry_for(relative, File.binread(path))
+        end
+      end
+
+      def lookup(path)
+        return manifest[path] if production?
+
+        disk_entry(path)
+      end
+
+      # Development only. PATH_INFO is not un-escaped here on purpose: an
+      # encoded "%2e%2e" stays a literal, nonexistent filename, and a
+      # decoded ".." is caught by the containment check below.
+      def disk_entry(path)
+        return nil if path.empty? || path.include?("\0")
+
+        root_path = File.expand_path(root)
+        full = File.expand_path(File.join(root_path, path.delete_prefix("/")))
+        return nil unless full.start_with?("#{root_path}#{File::SEPARATOR}")
+        return nil unless File.file?(full)
+
+        entry_for(path, File.binread(full))
+      end
+
+      def entry_for(path, body)
+        digest = Digest::SHA256.hexdigest(body)[0, 16]
+        { type: content_type(path), digest: digest, etag: %("#{digest}"), body: body }
+      end
+
+      def fresh?(env, entry)
+        env["HTTP_IF_NONE_MATCH"].to_s.split(",").any? { |candidate| candidate.strip == entry[:etag] }
+      end
+
+      def cache_control(env, entry)
+        return NO_CACHE unless production?
+
+        env["QUERY_STRING"].to_s.split("&").include?("v=#{entry[:digest]}") ? IMMUTABLE : REVALIDATE
+      end
+    end
+
+    @root = DEFAULT_ROOT
+    @manifest = {}
+    @production = false
+
+    Monk.freeze_hooks << self
+  end
+end

data/lib/monk/auth/errors.rb

@@ -0,0 +1,13 @@
+module Monk
+  class AuthNotConfiguredError < StandardError
+  end
+
+  class InvalidRedirectError < StandardError
+  end
+
+  class MissingAuthConfigError < StandardError
+  end
+
+  class MissingAuthDeliveryError < StandardError
+  end
+end

data/lib/monk/auth/helpers.rb

@@ -0,0 +1,76 @@
+require_relative "../context"
+
+module Monk
+  module Auth
+    # Mixed into Monk::Context (docs/design/auth-sessions.md's "Helpers, not
+    # state"): a Context is per-request and never crosses Ractors, so
+    # memoizing current_subject on it is exempt from the app's
+    # shareability constraints -- nothing here needs Ractor.make_shareable.
+    module Helpers
+      def current_subject
+        return @current_subject if defined?(@current_subject)
+
+        @current_subject = Monk::Auth.verify(bearer_token || session_cookie_token)
+      end
+
+      def require_user!
+        current_subject || halt(401)
+      end
+
+      # A no-op for Bearer-authenticated requests: a cross-origin attacker
+      # page has no channel to set an Authorization header at all, so the
+      # CSRF vector only exists for the cookie-authenticated path
+      # (docs/design/auth-sessions.md's "CSRF: stateless double-submit").
+      def require_csrf!
+        return if bearer_token
+
+        cookie_token = session_cookie_token
+        provided = header("x-csrf-token")
+        return if cookie_token && provided && OpenSSL.secure_compare(Monk::Auth.csrf_token_for(cookie_token), provided)
+
+        halt(403)
+      end
+
+      def set_session_cookie(session)
+        max_age = [(session[:expires_at] - Time.now).to_i, 0].max
+        add_response_cookie("session_token", session[:token], http_only: true, max_age: max_age)
+        add_response_cookie("csrf_token", Monk::Auth.csrf_token_for(session[:token]), http_only: false, max_age: max_age)
+      end
+
+      def clear_session_cookie
+        add_response_cookie("session_token", "", http_only: true, max_age: 0)
+        add_response_cookie("csrf_token", "", http_only: false, max_age: 0)
+      end
+
+      private
+
+      def bearer_token
+        auth_header = header("authorization")
+        return nil unless auth_header&.start_with?("Bearer ")
+
+        token = auth_header.delete_prefix("Bearer ")
+        token.empty? ? nil : token
+      end
+
+      def add_response_cookie(name, value, http_only:, max_age:)
+        flags = ["Path=/", "SameSite=Lax", "Max-Age=#{max_age}"]
+        flags << "Secure" if Monk::Auth.config[:secure]
+        flags << "HttpOnly" if http_only
+        headers["set-cookie"] = Array(headers["set-cookie"]) + ["#{name}=#{value}; #{flags.join("; ")}"]
+      end
+
+      def request_cookies
+        header("cookie").to_s.split(";").each_with_object({}) do |pair, cookies|
+          name, value = pair.strip.split("=", 2)
+          cookies[name] = value if name
+        end
+      end
+
+      def session_cookie_token
+        request_cookies["session_token"]
+      end
+    end
+  end
+end
+
+Monk::Context.include(Monk::Auth::Helpers)

data/lib/monk/auth/login_token.rb

@@ -0,0 +1,11 @@
+require_relative "../persistence/pg/model"
+
+module Monk
+  module Auth
+    # Internal storage for magic-link tokens -- not part of Monk::Auth's
+    # public API (docs/design/auth-sessions.md's "Two tokens, not one").
+    class LoginToken < Monk::Persistence::Pg::Model
+      self.table_name = "login_tokens"
+    end
+  end
+end

data/lib/monk/auth/rate_limiter.rb

@@ -0,0 +1,46 @@
+require_relative "../state_ractor"
+
+module Monk
+  module Auth
+    # Per-process, approximate rate limiting for POST /auth/request
+    # (docs/design/auth-sessions.md: StateRactor's "real job" here -- durability is
+    # explicitly not a goal). Frozen at construction, like StateRactor
+    # itself: that's what makes #exceeded? able to build a fresh #update
+    # block per call with a shareable self, satisfying CONTEXT.md's
+    # StateRactor rule ("build it where self is shareable... not inline in
+    # a route handler") without needing StateRactor#update to grow an
+    # argument-passing API just to thread a per-call key through.
+    class RateLimiter
+      def initialize(limit:, window:)
+        @limit = limit
+        @window = window
+        @counts = Monk::StateRactor.new({})
+        freeze
+      end
+
+      # True if `key` has already made more than `limit` calls within the
+      # current `window`-second window; also counts this call toward it.
+      def exceeded?(key)
+        # Ractor.make_shareable on a Proc requires every variable it
+        # captures to already be shareable -- it verifies, it doesn't
+        # freeze on the caller's behalf. Integers are always frozen; a
+        # caller-supplied String generally isn't, so dup+freeze a local
+        # copy (a distinct binding, not a reassignment of `key` -- a
+        # captured variable that could be reassigned is itself rejected as
+        # unshareable, regardless of what it holds at call time).
+        frozen_key = key.dup.freeze
+        limit = @limit
+        window = @window
+        now = Time.now.to_i
+
+        counts = @counts.update do |current|
+          count, window_start = current[frozen_key] || [0, now]
+          count, window_start = 0, now if now - window_start >= window
+          current.merge(frozen_key => [count + 1, window_start])
+        end
+
+        counts[frozen_key].first > limit
+      end
+    end
+  end
+end

data/lib/monk/auth/session.rb

@@ -0,0 +1,11 @@
+require_relative "../persistence/pg/model"
+
+module Monk
+  module Auth
+    # Internal storage for session tokens -- not part of Monk::Auth's public
+    # API (docs/design/auth-sessions.md's "Two tokens, not one").
+    class Session < Monk::Persistence::Pg::Model
+      self.table_name = "sessions"
+    end
+  end
+end