ruact 0.0.4 → 0.0.6

data/bench/server_functions_dispatch_bench.rb

@@ -1,34 +1,34 @@
 # frozen_string_literal: true
 
-# Story 8.1 — AC12 end-to-end dispatch overhead benchmark.
+# Story 9.9 — NFR21 dispatch-overhead benchmark, re-pointed at REAL routes.
 #
-# Compares `ruact_action :create_post` against a plain controller action
-# that does the SAME `Post.create!` work — per AC12's literal text:
+# The v1 substrate (the synthetic `POST /__ruact/fn/:name` endpoint + the
+# `ruact_action` DSL) was demolished, so this bench now exercises the
+# route-driven (v2) contract:
 #
-#   "the script compares `ruact_action :create_post` to a plain
-#   controller action that does the same `Post.create!` and prints
-#   both numbers"
-#   "the median ruact_action overhead is < 20ms per call"
+#   - A non-GET REST route (`POST /posts`) on a controller that does
+#     `include Ruact::Server` — Bucket-2 JSON dispatch (the generated accessor
+#     sends `Accept: application/json`), compared against a plain controller
+#     doing the SAME `Post.create!`. The only delta is the concern's callback
+#     chain (the structured-error `rescue_from` + the upload guard).
+#   - The multipart (`<form action>`) shape on the same route.
+#   - A query route (`GET /q/<jsId>`) drawn by `ruact_queries`.
 #
-# An in-memory SQLite + ActiveRecord schema (created at boot) backs the
-# `Post` model so the two endpoints exercise IDENTICAL write paths —
-# the only delta is the gem's dispatch wrapper (registry lookup +
-# path_parameters swap + thread-local sentinel + the wrapper method).
+# NFR21 budget: server-function dispatch adds < 20ms over a standard Rails
+# request. NOTE (Story 9.9 D2): the v2 path is a REAL Rails route through the
+# full router + the `Ruact::Server` concern — a different code path than the
+# deleted v1 synthetic endpoint, so there is no apples-to-apples per-call delta
+# against the historical v1 baseline. The honest gate is "p50/p95 < 20ms holds."
 #
-# Run with:
+# v1 baseline (historical, Story 9.1, 2026-06-05): ruact_action JSON dispatch
+# p50 0.973ms / p95 1.344ms; plain p50 0.771ms / p95 1.058ms; overhead +0.202ms
+# p50 / +0.286ms p95; multipart p50 1.05ms / p95 1.494ms — all PASS < 20ms.
 #
+# Run with:
 #   bundle exec ruby bench/server_functions_dispatch_bench.rb
 #
-# Output: warm-up + benchmark-ips comparison + 1000-request absolute
-# numbers + median per-call overhead in ms. AC12 target: < 20 ms.
-#
-# CI/nightly:
-#   `.github/workflows/server-functions-bench.yml` runs this script on
-#   `schedule: cron: "0 6 * * *"` (nightly) and on any PR touching
-#   `lib/ruact/server_functions/**`. The workflow does NOT gate merge —
-#   it posts a comment with the numbers so accidental 10× regressions
-#   surface in PR feedback (per AC12: "at minimum, a non-blocking
-#   nightly job").
+# CI/nightly: `.github/workflows/server-functions-bench.yml` runs this on a
+# nightly cron + any PR touching `lib/ruact/server_functions/**`. Non-blocking.
 
 require "bundler/setup"
 require "benchmark/ips"
@@ -40,8 +40,9 @@ require "rack/test"
 
 require "ruact"
 require "ruact/controller"
-require "ruact/server_functions/endpoint_controller"
-require "ruact/server_action"
+require "ruact/server"
+require "ruact/routing"
+require "ruact/query"
 
 ActiveRecord::Base.establish_connection(adapter: "sqlite3", database: ":memory:")
 ActiveRecord::Schema.verbose = false
@@ -57,6 +58,10 @@ class Post < ActiveRecord::Base
   validates :title, presence: true
 end
 
+# No host ApplicationController in this minimal bench — point query dispatch at
+# ActionController::Base so `ruact_queries` resolves its parent controller.
+Ruact.configure { |c| c.query_parent_controller = "ActionController::Base" }
+
 class BenchApp < Rails::Application
   config.eager_load                        = false
   config.consider_all_requests_local       = false
@@ -68,84 +73,101 @@ class BenchApp < Rails::Application
   config.hosts.clear if config.respond_to?(:hosts)
 end
 
