funicular 0.3.0 → 0.5.0

data/minitest/epoch_stamping_test.rb

@@ -0,0 +1,225 @@
+# frozen_string_literal: true
+
+require "test_helper"
+require "funicular/epoch_stamping"
+require "funicular/epoch_header"
+
+# Exercises Funicular::EpochStamping (the controller mixin the Railtie
+# installs) and its interplay with the EpochHeader middleware. The
+# around_action stamps the epoch before the action AND re-stamps in
+# its ensure with the post-action identity: a login/logout inside the
+# action rotates on its own response, and a raising action still gets
+# a truthful header on the exception page.
+class EpochStampingTest < Minitest::Test
+  class FakeRequest
+    attr_reader :env, :session
+
+    def initialize(env = {}, session = nil)
+      @env = env
+      @session = session
+    end
+  end
+
+  class FakeControllerBase
+    def self.around_action(name)
+      (@around_actions ||= []) << name
+    end
+
+    def self.around_actions
+      @around_actions || []
+    end
+
+    attr_reader :request, :session
+
+    def initialize(session, env = {})
+      @request = FakeRequest.new(env, session)
+      @session = session
+    end
+
+    # A minimal filter chain: the action block runs inside every
+    # registered around_action, exceptions propagating like Rails'.
+    def process(&action)
+      chain = self.class.around_actions.reverse.inject(action) do |inner, name|
+        -> { send(name) { inner.call } }
+      end
+      chain.call
+    end
+  end
+
+  class StampedController < FakeControllerBase
+    include Funicular::EpochStamping
+
+    attr_accessor :current_user_key
+  end
+
+  # What request.session looks like in a session-less Rails API app:
+  # enabled? says no, every read and write raises.
+  class DisabledSession
+    def enabled?
+      false
+    end
+
+    def [](_key)
+      raise "sessions are disabled in this application"
+    end
+
+    def []=(_key, _value)
+      raise "sessions are disabled in this application"
+    end
+  end
+
+  def setup
+    @config = Funicular::Configuration.new
+    @config.local_database = true
+    @config.user_key = ->(controller) { controller.current_user_key }
+    Funicular.instance_variable_set(:@configuration, @config)
+    @session = {}
+  end
+
+  def teardown
+    Funicular.instance_variable_set(:@configuration, nil)
+  end
+
+  def session_epoch
+    entry = @session["funicular_epochs"]
+    entry ? entry["funicular"]["epoch"] : nil
+  end
+
+  # Runs one fake request: the controller starts as initial_key, the
+  # action block may mutate it (login/logout), the env epoch is what
+  # the middleware would write.
+  def run_request(initial_key, env = {}, &action)
+    controller = StampedController.new(@session, env)
+    controller.current_user_key = initial_key
+    controller.process { action ? action.call(controller) : nil }
+    env["funicular.epoch"]
+  end
+
+  def test_including_registers_the_around_action
+    assert_includes StampedController.around_actions, :stamp_funicular_epoch
+  end
+
+  # An application may route an action named "session" (a schema
+  # endpoint, say): that action SHADOWS the controller's session
+  # accessor. The concern must read request.session and never notice.
+  # (Not a StampedController subclass: the fake around_action registry
+  # is a class ivar and does not inherit.)
+  class SessionShadowedController < FakeControllerBase
+    include Funicular::EpochStamping
+
+    attr_accessor :current_user_key
+
+    def session
+      raise "the session action was invoked instead of the accessor"
+    end
+  end
+
+  def test_the_stamp_never_calls_the_controller_session_accessor
+    env = {}
+    controller = SessionShadowedController.new(@session, env)
+    controller.current_user_key = "u1"
+    ran = false
+    controller.process { ran = true }
+    assert ran
+    refute_nil env["funicular.epoch"]
+    assert_equal session_epoch, env["funicular.epoch"]
+  end
+
+  def test_disabled_local_database_does_not_touch_the_session_or_resolver
+    @config.local_database = false
+    @config.user_key = ->(_controller) { flunk "resolver was called" }
+    ran = false
+    session = {}
+    controller = StampedController.new(session)
+    controller.current_user_key = "u1"
+    controller.process { ran = true }
+    assert ran
+    assert_empty session
+    assert_nil controller.request.env["funicular.epoch"]
+  end
+
+  def test_the_epoch_lands_in_the_request_env
+    epoch = run_request("u1")
+    refute_nil epoch
+    refute_empty epoch
+    # Same user, same session: stable across requests.
+    assert_equal epoch, run_request("u1")
+  end
+
+  def test_the_env_value_matches_the_session_entry
+    epoch = run_request("u1")
+    assert_equal epoch, session_epoch
+  end
+
+  def test_a_login_inside_the_action_rotates_on_its_own_response
+    # The page was rendered signed-out; the LOGIN action itself flips
+    # the identity mid-request. Its own response must already carry
+    # the rotated epoch -- with only a pre-action stamp, an old page
+    # would apply the login response as an epoch match and the
+    # rotation would be a request late.
+    anonymous = run_request(nil)
+    login_epoch = run_request(nil) do |controller|
+      controller.current_user_key = "u1"
+    end
+    refute_equal anonymous, login_epoch
+    assert_equal session_epoch, login_epoch
+    # And it holds on the user's next request.
+    assert_equal login_epoch, run_request("u1")
+  end
+
+  def test_a_logout_inside_the_action_rotates_on_its_own_response
+    signed_in = run_request("u1")
+    logout_epoch = run_request("u1") do |controller|
+      controller.current_user_key = nil
+    end
+    refute_equal signed_in, logout_epoch
+    assert_equal session_epoch, logout_epoch
+  end
+
+  def test_a_disabled_session_skips_stamping_but_runs_the_action
+    # Session-less Rails API apps (no session middleware) must keep
+    # working with Funicular merely loaded: the epoch feature stays
+    # off instead of raising on every action.
+    ran = false
+    controller = StampedController.new(DisabledSession.new)
+    controller.current_user_key = "u1"
+    controller.process { ran = true }
+    assert ran
+    assert_nil controller.request.env["funicular.epoch"]
+  end
+
+  def test_an_enabled_session_object_still_stamps
+    enabled = Hash.new
+    def enabled.enabled?
+      true
+    end
+    controller = StampedController.new(enabled)
+    controller.current_user_key = "u1"
+    controller.process { nil }
+    refute_nil controller.request.env["funicular.epoch"]
+  end
+
+  def test_a_raising_action_still_produces_a_stamped_response
+    # The exception renderer builds a FRESH response none of the
+    # controller's headers survive into; the ensure re-stamp plus the
+    # middleware cover it -- with the POST-transition identity even
+    # when the action logged the user in before dying.
+    inner = lambda do |env|
+      controller = StampedController.new(@session, env)
+      controller.current_user_key = nil
+      begin
+        controller.process do
+          controller.current_user_key = "u1"
+          raise "boom in the action"
+        end
+      rescue RuntimeError
+        [500, {}, ["error page"]]
+      end
+    end
+    status, headers, = Funicular::EpochHeader.new(inner).call({})
+    assert_equal 500, status
+    assert_equal session_epoch, headers["x-funicular-epoch"]
+    assert_equal '["v1","funicular","user","u1"]',
+                 @session["funicular_epochs"]["funicular"]["identity"]
+  end
+end

