ruact 0.0.1 → 0.0.3

data/spec/ruact/server_functions/standalone_action_spec.rb

@@ -0,0 +1,224 @@
+# frozen_string_literal: true
+
+# Story 8.3 — covers `Ruact::ServerAction` extended onto a Module: AC1
+# (registration shape + no method defined on host module) and AC6 (guard-
+# rail matrix mirroring the controller-DSL path adapted to module context).
+
+require "spec_helper"
+
+RSpec.describe Ruact::ServerAction, :story_8_3 do
+  describe "AC1 — extend Ruact::ServerAction + ruact_action registers a standalone host" do
+    it "registers a standalone host in Ruact.action_registry with controller: <the Module>" do
+      mod = Module.new do
+        extend Ruact::ServerAction
+
+        def self.name
+          "AC1RegistrationModule"
+        end
+
+        ruact_action(:standalone_create_post) { |_params| { ok: true } }
+      end
+
+      entries = Ruact.action_registry.entries
+      expect(entries).to include(:standalone_create_post)
+
+      entry = entries[:standalone_create_post]
+      expect(entry).to be_a(Ruact::ServerFunctions::RegistryEntry)
+      expect(entry.kind).to eq(:action)
+      expect(entry.controller).to be(mod)
+      expect(entry.controller).to be_a(Module)
+      expect(entry.controller).not_to be_a(Class)
+      expect(entry.js_identifier).to eq("standaloneCreatePost")
+      expect(entry.block).to be_a(Proc)
+    end
+
+    it "does NOT define an instance method on the host module — the block is reachable " \
+       "only through the gem endpoint, never as a Ruby method" do
+      mod = Module.new do
+        extend Ruact::ServerAction
+
+        def self.name
+          "AC1NoMethodModule"
+        end
+
+        ruact_action(:no_method_exposed) { |_params| nil }
+      end
+
+      expect(mod.respond_to?(:no_method_exposed)).to be(false)
+      expect(mod.instance_methods).not_to include(:no_method_exposed)
+      expect(mod.singleton_methods).not_to include(:no_method_exposed)
+      # Direct dispatch attempts (someone trying to `Mod.send(:no_method_exposed)`
+      # should fail with NoMethodError) — proves the surface is endpoint-only.
+      expect { mod.send(:no_method_exposed, {}) }.to raise_error(NoMethodError)
+    end
+  end
+
+  describe "AC6 — guard-rail matrix (mirror controller-DSL adapted to module context)" do
+    let(:host) do
+      Module.new do
+        extend Ruact::ServerAction
+
+        def self.name
+          "GuardRailModule"
+        end
+      end
+    end
+
+    it "raises ArgumentError when given a String instead of a Symbol" do
+      expect do
+        host.module_eval { ruact_action("create_post") { |_p| nil } }
+      end.to raise_error(ArgumentError, /ruact_action requires a Symbol/)
+    end
+
+    it "raises ArgumentError when the block is missing" do
+      expect { host.module_eval { ruact_action(:create_post) } }
+        .to raise_error(ArgumentError, /requires a block/)
+    end
+
+    it "raises ArgumentError when the block accepts no positional argument" do
+      expect do
+        host.module_eval { ruact_action(:create_post) {} } # no positional arg
+      end.to raise_error(ArgumentError, /exactly one positional parameter/)
+    end
+
+    it "raises ArgumentError when the block accepts more than one positional argument" do
+      expect do
+        host.module_eval { ruact_action(:create_post) { |_a, _b| nil } }
+      end.to raise_error(ArgumentError, /exactly one positional parameter/)
+    end
+
+    it "raises ArgumentError when the block has a required keyword argument" do
+      block_with_kwarg = ->(_p, required:) { required }
+      expect do
+        host.module_eval { ruact_action(:create_post, &block_with_kwarg) }
+      end.to raise_error(ArgumentError, /no required keyword arguments/)
+    end
+
+    it "ACCEPTS a block with a single positional arg" do
+      expect do
+        host.module_eval { ruact_action(:create_post) { |_p| nil } }
+      end.not_to raise_error
+    end
+
+    it "ACCEPTS a block with a splat positional arg" do
+      another_host = Module.new do
+        extend Ruact::ServerAction
+
+        def self.name
+          "SplatHost"
+        end
+      end
+      expect do
+        another_host.module_eval { ruact_action(:create_post) { |*_args| nil } }
+      end.not_to raise_error
+    end
+
+    it "ACCEPTS a block with optional keyword args" do
+      another_host = Module.new do
+        extend Ruact::ServerAction
+
+        def self.name
+          "OptKwHost"
+        end
+      end
+      expect do
+        another_host.module_eval { ruact_action(:create_post) { |_p, key: nil| key } }
+      end.not_to raise_error
+    end
+
+    it "raises Ruact::ConfigurationError for a bad naming-bridge symbol (:Create_Post)" do
+      expect do
+        host.module_eval { ruact_action(:Create_Post) { |_p| nil } }
+      end.to raise_error(Ruact::ConfigurationError) do |error|
+        expect(error.message).to include(":Create_Post")
+        expect(error.message).to include("GuardRailModule")
+      end
+    end
+
+    it "raises Ruact::ConfigurationError for a JS-reserved-word target (:class → \"class\")" do
+      expect do
+        host.module_eval { ruact_action(:class) { |_p| nil } }
+      end.to raise_error(Ruact::ConfigurationError, /JS reserved word/)
+    end
+
+    it "raises Ruact::ConfigurationError for a ruact-runtime-reserved target (:revalidate)" do
+      expect do
+        host.module_eval { ruact_action(:revalidate) { |_p| nil } }
+      end.to raise_error(Ruact::ConfigurationError) do |error|
+        expect(error.message).to include("revalidate")
+      end
+    end
+
+    it "raises Ruact::ConfigurationError for the second standalone host declaring the same symbol" do
+      host.module_eval { ruact_action(:dup_symbol) { |_p| nil } }
+      second_host = Module.new do
+        extend Ruact::ServerAction
+
+        def self.name
+          "SecondHostModule"
+        end
+      end
+      expect do
+        second_host.module_eval { ruact_action(:dup_symbol) { |_p| nil } }
+      end.to raise_error(Ruact::ConfigurationError) do |error|
+        expect(error.message).to include(":dup_symbol")
+        expect(error.message).to include("GuardRailModule")
+        expect(error.message).to include("SecondHostModule")
+      end
+    end
+
+    it "does NOT have a FRAMEWORK_RESERVED_METHODS check — standalone modules can use " \
+       "names that would clobber an ActionController method (e.g., :params), since the " \
+       "module has no ActionController surface" do
+      expect do
+        Module.new do
+          extend Ruact::ServerAction
+
+          def self.name
+            "FrameworkResvHost"
+          end
+
+          ruact_action(:params) { |_p| nil }
+        end
+      end.not_to raise_error
+    end
+
+    it "Story 8.3 review R4 — rejects Class hosts at first ruact_action call with a " \
+       "documented Ruact::ConfigurationError pointing the dev to `include Ruact::Controller`" do
+      klass = Class.new do
+        extend Ruact::ServerAction
+
+        def self.name
+          "WronglyExtendedClass"
+        end
+      end
+
+      expect do
+        klass.class_eval { ruact_action(:bad_host) { |_p| nil } }
+      end.to raise_error(Ruact::ConfigurationError) do |error|
+        expect(error.message).to include("WronglyExtendedClass")
+        expect(error.message).to include("standalone HOST MODULES")
+        expect(error.message).to include("include Ruact::Controller")
+      end
+    end
+
+    it "does NOT install a method_added hook — a later `def` on the host module does not " \
+       "raise (standalone modules don't define action methods at all)" do
+      expect do
+        Module.new do
+          extend Ruact::ServerAction
+
+          def self.name
+            "MethodAddedHost"
+          end
+
+          ruact_action(:registered_action) { |_p| nil }
+
+          # A later method definition on the module would not trigger anything
+          # — the registry holds the block; the module surface is irrelevant.
+          define_method(:registered_action) { :unrelated_def }
+        end
+      end.not_to raise_error
+    end
+  end
+end

