ruact 0.0.2 → 0.0.3

data/lib/ruact/server_functions/query_context.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module Ruact
+  module ServerFunctions
+    # Story 9.4 (D3) — per-request execution context injected into a
+    # {Ruact::Query} subclass by the internal query dispatch controller. A
+    # fresh instance is built per request (NFR8) wrapping the DISPATCHING
+    # controller instance; because that controller inherits
+    # `Ruact.config.query_parent_controller`, every delegated reader resolves
+    # to the host's own machinery — `current_user` IS the host's method
+    # (Devise / Pundit / hand-rolled), not a gem-side resolver lambda.
+    #
+    # Mirrors the SHAPE of the Story-8.3 `StandaloneContext` (plain accessors,
+    # per-request instance) while sourcing everything from the controller —
+    # the resolver-lambda pattern is superseded by the 2026-06-02 ADR
+    # addendum (Decision 2).
+    class QueryContext
+      # @param controller [ActionController::Base] the dispatching controller
+      #   instance (a generated subclass of `Ruact.config.query_parent_controller`).
+      def initialize(controller:)
+        @controller = controller
+      end
+
+      # The host's authenticated user. Resolved through the controller's own
+      # `current_user` — public OR private (hand-rolled apps commonly define
+      # it `private`). When the host chain defines no `current_user` at all,
+      # raises a NoMethodError that names the fix instead of a bare
+      # "undefined method" from deep inside a query body.
+      #
+      # @return [Object, nil]
+      # @raise [NoMethodError] when the parent controller chain defines no
+      #   `current_user`.
+      def current_user
+        unless @controller.respond_to?(:current_user, true)
+          raise NoMethodError,
+                "ruact: the query dispatch controller (inheriting " \
+                "#{@controller.class.superclass.name}, via Ruact.config.query_parent_controller) " \
+                "does not define `current_user`. Define it on the parent controller, or point " \
+                "`query_parent_controller` at a controller that does."
+        end
+
+        @controller.send(:current_user)
+      end
+
+      # @return [ActionController::Parameters] the request params (query-string
+      #   parameters on a GET query route).
+      def params
+        @controller.params
+      end
+
+      # @return [ActionDispatch::Request] the live request.
+      def request
+        @controller.request
+      end
+
+      # @return [ActionDispatch::Request::Session] the host middleware's session.
+      def session
+        @controller.session
+      end
+    end
+  end
+end

data/lib/ruact/server_functions/query_dispatch.rb

