Documentation
¶
Overview ¶
Package ghrelease resolves and downloads a pre-built package asset attached to a GitHub repository's Releases — a second, parallel install source alongside internal/registry's configured-registry lookups (ADR-0067). It never clones or builds a repository: it only calls GitHub's public REST API to find one release asset and downloads it. Install-time CLI tooling only; not part of any versioned public boundary (api/, sdk/, plugin protocol).
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Download ¶
Download streams resolved.Asset's bytes into a new file under destDir (created if missing) and returns its path — same shape as internal/registry.Fetch. The asset's BrowserDownloadURL, as returned by the GitHub API, is fetched directly with a plain GET (redirects followed by the default http.Client behavior); this is also what makes the download side trivially fakeable in tests without any extra "download base URL" option — a test's fake /releases/... handler just points BrowserDownloadURL at that same httptest.Server.
Types ¶
type Options ¶
type Options struct {
// APIBaseURL overrides https://api.github.com. Tests only.
APIBaseURL string
// Token, sent as "Authorization: Bearer <Token>" on the GitHub API
// call (never on the asset download), raises GitHub's unauthenticated
// rate limit (60 req/hr/IP). Optional; never required for a public
// repository. Not a private-repo mechanism — see ADR-0067.
Token string
// HTTPClient overrides the client used for both the API call and the
// asset download. Tests only; defaults to &http.Client{Timeout: 30 *
// time.Second}.
HTTPClient *http.Client
}
Options configures GitHub API access and the HTTP transport. The zero value talks to the real, unauthenticated github.com API with a 30s-timeout client — everything here exists to make GitHub fakeable in tests and to let a caller supply a token.
type Ref ¶
Ref is a parsed reference to a GitHub-hosted release asset: github.com/<owner>/<repo>[@<tag>]. Tag == "" means "resolve to the repository's latest release"; a non-empty Tag is used verbatim as a GitHub release tag name (no "v" prefix guessing).
type Resolved ¶
type Resolved struct {
Ref Ref
Tag string // always concrete, even when Ref.Tag was ""
Asset Asset
}
Resolved pins a Ref to one concrete release tag and exactly one release asset whose name ends in the assetSuffix given to Resolve.
func Resolve ¶
Resolve calls GitHub's Releases API for ref (releases/latest when ref.Tag == "", releases/tags/<ref.Tag> otherwise) and returns the single release asset whose name ends in assetSuffix (e.g. plugins.PackageExtension, passed in by the caller rather than imported, so this package stays usable for other package kinds later without depending on any of them).
Fails with a clear, actionable error if: the repository/release/tag does not exist (GitHub 404 — the API cannot distinguish "no such repo" from "no such release", so the message covers both plainly); the API returns any other non-2xx status (status + response body snippet included, with a dedicated message when the response indicates rate limiting); the release has zero assets ending in assetSuffix; or it has more than one (ambiguous — the caller is told to publish a single one, this pass does not support disambiguation).
Source Files