data/spec/ruact/server_functions/standalone_context_spec.rb

@@ -0,0 +1,142 @@
+# frozen_string_literal: true
+
+# Story 8.3 — `Ruact::ServerFunctions::StandaloneContext`: AC3 surface
+# (exposes params/request/session/cookies/headers; render/redirect_to/head
+# raise NoMethodError; current_user memoizes + falls back to env key +
+# raises CurrentUserNotConfiguredError when neither path produces a value).
+
+require "spec_helper"
+require "action_controller"
+require "action_dispatch"
+
+module Ruact
+  module ServerFunctions
+    RSpec.describe StandaloneContext, :story_8_3 do
+      let(:env) { {} }
+      let(:request) do
+        ActionDispatch::Request.new(env.merge(
+                                      "REQUEST_METHOD" => "POST",
+                                      "rack.input" => StringIO.new("")
+                                    ))
+      end
+      let(:params) { ActionController::Parameters.new("title" => "Hello") }
+      let(:context) { described_class.new(params: params, request: request) }
+
+      describe "exposed surface (AC3)" do
+        it "exposes params (the action-call args, as ActionController::Parameters)" do
+          expect(context.params).to be_a(ActionController::Parameters)
+          expect(context.params[:title]).to eq("Hello")
+        end
+
+        it "exposes the live request" do
+          expect(context.request).to be(request)
+        end
+
+        it "exposes headers via request.headers" do
+          expect(context.headers).to be(request.headers)
+        end
+      end
+
+      describe "blocked surface — render / redirect_to / head (AC3)" do
+        it "render raises NoMethodError with the documented hint" do
+          expect { context.render(json: { ok: true }) }
+            .to raise_error(NoMethodError, /does not expose `render`/)
+        end
+
+        it "redirect_to raises NoMethodError with the documented hint" do
+          expect { context.redirect_to("/login") }
+            .to raise_error(NoMethodError, /does not expose `redirect_to`/)
+        end
+
+        it "head raises NoMethodError with the documented hint" do
+          expect { context.head(:no_content) }
+            .to raise_error(NoMethodError, /does not expose `head`/)
+        end
+      end
+
+      describe "current_user resolver path (AC3)" do
+        around do |example|
+          Ruact.instance_variable_set(:@config, nil)
+          Ruact.instance_variable_set(:@configured_at_least_once, false)
+          example.run
+        ensure
+          Ruact.instance_variable_set(:@config, nil)
+          Ruact.instance_variable_set(:@configured_at_least_once, false)
+        end
+
+        before do
+          # Silence the warn-on-reconfigure noise.
+          allow(Rails).to receive(:logger).and_return(Logger.new(IO::NULL))
+        end
+
+        it "raises Ruact::CurrentUserNotConfiguredError when no resolver is configured AND no env key is set" do
+          expect { context.current_user }.to raise_error(Ruact::CurrentUserNotConfiguredError) do |err|
+            expect(err.message).to include("Ruact.current_user requires Ruact.config.current_user_resolver")
+            expect(err.message).to include("Devise")
+            expect(err.message).to include("hand-rolled session")
+          end
+        end
+
+        it "returns the configured resolver's value, passing request.env to the lambda" do
+          user = Struct.new(:id).new(42)
+          Ruact.configure do |c|
+            c.current_user_resolver = lambda { |env_arg|
+              expect(env_arg).to be(request.env)
+              user
+            }
+          end
+          expect(context.current_user).to be(user)
+        end
+
+        it "memoizes current_user across multiple calls (resolver invoked once)" do
+          call_count = 0
+          Ruact.configure do |c|
+            c.current_user_resolver = lambda { |_env|
+              call_count += 1
+              :user
+            }
+          end
+          context.current_user
+          context.current_user
+          context.current_user
+          expect(call_count).to eq(1)
+        end
+
+        it "prefers an upstream-set request.env['ruact.current_user'] over the resolver" do
+          env["ruact.current_user"] = :upstream_user
+          resolver_called = false
+          Ruact.configure do |c|
+            c.current_user_resolver = lambda { |_env|
+              resolver_called = true
+              :resolver_user
+            }
+          end
+          expect(context.current_user).to eq(:upstream_user)
+          expect(resolver_called).to be(false)
+        end
+
+        it "falls back to the resolver when the env key is absent (not just nil)" do
+          # Pitfall: env.key? differs from env.fetch — a `nil` value should still
+          # prefer the env path. Verify by setting nil explicitly.
+          env["ruact.current_user"] = nil
+          Ruact.configure do |c|
+            c.current_user_resolver = ->(_env) { :resolver_user }
+          end
+          expect(context.current_user).to be_nil
+        end
+      end
+
+      describe "__ruact_current_user_read? (Pitfall #4 dev warning flag)" do
+        it "is false when the block never reads current_user" do
+          expect(context.__ruact_current_user_read?).to be(false)
+        end
+
+        it "flips to true when the block reads current_user" do
+          Ruact.configure { |c| c.current_user_resolver = ->(_env) { :u } }
+          context.current_user
+          expect(context.__ruact_current_user_read?).to be(true)
+        end
+      end
+    end
+  end
+end