-class BenchController < ActionController::Base
-  include Ruact::Controller
+# v2 mutation host — a normal controller that includes Ruact::Server. The
+# `create` action is a non-GET REST route; the generated accessor calls it with
+# `Accept: application/json`, so the concern serves Bucket-2 JSON.
+class PostsController < ActionController::Base
+  include Ruact::Server
 
-  ruact_action(:create_post) do |params|
-    post = Post.create!(title: params[:title], body: params[:body])
-    { id: post.id, title: post.title }
+  def create
+    payload = JSON.parse(request.raw_post)
+    @post = Post.create!(title: payload["title"], body: payload["body"])
+    render(json: { id: @post.id, title: @post.title })
   end
 
-  def plain_create_post
+  # Multipart (`<form action={fn}>`) dispatch on the SAME Ruact::Server host:
+  # the request still flows through the concern (upload guard + error gate +
+  # Accept negotiation) — reads Rack-parsed multipart params.
+  def create_multipart
+    @post = Post.create!(title: params[:title], body: params[:body])
+    render(json: { id: @post.id, title: @post.title })
+  end
+end
+
+# Plain baseline — same Post.create! work, no concern. `create_multipart` reads
+# Rack-parsed multipart params (the `<form action>` wire shape).
+class PlainController < ActionController::Base
+  def create
     payload = JSON.parse(request.raw_post)
     post = Post.create!(title: payload["title"], body: payload["body"])
     render(json: { id: post.id, title: post.title })
   end
-end
 
-BenchApp.routes.append do
-  post "/plain", to: "bench#plain_create_post"
+  def create_multipart
+    post = Post.create!(title: params[:title], body: params[:body])
+    render(json: { id: post.id, title: post.title })
+  end
 end
 
-# Story 8.3 — standalone host module backing the AC10 scenario. Declared
-# BEFORE app initialization so the Railtie's `config.to_prepare` snapshot
-# writer sees the entry (parity with the controller-hosted side).
-module BenchStandaloneHost
-  extend Ruact::ServerAction
-
-  ruact_action :bench_action do |params|
-    post = Post.create!(title: params[:title], body: params[:body])
-    { id: post.id, title: post.title }
+# v2 read host — a Ruact::Query mounted via ruact_queries → GET /q/<jsId>.
+class CatalogQuery < Ruact::Query
+  def recent
+    Post.order(created_at: :desc).limit(5).pluck(:title)
   end
 end
 
+BenchApp.routes.append do
+  post "/posts", to: "posts#create"
+  post "/posts_mp", to: "posts#create_multipart"
+  post "/plain", to: "plain#create"
+  post "/plain_mp", to: "plain#create_multipart"
+  ruact_queries CatalogQuery
+end
+
 BenchApp.instance.initialize!
-# Story 8.3 bench needs API mode so CSRF doesn't reject the bench
-# requests (no session middleware in this minimal Rack::Test setup).
-Ruact::ServerFunctions::EndpointController.allow_forgery_protection = false
+# API mode so CSRF doesn't reject the bench requests (no session middleware in
+# this minimal Rack::Test setup).
+PostsController.allow_forgery_protection = false
 
 include Rack::Test::Methods
 
 def app = BenchApp.instance
 
-# Counter ensures titles stay unique under the AR validation; without
-# this, repeated calls would all attempt to insert the same row and
-# the bench would measure the validation-failure path, not the
-# create-success path.
 counter = 0
 body_for = lambda do
   counter += 1
   { title: "Post #{counter}", body: "body" }.to_json
 end
-headers = { "CONTENT_TYPE" => "application/json" }
+json_headers = { "CONTENT_TYPE" => "application/json", "HTTP_ACCEPT" => "application/json" }
 
-post("/__ruact/fn/create_post", body_for.call, headers)
+post("/posts", body_for.call, json_headers)
 unless last_response.status == 200
-  raise "ruact dispatch broken (status=#{last_response.status} body=#{last_response.body})"
+  raise "ruact server dispatch broken (status=#{last_response.status} body=#{last_response.body})"
 end
 
-post("/plain", body_for.call, headers)
+post("/plain", body_for.call, json_headers)
 raise "plain dispatch broken (status=#{last_response.status})" unless last_response.status == 200
 
+get("/q/recent", {}, { "HTTP_ACCEPT" => "application/json" })
+raise "query dispatch broken (status=#{last_response.status})" unless last_response.status == 200
+
 Benchmark.ips do |x|
   x.config(time: 3, warmup: 1)
 
