collavre_github 0.6.3 → 0.7.0

data/app/services/collavre_github/webhook_provisioner.rb

@@ -6,62 +6,164 @@ module CollavreGithub
     # a channel that silently misses comments. `pull_request` is required by
     # the auto-attach + close detection paths.
     CHANNEL_EVENTS = %w[issue_comment pull_request_review pull_request_review_comment].freeze
-    EVENTS = (%w[pull_request] + CHANNEL_EVENTS).freeze
-    EVENTS_WITH_PUSH = (%w[pull_request push] + CHANNEL_EVENTS).freeze
+
+    # `repository` carries the `renamed` action. Without it a rename is
+    # invisible to this app: `repository_full_name` goes stale on every link at
+    # once and, for links with no `repository_id` yet, there is no other key to
+    # find them by — so every subsequent delivery is answered 401 and the
+    # rename event that would repair it is rejected along with the rest.
+    # NOT a member of CHANNEL_EVENTS: it is routing maintenance, and the
+    # controller drops it rather than formatting it into any feed.
+    MAINTENANCE_EVENTS = %w[repository].freeze
+    EVENTS = (%w[pull_request] + CHANNEL_EVENTS + MAINTENANCE_EVENTS).freeze
+    EVENTS_WITH_PUSH = (%w[pull_request push] + CHANNEL_EVENTS + MAINTENANCE_EVENTS).freeze
     CONTENT_TYPE = "json".freeze
 
-    def self.ensure_for_links(account:, links:, webhook_url:)
-      new(account: account, webhook_url: webhook_url).ensure_for_links(Array(links))
+    # Last path segment of the deprecated singular `post "webhook"` route. The
+    # route still answers so that untouched repositories keep working, but a
+    # hook pointing at it is redundant with the plural one, so provisioning
+    # migrates the repository by deleting it. Derived from `webhook_url` at
+    # runtime so the engine's mount point stays the single source of truth.
+    LEGACY_ROUTE_SEGMENT = "webhook".freeze
+    ROUTE_SEGMENT = "webhooks".freeze
+
+    def self.ensure_for_links(account:, links:, webhook_url:, force_hook_refresh: false)
+      new(
+        account: account,
+        webhook_url: webhook_url,
+        force_hook_refresh: force_hook_refresh
+      ).ensure_for_links(Array(links))
     end
 
-    def self.remove_for_repositories(account:, repositories:, webhook_url:)
-      new(account: account, webhook_url: webhook_url).remove_for_repositories(Array(repositories))
+    def self.remove_for_links(account:, links:, webhook_url:)
+      new(account: account, webhook_url: webhook_url).remove_for_links(Array(links))
     end
 
-    def initialize(account:, webhook_url:, client: CollavreGithub::Client.new(account))
+    def initialize(
+      account:,
+      webhook_url:,
+      client: CollavreGithub::Client.new(account),
+      force_hook_refresh: false
+    )
       @client = client
       @webhook_url = webhook_url
+      @force_hook_refresh = force_hook_refresh
     end
 
     # Returns [[link, status], ...] so callers can detect silent GitHub
     # rejections. status is one of:
     #   :created         - new hook created
     #   :updated         - existing hook patched (events/url/secret)
-    #   :secret_aligned  - non-primary link with existing hook; only the local
-    #                      RepositoryLink secret was aligned. No GitHub call.
+    #   :secret_aligned  - non-primary link with existing hook; the local
+    #                      RepositoryLink secret was aligned and the hook itself
+    #                      was neither created nor patched. NOT a local-only
+    #                      operation: registration and legacy-hook cleanup still
+    #                      run, so GitHub may be called and a hook deleted. In
+    #                      particular the hook's event list is left untouched —
+    #                      see `provision_hook`.
+    #   :shared          - a hook registered in THIS database already exists, so
+    #                      another instance of this app owns it. No hook of this
+    #                      instance's own remains: a second one would make GitHub
+    #                      deliver every event twice. Its events and secret are
+    #                      refreshed, but its URL is left alone — rewriting that
+    #                      would break the sibling and start a rewrite war
+    #                      between the two. Also reported when this run created a
+    #                      hook, lost the registration race to a sibling doing
+    #                      the same concurrently, and deleted the hook it made.
     #   :failed          - Octokit/Faraday error OR Client returned nil
     def ensure_for_links(links)
       links.map { |link| [ link, ensure_webhook(link) ] }
     end
 
