ruact 0.0.1 → 0.0.3

data/spec/ruact/query_request_spec.rb

@@ -0,0 +1,446 @@
+# frozen_string_literal: true
+
+# Story 9.4 — request-cycle spec for the v2 query dispatch layer, on the shared
+# Story-7.9 Rails app. Pins, against REAL drawn routes (manual fetch — no
+# codegen dependency; the TS `useQuery` reference is Story 9.5):
+#
+#   - AC1: `ruact_queries` draws one NAMED GET route per public own method at
+#     `GET /q/<jsIdentifier>`; base-class and mixin methods are NOT mounted
+#   - AC2: the internal dispatch controller inherits
+#     `Ruact.config.query_parent_controller` — the host's REAL before_action
+#     chain runs (and halts) BEFORE the query class is instantiated (FR89)
+#   - AC3: the query reads `current_user` — the host's own method — end-to-end
+#   - AC4: `ruact_skip_before_action` opts a query class out per-query; the
+#     skipped callback provably does not run
+#   - AC5: GET + no CSRF; return value serialized via ruact_props /
+#     Serializable / strict_serialization; a raise → salvaged 8.4 chain (D5)
+#   - AC6: `GET /q/categories` round-trips through the host chain end-to-end
+#   - D6: nil return renders JSON `null` (200); D7: best-effort kwargs
+
+require "action_controller/railtie"
+require "action_view/railtie"
+
+require "spec_helper"
+require "rack/test"
+
+require "ruact/controller"
+require "ruact/server"
+require "ruact/routing"
+
+require_relative "controller_request_spec" unless defined?(ControllerRequestSpecSupport)
+
+# The default `Ruact.config.query_parent_controller` is "ApplicationController"
+# — define the conventional host parent the generated dispatch controllers
+# inherit (AC2). Top-level on purpose: that is exactly what the default config
+# resolves at route-draw time. Guards + CSRF mirror a real host app.
+class ApplicationController < ActionController::Base
+  protect_from_forgery with: :exception
+
+  before_action :require_login
+
+  private
+
+  # Counts every run so AC4 can prove the skip means "did not run", not
+  # "ran and allowed".
+  def require_login
+    QueryRequestSpecSupport.require_login_runs += 1
+    head :unauthorized unless request.headers["X-Test-Login"] == "1"
+  end
+
+  # The host's own current_user (hand-rolled style, private) — what the
+  # QueryContext delegates to via the inherited chain (AC3 / D3).
+  def current_user
+    return nil unless request.headers["X-Test-Login"] == "1"
+
+    { "id" => 42, "name" => "Luiz" }
+  end
+end
+
+module QueryRequestSpecSupport # rubocop:disable Style/OneClassPerFile
+  class << self
+    attr_accessor :require_login_runs
+  end
+  self.require_login_runs = 0
+
+  # Serializable return object — :secret must never reach the wire (AC5).
+  class QPost
+    include Ruact::Serializable
+
+    attr_reader :id, :title, :secret
+
+    def initialize(id:, title:, secret:)
+      @id = id
+      @title = title
+      @secret = secret
+    end
+
+    ruact_props :id, :title
+  end
+
+  # Non-Serializable with as_json — strict_serialization must 500 it (AC5).
+  class LeakyRecord
+    def as_json(_opts = nil)
+      { "id" => 1, "leak" => "everything" }
+    end
+  end
+
+  # AC1 fixture trio: a base-class method, a mixin method, and own methods —
+  # only the own methods may be mounted.
+  class ApplicationQuery < Ruact::Query
+    def base_helper
+      :never_mounted
+    end
+  end
+
+  module QueryMixin
+    def mixin_helper
+      :never_mounted
+    end
+  end
+
+  class CatalogQuery < ApplicationQuery
+    include QueryMixin
+
+    class << self
+      attr_accessor :categories_calls
+    end
+    self.categories_calls = 0
+
+    def categories
+      self.class.categories_calls += 1
+      [{ "value" => 1, "label" => "Books" }, { "value" => 2, "label" => "Games" }]
+    end
+
+    def whoami
+      { "user" => current_user }
+    end
+
+    def echo(term: "default")
+      { "term" => term }
+    end
+
+    def serialized_post
+      QPost.new(id: 1, title: "Hi", secret: "s3cret")
+    end
+
+    def leaky
+      LeakyRecord.new
+    end
+
+    def nothing
+      nil
+    end
+
+    def boom
+      raise "query exploded"
+    end
+  end
+
+  # AC4 — public query class: opts out of the parent's auth callback.
+  class PublicCatalogQuery < ApplicationQuery
+    ruact_skip_before_action :require_login
+
+    def open_categories
+      %w[alpha beta]
+    end
+  end
+
+  # Probe class for unit-level assertions (custom parent / custom prefix) so
+  # rebuilding ITS controller never touches the classes the e2e routes use.
+  class ProbeQuery < ApplicationQuery
+    def ping
+      :pong
+    end
+  end
+
+  # Custom parent for the AC2 configurability unit assertion.
+  class AltParentController < ActionController::Base; end
+end
+
+if defined?(ControllerRequestSpecSupport) &&
+   !ControllerRequestSpecSupport.instance_variable_get(:@__ruact_query_routes_appended)
+  ControllerRequestSpecSupport.instance_variable_set(:@__ruact_query_routes_appended, true)
+  ControllerRequestSpecSupport.app_class.routes.append do
+    ruact_queries QueryRequestSpecSupport::CatalogQuery, QueryRequestSpecSupport::PublicCatalogQuery
+  end
+end
+
+RSpec.describe "Story 9.4: Ruact::Query + ruact_queries dispatch", :story_9_4 do
+  include Rack::Test::Methods
+
+  let(:app_class) { ControllerRequestSpecSupport.app_class }
+  let(:app)       { app_class.instance }
+
+  let(:login_headers) { { "HTTP_X_TEST_LOGIN" => "1" } }
+
+  before do
+    Rails.logger = Logger.new(IO::NULL)
+    ControllerRequestSpecSupport.boot!
+  end
+
+  def reset_config
+    Ruact.instance_variable_set(:@config, nil)
+    Ruact.instance_variable_set(:@configured_at_least_once, false)
+  end
+
+  describe "AC1 — ruact_queries draws one named GET route per public own method" do
+    let(:drawn) { app_class.routes.routes }
+    let(:named) { drawn.filter_map(&:name) }
+
+    it "mounts every public_instance_methods(false) of the subclass at /q/<jsIdentifier>" do
+      expect(named).to include(
+        "ruact_query_categories", "ruact_query_whoami", "ruact_query_echo",
+        "ruact_query_serializedPost", "ruact_query_leaky", "ruact_query_nothing",
+        "ruact_query_boom", "ruact_query_openCategories"
+      )
+    end
+
+    it "does NOT mount base-class methods, mixin methods, or the Ruact::Query accessors" do
+      expect(named).not_to include(
+        "ruact_query_baseHelper", "ruact_query_mixinHelper",
+        "ruact_query_currentUser", "ruact_query_params",
+        "ruact_query_request", "ruact_query_session"
+      )
+    end
+
+    it "draws GET routes under the default /q prefix, snake_case → camelCase (D4)" do
+      route = drawn.find { |r| r.name == "ruact_query_serializedPost" }
+      expect(route.verb).to eq("GET")
+      expect(route.path.spec.to_s).to eq("/q/serializedPost(.:format)")
+    end
+
+    it "honors a custom Ruact.config.query_route_prefix on a fresh draw (contract decision #7)" do
+      reset_config
+      Ruact.configure { |c| c.query_route_prefix = "/api/queries" }
+      route_set = ActionDispatch::Routing::RouteSet.new
+      route_set.draw { ruact_queries QueryRequestSpecSupport::ProbeQuery }
+      expect(route_set.routes.map { |r| r.path.spec.to_s }).to include("/api/queries/ping(.:format)")
+    end
+  end
+
+  describe "AC2 — dispatch controller inherits the host parent; chain runs BEFORE instantiation (FR89)" do
+    it "inherits Ruact.config.query_parent_controller (default ApplicationController)" do
+      controller = Ruact::ServerFunctions::QueryDispatch.controller_for(QueryRequestSpecSupport::CatalogQuery)
+      expect(controller.superclass).to be(ApplicationController)
+    end
+
+    it "honors a custom query_parent_controller" do
+      reset_config
+      Ruact.configure { |c| c.query_parent_controller = "QueryRequestSpecSupport::AltParentController" }
+      controller = Ruact::ServerFunctions::QueryDispatch.controller_for(QueryRequestSpecSupport::ProbeQuery)
+      expect(controller.superclass).to be(QueryRequestSpecSupport::AltParentController)
+    end
+
+    it "raises Ruact::ConfigurationError at route-draw when the parent name does not resolve" do
+      reset_config
+      Ruact.configure { |c| c.query_parent_controller = "NoSuchParentController" }
+      expect { Ruact::ServerFunctions::QueryDispatch.controller_for(QueryRequestSpecSupport::ProbeQuery) }
+        .to raise_error(Ruact::ConfigurationError, /NoSuchParentController.*does not resolve/m)
+    end
+
+    it "a halting before_action rejects the request and the query class is never instantiated" do
+      calls_before = QueryRequestSpecSupport::CatalogQuery.categories_calls
+      get "/q/categories"
+      expect(last_response.status).to eq(401)
+      expect(QueryRequestSpecSupport::CatalogQuery.categories_calls).to eq(calls_before)
+    end
+  end
+
+  describe "AC6 — GET /q/categories end-to-end through the host chain (manual fetch)" do
+    it "round-trips: 200, JSON content type, serialized return value" do
+      get "/q/categories", {}, login_headers
+      expect(last_response.status).to eq(200)
+      expect(last_response.headers["Content-Type"]).to include("application/json")
+      expect(JSON.parse(last_response.body)).to eq(
+        [{ "value" => 1, "label" => "Books" }, { "value" => 2, "label" => "Games" }]
+      )
+    end
+  end
+
+  describe "AC3 — current_user delegates to the host's own (private) method" do
+    it "the query reads the authenticated user end-to-end" do
+      get "/q/whoami", {}, login_headers
+      expect(last_response.status).to eq(200)
+      expect(JSON.parse(last_response.body)).to eq("user" => { "id" => 42, "name" => "Luiz" })
+    end
+  end
+
+  describe "AC4 — per-query callback opt-out (ruact_skip_before_action)" do
+    it "without the opt-out, the unauthenticated request is rejected (control)" do
+      get "/q/categories"
+      expect(last_response.status).to eq(401)
+    end
+
+    it "with the opt-out, the skipped callback does NOT run and the query returns" do
+      runs_before = QueryRequestSpecSupport.require_login_runs
+      get "/q/openCategories"
+      expect(last_response.status).to eq(200)
+      expect(JSON.parse(last_response.body)).to eq(%w[alpha beta])
+      expect(QueryRequestSpecSupport.require_login_runs).to eq(runs_before)
+    end
+
+    it "the opt-out does not leak to sibling query classes" do
+      get "/q/whoami"
+      expect(last_response.status).to eq(401)
+    end
+  end
+
+  describe "AC5 — GET, no CSRF, serialized return value, error chain" do
+    it "a tokenless GET succeeds despite protect_from_forgery with: :exception (queries are reads)" do
+      get "/q/categories", {}, login_headers
+      expect(last_response.status).to eq(200)
+    end
+
+    it "serializes a Serializable return through ruact_props — :secret never leaks" do
+      get "/q/serializedPost", {}, login_headers
+      body = JSON.parse(last_response.body)
+      expect(body).to eq("id" => 1, "title" => "Hi")
+      expect(body).not_to have_key("secret")
+    end
+
+    it "under strict_serialization, a non-Serializable return → structured 500 (SerializationError)" do
+      reset_config
+      Ruact.configure { |c| c.strict_serialization = true }
+      get "/q/leaky", {}, login_headers
+      expect(last_response.status).to eq(500)
+      body = JSON.parse(last_response.body)
+      expect(body.fetch("_ruact_server_action_error")).to be(true)
+      expect(body.fetch("error_class")).to eq("Ruact::SerializationError")
+      expect(body.fetch("message")).to match(/Cannot serialize QueryRequestSpecSupport::LeakyRecord/)
+    end
+
+    it "a query raise renders the salvaged 8.4 structured payload on a GET (D5 gate override)" do
+      get "/q/boom", {}, login_headers
+      expect(last_response.status).to eq(500)
+      body = JSON.parse(last_response.body)
+      expect(body.fetch("_ruact_server_action_error")).to be(true)
+      expect(body.fetch("action_name")).to eq("boom")
+      expect(body.fetch("error_class")).to eq("RuntimeError")
+      expect(body.fetch("message")).to eq("query exploded")
+    end
+  end
+
+  describe "D6 — nil return renders JSON null (200), not 204" do
+    it "renders the literal null body" do
+      get "/q/nothing", {}, login_headers
+      expect(last_response.status).to eq(200)
+      expect(last_response.body).to eq("null")
+    end
+  end
+
+  describe "D7 — best-effort kwargs from GET query params (strict FR88 sanitization is 9.5)" do
+    it "passes a declared keyword argument by name" do
+      get "/q/echo?term=ruby", {}, login_headers
+      expect(JSON.parse(last_response.body)).to eq("term" => "ruby")
+    end
+
+    it "omits an absent keyword so the method default applies" do
+      get "/q/echo", {}, login_headers
+      expect(JSON.parse(last_response.body)).to eq("term" => "default")
+    end
+  end
+
+  describe "review round 1 — query method names colliding with controller plumbing are rejected" do
+    it "raises Ruact::ConfigurationError when a query method would shadow a framework method" do
+      shadowing = Class.new(Ruact::Query) do
+        def params
+          :shadowed
+        end
+      end
+      stub_const("QueryRequestSpecSupport::ParamsShadowQuery", shadowing)
+      expect { Ruact::ServerFunctions::QueryDispatch.controller_for(shadowing) }
+        .to raise_error(Ruact::ConfigurationError, /\bparams\b.*already defined/m)
+    end
+
+    it "rejects `render` too (any name on the generated controller chain)" do
+      shadowing = Class.new(Ruact::Query) do
+        def render
+          :shadowed
+        end
+      end
+      stub_const("QueryRequestSpecSupport::RenderShadowQuery", shadowing)
+      expect { Ruact::ServerFunctions::QueryDispatch.controller_for(shadowing) }
+        .to raise_error(Ruact::ConfigurationError, /\brender\b.*already defined/m)
+    end
+  end
+
+  describe "review round 4 — namespace is PRESERVED so collisions are impossible by construction" do
+    it "maps Admin::CatalogQuery and AdminCatalogQuery to DISTINCT controllers + route targets" do
+      namespaced = Class.new(Ruact::Query) { def ping_a = :a }
+      flat       = Class.new(Ruact::Query) { def ping_b = :b }
+      stub_const("QueryRequestSpecSupport::Nspace::CatalogQuery", namespaced)
+      stub_const("QueryRequestSpecSupport::NspaceCatalogQuery", flat)
+
+      c1 = Ruact::ServerFunctions::QueryDispatch.controller_for(namespaced)
+      c2 = Ruact::ServerFunctions::QueryDispatch.controller_for(flat)
+
+      # Every namespace segment is preserved (`::Nspace::CatalogQuery` keeps the
+      # boundary; `NspaceCatalogQuery` has no boundary) — the two map to
+      # DISTINCT nested constants, so a const overwrite / cross-wire is
+      # impossible regardless of how many RouteSets share the dispatch module.
+      expect(c1).not_to be(c2)
+      expect(c1.name).to eq(
+        "Ruact::ServerFunctions::QueryDispatch::QueryRequestSpecSupport::Nspace::CatalogQueryController"
+      )
+      expect(c2.name).to eq(
+        "Ruact::ServerFunctions::QueryDispatch::QueryRequestSpecSupport::NspaceCatalogQueryController"
+      )
+      expect(Ruact::ServerFunctions::QueryDispatch.route_target_for(namespaced))
+        .to eq("ruact/server_functions/query_dispatch/query_request_spec_support/nspace/catalog_query")
+      expect(Ruact::ServerFunctions::QueryDispatch.route_target_for(flat))
+        .to eq("ruact/server_functions/query_dispatch/query_request_spec_support/nspace_catalog_query")
+    end
+
+    it "mounts both on the same RouteSet without error, each routing to its own class (no cross-wiring)" do
+      namespaced = Class.new(Ruact::Query) { def from_ns = "ns" }
+      flat       = Class.new(Ruact::Query) { def from_flat = "flat" }
+      stub_const("QueryRequestSpecSupport::Pair::TwinQuery", namespaced)
+      stub_const("QueryRequestSpecSupport::PairTwinQuery", flat)
+
+      route_set = ActionDispatch::Routing::RouteSet.new
+      expect do
+        route_set.draw do
+          ruact_queries namespaced
+          ruact_queries flat
+        end
+      end.not_to raise_error
+
+      targets = route_set.routes.filter_map { |r| r.defaults[:controller] }
+      expect(targets).to include(
+        "ruact/server_functions/query_dispatch/query_request_spec_support/pair/twin_query",
+        "ruact/server_functions/query_dispatch/query_request_spec_support/pair_twin_query"
+      )
+    end
+
+    it "round-trips acronym namespaces so Rails resolves the generated controller (round 5)" do
+      acro = Class.new(Ruact::Query) { def ping_e = :e }
+      stub_const("QueryRequestSpecSupport::APIProbe::CatalogQuery", acro)
+
+      controller = Ruact::ServerFunctions::QueryDispatch.controller_for(acro)
+      target = Ruact::ServerFunctions::QueryDispatch.route_target_for(acro)
+      # Exactly how Rails' dispatcher resolves a "controller#action" target.
+      resolved = "#{target.camelize}Controller".constantize
+
+      expect(resolved).to be(controller)
+      expect(target).to eq(
+        "ruact/server_functions/query_dispatch/query_request_spec_support/api_probe/catalog_query"
+      )
+    end
+
+    it "the SAME class re-mounting (dev reload) is still allowed" do
+      expect do
+        Ruact::ServerFunctions::QueryDispatch.controller_for(QueryRequestSpecSupport::ProbeQuery)
+        Ruact::ServerFunctions::QueryDispatch.controller_for(QueryRequestSpecSupport::ProbeQuery)
+      end.not_to raise_error
+    end
+  end
+
+  describe "regeneration is idempotent (dev-mode routes reload)" do
+    it "controller_for builds a fresh class on every call without const warnings" do
+      first  = Ruact::ServerFunctions::QueryDispatch.controller_for(QueryRequestSpecSupport::ProbeQuery)
+      second = Ruact::ServerFunctions::QueryDispatch.controller_for(QueryRequestSpecSupport::ProbeQuery)
+      expect(second).not_to be(first)
+      expect(second.superclass).to be(ApplicationController)
+    end
+  end
+end

