funicular 0.4.0 → 0.5.0

data/lib/funicular/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Funicular
-  VERSION = "0.4.0"
+  VERSION = "0.5.0"
 end

data/lib/funicular.rb

@@ -2,6 +2,7 @@
 
 require_relative "funicular/version"
 require_relative "funicular/configuration"
+require_relative "funicular/session_epoch"
 require_relative "funicular/compiler"
 require_relative "funicular/plugin"
 require_relative "funicular/schema"

data/lib/tasks/funicular.rake

@@ -101,12 +101,20 @@ namespace :funicular do
 
       FileUtils.cp(source_js,          dest_js)
       FileUtils.cp(source_css,         dest_css)
-      FileUtils.cp(source_initializer, dest_initializer)
 
       puts "Installed Funicular debug assets:"
       puts "  - #{dest_js}"
       puts "  - #{dest_css}"
-      puts "  - #{dest_initializer}"
+
+      # The initializer belongs to the application once it exists:
+      # re-running the installer must never clobber its configuration
+      # (source choice, local_database opt-in, user_key).
+      if File.exist?(dest_initializer)
+        puts "Skipped #{dest_initializer} (exists; delete it first to reinstall the template)"
+      else
+        FileUtils.cp(source_initializer, dest_initializer)
+        puts "  - #{dest_initializer}"
+      end
     end
 
     desc "Install vendored PicoRuby.wasm artifacts (dist + debug) into public/picoruby/"

data/minitest/callback_error_visibility_test.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+require "test_helper"
+
+# The mrblib runtime is plain Ruby, so the CRuby suite can cover the
+# Response#body alias and the handler error report format directly;
+# the browser-side wiring ships with the next picoruby.wasm rebuild.
+class CallbackErrorVisibilityTest < Minitest::Test
+  def setup
+    Funicular::SSR::Runtime.load_framework!
+  end
+
+  # Assigning the anonymous class to a constant names it, so the report
+  # prints a real component name. Defined lazily: Funicular::Component
+  # only exists after the framework loads.
+  def probe_component
+    unless defined?(::CheckoutProbeComponent)
+      Object.const_set(:CheckoutProbeComponent, Class.new(Funicular::Component) do
+        def render; end
+      end)
+    end
+    ::CheckoutProbeComponent.new
+  end
+
+  def test_response_body_is_an_alias_of_data
+    response = Funicular::HTTP::Response.new(200, { "id" => 1 })
+    assert_equal response.data, response.body
+    assert_equal({ "id" => 1 }, response.body)
+  end
+
+  def test_report_handler_error_names_component_handler_and_event
+    error = ArgumentError.new("wrong number of arguments (given 1, expected 0)")
+
+    out, _err = capture_io do
+      probe_component.report_handler_error("click", "#handle_save", error)
+    end
+
+    assert_includes out, "CheckoutProbeComponent#handle_save"
+    assert_includes out, "(onclick)"
+    assert_includes out, "ArgumentError: wrong number of arguments"
+  end
+
+  def test_report_handler_error_never_raises
+    capture_io do
+      assert_nil probe_component.report_handler_error("click", "#x", RuntimeError.new("y"))
+    end
+  end
+end

data/minitest/configuration_test.rb

@@ -61,4 +61,82 @@ class ConfigurationTest < Minitest::Test
       assert_equal vendored, @config.cdn_version
     end
   end
