upkeep-rails 0.1.9

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