funicular 0.3.0 → 0.5.0

data/minitest/session_epoch_test.rb

@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+
+require "test_helper"
+
+# Exercises Funicular::SessionEpoch, the server half of the session
+# epoch (docs decision 13): identity encoding, rotation on every
+# authentication transition, stability while the identity holds, and
+# per-application_id isolation inside one shared Rails session.
+class SessionEpochTest < Minitest::Test
+  FakeController = Struct.new(:current_user_key)
+
+  def setup
+    @config = Funicular::Configuration.new
+    Funicular.instance_variable_set(:@configuration, @config)
+    @session = {}
+  end
+
+  def teardown
+    Funicular.instance_variable_set(:@configuration, nil)
+  end
+
+  def controller_for(key)
+    FakeController.new(key)
+  end
+
+  def configure_user_key
+    @config.user_key = ->(controller) { controller&.current_user_key }
+  end
+
+  def stamp(key)
+    Funicular::SessionEpoch.stamp!(@session, controller_for(key))
+  end
+
+  # --- identity ---------------------------------------------------------
+
+  def test_identity_is_the_typed_versioned_tuple
+    configure_user_key
+    assert_equal '["v1","funicular","anonymous"]',
+                 Funicular::SessionEpoch.identity(controller_for(nil))
+    assert_equal '["v1","funicular","user","u1"]',
+                 Funicular::SessionEpoch.identity(controller_for("u1"))
+  end
+
+  def test_user_key_is_canonicalized_with_to_s
+    configure_user_key
+    assert_equal '["v1","funicular","user","42"]',
+                 Funicular::SessionEpoch.identity(controller_for(42))
+  end
+
+  def test_a_user_key_of_anonymous_cannot_collide_with_signed_out
+    configure_user_key
+    refute_equal Funicular::SessionEpoch.identity(controller_for(nil)),
+                 Funicular::SessionEpoch.identity(controller_for("anonymous"))
+  end
+
+  def test_without_a_user_key_lambda_everyone_is_anonymous
+    assert_equal '["v1","funicular","anonymous"]',
+                 Funicular::SessionEpoch.identity(controller_for("u1"))
+  end
+
+  def test_empty_resolved_user_key_fails_loud
+    configure_user_key
+    error = assert_raises(Funicular::Error) { stamp("") }
+    assert_includes error.message, "empty"
+  end
+
+  # --- rotation ---------------------------------------------------------
+
+  def test_stamp_creates_and_then_holds_an_epoch
+    configure_user_key
+    epoch = stamp("u1")
+    refute_empty epoch
+    assert_equal epoch, stamp("u1")
+    assert_equal epoch, stamp("u1")
+  end
+
+  def test_login_logout_and_switch_all_rotate
+    configure_user_key
+    anonymous = stamp(nil)
+    login = stamp("u1")
+    refute_equal anonymous, login
+    switch = stamp("u2")
+    refute_equal login, switch
+    logout = stamp(nil)
+    refute_equal switch, logout
+    # A fresh anonymous epoch, not the first one resurrected.
+    refute_equal anonymous, logout
+  end
+
+  # --- per-application isolation ----------------------------------------
+
+  def test_epochs_are_tracked_per_application_id
+    configure_user_key
+    epoch_a = stamp("u1")
+    @config.application_id = "second_app"
+    epoch_b = stamp("u1")
+    refute_equal epoch_a, epoch_b
+    # Rotating the second app's epoch leaves the first app's alone.
+    stamp("u2")
+    @config.application_id = "funicular"
+    assert_equal epoch_a, stamp("u1")
+  end
+
+  # --- session shape ------------------------------------------------------
+
+  def test_session_entry_uses_string_keys_for_json_round_trips
+    configure_user_key
+    epoch = stamp("u1")
+    entry = @session["funicular_epochs"]["funicular"]
+    assert_equal '["v1","funicular","user","u1"]', entry["identity"]
+    assert_equal epoch, entry["epoch"]
+  end
+
+  def test_a_corrupt_session_value_is_replaced_not_crashed_on
+    configure_user_key
+    @session["funicular_epochs"] = "garbage"
+    epoch = stamp("u1")
+    refute_empty epoch
+    assert_equal epoch,
+                 @session["funicular_epochs"]["funicular"]["epoch"]
+  end
+end

