funicular 0.3.0 → 0.5.0

data/lib/funicular/assets/funicular.rb

@@ -19,3 +19,17 @@ Rails.autoloaders.main.ignore(Rails.root.join("app/funicular"))
 #   config.production_source = :cdn
 #   # config.cdn_version = "4.0.0"  # defaults to the version vendored in the gem
 # end
+
+# Local database (SQLite in the browser, docs/local_database.md):
+# disabled by default. Opting in also requires declaring how browser
+# storage is namespaced -- a user_key resolver for apps with
+# authentication, or anonymous_only for apps without users.
+#
+# Funicular.configure do |config|
+#   config.local_database = true
+#   config.user_key = ->(controller) {
+#     controller.request.session[:user_id]&.to_s
+#   }
+#   # or, for apps that genuinely have no users:
+#   # config.anonymous_only = true
+# end

data/lib/funicular/configuration.rb

@@ -26,6 +26,7 @@ module Funicular
     SOURCES = %i[local_debug local_dist cdn].freeze
 
     attr_reader :development_source, :test_source, :production_source
+    attr_reader :application_id, :user_key, :anonymous_only, :local_database
     attr_writer :cdn_version
 
     def initialize
@@ -33,6 +34,70 @@ module Funicular
       @test_source        = :local_debug
       @production_source  = :local_dist
       @cdn_version        = nil
+      @application_id     = "funicular"
+      @user_key           = nil
+      @anonymous_only     = false
+      @local_database     = false
+    end
+
+    # The SQLite/IndexedDB subsystem is deliberately opt-in. A plain
+    # Funicular application remains REST-only and pays none of its boot,
+    # storage, locking, or session-epoch costs.
+    def local_database=(value)
+      @local_database = value ? true : false
+    end
+
+    # Called after Rails initializers and again when the include tag is
+    # rendered. The client boot separately validates the emitted contract.
+    # Validation cannot run from local_database= because initializer
+    # assignment order is free.
+    def validate_local_database!
+      return true unless @local_database
+      return true if @user_key || @anonymous_only
+
+      raise ArgumentError,
+            "Funicular local_database requires config.user_key or " \
+            "config.anonymous_only = true"
+    end
+
+    # The application's namespace id (docs: local_database.md, data
+    # isolation). Give each Funicular app sharing an origin a distinct
+    # one; it keys the client's snapshot/lock namespace AND the epoch
+    # entry in the Rails session.
+    def application_id=(value)
+      id = value.to_s
+      if id.empty?
+        raise ArgumentError, "Funicular application_id cannot be empty"
+      end
+      @application_id = id
+    end
+
+    # A callable receiving the controller and returning a stable,
+    # non-reusable identifier for the signed-in user (nil when signed
+    # out). Mandatory whenever the local database is enabled, unless
+    # anonymous_only says the app genuinely has no users.
+    def user_key=(value)
+      unless value.respond_to?(:call)
+        raise ArgumentError,
+              "Funicular user_key must be callable (a lambda receiving the controller)"
+      end
+      if @anonymous_only
+        raise ArgumentError,
+              "Funicular user_key and anonymous_only are mutually exclusive; declare one or the other"
+      end
+      @user_key = value
+    end
+
+    # The explicit opt-out for apps without authentication: every
+    # visitor shares the anonymous namespace ON PURPOSE. Mutually
+    # exclusive with user_key -- the framework never picks silently.
+    def anonymous_only=(value)
+      flag = value ? true : false
+      if flag && @user_key
+        raise ArgumentError,
+              "Funicular user_key and anonymous_only are mutually exclusive; declare one or the other"
+      end
+      @anonymous_only = flag
     end
 
     def development_source=(value)

