funicular 0.4.0 → 0.5.1

data/mrblib/debug.rb

@@ -136,11 +136,7 @@ module Funicular
         state = component.instance_variable_get(:@state) || {}
         result = {} #: Hash[String, String]
         state.each do |key, value|
-          begin
-            result[key.to_s] = value.inspect
-          rescue
-            result[key.to_s] = "<error inspecting value>"
-          end
+          result[key.to_s] = safe_inspect(value)
         end
         JSON.generate(result)
       end
@@ -159,11 +155,7 @@ module Funicular
             result[name] = "<omitted>"
             next
           end
-          begin
-            result[name] = component.instance_variable_get(var).inspect
-          rescue
-            result[name] = "<error inspecting value>"
-          end
+          result[name] = safe_inspect(component.instance_variable_get(var))
         end
         JSON.generate(result)
       end
@@ -176,6 +168,58 @@ module Funicular
 
       private
 
+      # Bounded inspect for the DevTools inspector. A plain Object#inspect
+      # walks the whole object graph: a component's @runtime reaches the
+      # router, the mounted component and its entire VDOM tree, and that
+      # recursion overflows the wasm C stack in a -O0 build. Without a
+      # guard page the overflow silently overwrites the heap below the
+      # stack, which surfaces later as garbage registers and GC crashes.
+      # Only leaves are inspected in full; containers and objects are
+      # summarized past INSPECT_MAX_DEPTH.
+      INSPECT_MAX_DEPTH = 3
+      INSPECT_MAX_ITEMS = 25
+
+      def safe_inspect(value, depth = 0)
+        case value
+        when nil, true, false, Integer, Float, Symbol, String
+          value.inspect
+        when Array
+          return "[...#{value.size} items]" if depth >= INSPECT_MAX_DEPTH
+          items = value.first(INSPECT_MAX_ITEMS).map { |v| safe_inspect(v, depth + 1) }
+          items << "...#{value.size - INSPECT_MAX_ITEMS} more" if value.size > INSPECT_MAX_ITEMS
+          "[#{items.join(', ')}]"
+        when Hash
+          return "{...#{value.size} pairs}" if depth >= INSPECT_MAX_DEPTH
+          pairs = [] #: Array[String]
+          value.each do |k, v|
+            break if pairs.size >= INSPECT_MAX_ITEMS
+            pairs << "#{safe_inspect(k, depth + 1)} => #{safe_inspect(v, depth + 1)}"
+          end
+          pairs << "...#{value.size - INSPECT_MAX_ITEMS} more" if value.size > INSPECT_MAX_ITEMS
+          "{#{pairs.join(', ')}}"
+        else
+          safe_inspect_object(value, depth)
+        end
+      rescue => e
+        "<#{e.class}: #{e.message}>"
+      end
+
+      def safe_inspect_object(value, depth)
+        # JS::Object#inspect is a shallow C implementation; other BasicObject
+        # proxies (style accessors) raise from method_missing on any name.
+        return value.inspect if defined?(::JS::Object) && ::JS::Object === value
+        return "#<BasicObject>" unless ::Object === value
+        klass = value.class.to_s
+        return "#<#{klass}>" if depth >= INSPECT_MAX_DEPTH
+        ivars = value.instance_variables
+        return value.inspect if ivars.empty?
+        parts = ivars.first(INSPECT_MAX_ITEMS).map do |iv|
+          "#{iv}=#{safe_inspect(value.instance_variable_get(iv), depth + 1)}"
+        end
+        parts << "...#{ivars.size - INSPECT_MAX_ITEMS} more" if ivars.size > INSPECT_MAX_ITEMS
+        "#<#{klass} #{parts.join(', ')}>"
+      end
+
       def get_state_keys(component)
         state = component.instance_variable_get(:@state)
         return [] unless state.is_a?(Hash)

data/mrblib/differ.rb

@@ -103,8 +103,8 @@ module Funicular
       # The new shape is `[[:keyed_children, ops, removes]]`, applied as
       # three phases by the patcher:
       #   1. removes (descending old_index, against the original DOM snapshot)
-      #   2. content updates for kept children (against the snapshot, no move)
-      #   3. inserts in ascending new_index using insertBefore on the live DOM
+      #   2. content updates for kept children (against the snapshot)
+      #   3. kept-node moves and inserts in new-index order on the live DOM
       def self.diff_children_with_keys(old_children, new_children)
         # 1. Build key map from old children
         old_key_map = {} #: Hash[untyped, [Integer, child_t]]