data/minitest/sig_tags_test.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require "test_helper"
+
+# The tag whitelist lives in mrblib/0_tags.rb (runtime) and is manually
+# enumerated in sig/tags.rbs and sig/view_context.rbs (types). These drifted
+# in the past; fail loudly when they do again.
+class SigTagsTest < Minitest::Test
+  ROOT = File.expand_path("..", __dir__)
+
+  def setup
+    Funicular::SSR::Runtime.load_framework!
+  end
+
+  def assert_sig_covers_all_tags(sig_path)
+    sig = File.read(File.join(ROOT, sig_path))
+    missing = Funicular::Tags::HTML_TAGS.reject do |tag|
+      sig.include?("def #{tag}: ")
+    end
+    assert_empty missing, "#{sig_path} is missing tag signatures: #{missing.join(', ')}"
+  end
+
+  def test_sig_tags_rbs_covers_all_tags
+    assert_sig_covers_all_tags("sig/tags.rbs")
+  end
+
+  def test_sig_view_context_rbs_covers_all_tags
+    assert_sig_covers_all_tags("sig/view_context.rbs")
+  end
+end

data/minitest/ssr_database_test.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+require "test_helper"
+
+# The SSR contract for the local database (docs decision 18): model
+# class bodies evaluate under CRuby -- declarations are recorded, no
+# SQLite is touched -- but booting the database or materializing a
+# local query on the server fails loud with UnavailableError, never an
+# empty result.
+class SSRDatabaseTest < Minitest::Test
+  def setup
+    # Loads the mrblib runtime under CRuby and flips Funicular.server
+    # to true, exactly like a Rails SSR render.
+    Funicular::SSR::Runtime.load_framework!
+  end
+
+  def test_boot_refuses_on_the_server
+    error = assert_raises(Funicular::DB::UnavailableError) do
+      Funicular::DB.boot(models: [], metadata: {})
+    end
+    assert_includes error.message, "SSR"
+    # The refusal is a clean raise, not a failed state: nothing to
+    # tear down, nothing latched.
+    assert_equal :unbooted, Funicular::DB.boot_state
+  end
+
+  def test_a_local_class_body_evaluates_but_materializing_raises
+    model = Class.new(Funicular::Model) do
+      table_name "ssr_drafts"
+      storage :local do
+        migrate 1 do |t|
+          t.string :title
+        end
+      end
+    end
+    # The declaration side worked: storage recorded, no SQLite touched.
+    assert_equal true, model.local?
+    # Materializing is where the server says no.
+    assert_raises(Funicular::DB::UnavailableError) { model.count }
+    assert_raises(Funicular::DB::UnavailableError) { model.local.to_a }
+    assert_raises(Funicular::DB::UnavailableError) do
+      model.local_create(title: "nope")
+    end
+  end
+
+  def test_association_declarations_evaluate_but_reading_raises
+    # Named constants, because the conventions read the class name:
+    # SsrPost -> ssr_post_id, :ssr_comment -> SsrComment.
+    Object.const_set(:SsrComment, Class.new(Funicular::Model) do
+      storage :local do
+        migrate 1 do |t|
+          t.integer :ssr_post_id
+        end
+      end
+    end)
+    Object.const_set(:SsrPost, Class.new(Funicular::Model))
+    # Declared after the constant exists, the way a `class SsrPost <
+    # Funicular::Model` body reads: has_many derives its foreign key
+    # from the declaring class name.
+    SsrPost.class_eval do
+      storage :local do
+        migrate 1 do |t|
+          t.integer :ssr_comment_id
+        end
+      end
+      belongs_to :ssr_comment
+      has_many :ssr_comments
+    end
+    # The declaration side worked: nothing resolved, no SQLite touched.
+    record = SsrPost.new(ssr_comment_id: 1)
+    # Reading one is a local query, and the server has no local database.
+    assert_raises(Funicular::DB::UnavailableError) { record.ssr_comment }
+    assert_raises(Funicular::DB::UnavailableError) { record.ssr_comments.to_a }
+  ensure
+    Object.send(:remove_const, :SsrPost) if Object.const_defined?(:SsrPost)
+    Object.send(:remove_const, :SsrComment) if Object.const_defined?(:SsrComment)
+  end
+end