data/lib/funicular/epoch_header.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+require_relative "session_epoch"
+require_relative "epoch_stamping"
+
+module Funicular
+  # With the local database enabled, this Rack middleware writes the
+  # X-Funicular-Epoch header onto EVERY response -- the exception pages
+  # ActionDispatch renders included. Disabled responses are returned untouched.
+  # A controller-level after_action cannot guarantee that: it never
+  # runs when the action raises, and a header-less 500 reads as an
+  # epoch mismatch client-side, terminating a healthy page over a mere
+  # server error. The Railtie inserts this above
+  # ActionDispatch::ShowExceptions, so the freshly-built exception
+  # response passes through here too.
+  #
+  # The controller concern (EpochStamping) owns the ROTATION -- the
+  # user_key lambda needs its controller -- and leaves the epoch in the
+  # request env; this middleware only writes the header. When the
+  # request died before the concern ran, the stored session epoch
+  # (read without rotating) is the best truthful answer; with no
+  # session and no env value the header is simply absent, exactly as
+  # before the request.
+  class EpochHeader
+    # Every spelling of the header this middleware owns.
+    OWNED_HEADERS = [EpochStamping::HEADER, "X-Funicular-Epoch"].freeze
+
+    def initialize(app)
+      @app = app
+    end
+
+    def call(env)
+      status, headers, body = @app.call(env)
+      return [status, headers, body] unless Funicular.configuration.local_database
+      # This header is the framework's to write, so an inner layer's
+      # value is dropped FIRST and unconditionally: a stale one
+      # (stamped before a login/logout rotated the epoch) would let an
+      # old page read the post-transition response as a match --
+      # exactly the boundary decision 13 exists to keep closed. Leaving
+      # it in place when no authoritative epoch is available would be
+      # the same hole with none of the excuses. Both spellings go:
+      # plain header hashes are case-sensitive, so a legacy-cased
+      # duplicate would otherwise ride out alongside our lowercase
+      # (Rack 3) name.
+      OWNED_HEADERS.each { |name| headers.delete(name) }
+      epoch = env[EpochStamping::ENV_KEY] || stored_epoch(env)
+      headers[EpochStamping::HEADER] = epoch if epoch
+      [status, headers, body]
+    end
+
+    private
+
+    def stored_epoch(env)
+      session = env["rack.session"]
+      return nil unless session
+      epochs = session[SessionEpoch::SESSION_KEY]
+      return nil unless epochs.is_a?(Hash)
+      entry = epochs[Funicular.configuration.application_id]
+      return nil unless entry.is_a?(Hash)
+      epoch = entry["epoch"].to_s
+      epoch.empty? ? nil : epoch
+    rescue StandardError
+      # Best effort on the exception path: masking the original error
+      # with a session-read failure would be worse than a missing
+      # header.
+      nil
+    end
+  end
+end