@@ -127,7 +127,7 @@ module Funicular
               matched_old_indices[old_index] = true
               child_patches = diff(old_child, new_child)
               ops << [:keep, old_index, new_index, child_patches]
-              has_change = true unless child_patches.empty?
+              has_change = true if old_index != new_index || !child_patches.empty?
             else
               ops << [:insert, new_index, new_child]
               has_change = true
@@ -156,10 +156,12 @@ module Funicular
         #    unkeyed ones) is gone from the new render and must be removed.
         #    Skipping unkeyed olds here left stale nodes in the DOM, e.g. a
         #    "Loading..." placeholder that never disappeared once the keyed
-        #    list it was replaced by arrived.
+        #    list it was replaced by arrived. Raw String children are text
+        #    nodes in the DOM (normalize_children keeps them as Strings), so
+        #    they must be collected here as well; only nil slots are skipped.
         removes = [] #: Array[[Integer, child_t]]
         old_children.each_with_index do |old_child, old_index|
-          next unless old_child.is_a?(VNode)
+          next if old_child.nil?
           next if matched_old_indices[old_index]
           removes << [old_index, old_child]
           has_change = true

data/mrblib/file_upload.rb

@@ -16,8 +16,9 @@ module Funicular
         if (window.funicularFormDataUpload) {
           return;
         }
-        // FormData upload helper
-        window.funicularFormDataUpload = function(url, fieldsObj, fileFieldName, fileRefId) {
+        // FormData upload helper. The CSRF token is read fresh per
+        // request (Rails rotates it), matching Funicular::HTTP.
+        window.funicularFormDataUpload = function(url, fieldsObj, fileFieldName, fileRefId, method) {
           const formData = new FormData();
           for (const [key, value] of Object.entries(fieldsObj)) {
             formData.append(key, String(value));
@@ -28,10 +29,17 @@ module Funicular
               formData.append(fileFieldName, file);
             }
           }
-          return fetch(url, {
-            method: 'PATCH',
+          const options = {
+            method: method || 'PATCH',
+            credentials: 'include',
             body: formData
-          }).then(response => response.json());
+          };
+          const meta = document.querySelector('meta[name="csrf-token"]');
+          const token = meta && meta.getAttribute('content');
+          if (token) {
+            options.headers = { 'X-CSRF-Token': token };
+          }
+          return fetch(url, options).then(response => response.json());
         };
         console.log('Funicular helpers mounted');
       })();
@@ -83,8 +91,9 @@ module Funicular
     # @param fields [Hash] Form fields to include
     # @param file_field [String] Name of the file field
     # @param file [JS::Object] File object from input element
+    # @param method [String] HTTP method; PATCH is the historical default
     # @param block [Proc] Callback with response data
-    def self.upload_with_formdata(url, fields: {}, file_field: nil, file: nil, &block)
+    def self.upload_with_formdata(url, fields: {}, file_field: nil, file: nil, method: "PATCH", &block)
       # Store file and callback ID
       @callback_counters ||= [] # steep:ignore UnannotatedEmptyCollection
       callback_id = _ = nil
@@ -116,7 +125,8 @@ module Funicular
             '#{url}',
             fieldsObj,
             #{file_field ? "'#{file_field}'" : 'null'},
