upkeep-rails 0.1.6

data/lib/generators/upkeep/install/install_generator.rb

@@ -0,0 +1,127 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+require "rails/generators/active_record"
+require "pathname"
+
+module Upkeep
+  class InstallGenerator < ::Rails::Generators::Base
+    include ::Rails::Generators::Migration
+
+    source_root File.expand_path("templates", __dir__)
+
+    def self.next_migration_number(dirname)
+      ActiveRecord::Generators::Base.next_migration_number(dirname)
+    end
+
+    def create_subscription_migration
+      return if migration_exists?("create_upkeep_subscriptions")
+
+      @migration_version = ActiveRecord::Migration.current_version
+      migration_template "create_upkeep_subscriptions.rb.erb", "db/migrate/create_upkeep_subscriptions.rb"
+    end
+
+    def create_initializer
+      template "upkeep.rb", "config/initializers/upkeep.rb"
+    end
+
+    def create_browser_bootstrap
+      template "subscription.js", "app/javascript/upkeep/subscription.js"
+      append_application_import
+      pin_action_cable
+    end
+
+    def mount_action_cable
+      return if routes_path.exist? && routes_path.read.include?("ActionCable.server")
+
+      route %(mount ActionCable.server => "/cable")
+    end
+
+    def show_identity_setup_guidance
+      usages = detected_identity_usages
+      return if usages.empty?
+
+      say "\nIdentity setup required", :yellow
+      say "Upkeep found request-side identity usage:"
+      usages.each { |usage| say "  #{usage}" }
+      say "Upkeep does not infer subscriber identity by naming convention."
+      say "Add an explicit Upkeep::Rails.configure identity mapping in config/initializers/upkeep.rb."
+      say "Pages that depend on undeclared non-absent CurrentAttributes or Warden identities are refused for live updates."
+      say ""
+    end
+
+    private
+
+    def migration_exists?(name)
+      Dir.glob(destination_path("db/migrate/*.rb")).any? do |path|
+        File.basename(path).include?(name)
+      end
+    end
+
+    def append_application_import
+      return unless application_js_path.exist?
+
+      append_import("@hotwired/turbo-rails")
+      append_import("upkeep/subscription")
+    end
+
+    def pin_action_cable
+      return unless importmap_path.exist?
+
+      pin_importmap("@hotwired/turbo-rails", "turbo.min.js")
+      pin_importmap("@rails/actioncable", "actioncable.esm.js")
+      pin_importmap("upkeep/subscription", "upkeep/subscription.js")
+    end
+
+    def append_import(specifier)
+      return if application_js_path.read.include?(specifier)
+
+      append_to_file application_js_path.to_s, %(import "#{specifier}"\n)
+    end
+
+    def pin_importmap(specifier, asset)
+      return if importmap_path.read.include?(%("#{specifier}"))
+
+      append_to_file importmap_path.to_s, %(pin "#{specifier}", to: "#{asset}"\n)
+    end
+
+    def detected_identity_usages
+      usages = []
+      source = application_source
+      usages << "Current.user" if source.match?(/\bCurrent\.user\b/)
+      usages << "session[:user_id]" if source.match?(/\bsession\[(?::user_id|['"]user_id['"])\]/)
+      usages << "warden.user" if source.match?(/\bwarden\.user\b/)
+      usages.uniq
+    end
+
+    def application_source
+      app_paths.filter_map do |path|
+        File.read(path)
+      rescue StandardError
+        nil
+      end.join("\n")
+    end
+
+    def app_paths
+      Dir.glob(destination_path("app/**/*")).select do |path|
+        File.file?(path) && %w[.rb .erb].include?(File.extname(path))
+      end
+    end
+
+    def routes_path
+      Pathname(destination_path("config/routes.rb"))
+    end
+
+    def application_js_path
+      Pathname(destination_path("app/javascript/application.js"))
+    end
+
+    def importmap_path
+      Pathname(destination_path("config/importmap.rb"))
+    end
+
+    def destination_path(path)
+      File.join(destination_root, path)
+    end
+  end
+end

data/lib/generators/upkeep/install/templates/create_upkeep_subscriptions.rb.erb

@@ -0,0 +1,49 @@
+class CreateUpkeepSubscriptions < ActiveRecord::Migration[<%= @migration_version %>]
+  def change
+    create_table :upkeep_subscriptions, id: :string do |t|
+      t.string :subscriber_id, null: false
+      t.json :recorder_snapshot, null: false
+      t.json :metadata
+      t.string :subscription_shape_key
+      t.timestamps
+    end
+    add_index :upkeep_subscriptions, :subscriber_id
+    add_index :upkeep_subscriptions, :subscription_shape_key, name: "idx_upkeep_subscriptions_on_shape_key"
+
+    create_table :upkeep_subscription_index_entries do |t|
+      t.string :subscription_id, null: false
+      t.string :lookup_key_digest, null: false
+      t.string :dependency_source, null: false
+      t.string :lookup_table, null: false
+      t.json :lookup_record_id_snapshot
+      t.string :lookup_attribute, null: false
+      t.string :dependency_table, null: false
+      t.string :dependency_predicate_digest
+      t.json :dependency_metadata_snapshot
+      t.json :owner_ids_snapshot, null: false
+      t.timestamps
+    end
+    add_index :upkeep_subscription_index_entries, :subscription_id
+    add_index :upkeep_subscription_index_entries, :lookup_key_digest
+    add_foreign_key :upkeep_subscription_index_entries,
+      :upkeep_subscriptions,
+      column: :subscription_id,
+      on_delete: :cascade
+
+    create_table :upkeep_subscription_shape_index_entries do |t|
+      t.string :subscription_shape_key, null: false
+      t.string :lookup_key_digest, null: false
+      t.string :dependency_source, null: false
+      t.string :lookup_table, null: false
+      t.json :lookup_record_id_snapshot
+      t.string :lookup_attribute, null: false
+      t.string :dependency_table, null: false
+      t.string :dependency_predicate_digest
+      t.json :dependency_metadata_snapshot
+      t.json :owner_ids_snapshot, null: false
+      t.timestamps
+    end
+    add_index :upkeep_subscription_shape_index_entries, :subscription_shape_key, name: "idx_upkeep_sub_shape_entries_on_shape_key"
+    add_index :upkeep_subscription_shape_index_entries, :lookup_key_digest, name: "idx_upkeep_sub_shape_entries_on_lookup_digest"
+  end
+end

data/lib/generators/upkeep/install/templates/subscription.js

@@ -0,0 +1,99 @@
+import { createConsumer } from "@rails/actioncable"
+import { Turbo } from "@hotwired/turbo-rails"
+
+const SOURCE_ELEMENT = "upkeep-subscription-source"
+const SOURCE_SELECTOR = `${SOURCE_ELEMENT}[data-upkeep-subscription]`
+
+let consumer
+
+function cableConsumer() {
+  consumer ||= createConsumer()
+  return consumer
+}
+
+function parsePayload(element) {
+  try {
+    return JSON.parse(element.textContent || "{}")
+  } catch {
+    return {}
+  }
+}
+
+function renderStreamMessage(data) {
+  if (Turbo?.renderStreamMessage) {
+    Turbo.renderStreamMessage(String(data))
+  }
+}
+
+class UpkeepSubscriptionSourceElement extends HTMLElement {
+  connectedCallback() {
+    this.connectStreamSource()
+    this.subscribe()
+  }
+
+  disconnectedCallback() {
+    this.unsubscribe()
+    this.disconnectStreamSource()
+  }
+
+  connectStreamSource() {
+    if (this.streamSourceConnected) return
+    if (!Turbo?.session?.connectStreamSource) return
+
+    Turbo.session.connectStreamSource(this)
+    this.streamSourceConnected = true
+  }
+
+  disconnectStreamSource() {
+    if (!this.streamSourceConnected) return
+
+    Turbo.session.disconnectStreamSource(this)
+    this.streamSourceConnected = false
+  }
+
+  subscribe() {
+    const payload = parsePayload(this)
+    if (!payload.subscription_id || this.subscription) return
+
+    this.subscription = cableConsumer().subscriptions.create(
+      {
+        channel: payload.channel || "Upkeep::Rails::Cable::Channel",
+        subscription_id: payload.subscription_id,
+        activation_token: payload.activation_token
+      },
+      {
+        received: (data) => this.receive(data),
+
+        rejected: () => {
+          console.error(
+            "[upkeep] subscription rejected by the server; refresh app/javascript/upkeep/subscription.js if this started after upgrading upkeep-rails",
+            { subscription_id: payload.subscription_id, channel: payload.channel || "Upkeep::Rails::Cable::Channel" }
+          )
+        }
+      }
+    )
+  }
+
+  unsubscribe() {
+    if (!this.subscription) return
+
+    this.subscription.unsubscribe()
+    this.subscription = null
+  }
+
+  receive(data) {
+    if (this.streamSourceConnected) {
+      this.dispatchEvent(new MessageEvent("message", { data: String(data) }))
+    } else {
+      renderStreamMessage(data)
+    }
+  }
+}
+
+if (!customElements.get(SOURCE_ELEMENT)) {
+  customElements.define(SOURCE_ELEMENT, UpkeepSubscriptionSourceElement)
+}
+
+export function connectUpkeepSubscriptions() {
+  document.querySelectorAll(SOURCE_SELECTOR).forEach((source) => source.subscribe?.())
+}

data/lib/generators/upkeep/install/templates/upkeep.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+Upkeep::Rails.configure do |config|
+  app_config = Rails.application.config.upkeep
+
+  config.enabled = app_config.fetch(:enabled, true)
+  config.subscription_store = app_config.fetch(:subscription_store, Rails.env.test? ? :memory : :active_record)
+  config.delivery_adapter = app_config.fetch(:delivery_adapter, Rails.env.production? ? :active_job : :async)
+  config.delivery_queue = app_config.fetch(:delivery_queue, :upkeep_realtime)
+
+  # Delivery setup:
+  # Upkeep uses Active Job for committed-change delivery in production and async
+  # in development/test. Configure your app's Active Job backend normally
+  # (Solid Queue, Sidekiq, GoodJob, etc.) and configure ActionCable with a shared
+  # adapter such as Solid Cable, Redis, or PostgreSQL so worker broadcasts can
+  # reach web socket connections.
+  #
+  # Test setup:
+  # The generated test default is the in-process memory store. It follows the
+  # same subscription lifecycle as ActiveRecord without requiring subscription
+  # tables in every app test database. Keep at least one app/CI path on
+  # :active_record when you want to exercise durable subscription rows.
+  #
+  # View setup:
+  # No per-template annotations are required for ordinary Rails views. Upkeep
+  # instruments Action View templates as they render and adds the internal
+  # markers it needs for page roots, fragment roots, and safe partial collection
+  # render-site containers. Keep rendering normal ERB and collection partials:
+  #
+  # <ul>
+  #   <%%= render partial: "cards/card", collection: @cards, as: :card %>
+  # </ul>
+  #
+  # The upkeep_frame helper remains available for advanced/generated boundaries
+  # that cannot be derived from template source, but it is not part of normal
+  # application setup.
+
+  # Identity setup:
+  # Upkeep does not infer subscriber identity by naming convention. Declare each
+  # identity boundary that should partition live updates, and resolve the same
+  # boundary from ActionCable when the browser subscribes.
+  #
+  # Example for Current.user plus ApplicationCable identified_by :current_user:
+  #
+  # config.identify :viewer, current: ["Current", :user] do
+  #   subscribe { |connection| connection.current_user }
+  # end
+  #
+  # Example for Devise/Warden current_user:
+  #
+  # config.identify :viewer, warden: :user do
+  #   subscribe { |connection| connection.current_user }
+  # end
+  #
+  # Example for session-backed authentication:
+  #
+  # config.identify :viewer, session: :user_id do
+  #   # nil means this identity boundary is absent. Use absent_if for any
+  #   # additional app-specific sentinel, such as false or "guest".
+  #   # absent_if { |value| value.nil? || value == false }
+  #   subscribe { |connection| connection.session[:user_id] }
+  # end
+end

data/lib/upkeep/active_record_query.rb

@@ -0,0 +1,294 @@
+# frozen_string_literal: true
+
+require "active_record"
+
+module Upkeep
+  module ActiveRecordQuery
+    class OpaqueRelationError < StandardError
+      attr_reader :model_name, :table_name, :sql, :reasons
+
+      def initialize(relation, reasons:)
+        @model_name = relation.klass.name
+        @table_name = relation.klass.table_name
+        @sql = relation.to_sql
+        @reasons = reasons
+
+        super(build_message)
+      rescue StandardError => error
+        super("Upkeep cannot prove this Active Record relation's structural dependencies: #{error.message}")
+      end
+
+      private
+
+      def build_message
+        <<~MESSAGE
+          Upkeep cannot make this Active Record relation reactive because its query shape is opaque.
+
+          Relation:
+            #{model_name} (#{table_name})
+
+          SQL:
+            #{sql}
+
+          Why:
+          #{reasons.map { |reason| "            - #{reason}" }.join("\n")}
+
+          What to do:
+            - Rewrite raw SQL predicates with structural Active Record hash or Arel predicates.
+            - Rewrite raw SQL joins or FROM sources with structural Active Record/Arel joins.
+            - Render this boundary outside Upkeep reactivity when the query cannot expose its sources.
+        MESSAGE
+      end
+
+      public
+
+      def suggestions
+        [
+          "Rewrite raw SQL predicates with structural Active Record hash or Arel predicates.",
+          "Rewrite raw SQL joins or FROM sources with structural Active Record/Arel joins.",
+          "Render this boundary outside Upkeep reactivity when the query cannot expose its sources."
+        ]
+      end
+    end
+
+    Result = Data.define(
+      :primary_table,
+      :table_columns,
+      :coverage,
+      :sql,
+      :primary_key,
+      :appendable,
+      :limit_value,
+      :predicates
+    ) do
+      def tables = table_columns.keys.sort
+
+      def appendable?
+        appendable
+      end
+    end
+
+    module_function
+
+    def analyze(relation, opaque_table_policy: :raise)
+      collector = Collector.new(relation, opaque_table_policy: opaque_table_policy)
+      collector.analyze
+    end
+
+    class Collector
+      def initialize(relation, opaque_table_policy:)
+        @relation = relation
+        @opaque_table_policy = opaque_table_policy
+        @primary_table = relation.klass.table_name
+        @primary_key = relation.klass.primary_key
+        @table_columns = Hash.new { |hash, table| hash[table] = [] }
+        @table_aliases = {}
+        @opaque_columns = false
+        @opaque_tables = false
+        @opaque_table_reasons = []
+        @opaque_column_reasons = []
+        @predicates = []
+      end
+
+      def analyze
+        table(@primary_table)
+        collect_relation_shape
+        raise_opaque_relation! if opaque_relation? && @opaque_table_policy == :raise
+
+        Result.new(
+          primary_table: @primary_table,
+          table_columns: normalized_table_columns,
+          coverage: coverage,
+          sql: safe_sql,
+          primary_key: @primary_key,
+          appendable: appendable_relation?,
+          limit_value: @relation.limit_value,
+          predicates: normalized_predicates
+        )
+      end
+
+      private
+
+      def collect_relation_shape
+        ast = @relation.arel.ast
+
+        ast.cores.each do |core|
+          walk(core.source, source: true)
+          walk(core.wheres)
+          walk(core.groups)
+          walk(core.havings)
+        end
+
+        walk(ast.orders)
+        walk(ast.with) if ast.respond_to?(:with)
+      rescue StandardError => error
+        opaque_table!("relation AST could not be inspected (#{error.class}: #{error.message})")
+      end
+
+      def coverage
+        return :tables if @opaque_tables || @opaque_columns
+
+        :columns
+      end
+
+      def normalized_table_columns
+        table(@primary_table)
+        column(@primary_table, @primary_key) if @primary_key
+
+        @table_columns.transform_values { |columns| columns.compact.uniq.sort }.sort.to_h
+      end
+
+      def appendable_relation?
+        return false unless coverage == :columns
+        return false if @opaque_tables
+        return false if @relation.limit_value || @relation.offset_value
+        return false if @relation.distinct_value
+        return false if @relation.group_values.any?
+        return false if !@relation.having_clause.empty?
+
+        true
+      end
+
+      def walk(value, source: false)
+        case value
+        when nil, true, false, Numeric, Symbol, Class, Module
+          nil
+        when Array
+          value.each { |entry| walk(entry, source: source) }
+        when Hash
+          value.each_value { |entry| walk(entry, source: source) }
+        when Arel::Attributes::Attribute
+          attribute(value)
+        when Arel::Nodes::Equality
+          equality_predicate(value)
+          walk_arel_node(value, source: source)
+        when Arel::Nodes::HomogeneousIn
+          homogeneous_in_predicate(value)
+          walk_arel_node(value, source: source)
+        when Arel::Table
+          table(value.name)
+        when Arel::Nodes::TableAlias
+          table_alias(value)
+        when Arel::Nodes::StringJoin
+          opaque_table!("raw SQL join")
+        when Arel::Nodes::BoundSqlLiteral, Arel::Nodes::SqlLiteral
+          source ? opaque_table!("raw SQL source") : opaque_column!("raw SQL predicate or order expression")
+        when String
+          source ? opaque_table!("string SQL source") : opaque_column!("string SQL predicate or order expression")
+        else
+          walk_arel_node(value, source: source)
+        end
+      end
+
+      def walk_arel_node(value, source:)
+        return unless value.is_a?(Arel::Nodes::Node)
+
+        value.instance_variables.each do |ivar|
+          walk(value.instance_variable_get(ivar), source: source)
+        end
+      end
+
+      def attribute(value)
+        table_name = table_name_for(value.relation)
+        return opaque_table!("attribute references an unknown table source") unless table_name
+        return if value.name.to_s == "*"
+
+        column(table_name, value.name)
+      end
+
+      def table_name_for(relation)
+        if relation.is_a?(Arel::Nodes::TableAlias)
+          table_name_for(relation.left)
+        elsif relation.respond_to?(:name)
+          name = relation.name.to_s
+          @table_aliases.fetch(name, name)
+        elsif relation.respond_to?(:left)
+          table_name_for(relation.left)
+        end
+      end
+
+      def table_alias(value)
+        table_name = table_name_for(value.left)
+        return opaque_table!("table alias references an unknown table source") unless table_name
+
+        @table_aliases[value.right.to_s] = table_name
+        table(table_name)
+      end
+
+      def opaque_table!(reason)
+        @opaque_tables = true
+        @opaque_table_reasons << reason
+      end
+
+      def opaque_column!(reason)
+        @opaque_columns = true
+        @opaque_column_reasons << reason
+      end
+
+      def opaque_relation?
+        @opaque_tables || @opaque_columns
+      end
+
+      def raise_opaque_relation!
+        raise OpaqueRelationError.new(@relation, reasons: (@opaque_table_reasons + @opaque_column_reasons).uniq)
+      end
+
+      def table(name)
+        @table_columns[name.to_s]
+      end
+
+      def column(table_name, column_name)
+        @table_columns[table_name.to_s] << column_name.to_s
+      end
+
+      def equality_predicate(node)
+        predicate = predicate_for(node.left, "eq", [predicate_value(node.right)])
+        @predicates << predicate if predicate
+      end
+
+      def homogeneous_in_predicate(node)
+        predicate = predicate_for(node.attribute, "in", Array(node.values).map { |value| predicate_value(value) })
+        @predicates << predicate if predicate
+      end
+
+      def predicate_for(attribute, operator, values)
+        return unless attribute.is_a?(Arel::Attributes::Attribute)
+
+        table_name = table_name_for(attribute.relation)
+        return unless table_name
+
+        values = values.compact
+        return if values.empty?
+
+        {
+          table: table_name.to_s,
+          column: attribute.name.to_s,
+          operator: operator,
+          values: values.uniq
+        }
+      end
+
+      def predicate_value(value)
+        if value.respond_to?(:value_for_database)
+          value.value_for_database
+        elsif value.respond_to?(:value)
+          value.value
+        elsif value.nil? || value.is_a?(String) || value.is_a?(Numeric) || value == true || value == false || value.is_a?(Symbol)
+          value
+        end
+      end
+
+      def normalized_predicates
+        @predicates
+          .uniq
+          .sort_by { |predicate| [predicate.fetch(:table), predicate.fetch(:column), predicate.fetch(:operator), predicate.fetch(:values).inspect] }
+      end
+
+      def safe_sql
+        @relation.to_sql
+      rescue StandardError => error
+        "#{error.class}: #{error.message}"
+      end
+    end
+  end
+end