-    def remove_for_repositories(repositories)
-      # Batch-query to avoid N+1: find all repo names that still have links
-      linked_names = CollavreGithub::RepositoryLink
-        .where(repository_full_name: repositories)
-        .distinct
-        .pluck(:repository_full_name)
-        .to_set
-
-      repositories.each do |repository_full_name|
-        next if linked_names.include?(repository_full_name)
+    # Link objects retain their stable identity after destroy, allowing removal
+    # to find a surviving sibling even when it still stores a pre-rename name.
+    # Once the last ID-backed link is gone, re-resolve its stored name and
+    # require GitHub's live numeric id to match before touching the remote hook.
+    # NULL-id links fail closed: their name may have been reassigned and cannot
+    # safely identify a repository for an outbound mutation.
+    def remove_for_links(links)
+      links
+        .select { |link| link.repository_id.present? }
+        .group_by { |link| link.repository_id.to_s }
+        .each_value do |candidates|
+          repository_id = candidates.first.repository_id
+          CollavreGithub::RepositoryProvisioningLock.with_lock(repository_id) do
+            next if CollavreGithub::RepositoryLink.where(repository_id: repository_id).exists?
 
-        remove_webhook(repository_full_name)
-      end
+            verified_name = candidates.filter_map { |link| verified_removal_name(link) }.first
+            remove_webhook(verified_name) if verified_name
+          end
+        end
     end
 
     private
 
-    attr_reader :client, :webhook_url
+    attr_reader :client, :webhook_url, :provisioning_link, :force_hook_refresh,
+                :superseding_hook
 
     def ensure_webhook(link)
+      @provisioning_link = link
+      @superseding_hook = nil
       repository_full_name = link.repository_full_name
       primary_link = primary_link_for(repository_full_name)
-      hook = find_existing_hook(repository_full_name)
+      hooks = repository_hooks(repository_full_name)
+      # Read before provisioning, because registering the replacement overwrites
+      # it — and for a legacy hook under another host it is the only evidence
+      # that the hook belongs to a deployment sharing this database, which is
+      # what makes it ours to migrate.
+      prior_registration = registered_hook_id(repository_full_name)
+      hook = find_own_hook(hooks)
+      shared = find_shared_hook(hooks, repository_full_name, hook)
+
+      if shared && hook
+        # A leftover from before hooks were registered: this instance owns one
+        # and a sibling owns another, both feeding this database. Inbound
+        # deliveries are already deduplicated by GUID, so the extra hook only
+        # wastes bandwidth — not enough to justify deleting a live hook out
+        # from under whoever created it, but worth surfacing.
+        Rails.logger.warn(
+          "[CollavreGithub] #{repository_full_name} carries both this instance's hook " \
+          "#{hook_url(hook)} and registered hook #{hook_url(shared)}; delete one to stop " \
+          "GitHub sending every delivery twice"
+        )
+      end
+
+      status = provision_hook(link, repository_full_name, primary_link, hooks, hook, shared)
+
+      # Deliberately AFTER a replacement is in place. Deleting first left the
+      # repository with no hook at all whenever the create that followed failed
+      # — a transient GitHub error was enough — and callers report success
+      # regardless, so events stopped until provisioning happened to run again.
+      # Keeping the legacy hook on failure costs at most a duplicate delivery,
+      # which the GUID ledger already collapses.
+      delete_legacy_hooks(repository_full_name, hooks, prior_registration) unless status == :failed
 