data/minitest/fixtures/funicular_app/components/greeting_component.rb

@@ -3,12 +3,12 @@ class GreetingComponent < Funicular::Component
     { title: "Default Title", items: [] }
   end
 
-  def render(h)
-    h.div(class: "greeting") do |hh|
-      hh.h1 { state[:title] }
-      hh.ul do |hhh|
+  def render
+    div(class: "greeting") do
+      h1 { state[:title] }
+      ul do
         state[:items].each do |item|
-          hhh.li(key: item["id"]) { item["name"] }
+          li(key: item["id"]) { item["name"] }
         end
       end
     end

data/minitest/fixtures/funicular_app/components/probe_component.rb

@@ -0,0 +1,15 @@
+# Reads both props and state so SSR.render_component tests can assert
+# each channel is wired through. Not routed on purpose: rendering it
+# is only possible through the single-component entry point.
+class ProbeComponent < Funicular::Component
+  def initialize_state
+    { note: "default note" }
+  end
+
+  def render
+    div(class: "probe") do
+      h2 { props[:label].to_s }
+      p { state[:note] }
+    end
+  end
+end

data/minitest/form_for_test.rb

@@ -19,8 +19,8 @@ class FormForTest < Minitest::Test
         @submitted = data
       end
 
-      def render(h)
-        h.form_for(:comment, on_submit: :handle_submit) do |f|
+      def render
+        form_for(:comment, on_submit: :handle_submit) do |f|
           f.textarea(:body)
           f.submit("Post")
         end

