collavre_github 0.6.3 → 0.7.0

data/app/jobs/collavre_github/webhook_delivery_prune_job.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module CollavreGithub
+  # Trims the webhook idempotency ledger. Rows are only useful for as long as
+  # GitHub could still redeliver the same GUID; past that they are dead weight.
+  class WebhookDeliveryPruneJob < ApplicationJob
+    queue_as :default
+
+    def perform
+      deleted = CollavreGithub::WebhookDelivery.prune!
+      Rails.logger.info("[CollavreGithub::WebhookDeliveryPruneJob] pruned #{deleted} rows") if deleted.positive?
+    end
+  end
+end

data/app/models/collavre_github/github_pr_channel.rb

@@ -2,6 +2,8 @@ module CollavreGithub
   class GithubPrChannel < Collavre::Channel
     self.table_name = "channels"
 
+    after_destroy_commit :broadcast_chips_changed
+
     def repo_full_name
       config["repo_full_name"]
     end
@@ -58,6 +60,39 @@ module CollavreGithub
       self.config = config.merge("pr_state" => value)
     end
 
+    # Keep a single monitor when identity repair meets a channel that a user
+    # already attached under the canonical repository name. The explicit
+    # canonical channel survives; topic comments are not owned by channels, so
+    # removing the obsolete routing row loses no timeline content.
+    def synchronize_repository_name!(canonical_full_name)
+      return self if repo_full_name == canonical_full_name
+
+      survivor = self.class
+        .where(topic_id: topic_id, pr_number: pr_number)
+        .where("LOWER(repo_full_name) = ?", canonical_full_name.to_s.downcase)
+        .where.not(id: id)
+        .first
+
+      if survivor
+        if preferred_over?(survivor)
+          self.class.transaction do
+            survivor.destroy!
+            update!(config: config.merge("repo_full_name" => canonical_full_name))
+          end
+          return self
+        end
+
+        survivor.update!(
+          config: survivor.config.merge("repo_full_name" => canonical_full_name)
+        )
+        destroy!
+        survivor
+      else
+        update!(config: config.merge("repo_full_name" => canonical_full_name))
+        self
+      end
+    end
+
     def attached_message
       Collavre::Channel::InjectedMessage.new(
         speaker: channel_bot_user,
@@ -67,6 +102,31 @@ module CollavreGithub
       )
     end
 