+      status
+    rescue Octokit::Error => e
+      Rails.logger.warn(
+        "GitHub webhook provisioning failed for #{repository_full_name}: #{e.message}"
+      )
+      :failed
+    ensure
+      @provisioning_link = nil
+      @superseding_hook = nil
+    end
+
+    def provision_hook(link, repository_full_name, primary_link, hooks, hook, shared)
       if hook
+        register_hook(repository_full_name, hook.id, hooks)
+
         if primary_link && primary_link != link
           align_link_secret(link, primary_link.webhook_secret)
-          :secret_aligned
+          if force_hook_refresh
+            update_webhook(
+              repository_full_name,
+              hook.id,
+              primary_link.webhook_secret
+            ) ? :updated : :failed
+          else
+            :secret_aligned
+          end
         else
           update_webhook(repository_full_name, hook.id, link.webhook_secret) ? :updated : :failed
         end
@@ -73,31 +175,478 @@ module CollavreGithub
           align_link_secret(link, secret)
         end
 
-        create_webhook(repository_full_name, secret) ? :created : :failed
+        if shared
+          # Registered in this database, so the instance that created it reads
+          # the same RepositoryLink rows: same signing secret, same event list
+          # (`events_for` queries those rows). Reusing it is safe and is the
+          # only way to keep exactly one hook per repo.
+          #
+          # Its subscriptions are still refreshed. `events_for` widens to
+          # include `push` the moment any link enables markdown sync, and the
+          # sibling that owns the hook has no reason to reprovision — leaving
+          # it on the old list would let the initial sync run and then silently
+          # miss every later push. Only the URL is preserved: rewriting that to
+          # this host would break the sibling and start the two instances
+          # flipping it back and forth.
+          log_shared_hook_reuse(repository_full_name, shared)
+          return update_shared_webhook(repository_full_name, shared, secret) ? :shared : :failed
+        end
+
+        created = create_webhook(repository_full_name, secret)
+        return :failed unless created
+
+        created_id = created_hook_id(created)
+        # No id to register with (a Client that swallowed the error): the hook
+        # may well exist, so registration is deferred to the next run, which
+        # finds it by URL. Nothing to undo either way.
+        return :created if created_id.blank?
+        # Only a positively established sibling registration may undo the hook
+        # just created. `:unverified` means GitHub did not answer, and deleting
+        # a working hook on a guess would leave the repository with none at
+        # all — strictly worse than the duplicate delivery that keeping it may
+        # cost, which the GUID ledger collapses anyway.
+        registration = register_hook(repository_full_name, created_id, hooks)
+        return :created unless registration == :superseded
+
+        if force_hook_refresh
+          return :failed unless superseding_hook &&
+            update_shared_webhook(repository_full_name, superseding_hook, secret)
+        end
+
+        # A sibling instance created and registered its own hook while this one
+        # was creating its own. Both feed this database, so keeping both would
+        # double every delivery for good.
+        discard_duplicate_hook(repository_full_name, created_id)
+        :shared
+      end
+    end
+
+    def remove_webhook(repository_full_name)
+      hooks = repository_hooks(repository_full_name)
+      delete_legacy_hooks(repository_full_name, hooks)
+
+      hook = find_own_hook(hooks)
+      if hook
+        client.delete_repository_webhook(repository_full_name, hook.id)
+      end
+
+      # Only this instance's own hook is deleted. The registration that would
+      # identify a sibling lives on the repository's links, and this method
+      # only runs once the last of them is gone, so there is no longer any
+      # evidence of who created the remaining hooks. A hook on the same path
+      # under a different host may equally be a sibling instance or a separate
+      # deployment with its own database, for which this unlink says nothing —
+      # deleting it would silently break that deployment. It is reported, not
+      # removed.
+      leftover = find_same_path_hook(hooks)
+      if leftover
+        Rails.logger.info(
+          "[CollavreGithub] hook #{hook_url(leftover)} on #{repository_full_name} was left in " \
+          "place after unlink: its owner cannot be determined once the links are gone. " \
+          "Delete it manually if no deployment still needs it"
+        )
       end
     rescue Octokit::Error => e
       Rails.logger.warn(
-        "GitHub webhook provisioning failed for #{repository_full_name}: #{e.message}"
+        "GitHub webhook removal failed for #{repository_full_name}: #{e.message}"
       )