-  x.report("ruact_action dispatch (Post.create!)") do
-    post("/__ruact/fn/create_post", body_for.call, headers)
+  x.report("Ruact::Server dispatch (POST /posts, Post.create!)") do
+    post("/posts", body_for.call, json_headers)
   end
 
   x.report("plain controller action (Post.create!)") do
-    post("/plain", body_for.call, headers)
+    post("/plain", body_for.call, json_headers)
   end
 
   x.compare!
 end
 
-# Re-run-5 (2026-05-15) — AC12 asks for MEDIAN per-call overhead, not
-# mean. Sample N individual requests so we can compute the median and
-# the percentile spread. The median is the load-bearing number — a few
-# slow outliers (GC pause, OS scheduler) would otherwise inflate the
-# mean and produce misleading regression alerts.
+# NFR21 asks for the MEDIAN per-call number. Sample N individual requests so we
+# can compute the median + the percentile spread; the median is load-bearing (a
+# few GC/scheduler outliers would inflate the mean).
 def time_one_seconds
   t0 = Process.clock_gettime(Process::CLOCK_MONOTONIC)
   yield
@@ -162,8 +184,8 @@ def percentile(sorted, pct)
 end
 
 SAMPLES = 1000
-ruact_samples = sample_times(SAMPLES) { post("/__ruact/fn/create_post", body_for.call, headers) }
-plain_samples = sample_times(SAMPLES) { post("/plain", body_for.call, headers) }
+ruact_samples = sample_times(SAMPLES) { post("/posts", body_for.call, json_headers) }
+plain_samples = sample_times(SAMPLES) { post("/plain", body_for.call, json_headers) }
 
 ruact_p50 = percentile(ruact_samples, 50) * 1000
 plain_p50 = percentile(plain_samples, 50) * 1000
@@ -177,20 +199,17 @@ overhead_p95 = (ruact_p95 - plain_p95).round(3)
 
 puts ""
 puts "#{SAMPLES} requests (Post.create! body):"
-puts "  ruact_action dispatch:    total=#{(ruact_total * 1000).round(1)}ms  p50=#{ruact_p50.round(3)}ms  p95=#{ruact_p95.round(3)}ms"
+puts "  Ruact::Server dispatch:   total=#{(ruact_total * 1000).round(1)}ms  p50=#{ruact_p50.round(3)}ms  p95=#{ruact_p95.round(3)}ms"
 puts "  plain controller action:  total=#{(plain_total * 1000).round(1)}ms  p50=#{plain_p50.round(3)}ms  p95=#{plain_p95.round(3)}ms"
 puts "  per-call overhead (p50):  +#{overhead_p50}ms"
 puts "  per-call overhead (p95):  +#{overhead_p95}ms"
 puts ""
-puts "AC12 target: MEDIAN ruact_action overhead < 20 ms per call (#{overhead_p50 < 20 ? 'PASS' : 'FAIL'})"
+puts "NFR21 target: MEDIAN Ruact::Server dispatch p50/p95 < 20 ms per call " \
+     "(p50 #{ruact_p50.round(3)}ms #{ruact_p50 < 20 ? 'PASS' : 'FAIL'}, " \
+     "p95 #{ruact_p95.round(3)}ms #{ruact_p95 < 20 ? 'PASS' : 'FAIL'})"
 
 # ----------------------------------------------------------------------------
-# Story 8.2 — `<form action={fn}>` multipart dispatch overhead.
-#
-# AC11: median multipart per-call overhead stays within 1.2× of the JSON
-# baseline above. Multipart parsing is heavier than JSON parsing — Rails'
-# multipart parser allocates a temp file per part and walks the boundary
-# stream — but for sub-1KB bodies the cost should be negligible.
+# Multipart (`<form action={fn}>`) dispatch overhead on the same route.
 # ----------------------------------------------------------------------------
 
 require "securerandom"
@@ -216,10 +235,9 @@ multipart_counter = 0
 multipart_post = lambda do
   multipart_counter += 1
   data, boundary = multipart_body("MP Post #{multipart_counter}", "multipart body")
-  post("/__ruact/fn/create_post", data, multipart_headers.call(boundary))
+  post("/posts_mp", data, multipart_headers.call(boundary))
 end
 
-# Warm-up to ensure multipart parser is loaded
 multipart_post.call
 raise "multipart broken (status=#{last_response.status})" unless last_response.status == 200
 
@@ -227,83 +245,32 @@ multipart_samples = sample_times(SAMPLES) { multipart_post.call }
 mp_p50 = percentile(multipart_samples, 50) * 1000
 mp_p95 = percentile(multipart_samples, 95) * 1000
 mp_total_ms = (multipart_samples.sum * 1000).round(1)