+
+  # --- local-database namespace settings (docs decisions 12/13) ---------
+
+  def test_namespace_defaults
+    assert_equal false, @config.local_database
+    assert_equal "funicular", @config.application_id
+    assert_nil @config.user_key
+    assert_equal false, @config.anonymous_only
+  end
+
+  def test_local_database_setter_normalizes_truthiness
+    @config.local_database = Object.new
+    assert_equal true, @config.local_database
+    @config.local_database = nil
+    assert_equal false, @config.local_database
+  end
+
+  def test_disabled_local_database_needs_no_identity
+    assert_equal true, @config.validate_local_database!
+  end
+
+  def test_enabled_local_database_requires_an_identity_declaration
+    @config.local_database = true
+    error = assert_raises(ArgumentError) do
+      @config.validate_local_database!
+    end
+    assert_includes error.message, "user_key"
+    assert_includes error.message, "anonymous_only"
+  end
+
+  def test_either_identity_declaration_satisfies_local_database
+    @config.local_database = true
+    @config.anonymous_only = true
+    assert_equal true, @config.validate_local_database!
+
+    fresh = Funicular::Configuration.new
+    fresh.local_database = true
+    fresh.user_key = ->(_controller) { nil }
+    assert_equal true, fresh.validate_local_database!
+  end
+
+  def test_application_id_rejects_empty_values
+    error = assert_raises(ArgumentError) { @config.application_id = "" }
+    assert_includes error.message, "application_id"
+    error = assert_raises(ArgumentError) { @config.application_id = nil }
+    assert_includes error.message, "application_id"
+  end
+
+  def test_application_id_is_canonicalized_with_to_s
+    @config.application_id = :chat_app
+    assert_equal "chat_app", @config.application_id
+  end
+
+  def test_user_key_must_be_callable
+    error = assert_raises(ArgumentError) { @config.user_key = "not callable" }
+    assert_includes error.message, "callable"
+  end
+
+  def test_user_key_and_anonymous_only_are_mutually_exclusive
+    # The reliably-detectable server-side config error: whichever
+    # setter comes second raises, in both orders.
+    @config.user_key = ->(controller) { nil }
+    error = assert_raises(ArgumentError) { @config.anonymous_only = true }
+    assert_includes error.message, "mutually exclusive"
+
+    fresh = Funicular::Configuration.new
+    fresh.anonymous_only = true
+    error = assert_raises(ArgumentError) do
+      fresh.user_key = ->(controller) { nil }
+    end
+    assert_includes error.message, "mutually exclusive"
+  end
+
+  def test_anonymous_only_false_never_conflicts
+    @config.user_key = ->(controller) { nil }
+    @config.anonymous_only = false
+    assert_equal false, @config.anonymous_only
+  end
 end

data/minitest/dsl_test.rb

@@ -164,6 +164,33 @@ class DSLTest < Minitest::Test
     assert_equal "btn btn--on extra", vnode.children[2].props[:class]
   end
 
+  def test_style_value_behaves_like_the_string_it_wraps
+    klass = Class.new(Funicular::Component) do
+      styles do
+        field "field-base"
+      end
+
+      def render
+        div(class: styles.field + " col-span-2") { "x" }
+      end
+    end
+
+    vnode = klass.new.build_vdom
+    assert_equal "field-base col-span-2", vnode.props[:class]
+
+    value = klass.new.styles.field
+    combined = value + "!"
+    assert_kind_of Funicular::StyleValue, combined
+    assert_equal "field-base!", combined.to_s
+    assert_equal "field-basefield-base", (value + value).to_s
+    # Like String#+: non-String operands raise instead of being to_s-ed.
+    assert_raises(TypeError) { value + 123 }
+    # No to_str on purpose: the mruby client's String#+ never coerces,
+    # so CRuby must reject the reversed form the same way the browser
+    # does instead of letting SSR accept code the client raises on.
+    assert_raises(TypeError) { "prefix " + value }
+  end
+
   def test_unknown_style_raises
     klass = Class.new(Funicular::Component) do
       styles do

data/minitest/epoch_header_test.rb