-      :failed
     end
 
-    def remove_webhook(repository_full_name)
-      hook = find_existing_hook(repository_full_name)
-      return unless hook
+    def repository_hooks(repository_full_name)
+      Array(client.repository_hooks(repository_full_name))
+    end
+
+    def find_own_hook(hooks)
+      hooks.find { |hook| hook_url(hook) == webhook_url }
+    end
+
+    # A hook another instance of this app created, identified by the id it
+    # recorded on this repository's links.
+    #
+    # Registration is the only positive evidence of shared state, and that is
+    # what makes reuse safe. Matching on the URL path instead would classify a
+    # completely separate deployment's hook as reusable merely because it
+    # serves the same path — that deployment has its own database and its own
+    # webhook secret, so deferring to it would leave this instance receiving no
+    # deliveries at all. Matching on the full URL is the opposite failure and is
+    # the proliferation this fix targets: every instance saw its siblings' hooks
+    # as foreign and created its own, so N instances meant N hooks.
+    #
+    # `own_hook` is excluded so callers can distinguish "mine" from "theirs"
+    # when this instance is itself the registered owner.
+    #
+    # A hook on the legacy path is excluded too, however it came to be
+    # registered. This run deletes it, so reusing it as the replacement means
+    # patching it, reporting success, and then deleting the only hook the
+    # repository had — no replacement was ever created because this branch
+    # said one already existed.
+    def find_shared_hook(hooks, repository_full_name, own_hook)
+      registered = registered_hook_id(repository_full_name)
+      return nil if registered.blank?
+
+      hooks.find do |hook|
+        hook.id.to_s == registered.to_s &&
+          (own_hook.nil? || hook.id != own_hook.id) &&
+          !legacy_hook?(hook)
+      end
+    end
+
+    # Hooks this run will migrate off the deprecated singular path. Blank
+    # `legacy_webhook_path` (an unexpected `webhook_url`) matches nothing, so
+    # no hook is ever reclassified on a guess.
+    def legacy_hook?(hook)
+      return false if legacy_webhook_path.blank?
+
+      url_path(hook_url(hook)) == legacy_webhook_path
+    end
+
+    # Reporting only — never a reuse decision. See `remove_webhook`.
+    def find_same_path_hook(hooks)
+      hooks.find do |hook|
+        url = hook_url(hook)
+        url != webhook_url && url_path(url) == webhook_path
+      end
+    end
+
+    # Every primary-link, registration, and event lookup is bounded by the
+    # selected link's identity. ID-backed attempts use the stable repository id
+    # across every stored-name alias, including links that missed a rename.
+    # Name-only attempts remain limited to same-name NULL-id links: a row with
+    # an authoritative id under that reused name may belong to another
+    # repository and must not contribute its secret, registration, or settings.
+    def links_for(repository_full_name)
+      if provisioning_link&.repository_id.present?
+        return CollavreGithub::RepositoryLink.where(repository_id: provisioning_link.repository_id)
+      end
 