data/lib/funicular/epoch_stamping.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+require_relative "session_epoch"
+
+module Funicular
+  # Controller mixin installed by the Railtie: when the local database is
+  # enabled, it rotates the session epoch where the user_key lambda has its
+  # controller, and leaves the value in the request env for the EpochHeader
+  # middleware to write out (docs decision 13).
+  #
+  # The header itself is deliberately NOT set here: a controller-set
+  # header dies with the controller's response when the action raises,
+  # and the exception page ActionDispatch renders would go out
+  # header-less -- which the client must treat as an epoch mismatch,
+  # terminating a healthy page over a mere 500.
+  #
+  # The epoch is stamped TWICE around the action. Before it, so a
+  # mid-action exception still sends a truthful value; and again in
+  # the ensure, with the POST-action identity, because the very
+  # actions that log a user in or out change the identity INSIDE the
+  # action -- their own response must already carry the rotated epoch,
+  # not leave the rotation to the next request (an old page would
+  # apply the login response as a match).
+  module EpochStamping
+    # Lowercase per the Rack 3 spec (response header names MUST be
+    # lowercase; Rack::Lint enforces it). HTTP header names are
+    # case-insensitive on the wire, so the client contract is
+    # unchanged.
+    HEADER = "x-funicular-epoch"
+    ENV_KEY = "funicular.epoch"
+
+    def self.included(base)
+      base.around_action :stamp_funicular_epoch if base.respond_to?(:around_action)
+    end
+
+    private
+
+    # request.session, never the controller's session accessor: an
+    # application action named "session" SHADOWS the accessor, and
+    # calling it from here would invoke the action itself (rendering
+    # twice). The ensure re-reads request.session instead of reusing
+    # the pre-action object because reset_session (a logout) replaces
+    # it mid-action.
+    def stamp_funicular_epoch
+      local_database = Funicular.configuration.local_database
+      return yield unless local_database
+      sess = request.session
+      unless Funicular::SessionEpoch.session_available?(sess)
+        # No session middleware (API-only Rails): there is no cookie
+        # identity for the epoch to protect, so the feature stays off
+        # instead of breaking every action with a disabled-session
+        # error.
+        return yield
+      end
+      request.env[ENV_KEY] = Funicular::SessionEpoch.stamp!(sess, self)
+      yield
+    ensure
+      if local_database
+        sess = request.session
+        if Funicular::SessionEpoch.session_available?(sess)
+          request.env[ENV_KEY] = Funicular::SessionEpoch.stamp!(sess, self)
+        end
+      end
+    end
+  end
+end

data/lib/funicular/helpers/picoruby_helper.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require "funicular/session_epoch"
+
 module Funicular
   module Helpers
     # View helpers exposed to ActionView through Funicular::Railtie.
@@ -16,6 +18,15 @@ module Funicular
         local_dist:  "dist"
       }.freeze
 
+      LOCAL_DATABASE_METADATA_KEYS = %i[
+        funicular_local_database
+        funicular_application_id
+        funicular_user_key
+        funicular_user_key_configured
+        funicular_anonymous_only
+        funicular_epoch
+      ].freeze
+
       # Minimal CSS the gem ships for class names it emits itself (e.g.
       # FormBuilder error states). Read once; see assets/funicular.css.
       BASE_CSS_PATH = File.expand_path("../assets/funicular.css", __dir__)
@@ -37,10 +48,42 @@ module Funicular
       # such as form error states render without host-CSS setup); pass
       # base_styles: false to skip it. Any extra options become HTML attributes
       # on the <script> tag.
+      #
+      # When opted in, the tag also carries the local-database page metadata as
+      # data-funicular-* attributes (docs: local_database.md, data
+      # isolation): the application id, the user-key contract, and the
+      # session epoch. With the feature disabled these attributes are omitted.
       def picoruby_include_tag(source: nil, base_styles: true, **options)
         resolved_source = source ? source.to_sym : Funicular.configuration.source_for(Rails.env)
         src = picoruby_src_for(resolved_source)
-        script = tag.script("", src: src, **options)
+        # Caller extras survive, but the framework's contract values
+        # always win: a data: override of the epoch or the user key
+        # would make the page disagree with its own responses (instant
+        # terminal) or boot the wrong namespace. Keys are normalized so
+        # a string or dashed spelling cannot smuggle in a duplicate of
+        # the same HTML attribute either.
+        data = {}
+        caller_data = (options.delete(:data) || {}).to_a
+        i = 0
+        caller_data_size = caller_data.size
+        while i < caller_data_size
+          key, value = caller_data[i]
+          normalized = key.to_s.tr("-", "_").to_sym
+          unless LOCAL_DATABASE_METADATA_KEYS.include?(normalized)
+            data[normalized] = value
+          end
+          i += 1
+        end
+        data.merge!(funicular_page_metadata)
+        # The same contract values can arrive as TOP-LEVEL options too
+        # ("data-funicular-epoch" => ..., or data_funicular_epoch:).
+        # Left in options they reach the tag builder unfiltered and
+        # emit a second copy of an attribute the metadata owns -- or,
+        # with the feature disabled, the only copy.
+        options.keys.each do |key|
+          options.delete(key) if reserved_metadata_option?(key)
+        end
+        script = tag.script("", src: src, data: data, **options)
         return script unless base_styles
 
         style = tag.style(PicorubyHelper.base_css.html_safe, "data-funicular-base": "")
