fix(host-service): fetch PRs per-branch to avoid 504 on large repos

Merged
RU
6mo ago
+54-12

Summary

  • Replace the single pullRequests(first: 100) GraphQL query with per-branch pullRequests(headRefName: $branch, first: 1) queries, scoped per workspace branch.
  • Make refresh failure-isolating: a 504/rate-limit on one branch no longer blanks every workspace's PR badge — the existing pullRequestId is preserved and the next tick retries.

Why / Context

On large repos (e.g. Monest-Eng/monest-backend) the existing query — fetch all PRs sorted by updated_at — frequently returned GraphQL 504 or tripped GitHub abuse-detection (403). Symptoms in the desktop UI:

  • PR badges in the sidebar disappeared on every refresh tick.
  • Failures cached for the full TTL (working as designed for stability) meant the badges stayed gone for ~20s at a time.
  • A single bad branch (or transient outage) blanked badges for unrelated workspaces in the same repo.

How It Works

  • Per-branch GraphQL: PULL_REQUEST_FOR_BRANCH_QUERY filters with headRefName: $branch, cost-light vs. paginating 100 PRs. Util renamed fetchRepositoryPullRequests → fetchPullRequestForBranch.
  • Cache key changed from owner/repo → owner/repo#branch. One failing branch can no longer poison resolution for the rest. Failed promises still cached for the full TTL to avoid retry storms (existing semantics preserved).
  • Three-way refresh semantics in performProjectRefresh:
    • matched → upsert PR row, set pullRequestId.
    • no-match (resolved-null OR head-identity mismatch) → clear pullRequestId.
    • failed (Promise.allSettled rejection) → preserve existing pullRequestId. Transient 504 must not blank the badge.
  • Fork guard: pullRequests(headRefName: …) filters by branch name only on the base repo. Fork PRs share branch names; we verify headRepositoryOwner.login and headRepository.name match the workspace upstream before accepting the node.
  • Cache eviction scoped by project repo prefix so refreshing one project doesn't evict cache entries belonging to other projects we haven't refreshed yet.

Manual QA Checklist

Refresh behaviour

  • Workspaces in a healthy repo show correct PR badges.
  • Workspaces in a large repo (e.g. Monest-Eng/monest-backend) show badges without 504s.
  • On simulated transient failure, existing PR badges remain (don't blank).
  • After failure resolves, next tick repopulates badges.
  • Closing/merging a PR clears the badge on the next refresh.
  • A workspace whose branch points to a fork (different owner/repo) is not matched against a base-repo PR with the same branch name.

Cache

  • Two workspaces on the same branch share one in-flight fetch (no duplicate GraphQL call).
  • Refreshing project A doesn't evict cache entries for project B.

Testing

  • bun run typecheck ✓ (turbo cache hit)
  • bun run lint ✓ (Biome, 4352 files, 0 issues)
  • bun test packages/host-service/src/runtime/pull-requests/pull-requests.test.ts ✓ — 11 pass / 0 fail / 34 expects covering:
    • multi-workspace test harness (PR refresh)
    • hardened harness fragility note + correct multi-PR upsert
    • per-branch routing + same-branch dedup
    • failure-isolation (one branch's 504 doesn't affect siblings)
    • fork-mismatch (branch-name collision with base repo doesn't false-match)

Design Decisions

  • Per-branch fetch over single repo fetch with first: 100: Per-branch is O(workspaces) GraphQL points but each is cheap and isolates failures. The previous "one fetch for all" looks cheaper in nominal case but its tail (504, 403 abuse) was the production failure mode.
  • Preserve pullRequestId on fetch failure instead of clearing: Transient infra blips shouldn't show "no PR" and trigger UI flicker. Stale-but-correct beats correct-but-flickery.

Risks / Rollout

  • Risk: Per-branch fetches multiply GraphQL points usage on repos with many workspaces. Per-branch cache + 20s TTL bounds this to one query per (repo, branch) per refresh window. No primary-rate-limit impact observed in tests.
  • Rollout: Ships in next desktop build; no migration required, no flag.
  • Rollback: Single revert of this PR restores the previous "fetch all" path. Cache state is in-memory only; no on-disk schema or persisted format changed.

Summary by cubic

Fixes PR badge timeouts and flicker on large GitHub repos by fetching PRs per-branch with failure isolation and better fork matching. Badges stay stable under 504s and when multiple forks share the same branch. Addresses #4246.

  • Bug Fixes
    • Replace repo-wide query with per-branch pullRequests(headRefName: $branch, first: 10) and match by head owner/repo case-insensitively.
    • Cache per owner/repo#branch (20s TTL), dedup same-branch requests, and keep failed promises cached to avoid retry storms.
    • Failure isolation: matched → link; no-match → clear; head lookup failed → keep existing pullRequestId (tracked per-branch).
    • Handle multi-fork branch collisions by picking the candidate whose head matches the workspace’s upstream.
    • Evict stale branch cache entries scoped to the project’s repo prefix.
    • Tests cover per-branch routing/dedup, lookup-failure preservation, fork mismatch, multi-fork collisions, and case-insensitive matching.

Summary by CodeRabbit

  • Bug Fixes
    • Improved PR linking resilience: when upstream PR data cannot be fetched, the system now preserves existing PR links instead of clearing them, reducing data loss during refresh operations.

Review Change Stack