-            fileRefId
+            fileRefId,
+            #{JSON.generate(method.to_s)}
           ).then(function(data) {
             // Store as JSON string for easy Ruby parsing
             window._funicularUploadResult_#{callback_id} = JSON.stringify(data);

data/mrblib/funicular.rb

@@ -15,11 +15,8 @@ rescue LoadError
 end
 
 module Funicular
-  # Guard against redefinition: when the mrblib runtime is loaded into a
-  # CRuby/Rails process for SSR, lib/funicular/version.rb has already defined
-  # VERSION for the CRuby gem. In the wasm build VERSION is undefined here.
-  VERSION = '0.4.0' unless Funicular.const_defined?(:VERSION)
-
+  # VERSION is defined in mrblib/version.rb, which is compiled into the wasm
+  # build alongside this file and loaded by lib/funicular/version.rb on CRuby.
   def self.version
     VERSION
   end
@@ -60,6 +57,23 @@ module Funicular
     @router
   end
 
+  # Confirmation dialog used by the router's navigation guard. The
+  # default asks through window.confirm; tests (and apps wanting a
+  # custom dialog) can replace it with a proc taking the message and
+  # returning true to leave, false to stay.
+  @confirm_handler = nil
+
+  def self.confirm_handler=(handler)
+    @confirm_handler = handler
+  end
+
+  def self.confirm(message)
+    handler = @confirm_handler
+    return !!handler.call(message) if handler
+    return true if server?
+    !!JS.global.confirm(message)
+  end
+
   # Read the SSR state embedded by the server (funicular_state_tag) as a
   # Ruby Hash with string keys. Returns {} when absent or on the server.
   # Goes through JSON.stringify/parse for a reliable JS->Ruby conversion.
@@ -97,11 +111,17 @@ module Funicular
     child.is_a?(JS::Element) ? child : nil
   end
 
-  # Load schemas for models
+  # The schema boot barrier (docs decisions 6/19).
   # Usage:
   #   Funicular.load_schemas({ User => "user", Session => "session" }) do
   #     Funicular.start(container: 'app') { |router| ... }
   #   end
+  # EVERY request settles its slot exactly once -- success, HTTP
+  # error, or a schema that fails to apply -- so the barrier always
+  # completes. All green: an opted-in local database boots before the
+  # completion block; a REST-only app runs the block directly. Any failure:
+  # the block is NEVER invoked and the errors reach the console and
+  # config.on_boot_error. Only an active DB lifecycle is marked failed.
   def self.load_schemas(models, &block)
     # On the server there is no fetch and no need for client-side schemas:
     # SSR injects plain data into component state directly. Just run the
@@ -111,28 +131,116 @@ module Funicular
       return
     end
 
-    schemas_loaded = 0
-    total_schemas = models.size
-
-    check_completion = -> {
-      if schemas_loaded >= total_schemas
-        puts "[Funicular] All schemas loaded (#{schemas_loaded}/#{total_schemas})"
-        block.call if block
-      end
+    # Arm the page's epoch before the first request leaves: schema
+    # responses are epoch-checked too (docs decision 13). The response
+    # gate latches lazily on its own; the explicit call keeps the
+    # whole barrier deterministically armed at issue time.
+    local_database = Funicular::DB.local_database_enabled?
+    Funicular::DB.__latch_page_epoch if local_database
+
+    total = models.size
+    settled = 0
+    # @type var errors: Array[untyped]
+    errors = []
+    completed = false
+
+    settle = -> {
+      settled += 1
+      # Exactly once, and only with every slot settled.
+      next if completed
+      next if settled < total
+      completed = true
+      __settle_boot_barrier(errors, &block)
     }
 
-    models.each do |model_class, schema_name|
-      HTTP.get("/api/schema/#{schema_name}") do |response|
-        if response.error?
-          puts "[Schema] Failed to load #{schema_name} schema: #{response.error_message}"
-        else
+    if total == 0
+      __settle_boot_barrier(errors, &block)
+      return
+    end
+
+    entries = models.to_a
+    entries_size = entries.size
+    i = 0
+    while i < entries_size
+      entry = entries[i]
+      # One request per method call: the response block must capture
+      # ITS model and name, and a while loop's shared locals would all
+      # resolve to the last pair by response time.
+      __request_schema(entry[0], entry[1], errors, settle)
+      i += 1
+    end
+  end
+
+  def self.__request_schema(model_class, schema_name, errors, settle)
+    HTTP.get("/api/schema/#{schema_name}") do |response|
+      if response.error?
+        # Status and model always; the body's message only when the
+        # server actually sent one (an empty or HTML error body has
+        # no error_message).
+        message = "schema #{schema_name} (#{model_class.to_s}): " \
+                  "HTTP #{response.status}"
+        detail = response.error_message
+        message = "#{message}: #{detail}" if detail
+        errors << Funicular::DB::Error.new(message)
+      else
+        begin
           model_class.load_schema(response.data)
           puts "[Schema] #{schema_name} model initialized"
-          schemas_loaded += 1
-          check_completion.call
+        rescue => e
+          # A schema that arrived but cannot be applied settles as a
+          # failure -- the barrier must never hang on it. Wrapped so
+          # on_boot_error can tell WHICH model broke among several.
+          errors << Funicular::DB::Error.new(
+            "schema #{schema_name} (#{model_class.to_s}): " \
+            "#{e.class}: #{e.message}")
         end
       end
+      settle.call
     end
+    nil
+  end
+
+  # The barrier settled: boot on all-green (the completion block runs
+  # only when the boot itself succeeded too), fail loud otherwise.
+  def self.__settle_boot_barrier(errors, &block)
+    if errors.empty?
+      if Funicular::DB.local_database_enabled?
+        block.call if Funicular::DB.boot && block
+      else
+        block.call if block
+      end
+    else
+      if Funicular::DB.local_database_enabled?
+        Funicular::DB.__fail_boot(errors)
+      else
+        Funicular::DB.__report_boot_errors(errors)
+      end
+    end
+    nil
+  end
+
+  # Funicular.start's client-side gate (docs decision 19): apps with
+  # opted-in replica models boot inside the schema barrier above; opted-in
+  # local-only apps (no load_schemas call) boot right here. REST-only apps
+  # bypass DB boot, except that an explicit storage :local declaration fails.
+  def self.__boot_for_start
+    unless Funicular::DB.local_database_enabled?
+      models = Funicular::Model.__registered_models
+      i = 0
+      models_size = models.size
+      while i < models_size
+        if models[i].local?
+          raise Funicular::DB::ConfigError,
+            "storage :local requires config.local_database = true"
+        end
+        i += 1
+      end
+      return true
+    end
+    state = Funicular::DB.boot_state
+    return true if state == :ready
+    return false unless state == :unbooted
+    Funicular::DB.boot
   end
 
   # Start Funicular application
@@ -153,6 +261,14 @@ module Funicular
       return nil
     end
 
+    # An opted-in local database comes up before anything mounts. A failed
+    # boot already reported itself, so start quietly refuses to mount on it;
+    # a REST-only application passes this gate without touching the DB.
+    unless __boot_for_start
+      puts "[Funicular] start aborted: the local database did not boot"
+      return nil
+    end
+
     # Export debug configuration to JavaScript
     export_debug_config
 

data/mrblib/http.rb

@@ -1,13 +1,12 @@
 module Funicular
   module HTTP
-    CACHE_DB_NAME = 'funicular_http_cache'.freeze
-    CACHE_STORE = 'responses'.freeze
-
-    @cache = nil
-
     class Response
       attr_reader :data, :status, :ok
 
+      # Every mainstream HTTP client calls the payload `body`; keep
+      # that name working alongside `data`.
+      alias body data
+
       def initialize(status, data)
         @status = status
         @ok = @status >= 200 && @status < 300
@@ -26,73 +25,23 @@ module Funicular
       end
     end
 
-    # Open (or reuse) the response cache store. Idempotent and safe to call
-    # multiple times. Falls back to the in-memory backing if browser
-    # IndexedDB is unavailable.
-    def self.cache_init!
-      cache = @cache
-      return cache if cache
-      @cache = IndexedDB::KVS.open(CACHE_DB_NAME, store: CACHE_STORE)
-    end
-
-    # Drop a single cached entry by URL key. No-op if the cache is not
-    # initialized.
-    def self.cache_purge(url)
-      cache = @cache
-      return nil unless cache
-      cache.delete(url)
-      nil
-    end
-
-    # Drop every cached entry. No-op if the cache is not initialized.
-    def self.cache_clear
-      cache = @cache
-      return nil unless cache
-      cache.clear
-      nil
-    end
-
-    # Internal: read the cache for *url*. Returns the parsed entry hash or
-    # nil. Lazily initializes the cache on first use so callers can pass
-    # `cache:` without booting the SPA shell first.
-    def self.cache_lookup(url)
-      cache_init! unless @cache
-      cache = @cache
-      return nil unless cache
-      cache[url]
-    end
-
-    # Internal: write *entry* (a Hash with status/data/cached_at) to the
-    # cache. Awaits one extra Promise so the next request reliably hits.
-    def self.cache_write(url, entry)
-      cache_init! unless @cache
-      cache = @cache
-      return nil unless cache
-      cache[url] = entry
-      nil
-    end
-
-    def self.get(url, cache: nil, &block)
-      request("GET", url, nil, cache: cache, &block)
+    def self.get(url, &block)
+      request("GET", url, nil, &block)
     end
 
-    def self.post(url, body = nil, cache: nil, &block)
-      warn_unsupported_cache("post") if cache
+    def self.post(url, body = nil, &block)
       request("POST", url, body, &block)
     end
 
-    def self.patch(url, body = nil, cache: nil, &block)
-      warn_unsupported_cache("patch") if cache
+    def self.patch(url, body = nil, &block)
       request("PATCH", url, body, &block)
     end
 
-    def self.delete(url, cache: nil, &block)
-      warn_unsupported_cache("delete") if cache
+    def self.delete(url, &block)
       request("DELETE", url, nil, &block)
     end
 
-    def self.put(url, body = nil, cache: nil, &block)
-      warn_unsupported_cache("put") if cache
+    def self.put(url, body = nil, &block)
       request("PUT", url, body, &block)
     end
 
@@ -111,29 +60,6 @@ module Funicular
     class << self
       private
 
-      def warn_unsupported_cache(verb)
-        puts "[Funicular::HTTP] cache: option is GET-only; ignoring on #{verb.upcase}"
-      end
-
-      def now_seconds
-        # JavaScript Date.now() returns ms since epoch
-        ms = JS.global[:Date].now # steep:ignore
-        (ms.to_i / 1000)
-      end
-
-      def cache_hit?(entry, ttl)
-        return false unless entry.is_a?(Hash)
-        cached_at = entry["cached_at"]
-        return false unless cached_at.is_a?(Integer)
-        (now_seconds - cached_at) <= ttl
-      end
-
-      def serve_from_cache(entry, &block)
-        status = entry["status"].to_i
-        data = entry["data"]
-        block.call(Response.new(status, data)) if block
-      end
-
       def parse_response_body(text)
         return nil if text.nil?
 
@@ -145,15 +71,17 @@ module Funicular
         body
       end
 
-      def request(method, url, body, cache: nil, &block)
-        if method == "GET" && cache.is_a?(Integer) && cache > 0
-          entry = cache_lookup(url)
-          if cache_hit?(entry, cache)
-            serve_from_cache(entry, &block)
-            return
-          end
+      def request(method, url, body, &block)
+        # A terminal page must not TALK to the server either (docs
+        # decision 13): discarding the response is not enough, because
+        # the request itself would already have executed under the NEW
+        # session's cookies -- an old screen's click could mutate
+        # another user's data. Refused BEFORE the fetch; the callback
+        # still settles exactly once.
+        if Funicular::DB.session_terminated?
+          block.call(session_changed_response) if block
+          return nil
         end
-
         # @type var options: Hash[Symbol, String | Hash[String, String]]
         options = { method: method, credentials: "include" }
 
@@ -171,24 +99,73 @@ module Funicular
 
         options[:headers] = headers unless headers.empty?
 
-        JS.global.fetch(url, options) do |response|
-          status = response.status.to_i
-          json_text = response.to_binary
-          data = parse_response_body(json_text)
-          # @type var status: Integer
-          http_response = Response.new(status, data)
-
-          if method == "GET" && cache.is_a?(Integer) && cache > 0 && http_response.ok
-            cache_write(url, {
-              "status" => status,
-              "data" => data,
-              "cached_at" => now_seconds
-            })
+        settled = false
+        begin
+          JS.global.fetch(url, options) do |response|
+            # The epoch decides BEFORE the body is touched. fetch
+            # resolves once the headers arrive -- which is all this
+            # check needs -- but to_binary can still fail on an
+            # interrupted body stream, and the rescue below would then
+            # settle with a network error without ever processing the
+            # mismatch: the page would stay non-terminal and free to
+            # issue another request under the NEW session.
+            if Funicular::DB.__session_epoch_ok?(response_epoch(response))
+              # @type var status: Integer
+              status = response.status.to_i
+              json_text = response.to_binary
+              data = parse_response_body(json_text)
+              http_response = Response.new(status, data)
+            else
+              # The session changed under this page (docs decision 13):
+              # the response is DISCARDED, and the caller settles with
+              # an error instead of applying stale-session data.
+              http_response = session_changed_response
+            end
+            settled = true
+            block.call(http_response) if block
+          end
+        rescue => e
+          # Exactly-once settle: a rejected fetch (network failure,
+          # invalid URL) must still deliver a response -- a hanging
+          # callback would hang the schema barrier and every REST
+          # caller. An exception out of the caller's OWN block must
+          # NOT settle a second time. It is re-raised into the JS
+          # bridge, where it can vanish silently, so name the culprit
+          # on the console first: a swallowed typo in a response
+          # handler otherwise just freezes the page in its loading
+          # state.
+          if settled
+            puts "[Funicular::HTTP] #{method} #{url} callback raised " \
+                 "#{e.class}: #{e.message}"
+            raise e
+          end
+          settled = true
+          if block
+            block.call(Response.new(0,
+              { "error" => "network error: #{e.class}: #{e.message}" }))
           end
-
-          block.call(http_response) if block
         end
       end
+
+      def session_changed_response
+        Response.new(0,
+          { "error" => "the session changed; this page is " \
+                       "terminal (reload to continue)" })
+      end
+
+      # The X-Funicular-Epoch response header, nil when absent (no
+      # headers surface, no such header, or a null value through the
+      # JS bridge).
+      def response_epoch(response)
+        # @type var raw: untyped
+        raw = response
+        value = raw[:headers].get("X-Funicular-Epoch").to_s
+        return nil if value.empty?
+        return nil if value == "null" || value == "undefined"
+        value
+      rescue
+        nil
+      end
     end
   end
 end