data/minitest/hydration_test.rb

@@ -25,8 +25,8 @@ class HydrationMatchTest < Minitest::Test
   # invoked here (we feed vnodes directly); it only satisfies the abstract API.
   def probe
     klass = Class.new(Funicular::Component) do
-      def render(h)
-        h.div { "x" }
+      def render
+        div { "x" }
       end
 
       def match?(vnode, dom)

data/minitest/navigation_guard_test.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+require "test_helper"
+
+Funicular::SSR::Runtime.load_framework!
+
+# Router-side navigation guard: a component may veto navigation with a
+# confirmation message (mrblib logic exercised under CRuby; the browser
+# integration is covered by test/navigation_guard_test.rb and the
+# beforeunload listener).
+class NavigationGuardTest < Minitest::Test
+  class FreeComponent
+    def navigation_guard
+      nil
+    end
+  end
+
+  class GuardedComponent
+    def navigation_guard
+      "Unsaved changes will be lost. Leave?"
+    end
+  end
+
+  def setup
+    @router = Funicular::Router.new(nil)
+  end
+
+  def teardown
+    Funicular.confirm_handler = nil
+  end
+
+  def test_leaving_is_allowed_without_a_current_component
+    assert_equal true, @router.leave_allowed?
+  end
+
+  def test_leaving_is_allowed_when_the_guard_returns_nil
+    @router.instance_variable_set(:@current_component, FreeComponent.new)
+    assert_equal true, @router.leave_allowed?
+  end
+
+  def test_guard_message_is_prompted_and_denial_blocks_leaving
+    @router.instance_variable_set(:@current_component, GuardedComponent.new)
+    asked = []
+    Funicular.confirm_handler = ->(message) { asked << message; false }
+
+    assert_equal false, @router.leave_allowed?
+    assert_equal [ "Unsaved changes will be lost. Leave?" ], asked
+  end
+
+  def test_confirmation_allows_leaving
+    @router.instance_variable_set(:@current_component, GuardedComponent.new)
+    Funicular.confirm_handler = ->(_message) { true }
+
+    assert_equal true, @router.leave_allowed?
+  end
+
+  def test_confirm_defaults_to_true_on_the_server
+    # SSR must never block: without a handler, server mode allows leaving.
+    assert_equal true, Funicular.confirm("anything")
+  end
+
+  def test_component_guard_defaults_to_nil
+    assert_nil Funicular::Component.new.navigation_guard
+  end
+end

data/minitest/picoruby_helper_test.rb

@@ -63,6 +63,242 @@ class PicorubyHelperTest < Minitest::Test
     assert_includes html, "defer"
   end
 