@@ -96,6 +139,58 @@ module Funicular
 
       private
 
+      # True for every top-level spelling of a key the page metadata
+      # owns: "data-funicular-epoch", :"data-funicular-epoch", and the
+      # underscored data_funicular_epoch the tag builder dasherizes.
+      # Other data- attributes are the caller's business and survive.
+      def reserved_metadata_option?(key)
+        normalized = key.to_s.tr("-", "_")
+        return false unless normalized.start_with?("data_")
+
+        LOCAL_DATABASE_METADATA_KEYS.include?(
+          normalized.delete_prefix("data_").to_sym)
+      end
+
+      # The namespace + epoch metadata the client boot reads
+      # (DB.read_page_metadata): attribute values are HTML-escaped by
+      # the tag helper, so hostile application ids or user keys cannot
+      # break out of the attribute. The user-key attribute is OMITTED
+      # for signed-out visitors (the client boots the anonymous
+      # namespace), and the epoch is stamped through the same session
+      # entry the response header uses -- the page and its responses
+      # can never disagree at render time.
+      def funicular_page_metadata
+        config = Funicular.configuration
+        return {} unless config.local_database
+        config.validate_local_database!
+        ctrl = respond_to?(:controller) ? controller : nil
+        meta = {
+          funicular_local_database: "true",
+          funicular_application_id: config.application_id,
+        }
+        meta[:funicular_anonymous_only] = "true" if config.anonymous_only
+        # ONE resolver evaluation feeds both the page attribute and the
+        # epoch identity below: two evaluations could disagree
+        # mid-transition and stamp one user's epoch onto another
+        # user's page namespace.
+        key = nil
+        if config.user_key
+          meta[:funicular_user_key_configured] = "true"
+          key = Funicular::SessionEpoch.user_key(ctrl)
+          meta[:funicular_user_key] = key if key
+        end
+        # The view's session helper delegates to the controller, where
+        # an action named "session" shadows the accessor -- go through
+        # request.session, which cannot be shadowed.
+        req = respond_to?(:request) ? request : nil
+        sess = req && req.session
+        if sess && Funicular::SessionEpoch.session_available?(sess)
+          meta[:funicular_epoch] = Funicular::SessionEpoch.stamp_identity!(
+            sess, Funicular::SessionEpoch.identity_for(key))
+        end
+        meta
+      end
+
       def picoruby_src_for(source)
         if source == :cdn
           version = Funicular.configuration.cdn_version

data/lib/funicular/railtie.rb

@@ -9,6 +9,11 @@ module Funicular
     initializer "funicular.middleware" do |app|
       if Rails.env.development?
         app.middleware.use Funicular::Middleware
+        # The middleware recompiles the client bundle on change; SSR
+        # must reload the same sources, or server-rendered markup goes
+        # stale until a restart while hydration is already fresh.
+        require "funicular/ssr/runtime"
+        Funicular::SSR::Runtime.auto_reload = true
       end
     end
 
@@ -19,6 +24,31 @@ module Funicular
       end
     end
 
+    initializer "funicular.epoch" do |app|
+      # When the local database is enabled, every response carries
+      # X-Funicular-Epoch (docs decision 13):
+      # the controller concern rotates the epoch, the middleware writes
+      # the header. The middleware sits ABOVE the exception renderer so
+      # even a 500 page carries it -- a header-less error response
+      # would terminal the client over a mere server error.
+      require "funicular/epoch_header"
+      if defined?(ActionDispatch::ShowExceptions)
+        app.middleware.insert_before ActionDispatch::ShowExceptions,
+                                     Funicular::EpochHeader
+      else
+        app.middleware.use Funicular::EpochHeader
+      end
+      # :action_controller fires for both Base and API.
+      ActiveSupport.on_load(:action_controller) do
+        require "funicular/epoch_stamping"
+        include Funicular::EpochStamping
+      end
+    end
+
+    config.after_initialize do
+      Funicular.configuration.validate_local_database!
+    end
+
     rake_tasks do
       load "tasks/funicular.rake"
     end