+      links = CollavreGithub::RepositoryLink
+        .where("LOWER(repository_full_name) = ?", normalize_repository_name(repository_full_name))
+      return links unless provisioning_link
+
+      links.where(repository_id: nil)
+    end
+
+    def normalize_repository_name(repository_full_name)
+      repository_full_name.to_s.downcase
+    end
+
+    def verified_removal_name(link)
+      return if link.repository_id.blank?
+
+      identity = client.repository_identity(link.repository_full_name)
+      return if identity&.id.blank? || identity&.full_name.blank?
+      return unless identity.id.to_s == link.repository_id.to_s
+
+      identity.full_name
+    rescue Octokit::Error, Faraday::Error => e
+      Rails.logger.warn(
+        "[CollavreGithub] webhook removal identity verification failed for " \
+        "#{link.repository_full_name}: #{e.class}: #{e.message}"
+      )
+      nil
+    end
+
+    def registered_hook_id(repository_full_name)
+      links_for(repository_full_name)
+        .where.not(webhook_hook_id: nil)
+        .order(:id)
+        .pick(:webhook_hook_id)
+    end
+
+    # Records the hook so sibling instances can recognise it. Written to every
+    # link for the repository, not just the primary one, so that deleting a
+    # link cannot lose the registration and let the next run create a duplicate.
+    #
+    # Skipped while the registered hook is still live on GitHub: overwriting a
+    # sibling's registration would let the two instances take turns claiming it
+    # and bring the proliferation straight back. A registration whose hook has
+    # since been deleted is stale and gets replaced.
+    #
+    # Returns what became of the registration, which is what tells the caller
+    # whether the hook it just created may stay:
+    #   :recorded   - this database's registration names `hook_id`
+    #   :superseded - a sibling's registration stands; `hook_id` is redundant
+    #   :unverified - GitHub could not confirm what the registration names, so
+    #                 nothing was written and nothing may be undone on the
+    #                 strength of it
+    #
+    # The caller needs that answer because the read above and the write below
+    # are not one operation: two instances provisioning the same repository at
+    # once both list no hooks, both create one, and both arrive here. The write
+    # is therefore a compare-and-set against the value just read, so only one
+    # can win — the loser's UPDATE matches nothing, because the row it is
+    # testing against has already moved. Without it the two writes were plain
+    # last-writer-wins and both hooks stayed live forever.
+    def register_hook(repository_full_name, hook_id, hooks)
+      return :unverified if hook_id.blank?
+
+      registered = registered_hook_id(repository_full_name)
+      if registered.to_s == hook_id.to_s
+        backfill_registration(repository_full_name, hook_id)
+        return :recorded
+      end
+      live = live_registered_hook(repository_full_name, registered, hooks)
+      return :unverified if live == :unknown
+
+      # A live registration naming a LEGACY hook is not a competitor to defer
+      # to: this run is replacing that hook, not racing a sibling for it.
+      # Deferring would discard the replacement just created and then delete the
+      # legacy hook, leaving the repository with none at all.
+      if live && !legacy_hook?(live)
+        @superseding_hook = live
+        return :superseded
+      end
+
+      links_for(repository_full_name)
+        .where(webhook_hook_id: [ nil, registered ].uniq)
+        .update_all(webhook_hook_id: hook_id)
+
+      # Re-read rather than trust the affected-row count: the rows are only
+      # "ours" if the registration now reads back as this hook.
+      if registered_hook_id(repository_full_name).to_s == hook_id.to_s
+        :recorded
+      else
+        :superseded
+      end
+    end
+
+    # A link created after the hook was registered starts with a null
+    # webhook_hook_id, and the compare-and-set above returns before writing
+    # anything — the value it compares against is already correct, so there is
+    # nothing to set. That leaves the registration on the older links only.
+    # Removing those links then takes the last copy of it with them, and the
+    # live hook becomes unrecognisable: `find_shared_hook` requires a recorded
+    # id, so the next run from a sibling host reads it as foreign and adds a
+    # second hook — the proliferation this registry exists to stop.
+    #
+    # Only null registrations are filled. A link naming a different hook is not
+    # this run's to overwrite; that case is the stale-vs-live question the CAS
+    # above already answers.
+    def backfill_registration(repository_full_name, hook_id)
+      links_for(repository_full_name)
+        .where(webhook_hook_id: nil)
+        .update_all(webhook_hook_id: hook_id)
+    end
+
+    # The registered hook as it exists on GitHub: the hook itself if it is
+    # live, nil if GitHub says it is gone, `:unknown` if GitHub could not be
+    # asked.
+    #
+    # `hooks` was listed before this run started creating anything, so a
+    # registration missing from it is NOT proof the hook is gone — a sibling
+    # instance may have created and registered it since. The two cases demand
+    # opposite actions (replace a stale registration; defer to a live one) and
+    # getting either wrong puts a second hook on the repository, so when the
+    # cached listing cannot vouch for it the question is put to GitHub.
+    #
+    # The hook itself is returned rather than a boolean: the caller also has to
+    # know whether it sits on the legacy path, which only its URL can say.
+    def live_registered_hook(repository_full_name, registered, hooks)
+      # Nothing registered, so there is no hook to vouch for and the re-listing
+      # below could only ever come back empty. Skipping it matters because this
+      # is the ordinary first provision of a repository, where paying for a
+      # second GitHub round trip buys nothing.
+      return nil if registered.blank?
+
+      found = hooks.find { |hook| hook.id.to_s == registered.to_s }
+      return found if found
+
+      verify_registered_hook(repository_full_name, registered)
+    end
+
+    # Deliberately NOT `repository_hooks`, which is the error-swallowing form
+    # and answers `[]` for a request GitHub never served. Here that empty list
+    # would be read as "the registered hook is gone" and the registration
+    # overwritten with this run's hook while the original stays live — and
+    # since the original's id is then recorded nowhere, no later run can even
+    # see it: `find_shared_hook` needs a registered id and `find_own_hook`
+    # matches only this instance's URL. The repository keeps delivering twice
+    # for good, with nothing left to report it. This is the one caller that
+    # must tell an empty answer from no answer.
+    def verify_registered_hook(repository_full_name, registered)
+      Array(client.repository_hooks!(repository_full_name))
+        .find { |hook| hook.id.to_s == registered.to_s }
+    rescue Octokit::Error, Faraday::Error => e
+      Rails.logger.warn(
+        "[CollavreGithub] could not verify registered hook #{registered} on " \
+        "#{repository_full_name}: #{e.message}; leaving the registration alone. " \
+        "The next provisioning run decides it with a listing that answered"
+      )
+      :unknown
+    end
+
+    # Undoes a hook this run created after losing the registration race above.
+    # Leaving it would put two live hooks on the repository permanently — the
+    # next run sees one registered hook and one of its own and can only warn,
+    # since deleting a hook it cannot prove it created is unsafe. Here that
+    # proof exists: this run created this hook seconds ago.
+    #
+    # A failure to delete is logged rather than raised. The hook is real and
+    # working, so the cost is a duplicate delivery, which the GUID ledger
+    # already collapses — not worth failing an otherwise successful provision.
+    def discard_duplicate_hook(repository_full_name, hook_id)
+      Rails.logger.info(
+        "[CollavreGithub] deleting hook #{hook_id} just created for #{repository_full_name}: " \
+        "another instance registered its own hook concurrently"
+      )
+      client.delete_repository_webhook(repository_full_name, hook_id)
+    rescue Octokit::Error => e
+      Rails.logger.warn(
+        "[CollavreGithub] could not delete redundant hook #{hook_id} on " \
+        "#{repository_full_name}: #{e.message}. Delete it manually to stop GitHub " \
+        "sending every delivery twice"
+      )
+    end
+
+    # Octokit returns the created hook; a Client that swallowed the error
+    # returns something without an id, in which case registration is simply
+    # deferred to the next run, which finds the hook by URL.
+    def created_hook_id(created)
+      created.id if created.respond_to?(:id)
+    end
+
+    # Migrates the repository off the deprecated singular `/github/webhook`
+    # path: alongside the plural hook it only produces a duplicate delivery,
+    # and removing it here is what eventually makes the alias route droppable.
+    def delete_legacy_hooks(repository_full_name, hooks, prior_registration = nil)
+      return if legacy_webhook_path.blank?
+
+      registered = [ prior_registration, registered_hook_id(repository_full_name) ]
+        .compact_blank
+        .map(&:to_s)
+      legacy = hooks.select { |hook| legacy_hook?(hook) }
+      mine, theirs = legacy.partition { |hook| own_legacy_hook?(hook, registered) }
+
+      theirs.each do |hook|
+        Rails.logger.info(
+          "[CollavreGithub] leaving legacy hook #{hook_url(hook)} on #{repository_full_name} " \
+          "in place: it is not registered here and sits under another host, so it may belong " \
+          "to an independent deployment still served by that route"
+        )
+      end
+
+      mine.each do |hook|
+        Rails.logger.info(
+          "[CollavreGithub] deleting legacy hook #{hook_url(hook)} on #{repository_full_name}"
+        )
+        delete_legacy_hook(repository_full_name, hook)
+      end
+    end
+
+    # Rescued for the same reason `discard_duplicate_hook` is: by the time this
+    # runs the replacement hook is already in place, so a failure to remove the
+    # deprecated one costs a duplicate delivery that the GUID ledger collapses.
+    # Letting it escape reaches `ensure_webhook`'s `rescue Octokit::Error` and
+    # turns a provision that actually succeeded into `:failed`, which
+    # `pr_monitor` reports as "GitHub API rejected the hook request" — a false
+    # alarm about the very hook that was just provisioned correctly.
+    #
+    # Defence in depth rather than a live bug: the injected production client
+    # (`CollavreGithub::Client`) rescues Octokit and Faraday itself and answers
+    # nil, so nothing raises this far today. That also makes the outer rescue
+    # unreachable in production, which is precisely why the cost of an
+    # unrescued raise here is invisible until a client that does raise is used.
+    def delete_legacy_hook(repository_full_name, hook)
       client.delete_repository_webhook(repository_full_name, hook.id)
     rescue Octokit::Error => e
       Rails.logger.warn(
-        "GitHub webhook removal failed for #{repository_full_name}: #{e.message}"
+        "[CollavreGithub] could not delete legacy hook #{hook_url(hook)} on " \
+        "#{repository_full_name}: #{e.message}. It is redundant with the plural-path " \
+        "hook; delete it manually to stop GitHub sending every delivery twice"
       )
     end
 
