jimmu 1.0.0

data/lib/jimmu.rb

@@ -0,0 +1,1916 @@
+# frozen_string_literal: false
+#
+# Jimmu (神武) - A lightweight, single-file Ruby web framework.
+#
+# "Full-featured but simple."
+# "Build small web apps quickly, from a single file."
+#
+# Jimmu bundles ERB templating, file-based routing, SQLite (via a
+# dependency-free Fiddle binding to the system libsqlite3), WebSocket
+# support, sessions, cookies, and a small JSON/HTML/text response API
+# into one file with no gem dependencies beyond the Ruby standard
+# library.
+#
+# https://github.com/ (project home - edit me)
+#
+# Copyright and license: see LICENSE.
+
+require 'erb'
+require 'socket'
+require 'digest/sha1'
+require 'base64'
+require 'securerandom'
+require 'time'
+require 'json'
+require 'uri'
+require 'cgi'
+require 'fileutils'
+require 'optparse'
+require 'monitor'
+require 'fiddle'
+require 'fiddle/import'
+
+module Jimmu
+  VERSION = '1.0.0'
+
+  class << self
+    # The single Application instance that app.rb's top-level DSL
+    # calls (port, before, websocket, run, ...) delegate to. Set by
+    # Application#load_app_file just before `load`ing app.rb.
+    attr_accessor :application
+  end
+
+  # Base class for all Jimmu-specific errors.
+  class Error < StandardError; end
+
+  # Raised when the SQLite shared library cannot be located, or when a
+  # query fails.
+  class DatabaseError < Error; end
+
+  # Raised when app.rb cannot be found or fails to load.
+  class ConfigError < Error; end
+
+  # Internal symbol used with `throw`/`catch` to unwind out of ERB
+  # evaluation as soon as a response-terminating DSL method
+  # (redirect / json / text / html / render) is called. This is a
+  # lightweight, non-exception based control-flow jump: the methods
+  # that call it have already recorded the final status/headers/body
+  # on the Context object before throwing, so the catch site simply
+  # reads those back off the Context.
+  HALT = :jimmu_halt
+
+  # Maximum accepted request body size (form posts / uploads), in bytes.
+  # This exists purely as a safety net against a client claiming an
+  # enormous Content-Length; it is not a tuning knob most apps need to
+  # touch. 50 MB is generous for a "small-to-medium" app.
+  MAX_BODY_SIZE = 50 * 1024 * 1024
+
+  # File extension -> MIME type, used for static file serving.
+  MIME_TYPES = {
+    '.html' => 'text/html; charset=utf-8',
+    '.htm'  => 'text/html; charset=utf-8',
+    '.css'  => 'text/css; charset=utf-8',
+    '.js'   => 'text/javascript; charset=utf-8',
+    '.mjs'  => 'text/javascript; charset=utf-8',
+    '.json' => 'application/json; charset=utf-8',
+    '.txt'  => 'text/plain; charset=utf-8',
+    '.xml'  => 'application/xml; charset=utf-8',
+    '.csv'  => 'text/csv; charset=utf-8',
+    '.md'   => 'text/markdown; charset=utf-8',
+    '.png'  => 'image/png',
+    '.jpg'  => 'image/jpeg',
+    '.jpeg' => 'image/jpeg',
+    '.gif'  => 'image/gif',
+    '.svg'  => 'image/svg+xml',
+    '.webp' => 'image/webp',
+    '.ico'  => 'image/x-icon',
+    '.bmp'  => 'image/bmp',
+    '.woff' => 'font/woff',
+    '.woff2' => 'font/woff2',
+    '.ttf'  => 'font/ttf',
+    '.otf'  => 'font/otf',
+    '.eot'  => 'application/vnd.ms-fontobject',
+    '.mp3'  => 'audio/mpeg',
+    '.wav'  => 'audio/wav',
+    '.ogg'  => 'audio/ogg',
+    '.mp4'  => 'video/mp4',
+    '.webm' => 'video/webm',
+    '.pdf'  => 'application/pdf',
+    '.zip'  => 'application/zip',
+    '.wasm' => 'application/wasm',
+    '.map'  => 'application/json; charset=utf-8'
+  }
+  MIME_TYPES.default = 'application/octet-stream'
+  MIME_TYPES.freeze
+
+  # HTTP status code -> reason phrase.
+  STATUS_PHRASES = {
+    100 => 'Continue', 101 => 'Switching Protocols',
+    200 => 'OK', 201 => 'Created', 202 => 'Accepted', 204 => 'No Content', 206 => 'Partial Content',
+    301 => 'Moved Permanently', 302 => 'Found', 303 => 'See Other', 304 => 'Not Modified',
+    307 => 'Temporary Redirect', 308 => 'Permanent Redirect',
+    400 => 'Bad Request', 401 => 'Unauthorized', 403 => 'Forbidden', 404 => 'Not Found',
+    405 => 'Method Not Allowed', 406 => 'Not Acceptable', 408 => 'Request Timeout',
+    409 => 'Conflict', 410 => 'Gone', 411 => 'Length Required', 413 => 'Payload Too Large',
+    414 => 'URI Too Long', 415 => 'Unsupported Media Type', 422 => 'Unprocessable Entity',
+    426 => 'Upgrade Required', 429 => 'Too Many Requests',
+    500 => 'Internal Server Error', 501 => 'Not Implemented', 502 => 'Bad Gateway',
+    503 => 'Service Unavailable', 504 => 'Gateway Timeout'
+  }.freeze
+
+  def self.status_phrase(code)
+    STATUS_PHRASES[code.to_i] || 'Unknown Status'
+  end
+
+  # Percent-decode a URL path segment (`%XX` sequences only; unlike
+  # form/query decoding, `+` is left as a literal plus in paths).
+  def self.percent_decode(str)
+    str.gsub(/%([0-9A-Fa-f]{2})/) { [Regexp.last_match(1)].pack('H2') }
+  end
+end
+module Jimmu
+  # Minimal Fiddle-based binding to the system's libsqlite3. This
+  # avoids requiring the `sqlite3` gem (and therefore avoids a native
+  # extension compile step) by calling directly into the SQLite C API
+  # that ships with the OS (Linux/macOS) or can be dropped in as a DLL
+  # (Windows).
+  module SQLite3FFI
+    extend Fiddle::Importer
+
+    LIB_CANDIDATES =
+      if Fiddle::WINDOWS
+        %w[sqlite3.dll]
+      elsif RbConfig::CONFIG['host_os'] =~ /darwin/
+        %w[libsqlite3.dylib /usr/lib/libsqlite3.dylib /opt/homebrew/lib/libsqlite3.dylib /usr/local/lib/libsqlite3.dylib]
+      else
+        %w[libsqlite3.so.0 libsqlite3.so /usr/lib/x86_64-linux-gnu/libsqlite3.so.0 /usr/lib/libsqlite3.so.0]
+      end.freeze
+
+    loaded_lib = LIB_CANDIDATES.find do |lib|
+      begin
+        dlload lib
+        true
+      rescue Fiddle::DLError
+        false
+      end
+    end
+
+    LOADED = !loaded_lib.nil?
+
+    if LOADED
+      extern 'int sqlite3_open(const char*, void**)'
+      extern 'int sqlite3_close(void*)'
+      extern 'int sqlite3_prepare_v2(void*, const char*, int, void**, void**)'
+      extern 'int sqlite3_step(void*)'
+      extern 'int sqlite3_finalize(void*)'
+      extern 'int sqlite3_reset(void*)'
+      extern 'int sqlite3_column_count(void*)'
+      extern 'const char* sqlite3_column_name(void*, int)'
+      extern 'int sqlite3_column_type(void*, int)'
+      extern 'const char* sqlite3_column_text(void*, int)'
+      extern 'double sqlite3_column_double(void*, int)'
+      extern 'long long sqlite3_column_int64(void*, int)'
+      extern 'int sqlite3_column_bytes(void*, int)'
+      extern 'const void* sqlite3_column_blob(void*, int)'
+      extern 'int sqlite3_bind_text(void*, int, const char*, int, void*)'
+      extern 'int sqlite3_bind_int64(void*, int, long long)'
+      extern 'int sqlite3_bind_double(void*, int, double)'
+      extern 'int sqlite3_bind_null(void*, int)'
+      extern 'int sqlite3_bind_blob(void*, int, const void*, int, void*)'
+      extern 'const char* sqlite3_errmsg(void*)'
+      extern 'int sqlite3_changes(void*)'
+      extern 'long long sqlite3_last_insert_rowid(void*)'
+      extern 'int sqlite3_busy_timeout(void*, int)'
+    end
+  end
+
+  # A small SQLite wrapper exposing the query / exec / transaction API
+  # described in the Jimmu spec. A single Database instance may be
+  # shared across the many request-handling threads the server spawns;
+  # all access to the underlying sqlite3 connection handle is
+  # serialized through a re-entrant Monitor so that (a) concurrent
+  # requests never touch the C-level handle at the same time and
+  # (b) a block passed to #transaction can itself call #query / #exec
+  # on the same thread without deadlocking.
+  class Database
+    SQLITE_OK = 0
+    SQLITE_ROW = 100
+    SQLITE_DONE = 101
+    SQLITE_INTEGER = 1
+    SQLITE_FLOAT = 2
+    SQLITE_TEXT = 3
+    SQLITE_BLOB = 4
+    SQLITE_NULL = 5
+    SQLITE_TRANSIENT = Fiddle::Pointer.new(-1)
+
+    attr_reader :path
+
+    def initialize(path)
+      unless SQLite3FFI::LOADED
+        raise DatabaseError,
+              "Could not locate the SQLite3 shared library on this system " \
+              "(looked for: #{SQLite3FFI::LIB_CANDIDATES.join(', ')}). " \
+              "Install SQLite3 (e.g. `apt install libsqlite3-0`, `brew install sqlite3`); " \
+              "it ships with macOS by default, and Windows needs sqlite3.dll on the PATH."
+      end
+
+      @path = path
+      dir = File.dirname(path)
+      FileUtils.mkdir_p(dir) unless dir == '.' || Dir.exist?(dir)
+
+      @lock = Monitor.new
+      dbptr = Fiddle::Pointer.malloc(Fiddle::SIZEOF_VOIDP)
+      rc = SQLite3FFI.sqlite3_open(path.to_s, dbptr)
+      @db = dbptr.ptr
+      if rc != SQLITE_OK
+        raise DatabaseError, "Could not open database at #{path.inspect} (sqlite3_open returned #{rc})"
+      end
+      SQLite3FFI.sqlite3_busy_timeout(@db, 5000)
+    end
+
+    # Run a SELECT (or any statement that returns rows) and return an
+    # Array of Hashes, keyed by column name (as Symbols).
+    #
+    #   db.query("SELECT * FROM users")
+    #   db.query("SELECT * FROM users WHERE id = ?", id)
+    def query(sql, *binds)
+      @lock.synchronize { run_query(sql, binds) }
+    end
+
+    # Run an INSERT / UPDATE / DELETE / DDL statement. Returns the
+    # number of rows changed by the statement (via sqlite3_changes).
+    #
+    #   db.exec("INSERT INTO users(name) VALUES (?)", "Yamato")
+    def exec(sql, *binds)
+      @lock.synchronize { run_exec(sql, binds) }
+    end
+
+    # Wrap a block in BEGIN / COMMIT. If the block raises, the
+    # transaction is rolled back and the error re-raised.
+    #
+    #   db.transaction do
+    #     db.exec(...)
+    #     db.exec(...)
+    #   end
+    def transaction
+      @lock.synchronize do
+        run_exec('BEGIN', [])
+        begin
+          result = yield
+          run_exec('COMMIT', [])
+          result
+        rescue Exception => e
+          begin
+            run_exec('ROLLBACK', [])
+          rescue Exception
+            nil # the original error is more useful than a rollback failure
+          end
+          raise e
+        end
+      end
+    end
+
+    # The rowid of the most recent successful INSERT on this
+    # connection.
+    def last_insert_rowid
+      @lock.synchronize { SQLite3FFI.sqlite3_last_insert_rowid(@db) }
+    end
+
+    def close
+      @lock.synchronize do
+        next if @closed
+        SQLite3FFI.sqlite3_close(@db)
+        @closed = true
+      end
+    end
+
+    private
+
+    def prepare(sql)
+      stmtptr = Fiddle::Pointer.malloc(Fiddle::SIZEOF_VOIDP)
+      tailptr = Fiddle::Pointer.malloc(Fiddle::SIZEOF_VOIDP)
+      sql_bytes = sql.to_s.dup.force_encoding(Encoding::UTF_8)
+      rc = SQLite3FFI.sqlite3_prepare_v2(@db, sql_bytes, sql_bytes.bytesize, stmtptr, tailptr)
+      unless rc == SQLITE_OK
+        raise DatabaseError, "SQL error: #{SQLite3FFI.sqlite3_errmsg(@db)} (in query: #{sql})"
+      end
+      stmtptr.ptr
+    end
+
+    def bind_all(stmt, binds)
+      binds.each_with_index do |val, i|
+        idx = i + 1
+        case val
+        when nil
+          SQLite3FFI.sqlite3_bind_null(stmt, idx)
+        when Integer
+          SQLite3FFI.sqlite3_bind_int64(stmt, idx, val)
+        when Float
+          SQLite3FFI.sqlite3_bind_double(stmt, idx, val)
+        when true
+          SQLite3FFI.sqlite3_bind_int64(stmt, idx, 1)
+        when false
+          SQLite3FFI.sqlite3_bind_int64(stmt, idx, 0)
+        else
+          str = val.to_s.dup.force_encoding(Encoding::UTF_8)
+          SQLite3FFI.sqlite3_bind_text(stmt, idx, str, str.bytesize, SQLITE_TRANSIENT)
+        end
+      end
+    end
+
+    def run_query(sql, binds)
+      stmt = prepare(sql)
+      bind_all(stmt, binds)
+      results = []
+      loop do
+        rc = SQLite3FFI.sqlite3_step(stmt)
+        case rc
+        when SQLITE_ROW
+          results << extract_row(stmt)
+        when SQLITE_DONE
+          break
+        else
+          SQLite3FFI.sqlite3_finalize(stmt)
+          raise DatabaseError, "SQL error: #{SQLite3FFI.sqlite3_errmsg(@db)} (in query: #{sql})"
+        end
+      end
+      SQLite3FFI.sqlite3_finalize(stmt)
+      results
+    end
+
+    def run_exec(sql, binds)
+      stmt = prepare(sql)
+      bind_all(stmt, binds)
+      rc = SQLite3FFI.sqlite3_step(stmt)
+      unless rc == SQLITE_DONE || rc == SQLITE_ROW
+        SQLite3FFI.sqlite3_finalize(stmt)
+        raise DatabaseError, "SQL error: #{SQLite3FFI.sqlite3_errmsg(@db)} (in query: #{sql})"
+      end
+      SQLite3FFI.sqlite3_finalize(stmt)
+      SQLite3FFI.sqlite3_changes(@db)
+    end
+
+    def extract_row(stmt)
+      count = SQLite3FFI.sqlite3_column_count(stmt)
+      row = {}
+      count.times do |i|
+        name = SQLite3FFI.sqlite3_column_name(stmt, i).to_s.to_sym
+        row[name] = extract_value(stmt, i)
+      end
+      row
+    end
+
+    def extract_value(stmt, i)
+      type = SQLite3FFI.sqlite3_column_type(stmt, i)
+      case type
+      when SQLITE_INTEGER
+        SQLite3FFI.sqlite3_column_int64(stmt, i)
+      when SQLITE_FLOAT
+        SQLite3FFI.sqlite3_column_double(stmt, i)
+      when SQLITE_TEXT
+        bytes = SQLite3FFI.sqlite3_column_bytes(stmt, i)
+        return ''.dup.force_encoding(Encoding::UTF_8) if bytes.zero?
+        ptr = SQLite3FFI.sqlite3_column_text(stmt, i)
+        ptr.to_s(bytes).force_encoding(Encoding::UTF_8)
+      when SQLITE_BLOB
+        bytes = SQLite3FFI.sqlite3_column_bytes(stmt, i)
+        return ''.b if bytes.zero?
+        ptr = SQLite3FFI.sqlite3_column_blob(stmt, i)
+        ptr.to_s(bytes)
+      when SQLITE_NULL
+        nil
+      end
+    end
+  end
+end
+module Jimmu
+  # Represents one uploaded file from a multipart/form-data request.
+  # Data is held in memory as a binary String; call #save to write it
+  # to disk.
+  #
+  #   file = params[:image]
+  #   file.filename       # "photo.png"
+  #   file.content_type   # "image/png"
+  #   file.size           # 48213
+  #   file.save("public/uploads/photo.png")
+  UploadedFile = Struct.new(:filename, :content_type, :data) do
+    def size
+      data.bytesize
+    end
+
+    def save(path)
+      dir = File.dirname(path)
+      FileUtils.mkdir_p(dir) unless Dir.exist?(dir)
+      File.open(path, 'wb') { |f| f.write(data) }
+      path
+    end
+
+    def empty?
+      data.nil? || data.empty?
+    end
+  end
+
+  # Parses application/x-www-form-urlencoded and multipart/form-data
+  # request bodies, and application/json bodies. All parsing is done
+  # byte-safe (ASCII-8BIT) throughout and only the final text values
+  # are tagged back to UTF-8, so binary upload data is never at risk
+  # of being mangled or raising encoding errors partway through.
+  module BodyParser
+    module_function
+
+    def parse_urlencoded(raw_body)
+      str = raw_body.to_s.dup.force_encoding(Encoding::UTF_8)
+      result = {}
+      URI.decode_www_form(str, Encoding::UTF_8).each do |k, v|
+        result[k.to_sym] = v
+      end
+      result
+    rescue ArgumentError
+      {}
+    end
+
+    def parse_json(raw_body)
+      return {} if raw_body.nil? || raw_body.empty?
+      data = JSON.parse(raw_body.dup.force_encoding(Encoding::UTF_8), symbolize_names: true)
+      data.is_a?(Hash) ? data : { _json: data }
+    rescue JSON::ParserError
+      {}
+    end
+
+    # Returns [fields_hash, files_hash], both keyed by Symbol.
+    def parse_multipart(raw_body, boundary)
+      fields = {}
+      files = {}
+      return [fields, files] if raw_body.nil? || boundary.nil? || boundary.empty?
+
+      body = raw_body.dup.force_encoding(Encoding::BINARY)
+      delim = "--#{boundary}".b
+
+      body.split(delim).each do |part|
+        next if part.nil? || part.empty?
+        next if part.start_with?('--'.b)
+
+        part = part.sub(/\A\r\n/n, ''.b)
+        part = part.sub(/\r\n\z/n, ''.b)
+        next if part.empty?
+
+        header_section, sep, body_section = part.partition("\r\n\r\n".b)
+        next if sep.empty?
+
+        headers = {}
+        header_section.split("\r\n".b).each do |line|
+          k, v = line.split(':'.b, 2)
+          next unless k && v
+          headers[k.strip.downcase] = v.strip
+        end
+
+        disposition = headers['content-disposition'.b]
+        next unless disposition
+
+        name = disposition[/name="([^"]*)"/n, 1] || disposition[/name=([^;]*)/n, 1]
+        next unless name
+
+        name_sym = name.dup.force_encoding(Encoding::UTF_8).to_sym
+        filename = disposition[/filename="([^"]*)"/n, 1]
+
+        if filename
+          content_type = (headers['content-type'.b] || 'application/octet-stream').dup.force_encoding(Encoding::UTF_8)
+          files[name_sym] = UploadedFile.new(filename.dup.force_encoding(Encoding::UTF_8), content_type, body_section)
+        else
+          fields[name_sym] = body_section.dup.force_encoding(Encoding::UTF_8)
+        end
+      end
+
+      [fields, files]
+    end
+
+    def extract_boundary(content_type)
+      return nil unless content_type
+      content_type[/boundary="?([^";]+)"?/, 1]
+    end
+  end
+
+  # A parsed HTTP request. Constructed once per connection by
+  # Application's connection-handling code; passed into Context.
+  class Request
+    attr_reader :http_method, :path, :query_string, :raw_headers, :body, :ip, :http_version
+    attr_accessor :route_params
+
+    def initialize(http_method:, path:, query_string:, headers:, body:, ip:)
+      @http_method = http_method
+      @path = path
+      @query_string = query_string || ''
+      @raw_headers = headers # Hash, lowercase String keys => String values
+      @body = body || ''.b
+      @ip = ip
+      @route_params = {}
+    end
+
+    # Public DSL name (spec: request.method)
+    def method
+      @http_method
+    end
+
+    def header(name)
+      @raw_headers[name.to_s.downcase]
+    end
+
+    def content_type
+      header('content-type')
+    end
+
+    def query_params
+      @query_params ||= begin
+        h = {}
+        URI.decode_www_form(@query_string, Encoding::UTF_8).each { |k, v| h[k.to_sym] = v } unless @query_string.empty?
+        h
+      rescue ArgumentError
+        {}
+      end
+    end
+
+    def body_params
+      @body_params ||= compute_body_params
+    end
+
+    def uploaded_files
+      @uploaded_files ||= begin
+        compute_body_params
+        @uploaded_files_cache || {}
+      end
+    end
+
+    # Query params, then body params, then route (file-based dynamic
+    # segment) params, then uploaded files -- later sources win on key
+    # collision, with route params taking precedence as the most
+    # specific/intentional source, and uploaded files layered on top
+    # since their field names are defined by the form itself.
+    def params
+      @params ||= query_params.merge(body_params).merge(route_params).merge(uploaded_files)
+    end
+
+    private
+
+    def compute_body_params
+      return @body_params_cache if defined?(@body_params_cache)
+      ctype = content_type.to_s
+      if ctype.start_with?('multipart/form-data')
+        boundary = BodyParser.extract_boundary(ctype)
+        fields, files = BodyParser.parse_multipart(@body, boundary)
+        @uploaded_files_cache = files
+        @body_params_cache = fields
+      elsif ctype.start_with?('application/json')
+        @uploaded_files_cache = {}
+        @body_params_cache = BodyParser.parse_json(@body)
+      elsif ctype.start_with?('application/x-www-form-urlencoded')
+        @uploaded_files_cache = {}
+        @body_params_cache = BodyParser.parse_urlencoded(@body)
+      else
+        @uploaded_files_cache = {}
+        @body_params_cache = {}
+      end
+    end
+  end
+
+  # Read/write access to request and response cookies for a single
+  # request. `cookie[:user]` reads an incoming cookie value (or nil).
+  # `cookie[:user] = "value"` queues a Set-Cookie header on the
+  # response. Values are transparently percent-encoded/decoded so any
+  # text (including Japanese) round-trips safely.
+  class CookieJar
+    def initialize(cookie_header)
+      @incoming = {}
+      cookie_header.to_s.split(';').each do |pair|
+        k, v = pair.split('=', 2)
+        next unless k
+        k = k.strip
+        next if k.empty?
+        v = (v || '').strip
+        @incoming[k] = begin
+          URI.decode_www_form_component(v)
+        rescue ArgumentError
+          v
+        end
+      end
+      @outgoing = []
+    end
+
+    def [](name)
+      @incoming[name.to_s]
+    end
+
+    def []=(name, value)
+      set(name, value)
+    end
+
+    # Full control over cookie attributes when needed.
+    def set(name, value, path: '/', max_age: nil, expires: nil, http_only: false, secure: false, same_site: nil)
+      parts = ["#{name}=#{URI.encode_www_form_component(value.to_s)}"]
+      parts << "Path=#{path}" if path
+      parts << "Max-Age=#{max_age.to_i}" if max_age
+      parts << "Expires=#{expires.httpdate}" if expires
+      parts << 'HttpOnly' if http_only
+      parts << 'Secure' if secure
+      parts << "SameSite=#{same_site}" if same_site
+      @outgoing << parts.join('; ')
+      value
+    end
+
+    def delete(name, path: '/')
+      set(name, '', path: path, max_age: 0, expires: Time.at(0))
+    end
+
+    def to_a
+      @incoming.dup
+    end
+
+    def response_header_values
+      @outgoing
+    end
+  end
+
+  # Thread-safe, in-memory server-side session store shared by the
+  # whole Application. Session data does not survive a server
+  # restart -- this is a development-focused framework, and adding a
+  # persistent backend is left as an extension point.
+  class SessionStore
+    COOKIE_NAME = '_jimmu_session'
+    DEFAULT_MAX_AGE = 60 * 60 * 24 # 24 hours, refreshed on every response
+
+    def initialize
+      @sessions = {}
+      @lock = Mutex.new
+    end
+
+    # Returns [session_id, session_hash, newly_created]
+    def fetch_or_create(session_id)
+      @lock.synchronize do
+        if session_id && @sessions.key?(session_id)
+          [session_id, @sessions[session_id], false]
+        else
+          id = SecureRandom.hex(16)
+          @sessions[id] = {}
+          [id, @sessions[id], true]
+        end
+      end
+    end
+
+    def destroy(session_id)
+      @lock.synchronize { @sessions.delete(session_id) }
+    end
+  end
+end
+module Jimmu
+  BUILTIN_ERROR_CSS = <<~CSS.freeze
+    body{margin:0;padding:0;background:#1e1f26;color:#e8e8ec;font-family:-apple-system,BlinkMacSystemFont,"Segoe UI",Helvetica,Arial,sans-serif}
+    .jimmu-error{max-width:760px;margin:6vh auto;padding:0 24px}
+    .jimmu-error h1{font-size:22px;color:#ff6b6b;border-bottom:1px solid #34353f;padding-bottom:14px;margin-bottom:18px}
+    .jimmu-error p{line-height:1.6;color:#c3c4cf}
+    .jimmu-error-class{font-family:ui-monospace,SFMono-Regular,Menlo,Consolas,monospace;font-size:14px;background:#2a2b35;padding:10px 14px;border-radius:6px;color:#ffb1b1}
+    .jimmu-error-trace{background:#26272f;border-radius:6px;padding:16px;overflow-x:auto;font-size:12.5px;line-height:1.6;color:#9fa3b5}
+    .jimmu-error-hint{font-size:13px;color:#767a8c;margin-top:20px}
+    .jimmu-error a{color:#7aa2ff}
+  CSS
+
+  # Context is instantiated once per HTTP request. It is the `self`
+  # against which ERB templates, layouts, and before/after hook blocks
+  # all run (via instance_eval / a bound top-level `binding`), which is
+  # what makes bare DSL calls like `params`, `redirect "/login"`, or
+  # `session[:user]` work naturally inside a .erb file.
+  class Context
+    attr_reader :status_code, :response_headers, :session_id
+    attr_accessor :response_body, :error
+
+    def initialize(application, request, cookie_jar, session_id, session_hash, new_session)
+      @application = application
+      @request = request
+      @cookie_jar = cookie_jar
+      @session_id = session_id
+      @session_hash = session_hash
+      @new_session = new_session
+      @status_code = 200
+      @response_headers = {}
+      @response_body = nil
+      @use_layout = true
+      @error = nil
+    end
+
+    # ---- DSL: read accessors -------------------------------------------
+
+    def params
+      @request.params
+    end
+
+    def request
+      @request
+    end
+
+    def cookie
+      @cookie_jar
+    end
+
+    def session
+      @session_hash
+    end
+
+    # ---- DSL: response building -----------------------------------------
+
+    def status(code)
+      @status_code = code.to_i
+      nil
+    end
+
+    def header(name, value)
+      @response_headers[name.to_s] = value.to_s
+      nil
+    end
+
+    def log(message)
+      @application.log(message)
+      nil
+    end
+
+    def db
+      @application.default_db
+    end
+
+    def layout(enabled)
+      @use_layout = enabled ? true : false
+      nil
+    end
+
+    # ---- DSL: response-terminating actions ------------------------------
+    # Each of these fully determines the response and immediately
+    # unwinds out of whatever ERB template (or before-hook) called it,
+    # via `throw Jimmu::HALT`. The dispatch loop in Application wraps
+    # request handling in `catch(Jimmu::HALT)`, so this jump is always
+    # caught -- see Application#dispatch.
+
+    def redirect(location, code = 302)
+      @status_code = code
+      @response_headers['Location'] = location.to_s
+      @response_body = ''
+      throw HALT
+    end
+
+    def json(data)
+      @response_headers['Content-Type'] = 'application/json; charset=utf-8'
+      @response_body = data.to_json
+      throw HALT
+    end
+
+    def text(str)
+      @response_headers['Content-Type'] = 'text/plain; charset=utf-8'
+      @response_body = str.to_s
+      throw HALT
+    end
+
+    def html(str)
+      @response_headers['Content-Type'] = 'text/html; charset=utf-8'
+      @response_body = str.to_s
+      throw HALT
+    end
+
+    def render(name)
+      @response_body = render_file(resolve_view_path(name))
+      @response_headers['Content-Type'] ||= 'text/html; charset=utf-8'
+      throw HALT
+    end
+
+    # ---- Internal rendering pipeline (not part of the ERB-facing DSL) --
+
+    # Renders a static file's bytes directly, without ERB or layout.
+    def serve_static_file(path)
+      @response_body = File.binread(path)
+      @response_headers['Content-Type'] = MIME_TYPES[File.extname(path).downcase]
+      nil
+    end
+
+    # Renders `views/<code>.erb` if present (through the normal
+    # ERB+layout pipeline, so it has full access to params/session/etc),
+    # falling back to a built-in page if it is missing or itself
+    # raises.
+    def render_error_page(code)
+      @status_code = code
+      path = resolve_view_path(code.to_s)
+      if File.file?(path)
+        begin
+          return render_file(path)
+        rescue Exception => e
+          @application.log("[jimmu] error while rendering views/#{code}.erb: #{e.class}: #{e.message}")
+        end
+      end
+      built_in_error_page(code)
+    end
+
+    # Renders the .erb file at `path`, wrapping it in views/layout.erb
+    # unless the template disabled that via `layout false`. This is
+    # used both for the initially-matched route and by the `render`
+    # DSL method above.
+    def render_file(path)
+      raise Jimmu::Error, "Template not found: #{path}" unless File.file?(path)
+
+      @use_layout = true
+      content = evaluate_erb(read_template(path))
+      return content unless @use_layout
+
+      layout_path = File.join(@application.views_dir, 'layout.erb')
+      return content unless File.file?(layout_path)
+
+      layout_src = read_template(layout_path)
+      wrap_with_layout(content, layout_src)
+    end
+
+    private
+
+    def read_template(path)
+      File.read(path, encoding: Encoding::UTF_8)
+    end
+
+    def resolve_view_path(name)
+      rel = name.to_s
+      rel = "#{rel}.erb" unless rel.end_with?('.erb')
+      File.join(@application.views_dir, rel)
+    end
+
+    def evaluate_erb(src)
+      erb = ERB.new(src, trim_mode: '-')
+      erb.result(binding)
+    end
+
+    def wrap_with_layout(content, layout_src)
+      erb = ERB.new(layout_src, trim_mode: '-')
+      capture_and_render(erb) { content }
+    end
+
+    # `binding` is captured directly in this method's own body (not
+    # nested inside a further block), so that a bare `yield` inside
+    # the layout ERB -- once compiled and eval'd against that binding
+    # -- correctly resolves to the block passed to *this* call
+    # (`{ content }` from wrap_with_layout above), rather than to any
+    # outer method. This is the standard trick ERB-based frameworks
+    # use to support `<%= yield %>` in layouts.
+    def capture_and_render(erb)
+      erb.result(binding)
+    end
+
+    def built_in_error_page(code)
+      title = code == 404 ? '404 Not Found' : "#{code} Internal Server Error"
+      if code == 500 && @error
+        backtrace = @error.backtrace ? @error.backtrace.first(25).join("\n") : '(no backtrace available)'
+        <<~HTML
+          <!DOCTYPE html>
+          <html><head><meta charset="UTF-8"><title>500 Internal Server Error</title>
+          <style>#{BUILTIN_ERROR_CSS}</style></head>
+          <body><div class="jimmu-error">
+          <h1>500 Internal Server Error</h1>
+          <p class="jimmu-error-class">#{CGI.escapeHTML(@error.class.to_s)}: #{CGI.escapeHTML(@error.message.to_s)}</p>
+          <pre class="jimmu-error-trace">#{CGI.escapeHTML(backtrace)}</pre>
+          <p class="jimmu-error-hint">This detailed page is shown because no <code>views/500.erb</code> was found (or it raised too). Add one to customize error handling -- it can read <code>error.message</code> and <code>error.backtrace</code> if you want to keep showing details, or just show a friendly message.</p>
+          </div></body></html>
+        HTML
+      else
+        message = code == 404 ? 'The page you requested could not be found.' : 'Something went wrong while handling this request.'
+        <<~HTML
+          <!DOCTYPE html>
+          <html><head><meta charset="UTF-8"><title>#{title}</title>
+          <style>#{BUILTIN_ERROR_CSS}</style></head>
+          <body><div class="jimmu-error"><h1>#{title}</h1><p>#{message}</p></div></body></html>
+        HTML
+      end
+    end
+  end
+end
+module Jimmu
+  # Resolves request paths to .erb files under views/, following the
+  # file-based routing convention described in the Jimmu spec:
+  #
+  #   views/index.erb            ->  /
+  #   views/about.erb            ->  /about
+  #   views/blog/index.erb       ->  /blog
+  #   views/blog/post.erb        ->  /blog/post
+  #   views/user/[id].erb        ->  /user/:id
+  #   views/post/[category]/[id].erb -> /post/:category/:id
+  #
+  # A literal path segment always wins over a `[dynamic]` one at the
+  # same directory level (so views/user/admin.erb beats
+  # views/user/[id].erb for the request "/user/admin", while any other
+  # value still falls through to the dynamic route).
+  #
+  # Directory entries are enumerated directly (Dir.children) rather
+  # than matched with Dir.glob bracket patterns, since glob's `[...]`
+  # character-class syntax collides with the literal `[name]` folder
+  # naming convention and is easy to get subtly wrong across relative
+  # vs. absolute paths.
+  module Router
+    module_function
+
+    # Returns [file_path, params] or nil.
+    def resolve_view(views_dir, request_path)
+      segments = split_segments(request_path)
+      resolve_dir(views_dir, segments, {})
+    end
+
+    # Returns the on-disk path if `request_path` maps to a real file
+    # under public_dir, else nil. Guards against path traversal.
+    def resolve_static(public_dir, request_path)
+      return nil if request_path.include?('..')
+      decoded = Jimmu.percent_decode(request_path)
+      return nil if decoded.include?('..')
+      path = File.join(public_dir, decoded)
+      return nil unless path.start_with?(File.expand_path(public_dir) + File::SEPARATOR) ||
+                         File.expand_path(path).start_with?(File.expand_path(public_dir) + File::SEPARATOR)
+      File.file?(path) ? path : nil
+    end
+
+    # Matches a single registered pattern (e.g. "/room/[name]") against
+    # an incoming request path, used for `websocket` routes. Returns a
+    # params Hash on match, or nil.
+    def match_pattern(pattern, request_path)
+      pattern_segments = split_segments(pattern)
+      path_segments = split_segments(request_path)
+      return nil unless pattern_segments.length == path_segments.length
+
+      params = {}
+      pattern_segments.each_with_index do |seg, i|
+        actual = path_segments[i]
+        if seg.start_with?('[') && seg.end_with?(']')
+          params[seg[1..-2].to_sym] = actual
+        elsif seg != actual
+          return nil
+        end
+      end
+      params
+    end
+
+    def split_segments(path)
+      path.to_s.split('/').reject(&:empty?)
+    end
+
+    def resolve_dir(base_dir, segments, params)
+      return nil unless Dir.exist?(base_dir)
+
+      if segments.empty?
+        idx = File.join(base_dir, 'index.erb')
+        return File.file?(idx) ? [idx, params] : nil
+      end
+
+      seg = segments[0]
+      rest = segments[1..-1]
+
+      if rest.empty?
+        exact = File.join(base_dir, "#{seg}.erb")
+        return [exact, params] if File.file?(exact)
+
+        subdir = File.join(base_dir, seg)
+        if Dir.exist?(subdir)
+          idx = File.join(subdir, 'index.erb')
+          return [idx, params] if File.file?(idx)
+        end
+      else
+        subdir = File.join(base_dir, seg)
+        if Dir.exist?(subdir)
+          result = resolve_dir(subdir, rest, params)
+          return result if result
+        end
+      end
+
+      resolve_dynamic(base_dir, seg, rest, params)
+    end
+
+    def resolve_dynamic(base_dir, seg, rest, params)
+      entries = Dir.children(base_dir).sort
+      if rest.empty?
+        entries.each do |entry|
+          next unless entry.start_with?('[') && entry.end_with?('].erb')
+          f = File.join(base_dir, entry)
+          next unless File.file?(f)
+          name = entry[1...-('].erb'.length)]
+          return [f, params.merge(name.to_sym => seg)]
+        end
+      else
+        entries.each do |entry|
+          next unless entry.start_with?('[') && entry.end_with?(']')
+          d = File.join(base_dir, entry)
+          next unless Dir.exist?(d)
+          name = entry[1..-2]
+          result = resolve_dir(d, rest, params.merge(name.to_sym => seg))
+          return result if result
+        end
+      end
+      nil
+    end
+    private_class_method :resolve_dynamic
+  end
+end
+module Jimmu
+  # RFC 6455 handshake + frame codec. Implements unfragmented and
+  # fragmented text/binary messages, ping/pong, and close frames.
+  # Extensions (permessage-deflate etc.) are not negotiated or
+  # supported, which is the right amount of protocol for a
+  # small-to-medium app framework talking to browser clients.
+  module WebSocketProtocol
+    MAGIC_GUID = '258EAFA5-E914-47DA-95CA-C5AB0DC85B11'
+
+    module_function
+
+    def accept_key(client_key)
+      Base64.strict_encode64(Digest::SHA1.digest(client_key.to_s + MAGIC_GUID))
+    end
+
+    # Reads one complete (possibly fragmented) message from `socket`.
+    # Returns {opcode:, payload:} or nil on EOF/disconnect. Control
+    # frames (close/ping/pong) are returned immediately and are never
+    # fragmented, per spec.
+    def read_message(socket)
+      first_opcode = nil
+      buffer = +''.b
+      loop do
+        frame = read_single_frame(socket)
+        return nil if frame.nil?
+        return frame if [0x8, 0x9, 0xA].include?(frame[:opcode])
+
+        first_opcode ||= frame[:opcode]
+        buffer << frame[:payload]
+        if frame[:fin]
+          payload = first_opcode == 0x1 ? buffer.force_encoding(Encoding::UTF_8) : buffer
+          return { opcode: first_opcode, payload: payload }
+        end
+      end
+    end
+
+    def read_single_frame(socket)
+      hdr = read_exactly(socket, 2)
+      return nil if hdr.nil?
+      b0, b1 = hdr.unpack('C2')
+      fin = (b0 & 0x80) != 0
+      opcode = b0 & 0x0F
+      masked = (b1 & 0x80) != 0
+      len = b1 & 0x7F
+
+      if len == 126
+        ext = read_exactly(socket, 2)
+        return nil if ext.nil?
+        len = ext.unpack1('n')
+      elsif len == 127
+        ext = read_exactly(socket, 8)
+        return nil if ext.nil?
+        len = ext.unpack1('Q>')
+      end
+
+      mask_key = nil
+      if masked
+        mask_key = read_exactly(socket, 4)
+        return nil if mask_key.nil?
+      end
+
+      payload = len.positive? ? read_exactly(socket, len) : ''.b
+      return nil if payload.nil?
+
+      if masked
+        unmasked = +''.b
+        payload.each_byte.with_index { |byte, i| unmasked << (byte ^ mask_key.getbyte(i % 4)) }
+        payload = unmasked
+      end
+
+      { fin: fin, opcode: opcode, payload: payload }
+    end
+
+    def write_frame(socket, opcode, payload, fin: true)
+      payload = payload.to_s.dup.force_encoding(Encoding::BINARY)
+      b0 = (fin ? 0x80 : 0x00) | (opcode & 0x0F)
+      out = +''.b
+      out << [b0].pack('C')
+      len = payload.bytesize
+      if len <= 125
+        out << [len].pack('C')
+      elsif len <= 0xFFFF
+        out << [126, len].pack('Cn')
+      else
+        out << [127, len].pack('CQ>')
+      end
+      out << payload
+      socket.write(out)
+    end
+
+    def read_exactly(socket, n)
+      data = socket.read(n)
+      return nil if data.nil? || data.bytesize < n
+      data
+    rescue IOError, Errno::ECONNRESET, Errno::EPIPE, Errno::ETIMEDOUT
+      nil
+    end
+    private_class_method :read_exactly
+  end
+
+  # Passed as `self` into a `websocket "/path" do ... end` block (via
+  # instance_exec), and as `self` into the on_message / on_close
+  # handler blocks registered from inside it. This is what lets those
+  # blocks call bare `send(...)`, `close`, `params`, `session`, etc.
+  #
+  #   websocket "/room/[name]" do
+  #     log "opened: #{params[:name]}"
+  #     on_message { |msg| send("echo: #{msg}") }
+  #     on_close { log "closed" }
+  #   end
+  class WebSocketConnection
+    attr_reader :params, :request, :cookie, :session
+
+    def initialize(application, socket, request, route_params, cookie_jar, session_hash)
+      @application = application
+      @socket = socket
+      @request = request
+      @params = route_params
+      @cookie = cookie_jar
+      @session = session_hash
+      @message_handler = nil
+      @close_handler = nil
+      @open = true
+    end
+
+    def open?
+      @open
+    end
+
+    def on_message(&block)
+      @message_handler = block
+      nil
+    end
+
+    def on_close(&block)
+      @close_handler = block
+      nil
+    end
+
+    def log(message)
+      @application.log(message)
+      nil
+    end
+
+    def db
+      @application.default_db
+    end
+
+    # Sends a text frame to this client.
+    def send(message)
+      return false unless @open
+      WebSocketProtocol.write_frame(@socket, 0x1, message.to_s)
+      true
+    rescue IOError, Errno::EPIPE, Errno::ECONNRESET
+      @open = false
+      false
+    end
+
+    # Sends a binary frame to this client.
+    def send_binary(bytes)
+      return false unless @open
+      WebSocketProtocol.write_frame(@socket, 0x2, bytes)
+      true
+    rescue IOError, Errno::EPIPE, Errno::ECONNRESET
+      @open = false
+      false
+    end
+
+    def close(code = 1000, reason = '')
+      return unless @open
+      payload = [code].pack('n') + reason.to_s
+      begin
+        WebSocketProtocol.write_frame(@socket, 0x8, payload)
+      rescue IOError, Errno::EPIPE, Errno::ECONNRESET
+        nil
+      end
+      @open = false
+      begin
+        @socket.close
+      rescue IOError
+        nil
+      end
+      nil
+    end
+
+    # Runs the blocking read loop for this connection's lifetime.
+    # Called by Application after the block passed to `websocket` has
+    # been instance_exec'd (so on_message/on_close are registered).
+    def run_loop
+      loop do
+        break unless @open
+        message = WebSocketProtocol.read_message(@socket)
+        break if message.nil?
+
+        case message[:opcode]
+        when 0x1, 0x2
+          safely { @message_handler&.call(message[:payload]) }
+        when 0x8
+          close(1000, '')
+          break
+        when 0x9
+          WebSocketProtocol.write_frame(@socket, 0xA, message[:payload]) rescue nil
+        when 0xA
+          nil # pong received, nothing to do
+        end
+      end
+    rescue IOError, Errno::ECONNRESET, Errno::EPIPE, Errno::ETIMEDOUT
+      nil
+    ensure
+      @open = false
+      safely { @close_handler&.call }
+      begin
+        @socket.close
+      rescue IOError
+        nil
+      end
+    end
+
+    private
+
+    def safely
+      yield
+    rescue Exception => e
+      @application.log("[jimmu] websocket handler error: #{e.class}: #{e.message}")
+    end
+  end
+end
+module Jimmu
+  # Application is the object app.rb runs against (via instance_eval),
+  # which is what makes bare top-level calls like `port 3000`,
+  # `before do ... end`, or `run` work as a DSL. It also owns the
+  # actual TCPServer accept loop and per-connection dispatch once
+  # `run` is called.
+  class Application
+    attr_reader :views_dir, :public_dir, :db_dir, :app_root
+
+    def initialize(app_root)
+      @app_root = File.expand_path(app_root)
+      @views_dir = File.join(@app_root, 'views')
+      @public_dir = File.join(@app_root, 'public')
+      @db_dir = File.join(@app_root, 'db')
+
+      @port = 3000
+      @host = '127.0.0.1'
+      @port_forced = false
+      @host_forced = false
+
+      @before_hooks = []
+      @after_hooks = []
+      @websocket_routes = []
+      @databases = []
+      @default_db = nil
+
+      @session_store = SessionStore.new
+      @log_mutex = Mutex.new
+      @run_called = false
+      @server = nil
+    end
+
+    # ================= DSL methods (called from app.rb) =================
+
+    # `port 8080` sets it (unless overridden with -p on the command
+    # line); `port` with no argument reads the current value.
+    def port(value = nil)
+      return @port if value.nil?
+      @port = value.to_i unless @port_forced
+      nil
+    end
+
+    def host(value = nil)
+      return @host if value.nil?
+      @host = value.to_s unless @host_forced
+      nil
+    end
+
+    # Used internally by the CLI's -p/-h flags, which always win over
+    # whatever app.rb itself requests.
+    def force_port!(value)
+      @port = value.to_i
+      @port_forced = true
+    end
+
+    def force_host!(value)
+      @host = value.to_s
+      @host_forced = true
+    end
+
+    # `db = sqlite "db/app.db"` -- opens (creating if needed) a SQLite
+    # database, relative to the app root. The most recently opened
+    # connection becomes the implicit `db` available inside views.
+    def sqlite(path)
+      full_path = File.expand_path(path, @app_root)
+      database = Database.new(full_path)
+      @databases << database
+      @default_db = database
+      database
+    end
+
+    def default_db
+      @default_db
+    end
+
+    def before(&block)
+      raise ArgumentError, 'before requires a block' unless block
+      @before_hooks << block
+      nil
+    end
+
+    def after(&block)
+      raise ArgumentError, 'after requires a block' unless block
+      @after_hooks << block
+      nil
+    end
+
+    # `websocket "/room/[name]" do ... end` -- the block runs with
+    # self bound to a WebSocketConnection (see WebSocketConnection);
+    # register on_message / on_close from inside it.
+    def websocket(path, &block)
+      raise ArgumentError, 'websocket requires a block' unless block
+      @websocket_routes << [path.to_s, block]
+      nil
+    end
+
+    def log(message, level = :info)
+      @log_mutex.synchronize do
+        ts = Time.now.strftime('%Y-%m-%d %H:%M:%S.%L')
+        $stdout.puts "[#{ts}] #{level.to_s.upcase.ljust(5)} #{message}"
+        $stdout.flush
+      end
+      nil
+    end
+
+    def run
+      @run_called = true
+      start_server
+    end
+
+    def run_called?
+      @run_called
+    end
+
+    # ================= App loading =================
+
+    def load_app_file(path)
+      raise ConfigError, "app.rb not found at #{path}" unless File.file?(path)
+      # Deliberately `load` rather than `instance_eval` a string: Ruby
+      # scopes `def` / `module` / `class` / constants written inside
+      # instance_eval'd source to the receiver's singleton class, which
+      # would make helper methods, modules, and constants that app.rb
+      # defines invisible from views (Context runs its own bindings) or
+      # from before/after/websocket blocks running against a different
+      # object. Loading the file normally puts them at the true,
+      # ordinary Ruby top level, and Jimmu.application (see the DSL
+      # module below) is what makes bare `port 3000`-style calls still
+      # work despite that.
+      Jimmu.application = self
+      load(path)
+    end
+
+    # ================= Server =================
+
+    def start_server
+      begin
+        @server = TCPServer.new(@host, @port)
+      rescue Errno::EADDRINUSE
+        raise ConfigError, "Port #{@port} is already in use. Try `jimmu server -p <port>` with a different port."
+      rescue Errno::EACCES
+        raise ConfigError, "Permission denied binding to #{@host}:#{@port}. Ports below 1024 usually need elevated privileges -- try a port like 3000 or 8080."
+      end
+
+      log("Jimmu #{VERSION} listening on http://#{display_host}:#{@port}  (app: #{@app_root})")
+      log('Press Ctrl+C to stop.')
+
+      # Signal handlers run in a restricted "trap context" where
+      # blocking operations (Mutex#synchronize, which our #log uses)
+      # are not allowed. So the handler itself does nothing but raise
+      # Interrupt back into the accepting thread; all real cleanup
+      # (closing databases, logging, closing the socket) happens down
+      # in the rescue/ensure below, in ordinary thread context.
+      trap('INT') { raise Interrupt }
+      trap('TERM') { raise Interrupt }
+
+      begin
+        loop do
+          client =
+            begin
+              @server.accept
+            rescue IOError, Errno::EBADF
+              break
+            end
+          Thread.new(client) { |socket| handle_connection(socket) }
+        end
+      rescue Interrupt
+        nil
+      ensure
+        log('Shutting down...')
+        @databases.each { |d| d.close rescue nil }
+        begin
+          @server.close
+        rescue IOError
+          nil
+        end
+      end
+    end
+
+    def display_host
+      @host == '0.0.0.0' ? 'localhost' : @host
+    end
+
+    # ================= Per-connection handling =================
+
+    def handle_connection(socket)
+      socket.setsockopt(Socket::IPPROTO_TCP, Socket::TCP_NODELAY, 1) rescue nil
+      socket.set_encoding(Encoding::BINARY)
+
+      request = parse_request(socket)
+      return if request.nil?
+
+      if websocket_upgrade_request?(request)
+        route = find_websocket_route(request.path)
+        if route
+          handle_websocket_upgrade(socket, request, route)
+          return
+        end
+      end
+
+      handle_http_request(socket, request)
+    rescue Exception => e
+      log("connection error: #{e.class}: #{e.message}", :error)
+    ensure
+      begin
+        socket.close unless socket.closed?
+      rescue IOError
+        nil
+      end
+    end
+
+    def parse_request(socket)
+      request_line = read_line(socket)
+      return nil if request_line.nil? || request_line.empty?
+
+      parts = request_line.split(' ')
+      return nil if parts.length < 2
+      http_method, target = parts[0], parts[1]
+
+      raw_path, _, query = target.partition('?')
+      path = Jimmu.percent_decode(raw_path).dup.force_encoding(Encoding::UTF_8)
+      path = path.valid_encoding? ? path : path.scrub
+      path = '/' if path.empty?
+
+      headers = {}
+      loop do
+        line = read_line(socket)
+        break if line.nil? || line.empty?
+        k, v = line.split(':', 2)
+        next unless k && v
+        headers[k.strip.downcase] = v.strip
+      end
+
+      body = ''.b
+      content_length = headers['content-length'].to_i
+      if content_length.positive?
+        return nil if content_length > MAX_BODY_SIZE
+        remaining = content_length
+        chunks = []
+        while remaining.positive?
+          chunk = socket.read([remaining, 65536].min)
+          break if chunk.nil?
+          chunks << chunk
+          remaining -= chunk.bytesize
+        end
+        body = chunks.join.b
+      end
+
+      peer_ip =
+        begin
+          socket.peeraddr(false)[3]
+        rescue IOError, Errno::ENOTCONN, SocketError
+          'unknown'
+        end
+
+      Request.new(
+        http_method: http_method.to_s.upcase,
+        path: path,
+        query_string: query.to_s,
+        headers: headers,
+        body: body,
+        ip: peer_ip
+      )
+    rescue IOError, Errno::ECONNRESET, Errno::ETIMEDOUT
+      nil
+    end
+
+    def read_line(socket)
+      line = socket.gets("\n")
+      return nil if line.nil?
+      line.sub(/\r?\n\z/, '')
+    rescue IOError, Errno::ECONNRESET
+      nil
+    end
+
+    def websocket_upgrade_request?(request)
+      upgrade = request.header('upgrade').to_s.downcase
+      connection = request.header('connection').to_s.downcase
+      upgrade == 'websocket' && connection.include?('upgrade')
+    end
+
+    def find_websocket_route(path)
+      @websocket_routes.each do |pattern, block|
+        params = Router.match_pattern(pattern, path)
+        return [block, params] if params
+      end
+      nil
+    end
+
+    def handle_websocket_upgrade(socket, request, route)
+      block, route_params = route
+      key = request.header('sec-websocket-key')
+      unless key
+        write_simple_response(socket, 400, 'Bad Request', 'Missing Sec-WebSocket-Key header.')
+        return
+      end
+
+      cookie_jar = CookieJar.new(request.header('cookie'))
+      session_id, session_hash, = @session_store.fetch_or_create(cookie_jar[SessionStore::COOKIE_NAME])
+      cookie_jar.set(SessionStore::COOKIE_NAME, session_id, http_only: true, max_age: SessionStore::DEFAULT_MAX_AGE)
+      request.route_params = route_params
+
+      accept = WebSocketProtocol.accept_key(key)
+      out = +''.b
+      out << "HTTP/1.1 101 Switching Protocols\r\n"
+      out << "Upgrade: websocket\r\n"
+      out << "Connection: Upgrade\r\n"
+      out << "Sec-WebSocket-Accept: #{accept}\r\n"
+      cookie_jar.response_header_values.each { |v| out << "Set-Cookie: #{v}\r\n" }
+      out << "\r\n"
+      socket.write(out)
+
+      ws = WebSocketConnection.new(self, socket, request, route_params, cookie_jar, session_hash)
+      log("WS   #{request.path} connected [#{request.ip}]")
+
+      begin
+        ws.instance_exec(&block)
+      rescue Exception => e
+        log("websocket setup error on #{request.path}: #{e.class}: #{e.message}", :error)
+        (e.backtrace || []).first(10).each { |l| log("    #{l}", :error) }
+        ws.close rescue nil
+        return
+      end
+
+      ws.run_loop
+      log("WS   #{request.path} disconnected [#{request.ip}]")
+    end
+
+    def handle_http_request(socket, request)
+      start_time = Time.now
+      cookie_jar = CookieJar.new(request.header('cookie'))
+      session_id, session_hash, = @session_store.fetch_or_create(cookie_jar[SessionStore::COOKIE_NAME])
+      ctx = Context.new(self, request, cookie_jar, session_id, session_hash, false)
+
+      begin
+        catch(HALT) do
+          run_before_hooks(ctx)
+          dispatch(ctx, request)
+        end
+        run_after_hooks(ctx)
+      rescue Exception => e
+        log("#{request.http_method} #{request.path} -> 500 #{e.class}: #{e.message}", :error)
+        (e.backtrace || []).each { |line| log("    #{line}", :error) }
+        ctx.error = e
+        ctx.response_body = ctx.render_error_page(500)
+        ctx.response_headers['Content-Type'] ||= 'text/html; charset=utf-8'
+        begin
+          run_after_hooks(ctx)
+        rescue Exception => e2
+          log("error in after-hook while handling 500: #{e2.class}: #{e2.message}", :error)
+        end
+      end
+
+      cookie_jar.set(SessionStore::COOKIE_NAME, session_id, http_only: true, max_age: SessionStore::DEFAULT_MAX_AGE)
+      send_response(socket, ctx, request)
+
+      duration_ms = ((Time.now - start_time) * 1000).round(1)
+      log("#{request.http_method} #{request.path} -> #{ctx.status_code} (#{ctx.response_body.to_s.bytesize}B, #{duration_ms}ms) [#{request.ip}]")
+    end
+
+    def run_before_hooks(ctx)
+      @before_hooks.each { |hook| ctx.instance_exec(&hook) }
+    end
+
+    def run_after_hooks(ctx)
+      @after_hooks.each { |hook| ctx.instance_exec(&hook) }
+    end
+
+    def dispatch(ctx, request)
+      if %w[GET HEAD].include?(request.http_method)
+        static_path = Router.resolve_static(@public_dir, request.path)
+        if static_path
+          ctx.serve_static_file(static_path)
+          return
+        end
+      end
+
+      if find_websocket_route(request.path)
+        ctx.status(426)
+        ctx.text('Upgrade Required: this endpoint only accepts WebSocket connections.')
+        return
+      end
+
+      match = Router.resolve_view(@views_dir, request.path)
+      if match
+        file_path, route_params = match
+        request.route_params = route_params
+        ctx.response_body = ctx.render_file(file_path)
+        ctx.response_headers['Content-Type'] ||= 'text/html; charset=utf-8'
+      else
+        ctx.response_body = ctx.render_error_page(404)
+        ctx.response_headers['Content-Type'] ||= 'text/html; charset=utf-8'
+      end
+    end
+
+    def send_response(socket, ctx, request)
+      body_bytes = ctx.response_body.to_s.dup.force_encoding(Encoding::BINARY)
+
+      headers = ctx.response_headers.dup
+      headers['Content-Type'] ||= 'text/html; charset=utf-8'
+      headers['Content-Length'] = body_bytes.bytesize.to_s
+      headers['Connection'] = 'close'
+      headers['Server'] = "Jimmu/#{VERSION}"
+
+      out = +''.b
+      out << "HTTP/1.1 #{ctx.status_code} #{Jimmu.status_phrase(ctx.status_code)}\r\n"
+      headers.each { |k, v| out << "#{k}: #{v}\r\n" }
+      ctx.cookie.response_header_values.each { |v| out << "Set-Cookie: #{v}\r\n" }
+      out << "\r\n"
+      out << body_bytes unless request.http_method == 'HEAD'
+
+      socket.write(out)
+    rescue IOError, Errno::EPIPE, Errno::ECONNRESET
+      nil
+    end
+
+    def write_simple_response(socket, code, title, message)
+      body = message.to_s.b
+      out = +''.b
+      out << "HTTP/1.1 #{code} #{title}\r\n"
+      out << "Content-Type: text/plain; charset=utf-8\r\n"
+      out << "Content-Length: #{body.bytesize}\r\n"
+      out << "Connection: close\r\n\r\n"
+      out << body
+      socket.write(out)
+    rescue IOError
+      nil
+    end
+  end
+
+  # Mixed into Object (below) so that app.rb -- an ordinary, normally
+  # `load`ed Ruby file, not an instance_eval'd string -- can still use
+  # top-level DSL calls like `port 3000` or `before do ... end`. Each
+  # method simply forwards to whatever Application instance is
+  # currently active (Jimmu.application), which the CLI sets just
+  # before loading app.rb.
+  module DSL
+    def port(value = nil)
+      Jimmu.application.port(value)
+    end
+
+    def host(value = nil)
+      Jimmu.application.host(value)
+    end
+
+    def sqlite(path)
+      Jimmu.application.sqlite(path)
+    end
+
+    def before(&block)
+      Jimmu.application.before(&block)
+    end
+
+    def after(&block)
+      Jimmu.application.after(&block)
+    end
+
+    def websocket(path, &block)
+      Jimmu.application.websocket(path, &block)
+    end
+
+    def run
+      Jimmu.application.run
+    end
+
+    def log(message, level = :info)
+      Jimmu.application.log(message, level)
+    end
+  end
+end
+
+# Extend only the single top-level "main" object (not Object globally)
+# with the DSL, so app.rb's bare `port 3000` / `before do ... end`
+# calls work without making these method names appear on every object
+# in the process.
+TOPLEVEL_BINDING.eval('self').singleton_class.include(Jimmu::DSL)
+module Jimmu
+  module CLI
+    TEMPLATE_APP_RB = <<~'RUBY'
+      # Jimmu application entry point.
+      # Start the development server with:  jimmu server
+
+      port 3000
+      host "127.0.0.1"
+
+      before do
+        log "#{request.method} #{request.path}"
+      end
+
+      run
+    RUBY
+
+    TEMPLATE_LAYOUT_ERB = <<~'ERB'
+      <!DOCTYPE html>
+      <html lang="en">
+      <head>
+      <meta charset="UTF-8">
+      <meta name="viewport" content="width=device-width, initial-scale=1">
+      <title>Jimmu App</title>
+      <link rel="stylesheet" href="/css/style.css">
+      </head>
+      <body>
+      <%= yield %>
+      <script src="/js/app.js"></script>
+      </body>
+      </html>
+    ERB
+
+    TEMPLATE_INDEX_ERB = <<~'ERB'
+      <h1>Welcome to Jimmu</h1>
+      <p>Edit <code>views/index.erb</code> to get started.</p>
+      <p>This page is automatically wrapped by <code>views/layout.erb</code>.</p>
+    ERB
+
+    TEMPLATE_404_ERB = <<~'ERB'
+      <h1>404 - Page Not Found</h1>
+      <p>The page you requested does not exist.</p>
+      <p><a href="/">Go back home</a></p>
+    ERB
+
+    TEMPLATE_500_ERB = <<~'ERB'
+      <h1>500 - Internal Server Error</h1>
+      <p>Something went wrong on our end.</p>
+    ERB
+
+    TEMPLATE_CSS = <<~'CSS'
+      :root { color-scheme: light dark; }
+      * { box-sizing: border-box; }
+      body {
+        margin: 0;
+        font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Helvetica, Arial, sans-serif;
+        line-height: 1.6;
+        max-width: 760px;
+        padding: 48px 24px;
+        margin: 0 auto;
+      }
+      code {
+        background: rgba(127,127,127,0.15);
+        padding: 2px 6px;
+        border-radius: 4px;
+        font-size: 0.9em;
+      }
+      a { color: #3b6fe0; }
+    CSS
+
+    TEMPLATE_JS = <<~'JS'
+      console.log("Jimmu app loaded");
+    JS
+
+    # ================= entry point =================
+
+    def self.start(argv)
+      command = argv[0]
+      case command
+      when 'new'
+        cmd_new(argv[1..-1])
+      when 'server'
+        cmd_server(argv[1..-1])
+      when 'version', '-v', '--version'
+        puts "jimmu #{Jimmu::VERSION}"
+      when 'build'
+        puts 'jimmu build: not implemented yet. Future versions of Jimmu will support'
+        puts 'bundling an app into a single distributable executable/package.'
+      when 'help', '-h', '--help', nil
+        print_help
+      else
+        warn "Unknown command: #{command}\n\n"
+        print_help
+        exit(1)
+      end
+    end
+
+    def self.print_help
+      puts <<~HELP
+        Jimmu #{Jimmu::VERSION} - a lightweight, single-file Ruby web framework
+
+        Usage:
+          jimmu new <name>        Create a new Jimmu project in ./<name>
+          jimmu server [options]  Start the development server (reads ./app.rb)
+          jimmu version           Print the installed Jimmu version
+          jimmu help              Show this help message
+          jimmu build              (reserved for future use)
+
+        Server options:
+          -p, --port PORT   Port to listen on (overrides app.rb's `port`, default 3000)
+          -h, --host HOST   Host/IP to bind to (overrides app.rb's `host`, default 127.0.0.1)
+
+        Examples:
+          jimmu new myapp
+          cd myapp
+          jimmu server
+          jimmu server -p 8080
+          jimmu server -h 0.0.0.0 -p 8080
+      HELP
+    end
+
+    def self.cmd_new(args)
+      name = args[0]
+      if name.nil? || name.strip.empty?
+        warn 'Usage: jimmu new <name>'
+        exit(1)
+      end
+
+      root = File.expand_path(name)
+      if Dir.exist?(root) && !Dir.empty?(root)
+        warn "Error: directory #{name.inspect} already exists and is not empty."
+        exit(1)
+      end
+
+      %w[views public/css public/js public/img db].each do |dir|
+        FileUtils.mkdir_p(File.join(root, dir))
+      end
+
+      write_file(File.join(root, 'app.rb'), TEMPLATE_APP_RB)
+      write_file(File.join(root, 'views/layout.erb'), TEMPLATE_LAYOUT_ERB)
+      write_file(File.join(root, 'views/index.erb'), TEMPLATE_INDEX_ERB)
+      write_file(File.join(root, 'views/404.erb'), TEMPLATE_404_ERB)
+      write_file(File.join(root, 'views/500.erb'), TEMPLATE_500_ERB)
+      write_file(File.join(root, 'public/css/style.css'), TEMPLATE_CSS)
+      write_file(File.join(root, 'public/js/app.js'), TEMPLATE_JS)
+      write_file(File.join(root, 'public/img/.gitkeep'), '')
+      write_file(File.join(root, 'db/.gitkeep'), '')
+
+      puts "Created new Jimmu app in ./#{name}"
+      puts ''
+      puts '  cd ' + name
+      puts '  jimmu server'
+      puts ''
+    end
+
+    def self.write_file(path, content)
+      File.write(path, content, encoding: Encoding::UTF_8)
+    end
+
+    def self.cmd_server(args)
+      forced_port = nil
+      forced_host = nil
+
+      parser = OptionParser.new do |opts|
+        opts.banner = 'Usage: jimmu server [options]'
+        opts.on('-p PORT', '--port PORT', 'Port to listen on') { |v| forced_port = v }
+        opts.on('-h HOST', '--host HOST', 'Host/IP to bind to') { |v| forced_host = v }
+      end
+
+      begin
+        parser.parse!(args)
+      rescue OptionParser::ParseError => e
+        warn "Error: #{e.message}"
+        exit(1)
+      end
+
+      app_rb_path = File.expand_path('app.rb', Dir.pwd)
+      unless File.file?(app_rb_path)
+        warn "Error: no app.rb found in the current directory (#{Dir.pwd})."
+        warn 'Run `jimmu new <name>` to create a new project, or `cd` into an existing one.'
+        exit(1)
+      end
+
+      app = Jimmu::Application.new(Dir.pwd)
+      app.force_port!(forced_port) if forced_port
+      app.force_host!(forced_host) if forced_host
+
+      begin
+        app.load_app_file(app_rb_path)
+        unless app.run_called?
+          app.log('app.rb did not call `run` -- starting the server automatically.')
+          app.run
+        end
+      rescue Jimmu::ConfigError => e
+        warn "Error: #{e.message}"
+        exit(1)
+      rescue Jimmu::DatabaseError => e
+        warn "Database error: #{e.message}"
+        exit(1)
+      rescue Interrupt
+        puts "\nShutting down..."
+        exit(0)
+      rescue Exception => e
+        warn "Error loading app.rb: #{e.class}: #{e.message}"
+        (e.backtrace || []).first(15).each { |l| warn "    #{l}" }
+        exit(1)
+      end
+    end
+  end
+end