upkeep-rails 0.1.6

data/lib/upkeep/targeting.rb

@@ -0,0 +1,135 @@
+# frozen_string_literal: true
+
+require "digest"
+require "nokogiri"
+
+module Upkeep
+  module Targeting
+    Target = Data.define(:kind, :id, :reason)
+    Patch = Data.define(:target, :html)
+
+    class Selector
+      def select(recorder, changes)
+        graph = recorder.graph
+
+        frame_nodes =
+          graph.dependency_node_ids_matching(changes)
+            .flat_map { |dependency_id| graph.dependency_owner_ids(dependency_id) }
+            .flat_map { |owner_id| graph.nearest_frame_nodes_from(owner_id) }
+
+        uniq_targets(remove_contained_frames(graph, frame_nodes).filter_map { |frame| target_for_frame(frame) })
+      end
+
+      private
+
+      def remove_contained_frames(graph, frames)
+        frames.uniq(&:id).reject do |frame|
+          frames.any? { |candidate| candidate.id != frame.id && graph.contained_by?(frame.id, candidate.id) }
+        end
+      end
+
+      def target_for_frame(frame)
+        case frame.payload.fetch(:kind)
+        when "page"
+          Target.new("page", frame.id, "page frame dependency matched committed change")
+        when "render_site"
+          Target.new("render_site", frame.payload.fetch(:site_id), "render-site dependency matched committed change")
+        when "fragment"
+          Target.new("fragment", frame.id, "record attribute read matched committed attributes")
+        end
+      end
+
+      def uniq_targets(targets)
+        targets.uniq { |target| [target.kind, target.id] }
+      end
+    end
+
+    class Patcher
+      def initialize(html)
+        @fragment = Extraction.parse_html(html)
+      end
+
+      def apply(patches)
+        patches.each { |patch| apply_patch(patch) }
+        fragment.to_html
+      end
+
+      private
+
+      attr_reader :fragment
+
+      def apply_patch(patch)
+        node = node_for(patch.target)
+        raise "target not found in current DOM: #{patch.target.inspect}" unless node
+
+        replacement = replacement_for(patch)
+        node.replace(replacement)
+      end
+
+      def node_for(target)
+        Extraction.node_for(fragment, target)
+      end
+
+      def replacement_for(patch)
+        parsed = Extraction.parse_html(patch.html)
+        Extraction.node_for(parsed, patch.target) ||
+          parsed.children.find { |child| child.element? } ||
+          parsed.at_css("body > *")
+      end
+    end
+
+    module Extraction
+      module_function
+
+      def patches_from_full_rerender(full_html, targets)
+        targets.map { |target| Patch.new(target, extract_target_html(full_html, target)) }
+      end
+
+      def extract_target_html(html, target)
+        fragment = parse_html(html)
+        node = node_for(fragment, target)
+
+        raise "target not found in full rerender: #{target.inspect}" unless node
+
+        node.to_html
+      end
+
+      def node_for(fragment, target)
+        case target.kind
+        when "page"
+          fragment.at_css(%([data-upkeep-page-frame="#{css_escape(target.id)}"]))
+        when "fragment"
+          fragment.at_css(%([data-upkeep-frame="#{css_escape(target.id)}"]))
+        when "render_site"
+          fragment.at_css(%([data-upkeep-render-site="#{css_escape(target.id)}"]))
+        end
+      end
+
+      def normalize_html(html)
+        parse_html(html).to_html
+      end
+
+      def digest_html(html)
+        Digest::SHA256.hexdigest(normalize_html(html))
+      end
+
+      def frame_id_for(target)
+        target.kind == "render_site" ? "site:#{target.id}" : target.id
+      end
+
+      def css_escape(value)
+        value.to_s.gsub("\\", "\\\\\\").gsub('"', '\"')
+      end
+
+      def parse_html(html)
+        source = html.to_s
+
+        if source.match?(/\A\s*(?:<!doctype\b[^>]*>\s*)?<html[\s>]/i)
+          Nokogiri::HTML5.parse(source)
+        else
+          Nokogiri::HTML5.fragment(source)
+        end
+      end
+    end
+  end
+end

data/lib/upkeep/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Upkeep
+  VERSION = "0.1.6"
+end

data/lib/upkeep-rails.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require "upkeep"