-    def find_existing_hook(repository_full_name)
-      client.repository_hooks(repository_full_name).find do |hook|
-        config = normalize_config(hook.config)
-        config["url"] == webhook_url
+    # Deletion must rest on stronger evidence than reuse, not weaker. Matching
+    # the legacy PATH alone would delete the hook of an independent deployment
+    # that still serves `/github/webhook` — a supported route — and take its
+    # deliveries offline. Ownership is therefore positive: either the hook
+    # carries this instance's own host, or its id is registered in this
+    # database, which only an instance sharing this database could have written.
+    def own_legacy_hook?(hook, registered_ids)
+      return true if registered_ids.include?(hook.id.to_s)
+
+      same_origin?(hook_url(hook), webhook_url)
+    end
+
+    def same_origin?(url, other)
+      a = URI.parse(url)
+      b = URI.parse(other)
+      a.host.present? && a.host == b.host && a.port == b.port
+    rescue URI::InvalidURIError
+      false
+    end
+
+    def webhook_path
+      @webhook_path ||= url_path(webhook_url)
+    end
+
+    # `/github/webhooks` -> `/github/webhook`. Blank when `webhook_url` does not
+    # end in the expected segment, so an unexpected URL never causes an
+    # unrelated hook to be deleted.
+    def legacy_webhook_path
+      return @legacy_webhook_path if defined?(@legacy_webhook_path)
+
+      @legacy_webhook_path =
+        if webhook_path.end_with?("/#{ROUTE_SEGMENT}")
+          webhook_path.sub(/#{Regexp.escape(ROUTE_SEGMENT)}\z/, LEGACY_ROUTE_SEGMENT)
+        end
+    end
+
+    def hook_url(hook)
+      normalize_config(hook.config)["url"].to_s
+    end
+
+    # Reuse leaves this instance with no hook of its own: every delivery for the
+    # repository goes to whichever host created it. The registry is claimed
+    # first-come, so that host can be a laptop or a tunnel — and when it goes
+    # away GitHub keeps delivering to a dead URL while no instance receives
+    # anything. Nothing else reports that state: the hook exists, the links are
+    # linked, and the repository simply goes quiet.
+    #
+    # Reusing a hook on this instance's own origin carries none of that (the
+    # deliveries arrive here), so only the cross-host case is raised to `warn`,
+    # together with GitHub's own record of the last delivery to that URL. The
+    # listing already carries it, so this costs no extra API call and turns a
+    # state the setup guide can currently only tell operators to check by hand
+    # on github.com into something greppable in the logs.
+    def log_shared_hook_reuse(repository_full_name, shared)
+      url = hook_url(shared)
+      message = "[CollavreGithub] reusing registered hook #{url} " \
+                "for #{repository_full_name}; not creating #{webhook_url}"
+
+      if same_origin?(url, webhook_url)
+        Rails.logger.info(message)
+        return
       end
+
+      Rails.logger.warn(
+        "#{message}. This instance will receive no deliveries for that repository; " \
+        "if that host stops answering, none will. GitHub's last delivery to it: " \
+        "#{last_delivery_summary(shared)}"
+      )
+    end
+
+    # Present on every hook GitHub lists. Reported verbatim rather than
+    # interpreted: a failing last delivery is the signal an operator needs, but
+    # which shape GitHub records for an unreachable host is not something this
+    # code can establish, and acting on a guess would rewrite a sibling's URL.
+    def last_delivery_summary(hook)
+      response = hook.respond_to?(:last_response) ? hook.last_response : nil
+      response = normalize_config(response)
+      return "not reported" if response.blank?
+
+      summary = [ response["status"], response["code"] ].compact_blank.join(" ")
+      summary.presence || "not reported"
+    end
+
+    # Trailing slashes are insignificant to Rails routing but not to string
+    # comparison, so normalize them away before matching.
+    def url_path(url)
+      path = URI.parse(url).path.to_s
+      path = path.chomp("/") if path.length > 1
+      path
+    rescue URI::InvalidURIError
+      ""
     end
 
     def create_webhook(repository_full_name, secret)
@@ -121,18 +670,28 @@ module CollavreGithub
       )
     end
 
+    # Refreshes a sibling instance's hook while leaving its URL alone, so the
+    # deliveries keep flowing to whichever host created it.
+    def update_shared_webhook(repository_full_name, hook, secret)
+      client.update_repository_webhook(
+        repository_full_name,
+        hook.id,
+        url: hook_url(hook),
+        secret: secret,
+        events: events_for(repository_full_name),
+        content_type: CONTENT_TYPE
+      )
+    end
+
     def events_for(repository_full_name)
-      has_markdown_sync = CollavreGithub::RepositoryLink
-        .where(repository_full_name: repository_full_name, markdown_sync_enabled: true)
+      has_markdown_sync = links_for(repository_full_name)
+        .where(markdown_sync_enabled: true)
         .exists?
       has_markdown_sync ? EVENTS_WITH_PUSH : EVENTS
     end
 
     def primary_link_for(repository_full_name)
-      CollavreGithub::RepositoryLink
-        .where(repository_full_name: repository_full_name)
-        .order(:id)
-        .first
+      links_for(repository_full_name).order(:id).first
     end
 
     def align_link_secret(link, secret)