data/minitest/ssr_reload_test.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "tmpdir"
+
+require "test_helper"
+
+# Development-mode SSR reload: with auto_reload enabled (the railtie
+# turns it on in development), editing an app source makes the next
+# boot! re-load the sources, so server-rendered markup matches what the
+# recompiled client bundle will hydrate.
+class SSRReloadTest < Minitest::Test
+  def setup
+    Funicular::SSR::Runtime.load_framework!
+  end
+
+  def teardown
+    Funicular::SSR::Runtime.auto_reload = false
+    Funicular::SSR::Runtime.reset_app!
+  end
+
+  def write_component(dir, title)
+    File.write(File.join(dir, "components", "reload_probe_component.rb"), <<~RUBY)
+      class ReloadProbeComponent < Funicular::Component
+        def render
+          div { "#{title}" }
+        end
+      end
+    RUBY
+  end
+
+  def build_app(dir)
+    FileUtils.mkdir_p(File.join(dir, "components"))
+    write_component(dir, "before reload")
+    File.write(File.join(dir, "initializer.rb"), <<~RUBY)
+      Funicular.start(container: "app") do |router|
+        router.get("/probe", to: ReloadProbeComponent, as: "probe")
+      end
+    RUBY
+  end
+
+  def render_probe(dir)
+    Funicular::SSR.render(path: "/probe", source_dir: dir)[:html]
+  end
+
+  def quietly
+    original_verbose = $VERBOSE
+    $VERBOSE = nil
+    yield
+  ensure
+    $VERBOSE = original_verbose
+  end
+
+  def test_edited_sources_are_reloaded_when_auto_reload_is_on
+    Dir.mktmpdir do |dir|
+      build_app(dir)
+      Funicular::SSR::Runtime.reset_app!
+      assert_includes render_probe(dir), "before reload"
+
+      write_component(dir, "after reload")
+      bump_mtime(dir)
+
+      # Off (the default): still the stale markup.
+      assert_includes render_probe(dir), "before reload"
+
+      Funicular::SSR::Runtime.auto_reload = true
+      quietly do
+        assert_includes render_probe(dir), "after reload"
+      end
+    end
+  end
+
+  def test_reset_app_discards_the_snapshot
+    Dir.mktmpdir do |dir|
+      build_app(dir)
+      Funicular::SSR::Runtime.reset_app!
+      quietly { render_probe(dir) }
+      refute Funicular::SSR::Runtime.sources_changed?(dir)
+
+      Funicular::SSR::Runtime.reset_app!
+      assert Funicular::SSR::Runtime.sources_changed?(dir)
+    end
+  end
+
+  def test_unchanged_sources_are_not_reloaded
+    Dir.mktmpdir do |dir|
+      build_app(dir)
+      Funicular::SSR::Runtime.reset_app!
+      Funicular::SSR::Runtime.auto_reload = true
+      quietly { render_probe(dir) }
+
+      refute Funicular::SSR::Runtime.sources_changed?(dir)
+    end
+  end
+
+  private
+
+  # mtime comparison, not equality of content: make the edit observable
+  # even on filesystems with coarse timestamps.
+  def bump_mtime(dir)
+    future = Time.now + 2
+    Dir.glob(File.join(dir, "**", "*.rb")).each do |file|
+      File.utime(future, future, file)
+    end
+  end
+end

data/minitest/ssr_test.rb

@@ -122,6 +122,47 @@ class SSRTest < Minitest::Test
     assert_includes result[:html], "greeting"
   end
 