data/lib/upkeep.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+require_relative "upkeep/version"
+require_relative "upkeep/dependencies"
+require_relative "upkeep/dag"
+require_relative "upkeep/replay"
+require_relative "upkeep/active_record_query"
+require_relative "upkeep/runtime"
+require_relative "upkeep/targeting"
+require_relative "upkeep/subscriptions"
+require_relative "upkeep/shared_streams"
+require_relative "upkeep/invalidation"
+require_relative "upkeep/delivery"
+require_relative "upkeep/rails"

data/upkeep-rails.gemspec

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+require_relative "lib/upkeep/version"
+
+Gem::Specification.new do |spec|
+  spec.name = "upkeep-rails"
+  spec.version = Upkeep::VERSION
+  spec.authors = [ "Felipe dos Anjos" ]
+  spec.email = [ "felipe.cavalheiro.anjos@gmail.com" ]
+  spec.license = "MIT"
+
+  spec.summary = "Dependency-tracked live updates for Rails views"
+  spec.description = "Upkeep records the data and identity dependencies used while Rails renders a view, then updates subscribed frames when matching application data changes."
+  spec.homepage = "https://github.com/fc-anjos/upkeep-rails"
+  spec.required_ruby_version = ">= 3.2.0"
+  spec.metadata["homepage_uri"] = spec.homepage
+  spec.metadata["source_code_uri"] = "#{spec.homepage}/tree/main"
+  spec.metadata["bug_tracker_uri"] = "#{spec.homepage}/issues"
+  spec.metadata["rubygems_mfa_required"] = "true"
+
+  internal_files = Dir[
+    "lib/upkeep/probes/**/*.rb",
+    "lib/upkeep/proofs/**/*.rb"
+  ] + %w[
+    lib/upkeep/domain.rb
+    lib/upkeep/herb/fallback_analyzer.rb
+    lib/upkeep/herb/performance_gate.rb
+    lib/upkeep/herb/runtime_alignment.rb
+    lib/upkeep/proof_support.rb
+    lib/upkeep/rendering.rb
+    lib/upkeep/templates.rb
+  ]
+
+  spec.files = (Dir[
+    "README.md",
+    "LICENSE.txt",
+    "upkeep-rails.gemspec",
+    "docs/**/*.md",
+    "lib/**/*.rb",
+    "lib/generators/**/templates/**/*"
+  ] - internal_files).sort
+  spec.require_paths = [ "lib" ]
+
+  spec.add_dependency "actionview", ">= 7.1", "< 9.0"
+  spec.add_dependency "actionpack", ">= 7.1", "< 9.0"
+  spec.add_dependency "actioncable", ">= 7.1", "< 9.0"
+  spec.add_dependency "activejob", ">= 7.1", "< 9.0"
+  spec.add_dependency "activerecord", ">= 7.1", "< 9.0"
+  spec.add_dependency "activesupport", ">= 7.1", "< 9.0"
+  spec.add_dependency "herb", ">= 0.10.1", "< 0.11"
+  spec.add_dependency "nokogiri", ">= 1.15", "< 2.0"
+  spec.add_dependency "railties", ">= 7.1", "< 9.0"
+  spec.add_dependency "turbo-rails", ">= 2.0", "< 3.0"
+end

metadata