data/spec/ruact/query_spec.rb

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+# Story 9.4 — unit spec for the Ruact::Query base class. Deliberately NO Rails
+# boot (AC3): a query subclass is exercised with a plain double standing in for
+# the dispatch context, proving `CatalogQuery.new(fake_context).categories` is
+# unit-testable in isolation.
+require "spec_helper"
+
+module Ruact
+  RSpec.describe Query, :story_9_4 do
+    let(:fake_user) { { "id" => 42 } }
+    let(:fake_params) { { "q" => "ruby" } }
+    let(:fake_request) { instance_double(Object) }
+    let(:fake_session) { { "token" => "abc" } }
+    let(:context) do
+      double(
+        current_user: fake_user,
+        params: fake_params,
+        request: fake_request,
+        session: fake_session
+      )
+    end
+
+    let(:query_class) do
+      Class.new(described_class) do
+        def categories
+          %w[books games]
+        end
+
+        def whoami
+          current_user
+        end
+
+        def search
+          params["q"]
+        end
+      end
+    end
+
+    describe "Story 9.4 — context accessors delegate to the injected context (AC3)" do
+      subject(:query) { query_class.new(context) }
+
+      it "exposes current_user from the context" do
+        expect(query.whoami).to eq(fake_user)
+      end
+
+      it "exposes params from the context" do
+        expect(query.search).to eq("ruby")
+      end
+
+      it "exposes request from the context" do
+        expect(query.request).to be(fake_request)
+      end
+
+      it "exposes session from the context" do
+        expect(query.session).to eq(fake_session)
+      end
+
+      it "is unit-testable with a plain fake context and no Rails boot (AC3)" do
+        expect(query_class.new(context).categories).to eq(%w[books games])
+      end
+    end
+
+    describe "Story 9.4 — accessor methods are inherited, never own methods of the subclass (AC1)" do
+      it "keeps current_user/params/request/session OUT of the subclass's public_instance_methods(false)" do
+        own = query_class.public_instance_methods(false)
+        expect(own).to contain_exactly(:categories, :whoami, :search)
+      end
+
+      it "defines the accessors on Ruact::Query itself (inherited by every subclass)" do
+        expect(described_class.public_instance_methods(false))
+          .to include(:current_user, :params, :request, :session)
+      end
+    end
+
+    describe "Story 9.4 — ruact_skip_before_action class macro (AC4 / D1)" do
+      it "records the callback with its options on the query class" do
+        klass = Class.new(described_class)
+        klass.ruact_skip_before_action(:require_login, only: :categories)
+        expect(klass.__ruact_skipped_callbacks).to eq([[[:require_login], { only: :categories }]])
+      end
+
+      it "accepts multiple callbacks in one call, mirroring Rails' skip_before_action" do
+        klass = Class.new(described_class)
+        klass.ruact_skip_before_action(:require_login, :check_tenant)
+        expect(klass.__ruact_skipped_callbacks).to eq([[%i[require_login check_tenant], {}]])
+      end
+
+      it "accumulates across calls in declaration order" do
+        klass = Class.new(described_class)
+        klass.ruact_skip_before_action(:require_login)
+        klass.ruact_skip_before_action(:check_tenant, raise: false)
+        expect(klass.__ruact_skipped_callbacks)
+          .to eq([[[:require_login], {}], [[:check_tenant], { raise: false }]])
+      end
+
+      it "keeps the recorded skips per-class — sibling query classes never share them" do
+        klass_a = Class.new(described_class)
+        klass_b = Class.new(described_class)
+        klass_a.ruact_skip_before_action(:require_login)
+        expect(klass_b.__ruact_skipped_callbacks).to be_empty
+      end
+    end
+  end
+end

