GitLabgitlab-org
cli
main
1package binarymgr
3import (
4 "context"
5 "crypto/sha256"
6 "encoding/hex"
7 "errors"
8 "fmt"
9 "io"
10 "os"
11 "runtime"
12 "slices"
13 "time"
15 "github.com/hashicorp/go-version"
17 gitlab "gitlab.com/gitlab-org/api/client-go/v3"
19 "gitlab.com/gitlab-org/cli/internal/iostreams"
20)
22const defaultUpdateCheckDelay = 24 * time.Hour
24// registryLookupTimeout bounds the package-registry metadata calls (list packages, list files).
25// Without it, an unreachable registry costs six 30 s dial timeouts per call.
26const registryLookupTimeout = 15 * time.Second
28// BinaryInfo describes an installed (or located) managed binary.
29type BinaryInfo struct {
30 Path string
31 Version string
32 Checksum string
33}
35// packageAsset is the resolved upstream asset to download.
36type packageAsset struct {
37 version string
38 filename string
39 checksum string
40}
42// Manager handles the lifecycle (install, update, validate) of a single
43// managed binary described by Spec.
44type Manager struct {
45 io *iostreams.IOStreams
46 spec Spec
47 client *gitlab.Client
48}
50// NewManager constructs a Manager for spec. Network requests use an
51// unauthenticated client because package downloads are public.
52func NewManager(io *iostreams.IOStreams, spec Spec) *Manager {
53 client, _ := gitlab.NewAuthSourceClient(gitlab.Unauthenticated{})
54 return &Manager{io: io, spec: spec, client: client}
55}
57// EnsureResult is what EnsureInstalled returns: the resolved binary plus
58// metadata the runner needs to react to.
59type EnsureResult struct {
60 Info *BinaryInfo
62 // Downloaded is true when this call actually downloaded and installed
63 // the binary (vs. returning an existing installation or a custom path).
64 Downloaded bool
66 // AutoDownloadPreference is set to "true" when the user opted into
67 // automatic future downloads during the prompt. Empty otherwise.
68 AutoDownloadPreference string
69}
71// EnsureInstalled returns a usable binary path, prompting the user to
72// download if necessary. installedPath/installedVersion come from saved
73// config. If installedPath points outside the managed install directory it
74// is treated as a user-provided custom binary and returned without download.
75func (m *Manager) EnsureInstalled(ctx context.Context, installedVersion, installedPath, autoDownload string) (*EnsureResult, error) {
76 platform, err := detectPlatform(m.spec)
77 if err != nil {
78 return nil, err
79 }
81 managedPath := binaryPath(m.spec, platform)
83 if installedPath != "" && installedPath != managedPath {
84 if err := validateBinaryPath(installedPath, m.spec); err != nil {
85 return nil, err
86 }
87 return &EnsureResult{
88 Info: &BinaryInfo{Path: installedPath, Version: installedVersion},
89 }, nil
90 }
92 if installedVersion != "" && isBinaryValid(managedPath) {
93 return &EnsureResult{
94 Info: &BinaryInfo{Path: managedPath, Version: installedVersion},
95 }, nil
96 }
98 shouldDownload, preference, err := m.promptDownload(ctx, autoDownload)
99 if err != nil {
100 return nil, err
101 }
102 if !shouldDownload {
103 return nil, errors.New("download cancelled")
104 }
106 info, err := m.downloadAndInstall(ctx, platform)
107 if err != nil {
108 return nil, err
109 }
110 return &EnsureResult{Info: info, Downloaded: true, AutoDownloadPreference: preference}, nil
111}
113// UpdateCheck is the result of CheckForUpdate. NewCheckTime is non-zero
114// when a registry lookup was attempted, whether or not it succeeded;
115// callers should persist it.
116type UpdateCheck struct {
117 HasUpdate bool
118 LatestVersion string
119 NewMajorVersion string // set when latest exceeds Spec.MaxCompatibleMajor
120 NewCheckTime time.Time
121}
123// CheckForUpdate reports whether a newer compatible version exists. If the
124// latest upstream version exceeds Spec.MaxCompatibleMajor, HasUpdate is
125// false and NewMajorVersion is set so callers can surface the gating to
126// the user.
127func (m *Manager) CheckForUpdate(ctx context.Context, currentVersion string, lastCheckTime time.Time, forceCheck bool) (UpdateCheck, error) {
128 if !forceCheck && !lastCheckTime.IsZero() && time.Since(lastCheckTime) < defaultUpdateCheckDelay {
129 return UpdateCheck{}, nil
130 }
132 lookupCtx, cancel := context.WithTimeout(ctx, registryLookupTimeout)
133 defer cancel()
134 latestPkg, err := m.fetchLatestPackage(lookupCtx)
135 if err != nil {
136 return UpdateCheck{NewCheckTime: time.Now()}, err
137 }
139 now := time.Now()
141 latestV, err := version.NewVersion(latestPkg.Version)
142 if err != nil {
143 return UpdateCheck{NewCheckTime: now}, fmt.Errorf("invalid latest version: %w", err)
144 }
146 if m.spec.MaxCompatibleMajor > 0 {
147 segs := latestV.Segments()
148 if len(segs) == 0 {
149 return UpdateCheck{NewCheckTime: now}, fmt.Errorf("invalid latest version: %q", latestPkg.Version)
150 }
151 if segs[0] > m.spec.MaxCompatibleMajor {
152 return UpdateCheck{NewMajorVersion: latestPkg.Version, NewCheckTime: now}, nil
153 }
154 }
156 current, err := version.NewVersion(currentVersion)
157 if err != nil {
158 return UpdateCheck{NewCheckTime: now}, fmt.Errorf("invalid current version: %w", err)
159 }
161 result := UpdateCheck{LatestVersion: latestPkg.Version, NewCheckTime: now}
162 if latestV.GreaterThan(current) {
163 result.HasUpdate = true
164 }
165 return result, nil
166}
168// Update downloads and installs the latest version unconditionally.
169func (m *Manager) Update(ctx context.Context) (*BinaryInfo, error) {
170 platform, err := detectPlatform(m.spec)
171 if err != nil {
172 return nil, err
173 }
174 return m.downloadAndInstall(ctx, platform)
175}
177// validateBinaryPath verifies that a custom binary path is usable.
178//
179// Error messages avoid leading with the env-var name because fang
180// Title-cases the first token of an error ("Glab_orbit_cli_..."), and
181// they name both configuration sources (env var + config key) since either
182// can set the value.
183func validateBinaryPath(path string, spec Spec) error {
184 source := fmt.Sprintf("the %s env var or the %s config key", spec.envVar("BINARY_PATH"), spec.configKey("binary_path"))
185 info, err := os.Stat(path)
186 if err != nil {
187 if os.IsNotExist(err) {
188 return fmt.Errorf("custom %s binary path %q (set via %s) was not found. Check that the path is correct", spec.DisplayName, path, source)
189 }
190 return fmt.Errorf("custom %s binary path %q (set via %s) could not be accessed: %w", spec.DisplayName, path, source, err)
191 }
192 if info.IsDir() {
193 return fmt.Errorf("custom %s binary path %q (set via %s) is a directory, not an executable file", spec.DisplayName, path, source)
194 }
195 if runtime.GOOS != "windows" && info.Mode()&0o111 == 0 {
196 return fmt.Errorf("custom %s binary path %q (set via %s) is not executable. Run: chmod +x %s", spec.DisplayName, path, source, path)
197 }
198 return nil
199}
201func isBinaryValid(path string) bool {
202 info, err := os.Stat(path)
203 if err != nil {
204 return false
205 }
206 if !info.Mode().IsRegular() {
207 return false
208 }
209 if runtime.GOOS != "windows" && info.Mode().Perm()&0o111 == 0 {
210 return false
211 }
212 return true
213}
215// promptDownload asks the user to confirm a download. If they accept, it
216// follows up with an "always?" prompt. Returns (shouldDownload, preference,
217// err) where preference is "true" iff the user wants future downloads to
218// proceed automatically.
219func (m *Manager) promptDownload(ctx context.Context, autoDownload string) (bool, string, error) {
220 if autoDownload == "true" {
221 return true, "", nil
222 }
224 if !m.io.CanPrompt() {
225 return false, "", consentRequiredError(m.spec, "auto_download", fmt.Sprintf("download the %s binary", m.spec.DisplayName))
226 }
228 confirm := true
229 if err := m.io.Confirm(ctx, &confirm, fmt.Sprintf("Download %s binary?", m.spec.DisplayName)); err != nil {
230 return false, "", err
231 }
232 if !confirm {
233 return false, "", errors.New("download cancelled")
234 }
236 var always bool
237 if err := m.io.Confirm(ctx, &always, "Always download updates automatically?"); err != nil {
238 return true, "", nil //nolint:nilerr // proceed with download even if the secondary "always" prompt fails (e.g. non-interactive)
239 }
240 if always {
241 return true, "true", nil
242 }
243 return true, "", nil
244}
246func (m *Manager) downloadAndInstall(ctx context.Context, platform Platform) (*BinaryInfo, error) {
247 asset, err := m.fetchPackageAsset(ctx, platform)
248 if err != nil {
249 return nil, err
250 }
252 tempFile, err := os.CreateTemp("", "binarymgr-*.tmp")
253 if err != nil {
254 return nil, fmt.Errorf("failed to create temp file: %w", err)
255 }
256 defer os.Remove(tempFile.Name())
257 defer tempFile.Close()
259 m.io.LogErrorf("Downloading %s version %s...\n", asset.filename, asset.version)
260 if err := m.downloadFile(ctx, asset, tempFile); err != nil {
261 return nil, err
262 }
264 if err := m.verifyChecksum(tempFile.Name(), asset.checksum); err != nil {
265 return nil, err
266 }
268 binarySrc := tempFile.Name()
269 if m.spec.Extract != nil {
270 extractDir, err := os.MkdirTemp("", "binarymgr-extract-*")
271 if err != nil {
272 return nil, fmt.Errorf("failed to create extract directory: %w", err)
273 }
274 defer os.RemoveAll(extractDir)
276 extracted, err := m.spec.Extract(tempFile.Name(), extractDir)
277 if err != nil {
278 return nil, fmt.Errorf("failed to extract binary: %w", err)
279 }
280 binarySrc = extracted
281 }
283 if err := m.installBinary(binarySrc, platform); err != nil {
284 return nil, err
285 }
287 finalPath := binaryPath(m.spec, platform)
288 color := m.io.Color()
289 m.io.LogErrorf("%s Installed to: %s\n", color.GreenCheck(), finalPath)
291 return &BinaryInfo{
292 Path: finalPath,
293 Version: asset.version,
294 Checksum: asset.checksum,
295 }, nil
296}
298// fetchLatestPackage returns the package with the highest semantic version
299// in the registry. The GitLab packages API sorts `order_by=version`
300// lexicographically (8.99.0 > 8.100.0), so we collect all packages and pick
301// the max via hashicorp/go-version client-side. Non-parseable versions are
302// skipped — the generic packages API permits any version string.
303func (m *Manager) fetchLatestPackage(ctx context.Context) (*gitlab.Package, error) {
304 opts := &gitlab.ListProjectPackagesOptions{
305 PackageType: new("generic"),
306 PackageName: &m.spec.PackageName,
307 OrderBy: new("created_at"),
308 Sort: new("desc"),
309 ListOptions: gitlab.ListOptions{PerPage: 100},
310 }
311 packages, err := gitlab.ScanAndCollect(func(p gitlab.PaginationOptionFunc) ([]*gitlab.Package, *gitlab.Response, error) {
312 return m.client.Packages.ListProjectPackages(m.spec.ProjectID, opts, p, gitlab.WithContext(ctx))
313 })
314 if err != nil {
315 return nil, registryError("packages", err)
316 }
317 if len(packages) == 0 {
318 return nil, errors.New("no packages found")
319 }
321 var latestPkg *gitlab.Package
322 var latestVer *version.Version
323 for _, pkg := range packages {
324 v, err := version.NewVersion(pkg.Version)
325 if err != nil {
326 continue
327 }
328 if latestVer == nil || v.GreaterThan(latestVer) {
329 latestPkg, latestVer = pkg, v
330 }
331 }
332 if latestPkg == nil {
333 return nil, errors.New("no packages with parseable versions found")
334 }
335 return latestPkg, nil
336}
338func registryError(what string, err error) error {
339 if errors.Is(err, context.DeadlineExceeded) {
340 return fmt.Errorf("package registry did not respond within %s: %w", registryLookupTimeout, err)
341 }
342 return fmt.Errorf("failed to fetch %s: %w", what, err)
343}
345func (m *Manager) fetchPackageAsset(ctx context.Context, platform Platform) (*packageAsset, error) {
346 ctx, cancel := context.WithTimeout(ctx, registryLookupTimeout)
347 defer cancel()
348 pkg, err := m.fetchLatestPackage(ctx)
349 if err != nil {
350 return nil, err
351 }
353 if m.spec.MaxCompatibleMajor > 0 {
354 latestV, err := version.NewVersion(pkg.Version)
355 if err != nil {
356 return nil, fmt.Errorf("invalid package version %q: %w", pkg.Version, err)
357 }
358 segs := latestV.Segments()
359 if len(segs) == 0 || segs[0] > m.spec.MaxCompatibleMajor {
360 return nil, fmt.Errorf("no compatible %s version found (major version %d supported; %s requires a newer glab)", m.spec.DisplayName, m.spec.MaxCompatibleMajor, pkg.Version)
361 }
362 }
364 files, _, err := m.client.Packages.ListPackageFiles(m.spec.ProjectID, pkg.ID, &gitlab.ListPackageFilesOptions{}, gitlab.WithContext(ctx))
365 if err != nil {
366 return nil, registryError("package files", err)
367 }
369 wanted := assetName(m.spec, platform)
370 idx := slices.IndexFunc(files, func(file *gitlab.PackageFile) bool {
371 return file.FileName == wanted
372 })
373 if idx == -1 {
374 return nil, fmt.Errorf("binary not found for platform: %s", wanted)
375 }
377 file := files[idx]
378 return &packageAsset{
379 version: pkg.Version,
380 filename: file.FileName,
381 checksum: file.FileSHA256,
382 }, nil
383}
385func (m *Manager) downloadFile(ctx context.Context, asset *packageAsset, dest *os.File) error {
386 data, _, err := m.client.GenericPackages.DownloadPackageFile(
387 m.spec.ProjectID,
388 m.spec.PackageName,
389 asset.version,
390 asset.filename,
391 gitlab.WithContext(ctx),
392 )
393 if err != nil {
394 return fmt.Errorf("failed to download: %w", err)
395 }
396 if _, err := dest.Write(data); err != nil {
397 return fmt.Errorf("failed to write file: %w", err)
398 }
399 return nil
400}
402func (m *Manager) verifyChecksum(filePath, expectedChecksum string) error {
403 if expectedChecksum == "" {
404 if m.spec.RequireChecksum {
405 return fmt.Errorf("refusing to run %s: no checksum available from the registry to verify the download", m.spec.DisplayName)
406 }
407 color := m.io.Color()
408 m.io.LogErrorf("%s No checksum available, skipping verification\n", color.DotWarnIcon())
409 return nil
410 }
412 file, err := os.Open(filePath)
413 if err != nil {
414 return fmt.Errorf("failed to open file for checksum: %w", err)
415 }
416 defer file.Close()
418 hash := sha256.New()
419 if _, err := io.Copy(hash, file); err != nil {
420 return fmt.Errorf("failed to compute checksum: %w", err)
421 }
423 actual := hex.EncodeToString(hash.Sum(nil))
424 if actual != expectedChecksum {
425 return fmt.Errorf("checksum verification failed: expected %s, got %s", expectedChecksum, actual)
426 }
428 color := m.io.Color()
429 m.io.LogErrorf("%s Checksum verified\n", color.GreenCheck())
430 return nil
431}
433// installBinary atomically places the binary at its final managed path.
434func (m *Manager) installBinary(srcPath string, platform Platform) error {
435 dir := installDir()
436 if err := os.MkdirAll(dir, 0o755); err != nil {
437 return fmt.Errorf("failed to create install directory: %w", err)
438 }
440 dest := binaryPath(m.spec, platform)
442 tmp, err := os.CreateTemp(dir, ".binarymgr-install-*.tmp")
443 if err != nil {
444 return fmt.Errorf("failed to create temp file in install directory: %w", err)
445 }
446 tmpName := tmp.Name()
447 defer os.Remove(tmpName)
449 src, err := os.Open(srcPath)
450 if err != nil {
451 tmp.Close()
452 return fmt.Errorf("failed to open source binary: %w", err)
453 }
454 defer src.Close()
456 if _, err := io.Copy(tmp, src); err != nil {
457 tmp.Close()
458 return fmt.Errorf("failed to copy binary: %w", err)
459 }
460 if err := tmp.Chmod(0o755); err != nil {
461 tmp.Close()
462 return fmt.Errorf("failed to set permissions: %w", err)
463 }
464 if err := tmp.Close(); err != nil {
465 return fmt.Errorf("failed to close temp file: %w", err)
466 }
467 if err := os.Rename(tmpName, dest); err != nil {
468 return fmt.Errorf("failed to install binary: %w", err)
469 }
470 return nil
471}
Diagnostics6 git calls · 262 ms
CallStatusSizeTime0262 ms
discover200185 B2 ms
git.upload-pack discover http.response.status_code=200 git.upstream.cf_ray=- git.upstream.phase=fetch git.upstream.dur_ms=2 git.response.bytes=185 git.server.agent=git/2.56.g1891de4-Linux git.server.object_format=sha1 git.server.caps=agent ls-refs fetch server-option object-format git.server.fetch=shallow wait-for-done filter git.protocol.version=2 git.pkt.frames=9 git.pkt.data=7 git.pkt.flush=2 git.pkt.delim=0 git.pkt.bytes=185 git.pkt.payload.max=35
ls-refs20058 KiB · hit2 ms
git.upload-pack ls-refs http.response.status_code=200 git.upstream.cf_ray=- git.upstream.phase=ls-refs git.upstream.dur_ms=2 git.response.bytes=59849 git.response.cache=HIT git.response.duration_ms=2 git.protocol.version=2 git.pkt.frames=731 git.pkt.data=730 git.pkt.flush=1 git.pkt.delim=0 git.pkt.bytes=59849 git.pkt.payload.max=143 git.ls_refs.count=730 git.ls_refs.head=refs/heads/main
fetchtree:0 · deepen 1020032 KiB · hit2 ms
git.upload-pack fetch http.response.status_code=200 git.upstream.cf_ray=- git.upstream.phase=fetch git.upstream.dur_ms=2 git.response.bytes=32926 git.response.cache=HIT git.response.duration_ms=2 git.fetch.filter=tree:0 git.fetch.wants=0dd7574dce9e385c5c30540e6c15657adc6bdce9 git.fetch.haves.count=0 git.fetch.deepen=10 git.fetch.thin_pack=false git.fetch.ofs_delta=true git.protocol.version=2 git.pkt.frames=22 git.pkt.data=20 git.pkt.flush=1 git.pkt.delim=1 git.pkt.bytes=32926 git.pkt.payload.max=32046 git.sideband.band1.bytes=32046 git.sideband.band2.bytes=0 git.sideband.band3.bytes=0 git.pack.objects=80 git.pack.bytes=32046 git.pack.ofs_delta=36 git.pack.ref_delta=0 git.pack.chain.max=2 git.pack.trailer=cb0bad5d7ffc514895d8b21c4dd470327f90bc91 git.pack.full=44Open pack map
fetchcombine:blob:none+tree:2 · deepen 12004.2 KiB · hit2 ms
git.upload-pack fetch http.response.status_code=200 git.upstream.cf_ray=- git.upstream.phase=fetch git.upstream.dur_ms=2 git.response.bytes=4273 git.response.cache=HIT git.response.duration_ms=2 git.fetch.filter=combine:blob:none+tree:2 git.fetch.wants=0dd7574dce9e385c5c30540e6c15657adc6bdce9 git.fetch.haves.count=0 git.fetch.deepen=1 git.fetch.thin_pack=false git.fetch.ofs_delta=true git.protocol.version=2 git.pkt.frames=7 git.pkt.data=5 git.pkt.flush=1 git.pkt.delim=1 git.pkt.bytes=4273 git.pkt.payload.max=4173 git.sideband.band1.bytes=4173 git.sideband.band2.bytes=0 git.sideband.band3.bytes=0 git.pack.objects=11 git.pack.bytes=4173 git.fetch.wide.objects=11 git.fetch.wide.extra_bytes=3930 git.fetch.wide.blobs=0
fetchtree:0200528 B · hit2 ms
git.upload-pack fetch http.response.status_code=200 git.upstream.cf_ray=- git.upstream.phase=fetch git.upstream.dur_ms=256 git.response.bytes=528 git.response.cache=HIT git.response.duration_ms=2 git.fetch.filter=tree:0 git.fetch.wants=6f25b436c20690dd9e61e310cecb2c93d3671017 git.fetch.haves.count=0 git.fetch.deepen=0 git.fetch.thin_pack=false git.fetch.ofs_delta=true git.protocol.version=2 git.pkt.frames=4 git.pkt.data=3 git.pkt.flush=1 git.pkt.delim=0 git.pkt.bytes=528 git.pkt.payload.max=501 git.sideband.band1.bytes=501 git.sideband.band2.bytes=0 git.sideband.band3.bytes=0 git.pack.objects=1 git.pack.bytes=501 git.pack.trailer=3f78362ab585c40c9cff18b66b4df6f87bfba2d8Open pack map
fetch2004.5 KiB256 ms
git.upload-pack fetch http.response.status_code=200 git.response.bytes=4620 git.response.cache=MISS git.response.duration_ms=256 git.fetch.wants=98b928a3eb2df25457a2643050be61cd4b253280 git.fetch.haves.count=0 git.fetch.deepen=0 git.fetch.thin_pack=false git.fetch.ofs_delta=true git.protocol.version=2 git.pkt.frames=4 git.pkt.data=3 git.pkt.flush=1 git.pkt.delim=0 git.pkt.bytes=4620 git.pkt.payload.max=4593 git.sideband.band1.bytes=4593 git.sideband.band2.bytes=0 git.sideband.band3.bytes=0
Each row is one HTTP round trip ply made to the git server for this page, on one timeline. discover asks what the server speaks, ls-refs lists branch tips, fetch brings objects by id. A hit was served by Workers Cache. Tap a row for its wire details.
- Remote
- https://gitlab.com/gitlab-org/cli
- Ref
- refs/heads/main
- Commit
- 0dd7574dce9e385c5c30540e6c15657adc6bdce9
- cf-ray
- a5e1301bf9ada9fe
- Request
- baa165f3…
- Protocol
- v2 · sha1
- Agent
- git/2.56.g1891de4-Linux
- Filter
- advertised
- Fetch
- shallow wait-for-done filter
- Capabilities
- agent ls-refs fetch server-option object-format