data/lib/funicular/schema.rb

@@ -34,12 +34,24 @@ module Funicular
     def self.build(model_class, attributes:, endpoints: {}, except: {})
       merged = {}
       attributes.each do |name, definition|
+        # Readonly attributes are server-managed: the client never
+        # submits them, so validating their (nil) client-side value
+        # against e.g. a presence validator would reject every create.
+        # Skip validator introspection for them entirely.
+        if readonly?(definition)
+          merged[name] = definition
+          next
+        end
         rules = rules_for(model_class, name, except_kinds(except, name))
         merged[name] = rules.empty? ? definition : definition.merge(validations: rules)
       end
       { attributes: merged, endpoints: endpoints }
     end
 
+    def self.readonly?(definition)
+      definition.is_a?(Hash) && !!(definition[:readonly] || definition["readonly"])
+    end
+
     # Returns { "attr" => { "presence" => true, "length" => { "maximum" => 30 } } }
     # for the given attribute names only. Useful when emitting validations as a
     # separate block rather than inline (see #build for the inline form).
@@ -79,18 +91,34 @@ module Funicular
     end
 
     def self.serialize(kind, options)
-      case kind
-      when :presence, :absence, :acceptance, :confirmation
-        true
-      when :length
-        serialize_length(options)
-      when :numericality
-        serialize_numericality(options)
-      when :inclusion, :exclusion
-        serialize_set(options)
-      when :format
-        RegexpTranslator.translate(options[:with])
-      end
+      serialized =
+        case kind
+        when :presence, :absence, :acceptance, :confirmation
+          true
+        when :length
+          serialize_length(options)
+        when :numericality
+          serialize_numericality(options)
+        when :inclusion, :exclusion
+          serialize_set(options)
+        when :format
+          RegexpTranslator.translate(options[:with])
+        end
+      attach_shared_options(serialized, options)
+    end
+
+    # allow_nil / allow_blank change what the client may skip; without them
+    # a format validator on an optional attribute rejects the blank value
+    # that the server happily accepts. Kinds that serialize to a bare true
+    # (presence, or numericality without constraints) upgrade to a Hash so
+    # the flags survive for them too.
+    def self.attach_shared_options(serialized, options)
+      return serialized unless options[:allow_nil] || options[:allow_blank]
+      serialized = {} if serialized == true
+      return serialized unless serialized.is_a?(Hash)
+      serialized["allow_nil"] = true if options[:allow_nil]
+      serialized["allow_blank"] = true if options[:allow_blank]
+      serialized
     end
 
     def self.serialize_length(options)
@@ -149,6 +177,11 @@ module Funicular
         end
 
         js_source = source.gsub('\\A', '^').gsub('\\z', '$').gsub('\\Z', '$')
+        # Ruby regexp literals escape "#" to suppress interpolation and the
+        # escape survives in Regexp#source, but "\#" is an invalid identity
+        # escape for a JS RegExp under the u flag. "#" never needs escaping
+        # in JS source (x mode is already rejected above), so unescape it.
+        js_source = js_source.gsub('\\#', '#')
 
         flags = +''
         flags << 'i' if (regexp.options & Regexp::IGNORECASE) != 0

