From eccc315408588f327d102a8b2dee1a4de1831e53 Mon Sep 17 00:00:00 2001 From: Andy Anderson Date: Wed, 18 Nov 2026 00:25:24 -0500 Subject: [PATCH 1/2] =?UTF-8?q?=E2=9C=A8=20Does=20this=20build=20contain?= =?UTF-8?q?=20PR=20#N:=20ancestry=20lookup=20API=20on=20the=20hub=20and=20?= =?UTF-8?q?each=20hive?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Adds pkg/buildcontains (yes/no/unknown from git ancestry; an unresolvable commit is unknown, a PR outside the build's history is no), the hub read route GET /api/saas/build-contains and the hive route GET /api/version/contains, with openapi, API-reference and telemetry docs. Part of #18915. Signed-off-by: Andy Anderson --- changelog.d/added-18915-build-contains-api.md | 1 + dashboard/openapi.json | 79 ++++ .../api-reference/health-status-events.md | 1 + src/docs/api-reference/hub-saas.md | 1 + src/docs/release-channels.md | 19 + src/docs/telemetry.md | 1 + src/pkg/buildcontains/buildcontains.go | 336 ++++++++++++++++++ src/pkg/buildcontains/buildcontains_test.go | 210 +++++++++++ src/pkg/dashboard/api.go | 1 + src/pkg/dashboard/api_version_contains.go | 114 ++++++ .../dashboard/api_version_contains_test.go | 58 +++ src/pkg/dashboard/import_count_test.go | 6 +- src/pkg/hub/build_contains.go | 226 ++++++++++++ src/pkg/hub/build_contains_test.go | 130 +++++++ src/pkg/hub/saas.go | 1 + 15 files changed, 1182 insertions(+), 2 deletions(-) create mode 100644 changelog.d/added-18915-build-contains-api.md create mode 100644 src/pkg/buildcontains/buildcontains.go create mode 100644 src/pkg/buildcontains/buildcontains_test.go create mode 100644 src/pkg/dashboard/api_version_contains.go create mode 100644 src/pkg/dashboard/api_version_contains_test.go create mode 100644 src/pkg/hub/build_contains.go create mode 100644 src/pkg/hub/build_contains_test.go diff --git a/changelog.d/added-18915-build-contains-api.md b/changelog.d/added-18915-build-contains-api.md new file mode 100644 index 0000000000..a12dfef4aa --- /dev/null +++ b/changelog.d/added-18915-build-contains-api.md @@ -0,0 +1 @@ +- Added "does this build contain PR #N" lookups ([#18915](https://github.com/hivecommons/hive/issues/18915)): `GET /api/saas/build-contains?q=` on the hub answers `yes`, `no` or `unknown` for each hive you can see, and `GET /api/version/contains?q=` answers for a hive's own running build. The answer comes from git ancestry of the commit the hive already reports; a commit that cannot be resolved is always `unknown`, and a PR outside the build's history is `no`. No new heartbeat field; see `src/docs/telemetry.md` for the on-demand GitHub request. diff --git a/dashboard/openapi.json b/dashboard/openapi.json index 4a685adee4..9f53c74c47 100644 --- a/dashboard/openapi.json +++ b/dashboard/openapi.json @@ -6536,6 +6536,85 @@ } } }, + "/api/version/contains": { + "get": { + "tags": [ + "System" + ], + "summary": "Does the running build contain a PR or commit", + "description": "Answers from git ancestry, computed from the commit this hive reports running (the same value as `hash` on `/api/version`) and the repository history. `contains` is `yes` when the PR's merge commit (or the commit itself) is the running commit or one of its ancestors, `no` when ancestry was resolved and it is not (including a PR that was never merged), and `unknown` when it cannot be established: the commit is not resolvable in the repository history, the lookup failed, or this hive has no GitHub access. `unknown` is never a guess. Reads the public repository through the hive's existing GitHub client; sends only commit SHAs and a PR number.", + "parameters": [ + { + "name": "q", + "in": "query", + "required": true, + "description": "A PR number (`123`, `#123`, `PR 123`; up to six digits) or a commit SHA (7 to 40 hex characters)", + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "Containment answer", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "query": { + "type": "object", + "properties": { + "kind": { + "type": "string", + "enum": [ + "pr", + "commit" + ] + }, + "pr": { + "type": "integer" + }, + "commit": { + "type": "string" + } + } + }, + "commit": { + "type": "string", + "description": "The commit whose presence was tested: the PR's merge commit, or the SHA asked about" + }, + "running": { + "type": "string", + "description": "The commit this hive reports running" + }, + "channel": { + "type": "string", + "description": "The release channel the hive's image follows, when known" + }, + "contains": { + "type": "string", + "enum": [ + "yes", + "no", + "unknown" + ] + }, + "reason": { + "type": "string", + "description": "Why the answer is unknown, or why a PR is not contained" + } + } + } + } + } + }, + "400": { + "description": "The query is neither a PR number nor a commit SHA" + } + } + } + }, "/api/version/release-notes": { "get": { "tags": [ diff --git a/src/docs/api-reference/health-status-events.md b/src/docs/api-reference/health-status-events.md index 16ee7769c1..33b9695c50 100644 --- a/src/docs/api-reference/health-status-events.md +++ b/src/docs/api-reference/health-status-events.md @@ -23,6 +23,7 @@ Part of the [Dashboard REST API reference](../api-reference.md); see that page f |---|---|---|---|---| | `GET` | `/api/version` | Dashboard auth/session | Build/version metadata; includes `upgradeMarker` (`target`, `current`, `attempts`, `maxAttempts`, `failed`, `requestedAt`, `lastError`) while a self-upgrade is in flight or has failed ([#6765](https://github.com/hivecommons/hive/issues/6765)), the hub-delivered `upgradePolicy` (`hub_managed`, `spoke_managed`, `schedule`, `schedule_hour`, `schedule_timezone`, `schedule_weekday`, `paused`, `branch`, `channel`, `target_sha`, `target_resolved`, `armed_target`, and `next_update_at` — the hub's RFC3339 ETA for the next promotion into the `stable` channel, omitted when unknown ([#10256](https://github.com/hivecommons/hive/issues/10256))) when available, and an `autoUpdate` object (`enabled`, `state` — one of `disabled`/`up_to_date`/`behind`/`retrying`/`failed`/`unknown` — `healthy`, `period`, `targetBranch`, `targetCommit`, `currentCommit`, `commitsBehind`, `lastAttemptAt`, `lastError`, `detail`, and `nextUpdateAt` — the hub's RFC3339 ETA for the next update, omitted when unknown, disabled or paused ([#10257](https://github.com/hivecommons/hive/issues/10257))) that never reports a failed or unknown update as healthy ([#6962](https://github.com/hivecommons/hive/issues/6962), [#6963](https://github.com/hivecommons/hive/issues/6963)). Also `startedAt` (RFC3339 process start — changes on every pod roll even when the build does not, so the dashboard can say "Restarted" vs "Upgraded") and, until the first status is published, `startupPhase`/`startupPhaseLabel` (the boot phase a fresh pod is in) ([#15788](https://github.com/hivecommons/hive/issues/15788)) | `pkg/dashboard/api.go:45` | | `GET` | `/api/version/release-notes` | Dashboard auth/session | Changelog gap between two revisions: `?from=&to=` returns `{from:{sha,version?}, to:{sha,ref,version?}, sections:[{version,date,categories:{added,changed,fixed,security,deprecated}}], unreleased?, truncated, source, error?}` — the `CHANGELOG.md` release sections present at `to` and absent at `from`, newest first, plus (when `to` is not a release tag) the `changelog.d/` fragments new at `to` under an `Unreleased (in this build)` section. Fetch failures return `source: "unavailable"` with `error` rather than an error status; results are cached per (from, to) for an hour ([#11065](https://github.com/hivecommons/hive/issues/11065)) | `pkg/dashboard/api.go:46` | +| `GET` | `/api/version/contains` | Dashboard auth/session | Does the running build contain a PR or commit ([#18915](https://github.com/hivecommons/hive/issues/18915)): `?q=` returns `{query, commit?, running?, channel?, contains, reason?}`. `contains` is `yes`, `no` or `unknown`, computed from the commit this hive reports running (`hash` on `/api/version`) and repository ancestry; `unknown` (with `reason`) when the commit cannot be resolved, the lookup failed or the hive has no GitHub access, never a guess. An unmerged PR is `no`. `400` when `q` is neither a PR number nor a SHA | `pkg/dashboard/api_version_contains.go:113` | | `POST` | `/api/release-channel` | Owner only | Hosted spoke self-service release-channel selector; relays `stable`/`candidate`/`edge` to the hub's existing switch-branch endpoint with the spoke dashboard-token proof, and reports the requested channel as pending until the Deployment image lands | `pkg/dashboard/api.go:70` | | `GET` | `/api/health` | Public | Basic health probe | `pkg/dashboard/server.go:1781` | | `GET` | `/api/health/deep` | Public | Deep health probe | `pkg/dashboard/server.go:1782` | diff --git a/src/docs/api-reference/hub-saas.md b/src/docs/api-reference/hub-saas.md index 302fe86eea..bfeadafa03 100644 --- a/src/docs/api-reference/hub-saas.md +++ b/src/docs/api-reference/hub-saas.md @@ -91,6 +91,7 @@ Part of the [Dashboard REST API reference](../api-reference.md); see that page f | `POST` | `/api/saas/admin/rotate-master-key` | Hub admin | Rotate Token Master Key (double-call refused) | `pkg/hub/saas.go:501` | | `GET` | `/api/saas/admin/advisory-diagnostics` | Hub admin | Fleet Advisory/App-State Diagnostics | `pkg/hub/saas.go:527` | | `POST` | `/api/saas/hives/bulk` | Hub auth | Bulk Hive Action | `pkg/hub/saas_bulk.go:89` | +| `GET` | `/api/saas/build-contains` | Hub auth | Does each hive's running build contain a PR or commit ([#18915](https://github.com/hivecommons/hive/issues/18915)): `?q=` returns `{query:{kind,pr?,commit?}, commit?, reason?, hives:[{id,name?,commit?,channel?,contains,reason?}]}` for the hives the caller can see in My Hives. `contains` is `yes`, `no` or `unknown`, computed from the hive's already-reported commit and repository ancestry: `yes` when the PR's merge commit (or the SHA) is the running commit or an ancestor, `no` when ancestry resolved and it is not (an unmerged PR is `no`), `unknown` (with `reason`) when the commit cannot be resolved or the lookup failed. Never a guess. `400` when `q` is neither a PR number nor a SHA. See [Build visibility](../release-channels.md) | `pkg/hub/build_contains.go:225` | | `GET` | `/api/saas/me/country` | Hub auth | My Country Get | `pkg/hub/saas.go:391` | | `PUT` | `/api/saas/me/country` | Hub auth | My Country Set (write blocked while impersonating) | `pkg/hub/saas.go:392` | | `POST` | `/api/saas/lite/enroll` | Hub auth | Hive Lite Enroll | `pkg/hub/saas.go:393` | diff --git a/src/docs/release-channels.md b/src/docs/release-channels.md index b65d08f543..b005cb7d94 100644 --- a/src/docs/release-channels.md +++ b/src/docs/release-channels.md @@ -285,3 +285,22 @@ The My Hives **GROUP BY** selector includes an `Upgrade state` dimension ([#3805 `GET /api/version/release-notes?from=&to=` answers "what changes if I upgrade from here to there?" ([#11065](https://github.com/hivecommons/hive/issues/11065)). The dashboard reads `CHANGELOG.md` at both revisions (through the configured GitHub credential, falling back to the public raw endpoint) and returns the `## (vX.Y.Z)` sections that exist at `to` but not at `from`, newest first, grouped Added / Changed / Fixed / Security / Deprecated. The diff comes from repo content, never version arithmetic, so channel and nightly heads work. When `to` is not a release tag, `changelog.d/` fragments that are new at `to` are listed under an `Unreleased (in this build)` section, categorised by filename prefix. If the notes cannot be fetched the endpoint still returns 200 with `source: "unavailable"` and a reason, so an upgrade is never blocked on it. Responses are cached per (from, to) pair for an hour (the cache holds at most 64 pairs, evicting the oldest) and capped at 400 entries (`truncated: true` when cut). Because each uncached build can cost a few hundred GitHub content reads against the hive's own credential, uncached builds are admitted at most 2 at a time and 8 per 10 minutes process-wide; a request past that limit still returns 200 with `source: "unavailable"` and a retry hint, while already-cached pairs keep being served. When a hub-managed spoke is upgraded without the operator clicking anything, its dashboard shows a dismissible banner at the top of the overview for owners and mergers: "Upgraded → : N releases. What changed ▸" ([#11067](https://github.com/hivecommons/hive/issues/11067)). Expanding it opens these release notes in a read-only modal. It appears once per upgrade per browser and never on a first visit. See [Dashboard-triggered standalone upgrades](dashboard-standalone-upgrades.md#release-notes-before-and-after-an-upgrade). + +## Does this build contain PR #N? + +"Merged" is not "deployed". Image tags move, a build can be untagged, and a digest says nothing about history, so the only sound answer is git ancestry ([#18915](https://github.com/hivecommons/hive/issues/18915)). Two read endpoints answer it from the commit a hive already reports running: + +- `GET /api/saas/build-contains?q=` on the hub, one answer per hive the caller can see in My Hives. +- `GET /api/version/contains?q=` on a hive, for that hive's own running build. + +`q` is a PR number (`123`, `#123`, `PR 123`; up to six digits) or a commit SHA (7 to 40 hex characters). A PR resolves to its merge commit. Each answer is one of: + +| `contains` | Meaning | +|---|---| +| `yes` | The merge commit (or the SHA) is the running commit or one of its ancestors. | +| `no` | Ancestry was resolved and it is not in the running build's history. A PR that was never merged is `no` for every hive. | +| `unknown` | Ancestry could not be established, and `reason` says why: the hive reports no usable commit, the commit is not in the repository history the hub can read (unpublished, force-pushed or from a fork), the PR does not exist, or the lookup failed. `unknown` is never a guess; try again or check the commit by hand. | + +The lookup reads the public repository through the hub's existing read-only GitHub identity (or the hive's own GitHub client for the hive endpoint) and sends only commit SHAs and a PR number. It adds no heartbeat field: the commit and image reference are what the hive already reports. One lookup compares at most 40 distinct running commits; hives past that answer `unknown`. + +A channel image can sit on an older commit than the newest merge (the "latest merged, not yet built" gap). The My Hives rows already carry both numbers separately: `behindTargetSHA` is the newest commit whose image is published for the hive's channel, and `branchTipSHA` is the newest merged commit on the hive's branch. A `no` for a PR merged after the channel's newest image therefore means "merged, not yet built", not "lost". diff --git a/src/docs/telemetry.md b/src/docs/telemetry.md index bfa59f39fa..9616a395b7 100644 --- a/src/docs/telemetry.md +++ b/src/docs/telemetry.md @@ -9,6 +9,7 @@ Hive sends a small number of operational signals outside the running hive only t | Hub heartbeat | Hive ID; org/repos/primary repo; configured AI author; GitHub API/base host; ACMM level; agent names, state, backend/model counts; governor mode and queue counts; process/version/image/uptime; dashboard URL/snapshot URL/public flag/cluster ID; health summaries; token/budget counters; contributor counts, leaderboard usernames/avatar URLs/task counts/current task; active/engaged dashboard usernames and last-action timestamps; repo activity counts; PR/CVE/fleet counters; advisory/error strings; non-secret GitHub App IDs/slugs/installation IDs/key fingerprints; dashboard-token hash; file-descriptor counts; cluster-health status. No raw GitHub tokens, App private keys, dashboard tokens, session IDs, or heartbeat secrets are sent. | Configured hub at `hub.url` / `HIVE_HUB_URL`; hub UI/API access is hub-admin/operator gated. | Sent every two minutes when the hive is hub-linked. A standalone hive with no hub URL does not heartbeat. Once hub-linked, sensitive identifier classes can be withheld with `hub.heartbeat_omit` (see [Withholding heartbeat identifiers](#withholding-heartbeat-identifiers)); other fields are not configurable. | Hub registry retention is operational state, not currently documented as a fixed expiry. | Remove the hub link (`hub.url` / `HIVE_HUB_URL`) to stop all hub features. `hub.heartbeat_omit` withholds identifier classes per hive; a core-heartbeat disable switch is still pending maintainer direction (tracking issue: [#10202](https://github.com/hivecommons/hive/issues/10202)). | `src/cmd/hive/boot_heartbeat_deps.go`; `src/cmd/hive/main.go` (`bootHeartbeatWith`); `src/pkg/hub/spoke/heartbeat.go` (`HeartbeatPayload`); `src/pkg/hub/hub_keys.go` (`SpokeHeartbeatKey`). | | Task-status push / contributor relay status | Hive ID, contributor summary, and leaderboard entries: GitHub username, avatar URL, trust tier, tasks completed/failed, active flag, and current task title. | Same configured hub, authenticated with the per-hive heartbeat bearer. | Defaults on when the hive is hub-linked; controlled by `hub.task_status_push` / `HIVE_HUB_TASK_STATUS_PUSH`. | Operational hub state; no fixed expiry documented. | Set `hub.task_status_push: false` or `HIVE_HUB_TASK_STATUS_PUSH=false` and restart; this stops only the separate task-status loop. | `src/cmd/hive/main.go` (`StartTaskStatusPush` collector); `src/pkg/hub/spoke/heartbeat.go` (`TaskStatusPayload`). | | Dashboard feedback reports | User-entered title/description/screenshots; optional diagnostics if the user keeps **Include diagnostics** checked: version, commit, channel, ACMM level, hive ID, hosted/hub-linked flags, agent count, agent names/backend/model/state, browser user agent/platform/language, screen/window size, dashboard page, plus recent console errors and failed local `/api` calls. Project org/repo is sent only if the user checks **Also include project org/repos**. Tokens, bearer strings, emails, and secret-looking key/value text are redacted before submission. | The diagnostic bundle is committed to the `hive-feedback` branch of `hivecommons/hive` or `hivecommons/docs` with the GitHub App installation token (hub-less: the spoke's; hub-linked: minted by the hub for that spoke). The issue itself is opened by the user from a prefilled `issues/new` URL that links to the bundle; Hive never authors feedback with a user, bot, or operator token, and dashboard login requests no OAuth scope (#1927). | User-initiated only. The modal previews exactly what will be sent; diagnostics can be unchecked; project org/repos require a second opt-in checkbox. | GitHub issue retention follows GitHub/project issue retention. The spoke stores up to 50 local feedback issue references in `/data/feedback-submissions.json`. | Do not submit; uncheck diagnostics/project context; remove screenshots. Operators can also avoid hub relay by not hub-linking. | `src/pkg/dashboard/static/index.html` (`FEEDBACK_DIAGNOSTIC_FIELDS`, preview, checkboxes); `src/pkg/dashboard/feedback.go`. | +| Build-containment lookup | A commit SHA (the hive's running commit and the commit being asked about) or a PR number, sent as part of a GitHub REST `compare` or `pulls` request. Only when an operator runs a lookup (`GET /api/saas/build-contains` on the hub, `GET /api/version/contains` on a hive). No hive identifier, org, repo name or user is in the request. | `api.github.com`, the public `hivecommons/hive` repository, using the hub's read-only GitHub identity or the hive's own configured GitHub client. The answer is shown to the caller only. | On demand only; no background polling. A hive with no GitHub client answers `unknown` and sends nothing. | None stored; compare answers are cached in memory, for the life of the process. | Do not run the lookup; there is no setting because nothing is sent otherwise. | `src/pkg/buildcontains/buildcontains.go`; `src/pkg/hub/build_contains.go`; `src/pkg/dashboard/api_version_contains.go`. | | NPS prompt | Score 1-4, optional free text, hive ID, and dashboard version. The signed-in username is used only locally for rate limiting and is not sent. | Hub `POST /api/nps/ingest`, or an explicitly configured NPS relay for standalone hives; only hub admins can read stored responses. | Hosted spokes default on; self-hosted/federated/standalone default off. Standalone relay requires explicit `hub.nps_enabled`/`HIVE_NPS_ENABLED` and `hub.nps_relay_url`/`HIVE_NPS_RELAY_URL`. | Hub store keeps at most 1,000 responses per hive and 10,000 total, oldest dropped first. | `hub.nps_enabled: false` or `HIVE_NPS_ENABLED=false`; leave relay URL unset. | `src/docs/nps.md`; `src/docs/env-vars.md`; `src/pkg/dashboard/nps.go`; `src/pkg/hub/nps.go`. | | Hosted hub web analytics | GA4 page/event data from hub-hosted pages, including custom hub events such as hive creation/deletion. Existing event code includes hive IDs and creation inputs such as org, primary repo, ACMM level, and cluster ID. | Google Analytics via `www.googletagmanager.com`, property `G-4707R797K3`. | Loaded by hosted hub static HTML pages. This is website analytics, not spoke software telemetry, but it still needs privacy review because custom events may include project identifiers. | Google Analytics retention is controlled in the GA property, not in this repository. | Browser tracking protections or removing the hosted hub GA script; there is no repository config flag. | `src/pkg/hub/assets/dashboard.html`; `src/pkg/hub/saas_pages.go`; `src/pkg/hub/static/*.html` pages such as `reading.html` and `cncf-reference-architecture.html`. | | Crash/error reporting | No Sentry/PostHog/Segment/Plausible crash reporter was found in `src` during the onboarding audit. Errors are logged locally; selected log-safe health/error strings can appear in hub heartbeats as described above. | Local logs and, for selected operational state, the configured hub. | No third-party crash reporting by default. | Local log/PVC retention is deployment-specific. | N/A for third-party crash reporting; disable hub link for heartbeat-carried operational errors. | Audit search: `telemetry|analytics|metrics push|phone.?home|posthog|segment|plausible|gtag|googletagmanager|sentry` over Go/HTML/JS/Markdown. | diff --git a/src/pkg/buildcontains/buildcontains.go b/src/pkg/buildcontains/buildcontains.go new file mode 100644 index 0000000000..7b92f60ff7 --- /dev/null +++ b/src/pkg/buildcontains/buildcontains.go @@ -0,0 +1,336 @@ +// Package buildcontains answers "does the build this hive is running contain +// PR #N (or commit X)?" from git ancestry, and from nothing else. +// +// Image tags move, builds can be untagged, and a digest says nothing about +// history, so "merged" is routinely mistaken for "deployed". The only sound +// answer is ancestry: the PR's merge commit is an ancestor of (or equal to) +// the commit the hive reports running, or it is not. +// +// The package is deliberately small and pure. The repository history lives +// behind the Source interface so the hub and a hive's own dashboard can each +// supply their own GitHub client, and so tests can assert the invariants +// without a network: +// +// - A commit that cannot be resolved is Unknown, never Yes and never No. +// - A PR whose merge commit is not in the running build's history is No. +// - Any lookup failure is Unknown. A guess is never returned. +package buildcontains + +import ( + "context" + "fmt" + "strconv" + "strings" + "sync" +) + +// Verdict is the three-valued answer to "does this build contain it?". +type Verdict string + +const ( + // Yes means the queried commit is the running commit or one of its ancestors. + Yes Verdict = "yes" + // No means ancestry was resolved and the queried commit is not in the + // running build's history (or the PR was never merged). + No Verdict = "no" + // Unknown means ancestry could not be established. It is the only + // permitted answer to a failed, partial or unresolvable lookup. + Unknown Verdict = "unknown" +) + +// QueryKind says how a Query was interpreted. +type QueryKind string + +const ( + KindPR QueryKind = "pr" + KindCommit QueryKind = "commit" +) + +const ( + // maxPRDigits bounds what is read as a PR number. A string of seven or + // more digits is read as a commit SHA instead: the repository will not + // reach a million PRs, while a 7-character SHA made only of digits is + // ordinary. + maxPRDigits = 6 + // minSHALen and maxSHALen bound an accepted hex commit reference: the + // canonical 7-character short form up to a full 40-character SHA-1. + minSHALen = 7 + maxSHALen = 40 + // MaxCompares caps how many distinct running commits one lookup compares. + // Each is a remote request, so a fleet of hives on many different builds + // must not fan out without limit; the rest answer Unknown. + MaxCompares = 40 + // compareConcurrency bounds in-flight compares for one lookup. + compareConcurrency = 4 + // cacheMax bounds a CachingSource. Dropped wholesale on overflow: an + // entry is one cheap request to re-derive. + cacheMax = 1024 +) + +// Reasons attached to Unknown/No results. They are display text for operators +// and part of the read API, so they are constants. +const ( + ReasonNoRunningCommit = "the hive reports no resolvable commit" + ReasonCommitNotFound = "the commit is not in the repository history this hub can read (unpublished, force-pushed or from a fork)" + ReasonCompareFailed = "the history lookup failed; try again" + ReasonCompareStatus = "the history lookup returned an unrecognised status" + ReasonPRNotFound = "pull request not found" + ReasonPRLookupFailed = "the pull request lookup failed; try again" + ReasonPRNotMerged = "the pull request is not merged, so no build of the base branch contains it" + ReasonPRNoMergeCommit = "the pull request is merged but reports no merge commit" + ReasonBudgetExceeded = "too many distinct builds in one lookup; narrow the fleet or retry" + ReasonNoQueryCommit = "no commit to look up" + reasonBadQueryTemplate = "not a PR number or a commit SHA: %q" +) + +// Query is a parsed lookup: a PR number or a commit SHA. +type Query struct { + Kind QueryKind `json:"kind"` + // PR is set when Kind is KindPR. + PR int `json:"pr,omitempty"` + // Commit is set when Kind is KindCommit (lowercased, as typed). + Commit string `json:"commit,omitempty"` +} + +// ParseQuery reads a PR number ("123", "#123", "PR 123", "pr#123") or a commit +// SHA (7 to 40 hex characters). Digits-only input of up to six digits is a PR +// number; anything else must be a hex SHA. Everything else is an error. +func ParseQuery(raw string) (Query, error) { + s := strings.ToLower(strings.TrimSpace(raw)) + if s == "" { + return Query{}, fmt.Errorf(reasonBadQueryTemplate, raw) + } + digits := strings.TrimLeft(strings.TrimPrefix(s, "pr"), " #-:") + if strings.HasPrefix(s, "#") { + digits = strings.TrimLeft(s, "# ") + } + if isDigits(digits) && len(digits) <= maxPRDigits { + n, err := strconv.Atoi(digits) + if err == nil && n > 0 { + return Query{Kind: KindPR, PR: n}, nil + } + return Query{}, fmt.Errorf(reasonBadQueryTemplate, raw) + } + if IsCommitRef(s) { + return Query{Kind: KindCommit, Commit: s}, nil + } + return Query{}, fmt.Errorf(reasonBadQueryTemplate, raw) +} + +// IsCommitRef reports whether s is a plausible hex commit reference. A hive +// that reports "unknown", "dev" or an empty string is therefore not resolvable. +func IsCommitRef(s string) bool { + s = strings.TrimSpace(s) + if len(s) < minSHALen || len(s) > maxSHALen { + return false + } + for _, c := range s { + isHex := (c >= '0' && c <= '9') || (c >= 'a' && c <= 'f') || (c >= 'A' && c <= 'F') + if !isHex { + return false + } + } + return true +} + +func isDigits(s string) bool { + if s == "" { + return false + } + for _, c := range s { + if c < '0' || c > '9' { + return false + } + } + return true +} + +// PullRequest is the slice of a pull request the lookup needs. +type PullRequest struct { + Merged bool + MergeCommit string +} + +// Source supplies repository history. Implementations must report "not found" +// through the found flag and reserve err for transport and server failures, so +// that a missing commit (Unknown, reason says why) is distinguishable from a +// lookup that failed (Unknown, try again). +type Source interface { + // Compare returns GitHub's compare status of base...head: "identical", + // "ahead" (head has commits base lacks, base is an ancestor), "behind" or + // "diverged". found is false when either commit cannot be resolved. + Compare(ctx context.Context, base, head string) (status string, found bool, err error) + // PullRequest looks one pull request up. found is false when it does not exist. + PullRequest(ctx context.Context, number int) (pr PullRequest, found bool, err error) +} + +// Result is one hive's answer. +type Result struct { + Contains Verdict `json:"contains"` + Reason string `json:"reason,omitempty"` +} + +// Target is a resolved Query: the commit whose presence is being tested, or an +// answer that holds for every hive without any comparison. +type Target struct { + // Query is what was asked. + Query Query `json:"query"` + // Commit is the commit tested for presence ("" when Final). + Commit string `json:"commit,omitempty"` + // Final is true when the answer is the same for every hive and needs no + // comparison (an unmerged or unknown PR). + Final bool `json:"-"` + // Answer holds the verdict when Final. + Answer Result `json:"-"` +} + +// Resolve turns a Query into the commit to test. A PR resolves to its merge +// commit; a PR that is not merged resolves to a final No, and one that cannot +// be read resolves to a final Unknown. +func Resolve(ctx context.Context, src Source, q Query) Target { + t := Target{Query: q} + switch q.Kind { + case KindCommit: + if !IsCommitRef(q.Commit) { + t.Final, t.Answer = true, Result{Contains: Unknown, Reason: ReasonNoQueryCommit} + return t + } + t.Commit = q.Commit + case KindPR: + pr, found, err := src.PullRequest(ctx, q.PR) + switch { + case err != nil: + t.Final, t.Answer = true, Result{Contains: Unknown, Reason: ReasonPRLookupFailed} + case !found: + t.Final, t.Answer = true, Result{Contains: Unknown, Reason: ReasonPRNotFound} + case !pr.Merged: + t.Final, t.Answer = true, Result{Contains: No, Reason: ReasonPRNotMerged} + case !IsCommitRef(pr.MergeCommit): + t.Final, t.Answer = true, Result{Contains: Unknown, Reason: ReasonPRNoMergeCommit} + default: + t.Commit = pr.MergeCommit + } + default: + t.Final, t.Answer = true, Result{Contains: Unknown, Reason: ReasonNoQueryCommit} + } + return t +} + +// Check answers whether running contains the target commit. +func (t Target) Check(ctx context.Context, src Source, running string) Result { + running = strings.TrimSpace(running) + if !IsCommitRef(running) { + return Result{Contains: Unknown, Reason: ReasonNoRunningCommit} + } + if t.Final { + return t.Answer + } + if t.Commit == "" { + return Result{Contains: Unknown, Reason: ReasonNoQueryCommit} + } + status, found, err := src.Compare(ctx, t.Commit, running) + if err != nil { + return Result{Contains: Unknown, Reason: ReasonCompareFailed} + } + if !found { + return Result{Contains: Unknown, Reason: ReasonCommitNotFound} + } + switch status { + case "identical", "ahead": + return Result{Contains: Yes} + case "behind", "diverged": + return Result{Contains: No} + default: + return Result{Contains: Unknown, Reason: ReasonCompareStatus} + } +} + +// CheckAll answers for many running commits at once, keyed by the commit as +// given. Each distinct commit is compared once, at most MaxCompares of them, +// with bounded concurrency; the remainder are Unknown. +func (t Target) CheckAll(ctx context.Context, src Source, running []string) map[string]Result { + out := make(map[string]Result, len(running)) + var todo []string + for _, r := range running { + if _, seen := out[r]; seen { + continue + } + if t.Final || !IsCommitRef(r) { + out[r] = t.Check(ctx, src, r) + continue + } + if len(todo) >= MaxCompares { + out[r] = Result{Contains: Unknown, Reason: ReasonBudgetExceeded} + continue + } + out[r] = Result{Contains: Unknown, Reason: ReasonCompareFailed} + todo = append(todo, r) + } + var ( + mu sync.Mutex + wg sync.WaitGroup + sem = make(chan struct{}, compareConcurrency) + ) + for _, r := range todo { + wg.Add(1) + sem <- struct{}{} + go func(r string) { + defer wg.Done() + defer func() { <-sem }() + res := t.Check(ctx, src, r) + mu.Lock() + out[r] = res + mu.Unlock() + }(r) + } + wg.Wait() + return out +} + +type compareKey struct{ base, head string } + +type compareValue struct { + status string +} + +// CachingSource memoises definitive compare answers. Ancestry between two +// fixed commits never changes, so a found result is cached for good; failures +// and not-found results are never cached, so a transient error cannot stick. +type CachingSource struct { + inner Source + mu sync.Mutex + cache map[compareKey]compareValue +} + +// NewCachingSource wraps inner with the compare cache. +func NewCachingSource(inner Source) *CachingSource { + return &CachingSource{inner: inner, cache: map[compareKey]compareValue{}} +} + +// Compare implements Source. +func (c *CachingSource) Compare(ctx context.Context, base, head string) (string, bool, error) { + key := compareKey{base: strings.ToLower(base), head: strings.ToLower(head)} + c.mu.Lock() + v, ok := c.cache[key] + c.mu.Unlock() + if ok { + return v.status, true, nil + } + status, found, err := c.inner.Compare(ctx, base, head) + if err != nil || !found { + return status, found, err + } + c.mu.Lock() + if len(c.cache) >= cacheMax { + c.cache = map[compareKey]compareValue{} + } + c.cache[key] = compareValue{status: status} + c.mu.Unlock() + return status, true, nil +} + +// PullRequest implements Source. Pull request state changes (open, then +// merged), so it is never cached. +func (c *CachingSource) PullRequest(ctx context.Context, number int) (PullRequest, bool, error) { + return c.inner.PullRequest(ctx, number) +} diff --git a/src/pkg/buildcontains/buildcontains_test.go b/src/pkg/buildcontains/buildcontains_test.go new file mode 100644 index 0000000000..ea0c9fa2bc --- /dev/null +++ b/src/pkg/buildcontains/buildcontains_test.go @@ -0,0 +1,210 @@ +package buildcontains + +import ( + "context" + "errors" + "sync/atomic" + "testing" +) + +// fakeSource serves a fixed history: commits maps "base...head" to a compare +// status; a pair that is absent is "not found". +type fakeSource struct { + compares map[string]string + failing map[string]bool + prs map[int]PullRequest + prErr error + calls atomic.Int32 +} + +func (f *fakeSource) Compare(_ context.Context, base, head string) (string, bool, error) { + f.calls.Add(1) + k := base + "..." + head + if f.failing[k] { + return "", false, errors.New("boom") + } + st, ok := f.compares[k] + return st, ok, nil +} + +func (f *fakeSource) PullRequest(_ context.Context, n int) (PullRequest, bool, error) { + if f.prErr != nil { + return PullRequest{}, false, f.prErr + } + pr, ok := f.prs[n] + return pr, ok, nil +} + +const ( + mergeSHA = "aaaaaaa1111111" + runSHA = "bbbbbbb2222222" +) + +func TestParseQuery(t *testing.T) { + cases := []struct { + in string + kind QueryKind + pr int + sha string + ok bool + }{ + {"123", KindPR, 123, "", true}, + {"#123", KindPR, 123, "", true}, + {"PR 123", KindPR, 123, "", true}, + {"pr#123", KindPR, 123, "", true}, + {"abcdef1", KindCommit, 0, "abcdef1", true}, + {"ABCDEF1234", KindCommit, 0, "abcdef1234", true}, + {"1234567", KindCommit, 0, "1234567", true}, + {"abc12", "", 0, "", false}, + {"", "", 0, "", false}, + {"0", "", 0, "", false}, + {"not-a-sha", "", 0, "", false}, + {"unknown", "", 0, "", false}, + } + for _, c := range cases { + q, err := ParseQuery(c.in) + if (err == nil) != c.ok { + t.Fatalf("ParseQuery(%q) err=%v want ok=%v", c.in, err, c.ok) + } + if !c.ok { + continue + } + if q.Kind != c.kind || q.PR != c.pr || q.Commit != c.sha { + t.Fatalf("ParseQuery(%q) = %+v", c.in, q) + } + } +} + +func TestCommitContainment(t *testing.T) { + src := &fakeSource{compares: map[string]string{ + mergeSHA + "..." + runSHA: "ahead", + }} + tgt := Resolve(context.Background(), src, Query{Kind: KindCommit, Commit: mergeSHA}) + if got := tgt.Check(context.Background(), src, runSHA); got.Contains != Yes { + t.Fatalf("ancestor must be yes, got %+v", got) + } +} + +func TestStatusMapping(t *testing.T) { + for status, want := range map[string]Verdict{ + "identical": Yes, + "ahead": Yes, + "behind": No, + "diverged": No, + "weird": Unknown, + } { + src := &fakeSource{compares: map[string]string{mergeSHA + "..." + runSHA: status}} + tgt := Target{Commit: mergeSHA} + if got := tgt.Check(context.Background(), src, runSHA); got.Contains != want { + t.Fatalf("status %q: got %q want %q", status, got.Contains, want) + } + } +} + +// An unresolvable commit must be unknown, never yes and never no. +func TestUnresolvableCommitIsUnknown(t *testing.T) { + src := &fakeSource{compares: map[string]string{}} + tgt := Target{Commit: mergeSHA} + got := tgt.Check(context.Background(), src, runSHA) + if got.Contains != Unknown || got.Reason == "" { + t.Fatalf("missing commit must be unknown with a reason, got %+v", got) + } + for _, running := range []string{"", "unknown", "dev", "abc", " "} { + got := tgt.Check(context.Background(), src, running) + if got.Contains != Unknown { + t.Fatalf("running %q must be unknown, got %+v", running, got) + } + } +} + +func TestCompareErrorIsUnknownNotNo(t *testing.T) { + src := &fakeSource{failing: map[string]bool{mergeSHA + "..." + runSHA: true}} + got := Target{Commit: mergeSHA}.Check(context.Background(), src, runSHA) + if got.Contains != Unknown { + t.Fatalf("transport failure must be unknown, got %+v", got) + } +} + +// A PR whose merge commit is not in the build's history is no. +func TestPRNotInHistoryIsNo(t *testing.T) { + src := &fakeSource{ + compares: map[string]string{mergeSHA + "..." + runSHA: "behind"}, + prs: map[int]PullRequest{7: {Merged: true, MergeCommit: mergeSHA}}, + } + tgt := Resolve(context.Background(), src, Query{Kind: KindPR, PR: 7}) + if tgt.Commit != mergeSHA { + t.Fatalf("PR must resolve to its merge commit, got %+v", tgt) + } + if got := tgt.Check(context.Background(), src, runSHA); got.Contains != No { + t.Fatalf("got %+v", got) + } +} + +func TestPRResolution(t *testing.T) { + src := &fakeSource{prs: map[int]PullRequest{ + 1: {Merged: false}, + 2: {Merged: true, MergeCommit: ""}, + }} + cases := []struct { + name string + src Source + pr int + want Verdict + }{ + {"unmerged", src, 1, No}, + {"merged without commit", src, 2, Unknown}, + {"missing", src, 99, Unknown}, + {"lookup error", &fakeSource{prErr: errors.New("boom")}, 1, Unknown}, + } + for _, c := range cases { + tgt := Resolve(context.Background(), c.src, Query{Kind: KindPR, PR: c.pr}) + got := tgt.Check(context.Background(), c.src, runSHA) + if got.Contains != c.want { + t.Fatalf("%s: got %+v want %q", c.name, got, c.want) + } + } +} + +func TestCheckAllDedupesAndBounds(t *testing.T) { + src := &fakeSource{compares: map[string]string{mergeSHA + "..." + runSHA: "ahead"}} + tgt := Target{Commit: mergeSHA} + out := tgt.CheckAll(context.Background(), src, []string{runSHA, runSHA, runSHA, "unknown"}) + if src.calls.Load() != 1 { + t.Fatalf("one distinct commit must be one compare, got %d", src.calls.Load()) + } + if out[runSHA].Contains != Yes || out["unknown"].Contains != Unknown { + t.Fatalf("got %+v", out) + } + + many := make([]string, 0, MaxCompares+5) + for i := 0; i < MaxCompares+5; i++ { + many = append(many, "c"+string(rune('a'+i%6))+"00000"+string(rune('0'+i/10))+string(rune('0'+i%10))) + } + out = tgt.CheckAll(context.Background(), &fakeSource{}, many) + for _, r := range many { + if out[r].Contains == Yes { + t.Fatalf("an unresolved commit must never be yes: %q", r) + } + } +} + +func TestCachingSourceCachesOnlyDefinitiveAnswers(t *testing.T) { + inner := &fakeSource{compares: map[string]string{mergeSHA + "..." + runSHA: "ahead"}} + c := NewCachingSource(inner) + for i := 0; i < 3; i++ { + if st, found, err := c.Compare(context.Background(), mergeSHA, runSHA); st != "ahead" || !found || err != nil { + t.Fatalf("got %q %v %v", st, found, err) + } + } + if inner.calls.Load() != 1 { + t.Fatalf("definitive answer must be cached, calls=%d", inner.calls.Load()) + } + for i := 0; i < 2; i++ { + if _, found, _ := c.Compare(context.Background(), "ccccccc", runSHA); found { + t.Fatal("missing commit must stay not found") + } + } + if inner.calls.Load() != 3 { + t.Fatalf("not-found must not be cached, calls=%d", inner.calls.Load()) + } +} diff --git a/src/pkg/dashboard/api.go b/src/pkg/dashboard/api.go index c3ba88ac79..8a1563175a 100644 --- a/src/pkg/dashboard/api.go +++ b/src/pkg/dashboard/api.go @@ -569,6 +569,7 @@ func (s *Server) RegisterAPI(deps *Dependencies) { // Agents discovered in managed repos' .hive/agents/ (#18491, // api_repo_agents.go): list, approve, reject, rescan. s.registerRepoAgentRoutes() + s.registerVersionContainsRoute() } var ( diff --git a/src/pkg/dashboard/api_version_contains.go b/src/pkg/dashboard/api_version_contains.go new file mode 100644 index 0000000000..db993d474b --- /dev/null +++ b/src/pkg/dashboard/api_version_contains.go @@ -0,0 +1,114 @@ +package dashboard + +import ( + "context" + "net/http" + "time" + + gh "github.com/google/go-github/v72/github" + + "github.com/hivecommons/hive/pkg/buildcontains" + spoke "github.com/hivecommons/hive/pkg/hub/spoke" +) + +// versionContainsTimeout bounds one lookup (a PR read plus one compare). +const versionContainsTimeout = 15 * time.Second + +// versionContainsOwner and versionContainsRepo name the repository whose +// history the lookup reads: the one Hive builds are cut from. +const ( + versionContainsOwner = "hivecommons" + versionContainsRepo = "hive" +) + +// reasonNoGitHub is the answer when this hive has no GitHub client to read +// history with. It is unknown, never a guess. +const reasonNoGitHub = "this hive has no GitHub access to read repository history" + +// versionContainsResponse is the body of GET /api/version/contains. +type versionContainsResponse struct { + Query buildcontains.Query `json:"query"` + Commit string `json:"commit,omitempty"` + // Running is the commit this hive reports running (the same value + // /api/version reports as hash). + Running string `json:"running,omitempty"` + Channel string `json:"channel,omitempty"` + Contains string `json:"contains"` + Reason string `json:"reason,omitempty"` +} + +// ghContainsSource reads ancestry through the hive's existing GitHub client. +// It requests only commit SHAs and a PR number of the public repository. +type ghContainsSource struct{ client *gh.Client } + +func (g ghContainsSource) Compare(ctx context.Context, base, head string) (string, bool, error) { + cmp, resp, err := g.client.Repositories.CompareCommits(ctx, versionContainsOwner, versionContainsRepo, base, head, &gh.ListOptions{PerPage: 1}) + if err != nil { + if resp != nil && (resp.StatusCode == http.StatusNotFound || resp.StatusCode == http.StatusUnprocessableEntity) { + return "", false, nil + } + return "", false, err + } + if cmp.GetStatus() == "" { + return "", false, nil + } + return cmp.GetStatus(), true, nil +} + +func (g ghContainsSource) PullRequest(ctx context.Context, number int) (buildcontains.PullRequest, bool, error) { + pr, resp, err := g.client.PullRequests.Get(ctx, versionContainsOwner, versionContainsRepo, number) + if err != nil { + if resp != nil && resp.StatusCode == http.StatusNotFound { + return buildcontains.PullRequest{}, false, nil + } + return buildcontains.PullRequest{}, false, err + } + return buildcontains.PullRequest{Merged: pr.GetMerged(), MergeCommit: pr.GetMergeCommitSHA()}, true, nil +} + +// versionContainsAnswer resolves the query and tests the running commit. Pure +// over src: an unresolvable commit is unknown, a PR outside the build's +// history is no. +func versionContainsAnswer(ctx context.Context, src buildcontains.Source, q buildcontains.Query, running, channel string) versionContainsResponse { + tgt := buildcontains.Resolve(ctx, src, q) + res := tgt.Check(ctx, src, running) + return versionContainsResponse{ + Query: q, + Commit: tgt.Commit, + Running: running, + Channel: channel, + Contains: string(res.Contains), + Reason: res.Reason, + } +} + +// handleVersionContains answers GET /api/version/contains?q=: does the build this hive is running contain it? +func (s *Server) handleVersionContains(w http.ResponseWriter, r *http.Request) { + q, err := buildcontains.ParseQuery(r.URL.Query().Get("q")) + if err != nil { + jsonError(w, err.Error(), http.StatusBadRequest) + return + } + channel := versionChannel + if versionImageSource != nil { + channel = spoke.ImageReleaseChannel(versionImageSource()) + } + if s.deps == nil || s.deps.GHClient == nil || s.deps.GHClient.GoGitHub() == nil { + jsonResponse(w, versionContainsResponse{ + Query: q, Running: versionHash, Channel: channel, + Contains: string(buildcontains.Unknown), Reason: reasonNoGitHub, + }) + return + } + ctx, cancel := context.WithTimeout(r.Context(), versionContainsTimeout) + defer cancel() + src := ghContainsSource{client: s.deps.GHClient.GoGitHub()} + jsonResponse(w, versionContainsAnswer(ctx, src, q, versionHash, channel)) +} + +// registerVersionContainsRoute wires the lookup. Kept apart from RegisterAPI's +// route table so the line numbers the API reference cites do not shift. +func (s *Server) registerVersionContainsRoute() { + s.mux.HandleFunc("GET /api/version/contains", s.handleVersionContains) +} diff --git a/src/pkg/dashboard/api_version_contains_test.go b/src/pkg/dashboard/api_version_contains_test.go new file mode 100644 index 0000000000..5753fc181b --- /dev/null +++ b/src/pkg/dashboard/api_version_contains_test.go @@ -0,0 +1,58 @@ +package dashboard + +import ( + "context" + "testing" + + "github.com/hivecommons/hive/pkg/buildcontains" +) + +type fakeVersionHistory struct { + compares map[string]string + prs map[int]buildcontains.PullRequest +} + +func (f fakeVersionHistory) Compare(_ context.Context, base, head string) (string, bool, error) { + st, ok := f.compares[base+"..."+head] + return st, ok, nil +} + +func (f fakeVersionHistory) PullRequest(_ context.Context, n int) (buildcontains.PullRequest, bool, error) { + pr, ok := f.prs[n] + return pr, ok, nil +} + +func TestVersionContainsAnswer(t *testing.T) { + hist := fakeVersionHistory{ + compares: map[string]string{ + "1a2b3c4d5e6f...bbbbbbb": "ahead", + "1a2b3c4d5e6f...aaaaaaa": "behind", + }, + prs: map[int]buildcontains.PullRequest{5: {Merged: true, MergeCommit: "1a2b3c4d5e6f"}}, + } + ctx := context.Background() + pr := buildcontains.Query{Kind: buildcontains.KindPR, PR: 5} + + if got := versionContainsAnswer(ctx, hist, pr, "bbbbbbb", "stable"); got.Contains != "yes" || got.Channel != "stable" { + t.Fatalf("containing build must be yes: %+v", got) + } + if got := versionContainsAnswer(ctx, hist, pr, "aaaaaaa", "stable"); got.Contains != "no" { + t.Fatalf("a PR outside the build's history must be no: %+v", got) + } + // A commit the history cannot resolve is unknown, never yes or no. + if got := versionContainsAnswer(ctx, hist, pr, "ccccccc", "stable"); got.Contains != "unknown" || got.Reason == "" { + t.Fatalf("unresolvable commit must be unknown: %+v", got) + } + // A hive that reports no usable commit is unknown. + if got := versionContainsAnswer(ctx, hist, pr, "unknown", ""); got.Contains != "unknown" { + t.Fatalf("unresolvable running commit must be unknown: %+v", got) + } +} + +func TestVersionContainsAnswerUnmergedPR(t *testing.T) { + hist := fakeVersionHistory{prs: map[int]buildcontains.PullRequest{6: {Merged: false}}} + got := versionContainsAnswer(context.Background(), hist, buildcontains.Query{Kind: buildcontains.KindPR, PR: 6}, "bbbbbbb", "") + if got.Contains != "no" { + t.Fatalf("an unmerged PR is in no build: %+v", got) + } +} diff --git a/src/pkg/dashboard/import_count_test.go b/src/pkg/dashboard/import_count_test.go index 8ec2a3495a..96feb86bb7 100644 --- a/src/pkg/dashboard/import_count_test.go +++ b/src/pkg/dashboard/import_count_test.go @@ -77,8 +77,10 @@ func TestDashboardInternalImportCountRatchet(t *testing.T) { // subpackage, the hive-mx delivery contract) behind the email-in routes // (hivecommons/hive#18395), plus pkg/repoagents, the .hive/agents/ // discoverer behind the /api/agents/discovered approval routes - // (hivecommons/hive#18491). - const maxDashboardInternalImports = 65 + // (hivecommons/hive#18491), plus pkg/buildcontains, the dependency-free + // ancestry resolver shared with the hub behind GET /api/version/contains + // (hivecommons/hive#18915). + const maxDashboardInternalImports = 66 entries, err := os.ReadDir(".") if err != nil { diff --git a/src/pkg/hub/build_contains.go b/src/pkg/hub/build_contains.go new file mode 100644 index 0000000000..3f42ec3104 --- /dev/null +++ b/src/pkg/hub/build_contains.go @@ -0,0 +1,226 @@ +package hub + +import ( + "context" + "encoding/json" + "fmt" + "net/http" + "net/url" + "strings" + "time" + + "github.com/hivecommons/hive/pkg/buildcontains" +) + +// buildContainsTimeout bounds one whole lookup: the PR read plus every +// ancestry compare. A lookup that runs out of time answers unknown for the +// hives it did not finish, never a guess. +const buildContainsTimeout = 20 * time.Second + +// buildContainsRepoPath is the repository whose history is consulted. Hives +// run builds of this repository only; a hive on a fork build resolves to +// unknown rather than being compared against the wrong history. +const buildContainsRepoPath = "/repos/hivecommons/hive" + +// buildContainsSource is the history the lookup reads. A var so tests supply +// a fake history without a network round-trip. +var buildContainsSource buildcontains.Source = buildcontains.NewCachingSource(hubContainsSource{}) + +// hubContainsSource reads ancestry from the GitHub REST API with the hub's +// existing read-only identity (the same client, token and base URL the +// channel-distance and commit-behind lookups use). It sends only commit SHAs +// and a PR number of a public repository. +type hubContainsSource struct{} + +func (hubContainsSource) get(ctx context.Context, path string) (*http.Response, error) { + ctx = hubGitHubCallerContext(ctx, "build_contains") + req, err := http.NewRequestWithContext(ctx, http.MethodGet, githubAPIBase+path, nil) + if err != nil { + return nil, err + } + req.Header.Set("Accept", "application/vnd.github+json") + authGitHubRequest(req) + return hubGitHubHTTPClient().Do(req) +} + +// Compare implements buildcontains.Source. per_page=1 keeps the payload to +// the status and counts; the commit list is not needed. +func (hubContainsSource) Compare(ctx context.Context, base, head string) (string, bool, error) { + resp, err := hubContainsSource{}.get(ctx, fmt.Sprintf("%s/compare/%s...%s?per_page=1", + buildContainsRepoPath, url.PathEscape(base), url.PathEscape(head))) + if err != nil { + return "", false, err + } + defer func() { _ = resp.Body.Close() }() + switch resp.StatusCode { + case http.StatusOK: + case http.StatusNotFound, http.StatusUnprocessableEntity: + // GitHub answers 404 for an unknown SHA and 422 for an unparseable + // one: the commit is not resolvable, which is not a failure. + return "", false, nil + default: + return "", false, fmt.Errorf("compare %s...%s: HTTP %d", base, head, resp.StatusCode) + } + var body struct { + Status string `json:"status"` + } + if err := json.NewDecoder(resp.Body).Decode(&body); err != nil { + return "", false, err + } + if body.Status == "" { + return "", false, fmt.Errorf("compare %s...%s: empty status", base, head) + } + return body.Status, true, nil +} + +// PullRequest implements buildcontains.Source. +func (hubContainsSource) PullRequest(ctx context.Context, number int) (buildcontains.PullRequest, bool, error) { + resp, err := hubContainsSource{}.get(ctx, fmt.Sprintf("%s/pulls/%d", buildContainsRepoPath, number)) + if err != nil { + return buildcontains.PullRequest{}, false, err + } + defer func() { _ = resp.Body.Close() }() + switch resp.StatusCode { + case http.StatusOK: + case http.StatusNotFound: + return buildcontains.PullRequest{}, false, nil + default: + return buildcontains.PullRequest{}, false, fmt.Errorf("pull %d: HTTP %d", number, resp.StatusCode) + } + var body struct { + Merged bool `json:"merged"` + MergeCommitSHA string `json:"merge_commit_sha"` + } + if err := json.NewDecoder(resp.Body).Decode(&body); err != nil { + return buildcontains.PullRequest{}, false, err + } + return buildcontains.PullRequest{Merged: body.Merged, MergeCommit: body.MergeCommitSHA}, true, nil +} + +// buildContainsHive is the slice of a My Hives row the lookup reads. These are +// the commit and image reference the spoke already reports on its heartbeat +// plus the hub-owned tracked channel; nothing new is collected. +type buildContainsHive struct { + ID string `json:"id"` + Name string `json:"name"` + ProjectName string `json:"projectName"` + GitHash string `json:"gitHash"` + ImageRef string `json:"imageRef"` + TrackedChannel string `json:"trackedChannel"` +} + +// BuildContainsHive is one hive's row in the lookup response. +type BuildContainsHive struct { + ID string `json:"id"` + Name string `json:"name,omitempty"` + Commit string `json:"commit,omitempty"` + Channel string `json:"channel,omitempty"` + Contains string `json:"contains"` + Reason string `json:"reason,omitempty"` +} + +// BuildContainsResponse is the body of GET /api/saas/build-contains. +type BuildContainsResponse struct { + Query buildcontains.Query `json:"query"` + // Commit is the commit whose presence was tested: the PR's merge commit + // for a PR query, the SHA itself for a commit query. Empty when the answer + // needed no comparison. + Commit string `json:"commit,omitempty"` + // Reason explains a fleet-wide answer (an unmerged or unknown PR). + Reason string `json:"reason,omitempty"` + Hives []BuildContainsHive `json:"hives"` +} + +// buildContainsAnswer resolves the query once and tests every hive's running +// commit against it. Pure over src, so the invariants are testable without a +// network: an unresolvable commit is unknown, a PR outside a build's history +// is no. +func buildContainsAnswer(ctx context.Context, src buildcontains.Source, q buildcontains.Query, hives []buildContainsHive) BuildContainsResponse { + tgt := buildcontains.Resolve(ctx, src, q) + resp := BuildContainsResponse{Query: q, Commit: tgt.Commit, Hives: make([]BuildContainsHive, 0, len(hives))} + if tgt.Final { + resp.Reason = tgt.Answer.Reason + } + running := make([]string, 0, len(hives)) + for _, h := range hives { + running = append(running, strings.TrimSpace(h.GitHash)) + } + results := tgt.CheckAll(ctx, src, running) + for _, h := range hives { + commit := strings.TrimSpace(h.GitHash) + res := results[commit] + if res.Contains == "" { + res = buildcontains.Result{Contains: buildcontains.Unknown, Reason: buildcontains.ReasonNoRunningCommit} + } + name := h.ProjectName + if name == "" { + name = h.Name + } + resp.Hives = append(resp.Hives, BuildContainsHive{ + ID: h.ID, + Name: name, + Commit: commit, + Channel: spokeReleaseChannel(h.ImageRef, h.TrackedChannel), + Contains: string(res.Contains), + Reason: res.Reason, + }) + } + return resp +} + +// handleBuildContains answers GET /api/saas/build-contains?q= for the hives the signed-in user can already see in My Hives. It +// reads the same per-user snapshot as the list, so it can neither show a hive +// the list would hide nor add a data source. +func (s *HubServer) handleBuildContains(w http.ResponseWriter, r *http.Request) { + username := s.getAuthUser(r) + if username == "" { + w.WriteHeader(http.StatusUnauthorized) + return + } + q, err := buildcontains.ParseQuery(r.URL.Query().Get("q")) + if err != nil { + writeJSONError(w, http.StatusBadRequest, err.Error()) + return + } + hives, err := s.buildContainsVisibleHives(username) + if err != nil { + s.logger.Warn("handleBuildContains: could not read hives", "user", username, "error", err) + writeJSONError(w, http.StatusInternalServerError, "failed to read hives") + return + } + ctx, cancel := context.WithTimeout(r.Context(), buildContainsTimeout) + defer cancel() + resp := buildContainsAnswer(ctx, buildContainsSource, q, hives) + w.Header().Set("Content-Type", "application/json") + _ = json.NewEncoder(w).Encode(resp) +} + +// buildContainsVisibleHives returns the caller's My Hives rows, preferring the +// cached snapshot (even a stale one: a commit that moved since is covered by +// the next heartbeat, and the answer states which commit it tested). +func (s *HubServer) buildContainsVisibleHives(username string) ([]buildContainsHive, error) { + body, _, ok := s.myHivesCachedResponse(myHivesSnapshotKey(username, ""), true) + if !ok { + var err error + body, err = s.buildMyHivesResponse(username, nil) + if err != nil { + return nil, err + } + s.storeMyHivesSnapshot(myHivesSnapshotKey(username, ""), body) + } + var parsed struct { + Hives []buildContainsHive `json:"hives"` + } + if err := json.Unmarshal(body, &parsed); err != nil { + return nil, err + } + return parsed.Hives, nil +} + +// registerBuildContainsRoutes wires the lookup. Kept apart from +// registerSaaSRoutes so the route table's line numbers (cited by the API +// reference) do not shift. +func (s *HubServer) registerBuildContainsRoutes() { + s.mux.HandleFunc("GET /api/saas/build-contains", s.requireAuth(s.handleBuildContains)) +} diff --git a/src/pkg/hub/build_contains_test.go b/src/pkg/hub/build_contains_test.go new file mode 100644 index 0000000000..ddba25e16c --- /dev/null +++ b/src/pkg/hub/build_contains_test.go @@ -0,0 +1,130 @@ +package hub + +import ( + "context" + "encoding/json" + "testing" + + "github.com/hivecommons/hive/pkg/buildcontains" +) + +type fakeContainsHistory struct { + compares map[string]string + prs map[int]buildcontains.PullRequest +} + +func (f fakeContainsHistory) Compare(_ context.Context, base, head string) (string, bool, error) { + st, ok := f.compares[base+"..."+head] + return st, ok, nil +} + +func (f fakeContainsHistory) PullRequest(_ context.Context, n int) (buildcontains.PullRequest, bool, error) { + pr, ok := f.prs[n] + return pr, ok, nil +} + +const ( + containsMerge = "1a2b3c4d5e6f" + containsOld = "aaaaaaa" + containsNew = "bbbbbbb" + containsGone = "ccccccc" +) + +func containsFixture() (fakeContainsHistory, []buildContainsHive) { + hist := fakeContainsHistory{ + compares: map[string]string{ + containsMerge + "..." + containsNew: "ahead", + containsMerge + "..." + containsOld: "behind", + }, + prs: map[int]buildcontains.PullRequest{ + 10: {Merged: true, MergeCommit: containsMerge}, + 11: {Merged: false}, + }, + } + hives := []buildContainsHive{ + {ID: "h-new", Name: "alpha", GitHash: containsNew, ImageRef: "ghcr.io/hivecommons/hive:stable"}, + {ID: "h-old", ProjectName: "beta", GitHash: containsOld, TrackedChannel: "candidate"}, + {ID: "h-gone", GitHash: containsGone}, + {ID: "h-none"}, + } + return hist, hives +} + +func containsByID(resp BuildContainsResponse) map[string]BuildContainsHive { + out := map[string]BuildContainsHive{} + for _, h := range resp.Hives { + out[h.ID] = h + } + return out +} + +func TestBuildContainsAnswerPR(t *testing.T) { + hist, hives := containsFixture() + resp := buildContainsAnswer(context.Background(), hist, buildcontains.Query{Kind: buildcontains.KindPR, PR: 10}, hives) + got := containsByID(resp) + if got["h-new"].Contains != "yes" { + t.Fatalf("build containing the merge commit must be yes: %+v", got["h-new"]) + } + if got["h-old"].Contains != "no" { + t.Fatalf("a PR outside the build's history must be no: %+v", got["h-old"]) + } + if got["h-gone"].Contains != "unknown" || got["h-gone"].Reason == "" { + t.Fatalf("an unresolvable commit must be unknown with a reason: %+v", got["h-gone"]) + } + if got["h-none"].Contains != "unknown" { + t.Fatalf("a hive reporting no commit must be unknown: %+v", got["h-none"]) + } + if got["h-old"].Channel != "candidate" || got["h-old"].Name != "beta" { + t.Fatalf("row labels wrong: %+v", got["h-old"]) + } + if resp.Commit != containsMerge { + t.Fatalf("response must name the tested commit, got %q", resp.Commit) + } +} + +func TestBuildContainsAnswerUnmergedPRIsNoForEveryHive(t *testing.T) { + hist, hives := containsFixture() + resp := buildContainsAnswer(context.Background(), hist, buildcontains.Query{Kind: buildcontains.KindPR, PR: 11}, hives) + for _, h := range resp.Hives { + if h.Commit == "" { + if h.Contains != "unknown" { + t.Fatalf("no running commit stays unknown: %+v", h) + } + continue + } + if h.Contains != "no" { + t.Fatalf("unmerged PR must not be contained: %+v", h) + } + } + if resp.Reason == "" { + t.Fatal("a fleet-wide answer must carry its reason") + } +} + +func TestBuildContainsAnswerUnknownPR(t *testing.T) { + hist, hives := containsFixture() + resp := buildContainsAnswer(context.Background(), hist, buildcontains.Query{Kind: buildcontains.KindPR, PR: 999}, hives) + for _, h := range resp.Hives { + if h.Contains == "yes" || h.Contains == "no" { + t.Fatalf("an unreadable PR must never yield yes or no: %+v", h) + } + } +} + +func TestBuildContainsResponseShape(t *testing.T) { + hist, hives := containsFixture() + resp := buildContainsAnswer(context.Background(), hist, buildcontains.Query{Kind: buildcontains.KindCommit, Commit: containsMerge}, hives) + raw, err := json.Marshal(resp) + if err != nil { + t.Fatal(err) + } + var back map[string]any + if err := json.Unmarshal(raw, &back); err != nil { + t.Fatal(err) + } + for _, k := range []string{"query", "commit", "hives"} { + if _, ok := back[k]; !ok { + t.Fatalf("response missing %q: %s", k, raw) + } + } +} diff --git a/src/pkg/hub/saas.go b/src/pkg/hub/saas.go index 82ce77528b..c75236d0cf 100644 --- a/src/pkg/hub/saas.go +++ b/src/pkg/hub/saas.go @@ -547,6 +547,7 @@ func (s *HubServer) registerSaaSRoutes() { s.mux.HandleFunc("POST /api/saas/admin/slack/broadcast", s.requireAdmin(s.handleSlackBroadcast)) s.mux.HandleFunc("POST /api/saas/admin/journey-snooze", s.requireAdmin(s.handleJourneySnooze)) s.mux.HandleFunc("GET /api/saas/admin/journey-status", s.requireAdmin(s.handleJourneyStatus)) + s.registerBuildContainsRoutes() } func pendingAgentRestartResetsForHeartbeat(hiveID string) []string { From a38422cab40e81d77fd7f4be7f774af61d251f80 Mon Sep 17 00:00:00 2001 From: Andy Anderson Date: Wed, 18 Nov 2026 00:37:57 -0500 Subject: [PATCH 2/2] =?UTF-8?q?=E2=9C=85=20Allow=20pkg/dashboard=20to=20im?= =?UTF-8?q?port=20the=20leaf=20pkg/buildcontains=20resolver?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Part of #18915. Signed-off-by: Andy Anderson --- src/internal/testutil/dashboard_import_allowlist.txt | 2 ++ 1 file changed, 2 insertions(+) diff --git a/src/internal/testutil/dashboard_import_allowlist.txt b/src/internal/testutil/dashboard_import_allowlist.txt index 61005b57e4..d13ba436cf 100644 --- a/src/internal/testutil/dashboard_import_allowlist.txt +++ b/src/internal/testutil/dashboard_import_allowlist.txt @@ -10,6 +10,7 @@ # workflowmodel: /api/workflows handlers compile lifecycle models (Compile, Profile diagnostics) and the tracker emits per-repo workflow columns; the store and bindings already route through Dependencies (hivecommons/hive#17620 P2). # egressmark: deployment_upgrade.go dials the in-cluster Kubernetes API for the hive's own rollout; the dial must carry the forced-egress SO_MARK or nodes without xt_owner redirect it into the MITM proxy (hivecommons/hive#17817). # agentsmd: the /api/status repo entries carry each repo's last AGENTS.md injection status (size, effective cap, dropped sections) from agentsmd.StatusFor, the read side of the registry the scheduler records into (hivecommons/hive#18495). +# buildcontains: GET /api/version/contains answers "does the running build contain PR #N" through the same dependency-free ancestry resolver the hub uses (yes/no/unknown, never a guess); a leaf package importing only the standard library (hivecommons/hive#18915). github.com/hivecommons/hive/crux github.com/hivecommons/hive/crux/agentsmd github.com/hivecommons/hive/crux/claude @@ -26,6 +27,7 @@ github.com/hivecommons/hive/pkg/advisory github.com/hivecommons/hive/pkg/agentaudit github.com/hivecommons/hive/pkg/beads github.com/hivecommons/hive/pkg/blocker +github.com/hivecommons/hive/pkg/buildcontains github.com/hivecommons/hive/pkg/celtrigger github.com/hivecommons/hive/pkg/claims github.com/hivecommons/hive/pkg/classify