@@ -0,0 +1,320 @@
+--- !ruby/object:Gem::Specification
+name: upkeep-rails
+version: !ruby/object:Gem::Version
+  version: 0.1.6
+platform: ruby
+authors:
+- Felipe dos Anjos
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: actionview
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9.0'
+- !ruby/object:Gem::Dependency
+  name: actionpack
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9.0'
+- !ruby/object:Gem::Dependency
+  name: actioncable
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9.0'
+- !ruby/object:Gem::Dependency
+  name: activejob
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9.0'
+- !ruby/object:Gem::Dependency
+  name: activerecord
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9.0'
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9.0'
+- !ruby/object:Gem::Dependency
+  name: herb
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.10.1
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '0.11'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.10.1
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '0.11'
+- !ruby/object:Gem::Dependency
+  name: nokogiri
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.15'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.15'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: railties
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9.0'
+- !ruby/object:Gem::Dependency
+  name: turbo-rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+description: Upkeep records the data and identity dependencies used while Rails renders
+  a view, then updates subscribed frames when matching application data changes.
+email:
+- felipe.cavalheiro.anjos@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE.txt
+- README.md
+- docs/architecture/ambient-inputs-roadmap.md
+- docs/architecture/herb-roadmap.md
+- docs/architecture/identity-and-sharing.md
+- docs/architecture/query-dependencies.md
+- docs/architecture/subscription-store-contract.md
+- docs/cost-model-roadmap.md
+- docs/guides/getting-started.md
+- docs/handoff-2026-05-15.md
+- docs/production_roadmap.md
+- docs/shared-warm-scale-roadmap.md
+- docs/single-subscriber-cold-roadmap.md
+- docs/stress-test-findings.md
+- docs/testing.md
+- lib/generators/upkeep/install/install_generator.rb
+- lib/generators/upkeep/install/templates/create_upkeep_subscriptions.rb.erb
+- lib/generators/upkeep/install/templates/subscription.js
+- lib/generators/upkeep/install/templates/upkeep.rb
+- lib/upkeep-rails.rb
+- lib/upkeep.rb
+- lib/upkeep/active_record_query.rb
+- lib/upkeep/capture/request.rb
+- lib/upkeep/dag.rb
+- lib/upkeep/dag/subscription_shape.rb
+- lib/upkeep/delivery.rb
+- lib/upkeep/delivery/action_cable_adapter.rb
+- lib/upkeep/delivery/async_dispatcher.rb
+- lib/upkeep/delivery/broadcast_transport.rb
+- lib/upkeep/delivery/transport.rb
+- lib/upkeep/delivery/turbo_streams.rb
+- lib/upkeep/dependencies.rb
+- lib/upkeep/herb/developer_report.rb
+- lib/upkeep/herb/manifest_cache.rb
+- lib/upkeep/herb/manifest_diff.rb
+- lib/upkeep/herb/source_instrumenter.rb
+- lib/upkeep/herb/template_manifest.rb
+- lib/upkeep/invalidation.rb
+- lib/upkeep/invalidation/collection_append.rb
+- lib/upkeep/invalidation/collection_member_replace.rb
+- lib/upkeep/invalidation/collection_prepend.rb
+- lib/upkeep/invalidation/collection_remove.rb
+- lib/upkeep/invalidation/planner.rb
+- lib/upkeep/rails.rb
+- lib/upkeep/rails/action_view_capture.rb
+- lib/upkeep/rails/activation_token.rb
+- lib/upkeep/rails/cable.rb
+- lib/upkeep/rails/cable/channel.rb
+- lib/upkeep/rails/cable/subscriber_identity.rb
+- lib/upkeep/rails/client_subscription.rb
+- lib/upkeep/rails/configuration.rb
+- lib/upkeep/rails/controller_runtime.rb
+- lib/upkeep/rails/delivery_job.rb
+- lib/upkeep/rails/install.rb
+- lib/upkeep/rails/railtie.rb
+- lib/upkeep/rails/replay.rb
+- lib/upkeep/rails/testing.rb
+- lib/upkeep/replay.rb
+- lib/upkeep/runtime.rb
+- lib/upkeep/shared_streams.rb
+- lib/upkeep/subscriptions.rb
+- lib/upkeep/subscriptions/active_record_store.rb
+- lib/upkeep/subscriptions/active_record_subscription_persistence.rb
+- lib/upkeep/subscriptions/active_registry.rb
+- lib/upkeep/subscriptions/async_durable_writer.rb
+- lib/upkeep/subscriptions/json_snapshot.rb
+- lib/upkeep/subscriptions/layered_reverse_index.rb
+- lib/upkeep/subscriptions/persistent_reverse_index.rb
+- lib/upkeep/subscriptions/registrar.rb
+- lib/upkeep/subscriptions/reverse_index.rb
+- lib/upkeep/subscriptions/shape.rb
+- lib/upkeep/subscriptions/store.rb
+- lib/upkeep/targeting.rb
+- lib/upkeep/version.rb
+- upkeep-rails.gemspec
+homepage: https://github.com/fc-anjos/upkeep-rails
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/fc-anjos/upkeep-rails
+  source_code_uri: https://github.com/fc-anjos/upkeep-rails/tree/main
+  bug_tracker_uri: https://github.com/fc-anjos/upkeep-rails/issues
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: Dependency-tracked live updates for Rails views
+test_files: []