data/lib/funicular/session_epoch.rb

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+
+require "json"
+require "securerandom"
+
+module Funicular
+  # The server half of the session epoch (docs: local_database.md, "The
+  # session epoch"). When the local database is enabled, the epoch is an
+  # opaque value that changes on every authentication transition; every
+  # response carries it in the X-Funicular-Epoch header, and the client goes
+  # terminal on a mismatch
+  # so a tab can never keep applying data that now belongs to somebody
+  # else's cookie session.
+  #
+  # State lives in the Rails session PER application_id, so several
+  # Funicular apps sharing one cookie session cannot rotate each other's
+  # epochs:
+  #
+  #   session["funicular_epochs"][app_id] = {
+  #     "identity" => <canonical identity JSON>,
+  #     "epoch"    => <opaque hex>,
+  #   }
+  #
+  # String keys throughout: cookie sessions round-trip through JSON.
+  module SessionEpoch
+    SESSION_KEY = "funicular_epochs"
+
+    class << self
+      # A Rails API-only app usually runs WITHOUT a session middleware:
+      # request.session is a disabled stub whose every read and write
+      # raises. Loading Funicular must not break such an app, so both
+      # the controller concern and the include-tag helper check here
+      # and leave the epoch feature OFF -- with no cookie session there
+      # is no shared identity for the epoch to protect in the first
+      # place. Plain hashes (tests, exotic stores) count as enabled.
+      def session_available?(session)
+        return false if session.nil?
+        return true unless session.respond_to?(:enabled?)
+        session.enabled?
+      end
+
+      # The signed-in user's storage key, resolved through the
+      # configured lambda; nil when signed out or when no user_key is
+      # configured (anonymous_only apps included). An empty resolved
+      # key is a broken source and fails loud -- it would fold every
+      # user into one namespace.
+      def user_key(controller)
+        resolver = Funicular.configuration.user_key
+        return nil unless resolver
+        value = resolver.call(controller)
+        return nil if value.nil?
+        key = value.to_s
+        if key.empty?
+          raise Funicular::Error,
+                "Funicular user_key resolved to an empty string; " \
+                "return nil for signed-out visitors instead"
+        end
+        key
+      end
+
+      # The identity for an ALREADY-resolved user key (nil = signed
+      # out), encoded exactly like the client's namespace tuple (docs
+      # decision 12): ["v1", app, "anonymous"] or
+      # ["v1", app, "user", key] as canonical JSON. STRUCTURE separates
+      # the fields, so no delimiter or "anonymous"-as-a-user-key
+      # collisions. Callers that also DISPLAY the key (the include-tag
+      # helper) resolve it once and pass that same value here -- two
+      # resolver evaluations could disagree mid-transition and stamp
+      # one user's epoch onto another user's page namespace.
+      def identity_for(user_key)
+        app_id = Funicular.configuration.application_id
+        if user_key.nil?
+          JSON.generate(["v1", app_id, "anonymous"])
+        else
+          JSON.generate(["v1", app_id, "user", user_key])
+        end
+      end
+
+      # The current identity, resolving the user key through the
+      # configured lambda.
+      def identity(controller)
+        identity_for(user_key(controller))
+      end
+
+      # Returns the application's current epoch, rotating it first
+      # whenever the stored identity differs from the computed one --
+      # login, logout, and a direct user switch are all just "the
+      # identity changed". Writes the session entry on rotation.
+      def stamp!(session, controller)
+        stamp_identity!(session, identity(controller))
+      end
+
+      # The rotation core against a pre-computed identity.
+      def stamp_identity!(session, current)
+        stored = session[SESSION_KEY]
+        epochs = stored.is_a?(Hash) ? stored : {}
+        app_id = Funicular.configuration.application_id
+        entry = epochs[app_id]
+        if entry.is_a?(Hash) && entry["identity"] == current
+          epoch = entry["epoch"].to_s
+          return epoch unless epoch.empty?
+        end
+        epoch = SecureRandom.hex(16)
+        epochs[app_id] = { "identity" => current, "epoch" => epoch }
+        session[SESSION_KEY] = epochs
+        epoch
+      end
+    end
+  end
+end