@@ -0,0 +1,248 @@
+# frozen_string_literal: true
+
+require "action_controller"
+
+require_relative "error_rendering"
+require_relative "bucket_two_payload"
+require_relative "query_context"
+
+module Ruact
+  module ServerFunctions
+    # Story 9.4 (D2) — generates the INTERNAL dispatch controller backing the
+    # routes the `ruact_queries` macro draws: one controller subclass PER
+    # {Ruact::Query} subclass, with one action per public query method. The
+    # per-class shape is what makes the AC4 callback opt-out scopable — a
+    # `ruact_skip_before_action` on one query class lands on that class's
+    # controller only, and `only:`/`except:` options scope it further to
+    # individual query methods (each method is one action).
+    #
+    # The controller inherits `Ruact.config.query_parent_controller`
+    # (default `ApplicationController`), resolved LAZILY here — at route-draw
+    # time, when the host's constants exist — never at gem-load or configure
+    # time. The host's REAL callback chain therefore runs before the query
+    # class is instantiated (FR89). The dev never sees this controller; it is
+    # named under this module (e.g.
+    # `Ruact::ServerFunctions::QueryDispatch::CatalogQueryController`) only so
+    # Rails' string-based route resolution (`to: "…/catalog_query#categories"`)
+    # and `rails routes` output stay legible.
+    #
+    # Regeneration is idempotent: every `ruact_queries` evaluation (boot AND
+    # every dev-mode routes reload) rebuilds the constant from the query
+    # class's CURRENT state, and the query class itself is re-constantized per
+    # request, so code reloading never serves a stale class.
+    module QueryDispatch
+      # Instance-level dispatch plumbing shared by every generated controller.
+      # Included into the generated subclass, so these definitions override
+      # anything the parent chain provides (notably the {Ruact::Server} gates,
+      # when the host's ApplicationController happens to include the mutation
+      # concern).
+      module Dispatching
+        # The Method#parameters types that mark keyword arguments (D7).
+        KEYWORD_PARAM_TYPES = %i[key keyreq].freeze
+
+        private
+
+        # The action body of every query action: fresh context + fresh query
+        # instance per request (NFR8), return value serialized through the
+        # SAME policy Bucket 2 applies to ivars (D6). Encoded explicitly so a
+        # scalar String/nil return still renders valid JSON (`"hi"` / `null`),
+        # which `render json:` alone would pass through raw.
+        def __ruact_dispatch_query(query_method)
+          query_class = self.class.__ruact_query_class
+          query = query_class.new(QueryContext.new(controller: self))
+          result = query.public_send(query_method, **__ruact_query_kwargs(query, query_method))
+          serialized = BucketTwoPayload.serialize_value(result, strict: Ruact.config.strict_serialization)
+          render json: ActiveSupport::JSON.encode(serialized)
+        end
+
+        # D7 — minimal, best-effort param passing: only the keyword arguments
+        # the query method declares, read by name from the GET query params
+        # (values arrive as Strings). The strict FR88 sanitization contract
+        # (primitive allowlist, reject objects, 400 on invalid) is Story 9.5,
+        # coupled to the `useQuery` wire format.
+        def __ruact_query_kwargs(query, query_method)
+          query.method(query_method).parameters.each_with_object({}) do |(type, name), kwargs|
+            next unless KEYWORD_PARAM_TYPES.include?(type)
+
+            kwargs[name] = params[name.to_s] if params.key?(name.to_s)
+          end
+        end
+
+        # D5 — the {Ruact::Server} mutation gate returns false for GET/HEAD so
+        # GET *pages* keep stock Rails errors; query dispatch requests are GET
+        # *function calls*, so the structured 8.4 payload must render here.
+        # `Ruact::ConfigurationError` still re-raises — a misconfiguration is
+        # a loud setup failure, never a disguised runtime 500 (the same rule
+        # the mutation concern enforces).
+        def __ruact_render_structured_error?(error)
+          !error.is_a?(Ruact::ConfigurationError)
+        end
+      end
+
+      class << self
+        # Builds (or rebuilds) the dispatch controller for +query_class+ and
+        # installs it under this module's namespace, where the route target
+        # string from {.route_target_for} resolves to it.
+        #
+        # @param query_class [Class] a {Ruact::Query} subclass
+        # @return [Class] the generated controller
+        # @raise [Ruact::ConfigurationError] when the parent controller cannot
+        #   be resolved or +query_class+ is anonymous
+        def controller_for(query_class)
+          *namespace_segments, base = constant_segments(query_class)
+          namespace = ensure_namespace(namespace_segments)
+          const_name = "#{base}Controller"
+          namespace.send(:remove_const, const_name) if namespace.const_defined?(const_name, false)
+          namespace.const_set(const_name, build_controller(query_class))
+        end
+
+        # The `to:` route target for +query_class+'s generated controller —
+        # the underscored constant path Rails camelizes back at dispatch time.
+        # The query class's namespace is PRESERVED (review round 4): a nested
+        # path, never flattened, so two classes whose names differ only in
+        # namespace boundary (`Admin::CatalogQuery` vs `AdminCatalogQuery`)
+        # map to DISTINCT controllers and can never cross-wire — collision is
+        # impossible by construction, across any number of RouteSets / engines.
+        #
+        # @param query_class [Class] a {Ruact::Query} subclass
+        # @return [String] e.g. `"ruact/server_functions/query_dispatch/admin/catalog_query"`
+        def route_target_for(query_class)
+          "ruact/server_functions/query_dispatch/#{path_segments(query_class).join('/')}"
+        end
+
+        private
+
+        # The underscored route-path segments for +query_class+
+        # (`Admin::CatalogQuery` → `["admin", "catalog_query"]`).
+        def path_segments(query_class)
+          base_segments(query_class).map(&:underscore)
+        end
+
+        # The generated controller's constant-name segments — derived from the
+        # SAME underscored path the route target uses, then `camelize`d
+        # (review round 5). Deriving both directions from one underscored form
+        # via the shared global inflector guarantees the route target Rails
+        # `camelize`s at dispatch time resolves to EXACTLY this constant,
+        # regardless of how the query class spelled an acronym or how the host
+        # configured `inflect.acronym` (`APIProbe::CatalogQuery` and the route
+        # `.../api_probe/catalog_query` both canonicalize identically). Using
+        # the raw class spelling instead would 404 acronym constants with the
+        # default inflector.
+        def constant_segments(query_class)
+          path_segments(query_class).map(&:camelize)
+        end
+
+        # The query class's fully-qualified name split into constant segments
+        # (`Admin::CatalogQuery` → `["Admin", "CatalogQuery"]`). The namespace
+        # is preserved so the generated controller lives at a nested,
+        # collision-free constant path under {QueryDispatch}.
+        def base_segments(query_class)
+          name = query_class.name
+          unless name
+            raise Ruact::ConfigurationError,
+                  "ruact_queries cannot mount an anonymous Ruact::Query subclass — " \
+                  "assign it to a constant (e.g. `class CatalogQuery < ApplicationQuery`)."
+          end
+
+          name.split("::")
+        end
+
+        # Walks (creating as needed) the nested module path under {QueryDispatch}
+        # that mirrors the query class's namespace, returning the innermost
+        # module the controller constant is set on. Idempotent — reuses existing
+        # modules so repeated draws (boot + dev reloads) never duplicate them.
+        def ensure_namespace(segments)
+          segments.reduce(self) do |mod, segment|
+            if mod.const_defined?(segment, false)
+              mod.const_get(segment, false)
+            else
+              mod.const_set(segment, Module.new)
+            end
+          end
+        end
+
+        # Lazy resolution of `Ruact.config.query_parent_controller` (AC2). Both
+        # failure shapes are configuration-time errors raised at route-draw —
+        # a typo'd name or a non-controller class must never reach a request.
+        def resolve_parent_controller
+          name = Ruact.config.query_parent_controller
+          parent = begin
+            name.constantize
+          rescue NameError
+            raise Ruact::ConfigurationError,
+                  "ruact_queries: Ruact.config.query_parent_controller = #{name.inspect} does not " \
+                  "resolve to a constant. Define that controller, or point query_parent_controller " \
+                  "at an existing one in config/initializers/ruact.rb."
+          end
+
+          unless parent.is_a?(Class) && parent <= ActionController::Metal
+            raise Ruact::ConfigurationError,
+                  "ruact_queries: Ruact.config.query_parent_controller = #{name.inspect} resolved to " \
+                  "#{parent.inspect}, which is not an ActionController class."
+          end
+
+          parent
+        end
+
+        def build_controller(query_class)
+          query_class_name = query_class.name
+
+          # Mixins applied on the built class (not inside a `Class.new do … end`
+          # block) so YARD's static MixinHandler does not emit "Undocumentable
+          # mixin … for class" for an anonymous class body — the
+          # `--fail-on-warning` docs gate treats that as an error. Runtime is
+          # identical.
+          controller = Class.new(resolve_parent_controller)
+          controller.include(Ruact::ServerFunctions::ErrorRendering)
+          controller.include(Dispatching)
+
+          controller.define_singleton_method(:__ruact_query_class) { query_class_name.constantize }
+
+          # AC5 — the salvaged 8.4 error chain, with the same front-loading
+          # trick as Ruact::Server: handlers the parent chain registered
+          # (inherited OR declared later) stay more recent and keep precedence;
+          # the structured renderer only catches what the host did not.
+          inherited_handlers = controller.rescue_handlers
+          controller.rescue_from(StandardError, with: :__ruact_render_action_error)
+          controller.rescue_handlers = (controller.rescue_handlers - inherited_handlers) + inherited_handlers
+
+          define_query_actions(controller, query_class)
+          apply_skips(controller, query_class)
+          controller
+        end
+
+        # Review round 1 (finding 1) — a query method whose name already exists
+        # anywhere on the generated controller chain (`params`, `render`,
+        # `session`, `process`, the gem's own `__ruact_*` plumbing, …) would
+        # OVERRIDE that method when installed as an action, corrupting request
+        # handling (e.g. `def params` shadows `ActionController#params` and
+        # recurses through the dispatch path). Reject at route-draw with a
+        # legible error instead of failing at the first request.
+        def define_query_actions(controller, query_class)
+          query_class.public_instance_methods(false).each do |query_method|
+            if controller.method_defined?(query_method) || controller.private_method_defined?(query_method)
+              raise Ruact::ConfigurationError,
+                    "ruact_queries: query method :#{query_method} on #{query_class.name} is already " \
+                    "defined on the dispatch controller chain (#{controller.superclass.name} / " \
+                    "ActionController / ruact plumbing) and would shadow it — rename the query method."
+            end
+
+            controller.define_method(query_method) do
+              __ruact_dispatch_query(query_method)
+            end
+          end
+        end
+
+        # AC4 / D1 — forwards every recorded `ruact_skip_before_action` to
+        # Rails' own `skip_before_action` on the generated controller. An
+        # unknown callback raises here (route-draw time) unless the query
+        # passed `raise: false`, mirroring stock Rails behavior.
+        def apply_skips(controller, query_class)
+          query_class.__ruact_skipped_callbacks.each do |callbacks, options|
+            controller.skip_before_action(*callbacks, **options)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ruact/server_functions/registry.rb

