upkeep-rails 0.2.5-aarch64-linux-gnu

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

@@ -0,0 +1,192 @@
+# 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__)
+
+    SOLID_CABLE_DEVELOPMENT_BLOCK = <<~YAML
+      development:
+        adapter: solid_cable
+        connects_to:
+          database:
+            writing: cable
+        polling_interval: 0.1.seconds
+        message_retention: 1.day
+    YAML
+
+    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 configure_development_cable_adapter
+      unless solid_cable_in_gemfile?
+        show_solid_cable_guidance
+        return
+      end
+      return unless cable_config_path.exist?
+
+      content = cable_config_path.read
+      block = development_cable_block(content)
+      return if block&.include?("solid_cable")
+
+      updated = if block
+        content.sub(block, "#{SOLID_CABLE_DEVELOPMENT_BLOCK}\n")
+      else
+        "#{SOLID_CABLE_DEVELOPMENT_BLOCK}\n#{content}"
+      end
+      File.write(cable_config_path, updated)
+      say "Updated config/cable.yml development to the solid_cable adapter."
+      say "Ensure config/database.yml defines a cable database for development and loads db/cable_schema.rb."
+    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 solid_cable_in_gemfile?
+      gemfile_path.exist? && gemfile_path.read.match?(/^\s*gem\s+["']solid_cable["']/)
+    end
+
+    def development_cable_block(content)
+      content[/^development:\n(?:(?:[ \t].*)?\n)*/]
+    end
+
+    def show_solid_cable_guidance
+      say "\nAction Cable adapter", :yellow
+      say "Upkeep delivers live updates through standard Action Cable broadcasts."
+      say "The async development cable adapter is in-process only; with a clustered server"
+      say "(puma workers > 0), broadcasts from one process never reach browsers connected to another."
+      say "Add solid_cable and point config/cable.yml development at it:"
+      say "  bundle add solid_cable"
+      say "  bin/rails solid_cable:install"
+      say "  bin/rails db:prepare"
+      say ""
+    end
+
+    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?
+
+      upkeep_specifier = importmap_path.exist? ? "upkeep/subscription" : "./upkeep/subscription"
+      content = application_js_path.read
+        .gsub(/^import ["'](?:\.\/)?upkeep\/subscription["']\s*\n?/, "")
+
+      turbo_import = /^import ["']@hotwired\/turbo-rails["']\s*$/
+      if (match = content.match(turbo_import))
+        content.insert(match.begin(0), %(import "#{upkeep_specifier}"\n))
+      else
+        content << "\n" unless content.empty? || content.end_with?("\n")
+        content << %(import "#{upkeep_specifier}"\n)
+        content << %(import "@hotwired/turbo-rails"\n)
+      end
+
+      File.write(application_js_path, content)
+    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 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 gemfile_path
+      Pathname(destination_path("Gemfile"))
+    end
+
+    def cable_config_path
+      Pathname(destination_path("config/cable.yml"))
+    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,288 @@
+import { createConsumer } from "@rails/actioncable"
+
+const SOURCE_ELEMENT = "upkeep-subscription-source"
+const SOURCE_SELECTOR = `${SOURCE_ELEMENT}[data-upkeep-subscription]`
+const ID_HEADER = "X-Upkeep-Subscription-Id"
+const TOKEN_HEADER = "X-Upkeep-Subscription-Token"
+const CHANNEL_HEADER = "X-Upkeep-Subscription-Channel"
+const STREAM_HEADER = "X-Upkeep-Subscription-Stream"
+const ACTION_HEADER = "X-Upkeep-Subscription-Action"
+
+let consumer
+let activeFrame
+const queuedFrames = []
+
+function cableConsumer() {
+  consumer ||= createConsumer()
+  return consumer
+}
+
+function sourceElement() {
+  return document.querySelector(SOURCE_SELECTOR)
+}
+
+function ensureSourceElement() {
+  const existing = sourceElement()
+  if (existing) return existing
+  if (!document.body) return
+
+  const source = document.createElement(SOURCE_ELEMENT)
+  source.id = "upkeep-subscription-source"
+  source.hidden = true
+  source.style.display = "none"
+  source.setAttribute("data-upkeep-subscription", "")
+  document.body.append(source)
+  return source
+}
+
+function parsePayload(element) {
+  return {
+    channel: element.getAttribute("channel"),
+    subscription_id: element.getAttribute("subscription-id"),
+    activation_token: element.getAttribute("activation-token"),
+    stream_name: element.getAttribute("stream-name")
+  }
+}
+
+function responsePayload(fetchResponse) {
+  const headers = fetchResponse?.response?.headers
+  const subscriptionId = headers?.get(ID_HEADER)
+  if (!subscriptionId) return
+
+  return {
+    channel: headers.get(CHANNEL_HEADER),
+    subscription_id: subscriptionId,
+    activation_token: headers.get(TOKEN_HEADER),
+    stream_name: headers.get(STREAM_HEADER)
+  }
+}
+
+function setHeader(headers, name, value) {
+  if (headers?.set) {
+    headers.set(name, value)
+  } else {
+    headers[name] = value
+  }
+}
+
+function addSubscriptionHeaders(fetchOptions) {
+  const source = sourceElement()
+  if (!source) return
+
+  const payload = parsePayload(source)
+  if (!payload.subscription_id || !payload.activation_token) return
+
+  setHeader(fetchOptions.headers, ID_HEADER, payload.subscription_id)
+  setHeader(fetchOptions.headers, TOKEN_HEADER, payload.activation_token)
+}
+
+function beginFrameFetch(event) {
+  const frame = event.target
+  if (frame?.tagName !== "TURBO-FRAME") return
+
+  const start = () => {
+    activeFrame = frame
+    addSubscriptionHeaders(event.detail.fetchOptions)
+    event.detail.resume?.()
+  }
+
+  if (activeFrame && activeFrame !== frame) {
+    event.preventDefault()
+    queuedFrames.push(start)
+  } else {
+    activeFrame = frame
+    addSubscriptionHeaders(event.detail.fetchOptions)
+  }
+}
+
+function finishFrameFetch(frame) {
+  if (activeFrame !== frame) return
+
+  activeFrame = null
+  queuedFrames.shift()?.()
+}
+
+function resetFrameFetches() {
+  activeFrame = null
+  queuedFrames.splice(0)
+}
+
+function reloadPage() {
+  window.Turbo?.visit(window.location.href, { action: "replace", shouldCacheSnapshot: false })
+}
+
+function renderStreamMessage(data) {
+  if (window.Turbo?.renderStreamMessage) {
+    window.Turbo.renderStreamMessage(String(data))
+  }
+}
+
+function assertTurboCompatibility() {
+  const turbo = window.Turbo
+  if (!turbo || turbo.StreamActions?.refresh) return
+
+  throw new Error("Upkeep requires Turbo 8 or newer")
+}
+
+class UpkeepSubscriptionSourceElement extends HTMLElement {
+  connectedCallback() {
+    this.connectStreamSource()
+    this.subscribe()
+  }
+
+  disconnectedCallback() {
+    this.transitionGeneration = (this.transitionGeneration || 0) + 1
+    this.candidateSubscription?.unsubscribe()
+    this.candidateSubscription = null
+    this.unsubscribe()
+    this.disconnectStreamSource()
+    this.removeAttribute("connected")
+  }
+
+  connectStreamSource() {
+    if (this.streamSourceConnected) return
+    if (!window.Turbo?.session?.connectStreamSource) return
+
+    window.Turbo.session.connectStreamSource(this)
+    this.streamSourceConnected = true
+  }
+
+  disconnectStreamSource() {
+    if (!this.streamSourceConnected) return
+
+    window.Turbo.session.disconnectStreamSource(this)
+    this.streamSourceConnected = false
+  }
+
+  subscribe() {
+    const payload = parsePayload(this)
+    if (!payload.subscription_id || this.subscription) return
+
+    this.subscription = this.createSubscription(payload, {
+      connected: () => this.setAttribute("connected", ""),
+      disconnected: () => this.removeAttribute("connected")
+    })
+  }
+
+  replaceSubscription(payload, { connected, rejected } = {}) {
+    if (!payload?.subscription_id) return
+    if (payload.subscription_id === parsePayload(this).subscription_id) {
+      connected?.()
+      return
+    }
+
+    const generation = (this.transitionGeneration || 0) + 1
+    this.transitionGeneration = generation
+    this.candidateSubscription?.unsubscribe()
+
+    let candidate
+    candidate = this.createSubscription(payload, {
+      connected: () => {
+        if (this.transitionGeneration !== generation || !this.isConnected) {
+          candidate.unsubscribe()
+          return
+        }
+
+        const previous = this.subscription
+        this.subscription = candidate
+        this.candidateSubscription = null
+        this.applyPayload(payload)
+        this.setAttribute("connected", "")
+        previous?.unsubscribe()
+        connected?.()
+      },
+      rejected: () => {
+        if (this.transitionGeneration !== generation) return
+
+        this.candidateSubscription = null
+        rejected?.()
+      }
+    })
+    this.candidateSubscription = candidate
+  }
+
+  createSubscription(payload, callbacks = {}) {
+    const channel = payload.channel || "Upkeep::Rails::Cable::Channel"
+
+    return cableConsumer().subscriptions.create(
+      {
+        channel,
+        subscription_id: payload.subscription_id,
+        activation_token: payload.activation_token
+      },
+      {
+        connected: callbacks.connected,
+        disconnected: callbacks.disconnected,
+        received: (data) => this.receive(data),
+
+        rejected: () => {
+          console.error(
+            "[upkeep] subscription rejected by the server; the rejection reason is in the server log",
+            { subscription_id: payload.subscription_id, channel }
+          )
+          callbacks.rejected?.()
+        }
+      }
+    )
+  }
+
+  applyPayload(payload) {
+    this.setAttribute("channel", payload.channel || "Upkeep::Rails::Cable::Channel")
+    this.setAttribute("subscription-id", payload.subscription_id)
+    this.setAttribute("activation-token", payload.activation_token)
+    this.setAttribute("stream-name", payload.stream_name || "")
+  }
+
+  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)
+}
+
+ensureSourceElement()
+connectUpkeepSubscriptions()
+document.addEventListener("turbo:before-fetch-request", beginFrameFetch)
+document.addEventListener("turbo:frame-render", (event) => {
+  const source = ensureSourceElement()
+  const fetchResponse = event.detail.fetchResponse
+  const action = fetchResponse?.response?.headers?.get(ACTION_HEADER)
+  const payload = responsePayload(fetchResponse)
+
+  if (action === "reload") {
+    reloadPage()
+  } else if (source && payload) {
+    source.replaceSubscription(payload, {
+      connected: () => finishFrameFetch(event.target),
+      rejected: () => reloadPage()
+    })
+  } else {
+    finishFrameFetch(event.target)
+  }
+})
+document.addEventListener("turbo:fetch-request-error", (event) => finishFrameFetch(event.target))
+document.addEventListener("turbo:frame-missing", (event) => finishFrameFetch(event.target))
+document.addEventListener("turbo:before-visit", resetFrameFetches)
+document.addEventListener("turbo:load", connectUpkeepSubscriptions)
+
+export function connectUpkeepSubscriptions() {
+  assertTurboCompatibility()
+  ensureSourceElement()
+  document.querySelectorAll(SOURCE_SELECTOR).forEach((source) => {
+    source.connectStreamSource?.()
+    source.subscribe?.()
+  })
+}

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

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+Upkeep::Rails.configure do |config|
+  app_config = Rails.application.config.upkeep
+
+  config.enabled = app_config.fetch(:enabled, true)
+  config.request_activation = app_config.fetch(:request_activation, :all)
+  config.subscription_store = app_config.fetch(:subscription_store, Rails.env.test? ? :memory : :active_record)
+  config.deliver_inline = app_config.fetch(:deliver_inline, false)
+
+  # Delivery setup:
+  # Upkeep delivers committed changes on an in-process background dispatcher in
+  # every environment; no job backend is required. Broadcasts are standard
+  # Action Cable broadcasts, so multi-process deployments need a cross-process
+  # cable adapter (we recommend solid_cable) so a write handled by one process
+  # reaches browsers connected to another. Set config.deliver_inline = true in
+  # tests or console sessions that need delivery to run synchronously in the
+  # caller.
+  #
+  # 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