phlex-reactive 0.4.8 → 0.9.0

data/lib/phlex/reactive/component/identity.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+module Phlex
+  module Reactive
+    module Component
+      # The signed-identity half of Component (issue #115): reactive_token —
+      # the payload signed into the DOM root on EVERY render — plus the
+      # class-level ivar precomputation that keeps that render path
+      # allocation-free.
+      #
+      # THE token hot path. Both memos below are bare defined?/||= fast paths
+      # ON PURPOSE: a render must never pay a per-read generation compare
+      # (issue #115 invariant, .claude/rules/performance.md). Coherence comes
+      # from the WRITE side instead — Component::Registry.bump! sweeps these
+      # memos off the declaring class and all its descendants whenever any
+      # registry declaration lands (class-load-shaped, rare), so they can't go
+      # stale even when an ancestor re-declares after a subclass memoized.
+      module Identity
+        extend ActiveSupport::Concern
+
+        class_methods do
+          # The record's instance-variable symbol (e.g. :@todo), computed once.
+          # reactive_token reads it on every render; interpolating :"@#{key}" each
+          # time would allocate a symbol per render. Nil when record-less.
+          def reactive_record_ivar
+            return @reactive_record_ivar if defined?(@reactive_record_ivar)
+
+            @reactive_record_ivar = reactive_record_key ? :"@#{reactive_record_key}" : nil
+          end
+
+          # [string_key, ivar_symbol] pairs for the signed state, computed once.
+          # reactive_token walks these every render; precomputing the "count"/:@count
+          # forms avoids a String + Symbol allocation per key per render.
+          def reactive_state_ivars
+            @reactive_state_ivars ||= reactive_state_keys.map { [it.to_s, :"@#{it}"] }
+          end
+        end
+
+        private
+
+        # Signed identity payload: the class name plus whichever identity pieces
+        # the component declares — a record GlobalID (`gid`), signed state (`s`),
+        # or both. Keeping them in ONE MessageVerifier payload makes the state
+        # (e.g. which column an inline_edit may write) tamper-proof alongside the
+        # record. Record-only ({c, gid}) and state-only ({c, s}) shapes are
+        # unchanged.
+        #
+        # A record that is NOT YET PERSISTED (new_record?) has no id → no GlobalID
+        # (to_gid raises MissingModelIdError). A record-backed component may render
+        # such a draft (an unsaved order the user is building): we OMIT gid and rely
+        # on the declared state (reactive_state) as the draft seed, so the token
+        # still signs cleanly and the client controller mounts. The draft is then
+        # driven client-side (reactive_compute) until it's saved; once persisted, a
+        # re-render signs the gid as usual. If the record is unsaved AND no state is
+        # declared, the token carries just {c} — enough to mount, but with no
+        # identity to round-trip, so declare reactive_state for a draft you sync.
+        def reactive_token
+          klass = self.class
+          payload = { "c" => klass.name }
+
+          # Sign the gid ONLY for a present, persisted record. An unsaved draft
+          # (persisted? == false) has no GlobalID — omit gid and let the signed
+          # state seed it (the tokenless-draft seam documented above); a nil
+          # ivar likewise carries no identity to sign, and must short-circuit
+          # before to_gid (nil.to_gid would raise).
+          if (record_ivar = klass.reactive_record_ivar) &&
+             (record = instance_variable_get(record_ivar)) && signable_gid?(record)
+            payload["gid"] = record.to_gid.to_s
+          end
+
+          state_ivars = klass.reactive_state_ivars
+          unless state_ivars.empty?
+            state = {}
+            state_ivars.each { |key, ivar| state[key] = instance_variable_get(ivar).as_json }
+            payload["s"] = state
+          end
+
+          Phlex::Reactive.sign(payload)
+        end
+
+        # A record's gid is signable unless it is an unsaved AR-like draft
+        # (responds to persisted? and is not persisted) — a new_record has no
+        # id and to_gid would raise MissingModelIdError. A record that doesn't
+        # respond to persisted? (a plain GlobalID-able object) is treated as
+        # signable, matching the pre-existing contract.
+        def signable_gid?(record)
+          !(record.respond_to?(:persisted?) && !record.persisted?)
+        end
+      end
+    end
+  end
+end