@@ -0,0 +1,149 @@
+# frozen_string_literal: true
+
+require "test_helper"
+require "funicular/epoch_header"
+
+# Exercises Funicular::EpochHeader, the middleware that writes
+# X-Funicular-Epoch on every outgoing response: from the env value the
+# controller concern pinned, from the stored session entry when the
+# request died before the concern ran, or not at all when neither
+# exists.
+class EpochHeaderTest < Minitest::Test
+  # Lowercase: the Rack 3 spec requires lowercase response header
+  # names, and HTTP header lookups are case-insensitive client-side.
+  HEADER = "x-funicular-epoch"
+
+  def setup
+    @config = Funicular::Configuration.new
+    @config.local_database = true
+    Funicular.instance_variable_set(:@configuration, @config)
+  end
+
+  def teardown
+    Funicular.instance_variable_set(:@configuration, nil)
+  end
+
+  def app_returning(status, headers = {})
+    ->(_env) { [status, headers, ["body"]] }
+  end
+
+  def test_writes_the_env_pinned_epoch
+    middleware = Funicular::EpochHeader.new(app_returning(200))
+    _, headers, = middleware.call({ "funicular.epoch" => "e-ctrl" })
+    assert_equal "e-ctrl", headers[HEADER]
+  end
+
+  def test_disabled_local_database_leaves_the_response_untouched
+    @config.local_database = false
+    headers = { HEADER => "inner", "X-Funicular-Epoch" => "legacy" }
+    middleware = Funicular::EpochHeader.new(app_returning(200, headers))
+    _, result, = middleware.call({ "funicular.epoch" => "outer" })
+    assert_same headers, result
+    assert_equal "inner", result[HEADER]
+    assert_equal "legacy", result["X-Funicular-Epoch"]
+  end
+
+  def test_falls_back_to_the_stored_session_epoch
+    # The concern never ran (an earlier before_action raised, say),
+    # but the session already carries this app's epoch: stamped
+    # without rotation.
+    session = {
+      "funicular_epochs" => {
+        "funicular" => { "identity" => "i", "epoch" => "e-stored" },
+      },
+    }
+    middleware = Funicular::EpochHeader.new(app_returning(500))
+    _, headers, = middleware.call({ "rack.session" => session })
+    assert_equal "e-stored", headers[HEADER]
+  end
+
+  def test_the_env_value_wins_over_the_stored_one
+    session = {
+      "funicular_epochs" => {
+        "funicular" => { "identity" => "i", "epoch" => "e-stored" },
+      },
+    }
+    middleware = Funicular::EpochHeader.new(app_returning(200))
+    _, headers, = middleware.call(
+      { "funicular.epoch" => "e-ctrl", "rack.session" => session })
+    assert_equal "e-ctrl", headers[HEADER]
+  end
+
+  def test_without_any_epoch_the_header_stays_absent
+    middleware = Funicular::EpochHeader.new(app_returning(200))
+    _, headers, = middleware.call({})
+    refute headers.key?(HEADER)
+  end
+
+  def test_an_inner_header_is_dropped_when_no_epoch_is_available
+    # No env value and no session: the contract is "no authoritative
+    # epoch, no header". An inner layer's leftover would otherwise
+    # survive as the page's only epoch signal -- and one stamped
+    # before the session rotated would read as a MATCH, keeping a page
+    # alive that decision 13 wants terminal.
+    middleware = Funicular::EpochHeader.new(
+      app_returning(200, { HEADER => "stale-pre-login" }))
+    _, headers, = middleware.call({})
+    refute headers.key?(HEADER)
+  end
+
+  def test_a_legacy_cased_inner_header_is_dropped_without_an_epoch_too
+    middleware = Funicular::EpochHeader.new(
+      app_returning(200, { "X-Funicular-Epoch" => "stale-pre-login" }))
+    _, headers, = middleware.call({})
+    refute headers.key?("X-Funicular-Epoch")
+    refute headers.key?(HEADER)
+  end
+
+  def test_respects_the_configured_application_id
+    @config.application_id = "second_app"
+    session = {
+      "funicular_epochs" => {
+        "funicular"  => { "identity" => "i", "epoch" => "e-other" },
+        "second_app" => { "identity" => "i", "epoch" => "e-mine" },
+      },
+    }
+    middleware = Funicular::EpochHeader.new(app_returning(200))
+    _, headers, = middleware.call({ "rack.session" => session })
+    assert_equal "e-mine", headers[HEADER]
+  end
+
+  def test_overwrites_a_stale_inner_header
+    # An inner layer's header may have been stamped BEFORE a login/
+    # logout rotated the epoch; keeping it would let an old page apply
+    # the post-transition response as a match. The framework's value
+    # is authoritative.
+    middleware = Funicular::EpochHeader.new(
+      app_returning(200, { HEADER => "stale-pre-login" }))
+    _, headers, = middleware.call({ "funicular.epoch" => "e-ctrl" })
+    assert_equal "e-ctrl", headers[HEADER]
+  end
+
+  def test_a_legacy_cased_inner_header_cannot_ride_out_as_a_duplicate
+    # Plain header hashes are case-sensitive: a stale capitalized
+    # spelling must be removed, not merely shadowed by our lowercase
+    # (Rack 3) name.
+    middleware = Funicular::EpochHeader.new(
+      app_returning(200, { "X-Funicular-Epoch" => "stale-pre-login" }))
+    _, headers, = middleware.call({ "funicular.epoch" => "e-ctrl" })
+    assert_equal "e-ctrl", headers[HEADER]
+    refute headers.key?("X-Funicular-Epoch")
+  end
+
+  def test_the_header_name_is_lowercase_for_rack_3
+    middleware = Funicular::EpochHeader.new(app_returning(200))
+    _, headers, = middleware.call({ "funicular.epoch" => "e-ctrl" })
+    assert_equal ["x-funicular-epoch"], headers.keys
+  end
+
+  def test_a_broken_session_read_never_masks_the_response
+    broken = Object.new
+    def broken.[](_key)
+      raise "session store exploded"
+    end
+    middleware = Funicular::EpochHeader.new(app_returning(500))
+    status, headers, = middleware.call({ "rack.session" => broken })
+    assert_equal 500, status
+    refute headers.key?(HEADER)
+  end
+end

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/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/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