+  # --- page metadata (docs decisions 12/13) -----------------------------
+
+  def test_disabled_include_tag_omits_all_local_database_metadata
+    html = @view.picoruby_include_tag(source: :local_dist, base_styles: false)
+    refute_includes html, "data-funicular-local-database"
+    refute_includes html, "data-funicular-application-id"
+    refute_includes html, "data-funicular-user-key"
+    refute_includes html, "data-funicular-anonymous-only"
+    refute_includes html, "data-funicular-epoch"
+  end
+
+  def test_disabled_include_tag_does_not_call_the_identity_resolver_or_session
+    @config.user_key = ->(_controller) { flunk "resolver was called" }
+    session = DisabledSession.new
+    view = metadata_view(user_key: "u1", session: session)
+    html = view.picoruby_include_tag(source: :local_dist, base_styles: false)
+    refute_includes html, "data-funicular-local-database"
+  end
+
+  def test_include_tag_embeds_anonymous_only
+    @config.local_database = true
+    @config.anonymous_only = true
+    html = @view.picoruby_include_tag(source: :local_dist, base_styles: false)
+    assert_includes html, 'data-funicular-local-database="true"'
+    assert_includes html, 'data-funicular-application-id="funicular"'
+    assert_includes html, 'data-funicular-anonymous-only="true"'
+  end
+
+  def test_enabled_include_tag_requires_an_identity_declaration
+    @config.local_database = true
+    error = assert_raises(ArgumentError) do
+      @view.picoruby_include_tag(source: :local_dist, base_styles: false)
+    end
+    assert_includes error.message, "user_key"
+  end
+
+  # A harness with the controller/request surface a real view has. The
+  # helper reads the session through request.session (the view's own
+  # session helper delegates to the controller, where an action named
+  # "session" shadows it).
+  class MetadataHarness < Harness
+    attr_accessor :controller, :request
+  end
+
+  FakeController = Struct.new(:current_user_key)
+  FakeViewRequest = Struct.new(:session)
+
+  def metadata_view(user_key: nil, session: {})
+    view = MetadataHarness.new
+    view.controller = FakeController.new(user_key)
+    view.request = FakeViewRequest.new(session)
+    view
+  end
+
+  # A view rendered by a controller that routes an action named
+  # "session": the view's session delegate would invoke that action.
+  # The helper must go through request.session and never notice.
+  class SessionShadowedHarness < MetadataHarness
+    def session
+      raise "the session delegate was invoked instead of request.session"
+    end
+  end
+
+  def test_the_helper_never_calls_the_view_session_delegate
+    @config.local_database = true
+    @config.user_key = ->(controller) { controller.current_user_key }
+    view = SessionShadowedHarness.new
+    view.controller = FakeController.new("u1")
+    view.request = FakeViewRequest.new({})
+    html = view.picoruby_include_tag(source: :local_dist, base_styles: false)
+    assert_includes html, "data-funicular-epoch"
+  end
+
+  def test_include_tag_embeds_user_key_and_epoch
+    @config.local_database = true
+    @config.user_key = ->(controller) { controller.current_user_key }
+    session = {}
+    view = metadata_view(user_key: "u1", session: session)
+    html = view.picoruby_include_tag(source: :local_dist, base_styles: false)
+    assert_includes html, 'data-funicular-user-key="u1"'
+    assert_includes html, 'data-funicular-user-key-configured="true"'
+    # The epoch on the page is THE session entry the response header
+    # stamps: page and responses cannot disagree at render time.
+    epoch = session["funicular_epochs"]["funicular"]["epoch"]
+    assert_includes html, %(data-funicular-epoch="#{epoch}")
+  end
+
+  # What request.session looks like in a session-less Rails API app.
+  class DisabledSession
+    def enabled?
+      false
+    end
+
+    def [](_key)
+      raise "sessions are disabled in this application"
+    end
+
+    def []=(_key, _value)
+      raise "sessions are disabled in this application"
+    end
+  end
+
+  def test_a_disabled_session_skips_the_epoch_without_breaking
+    @config.local_database = true
+    @config.user_key = ->(controller) { controller.current_user_key }
+    view = metadata_view(user_key: "u1", session: DisabledSession.new)
+    html = view.picoruby_include_tag(source: :local_dist, base_styles: false)
+    refute_includes html, "data-funicular-epoch"
+    assert_includes html, 'data-funicular-user-key="u1"'
+  end
+
+  def test_the_resolver_feeds_attribute_and_epoch_from_one_evaluation
+    # A racy resolver (current_user changing between two calls) must
+    # not embed user A's namespace while stamping user B's identity
+    # into the epoch entry: the helper evaluates it exactly once.
+    @config.local_database = true
+    calls = 0
+    @config.user_key = lambda do |_controller|
+      calls += 1
+      "u#{calls}"
+    end
+    session = {}
+    view = metadata_view(user_key: "ignored", session: session)
+    html = view.picoruby_include_tag(source: :local_dist, base_styles: false)
+    assert_equal 1, calls
+    assert_includes html, 'data-funicular-user-key="u1"'
+    assert_equal '["v1","funicular","user","u1"]',
+                 session["funicular_epochs"]["funicular"]["identity"]
+  end
+
+  def test_signed_out_omits_the_user_key_attribute
+    @config.local_database = true
+    @config.user_key = ->(controller) { controller.current_user_key }
+    view = metadata_view(user_key: nil)
+    html = view.picoruby_include_tag(source: :local_dist, base_styles: false)
+    refute_includes html, "data-funicular-user-key="
+    assert_includes html, 'data-funicular-user-key-configured="true"'
+  end
+
+  def test_metadata_values_are_html_escaped
+    @config.local_database = true
+    @config.application_id = %q{"><script>alert(1)</script>}
+    @config.user_key = ->(controller) { controller.current_user_key }
+    view = metadata_view(user_key: %q{"><img src=x>})
+    html = view.picoruby_include_tag(source: :local_dist, base_styles: false)
+    refute_includes html, "<script>alert(1)</script>"
+    refute_includes html, "<img src=x>"
+    assert_includes html, "&quot;&gt;"
+  end
+
+  def test_caller_data_attributes_survive_alongside_the_metadata
+    @config.local_database = true
+    @config.anonymous_only = true
+    html = @view.picoruby_include_tag(source: :local_dist, base_styles: false,
+                                      data: { turbo_track: "reload" })
+    assert_includes html, 'data-turbo-track="reload"'
+    assert_includes html, 'data-funicular-application-id="funicular"'
+  end
+
+  def test_caller_data_cannot_override_the_framework_metadata
+    # A data: override of the epoch or the user key would make the
+    # page disagree with its own responses (instant terminal) or boot
+    # the wrong namespace: the framework's values win, in every key
+    # spelling that would render as the same HTML attribute.
+    @config.local_database = true
+    @config.user_key = ->(controller) { controller.current_user_key }
+    session = {}
+    view = metadata_view(user_key: "u1", session: session)
+    html = view.picoruby_include_tag(
+      source: :local_dist, base_styles: false,
+      data: { funicular_epoch: "evil-symbol",
+              "funicular_user_key" => "evil-string",
+              "funicular-application-id" => "evil-dashed",
+              turbo_track: "reload" })
+    refute_includes html, "evil-symbol"
+    refute_includes html, "evil-string"
+    refute_includes html, "evil-dashed"
+    assert_includes html, 'data-funicular-user-key="u1"'
+    assert_includes html, 'data-funicular-application-id="funicular"'
+    epoch = session["funicular_epochs"]["funicular"]["epoch"]
+    assert_includes html, %(data-funicular-epoch="#{epoch}")
+    # The caller's unrelated attribute still rides along, and no
+    # attribute is emitted twice.
+    assert_includes html, 'data-turbo-track="reload"'
+    assert_equal 1, html.scan("data-funicular-epoch=").size
+    assert_equal 1, html.scan("data-funicular-user-key=").size
+    assert_equal 1, html.scan("data-funicular-application-id=").size
+  end
+
+  def test_caller_data_cannot_enable_the_disabled_local_database
+    html = @view.picoruby_include_tag(
+      source: :local_dist, base_styles: false,
+      data: { funicular_local_database: "true",
+              "funicular-application-id" => "injected",
+              funicular_anonymous_only: "true" })
+    refute_includes html, "data-funicular-local-database"
+    refute_includes html, "data-funicular-application-id"
+    refute_includes html, "data-funicular-anonymous-only"
+  end
+
+  def test_top_level_options_cannot_override_the_framework_metadata
+    # The contract values can bypass the data: hash entirely and arrive
+    # as top-level options, in any spelling the tag builder accepts.
+    @config.local_database = true
+    @config.user_key = ->(controller) { controller.current_user_key }
+    session = {}
+    view = metadata_view(user_key: "u1", session: session)
+    html = view.picoruby_include_tag(
+      source: :local_dist, base_styles: false,
+      **{ "data-funicular-epoch" => "evil-dashed",
+          :"data-funicular-user-key" => "evil-symbol",
+          data_funicular_application_id: "evil-underscored",
+          "data-turbo-track" => "reload" })
+    refute_includes html, "evil-dashed"
+    refute_includes html, "evil-symbol"
+    refute_includes html, "evil-underscored"
+    assert_includes html, 'data-funicular-user-key="u1"'
+    assert_includes html, 'data-funicular-application-id="funicular"'
+    epoch = session["funicular_epochs"]["funicular"]["epoch"]
+    assert_includes html, %(data-funicular-epoch="#{epoch}")
+    # Unrelated top-level data attributes are the caller's business.
+    assert_includes html, 'data-turbo-track="reload"'
+    assert_equal 1, html.scan("data-funicular-epoch=").size
+    assert_equal 1, html.scan("data-funicular-user-key=").size
+    assert_equal 1, html.scan("data-funicular-application-id=").size
+  end
+
+  def test_top_level_options_cannot_enable_the_disabled_local_database
+    html = @view.picoruby_include_tag(
+      source: :local_dist, base_styles: false,
+      **{ "data-funicular-local-database" => "true",
+          data_funicular_application_id: "injected" })
+    refute_includes html, "data-funicular-local-database"
+    refute_includes html, "injected"
+  end
+
   def test_cdn_source_uses_versioned_jsdelivr_url
     @config.cdn_version = "1.2.3"
     html = @view.picoruby_include_tag(source: :cdn, base_styles: false)

data/minitest/schema_test.rb

@@ -88,6 +88,26 @@ class SchemaDerivationTest < Minitest::Test
     assert_equal({ "update" => { method: "PATCH", path: "/x/:id" } }, schema[:endpoints])
   end
 
+  def test_build_skips_validators_for_readonly_attributes
+    schema = Funicular::Schema.build(
+      Account,
+      attributes: {
+        # name has a presence validator, but a readonly (server-managed)
+        # attribute is never submitted by the client, so its validators
+        # must not be inlined at all.
+        "name" => { type: "string", readonly: true }
+      }
+    )
+    assert_equal({ type: "string", readonly: true }, schema[:attributes]["name"])
+
+    # String keys behave the same.
+    schema = Funicular::Schema.build(
+      Account,
+      attributes: { "name" => { "type" => "string", "readonly" => true } }
+    )
+    refute schema[:attributes]["name"].key?(:validations)
+  end
+
   def test_length_range_is_serialized_as_min_and_max
     klass = Class.new do
       include ActiveModel::Validations
@@ -99,6 +119,33 @@ class SchemaDerivationTest < Minitest::Test
     assert_equal({ "minimum" => 2, "maximum" => 10 }, result["bio"]["length"])
   end
 
+  def test_bare_numericality_keeps_allow_nil
+    # numericality with no constraints serializes to a bare true; the
+    # allow_nil flag must upgrade it to a Hash instead of being dropped.
+    klass = Class.new do
+      include ActiveModel::Validations
+      def self.name = "Aged"
+      attr_accessor :age
+      validates :age, numericality: true, allow_nil: true
+    end
+    result = Funicular::Schema.validations_for(klass, ["age"])
+    assert_equal({ "allow_nil" => true }, result["age"]["numericality"])
+  end
+
+  def test_format_unescapes_ruby_hash_escape
+    # Ruby regexp literals escape "#" to suppress interpolation and the escape
+    # survives in Regexp#source; JS RegExp under the u flag rejects "\#" as an
+    # invalid identity escape (URI::MailTo::EMAIL_REGEXP is the wild example).
+    klass = Class.new do
+      include ActiveModel::Validations
+      def self.name = "Mailish"
+      attr_accessor :email
+      validates :email, format: { with: /\A[a-z.!\#$%&]+\z/ }
+    end
+    result = Funicular::Schema.validations_for(klass, ["email"])
+    assert_equal "^[a-z.!#$%&]+$", result["email"]["format"]["with"]
+  end
+
   def test_format_multiline_flag_is_translated
     klass = Class.new do
       include ActiveModel::Validations