fresco 0.0.1

data/lib/fresco/runtime/runtime.rb

@@ -0,0 +1,1810 @@
+# Fresco: runtime shim. Auto-generated by `fresco build`; do not edit.
+#
+# Source of truth: lib/fresco/runtime/runtime.rb in the fresco gem —
+# `fresco build` copies this file verbatim into generated/runtime.rb.
+# The FFI module's `ffi_cflags "generated/runtime/http.c"` injects the
+# shim into the cc invocation Spinel issues. `fresco build` copies the
+# C source into generated/runtime/ before Spinel runs, so the relative
+# path resolves from the user app's cwd. CRuby ignores ffi_*
+# declarations because they're rewritten by Spinel's codegen, not
+# invoked at runtime.
+
+module Sock
+  ffi_cflags "generated/runtime/http.c"
+
+  ffi_func :sphttp_listen,       [:int, :int],       :int
+  ffi_func :sphttp_accept,       [:int],             :int
+  ffi_func :sphttp_read_request, [:int],             :int
+  ffi_func :sphttp_request_buf,  [],                 :str
+  ffi_func :sphttp_request_len,  [],                 :int
+  ffi_func :sphttp_header_end,   [],                 :int
+  ffi_func :sphttp_drain_body,   [:int, :int, :int], :int
+  ffi_func :sphttp_copy_body,    [:int, :int, :int], :int
+  ffi_func :sphttp_body_buf,     [],                 :str
+  ffi_func :sphttp_write_str,    [:int, :str],       :int
+  ffi_func :sphttp_sendfile,     [:int, :str],       :int
+  ffi_func :sphttp_file_size,    [:str],             :int
+  ffi_func :sphttp_close,        [:int],             :int
+  ffi_func :sphttp_fork,            [],                 :int
+  ffi_func :sphttp_wait_any,        [],                 :int
+  ffi_func :sphttp_getpid,          [],                 :int
+  ffi_func :sphttp_mark_now,        [],                 :int
+  ffi_func :sphttp_elapsed_micros,  [],                 :int
+
+  # HMAC-SHA256 over (key, msg). `_hex` returns 64-char hex (cookie
+  # session signature); `_b64url` returns 43-char RFC 4648 §5 (for
+  # future JWT). Both buffers are static — copy the result before the
+  # next call if you need to keep it. Inputs are NUL-terminated, which
+  # is fine for cookie secrets / URL-encoded payloads (NUL-free).
+  ffi_func :sphttp_hmac_sha256_hex,    [:str, :str], :str
+  ffi_func :sphttp_hmac_sha256_b64url, [:str, :str], :str
+end
+
+# The database wrapper (Sqlite/Postgres FFI module + Fresco::Db::*
+# Ruby surface) lives in a per-adapter file at lib/templates/db_*.rb.
+# bin/build picks one based on config/database.rb and copies it to
+# generated/db_adapter.rb. Boot order is fixed (see boot.rb):
+# runtime → views → layout_dispatch → db_adapter → config/app →
+# config/database → requires → dispatch. Keeping the adapter out of
+# this file means a Postgres-only build doesn't drag in the libsqlite3
+# FFI declarations and vice versa.
+
+# Marker base class for actions. The dispatcher calls
+# `SomeAction.new.handle(req)`; handle stashes @req on the instance
+# (so render can read flash) and delegates to the user-defined #call.
+# Concrete actions inherit from `Fresco::Action` (or app-level
+# `App::Action`) to share helpers — render, redirect_to, etc.
+module Fresco
+  # Per-process session secret. Set this in config/app.rb (typically
+  # `Fresco.session_secret = ENV.fetch("SESSION_SECRET")`); empty
+  # disables session signing entirely (req.session still accepts writes
+  # but no Set-Cookie is emitted and no inbound cookie is trusted).
+  # Module-level rather than per-App instance so request handlers can
+  # reach it without threading the App through the call stack.
+  @session_secret = ""
+
+  def self.session_secret
+    @session_secret
+  end
+
+  def self.session_secret=(s = "")
+    @session_secret = s
+  end
+
+  # Non-`=` setter, used by config/app.rb. Spinel's codegen for
+  # top-level `Fresco.session_secret = local` rewrites the call into
+  # a direct `cst_Fresco_session_secret = sp_box_str(local)` ivar
+  # write, but the ivar slot is declared `const char *` — the
+  # `sp_box_str` wrap produces a C type mismatch. Routing through a
+  # plain method bypasses the rewrite and goes through the
+  # function-call path (which handles the const-char-* assignment
+  # correctly, as in `def self.session_secret=`).
+  def self.set_session_secret(s = "")
+    @session_secret = s
+  end
+
+  # Database configuration slots. Populated by config/database.rb's
+  # `Fresco.database :sqlite, ...` (or :postgres) call. Mirrored
+  # verbatim from lib/fresco.rb so build-time and runtime see the
+  # same DSL.
+  #
+  # Three separate scalars instead of one Sym→Mixed hash:
+  #   - hash-shaped config widens to RbVal under Spinel (the
+  #     `[[spinel_poly_hash_each]]` / `[[spinel_poly_hash_aset]]`
+  #     trap), and a `:url` lookup returning RbVal can't be passed
+  #     to fresco_pg_open(const char *).
+  #   - module-level `@database_config = nil` emits as `sp_box_nil()`
+  #     in the generated C, which isn't a compile-time constant —
+  #     Spinel rejects it as a static initializer.
+  # Both go away with typed scalars: `:none` Symbol + two empty
+  # Strings. Each accessor pins to its own monomorphic type.
+  @database_adapter = :none
+  @database_path    = ""
+  @database_url     = ""
+
+  def self.database_adapter
+    @database_adapter
+  end
+
+  def self.database_path
+    @database_path
+  end
+
+  def self.database_url
+    @database_url
+  end
+
+  def self.database(adapter, path: "", url: "")
+    @database_adapter = adapter
+    @database_path    = path
+    @database_url     = url
+  end
+
+  # SQL roll-up counters for the [request] log line. Lives on
+  # `Fresco` (not `Fresco::Db`) so log_request_full — a top-level
+  # free function in this file — can read the totals with Spinel
+  # type resolution intact. Cross-file `Fresco::Db.<getter>` calls
+  # from a free function collapse the receiver to `int` and emit 0
+  # for any value-returning call (cross-file *side-effect* calls
+  # like begin_request!/flush_log! still resolve fine, since their
+  # return value is discarded). Same-file `Fresco.<getter>` is what
+  # `session_secret` / `database_adapter` already lean on, so
+  # mirroring that shape gets us reliable typing here too.
+  #
+  # The adapter (db_sqlite.rb / db_postgres.rb) calls
+  # `Fresco.add_sql_micros!(dt)` from its flush_pending! and exec
+  # paths; `Fresco.reset_db_sql_stats!` runs once per request from
+  # `Fresco::Db.begin_request!`. Both are side-effect-only — the
+  # cross-file write through these works under Spinel.
+  @db_sql_total_micros = 0
+  @db_sql_count        = 0
+
+  def self.db_sql_total_micros
+    @db_sql_total_micros
+  end
+
+  def self.db_sql_query_count
+    @db_sql_count
+  end
+
+  def self.reset_db_sql_stats!
+    @db_sql_total_micros = 0
+    @db_sql_count        = 0
+  end
+
+  def self.add_sql_micros!(us = 0)
+    @db_sql_total_micros += us
+    @db_sql_count        += 1
+  end
+end
+
+# Spinel #532: `String#index` / `#rindex` now return boxed poly (nil
+# for not-found, boxed int when found) instead of `mrb_int` with a
+# `-1` sentinel. These wrappers restore the old contract so call
+# sites can keep using `pos < 0` as the not-found test and pass `pos`
+# to int-expecting slices (`s[pos, n]`, `s[pos...n]`) without each
+# site having to unbox by hand. The `s = ""` / `needle = ""` / `start
+# = 0` defaults pin parameter types — required positional args with
+# no type signal collapse to `mrb_int` in Spinel's analyzer.
+def str_idx(s = "", needle = "")
+  p = s.index(needle)
+  p.nil? ? -1 : p.to_i
+end
+
+def str_idx_from(s = "", needle = "", start = 0)
+  p = s.index(needle, start)
+  p.nil? ? -1 : p.to_i
+end
+
+def str_ridx(s = "", needle = "")
+  p = s.rindex(needle)
+  p.nil? ? -1 : p.to_i
+end
+
+# Name of the cookie carrying the signed session payload. Hardcoded
+# rather than configurable — apps that need multiple session stores
+# can reach for `res.set_cookie` directly with their own names.
+SESSION_COOKIE_NAME = "_session"
+
+# Signed session cookie store. Wire format: `urlencoded_payload.hexhmac`.
+# The payload is *visible* to the client (not encrypted) but the HMAC
+# binds it to the server's secret — modifying the payload requires
+# forging a 32-byte SHA-256 HMAC, which is infeasible without the key.
+#
+# Spinel-shape constraints:
+#   - Custom `[]` / `[]=` on a user class collapses callers to mrb_int
+#     params and mismatches the underlying String/String slots. So we
+#     expose only named methods (`get`, `set`, `has?`); use those rather
+#     than `session[k]`.
+#   - `@data` is pinned to StrStrHash via the seed-and-clear trick used
+#     elsewhere in this file. `clear` reseeds the same way.
+class Session
+  attr_reader :data, :dirty
+
+  def initialize
+    @data = { "__t" => "" }
+    @data.delete("__t")
+    @dirty = false
+  end
+
+  # `|| ""` keeps the missing-key semantics consistent under CRuby
+  # (where Hash#[] returns nil) and Spinel (where the StrStrHash
+  # returns "" already — the coalesce is a no-op there). Callers can
+  # then write `req.session.get("x").length > 0` portably.
+  def get(k = "");    @data[k] || ""; end
+  def set(k = "", v = ""); @data[k] = v; @dirty = true; end
+  def has?(k = "");   @data.key?(k);            end
+  def length; @data.length; end
+
+  def clear
+    @data = { "__t" => "" }
+    @data.delete("__t")
+    @dirty = true
+  end
+
+  # Verify + decode an inbound cookie value. Returns true on success
+  # (data populated), false on missing / malformed / tampered. We don't
+  # raise so a forged cookie just looks like "no session" to the app.
+  def load_from(cookie_value, secret)
+    return false if cookie_value.length == 0 || secret.length == 0
+    dot = Session.last_dot(cookie_value)
+    return false if dot < 0
+    payload = cookie_value[0, dot]
+    sig     = cookie_value[dot + 1, cookie_value.length - dot - 1]
+    expect  = Sock.sphttp_hmac_sha256_hex(secret, payload)
+    return false unless Session.timing_safe_eq(sig, expect)
+    parse_payload!(payload)
+    true
+  end
+
+  # Sign + serialise the current data into a cookie value. Caller
+  # decides when (typically only when @dirty).
+  def to_cookie_value(secret)
+    payload = ""
+    first   = true
+    @data.each do |k, v|
+      payload += "&" unless first
+      payload += url_encode(k) + "=" + url_encode(v)
+      first = false
+    end
+    payload + "." + Sock.sphttp_hmac_sha256_hex(secret, payload)
+  end
+
+  # Walk a `k=v&k=v` payload into @data. Sibling of parse_query_string!
+  # but writes Str keys directly (no url_decode().to_sym), so it's
+  # private to Session.
+  def parse_payload!(payload)
+    pairs = payload.split("&")
+    i = 0
+    while i < pairs.length
+      pair = pairs[i]
+      if pair.length > 0
+        eq = str_idx(pair, "=")
+        if eq < 0
+          @data[url_decode(pair)] = ""
+        else
+          k = url_decode(pair[0, eq])
+          v = url_decode(pair[eq + 1, pair.length - eq - 1])
+          @data[k] = v
+        end
+      end
+      i += 1
+    end
+  end
+
+  # Last `.` position in s, or -1 if none. Spinel doesn't have a
+  # stdlib rindex equivalent we can rely on; the explicit walk lowers
+  # cleanly.
+  def self.last_dot(s)
+    i = s.length - 1
+    while i >= 0
+      return i if s[i] == "."
+      i -= 1
+    end
+    -1
+  end
+
+  # Constant-time string equality. Avoids leaking the matching prefix
+  # length via early-exit timing. Spinel doesn't have a stdlib crypto-
+  # safe compare, so we walk byte by byte.
+  def self.timing_safe_eq(a, b)
+    return false if a.length != b.length
+    diff = 0
+    i = 0
+    while i < a.length
+      diff = diff | (a[i].bytes[0] ^ b[i].bytes[0])
+      i += 1
+    end
+    diff == 0
+  end
+
+  # Force the dirty flag from outside the class (used by flash
+  # promotion, which mutates @data directly via the reader to clear
+  # consumed entries).
+  def mark_dirty
+    @dirty = true
+  end
+end
+
+# Key prefix marking flash entries inside the session payload. Apps
+# never write this prefix directly; req.flash.set / req.flash.get do
+# the bookkeeping.
+FLASH_KEY_PREFIX = "_flash."
+
+# One-shot key/value bag that survives exactly one request bounce.
+# Read side (`read_data`) carries messages set on the *previous*
+# request; write side (`write_data`) collects messages that should
+# survive into the *next* one. Backed by the signed session cookie —
+# flash is a thin wrapper on top of Session, not its own cookie.
+#
+# Lifecycle (per request):
+#   1. maybe_load_session! pulls `_flash.<key>` entries out of the
+#      newly-loaded session into req.flash.read_data, removes them
+#      from the session, and marks the session dirty (so the cleared
+#      state ships back).
+#   2. Handler reads via req.flash.get(k); writes via req.flash.set(k, v).
+#   3. attach_session_cookie! bakes write_data back into the session
+#      as `_flash.<key>` entries, then session signing proceeds as
+#      usual.
+class Flash
+  attr_reader :read_data, :write_data
+
+  def initialize
+    @read_data = { "__t" => "" }
+    @read_data.delete("__t")
+    @write_data = { "__t" => "" }
+    @write_data.delete("__t")
+  end
+
+  def get(k = "");    @read_data[k] || ""; end # see Session#get re `|| ""`
+  def has?(k = "");   @read_data.key?(k);   end
+  def set(k = "", v = ""); @write_data[k] = v; end
+  def length; @read_data.length; end
+end
+
+class Fresco::Action
+  attr_reader :req
+
+  # Per-instance filter state. @halt_response is left unset until
+  # halt! installs a real Response — #handle only reads it inside
+  # `if @halted` branches, so the uninitialised state is never
+  # observed.
+  def initialize
+    @halted = false
+  end
+
+  # Declare a layout by overriding `#layout` to return the symbol name
+  # of a layout under app/views/layouts/. Subclasses inherit via normal
+  # method lookup.
+  def layout
+    :none
+  end
+
+  # Dispatcher entry point. Stashes `@req` on the instance so #render
+  # can reach the current request's flash, then runs the before/after
+  # filter sandwich around the user-defined #call.
+  #
+  # Filter contract:
+  #   1. #before_action runs first. It can halt!(resp) to skip #call.
+  #   2. #call runs only if no halt was requested.
+  #   3. #after_action runs after #call. It can also halt! to replace
+  #      the response.
+  #
+  # "Around" filters: override #handle in a subclass and call super.
+  # (See app/actions/filters/show.rb for the Spinel-shape workaround
+  # the super-assignment requires.)
+  #
+  # Rails-style multi-callback chains (`before_action :auth, :rate_limit`)
+  # aren't viable under Spinel — they need `send(name)` for dynamic
+  # dispatch, which the analyzer rejects. Call helper methods explicitly
+  # from inside #before_action instead.
+  def handle(req)
+    @req = req
+    before_action(req)
+    return @halt_response if @halted
+    res = call(req)
+    after_action(req, res)
+    return @halt_response if @halted
+    res
+  end
+
+  # Filter hooks. Default no-op bodies; subclasses opt in by overriding.
+  def before_action(req)
+  end
+
+  def after_action(req, res)
+  end
+
+  # Default #call — the polymorphic-dispatch anchor for Spinel's bare
+  # `call(req)` inside #handle. Without this base definition the
+  # analyzer can't resolve the call and emits 0 (mrb_int), which
+  # cascades into handle returning mrb_int and breaks every
+  # dispatcher call site.
+  #
+  # Subclasses ALWAYS override. The body's 500 also doubles as a
+  # safety net for actions that genuinely forgot to implement #call.
+  #
+  # Spinel quirk worth knowing: this method dispatches polymorphically
+  # to subclass #call methods ONLY when their `req` param has a
+  # matching type. Subclass methods whose body doesn't reference `req`
+  # need an explicit typed default — `def call(req = Request.new("", "", ""))`
+  # — or Spinel collapses the param to mrb_int, the signature
+  # mismatches this base's `sp_Request *`, and the case-on-cls_id
+  # dispatch falls back to this base (which always returns 500).
+  def call(req)
+    Response.text(500, "Action is missing a #call implementation.\n")
+  end
+
+  # Short-circuit the filter chain. Sets the response that #handle
+  # will return in place of the normal #call result.
+  def halt!(response)
+    @halted        = true
+    @halt_response = response
+  end
+
+  def render(body, status: 200)
+    Response.html(status, dispatch_layout(layout, body, @req.flash))
+  end
+
+  def redirect_to(location = "", status: 302)
+    Response.redirect(location, status: status)
+  end
+end
+
+# Boot class for the user's application. Generated apps subclass this
+# in config/app.rb (e.g. `class App::Base < Fresco::App`) and call
+# `App::Base.new.run` from app.rb. Subclasses can override defaults by
+# reassigning @port / @workers in their own initialize.
+#
+# `run` dispatches between two modes:
+#   serve [-p PORT] [-w N]   → HTTP listener (run_server)
+#   METHOD PATH [BODY]       → one-shot CLI dispatch (kept for smoke tests)
+#
+# ARGV is referenced directly rather than passed through as a method
+# parameter — Spinel infers `ARGV` as its dedicated `sp_Argv` type
+# only at global-read sites; routing it through a Ruby parameter
+# collapses the type to `mrb_int` and the indexing/length lowering
+# fails. Keep all ARGV access inside these methods.
+class Fresco::App
+  attr_accessor :port, :workers
+
+  def initialize
+    @port    = 3000
+    @workers = 1
+  end
+
+  # Class-level convenience so app.rb is `App::Base.run` rather than
+  # `App::Base.new.run`. The instance carries config state; the class
+  # method exists purely to spare the caller the `.new`.
+  def self.run
+    new.run
+  end
+
+  def run
+    # Eager-open the DB connection at startup so a misconfigured DSN
+    # fails fast on the binary's first command rather than the first
+    # request. Spinel-shape note: Fresco::Db.boot! is defined by the
+    # generated db_adapter.rb when an adapter is configured; the
+    # `respond_to?` guard keeps no-DB apps working.
+    Fresco::Db.boot! if Fresco::Db.respond_to?(:boot!)
+
+    if ARGV[0] == "serve"
+      parse_serve_args
+      run_server(port: @port, workers: @workers)
+    elsif ARGV[0] == "db:migrate"
+      Fresco::DbMigrations.migrate!
+    elsif ARGV[0] == "db:rollback"
+      Fresco::DbMigrations.rollback!
+    else
+      run_cli
+    end
+  end
+
+  def parse_serve_args
+    i = 1
+    while i < ARGV.length
+      a = ARGV[i]
+      if a == "-p"
+        @port = ARGV[i + 1].to_i
+        i += 2
+      elsif a == "-w"
+        @workers = ARGV[i + 1].to_i
+        i += 2
+      else
+        i += 1
+      end
+    end
+  end
+
+  def run_cli
+    method = ARGV[0]
+    path   = ARGV[1]
+    body   = ARGV[2] || ""
+
+    req = Request.new(method, path, body)
+    res = dispatch_request(method, path, req)
+
+    puts res.status
+    puts
+    print res.body
+  end
+end
+
+# Params wraps a single Symbol→String hash that the parsers and
+# dispatcher all write into. Folding (path > form > query) happens at
+# write time — the dispatcher writes path captures after the parsers
+# have already folded form and query, so path wins by virtue of write
+# order. Writes use #set_sym instead of []= because Spinel widens
+# user-defined []= keys to sp_RbVal on the HTTP dispatch path. Typed
+# accessors (#int / #float / #bool / #str) coerce on read with a
+# positional scalar default (kwargs-with-defaults collapse to mrb_int
+# under Spinel — see [[spinel_initialize_kwargs]]).
+class Params
+  def initialize(raw)
+    @raw = raw
+  end
+
+  def [](key = :__t)
+    @raw[key]
+  end
+
+  # Defaults are type hints for Spinel. Without them, user-defined
+  # setters can widen the key to sp_RbVal even when every call passes a
+  # symbol, and codegen then emits a bad SymStrHash_set call.
+  def set_sym(key = :__t, value = "")
+    @raw[key] = value
+  end
+
+  def has?(key = :__t)
+    @raw.key?(key)
+  end
+
+  def length
+    @raw.length
+  end
+
+  # Underlying hash for monomorphic callers (logger, parsers). Returning
+  # the real reference is the point — the parsers mutate it in place.
+  # Callers that want to iterate go through `.raw.each` — proxying
+  # `each(&blk)` here doesn't lower under Spinel (the block param's
+  # type collapses and codegen emits an undefined block variable).
+  def raw
+    @raw
+  end
+
+  def str(key = :__t, default = "")
+    v = @raw[key]
+    return default if v.nil?
+    return default if v.length == 0
+    v
+  end
+
+  def int(key = :__t, default = 0)
+    v = @raw[key]
+    return default if v.nil?
+    return default if v.length == 0
+    v.to_i
+  end
+
+  def float(key = :__t, default = 0.0)
+    v = @raw[key]
+    return default if v.nil?
+    return default if v.length == 0
+    v.to_f
+  end
+
+  def bool(key = :__t, default = false)
+    v = @raw[key]
+    return default if v.nil?
+    return true  if v == "true"
+    return true  if v == "1"
+    return true  if v == "on"
+    false
+  end
+end
+
+class Request
+  attr_accessor :verb, :path, :body, :params, :query, :headers, :version, :cookies, :session, :flash, :parse_status
+
+  # The HTTP verb is exposed as `req.verb` (not `req.method`). Spinel
+  # mis-types any accessor named `method`: it conflates the reader
+  # with Ruby's `Object#method(:sym)` reflection and boxes the
+  # const-char* return as sp_Method (cls_id 45), which then breaks
+  # dispatch when handle_connection calls dispatch_request with the
+  # boxed value. Renaming sidesteps the analyzer collision.
+
+  def initialize(method, path, body)
+    @verb    = method
+    @path    = path
+    @body    = body
+    @version = "HTTP/1.0" # parser overwrites; CLI mode keeps the default
+    # 0 = parsed OK; 400 = malformed request; 413 = body too large.
+    # parse_http_request always returns a Request (no Request|nil
+    # union) so Spinel keeps `parsed` pinned to sp_Request * through
+    # the dispatch chain — otherwise every #handle / #call along the
+    # way widens to sp_RbVal req and the polymorphic call to each
+    # subclass's #call falls back to the base 500 fallback.
+    @parse_status = 0
+    # Seed-and-clear pins ivar hashes to their concrete specialisation;
+    # see plan's Spinel quirks. The Params wrapper keeps Request's
+    # public surface stable while letting actions reach typed coercion
+    # via `req.params.int(:id)` etc.
+    raw = { __t: "" }
+    raw.delete(:__t)
+    @params  = Params.new(raw)
+    @query   = { __t: "" }
+    @query.delete(:__t)
+    @headers = { "__t" => "" }
+    @headers.delete("__t")
+    # Cookies are Str→Str (raw Cookie header pairs after url_decode).
+    # Same StrStrHash pinning as @headers.
+    @cookies = { "__t" => "" }
+    @cookies.delete("__t")
+    # Session is allocated fresh per request. Stays empty unless
+    # parse_http_request / parse_dev_request finds a valid signed
+    # cookie and load_from succeeds.
+    @session = Session.new
+    # Flash is the one-shot companion to session. promote_flash!
+    # populates read_data after session load; consume_flash_writes!
+    # bakes write_data back in before the response cookie ships.
+    @flash   = Flash.new
+  end
+
+  # HTTP/1.1 keep-alive defaults to on; explicit `Connection: close`
+  # opts out. HTTP/1.0 defaults to off; `Connection: keep-alive` opts
+  # in. Header lookup is case-insensitive on the wire, but our parser
+  # already lowercased keys.
+  def keep_alive?
+    conn = ""
+    if @headers.key?("connection")
+      conn = @headers["connection"].downcase
+    end
+    if @version == "HTTP/1.1"
+      return conn != "close"
+    end
+    conn == "keep-alive"
+  end
+end
+
+class Response
+  attr_reader :status, :body, :content_type, :file_path, :set_cookies, :location
+
+  # All slots are kwargs with defaults. The defaults are sentinels —
+  # external callers go through the .text / .html / .json / .markdown
+  # / .file / .redirect helpers below. Spinel's type inference for
+  # `initialize` kwargs reads each default to fix the C parameter type;
+  # without a default the slot collapses to mrb_int. `file_path == ""`
+  # means "body response"; non-empty means "sendfile this path on the
+  # wire". `location == ""` means "no redirect"; non-empty emits a
+  # `Location:` header alongside the chosen 3xx status.
+  def initialize(status: 0, body: "", content_type: "text/plain; charset=utf-8", file_path: "", location: "")
+    @status       = status
+    @body         = body
+    @content_type = content_type
+    @file_path    = file_path
+    @location     = location
+    # Set-Cookie can repeat; one fully-formatted line per entry. Seed
+    # and delete to pin Array<String> for Spinel. Writes go through
+    # #set_cookie / #set_cookie_with_opts (named mutators) — the same
+    # poly-receiver-write trap that motivated Response's attr_reader
+    # surface also kills `res.set_cookies << x` from outside.
+    @set_cookies  = [""]
+    @set_cookies.delete_at(0)
+  end
+
+  # Append a Set-Cookie line with no attributes: `name=value` (value
+  # URL-encoded). The handful of apps that want Path/HttpOnly/SameSite
+  # use #set_cookie_with_opts instead.
+  def set_cookie(name, value)
+    @set_cookies.push(name + "=" + url_encode(value))
+  end
+
+  # Append a Set-Cookie line with attributes. `opts` is a Str→Str hash
+  # (`"Path" => "/"`, `"HttpOnly" => ""` for bare flags, etc.). Kept on
+  # a separate method (vs an optional kwarg) so this parameter stays
+  # monomorphic on StrStrHash — see [[spinel_poly_hash_each]]; an
+  # opts-default of `{}` would collapse to RbVal and the iteration
+  # would silently no-op.
+  def set_cookie_with_opts(name, value, opts)
+    line = name + "=" + url_encode(value)
+    opts.each do |k, v|
+      if v.length == 0
+        line += "; " + k # bare flag (HttpOnly, Secure)
+      else
+        line += "; " + k + "=" + v
+      end
+    end
+    @set_cookies.push(line)
+  end
+
+  # Every helper passes `location: ""` explicitly even though it's the
+  # initialize default. Spinel lowers an omitted kwarg as a literal 0
+  # (NULL pointer) into the C callee, NOT the Ruby-side default — so
+  # `Response.text` without `location:` would store NULL on @location
+  # and `build_headers` later strlen()s it → segfault. Same trap for
+  # any other helper that builds a Response from `new(...)` without
+  # supplying every kwarg.
+  def self.text(status, body)
+    new(status: status, body: body, content_type: "text/plain; charset=utf-8", file_path: "", location: "")
+  end
+
+  def self.html(status, body)
+    new(status: status, body: body, content_type: "text/html; charset=utf-8", file_path: "", location: "")
+  end
+
+  # `body` is a `Hash<Symbol, *>` — the typical JSON-response shape.
+  # We call `Spinel::Json.encode_hash` directly (not `encode`) so the
+  # hash type stays pinned at the call boundary. Going through
+  # `encode(body)` boxes the hash as `sp_RbVal`, and the analyzer's
+  # polymorphic `.each` lowering only walks array-tag classes — a
+  # Hash payload silently iterates zero entries (yielding `"{}"`).
+  def self.json(status, body)
+    new(status: status, body: Spinel::Json.encode_hash(body), content_type: "application/json", file_path: "", location: "")
+  end
+
+  def self.markdown(status, body)
+    new(status: status, body: body, content_type: "text/markdown; charset=utf-8", file_path: "", location: "")
+  end
+
+  def self.file(status, path, content_type)
+    new(status: status, body: "", content_type: content_type, file_path: path, location: "")
+  end
+
+  # 302 Found by default (matches Rails' `redirect_to`). Pass `status:`
+  # for 301 (permanent), 303 (POST → GET, See Other), or 307/308. The
+  # body is empty — clients follow the Location header without reading
+  # it — but content_type stays at the text/plain default so anything
+  # that does look at the response sees a sane Content-Type.
+  def self.redirect(location = "", status: 302)
+    new(status: status, body: "", content_type: "text/plain; charset=utf-8", file_path: "", location: location)
+  end
+end
+
+# HTTP/1.1 reason phrases for the statuses M2-M3 actually emit. Spinel
+# can't take a Hash#[] of a missing key safely under polymorphism, so
+# `reason_for` falls back to "OK" for anything we forgot.
+REASON_PHRASES = {
+  200 => "OK",
+  201 => "Created",
+  204 => "No 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",
+  413 => "Payload Too Large",
+  500 => "Internal Server Error",
+  501 => "Not Implemented",
+  503 => "Service Unavailable",
+}.freeze
+
+def reason_for(status)
+  r = REASON_PHRASES[status]
+  return r if r
+  "OK"
+end
+
+# Extension → Content-Type for the handful of types static-file
+# routes are likely to serve in MVP. Everything else falls back to
+# application/octet-stream so browsers download rather than guess.
+# View-helper namespace targeted by Herb-compiled templates. Templates
+# emit `::Spinel::View.h((expr))` for escaped interpolations and the
+# attr/js/css variants for attribute/script/style contexts. The escape
+# tables are open-coded as gsub chains — Spinel doesn't support the
+# `gsub(/regex/, hash)` form Herb's own helpers use, but
+# `gsub(string, string)` lowers fine.
+module Spinel
+  module View
+    def self.h(value)
+      s = value.to_s
+      s = s.gsub("&", "&amp;")
+      s = s.gsub("<", "&lt;")
+      s = s.gsub(">", "&gt;")
+      s = s.gsub('"', "&quot;")
+      s = s.gsub("'", "&#39;")
+      s
+    end
+
+    def self.attr(value)
+      s = value.to_s
+      s = s.gsub("&", "&amp;")
+      s = s.gsub('"', "&quot;")
+      s = s.gsub("'", "&#39;")
+      s = s.gsub("<", "&lt;")
+      s = s.gsub(">", "&gt;")
+      s = s.gsub("\n", "&#10;")
+      s = s.gsub("\r", "&#13;")
+      s = s.gsub("\t", "&#9;")
+      s
+    end
+
+    # MVP js/css escapers: conservative replacements rather than the
+    # codepoint-driven gsub-with-block Herb ships. Good enough to keep
+    # `</script>` and CSS terminators from breaking out; extend later.
+    def self.js(value)
+      s = value.to_s
+      s = s.gsub("\\", "\\\\")
+      s = s.gsub("\n", "\\n")
+      s = s.gsub("\r", "\\r")
+      s = s.gsub("\t", "\\t")
+      s = s.gsub("'", "\\'")
+      s = s.gsub('"', "\\\"")
+      s = s.gsub("<", "\\u003c")
+      s = s.gsub(">", "\\u003e")
+      s = s.gsub("&", "\\u0026")
+      s
+    end
+
+    def self.css(value)
+      s = value.to_s
+      s = s.gsub("\\", "\\\\")
+      s = s.gsub('"', "\\\"")
+      s = s.gsub("'", "\\'")
+      s = s.gsub("<", "\\3c ")
+      s = s.gsub(">", "\\3e ")
+      s = s.gsub("&", "\\26 ")
+      s
+    end
+  end
+
+  # Hand-rolled JSON encoder. Scalars and Arrays dispatch through the
+  # polymorphic `encode`; Hashes are handled by `encode_hash`, which
+  # is pinned to `Hash<Symbol, *>` (`SymPolyHash`) via a default-arg
+  # type hint *and* a single-call-site discipline.
+  #
+  # Spinel limitation: `.each` lowering on a polymorphic-typed
+  # (`sp_RbVal`) hash only emits array-tag branches — a Hash there
+  # silently iterates zero times. The analyzer also widens
+  # `encode_hash`'s parameter to `sp_RbVal` if there's any call site
+  # where the argument is polymorphic. So `encode_hash` is called
+  # only from `Response.json` (where `body` is a concrete SymPolyHash),
+  # and `encode`'s `value.is_a?(Hash)` branch recurses through it via
+  # an implicit `(sp_SymPolyHash *)` cast that Spinel inserts at the
+  # call site. Nested hashes within Arrays / Hash values therefore
+  # only encode their *first* level correctly when they happen to be
+  # SymPolyHash; deeper nesting through a polymorphic-typed value
+  # will need either a Spinel codegen change or per-shape encoders.
+  module Json
+    def self.encode(value)
+      return "null"  if value.nil?
+      return "true"  if value == true
+      return "false" if value == false
+      return value.to_s if value.is_a?(Integer)
+      return value.to_s if value.is_a?(Float)
+      return encode_string(value)        if value.is_a?(String)
+      return encode_string(value.to_s)   if value.is_a?(Symbol)
+      if value.is_a?(Array)
+        out = "["
+        i = 0
+        while i < value.length
+          out += "," if i > 0
+          out += encode(value[i])
+          i += 1
+        end
+        return out + "]"
+      end
+      # Polymorphic Hash recursion path. Under CRuby this iterates
+      # correctly; under Spinel the `.each` lowering on a RbVal-typed
+      # hash only emits array-tag branches and silently produces
+      # `"{}"`. The two implementations diverge here on purpose —
+      # CRuby (bin/dev) reads payloads as written, while Spinel-built
+      # binaries should pre-encode nested hashes with `encode_hash`
+      # and concatenate the outer JSON manually if they need it.
+      return encode_recursive_hash(value) if value.is_a?(Hash)
+      encode_string(value.to_s)
+    end
+
+    # CRuby-correct, Spinel-degraded sibling of `encode_hash`. Lives
+    # behind a different name so `encode_hash` stays single-caller
+    # and pinned to `SymPolyHash`; this one is the polymorphic
+    # recursion target from `encode` and Spinel widens its parameter
+    # to RbVal, breaking the iteration. Kept for CRuby parity so
+    # `bin/dev` and unit tests still behave as expected.
+    def self.encode_recursive_hash(h = { __t: nil })
+      out = "{"
+      first = true
+      h.each do |k, v|
+        out += "," unless first
+        first = false
+        encoded_value = encode(v)
+        out += encode_string(k.to_s) + ":" + encoded_value
+      end
+      out + "}"
+    end
+
+    # Hash branch lives in its own function so the `h = { __t: nil }`
+    # default pins `h` to `SymPolyHash` for Spinel's analyzer. Inline
+    # iteration on a polymorphic `value` inside `encode` would lower to
+    # array-only branches; passing through a typed parameter forces a
+    # real hash walk. The default `{ __t: nil }` is never visible —
+    # the function is only ever called with an actual hash from the
+    # `value.is_a?(Hash)` branch in `encode`.
+    def self.encode_hash(h = { __t: nil })
+      out = "{"
+      first = true
+      h.each do |k, v|
+        out += "," unless first
+        first = false
+        encoded_value = encode(v)
+        out += encode_string(k.to_s) + ":" + encoded_value
+      end
+      out + "}"
+    end
+
+    # Char-by-char concat (plan quirk: stick to the existing parsers'
+    # shape rather than `gsub` chains). gsub-with-string-replacement
+    # interprets backslash backreferences under CRuby — encoding the
+    # JSON `\\` escape requires four-deep escaping that doesn't carry
+    # to Spinel. The walk sidesteps all of that and stays monomorphic.
+    # Control chars below 0x20 other than the named escapes pass
+    # through unescaped; an MVP encoder for app-built payloads doesn't
+    # need the full \u00XX table.
+    def self.encode_string(s)
+      out = "\""
+      i = 0
+      n = s.length
+      while i < n
+        c = s[i]
+        if c == "\\"
+          out += "\\\\"
+        elsif c == "\""
+          out += "\\\""
+        elsif c == "\n"
+          out += "\\n"
+        elsif c == "\r"
+          out += "\\r"
+        elsif c == "\t"
+          out += "\\t"
+        elsif c == "\b"
+          out += "\\b"
+        elsif c == "\f"
+          out += "\\f"
+        else
+          out += c
+        end
+        i += 1
+      end
+      out + "\""
+    end
+
+  end
+end
+
+module Mime
+  EXT_MAP = {
+    ".html" => "text/html; charset=utf-8",
+    ".htm"  => "text/html; charset=utf-8",
+    ".css"  => "text/css; charset=utf-8",
+    ".js"   => "application/javascript",
+    ".json" => "application/json",
+    ".txt"  => "text/plain; 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",
+    ".ico"  => "image/x-icon",
+    ".wasm" => "application/wasm",
+  }.freeze
+
+  def self.for_path(path = "")
+    dot = str_ridx(path, ".")
+    return "application/octet-stream" if dot < 0
+    ext = path[dot...path.length].downcase
+    return EXT_MAP[ext] if EXT_MAP.key?(ext)
+    "application/octet-stream"
+  end
+end
+
+# Build a sendfile-backed Response for a path-under-root. Rejects
+# anything with `..` (traversal) or a leading `/` (absolute), then
+# stats the file. Missing file → 404 (rendered via error_response,
+# which picks up public/404.html if the app supplies one). Otherwise
+# → Response.file with the right Content-Type for the extension.
+#
+# Path-safety is intentionally simple: substring checks on the raw
+# string. We don't URL-decode (the parser leaves that alone for MVP),
+# and we don't follow symlinks back out of root. Good enough for an
+# MVP serving from a known-safe public/ dir; tighten when needed.
+def file_response(rel_path = "", root = "")
+  if rel_path.include?("..") || rel_path.length == 0 || rel_path[0] == "/"
+    return error_response(404, "Not Found")
+  end
+  abs = root + "/" + rel_path
+  size = Sock.sphttp_file_size(abs)
+  if size < 0
+    return error_response(404, "Not Found")
+  end
+  Response.file(200, abs, Mime.for_path(rel_path))
+end
+
+# Per-status error page lookup. If `public/<status>.html` exists,
+# serve it as the body (sendfile path); otherwise fall back to a
+# plain-text body so 4xx/5xx still emit a sane response when the
+# app hasn't supplied a custom page. Used by the dispatcher 404, the
+# static-file 404, the request-parse 400/413, and the action-raised
+# 500 path. Keep this dead simple — no template rendering, no
+# locals — so it stays callable when the rest of the app is broken.
+def error_response(status, default_body)
+  path = "public/" + status.to_s + ".html"
+  if Sock.sphttp_file_size(path) >= 0
+    return Response.file(status, path, "text/html; charset=utf-8")
+  end
+  Response.text(status, default_body)
+end
+
+# Single hex nibble — explicit case keeps each branch monomorphic on
+# String. Returns -1 for a non-hex char so `url_decode` can fall back
+# to literal '%' rather than fabricating a byte. The `c = ""` default
+# acts as a String type hint for Spinel: parameters without a default
+# collapse to mrb_int when the analyzer can't disambiguate (the same
+# rule as ctor kwargs — see [[spinel_initialize_kwargs]]).
+def hex_nibble(c = "")
+  return  0 if c == "0"
+  return  1 if c == "1"
+  return  2 if c == "2"
+  return  3 if c == "3"
+  return  4 if c == "4"
+  return  5 if c == "5"
+  return  6 if c == "6"
+  return  7 if c == "7"
+  return  8 if c == "8"
+  return  9 if c == "9"
+  return 10 if c == "a" || c == "A"
+  return 11 if c == "b" || c == "B"
+  return 12 if c == "c" || c == "C"
+  return 13 if c == "d" || c == "D"
+  return 14 if c == "e" || c == "E"
+  return 15 if c == "f" || c == "F"
+  -1
+end
+
+# `+` → space, then `%XX` → byte. Byte walk + char concat — no
+# String#unpack or Regexp tricks (Spinel quirks). Malformed escapes
+# (% at EOF, %ZZ) pass through literally rather than raising.
+# `s = ""` default pins `s` to String — without it, Spinel's analyzer
+# can't tell whether `s.length` / `s[i]` mean String or bitfield-on-int
+# and lowers s[i] to `(s >> i) & 1` (genuinely surprising).
+def url_decode(s = "")
+  out = ""
+  i = 0
+  n = s.length
+  while i < n
+    c = s[i]
+    if c == "+"
+      out += " "
+      i += 1
+    elsif c == "%" && i + 2 < n
+      hi = hex_nibble(s[i + 1])
+      lo = hex_nibble(s[i + 2])
+      if hi >= 0 && lo >= 0
+        out += (hi * 16 + lo).chr
+        i += 3
+      else
+        out += c
+        i += 1
+      end
+    else
+      out += c
+      i += 1
+    end
+  end
+  out
+end
+
+# Parse `k=v&k=v` into the supplied Params wrapper. Mutates in place
+# to dodge the polymorphic-write no-op (plan quirks). Both name and
+# value run through `url_decode` so `?q=hello%20world` lands as
+# `:q => "hello world"`.
+#
+# Takes the `Params` object rather than the raw hash so writes lower
+# through the monomorphic `Params#set_sym`. Spinel's generic polymorphic
+# `Hash#[]=` only emits array branches in the dispatch and silently
+# no-ops on the hash case.
+def parse_query_string!(s, into)
+  pairs = s.split("&")
+  i = 0
+  while i < pairs.length
+    pair = pairs[i]
+    if pair.length > 0
+      eq = str_idx(pair, "=")
+      if eq < 0
+        into.set_sym(url_decode(pair).to_sym, "")
+      else
+        name  = url_decode(pair[0...eq]).to_sym
+        value = url_decode(pair[(eq + 1)...pair.length])
+        into.set_sym(name, value)
+      end
+    end
+    i += 1
+  end
+end
+
+# Form bodies share the `application/x-www-form-urlencoded` framing
+# with query strings — same `k=v&k=v`, same percent/`+` decode. Kept
+# as a separate function (vs aliasing) so the call-site reads
+# "form body" rather than "abusing the query parser". Takes the
+# `Params` wrapper for the same reason as `parse_query_string!`.
+def parse_form_body!(body, into)
+  parse_query_string!(body, into)
+end
+
+# RFC 3986 percent-encode. ALPHA / DIGIT / `-._~` pass through; every
+# other byte becomes `%XX` (uppercase hex). Used by Response#set_cookie
+# to make values safe for the Set-Cookie line and by Session to encode
+# the signed payload. `s = ""` pins the String type for Spinel's analyzer
+# (same default-hint discipline as url_decode).
+def url_encode(s = "")
+  out = ""
+  i = 0
+  n = s.length
+  while i < n
+    c = s[i]
+    if (c >= "a" && c <= "z") || (c >= "A" && c <= "Z") ||
+       (c >= "0" && c <= "9") || c == "-" || c == "." ||
+       c == "_" || c == "~"
+      out += c
+    else
+      b = c.bytes[0]
+      out += "%"
+      out += hex_char_upper(b / 16)
+      out += hex_char_upper(b % 16)
+    end
+    i += 1
+  end
+  out
+end
+
+def hex_char_upper(n = 0)
+  return "0" if n == 0
+  return "1" if n == 1
+  return "2" if n == 2
+  return "3" if n == 3
+  return "4" if n == 4
+  return "5" if n == 5
+  return "6" if n == 6
+  return "7" if n == 7
+  return "8" if n == 8
+  return "9" if n == 9
+  return "A" if n == 10
+  return "B" if n == 11
+  return "C" if n == 12
+  return "D" if n == 13
+  return "E" if n == 14
+  return "F" if n == 15
+  "0"
+end
+
+# Parse a Cookie: header value (`a=1; b=hello%20world; flag`) into the
+# given Str->Str hash. Values are URL-decoded (clients may percent-encode
+# arbitrary bytes; we always round-trip via `url_decode` on read). Bare
+# tokens with no `=` are recorded as empty-value entries — rare but
+# preserves "is this name present?" semantics.
+def parse_cookie_header!(s = "", into = { "__t" => "" })
+  i = 0
+  n = s.length
+  while i < n
+    # Skip leading whitespace between pairs.
+    while i < n && (s[i] == " " || s[i] == "\t")
+      i += 1
+    end
+    break if i >= n
+
+    pair_end = str_idx_from(s, ";", i)
+    pair_end = n if pair_end < 0
+
+    eq = str_idx_from(s, "=", i)
+    if eq < 0 || eq >= pair_end
+      into[s[i...pair_end]] = ""
+    else
+      name  = s[i...eq]
+      value = url_decode(s[(eq + 1)...pair_end])
+      into[name] = value
+    end
+
+    i = pair_end + 1
+  end
+end
+
+# If a signed session cookie is present and a secret is configured,
+# verify + decode it into req.session. No-ops when either piece is
+# missing — the bag stays empty and handlers writing to it just stage
+# fresh state for the response cookie.
+def maybe_load_session!(req)
+  secret = Fresco.session_secret
+  return if secret.length == 0
+  cv = req.cookies[SESSION_COOKIE_NAME]
+  return if cv.nil?
+  return if cv.length == 0
+  req.session.load_from(cv, secret)
+  promote_flash!(req)
+end
+
+# Move any `_flash.<key>` entries from the loaded session into
+# req.flash.read_data, removing them from the session as we go. The
+# removal marks the session dirty so the cleared state ships back in
+# the response cookie — that's how flash earns its "one bounce only"
+# guarantee. If no flash entries are present this is a no-op (session
+# stays clean).
+def promote_flash!(req)
+  data = req.session.data
+  prefix_len = FLASH_KEY_PREFIX.length
+  # Collect keys first; can't safely mutate a hash while iterating it.
+  to_clear = [""]
+  to_clear.delete_at(0)
+  data.each do |k, v|
+    if k.length > prefix_len && k[0, prefix_len] == FLASH_KEY_PREFIX
+      short_key = k[prefix_len, k.length - prefix_len]
+      req.flash.read_data[short_key] = v
+      to_clear.push(k)
+    end
+  end
+  i = 0
+  while i < to_clear.length
+    data.delete(to_clear[i])
+    i += 1
+  end
+  if to_clear.length > 0
+    req.session.mark_dirty
+  end
+end
+
+# Before signing the outbound session cookie, copy req.flash.write_data
+# into the session as `_flash.<key>` entries. Each set marks the session
+# dirty, so the cookie will be emitted even if the handler didn't touch
+# req.session directly.
+def consume_flash_writes!(req)
+  return if req.flash.write_data.length == 0
+  req.flash.write_data.each do |k, v|
+    req.session.set(FLASH_KEY_PREFIX + k, v)
+  end
+end
+
+# After the handler runs, if anything wrote to req.session, sign +
+# encode the bag and attach a Set-Cookie line to the response. Path=/
+# so it covers the whole app; HttpOnly to keep it out of JS; SameSite=Lax
+# as a sensible default (blocks CSRF on top-level cross-site POSTs
+# without breaking link navigations).
+def attach_session_cookie!(req, res)
+  secret = Fresco.session_secret
+  return if secret.length == 0
+  consume_flash_writes!(req)
+  return unless req.session.dirty
+  opts = { "__t" => "" }
+  opts.delete("__t")
+  opts["Path"]     = "/"
+  opts["HttpOnly"] = ""
+  opts["SameSite"] = "Lax"
+  res.set_cookie_with_opts(SESSION_COOKIE_NAME, req.session.to_cookie_value(secret), opts)
+end
+
+# Parse an HTTP/1.x request out of the C-side request buffer. Reads
+# the request line, headers (lowercased keys), strips any `?query`
+# off the path, and pulls a `Content-Length`-bounded body. Returns a
+# fully populated Request, or nil if the bytes don't look like HTTP.
+#
+# Body strategy: any bytes that arrived past the header terminator are
+# already in the request buf (capped at 64 KiB). For bodies that span
+# beyond that, sphttp_drain_body reads the rest into the body buf.
+# Cap: 1 MiB (decision #5); larger requests get parse_status=413.
+#
+# Always returns a Request — failures populate `parse_status` with the
+# HTTP code the caller should respond with (400 / 413). The single-type
+# return is load-bearing for Spinel: a Request|nil|:too_large union
+# would widen the entire dispatch chain's `req` parameter to sp_RbVal
+# and break the polymorphic call from Fresco::Action#handle to each
+# subclass's #call.
+def bad_request
+  r = Request.new("", "", "")
+  r.parse_status = 400
+  r
+end
+
+def parse_http_request(client)
+  buf     = Sock.sphttp_request_buf
+  buf_len = Sock.sphttp_request_len
+  hdr_end = Sock.sphttp_header_end
+  return bad_request if hdr_end < 0
+  return bad_request if buf_len <= 0
+
+  rl_end = str_idx(buf, "\r\n")
+  return bad_request if rl_end < 0
+
+  request_line = buf[0...rl_end]
+  parts = request_line.split(" ")
+  return bad_request if parts.length < 3
+
+  method = parts[0]
+  raw_path = parts[1]
+  version  = parts[2]
+
+  qmark = str_idx(raw_path, "?")
+  if qmark >= 0
+    path = raw_path[0...qmark]
+    qstr = raw_path[(qmark + 1)...raw_path.length]
+  else
+    path = raw_path
+    qstr = ""
+  end
+
+  # Build the Request now so the parser can fill its headers/body
+  # in place. Reassigning @headers risks Spinel's polymorphic-write
+  # no-op trap (plan's Spinel quirks).
+  req = Request.new(method, path, "")
+  req.version = version
+  hdrs = req.headers
+
+  # Fold the query string directly into the params hash. The
+  # dispatcher will write path captures into the same hash after this
+  # parse returns, so path beats query without explicit precedence
+  # logic — see plan decision #2.
+  parse_query_string!(qstr, req.params) if qstr.length > 0
+
+  # cl + ctype captured during the header walk so the body-read step
+  # below doesn't need a `hdrs[]` lookup. Reading through `hdrs[]` (a
+  # Str→Str hash exposed via `attr_reader :headers`) returns sp_RbVal
+  # under Spinel, and `cl_str.to_i` on a boxed value silently evaluates
+  # to 0 — the body never gets drained and form-body params come back
+  # empty. Capturing the values inline avoids the boxed read entirely.
+  cl    = 0
+  ctype = ""
+  i = rl_end + 2
+  limit = hdr_end - 2 # one CRLF before the blank-line CRLF
+  while i < limit
+    line_end = str_idx_from(buf, "\r\n", i)
+    break if line_end < 0
+    break if line_end == i
+
+    colon = str_idx_from(buf, ":", i)
+    if colon > i && colon < line_end
+      name = buf[i...colon].downcase
+      v = colon + 1
+      while v < line_end && buf[v] == " "
+        v += 1
+      end
+      val = buf[v...line_end]
+      hdrs[name] = val
+      cl    = val.to_i if name == "content-length"
+      ctype = val      if name == "content-type"
+    end
+
+    i = line_end + 2
+  end
+
+  cookie_hdr = hdrs["cookie"]
+  if cookie_hdr && cookie_hdr.length > 0
+    parse_cookie_header!(cookie_hdr, req.cookies)
+  end
+  maybe_load_session!(req)
+
+  # `cl` and `ctype` were captured during the header walk above —
+  # see the comment there for why we don't read them back through
+  # `hdrs[]` here.
+  if cl > 0
+    if cl > 1048576
+      req.parse_status = 413
+      return req
+    end
+
+    body_in_buf = buf_len - hdr_end
+    if body_in_buf < 0
+      body_in_buf = 0
+    end
+    have = body_in_buf < cl ? body_in_buf : cl
+
+    # Seed body buf with bytes that came in with the headers.
+    Sock.sphttp_copy_body(hdr_end, 0, have)
+    if have < cl
+      Sock.sphttp_drain_body(client, have, cl - have)
+    end
+    # `+ ""` forces a Ruby-owned copy out of the C-owned body buf,
+    # which will be overwritten on the next request. Stash in a local
+    # so the form-body parser below gets a String-pinned value —
+    # reading back through `req.body`'s attr_accessor widens the type
+    # at the call site and the downstream `s.split("&")` lowers to a
+    # silent no-op.
+    body_str = Sock.sphttp_body_buf + ""
+    req.body = body_str
+
+    # Fold form bodies into the same params hash query went into.
+    # Exact-match content-type filter (plan decision #6) — no
+    # tolerance for `; charset=utf-8` suffixes in MVP. The dispatcher
+    # writes path captures after parse_http_request returns, so the
+    # final precedence is path > form > query.
+    #
+    # Calls parse_query_string! directly (not parse_form_body!): the
+    # one-line indirection through parse_form_body! collapses param
+    # types to mrb_int under Spinel and the parse silently no-ops.
+    if ctype == "application/x-www-form-urlencoded"
+      parse_query_string!(body_str, req.params)
+    end
+  end
+
+  # Rails-style `_method` override: HTML forms can only emit GET/POST,
+  # so a hidden `_method=patch|put|delete` lets a POST form route as
+  # the verb the dispatcher expects. Only honored when the wire method
+  # is POST — query-string overrides on GET would let a stray link
+  # delete things.
+  if req.verb == "POST"
+    override = req.params.str(:_method)
+    req.verb = override.upcase if override.length > 0
+  end
+
+  req
+end
+
+def build_headers(status, ctype, content_length, conn, set_cookies, location = "")
+  out  = "HTTP/1.1 "
+  out += status.to_s
+  out += " "
+  out += reason_for(status)
+  out += "\r\nContent-Type: "
+  out += ctype
+  out += "\r\nContent-Length: "
+  out += content_length.to_s
+  out += "\r\nConnection: "
+  out += conn
+  # `Location:` is emitted only for redirect responses (Response.redirect
+  # populates @location). Empty string → no header, so non-redirect
+  # responses stay byte-identical to before this slot existed.
+  if location.length > 0
+    out += "\r\nLocation: "
+    out += location
+  end
+  # One Set-Cookie line per array entry. Order matches push order.
+  i = 0
+  while i < set_cookies.length
+    out += "\r\nSet-Cookie: "
+    out += set_cookies[i]
+    i += 1
+  end
+  out += "\r\n\r\n"
+  out
+end
+
+# Build a wire-format HTTP/1.1 response. For body responses the
+# headers + body go out in one write. For file responses (file_path
+# set on the Response) we stat the file for size, send the headers,
+# then `sphttp_sendfile(2)` the bytes — skipping the copy through a
+# Ruby string entirely.
+def write_response(client, res, keep_alive)
+  if keep_alive
+    conn = "keep-alive"
+  else
+    conn = "close"
+  end
+
+  if res.file_path.length > 0
+    size = Sock.sphttp_file_size(res.file_path)
+    if size < 0
+      # File vanished between dispatch and write. Honor the contract
+      # with a 404 rather than partial output. Force the socket shut.
+      body = "Not Found"
+      hdr  = build_headers(404, "text/plain; charset=utf-8", body.length, "close", res.set_cookies, "")
+      Sock.sphttp_write_str(client, hdr + body)
+      return
+    end
+    Sock.sphttp_write_str(client, build_headers(res.status, res.content_type, size, conn, res.set_cookies, res.location))
+    Sock.sphttp_sendfile(client, res.file_path)
+    return
+  end
+
+  body  = res.body
+  bytes = body.length
+  Sock.sphttp_write_str(client, build_headers(res.status, res.content_type, bytes, conn, res.set_cookies, res.location) + body)
+end
+
+# ANSI colorization for log lines. Honors NO_COLOR
+# (https://no-color.org) — any non-empty value disables. We don't
+# auto-detect a TTY: log output usually goes to a terminal, journalctl,
+# or a TTY-aware aggregator, all of which render ANSI fine. Pipe to a
+# file? `NO_COLOR=1 ./bin/server`.
+#
+# Spinel-shape constraints worth flagging up front, since they shape
+# the awkward bits below:
+#   - `wrap` does stepwise concat (vs a single `+` chain) so each
+#     intermediate is narrowly typed String, matching the
+#     build_headers / url_encode pattern in this file.
+#   - The disabled branch goes through the same `out = ""; out += s`
+#     concat instead of `return s` so wrap's return type doesn't fork
+#     into String|RbVal — Spinel would widen the function (and every
+#     caller's parameter) to RbVal, then the enabled branch's
+#     `out += s` would fail to compile against an RbVal `s`.
+#   - For the same reason, `color_method` / `color_status` *always*
+#     route through a Color helper, including their fallback path —
+#     a bare `return m` would be String while the other returns are
+#     RbVal-shaped, and the unification widens `m` itself, which then
+#     propagates back into Color.red(m) → wrap → broken codegen.
+module Color
+  def self.enabled?
+    ENV.fetch("NO_COLOR", "") == ""
+  end
+
+  def self.wrap(code = "", s = "")
+    if enabled?
+      out  = "\e["
+      out += code
+      out += "m"
+      out += s
+      out += "\e[0m"
+      return out
+    end
+    out = ""
+    out += s
+    out
+  end
+
+  def self.dim(s = "");     wrap("2",  s); end
+  def self.bold(s = "");    wrap("1",  s); end
+  def self.red(s = "");     wrap("31", s); end
+  def self.green(s = "");   wrap("32", s); end
+  def self.yellow(s = "");  wrap("33", s); end
+  def self.blue(s = "");    wrap("34", s); end
+  def self.magenta(s = ""); wrap("35", s); end
+  def self.cyan(s = "");    wrap("36", s); end
+
+  # No-op coloring: emits the input untouched but routes through `wrap`
+  # so callers that need a uniform return type (color_method,
+  # color_status) can use it as a fallback without forking the return
+  # into String|RbVal — see the note on Color above.
+  def self.plain(s = "");   wrap("",   s); end
+end
+
+# Per-method palette — green for safe reads, yellow for creates,
+# blue for updates, red for destroys. Matches the convention most
+# request inspectors (Postman, Insomnia, the Chrome devtools network
+# panel) settled on, so it reads at a glance. Unknown methods route
+# through Color.plain for the uniform-return-type discipline noted
+# on Color.
+#
+# `s = m.to_s` is the type-pin: Spinel's `.to_s` always lowers to
+# `sp_poly_to_s` (declared `const char *`) regardless of m's inferred
+# type, so `s` is guaranteed String. Without this, m's parameter type
+# (which the analyzer pessimistically widens to RbVal here — the
+# multiple `Color.*` call sites in this body form a circular
+# unification with wrap's `s`) would propagate into Color.green/red/
+# etc. and force every wrap-helper to take RbVal, which then breaks
+# the `out += s` (String += RbVal) inside wrap.
+def color_method(m = "")
+  s = m.to_s
+  return Color.green(s)  if s == "GET"
+  return Color.green(s)  if s == "HEAD"
+  return Color.yellow(s) if s == "POST"
+  return Color.blue(s)   if s == "PATCH"
+  return Color.blue(s)   if s == "PUT"
+  return Color.red(s)    if s == "DELETE"
+  return Color.cyan(s)   if s == "OPTIONS"
+  Color.plain(s)
+end
+
+# Status: 2xx green (success), 3xx cyan (redirect), 4xx yellow
+# (client error — operator should glance), 5xx red (server error —
+# operator must look). 1xx falls through to Color.plain — same
+# uniform-return-type discipline as color_method. `status.to_s` here
+# is naturally String (Integer#to_s in Spinel is `sp_int_to_s` →
+# `const char *`).
+def color_status(status = 0)
+  s = status.to_s
+  return Color.green(s)  if status >= 200 && status < 300
+  return Color.cyan(s)   if status >= 300 && status < 400
+  return Color.yellow(s) if status >= 400 && status < 500
+  return Color.red(s)    if status >= 500
+  Color.plain(s)
+end
+
+# SQL log colorization. Verb-driven palette mirroring color_method —
+# green for safe reads (SELECT), yellow for creates (INSERT), blue for
+# updates (UPDATE), red for destroys (DELETE), magenta for transaction
+# control and DDL (BEGIN/COMMIT/ROLLBACK/CREATE/ALTER/DROP). Unknown
+# leads fall through to Color.plain.
+#
+# Uniform-return-type discipline: every branch routes through a Color
+# helper so the inferred return stays String. The same widening trap
+# from color_method/color_status applies here — a bare `return sql`
+# would fork the return into String|RbVal under Spinel's analyzer.
+#
+# Match is by leading-keyword on the raw SQL string. Generated model
+# code always emits uppercase leads (see lib/templates/model.rb.erb);
+# user-supplied `Fresco::Db.exec(...)` strings that lead with
+# lowercase will fall through to Color.plain rather than mis-match,
+# which is the right safety default.
+def color_sql(sql = "")
+  return Color.green(sql)   if sql.start_with?("SELECT")
+  return Color.yellow(sql)  if sql.start_with?("INSERT")
+  return Color.blue(sql)    if sql.start_with?("UPDATE")
+  return Color.red(sql)     if sql.start_with?("DELETE")
+  return Color.magenta(sql) if sql.start_with?("BEGIN")
+  return Color.magenta(sql) if sql.start_with?("COMMIT")
+  return Color.magenta(sql) if sql.start_with?("ROLLBACK")
+  return Color.magenta(sql) if sql.start_with?("CREATE")
+  return Color.magenta(sql) if sql.start_with?("ALTER")
+  return Color.magenta(sql) if sql.start_with?("DROP")
+  Color.plain(sql)
+end
+
+# Format a Sym→Str hash for the request log. Manual concat (vs
+# Hash#inspect) keeps the each-block in the str-concat narrow path —
+# Spinel infers the param as sym_str_hash from the k/v usage. See
+# spinel test/hash_each_param_narrow.rb.
+def format_hash(h)
+  out = "{"
+  first = true
+  h.each do |k, v|
+    out += ", " unless first
+    first = false
+    out += k.to_s + "=" + v.to_s
+  end
+  out + "}"
+end
+
+  # Format an integer micro-second count for the request / SQL log
+  # lines. Sub-millisecond values stay in micros ("742us") so single-
+  # digit-millisecond values aren't lost to rounding; >= 1ms switches
+  # to milliseconds with one decimal ("12.3ms") because once you're in
+  # the millis range nobody cares about the trailing micros.
+  #
+  # Plain integer math — Spinel doesn't lower Float arithmetic across
+  # the analyzer pass yet, and the rest of the timing code in this
+  # file is `int micros` throughout (sphttp_elapsed_micros returns
+  # `int`). The whole.to_s / tenth.to_s split keeps the result a
+  # narrow String.
+def fmt_micros(us = 0)
+  return us.to_s + "us" if us < 1000
+  whole = us / 1000
+  tenth = (us % 1000) / 100
+  whole.to_s + "." + tenth.to_s + "ms"
+end
+
+def log_request_brief(method, path, status, micros)
+  puts Color.dim("[request] ") + color_method(method) + " " + path + " " +
+       color_status(status) + " " + Color.dim("(" + fmt_micros(micros) + ")")
+end
+
+def log_request_full(req, status, micros)
+  line = Color.dim("[request] ") + color_method(req.verb) + " " + req.path + " " +
+         color_status(status) + " " + Color.dim("(" + fmt_micros(micros) + ")")
+  # SQL roll-up. The db adapter funnels per-query micros into the
+  # `Fresco`-module counters during the request (zeroed by
+  # `Fresco::Db.begin_request!` → `Fresco.reset_db_sql_stats!`);
+  # we read both back here so the operator sees the SQL share of
+  # the request budget on the same line as the request total.
+  # Read from `Fresco` (same file) rather than `Fresco::Db` (loaded
+  # later) because cross-file value-returning module calls resolve
+  # the receiver to `int` and emit 0 under Spinel — see the
+  # comment on the counters' declaration above. `query_count == 0`
+  # suppresses the segment entirely so request lines for handlers
+  # that don't touch the DB stay short. The totals are maintained
+  # even when FRESCO_LOG_SQL is off — per-query lines are gated,
+  # the cheap roll-up isn't.
+  sql_us = Fresco.db_sql_total_micros
+  sql_n  = Fresco.db_sql_query_count
+  if sql_n > 0
+    line += " " + Color.dim("sql=" + fmt_micros(sql_us) + "/" + sql_n.to_s + "q")
+  end
+  # Query is now folded into params at parse time; logging only the
+  # merged hash keeps the formatter monomorphic on Sym→Str (plan
+  # decision #5). `req.params.raw` is the underlying Hash — handing
+  # the Params wrapper to `format_hash` would force a second type.
+  if req.params.length > 0
+    line += " " + Color.dim("params=" + format_hash(req.params.raw))
+  end
+  puts line
+end
+
+# Serve one TCP connection. Loops until the client closes, a parse
+# fails, or the response opts out of keep-alive. Each iteration reads
+# a fresh request into the (reset) request buf; pipelining is out of
+# scope — clients must wait for response N before sending request N+1.
+def handle_connection(client)
+  keep_going = true
+  while keep_going
+    n = Sock.sphttp_read_request(client)
+    break if n <= 0
+
+    # Parse-error logs still use the parse/write window below. Successful
+    # requests reset the timer after parsing so dev and release report the
+    # same app-handling window: dispatch + session-cookie attachment.
+    Sock.sphttp_mark_now
+    parsed = parse_http_request(client)
+    if parsed.parse_status == 400
+      write_response(client, error_response(400, "Bad Request\n"), false)
+      log_request_brief("?", "?", 400, Sock.sphttp_elapsed_micros)
+      break
+    end
+    if parsed.parse_status == 413
+      write_response(client, error_response(413, "Payload Too Large\n"), false)
+      log_request_brief("?", "?", 413, Sock.sphttp_elapsed_micros)
+      break
+    end
+
+    keep_going = parsed.keep_alive?
+    # Tell Fresco::Db to buffer SQL log lines during this request so
+    # they flush as an indented block under the [request] line below
+    # (instead of streaming above it in dispatch order). No-op when
+    # FRESCO_LOG_SQL isn't set — the gate lives inside the db adapter.
+    Fresco::Db.begin_request!
+    begin
+      Sock.sphttp_mark_now
+      res = dispatch_request(parsed.verb, parsed.path, parsed)
+      attach_session_cookie!(parsed, res)
+      micros = Sock.sphttp_elapsed_micros
+      write_response(client, res, keep_going)
+      log_request_full(parsed, res.status, micros)
+      Fresco::Db.flush_log!
+    rescue => e
+      micros = Sock.sphttp_elapsed_micros
+      # An action raised. Log a single line (so an operator can grep
+      # for crashes) and serve a sanitised 500 — never the message,
+      # since it could leak internals to clients.
+      puts Color.red("[handler] ") + e.class + ": " + e.message
+      write_response(client, error_response(500, "Internal Server Error\n"), false)
+      log_request_full(parsed, 500, micros)
+      Fresco::Db.flush_log!
+      keep_going = false
+    end
+  end
+  Sock.sphttp_close(client)
+end
+
+def worker_loop(sfd)
+  loop do
+    cfd = Sock.sphttp_accept(sfd)
+    next if cfd < 0
+    handle_connection(cfd)
+  end
+end
+
+# Prefork model. With workers == 1 we run the accept loop inline (no
+# fork, easier to debug, same behavior as M4). With workers > 1 the
+# parent forks N children — each opens its OWN SO_REUSEPORT listener
+# on `port`, and the kernel load-balances incoming accepts across
+# them. The parent never opens a listener; it just waits to reap
+# children. Killing one worker (kill -9) leaves the others serving
+# while the parent reaps the corpse.
+# Fork one worker process and return the child's pid in the parent.
+# Child branch runs worker_loop until exit(0) / crash. Extracted so the
+# initial spawn loop and the reap-loop respawn use one code path —
+# important so the listener-setup details and the "ready" log line
+# stay in lock-step between fresh-boot and post-crash respawn.
+def spawn_worker(port = 0, slot = 0)
+  pid = Sock.sphttp_fork
+  if pid == 0
+    sfd = Sock.sphttp_listen(port, 1) # SO_REUSEPORT — each worker binds independently
+    if sfd < 0
+      puts Color.red("[worker " + Sock.sphttp_getpid.to_s + "] ") + "sphttp_listen failed"
+      exit(1)
+    end
+    puts Color.cyan("[worker " + Sock.sphttp_getpid.to_s + "] ") + "ready (slot " + slot.to_s + ")"
+    worker_loop(sfd)
+    exit(0)
+  end
+  pid
+end
+
+def run_server(port:, workers: 1)
+  if workers <= 1
+    sfd = Sock.sphttp_listen(port, 0)
+    if sfd < 0
+      puts Color.red("[server] ") + "sphttp_listen failed on port " + port.to_s
+      return
+    end
+    puts Color.cyan("[server] ") + "listening on http://0.0.0.0:" + port.to_s + " (pid " + Sock.sphttp_getpid.to_s + ")"
+    worker_loop(sfd)
+    return
+  end
+
+  puts Color.cyan("[server] ") + "listening on http://0.0.0.0:" + port.to_s +
+       " (parent pid " + Sock.sphttp_getpid.to_s +
+       ", workers=" + workers.to_s + ")"
+
+  workers.times do |i|
+    spawn_worker(port, i)
+  end
+
+  # Reap-and-respawn: when a worker dies (crash or graceful exit),
+  # the parent forks a fresh replacement so the served-process count
+  # stays steady. General-purpose crash safety net — handlers that
+  # raise are already caught inside handle_connection, but anything
+  # that escapes (OS-level signal, FFI fault) drops the worker, and
+  # without respawn the service degrades over time.
+  #
+  # `slot` is monotonically incremented so log lines remain unique
+  # (a respawned worker reports `slot=42` etc., not slot 0 again),
+  # making it easy to count restarts from logs. The initial spawn
+  # uses 0..N-1, so respawn slots start at `workers` to avoid overlap.
+  next_slot = workers
+  loop do
+    reaped = Sock.sphttp_wait_any
+    break if reaped < 0
+    puts Color.dim("[server] reaped worker pid " + reaped.to_s + " — respawning as slot " + next_slot.to_s)
+    spawn_worker(port, next_slot)
+    next_slot += 1
+  end
+end