funicular 0.3.0 → 0.5.0

data/lib/funicular/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Funicular
-  VERSION = "0.3.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/generators/funicular/chat/templates/funicular_chat_component.rb.tt

@@ -1,25 +1,24 @@
 class FunicularChatComponent < Funicular::Component
-  styles do |css|
-    css.define :shell, "funicular-chat"
-    css.define :panel, "funicular-chat__panel"
-    css.define :header, "funicular-chat__header"
-    css.define :title, "funicular-chat__title"
-    css.define :subtitle, "funicular-chat__subtitle"
-    css.define :messages, "funicular-chat__messages"
-    css.define :empty, "funicular-chat__empty"
-    css.define :message, "funicular-chat__message"
-    css.define :name, "funicular-chat__message-name"
-    css.define :body, "funicular-chat__message-body"
-    css.define :form, "funicular-chat__form"
-    css.define :row, "funicular-chat__form-row"
-    css.define :input, "funicular-chat__input"
-    css.define :button,
-               base: "funicular-chat__button",
-               variants: {
-                 enabled: "funicular-chat__button--enabled",
-                 disabled: "funicular-chat__button--disabled"
-               }
-    css.define :error, "funicular-chat__error"
+  styles do
+    shell "funicular-chat"
+    panel "funicular-chat__panel"
+    header "funicular-chat__header"
+    title "funicular-chat__title"
+    subtitle "funicular-chat__subtitle"
+    messages "funicular-chat__messages"
+    empty "funicular-chat__empty"
+    message "funicular-chat__message"
+    name "funicular-chat__message-name"
+    body "funicular-chat__message-body"
+    form "funicular-chat__form"
+    row "funicular-chat__form-row"
+    input "funicular-chat__input"
+    button base: "funicular-chat__button",
+           variants: {
+             enabled: "funicular-chat__button--enabled",
+             disabled: "funicular-chat__button--disabled"
+           }
+    error "funicular-chat__error"
   end
 
   def initialize_state
@@ -95,37 +94,37 @@ class FunicularChatComponent < Funicular::Component
     end
   end
 
-  def render(h)
-    h.div(class: h.styles[:shell]) do |hh|
-      hh.div(class: h.styles[:panel]) do |panel|
-        panel.div(class: h.styles[:header]) do |header|
-          header.h1(class: h.styles[:title]) { "Funicular Chat" }
-          header.p(class: h.styles[:subtitle]) do
+  def render
+    div(class: styles.shell) do
+      div(class: styles.panel) do
+        div(class: styles.header) do
+          h1(class: styles.title) { "Funicular Chat" }
+          p(class: styles.subtitle) do
             state[:connected] ? "Realtime Ruby chat over ActionCable" : "Connecting..."
           end
         end
 
-        panel.div(class: h.styles[:messages]) do |messages|
+        div(class: styles.messages) do
           if state[:messages].empty?
-            messages.p(class: h.styles[:empty]) { "No messages yet." }
+            p(class: styles.empty) { "No messages yet." }
           else
             state[:messages].each do |message|
-              messages.div(class: h.styles[:message], key: message["id"]) do |item|
-                item.div(class: h.styles[:name]) { message["name"] }
-                item.div(class: h.styles[:body]) { message["body"] }
+              div(class: styles.message, key: message["id"]) do
+                div(class: styles.name) { message["name"] }
+                div(class: styles.body) { message["body"] }
               end
             end
           end
         end
 
-        panel.form(onsubmit: :send_message, class: h.styles[:form]) do |form|
+        form(onsubmit: :send_message, class: styles.form) do
           if state[:error]
-            form.div(class: h.styles[:error]) { state[:error] }
+            div(class: styles.error) { state[:error] }
           end
-          form.div(class: h.styles[:row]) do |row|
-            row.input(type: "text", value: state[:name], placeholder: "Name", oninput: :update_name, class: h.styles[:input])
-            row.input(type: "text", value: state[:body], placeholder: "Message", oninput: :update_body, class: h.styles[:input])
-            row.button(type: "submit", class: h.styles[:button, state[:sending] ? :disabled : :enabled], disabled: state[:sending]) do
+          div(class: styles.row) do
+            input(type: "text", value: state[:name], placeholder: "Name", oninput: :update_name, class: styles.input)
+            input(type: "text", value: state[:body], placeholder: "Message", oninput: :update_body, class: styles.input)
+            button(type: "submit", class: styles.button(state[:sending] ? :disabled : :enabled), disabled: state[:sending]) do
               state[:sending] ? "Sending..." : "Send"
             end
           end

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