@@ -0,0 +1,148 @@
+# frozen_string_literal: true
+
+module Ruact
+  module ServerFunctions
+    # In-memory storage for server-function entries. One instance backs
+    # `Ruact.action_registry`; another backs `Ruact.query_registry` — kept
+    # separate so the JSON snapshot can emit a `kind` field per entry without
+    # the call sites having to thread an extra parameter through. Cross-registry
+    # JS-identifier collisions are detected by {Ruact::ServerFunctions::Snapshot}
+    # at snapshot time (a single registry only sees its own entries).
+    #
+    # Thread-safety: not thread-safe by design. Registration happens at
+    # controller-class load time (`config.to_prepare` in dev, eager-load in
+    # production), single-threaded. Reads from {#entries} return a frozen
+    # snapshot of the internal hash so concurrent readers cannot observe a
+    # partial registration.
+    class Registry
+      # The only kinds the codegen knows how to emit. Story 8.1 owns `:action`,
+      # Story 9.1 owns `:query`. Any other value is rejected at registration
+      # time — silent acceptance would otherwise let an unknown kind fall
+      # through and be emitted as an action signature.
+      ALLOWED_KINDS = %i[action query].freeze
+
+      def initialize
+        @entries = {}
+      end
+
+      # Adds +symbol+ to the registry.
+      #
+      # @param symbol [Symbol] the Ruby identifier (snake_case).
+      # @param kind [Symbol] `:action` or `:query`. Other values raise.
+      # @param controller [Class, nil] the controller class registering the
+      #   function. Used in collision-error messages.
+      # @yield the implementation body; stored verbatim for Story 8.1 / 9.1 to
+      #   invoke. May be nil for Story 8.0a's bootstrap (registries are empty
+      #   until 8.1 and 9.1 land).
+      # @return [Ruact::ServerFunctions::RegistryEntry] the entry just inserted.
+      # @raise [Ruact::ConfigurationError] when +symbol+ fails the naming-bridge
+      #   rule, when +kind+ is not in {ALLOWED_KINDS}, or when a different Ruby
+      #   symbol already maps to the same JS identifier in THIS registry. Cross-
+      #   registry collisions (one action + one query sharing a JS identifier)
+      #   are detected later by {Ruact::ServerFunctions::Snapshot.functions_payload}.
+      def register(symbol, kind:, controller: nil, &block)
+        validate_kind!(symbol, kind, controller)
+        js_identifier = translate_symbol(symbol, controller)
+        detect_collision!(symbol, js_identifier, controller)
+
+        entry = RegistryEntry.new(
+          ruby_symbol: symbol,
+          js_identifier: js_identifier,
+          kind: kind,
+          controller: controller,
+          block: block
+        )
+        @entries[symbol] = entry
+        entry
+      end
+
+      # @return [Hash{Symbol => Ruact::ServerFunctions::RegistryEntry}] frozen
+      #   snapshot of the current entries, ordered by insertion.
+      def entries
+        @entries.dup.freeze
+      end
+
+      # Wipes the registry. Used by `config.to_prepare` (between dev reloads) and
+      # by tests that need a clean slate.
+      #
+      # @return [self]
+      def clear!
+        @entries.clear
+        self
+      end
+
+      # @return [Integer] number of registered entries.
+      def size
+        @entries.size
+      end
+
+      # @return [Boolean] whether the registry has no entries.
+      def empty?
+        @entries.empty?
+      end
+
+      private
+
+      def validate_kind!(symbol, kind, controller)
+        return if ALLOWED_KINDS.include?(kind)
+
+        raise Ruact::ConfigurationError,
+              "invalid server-function symbol :#{symbol} in #{describe_controller(controller)}: " \
+              "kind #{kind.inspect} is not one of #{ALLOWED_KINDS.inspect}"
+      end
+
+      # Wraps the NameBridge call to attach controller context to the raised
+      # error (the AC7 "invalid server-function symbol :SYMBOL in CONTROLLER"
+      # shape). NameBridge itself is controller-agnostic; the wrap lives at the
+      # registry boundary because that is where controller context exists.
+      def translate_symbol(symbol, controller)
+        NameBridge.to_js_identifier(symbol)
+      rescue Ruact::ConfigurationError => e
+        raise Ruact::ConfigurationError,
+              "invalid server-function symbol :#{symbol} in #{describe_controller(controller)} — #{e.message}"
+      end
+
+      def detect_collision!(symbol, js_identifier, controller)
+        # Re-run-3 (2026-05-15) — TWO failure shapes:
+        #
+        # (a) Different Ruby symbols, same JS identifier (`:foo_bar` and
+        #     `:fooBar` both → "fooBar"). Filtered by `js_identifier ==`.
+        # (b) Same Ruby symbol declared on TWO different controllers
+        #     (e.g., `ruact_action :create_post` in both `PostsController`
+        #     AND `AdminPostsController`). Pre-batch this silently
+        #     overwrote `@entries[symbol]` with the last-loaded one, so
+        #     dispatch routed to whichever controller Zeitwerk happened
+        #     to load last — non-deterministic in dev, surprise breakage
+        #     when refactoring. Detect by checking the existing entry's
+        #     `controller` against the one trying to register.
+        existing = @entries[symbol]
+        if existing && existing.controller != controller
+          raise Ruact::ConfigurationError,
+                "server-function naming collision: " \
+                ":#{symbol} is declared in BOTH " \
+                "#{describe_controller(existing.controller)} and " \
+                "#{describe_controller(controller)}. Each `ruact_action` " \
+                "symbol must be unique across the whole registry — pick a " \
+                "more specific name (e.g. :admin_create_post) on one side."
+        end
+
+        collision = @entries.values.find do |e|
+          e.js_identifier == js_identifier && e.ruby_symbol != symbol
+        end
+        return unless collision
+
+        raise Ruact::ConfigurationError,
+              "server-function naming collision: " \
+              ":#{symbol} (in #{describe_controller(controller)}) and " \
+              ":#{collision.ruby_symbol} (in #{describe_controller(collision.controller)}) " \
+              "both map to JS identifier \"#{js_identifier}\""
+      end
+
+      def describe_controller(controller)
+        return "unknown controller" if controller.nil?
+
+        controller.respond_to?(:name) && controller.name ? controller.name : controller.inspect
+      end
+    end
+  end
+end