data/lib/phlex/reactive/component/registry.rb

@@ -0,0 +1,200 @@
+# frozen_string_literal: true
+
+module Phlex
+  module Reactive
+    module Component
+      # ONE inheritance semantic for every Component class-level registry
+      # (issue #115). Before this, the five registries hand-rolled two DIVERGENT
+      # patterns: reactive_record_key walked the superclass LIVE on every read,
+      # while reactive_actions/reactive_state_keys/reactive_collections/
+      # reactive_computes snapshot-dup'd the parent on FIRST access — so a
+      # parent declaring an action after a subclass had been read was visible
+      # via record-key semantics but silently invisible via action semantics.
+      #
+      # The unified semantic is the live one: **resolve through the superclass
+      # at read time**, memoized per class against a process-wide generation
+      # counter bumped on any registry write. Declarations happen at class-load
+      # (boot, dev reload), so post-boot reads are pure memo hits; a late
+      # declaration anywhere simply invalidates the memos lazily via the
+      # generation compare on next read.
+      #
+      # === The hot-path contract (issue #115 invariant, performance rule) ===
+      # The generation check gates registry RESOLUTION only. The identity-side
+      # memos read on EVERY reactive_token render — @reactive_record_ivar and
+      # @reactive_state_ivars (Component::Identity) — stay bare defined?/||=
+      # fast paths with NO per-read comparison. They are invalidated HERE, at
+      # write time: bump! sweeps them off the writing class and all its
+      # descendants (a declaration is rare and class-load-shaped; a render is
+      # not). That write-time sweep is also what fixes the pre-#115 split-brain
+      # where a parent's late reactive_record left a subclass's memoized ivar
+      # stale against the live reactive_record_key.
+      #
+      # Storage layout (all on the component class itself, so a Zeitwerk
+      # reload's fresh class object starts clean and nothing global retains a
+      # reference to app classes):
+      #   * @reactive_own_*              — the class's OWN declarations
+      #   * @reactive_registry_cache     — kind => resolved value
+      #   * @reactive_registry_generation — the generation the cache was built at
+      #
+      # Resolved values are fresh copies per class (merge/+), matching the
+      # pre-#115 mutability surface: mutating a returned collection never
+      # reaches an ancestor. Direct mutation of a returned registry is
+      # unsupported either way — it bypasses the generation bump, so the next
+      # declaration anywhere discards it. Declare through the DSL.
+      module Registry
+        # The class ivar carrying each registry's OWN declarations. A frozen
+        # lookup table (not :"@reactive_own_#{kind}") so no read or write
+        # allocates an intermediate string.
+        OWN_IVARS = {
+          actions: :@reactive_own_actions,
+          state_keys: :@reactive_own_state_keys,
+          collections: :@reactive_own_collections,
+          computes: :@reactive_own_computes,
+          record_key: :@reactive_own_record_key
+        }.freeze
+
+        # The identity-side hot-path memos swept by bump! (see the contract
+        # above). Owned by Component::Identity; invalidated here.
+        HOT_PATH_MEMOS = %i[@reactive_record_ivar @reactive_state_ivars].freeze
+
+        # Serializes generation bumps so two concurrent class definitions can't
+        # lose an increment (a resolution memoized between the two writes must
+        # see a THIRD generation, not the second one again). Reads stay bare —
+        # the resolution compare tolerates staleness (it just recomputes).
+        WRITE_MUTEX = Mutex.new
+
+        # Frozen empties for the no-declaration branches of resolve_* — the
+        # merge/+ still returns a fresh, per-class copy.
+        EMPTY_HASH = {}.freeze
+        EMPTY_LIST = [].freeze
+
+        @generation = 0
+
+        class << self
+          # The process-wide registry generation. Monotonic; never reset (a
+          # reloaded class carries no cache ivars, so it rebuilds regardless).
+          attr_reader :generation
+
+          # -- writes (all bump) ------------------------------------------------
+
+          # Store `key => value` in a Hash-shaped registry (actions,
+          # collections, computes). Returns the value, like the Hash#[]= the
+          # declarations used pre-#115.
+          def write_entry(klass, kind, key, value)
+            own!(klass, kind) { {} }[key] = value
+            bump!(klass)
+            value
+          end
+
+          # Append values to a List-shaped registry (state_keys). Keeps the
+          # pre-#115 concat semantics verbatim: declaration order, duplicates
+          # included.
+          def append(klass, kind, values)
+            own!(klass, kind) { [] }.concat(values)
+            bump!(klass)
+          end
+
+          # Set a Scalar-shaped registry (record_key). The nearest declaration
+          # up the ancestry wins at resolve time.
+          def write_scalar(klass, kind, value)
+            klass.instance_variable_set(OWN_IVARS.fetch(kind), value)
+            bump!(klass)
+            value
+          end
+
+          # -- resolution (all memoized against the generation) -----------------
+          #
+          # `reader` is the PUBLIC reader to walk the superclass through
+          # (e.g. :reactive_actions) — the walk must go through the public
+          # method so each ancestor memoizes its own resolution and a bare
+          # non-Component superclass (respond_to? false) terminates it.
+
+          # Hash-shaped: ancestors-first merge, nearest declaration winning per
+          # key — same key ordering Hash#merge gives the pre-#115 snapshot-dup
+          # (inherited entries keep their position, own keys append).
+          def resolve_hash(klass, kind, reader)
+            fetch(klass, kind) do
+              inherited = inherited_value(klass, reader)
+              own = own(klass, kind)
+              (inherited || EMPTY_HASH).merge(own || EMPTY_HASH)
+            end
+          end
+
+          # List-shaped: ancestors' entries first, own appended.
+          def resolve_list(klass, kind, reader)
+            fetch(klass, kind) do
+              inherited = inherited_value(klass, reader)
+              own = own(klass, kind)
+              (inherited || EMPTY_LIST) + (own || EMPTY_LIST)
+            end
+          end
+
+          # Scalar-shaped: own declaration if present (even one an ancestor
+          # would override), else the nearest ancestor's resolution, else nil.
+          def resolve_scalar(klass, kind, reader)
+            fetch(klass, kind) do
+              if klass.instance_variable_defined?(OWN_IVARS.fetch(kind))
+                klass.instance_variable_get(OWN_IVARS.fetch(kind))
+              else
+                inherited_value(klass, reader)
+              end
+            end
+          end
+
+          private
+
+          def own(klass, kind)
+            klass.instance_variable_get(OWN_IVARS.fetch(kind))
+          end
+
+          # The class's own storage for `kind`, initialized from the block on
+          # first write.
+          def own!(klass, kind)
+            ivar = OWN_IVARS.fetch(kind)
+            klass.instance_variable_get(ivar) || klass.instance_variable_set(ivar, yield)
+          end
+
+          # Invalidate every resolution memo in the process (generation bump)
+          # and sweep the hot-path identity memos off the writing class's
+          # family (see the contract in the module doc).
+          def bump!(klass)
+            WRITE_MUTEX.synchronize { @generation += 1 }
+            sweep_hot_path_memos(klass)
+          end
+
+          def sweep_hot_path_memos(klass)
+            HOT_PATH_MEMOS.each do
+              klass.remove_instance_variable(it) if klass.instance_variable_defined?(it)
+            end
+            klass.subclasses.each { sweep_hot_path_memos(it) }
+          end
+
+          # The generation-checked per-class memo: a cache built at an older
+          # generation is discarded wholesale and rebuilt lazily per kind.
+          def fetch(klass, kind)
+            cache = resolution_cache(klass)
+            cache.fetch(kind) { cache[kind] = yield }
+          end
+
+          def resolution_cache(klass)
+            generation = @generation
+            if klass.instance_variable_get(:@reactive_registry_generation) == generation
+              klass.instance_variable_get(:@reactive_registry_cache)
+            else
+              # Cache before generation: a concurrent reader that sees the new
+              # generation must find the new (empty) cache, never the stale one.
+              cache = klass.instance_variable_set(:@reactive_registry_cache, {})
+              klass.instance_variable_set(:@reactive_registry_generation, generation)
+              cache
+            end
+          end
+
+          def inherited_value(klass, reader)
+            sup = klass.superclass
+            sup.public_send(reader) if sup.respond_to?(reader)
+          end
+        end
+      end
+    end
+  end
+end