-overhead_mp_vs_json_p50 = (mp_p50 - ruact_p50).round(3)
-mp_factor = ruact_p50.zero? ? 0.0 : (mp_p50 / ruact_p50).round(3)
 
 puts ""
-puts "#{SAMPLES} multipart requests (Story 8.2 — `<form action>` shape):"
-puts "  multipart dispatch:       total=#{mp_total_ms}ms  p50=#{mp_p50.round(3)}ms  p95=#{mp_p95.round(3)}ms"
-puts "  vs. JSON ruact baseline:  +#{overhead_mp_vs_json_p50}ms  (factor=#{mp_factor}×)"
+puts "#{SAMPLES} multipart requests (`<form action>` shape) — Ruact::Server route /posts_mp:"
+puts "  Ruact::Server multipart dispatch:  total=#{mp_total_ms}ms  p50=#{mp_p50.round(3)}ms  p95=#{mp_p95.round(3)}ms"
 puts ""
-puts "AC11 target: multipart median <= 1.2× JSON median (#{mp_factor <= 1.2 ? 'PASS' : 'FAIL'})"
+puts "NFR21 target: multipart p50/p95 < 20 ms per call " \
+     "(p50 #{mp_p50.round(3)}ms #{mp_p50 < 20 ? 'PASS' : 'FAIL'}, " \
+     "p95 #{mp_p95.round(3)}ms #{mp_p95 < 20 ? 'PASS' : 'FAIL'})"
 
 # ----------------------------------------------------------------------------
-# Story 8.3 — standalone-host dispatch overhead (AC10).
-#
-# The standalone path SKIPS Rails' `process_action` callback chain + the
-# host controller allocation, so it can be slightly faster than the
-# controller-hosted JSON baseline OR slightly slower if the StandaloneContext
-# setup adds overhead. The AC10 band catches accidental 10× regressions
-# while accepting normal noise: 0.95× ≤ standalone_p50 / json_p50 ≤ 1.05×.
+# Query dispatch overhead — GET /q/<jsId> (a ruact_queries-mounted read).
 # ----------------------------------------------------------------------------
 
-standalone_counter = 0
-standalone_body_for = lambda do
-  standalone_counter += 1
-  { title: "Standalone Post #{standalone_counter}", body: "standalone body" }.to_json
-end
-
-post("/__ruact/fn/bench_action", standalone_body_for.call, headers)
-unless last_response.status == 200
-  raise "standalone dispatch broken (status=#{last_response.status} body=#{last_response.body})"
-end
+query_get = -> { get("/q/recent", {}, { "HTTP_ACCEPT" => "application/json" }) }
+query_get.call
+raise "query broken (status=#{last_response.status})" unless last_response.status == 200
 
-standalone_samples = sample_times(SAMPLES) { post("/__ruact/fn/bench_action", standalone_body_for.call, headers) }
-standalone_p50 = percentile(standalone_samples, 50) * 1000
-standalone_p95 = percentile(standalone_samples, 95) * 1000
-standalone_total_ms = (standalone_samples.sum * 1000).round(1)
-overhead_standalone_vs_json_p50 = (standalone_p50 - ruact_p50).round(3)
-standalone_factor = ruact_p50.zero? ? 0.0 : (standalone_p50 / ruact_p50).round(3)
+query_samples = sample_times(SAMPLES) { query_get.call }
+q_p50 = percentile(query_samples, 50) * 1000
+q_p95 = percentile(query_samples, 95) * 1000
+q_total_ms = (query_samples.sum * 1000).round(1)
 
 puts ""