data/spec/ruact/server_functions/standalone_dispatcher_spec.rb

@@ -0,0 +1,273 @@
+# frozen_string_literal: true
+
+# Story 8.3 — `Ruact::ServerFunctions::StandaloneDispatcher`: AC2 + AC3
+# dispatch shape: JSON / multipart / URL-encoded bodies; nil → 204; Hash →
+# 200 JSON; Array → 200 JSON; `Ruact::ActionError` → status + body; unknown
+# content-type → empty params; params shadow is `ActionController::Parameters`.
+
+require "spec_helper"
+require "action_controller"
+require "action_dispatch"
+require "rack"
+require "securerandom"
+
+module Ruact
+  module ServerFunctions
+    RSpec.describe StandaloneDispatcher, :story_8_3 do
+      let(:posts_module) do
+        Module.new do
+          extend Ruact::ServerAction
+
+          def self.name
+            "StandaloneDispatcherHost"
+          end
+        end
+      end
+
+      def make_request(body:, content_type:)
+        env = Rack::MockRequest.env_for(
+          "/__ruact/fn/whatever",
+          method: "POST",
+          input: body,
+          "CONTENT_TYPE" => content_type
+        )
+        ActionDispatch::Request.new(env)
+      end
+
+      def make_response
+        ActionDispatch::Response.new.tap do |resp|
+          # Touch the response so its internal state is initialized.
+          resp.request = nil
+        end
+      end
+
+      def register_and_entry(symbol, &block)
+        posts_module.module_eval { ruact_action(symbol, &block) }
+        Ruact.action_registry.entries[symbol]
+      end
+
+      describe "AC2 — content-type routing into params shadow" do
+        it "parses application/json bodies" do
+          entry = register_and_entry(:json_echo, &:to_unsafe_h)
+          request = make_request(body: '{"title":"Hi"}', content_type: "application/json")
+          response = make_response
+
+          described_class.dispatch(entry, request, response)
+
+          expect(response.status).to eq(200)
+          expect(response.headers["Content-Type"]).to include("application/json")
+          expect(JSON.parse(response.body)).to eq("title" => "Hi")
+        end
+
+        it "parses multipart/form-data bodies (Story 8.3 review R5 — AC9 multipart coverage)" do
+          # Hand-build a multipart body so the dispatcher exercises the same
+          # `request.request_parameters` path the runtime's `<form action>`
+          # wire shape produces. Mirrors the `multipart_post` helper in
+          # dispatch_request_spec.rb.
+          boundary = "----RuactDispatcherSpec#{SecureRandom.hex(8)}"
+          body = +""
+          body << "--#{boundary}\r\n"
+          body << "Content-Disposition: form-data; name=\"title\"\r\n\r\n"
+          body << "From multipart\r\n"
+          body << "--#{boundary}\r\n"
+          body << "Content-Disposition: form-data; name=\"body\"\r\n\r\n"
+          body << "Multipart body\r\n"
+          body << "--#{boundary}--\r\n"
+
+          entry = register_and_entry(:multipart_echo, &:to_unsafe_h)
+          request = make_request(body: body, content_type: "multipart/form-data; boundary=#{boundary}")
+          response = make_response
+
+          described_class.dispatch(entry, request, response)
+
+          expect(response.status).to eq(200)
+          expect(JSON.parse(response.body)).to eq(
+            "title" => "From multipart",
+            "body" => "Multipart body"
+          )
+        end
+
+        it "parses application/x-www-form-urlencoded bodies" do
+          entry = register_and_entry(:form_echo, &:to_unsafe_h)
+          request = make_request(
+            body: "title=Hello&body=World",
+            content_type: "application/x-www-form-urlencoded"
+          )
+          response = make_response
+
+          described_class.dispatch(entry, request, response)
+
+          expect(response.status).to eq(200)
+          expect(JSON.parse(response.body)).to eq("title" => "Hello", "body" => "World")
+        end
+
+        it "returns an empty params hash for unknown content types" do
+          entry = register_and_entry(:unknown_ct) { |params| { "keys" => params.to_unsafe_h.keys } }
+          request = make_request(body: "ignored", content_type: "application/xml")
+          response = make_response
+
+          described_class.dispatch(entry, request, response)
+
+          expect(response.status).to eq(200)
+          expect(JSON.parse(response.body)).to eq("keys" => [])
+        end
+
+        it "treats an empty JSON body as an empty hash" do
+          entry = register_and_entry(:empty_json, &:to_unsafe_h)
+          request = make_request(body: "", content_type: "application/json")
+          response = make_response
+
+          described_class.dispatch(entry, request, response)
+
+          expect(response.status).to eq(200)
+          expect(JSON.parse(response.body)).to eq({})
+        end
+
+        it "wraps a scalar JSON top-level value under the `_value` key (mirrors controller path)" do
+          entry = register_and_entry(:scalar_json) { |params| { value: params[:_value] } }
+          request = make_request(body: "42", content_type: "application/json")
+          response = make_response
+
+          described_class.dispatch(entry, request, response)
+
+          expect(response.status).to eq(200)
+          expect(JSON.parse(response.body)).to eq("value" => 42)
+        end
+
+        it "exposes the params shadow as ActionController::Parameters (strong params API)" do
+          entry = register_and_entry(:strong) do |params|
+            permitted = params.require(:post).permit(:title)
+            { "permitted" => permitted.to_h }
+          end
+          request = make_request(
+            body: '{"post":{"title":"Hi","evil":"ignored"}}',
+            content_type: "application/json"
+          )
+          response = make_response
+
+          described_class.dispatch(entry, request, response)
+
+          expect(response.status).to eq(200)
+          expect(JSON.parse(response.body)).to eq("permitted" => { "title" => "Hi" })
+        end
+      end
+
+      describe "AC2 — response shape" do
+        it "renders 204 No Content when the block returns nil" do
+          entry = register_and_entry(:nil_return) { |_params| nil }
+          request = make_request(body: "{}", content_type: "application/json")
+          response = make_response
+
+          described_class.dispatch(entry, request, response)
+
+          expect(response.status).to eq(204)
+          expect(response.body.to_s).to eq("")
+        end
+
+        it "renders 200 + JSON when the block returns a Hash" do
+          entry = register_and_entry(:hash_return) { |_params| { ok: true } }
+          request = make_request(body: "{}", content_type: "application/json")
+          response = make_response
+
+          described_class.dispatch(entry, request, response)
+
+          expect(response.status).to eq(200)
+          expect(JSON.parse(response.body)).to eq("ok" => true)
+        end
+
+        it "renders 200 + JSON when the block returns an Array" do
+          entry = register_and_entry(:array_return) { |_params| [1, 2, 3] }
+          request = make_request(body: "{}", content_type: "application/json")
+          response = make_response
+
+          described_class.dispatch(entry, request, response)
+
+          expect(response.status).to eq(200)
+          expect(JSON.parse(response.body)).to eq([1, 2, 3])
+        end
+
+        it "renders 200 + JSON when the block returns a scalar" do
+          entry = register_and_entry(:string_return) { |_params| "pong" }
+          request = make_request(body: "{}", content_type: "application/json")
+          response = make_response
+
+          described_class.dispatch(entry, request, response)
+
+          expect(response.status).to eq(200)
+          expect(JSON.parse(response.body)).to eq("pong")
+        end
+      end
+
+      describe "Story 8.3 review R3 — malformed JSON → structured 400" do
+        it "renders 400 + JSON {error} when the JSON body is malformed " \
+           "(parity with the controller-DSL path's malformed-JSON handler)" do
+          entry = register_and_entry(:malformed_demo) { |_p| { ok: true } }
+          request = make_request(body: "{ not json", content_type: "application/json")
+          response = make_response
+
+          described_class.dispatch(entry, request, response)
+
+          expect(response.status).to eq(400)
+          body = JSON.parse(response.body)
+          expect(body.fetch("error")).to match(/ruact action :malformed_demo received malformed JSON body/)
+        end
+
+        it "does NOT invoke the block when the body cannot be parsed" do
+          block_called = false
+          entry = register_and_entry(:never_runs) do |_p|
+            block_called = true
+            { ok: true }
+          end
+          request = make_request(body: "{ broken", content_type: "application/json")
+          response = make_response
+
+          described_class.dispatch(entry, request, response)
+
+          expect(block_called).to be(false)
+          expect(response.status).to eq(400)
+        end
+      end
+
+      describe "AC2 — Ruact::ActionError → status + body" do
+        it "renders the error's integer status + JSON body verbatim" do
+          entry = register_and_entry(:raise_action_error) do |_params|
+            raise Ruact::ActionError.new(status: 422, body: { error: "invalid" })
+          end
+          request = make_request(body: "{}", content_type: "application/json")
+          response = make_response
+
+          described_class.dispatch(entry, request, response)
+
+          expect(response.status).to eq(422)
+          expect(JSON.parse(response.body)).to eq("error" => "invalid")
+        end
+
+        it "translates a Symbol status to the matching HTTP code" do
+          entry = register_and_entry(:raise_symbol_status) do |_params|
+            raise Ruact::ActionError.new(status: :unauthorized, body: { error: "no" })
+          end
+          request = make_request(body: "{}", content_type: "application/json")
+          response = make_response
+
+          described_class.dispatch(entry, request, response)
+
+          expect(response.status).to eq(401)
+          expect(JSON.parse(response.body)).to eq("error" => "no")
+        end
+
+        it "renders nil body as empty when ActionError.body is nil" do
+          entry = register_and_entry(:raise_no_body) do |_params|
+            raise Ruact::ActionError.new(status: 418, body: nil)
+          end
+          request = make_request(body: "{}", content_type: "application/json")
+          response = make_response
+
+          described_class.dispatch(entry, request, response)
+
+          expect(response.status).to eq(418)
+          expect(response.body.to_s).to eq("")
+        end
+      end
+    end
+  end
+end