+  # --- Single-component render (no route lookup) ------------------------
+
+  def test_render_component_renders_by_name_without_a_route
+    html = Funicular::SSR.render_component(
+      "GreetingComponent",
+      state: { title: "Embedded" },
+      source_dir: APP_DIR
+    )
+    assert_includes html, "<h1>Embedded</h1>"
+    assert_includes html, 'class="greeting"'
+  end
+
+  def test_render_component_passes_props_and_state
+    html = Funicular::SSR.render_component(
+      "ProbeComponent",
+      props: { "label" => "From Props" },
+      state: { note: "injected note" },
+      source_dir: APP_DIR
+    )
+    assert_includes html, "<h2>From Props</h2>"
+    assert_includes html, "<p>injected note</p>"
+  end
+
+  def test_render_component_uses_initialize_state_without_injection
+    html = Funicular::SSR.render_component("GreetingComponent", source_dir: APP_DIR)
+    assert_includes html, "<h1>Default Title</h1>"
+  end
+
+  def test_render_component_raises_on_unknown_component
+    assert_raises(NameError) do
+      Funicular::SSR.render_component("NoSuchComponent", source_dir: APP_DIR)
+    end
+  end
+
+  def test_render_component_rejects_a_non_component_constant
+    error = assert_raises(ArgumentError) do
+      Funicular::SSR.render_component("String", source_dir: APP_DIR)
+    end
+    assert_match(/not a Funicular::Component/, error.message)
+  end
+
   def test_symbolize_keys_handles_nil_and_string_keys
     assert_equal({}, Funicular::SSR.symbolize_keys(nil))
     assert_equal({ a: 1, b: 2 }, Funicular::SSR.symbolize_keys("a" => 1, "b" => 2))

data/minitest/testing_ensure_compiled_test.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "tmpdir"
+
+require "test_helper"
+
+# Covers the freshness decision behind Funicular::Testing.ensure_compiled!.
+# The actual compile (Node + vendored mrbc) is integration-only, matching
+# the compiler tests' scope.
+class TestingEnsureCompiledTest < Minitest::Test
+  def test_stale_when_bundle_is_missing
+    Dir.mktmpdir do |dir|
+      assert Funicular::Testing.stale?(File.join(dir, "app.mrb"), [])
+    end
+  end
+
+  def test_fresh_when_bundle_is_newer_than_every_source
+    Dir.mktmpdir do |dir|
+      source = File.join(dir, "component.rb")
+      output = File.join(dir, "app.mrb")
+      File.write(source, "")
+      File.write(output, "")
+      File.utime(Time.now - 60, Time.now - 60, source)
+
+      refute Funicular::Testing.stale?(output, [ source ])
+    end
+  end
+
+  def test_stale_when_any_source_is_newer_than_the_bundle
+    Dir.mktmpdir do |dir|
+      old_source = File.join(dir, "old.rb")
+      new_source = File.join(dir, "new.rb")
+      output = File.join(dir, "app.mrb")
+      [ old_source, new_source, output ].each { |f| File.write(f, "") }
+      File.utime(Time.now - 60, Time.now - 60, old_source)
+      File.utime(Time.now - 30, Time.now - 30, output)
+      File.utime(Time.now, Time.now, new_source)
+
+      assert Funicular::Testing.stale?(output, [ old_source, new_source ])
+    end
+  end
+
+  def test_missing_sources_do_not_count
+    Dir.mktmpdir do |dir|
+      output = File.join(dir, "app.mrb")
+      File.write(output, "")
+
+      refute Funicular::Testing.stale?(output, [ File.join(dir, "gone.rb") ])
+    end
+  end
+end

data/minitest/validations_test.rb

@@ -30,6 +30,35 @@ class ValidationsTest < Minitest::Test
     assert_equal true, k.new("name" => "Alice").valid?
   end
 