+    # Shown when GitHub's delivery could not be authenticated. Renders this
+    # channel's OWN stored repo name, never the rejected payload's — the
+    # payload is unverified by definition at the point this is built.
+    def auth_failure_message
+      Collavre::Channel::InjectedMessage.new(
+        speaker: channel_bot_user,
+        message: t("auth_failure_message", repo: repo_full_name, label: label, url: pr_url),
+        label: label,
+        link: pr_url
+      )
+    end
+
+    # Closing message for `state` (merged / closed_without_merge). Public so
+    # the out-of-band corrector (PrChannelStateUpdater) posts the exact same
+    # text the webhook would have, instead of maintaining a second copy.
+    def closed_message(state = pr_state)
+      verb = state.to_s == "merged" ? t("state_merged") : t("state_closed")
+      Collavre::Channel::InjectedMessage.new(
+        speaker: channel_bot_user,
+        message: t("closed_message", label: label, verb: verb),
+        label: label,
+        link: pr_url
+      )
+    end
+
     def reopened_message
       Collavre::Channel::InjectedMessage.new(
         speaker: channel_bot_user,
@@ -91,11 +151,21 @@ module CollavreGithub
 
     private
 
+    def preferred_over?(other)
+      (lifecycle_priority(self) <=> lifecycle_priority(other)) == 1
+    end
+
+    def lifecycle_priority(channel)
+      [
+        channel.active? ? 1 : 0,
+        channel.dismissed? ? 0 : 1
+      ]
+    end
+
     def handle_pull_request(payload)
       return nil unless payload["action"] == "closed"
       pr = payload["pull_request"]
       new_state = pr["merged"] ? "merged" : "closed_without_merge"
-      verb = pr["merged"] ? t("state_merged") : t("state_closed")
 
       # pr_state is updated atomically with the closing comment: the dispatch
       # path wraps both `handle` and `inject_into_topic!` in a single with_lock
@@ -105,12 +175,7 @@ module CollavreGithub
       self.pr_state = new_state
       save!
 
-      Collavre::Channel::InjectedMessage.new(
-        speaker: channel_bot_user,
-        message: t("closed_message", label: label, verb: verb),
-        label: label,
-        link: pr_url
-      )
+      closed_message(new_state)
       # Detach is performed by the webhook controller AFTER injecting this
       # message, so the chip stays visible until the closing comment lands.
     end

data/app/models/collavre_github/repository_link.rb

@@ -21,6 +21,67 @@ module CollavreGithub
 
     scope :markdown_sync, -> { where(markdown_sync_enabled: true) }
 
+    # Every link for one GitHub repository, matched by its stable id plus
+    # unbackfilled name-only siblings.
+    #
+    # `repository_full_name` is the only key webhook routing used to have, and
+    # it is not stable: renaming a repository on GitHub changes `full_name` in
+    # every subsequent payload with no local event to notice it. The lookup
+    # then found nothing, the controller fell through to a fallback secret that
+    # production does not configure, and every delivery was answered 401 before
+    # dispatch — silently, since the deliveries ledger is only written after
+    # signature verification. `repository.id` does survive a rename, which is
+    # why it is matched first-class here.
+    #
+    # When an id is present, name matching is restricted to NULL-id rows. A
+    # repository linked to two creatives can be half-backfilled (one row
+    # stamped, its sibling still nil), so those legacy siblings must remain in
+    # the fan-out. Rows carrying another id are authoritative links to another
+    # repository, even when GitHub has reused their stored name.
+    def self.for_repository(id:, full_name:)
+      name = full_name.to_s.downcase.presence
+      if id.present?
+        by_id = where(repository_id: id)
+        return by_id unless name
+
+        unbackfilled_by_name = where(repository_id: nil)
+          .where("LOWER(repository_full_name) = ?", name)
+        return by_id.or(unbackfilled_by_name)
+      end
+
+      name ? where("LOWER(repository_full_name) = ?", name) : none
+    end
+
+    # A parent link normally applies to every descendant, but a descendant may
+    # carry its own link for another repository that reused the same name. An
+    # explicit different id proves the conflict; a NULL id is unverified and
+    # must fail closed. In either case, the descendant's channels must not be
+    # renamed through the parent.
+    def self.conflicting_repository_in_scope?(creative:, full_name:, repository_id:)
+      return false if creative.blank? || full_name.blank? || repository_id.blank?
+
+      creative_ids = [ creative.id ] + creative.ancestors.pluck(:id)
+      where(creative_id: creative_ids)
+        .where("LOWER(repository_full_name) = ?", full_name.to_s.downcase)
+        .where("repository_id IS NULL OR repository_id <> ?", repository_id)
+        .exists?
+    end
+
+    # Link mutations affect the link's whole descendant subtree, while an
+    # ancestor link is inherited into the same scope. Before assigning a
+    # canonical name, reject any NULL/different-id row in either direction so
+    # case variants cannot leave both repositories permanently undispatchable.
+    def self.identity_conflict_in_link_scope(creative:, full_name:, repository_id:, excluding_id: nil)
+      return if creative.blank? || full_name.blank? || repository_id.blank?
+
+      creative_ids = creative.subtree_ids + creative.ancestors.pluck(:id)
+      candidates = where(creative_id: creative_ids)
+        .where("LOWER(repository_full_name) = ?", full_name.to_s.downcase)
+        .where("repository_id IS NULL OR repository_id <> ?", repository_id)
+      candidates = candidates.where.not(id: excluding_id) if excluding_id
+      candidates.order(:id).first
+    end
+
     def markdown_sync_branch
       sync_branch.presence || "main"
     end

data/app/models/collavre_github/webhook_delivery.rb

@@ -0,0 +1,159 @@
+module CollavreGithub
+  # Idempotency ledger for inbound GitHub webhook deliveries, keyed by the
+  # `X-GitHub-Delivery` GUID.
+  #
+  # Two independent duplicate sources exist and both reuse the same GUID:
+  #   1. Multiple hooks on one repo (e.g. one per deployed instance sharing this
+  #      database) — GitHub fans the same delivery out to every hook URL. This
+  #      is what makes two hooks a bandwidth cost rather than the duplicate
+  #      processing this ledger exists to stop, so it is load-bearing. The
+  #      reference docs do state it, in one word that is easy to read past:
+  #      `X-GitHub-Delivery` identifies "the event", not the delivery, so every
+  #      destination subscribed to one event receives the same value and
+  #      `X-GitHub-Hook-ID` is what differs. That wording read "the delivery"
+  #      until github/docs#33184 corrected it (2024-05-27), after a GitHub
+  #      engineer confirmed on github/docs#32822 that one event fans out to
+  #      every listener under a single GUID.
+  #   2. Redelivery of a failed delivery. Never automatic: GitHub does not
+  #      retry a 4xx, a 5xx or a >10s timeout, it only records the failure.
+  #      Recovery is an operator pressing Redeliver or a script polling the
+  #      deliveries API, within GitHub's 3-day window — and either way the
+  #      original GUID comes back, which is what brings it here.
+  # A single UNIQUE claim on the GUID collapses both.
+  class WebhookDelivery < ApplicationRecord
+    self.table_name = "github_webhook_deliveries"
+
+    # Rows only exist to answer "have I seen this GUID?" — an updated_at column
+    # would never be written.
+    self.record_timestamps = false
+
+    # Sized against GitHub's redelivery window, which is 3 days: a delivery
+    # older than that can no longer be redelivered at all, so its row can never
+    # be consulted again. 7 days keeps better than 2x margin. Pruning EARLIER
+    # than the window would be the dangerous direction — the GUID would be
+    # claimed as new and every side effect would run a second time.
+    # https://docs.github.com/en/webhooks/testing-and-troubleshooting-webhooks/redelivering-webhooks
+    RETENTION = 7.days
+
+    # How long a claim may sit unprocessed before another delivery of the same
+    # GUID is allowed to take it over. `WebhooksController` releases its claim
+    # on any exception the process survives, so this window only covers a
+    # request that died without running its rescue — SIGKILL, an OOM, a worker
+    # timeout. Without the takeover such a GUID would answer 200 forever and
+    # the operator's Redeliver button would silently do nothing.
+    STALE_CLAIM_AFTER = 5.minutes
+
+    validates :delivery_guid, presence: true
+
+    # Claims the delivery for this process. Returns an ownership token when the
+    # caller owns the delivery and should process it, nil when another request
+    # (another hook, or a redelivery) already claimed it.
+    #
+    # The token, not the GUID, is what `release` and `mark_processed!` act on.
+    # Ownership is not permanent — a run that outlives STALE_CLAIM_AFTER has its
+    # claim taken over — so a caller that acted on the GUID alone would reach
+    # past its own claim and disturb the run that replaced it.
+    #
+    # A blank GUID means the request did not come from GitHub's delivery
+    # pipeline (hand-crafted request, legacy test client). There is nothing to
+    # deduplicate on, so it is allowed through rather than silently dropped —
+    # dropping would turn every unlabelled delivery into a no-op. UNTRACKED
+    # keeps the caller's contract uniform: it is truthy, and the GUID-blank
+    # guard in `release`/`mark_processed!` makes both a no-op for it.
+    UNTRACKED = "untracked".freeze
+
+    def self.claim(delivery_guid, event: nil)
+      return UNTRACKED if delivery_guid.blank?
+
+      insert_claim(delivery_guid, event)
+    end
+
+    # Resolves a collision on the UNIQUE index. Three things can be true of the
+    # row that beat us to it:
+    #
+    #   - it is stale, and `reclaim_stale` takes it over;
+    #   - it is live, so this delivery genuinely is a duplicate;
+    #   - it is GONE, because the request holding it failed and called
+    #     `release` between our INSERT and this lookup. Reporting a duplicate
+    #     then would lose the event outright — that request has already given
+    #     up, so nobody would process it — which is the very outcome the
+    #     ledger exists to prevent. The insert is retried instead.
+    #
+    # One retry suffices: it only has to cover the window opened by that single
+    # release, and bounding it keeps a pathological loop of releases from
+    # spinning here forever.
+    def self.insert_claim(delivery_guid, event, retried: false)
+      token = SecureRandom.uuid
+      create!(
+        delivery_guid: delivery_guid,
+        event: event,
+        claim_token: token,
+        created_at: Time.current
+      )
+      token
+    rescue ActiveRecord::RecordNotUnique
+      reclaimed = reclaim_stale(delivery_guid, event: event)
+      return reclaimed if reclaimed
+      return nil if retried || exists?(delivery_guid: delivery_guid)
+
+      insert_claim(delivery_guid, event, retried: true)
+    end
+    private_class_method :insert_claim
+
+    # Takes over an abandoned claim. A row on its own does not prove the
+    # delivery was handled — only `processed_at` does — so an unprocessed row
+    # older than STALE_CLAIM_AFTER is treated as owner-less.
+    #
+    # Concurrent takeovers resolve to one winner without extra locking: the
+    # UPDATE takes a row lock, and the loser re-evaluates its WHERE against the
+    # committed row, whose `created_at` is no longer stale, so it matches
+    # nothing and reports the delivery as a duplicate.
+    #
+    # The takeover issues a FRESH token, which is what strips ownership from the
+    # run being replaced: its own `release`/`mark_processed!` no longer match.
+    def self.reclaim_stale(delivery_guid, event: nil)
+      token = SecureRandom.uuid
+      updated = where(delivery_guid: delivery_guid, processed_at: nil)
+        .where(created_at: ...STALE_CLAIM_AFTER.ago)
+        .update_all(created_at: Time.current, event: event, claim_token: token)
+
+      token if updated.positive?
+    end
+
+    # Marks a claim as genuinely handled. Only after this does a redelivery of
+    # the same GUID get dismissed as a duplicate.
+    #
+    # Scoped to the token: if this run was superseded while it worked, the row
+    # now belongs to its replacement and must not be stamped processed on its
+    # behalf — the replacement is still running and has yet to earn that.
+    def self.mark_processed!(delivery_guid, token)
+      return if delivery_guid.blank? || token.blank?
+
+      where(delivery_guid: delivery_guid, claim_token: token)
+        .update_all(processed_at: Time.current)
+    end
+
+    # Drops a claim whose run failed so the redelivery is processed instead of
+    # dismissed.
+    #
+    # Scoped to the token as well as to unprocessed rows. Unprocessed alone was
+    # not enough: a run slower than STALE_CLAIM_AFTER has already lost the row
+    # to a replacement, and deleting on the GUID would have taken the
+    # replacement's live claim with it — freeing the GUID for a third request
+    # to claim while the replacement was still running, and leaving the
+    # replacement's own `mark_processed!` with no row to stamp, so every later
+    # redelivery would repeat the event.
+    def self.release(delivery_guid, token)
+      return if delivery_guid.blank? || token.blank?
+
+      where(delivery_guid: delivery_guid, claim_token: token, processed_at: nil).delete_all
+    end
+
+    # Called from the recurring prune job. Past RETENTION the delivery has aged
+    # out of GitHub's 3-day Redeliver window, so nothing can reuse the GUID and
+    # the row only grows the table.
+    def self.prune!(older_than: RETENTION.ago)
+      where(created_at: ...older_than).delete_all
+    end
+  end
+end

data/app/services/collavre_github/client.rb

@@ -1,6 +1,7 @@
 module CollavreGithub
   class Client
     MOCK_SERVER_DEFAULT = "http://localhost:4567"
+    RepositoryIdentity = Data.define(:id, :full_name)
 
     def initialize(account)
       options = { access_token: account.token }
@@ -71,6 +72,19 @@ module CollavreGithub
       []
     end
 
+    # The same listing, with the failure reported instead of swallowed. A
+    # caller asking whether a specific hook still exists cannot use the form
+    # above: an empty array would mean "GitHub says it is gone" and "GitHub did
+    # not answer" alike, and those two demand opposite actions.
+    def repository_hooks!(repo_full_name)
+      client.hooks(repo_full_name)
+    end
+
+    def repository_identity(repo_full_name)
+      repository = client.repository(repo_full_name)
+      RepositoryIdentity.new(id: repository.id, full_name: repository.full_name)
+    end
+
     def create_repository_webhook(repo_full_name, url:, secret:, events:, content_type: "json")
       client.create_hook(
         repo_full_name,

data/app/services/collavre_github/pr_channel_state_updater.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+module CollavreGithub
+  # Out-of-band PR state correction: applies the same end-state the webhook
+  # would have produced when a `pull_request` event was never delivered (hook
+  # added after the merge, delivery failure, repo renamed mid-flight).
+  #
+  # The webhook path does NOT route through here on purpose. There, `handle`
+  # only *returns* the closing message and WebhooksController injects it and
+  # detaches, because the controller owns the per-channel lock that also
+  # de-duplicates GitHub retries. This class owns the whole transition instead,
+  # so it takes the lock itself. Both paths share the message builders on
+  # GithubPrChannel, which is the part that would otherwise drift.
+  class PrChannelStateUpdater
+    # status ∈ :updated / :noop
+    Result = Struct.new(:status, :channel, :previous_state, keyword_init: true)
+
+    def self.call(channel:, state:)
+      new(channel: channel, state: state).call
+    end
+
+    def initialize(channel:, state:)
+      @channel = channel
+      @state = state.to_s
+      unless GithubPrChannel::PR_STATES.include?(@state)
+        raise ArgumentError, "Invalid pr_state: #{state.inspect}"
+      end
+    end
+
+    def call
+      channel.with_lock do
+        previous_state = channel.pr_state
+        next Result.new(status: :noop, channel: channel, previous_state: previous_state) if settled?
+
+        if state == "open"
+          reopen!
+        else
+          close!
+        end
+        Result.new(status: :updated, channel: channel, previous_state: previous_state)
+      end
+    end
+
+    private
+
+    attr_reader :channel, :state
+
+    # A repeat call must not inject a second timeline message. "Same state" is
+    # not enough on its own: a channel can read "open" while sitting detached
+    # (dismissed by the user, or reopened only in GitHub), and that still needs
+    # the reactivation half of the transition applied.
+    def settled?
+      return false unless channel.pr_state == state
+
+      if state == "open"
+        channel.active? && !channel.dismissed?
+      else
+        channel.detached?
+      end
+    end
+
+    # Mirrors WebhooksController's reopen handling: state back to active and
+    # the chip un-dismissed, so the channel resurfaces under `not_dismissed`
+    # and resumes receiving events.
+    def reopen!
+      channel.state = :active
+      channel.dismissed_at = nil
+      channel.pr_state = "open"
+      channel.save!
+      channel.inject_into_topic!(channel.reopened_message)
+    end
+
+    # Mirrors the closed-event path: set the badge, post the closing message,
+    # then detach — in that order, so the chip stays visible (now merged /
+    # closed) until the user dismisses it.
+    def close!
+      channel.pr_state = state
+      channel.save!
+      channel.inject_into_topic!(channel.closed_message(state))
+      channel.detach! if channel.active?
+    end
+  end
+end

data/app/services/collavre_github/repository_identity_synchronizer.rb

@@ -0,0 +1,145 @@
+module CollavreGithub
+  # Persists a repository identity established through trusted evidence and
+  # keeps attached channel routing keys in sync with the canonical GitHub name.
+  #
+  # Stable repository ids are authoritative. A NULL-id anchor is accepted only
+  # by the explicit operator reattachment workflow; hook registrations and HMAC
+  # secrets are not row identity because older provisioners propagated both.
+  class RepositoryIdentitySynchronizer
+    def self.call(
+      anchor:,
+      repository_id:,
+      full_name:,
+      trusted_secret: nil,
+      allow_anchor_backfill: false
+    )
+      return [] if anchor.blank? || repository_id.blank? || full_name.blank?
+
+      RepositoryProvisioningLock.with_repository_name_lock(full_name) do
+        new(
+          anchor: anchor,
+          repository_id: repository_id,
+          full_name: full_name,
+          trusted_secret: trusted_secret,
+          allow_anchor_backfill: allow_anchor_backfill
+        ).call
+      end
+    end
+
+    def initialize(
+      anchor:,
+      repository_id:,
+      full_name:,
+      trusted_secret:,
+      allow_anchor_backfill:
+    )
+      @anchor = anchor
+      @repository_id = repository_id
+      @full_name = full_name.to_s
+      @trusted_secret = trusted_secret
+      @allow_anchor_backfill = allow_anchor_backfill
+    end
+
+    def call
+      return [] if anchor.blank? || repository_id.blank? || full_name.blank?
+
+      synchronized = []
+      old_names_by_creative = Hash.new { |hash, key| hash[key] = [] }
+
+      RepositoryLink.transaction do
+        candidate_links.each do |link|
+          old_name = link.repository_full_name
+          survivor = synchronize_link(link)
+          next unless survivor
+
+          synchronized << survivor
+          if old_name.to_s == full_name
+            next
+          end
+
+          old_names_by_creative[old_name.to_s.downcase] << survivor.creative_id
+        end
+
+        old_names_by_creative.each do |old_name, creative_ids|
+          rename_channels(old_name, creative_ids.uniq)
+        end
+      end
+
+      synchronized.uniq(&:id)
+    end
+
+    private
+
+    attr_reader :anchor,
+      :repository_id,
+      :full_name,
+      :trusted_secret,
+      :allow_anchor_backfill
+
+    def candidate_links
+      links = RepositoryLink.where(repository_id: repository_id).to_a
+      links << anchor if allow_anchor_backfill || anchor.repository_id.to_s == repository_id.to_s
+      links.uniq(&:id)
+    end
+
+    def synchronize_link(link)
+      if link.repository_full_name.to_s == full_name &&
+          link.repository_id.to_s == repository_id.to_s
+        return link
+      end
+
+      conflict = RepositoryLink.identity_conflict_in_link_scope(
+        creative: link.creative,
+        full_name: full_name,
+        repository_id: repository_id,
+        excluding_id: link.id
+      )
+      return if conflict
+
+      survivor = RepositoryLink
+        .where(creative_id: link.creative_id)
+        .where("LOWER(repository_full_name) = ?", full_name.downcase)
+        .where.not(id: link.id)
+        .first
+
+      if survivor
+        return unless survivor.repository_id.to_s == repository_id.to_s
+
+        merge_links!(obsolete: link, survivor: survivor)
+        return survivor
+      end
+
+      link.update_columns(repository_id: repository_id, repository_full_name: full_name)
+      link
+    end
+
+    def merge_links!(obsolete:, survivor:)
+      survivor.update!(
+        webhook_secret: trusted_secret.presence || survivor.webhook_secret,
+        webhook_hook_id: survivor.webhook_hook_id || obsolete.webhook_hook_id,
+        markdown_sync_enabled: survivor.markdown_sync_enabled? || obsolete.markdown_sync_enabled?,
+        markdown_root_creative_id: survivor.markdown_root_creative_id || obsolete.markdown_root_creative_id,
+        sync_branch: survivor.sync_branch.presence || obsolete.sync_branch,
+        last_synced_at: [ survivor.last_synced_at, obsolete.last_synced_at ].compact.max
+      )
+      obsolete.destroy!
+    end
+
+    def rename_channels(old_name, creative_ids)
+      GithubPrChannel.where("LOWER(repo_full_name) = ?", old_name).find_each do |channel|
+        creative = channel.topic&.creative
+        next unless creative
+
+        candidate_ids = [ creative.id ] + creative.ancestors.pluck(:id)
+        next if (creative_ids & candidate_ids).empty?
+        next if RepositoryLink.conflicting_repository_in_scope?(
+          creative: creative,
+          full_name: old_name,
+          repository_id: repository_id
+        )
+
+        channel.synchronize_repository_name!(full_name)
+      end
+    end
+  end
+end