data/lib/ruact/server_functions/registry_entry.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Ruact
+  module ServerFunctions
+    # Immutable record describing a single registered server function. Stored by
+    # {Ruact::ServerFunctions::Registry}; serialized into the JSON snapshot by
+    # {Ruact::ServerFunctions::Snapshot}.
+    #
+    # @!attribute [r] ruby_symbol
+    #   @return [Symbol] the symbol the controller registered (e.g. `:create_post`).
+    # @!attribute [r] js_identifier
+    #   @return [String] result of {Ruact::ServerFunctions::NameBridge.to_js_identifier}
+    #     — cached at registration time so the snapshot writer never re-derives it.
+    # @!attribute [r] kind
+    #   @return [Symbol] `:action` or `:query`. Informational at codegen time
+    #     (Story 8.0 decision 2A-i: both kinds POST through the same accessor).
+    # @!attribute [r] controller
+    #   @return [Class, nil] the controller class that registered the function;
+    #     used for collision-error messages and downstream tooling. Nil is allowed
+    #     for tests / Rails-console registrations.
+    # @!attribute [r] block
+    #   @return [Proc, nil] the implementation block supplied by the controller
+    #     macro. Story 8.0a stores it untouched; Stories 8.1 / 9.1 invoke it.
+    RegistryEntry = Data.define(:ruby_symbol, :js_identifier, :kind, :controller, :block)
+  end
+end