data/spec/ruact/railtie_spec.rb

@@ -107,9 +107,8 @@ RSpec.describe Ruact::Railtie do
     end
 
     context "with missing manifest in production (AC#6)" do
-      before do
-        Rails.env = ActiveSupport::StringInquirer.new("production")
-      end
+      before { Rails.env = ActiveSupport::StringInquirer.new("production") }
+      after  { Rails.env = ActiveSupport::StringInquirer.new("development") }
 
       it "raises ManifestError" do
         expect { described_class.check_manifest!(missing_path) }

data/spec/ruact/render_context_spec.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+require "spec_helper"
+
+module Ruact
+  RSpec.describe RenderContext do
+    subject(:ctx) { described_class.new }
+
+    describe "#register" do
+      it "appends a new component entry" do
+        ctx.register("NavBar", { "currentUser" => 1 })
+        expect(ctx.components.length).to eq(1)
+        expect(ctx.components.first[:name]).to eq("NavBar")
+        expect(ctx.components.first[:props]).to eq({ "currentUser" => 1 })
+      end
+
+      it "returns a token of the form __RUACT_<index>__" do
+        token = ctx.register("Foo", {})
+        expect(token).to eq("__RUACT_0__")
+      end
+
+      it "increments token indices across successive registrations" do
+        t0 = ctx.register("A", {})
+        t1 = ctx.register("B", {})
+        t2 = ctx.register("C", {})
+        expect([t0, t1, t2]).to eq(%w[__RUACT_0__ __RUACT_1__ __RUACT_2__])
+      end
+    end
+
+    describe "#components" do
+      it "starts empty" do
+        expect(ctx.components).to eq([])
+      end
+    end
+
+    describe "#by_token" do
+      it "finds a registered component by its token" do
+        ctx.register("NavBar", { "x" => 1 })
+        entry = ctx.by_token("__RUACT_0__")
+        expect(entry[:name]).to eq("NavBar")
+      end
+
+      it "returns nil for an unknown token" do
+        expect(ctx.by_token("__RUACT_99__")).to be_nil
+      end
+    end
+
+    describe "isolation" do
+      it "two contexts are independent" do
+        a = described_class.new
+        b = described_class.new
+        a.register("A", {})
+        expect(b.components).to be_empty
+        expect(a.components.length).to eq(1)
+      end
+    end
+  end
+end