-puts "#{SAMPLES} standalone-host requests (Story 8.3 — extend Ruact::ServerAction):"
-puts "  standalone dispatch:        total=#{standalone_total_ms}ms  p50=#{standalone_p50.round(3)}ms  p95=#{standalone_p95.round(3)}ms"
-puts "  vs. JSON controller baseline: #{'+' if overhead_standalone_vs_json_p50 >= 0}#{overhead_standalone_vs_json_p50}ms  (factor=#{standalone_factor}×)"
-puts ""
-puts "AC10 target: standalone median within 0.95×..1.05× of JSON baseline " \
-     "(#{(0.95..1.05).cover?(standalone_factor) ? 'PASS' : 'WARN — outside band; see results.md (laptop noise dominates; 10× is the regression alert)'})"
-
-# ----------------------------------------------------------------------------
-# Story 8.4 — error-path overhead.
-#
-# The new endpoint-level `rescue_from StandardError` chain only fires on the
-# unhappy path, so it does NOT touch the happy-path numbers above. This
-# section measures the rescue-from cost itself: an action that always raises
-# `RuntimeError("forced")` end-to-end through the new handler. Captures p50
-# and p95 of the error path so future regressions (e.g., adding an expensive
-# serializer step inside `ErrorPayload.build`) surface in nightly numbers.
-#
-# No regression assertion against the happy-path scenarios above — they're
-# untouched because the new chain only fires on raise.
-# ----------------------------------------------------------------------------
-
-class BenchController
-  ruact_action(:forced_failure) { |_params| raise "forced bench failure" }
-end
-
-# Warm-up — exercise the rescue_from chain once so the path is loaded.
-post("/__ruact/fn/forced_failure", "{}", headers)
-unless last_response.status == 500
-  raise "error-path warm-up did not return 500 (got status=#{last_response.status})"
-end
-
-forced_samples = sample_times(SAMPLES) { post("/__ruact/fn/forced_failure", "{}", headers) }
-forced_p50 = percentile(forced_samples, 50) * 1000
-forced_p95 = percentile(forced_samples, 95) * 1000
-forced_total_ms = (forced_samples.sum * 1000).round(1)
-forced_overhead_p50 = (forced_p50 - ruact_p50).round(3)
-
+puts "#{SAMPLES} query requests (GET /q/recent):"
+puts "  query dispatch:           total=#{q_total_ms}ms  p50=#{q_p50.round(3)}ms  p95=#{q_p95.round(3)}ms"
 puts ""
-puts "#{SAMPLES} error-path requests (Story 8.4 — rescue_from + ErrorPayload.build):"
-puts "  error-path dispatch:        total=#{forced_total_ms}ms  p50=#{forced_p50.round(3)}ms  p95=#{forced_p95.round(3)}ms"
-puts "  vs. JSON happy-path:        #{'+' if forced_overhead_p50 >= 0}#{forced_overhead_p50}ms  (informational only — no regression band)"
+puts "NFR21 target: query p50/p95 < 20 ms per call " \
+     "(p50 #{q_p50.round(3)}ms #{q_p50 < 20 ? 'PASS' : 'FAIL'}, " \
+     "p95 #{q_p95.round(3)}ms #{q_p95 < 20 ? 'PASS' : 'FAIL'})"

data/bench/server_functions_dispatch_bench.results.md

@@ -119,3 +119,32 @@ scenarios above are the load-bearing gates.
 If a future change pushes the error path above ~5 ms p50 without a clear
 reason (e.g., a backtrace-cleaning algorithmic regression, an expensive
 suggestion lookup, or a serialiser change), surface it for review.
+
+## Story 9.9 re-point (NFR21 — route-driven dispatch)
+
+The v1 synthetic endpoint + `ruact_action` DSL were demolished in Story 9.9, so
+the bench is re-pointed at REAL routes: a non-GET REST route (`POST /posts`) on a
+`include Ruact::Server` controller (Bucket-2 JSON), the multipart `<form action>`
+shape on a plain route, and a `ruact_queries`-mounted query route (`GET /q/recent`).
+
+NOTE (D2): the v2 path is a real Rails route through the full router + the
+`Ruact::Server` concern — a different code path than the deleted v1 synthetic
+endpoint, so the per-call delta vs. plain is NOT apples-to-apples with the v1
+baseline above. The honest NFR21 gate is "p50/p95 < 20 ms holds."
+
+| Metric | Value |
+| --- | --- |
+| Target | server-function dispatch p50/p95 < 20 ms per call |
+| Status | PASS |
+
+| Scenario | p50 | p95 |
+| --- | --- | --- |
+| `Ruact::Server` JSON dispatch (`POST /posts`, `Post.create!`) | ~0.79 ms | ~1.2 ms |
+| Plain controller action (same `Post.create!`) | ~0.78 ms | ~1.22 ms |
+| Per-call overhead (p50) | ~+0.01 ms | — |
+| Multipart (`<form action>` shape) | ~0.86 ms | ~1.37 ms |
+| Query (`GET /q/recent`, `ruact_queries`) | ~4.23 ms | ~5.90 ms |
+
+Local reference run (2026-06-15, rbenv Ruby 3.4.5, Rails 8.1, 1000 samples).
+The query path is heavier than the mutation path (it boots the gem's internal
+query dispatch controller + sanitizes params) but stays comfortably < 20 ms.