+  def test_uncompilable_format_regex_is_skipped_not_fatal
+    k = model_class
+    out, _err = capture_io do
+      k.register_schema_validations(
+        "name" => {
+          "format" => { "with" => "[", "flags" => "" },
+          "presence" => true
+        }
+      )
+    end
+    # The warning names the rejected pattern so it can be found among
+    # many schemas loading at boot.
+    assert_match(/Skipping format validator/, out)
+    assert_match(/pattern: \[/, out)
+    # The broken format validator is dropped; the rest still applies and
+    # schema registration does not raise.
+    blank = k.new("name" => "")
+    assert_equal false, blank.valid?
+    assert_equal true, k.new("name" => "Alice").valid?
+  end
+
+  def test_schema_numericality_with_allow_nil_skips_nil
+    k = model_class({ "age" => false })
+    k.register_schema_validations("age" => { "numericality" => { "allow_nil" => true } })
+
+    assert_equal true, k.new("age" => nil).valid?
+    assert_equal false, k.new("age" => "abc").valid?
+  end
+
   def test_length_maximum_and_minimum
     k = model_class
     k.class_eval { validates :name, length: { minimum: 2, maximum: 5 } }
@@ -170,14 +199,15 @@ class ValidationsTest < Minitest::Test
     m = k.new("name" => "ok")
     m.instance_variable_set("@id", 1)
 
-    got_success = :unset
     got_result = :unset
-    m.update("name" => "") do |success, result|
-      got_success = success
+    got_error = :unset
+    m.update("name" => "") do |result, error|
       got_result = result
+      got_error = error
     end
 
-    assert_equal false, got_success
-    assert_equal ["can't be blank"], got_result[:name]
+    # Unified 0.5.0 callback contract: (result, error), result nil on failure
+    assert_nil got_result
+    assert_equal ["can't be blank"], got_error[:name]
   end
 end

data/minitest/view_context_test.rb

@@ -7,7 +7,7 @@ class ViewContextTest < Minitest::Test
     Funicular::SSR::Runtime.load_framework!
   end
 
-  def test_explicit_state_styles_and_resources_do_not_collide_with_html_methods
+  def test_state_styles_and_resources_are_reachable_alongside_tags
     klass = Class.new(Funicular::Component) do
       styles { |css| css.define :hash, "hash-class" }
 
@@ -17,9 +17,9 @@ class ViewContextTest < Minitest::Test
         { class: "state-class", hash: "state-hash" }
       end
 
-      def render(h)
-        h.data(class: h.styles[:hash]) do
-          "#{state[:class]} #{state[:hash]} #{h.resources[:data]}"
+      def render
+        data(class: styles[:hash]) do
+          "#{state[:class]} #{state[:hash]} #{resources[:data]}"
         end
       end
     end
@@ -37,15 +37,15 @@ class ViewContextTest < Minitest::Test
 
   def test_component_children_are_vdom_children_not_props
     child = Class.new(Funicular::Component) do
-      def render(h)
-        h.div { children }
+      def render
+        div { children }
       end
     end
 
     parent = Class.new(Funicular::Component) do
-      define_method(:render) do |h|
-        h.component(child, title: "x") do |hh|
-          hh.span { "inside" }
+      define_method(:render) do
+        component(child, title: "x") do
+          span { "inside" }
         end
       end
     end
@@ -70,23 +70,23 @@ class ViewContextTest < Minitest::Test
     component_a.runtime = Funicular::Runtime.new(router_a)
     component_b.runtime = Funicular::Runtime.new(router_b)
 
-    assert_equal "/users/7", Funicular::ViewContext.new(component_a).routes.user_path(7)
-    assert_equal "/accounts/7", Funicular::ViewContext.new(component_b).routes.user_path(7)
+    assert_equal "/users/7", component_a.routes.user_path(7)
+    assert_equal "/accounts/7", component_b.routes.user_path(7)
   end
 
   def test_child_collector_is_restored_when_render_raises
     klass = Class.new(Funicular::Component) do
       attr_reader :captured
 
-      def render(h)
+      def render
         begin
-          h.div do |hh|
-            hh.span { "before" }
+          div do
+            span { "before" }
             raise "boom"
           end
         rescue
           @captured = current_children
-          h.div { "after" }
+          div { "after" }
         end
       end
     end

data/mrbgem.rake

@@ -7,7 +7,9 @@ MRuby::Gem::Specification.new('picoruby-funicular') do |spec|
     spec.add_dependency 'picoruby-wasm'
   end
   spec.add_dependency 'picoruby-indexeddb'
+  spec.add_dependency 'picoruby-sqlite3'
   spec.add_dependency 'picoruby-json'
+  spec.add_dependency 'picoruby-uri'
   spec.add_dependency 'mruby-object-ext', gemdir: "#{MRUBY_ROOT}/mrbgems/picoruby-mruby/lib/mruby/mrbgems/mruby-object-ext"
   spec.add_dependency 'mruby-hash-ext', gemdir: "#{MRUBY_ROOT}/mrbgems/picoruby-mruby/lib/mruby/mrbgems/mruby-hash-ext"
   spec.add_dependency 'mruby-array-ext', gemdir: "#{MRUBY_ROOT}/mrbgems/picoruby-mruby/lib/mruby/mrbgems/mruby-array-ext"

data/mrblib/0_tags.rb

@@ -0,0 +1,62 @@
+module Funicular
+  # Raised at class-definition time (method_added) or first mount when a
+  # component defines a method whose name collides with the view DSL.
+  class DSLCollisionError < StandardError; end
+
+  # Raised when a tag helper is called while the component is not rendering
+  # (e.g. from a stale proc or an event handler outside build_vdom).
+  class RenderContextError < StandardError; end
+
+  # Bareword tag DSL mixed into Funicular::Component. Tags are real public
+  # instance methods so `div(...)` works with self = the component inside
+  # `render`. Element construction is delegated to the component's internal
+  # ViewContext, which remains the single element factory (FormBuilder and
+  # the framework internals keep using it directly).
+  module Tags
+    # Single source of truth for the tag whitelist. sig/tags.rbs must list
+    # one method per entry; test/sig_tags_test.rb enforces that in CI.
+    HTML_TAGS = %w[
+      div span p a data
+      h1 h2 h3 h4 h5 h6
+      ul ol li
+      table thead tbody tr th td
+      form input textarea button select option label
+      header footer nav section article aside
+      img video audio canvas
+      br hr
+    ]
+
+    HELPER_NAMES = %w[
+      tag component form_for link_to button_to suspense
+      state props styles resources routes patch
+    ]
+
+    # Symbol => :tag | :helper. Component.method_added consults this to turn
+    # silent shadowing into a load-time error.
+    RESERVED_DSL = {} #: Hash[Symbol, Symbol]
+    HTML_TAGS.each { |name| RESERVED_DSL[name.to_sym] = :tag }
+    HELPER_NAMES.each { |name| RESERVED_DSL[name.to_sym] = :helper }
+
+    HTML_TAGS.each do |tag_name|
+      define_method(tag_name) do |props = {}, &block|
+        # @type self: Funicular::Component
+        unless props.is_a?(Hash)
+          hint = if tag_name == "p"
+            " Inside a component, `p` builds a <p> element; use `puts x.inspect` to debug."
+          else
+            ""
+          end
+          raise ArgumentError, "#{tag_name}() expects an attributes Hash, got #{props.class}.#{hint}"
+        end
+        __view__.tag(tag_name, props, &block)
+      end
+    end
+
+    # Escape hatch: emit any element, including custom elements outside the
+    # whitelist or a tag whose bareword is shadowed via allow_dsl_override.
+    def tag(name, props = {}, &block)
+      # @type self: Funicular::Component
+      __view__.tag(name, props, &block)
+    end
+  end
+end

data/mrblib/cable.rb

@@ -229,7 +229,7 @@ module Funicular
 
       # Setup beforeunload handler to persist pending commands
       def setup_beforeunload_handler
-        @beforeunload_callback_id = JS.global.addEventListener("beforeunload") do
+        @beforeunload_callback_id = JS.global.addEventListener("beforeunload", sync: true) do
           save_pending_to_storage
         end
       end