@@ -0,0 +1,264 @@
+# frozen_string_literal: true
+
+require "test_helper"
+
+# Bareword component DSL (0.4.0), CRuby/SSR side. Twin of test/dsl_test.rb;
+# the attr_accessor case differs by VM: CRuby fires method_added for attr_*
+# so the collision surfaces at class-definition time, while mruby relies on
+# the mount-time sweep.
+class DSLTest < Minitest::Test
+  def setup
+    Funicular::SSR::Runtime.load_framework!
+  end
+
+  def test_bareword_render_builds_nested_tree
+    klass = Class.new(Funicular::Component) do
+      def initialize_state
+        { items: ["a", "b"] }
+      end
+
+      def render
+        div(class: "list") do
+          h1 { "title" }
+          ul do
+            state[:items].each_with_index do |item, i|
+              li(key: i) { item }
+            end
+          end
+        end
+      end
+    end
+
+    vnode = klass.new.build_vdom
+
+    assert_equal "div", vnode.tag
+    assert_equal ["h1", "ul"], vnode.children.map(&:tag)
+    assert_equal 2, vnode.children[1].children.size
+  end
+
+  def test_defining_reserved_tag_name_raises_at_class_definition
+    assert_raises(Funicular::DSLCollisionError) do
+      Class.new(Funicular::Component) do
+        def label
+        end
+      end
+    end
+  end
+
+  def test_attr_accessor_collision_raises_at_class_definition_on_cruby
+    # CRuby fires method_added for attr_*, so this is caught immediately
+    # (on mruby the mount-time sweep catches it instead).
+    assert_raises(Funicular::DSLCollisionError) do
+      Class.new(Funicular::Component) do
+        attr_accessor :label
+      end
+    end
+  end
+
+  def test_included_module_collision_is_caught_at_first_build
+    mod = Module.new do
+      def select
+      end
+    end
+    klass = Class.new(Funicular::Component) do
+      def render
+        div { "x" }
+      end
+    end
+    klass.include(mod)
+
+    assert_raises(Funicular::DSLCollisionError) { klass.new.build_vdom }
+  end
+
+  def test_allow_dsl_override_restores_user_method_and_tag_escape_hatch
+    klass = Class.new(Funicular::Component) do
+      allow_dsl_override :label
+
+      def label
+        "custom"
+      end
+
+      def render
+        div { tag(:label) { label } }
+      end
+    end
+
+    vnode = klass.new.build_vdom
+
+    assert_equal "label", vnode.children.first.tag
+    assert_equal ["custom"], vnode.children.first.children
+  end
+
+  def test_render_with_parameter_raises_migration_error
+    klass = Class.new(Funicular::Component) do
+      def render(h)
+        h
+      end
+    end
+
+    error = assert_raises(Funicular::DSLCollisionError) { klass.new.build_vdom }
+    assert_match(/must not take parameters/, error.message)
+  end
+
+  def test_p_with_non_hash_raises_with_hint
+    klass = Class.new(Funicular::Component) do
+      def render
+        div { p "debug me" }
+      end
+    end
+
+    error = assert_raises(ArgumentError) { klass.new.build_vdom }
+    assert_match(/puts x.inspect/, error.message)
+  end
+
+  def test_p_with_hash_builds_paragraph
+    klass = Class.new(Funicular::Component) do
+      def render
+        p(class: "para") { "text" }
+      end
+    end
+
+    vnode = klass.new.build_vdom
+
+    assert_equal "p", vnode.tag
+    assert_equal ["text"], vnode.children
+  end
+
+  def test_tag_outside_render_raises
+    klass = Class.new(Funicular::Component) do
+      def render
+        div { "x" }
+      end
+    end
+    component = klass.new
+    component.build_vdom
+
+    assert_raises(Funicular::RenderContextError) { component.div { "outside" } }
+  end
+
+  def test_bareword_styles_definition_and_method_access
+    klass = Class.new(Funicular::Component) do
+      styles do
+        shell "app-shell"
+        display "display-class"
+        button base: "btn", variants: { primary: "btn--primary" }, active: "btn--on"
+      end
+
+      def render
+        div(class: styles.shell) do
+          span(class: styles.display) { "d" }
+          button(class: styles.button(:primary)) { "b" }
+          a(class: styles[:button, true] | "extra") { "x" }
+        end
+      end
+    end
+
+    vnode = klass.new.build_vdom
+
+    assert_equal "app-shell", vnode.props[:class]
+    # :display would resolve to Object#display on an Object-based accessor;
+    # the BasicObject accessor keeps it a plain style name under CRuby SSR,
+    # matching the mruby client.
+    assert_equal "display-class", vnode.children[0].props[:class]
+    assert_equal "btn btn--primary", vnode.children[1].props[:class]
+    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
+        shell "app-shell"
+      end
+
+      def render
+        div { "x" }
+      end
+    end
+    component = klass.new
+
+    assert_raises(NoMethodError) { component.styles.typo_name }
+    assert_raises(ArgumentError) { component.styles[:typo] }
+  end
+
+  def test_bareword_helper_call_inside_styles_block_raises
+    assert_raises(ArgumentError) do
+      Class.new(Funicular::Component) do
+        styles do
+          button base: helper_that_does_not_exist("x")
+        end
+      end
+    end
+  end
+
+  def test_duplicate_style_definition_raises
+    assert_raises(ArgumentError) do
+      Class.new(Funicular::Component) do
+        styles do
+          shell "a"
+          shell "b"
+        end
+      end
+    end
+  end
+
+  def test_suspense_fallback_runs_bareword_in_own_component
+    klass = Class.new(Funicular::Component) do
+      use_suspense :user, ->(resolve, _reject) { resolve.call("u") }
+
+      def render
+        div do
+          suspense(:user, fallback: -> { span { "loading" } }) do |res|
+            span { res[:user] }
+          end
+        end
+      end
+    end
+
+    component = klass.new
+    vnode = component.build_vdom
+    assert_equal "loading", vnode.children.first.children.first
+
+    component.instance_variable_get(:@suspense_data)[:user] = "u"
+    component.instance_variable_get(:@suspense_states)[:user] = :resolved
+    vnode = component.build_vdom
+    assert_equal "u", vnode.children.first.children.first
+  end
+
+  def test_error_boundary_fallback_receives_view_context
+    fallback = ->(h, error) { h.div(class: "custom-error") { error.message } }
+    boundary = Funicular::ErrorBoundary.new(fallback: fallback)
+    boundary.catch_error(RuntimeError.new("boom"))
+    vnode = boundary.build_vdom
+
+    assert_equal "div", vnode.tag
+    assert_equal "custom-error", vnode.props[:class]
+    assert_equal ["boom"], vnode.children
+  end
+end

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