GitLabgitlab-org

cli

main
ply8 git calls208 ms100 KiB6 cachedprotocol v2
303 lines11 KiBRaw
1package download
3import (
4 "context"
5 "crypto/sha256"
6 "encoding/hex"
7 "errors"
8 "fmt"
9 "io"
10 "os"
11 "path/filepath"
12 "strconv"
14 "github.com/MakeNowJust/heredoc/v2"
15 "github.com/spf13/cobra"
17 gitlab "gitlab.com/gitlab-org/api/client-go/v3"
19 "gitlab.com/gitlab-org/cli/internal/cmdutils"
20 "gitlab.com/gitlab-org/cli/internal/commands/securefile/helpers"
21 "gitlab.com/gitlab-org/cli/internal/iostreams"
22 "gitlab.com/gitlab-org/cli/internal/mcpannotations"
23 "gitlab.com/gitlab-org/cli/internal/utils"
26func NewCmdDownload(f cmdutils.Factory) *cobra.Command {
27 securefileDownloadCmd := &cobra.Command{
28 Use: "download [<id> | --id <id> | --name <name>] [flags]",
29 Short: `Download one or more secure files from a project.`,
30 Long: heredoc.Docf(`
31 To download a single file, identify it by its numeric ID (as a positional
32 argument or with %[1]s--id%[1]s) or by its name with %[1]s--name%[1]s. To download every
33 secure file in the project, use %[1]s--all%[1]s.
35 Use %[1]s--path%[1]s to save a single download to a specific filename, or
36 %[1]s--output-dir%[1]s to choose the destination directory when downloading
37 multiple files.
39 By default, downloaded files are verified against their checksum.
40 Use %[1]s--no-verify%[1]s to skip verification, or %[1]s--force-download%[1]s to keep
41 files even when verification fails. Both options can allow corrupted
42 or tampered files; use with caution.
44 By default, files are downloaded from the current project. Use
45 %[1]s--repo%[1]s to target another project.
46 `, "`"),
47 Example: heredoc.Doc(`
48 # Download a file by ID (positional or flag)
49 glab securefile download 1
50 glab securefile download --id 1
52 # Download a file by ID to a specific path
53 glab securefile download 1 --path "securefiles/file.txt"
55 # Download a file to an absolute path
56 glab securefile download 1 --path /tmp/secure/file.txt
58 # Download a file by name to the current directory
59 glab securefile download --name my-secure-file.pem
61 # Download a file by name to a chosen path
62 glab securefile download --name my-secure-file.pem --path securefiles/some-other-name.pem
64 # Download without verifying the checksum
65 glab securefile download 1 --no-verify
67 # Download all secure files in the project
68 glab securefile download --all
70 # Download all secure files to a specific directory
71 glab securefile download --all --output-dir secure_files/
72 `),
73 Args: cobra.MaximumNArgs(1),
74 Annotations: map[string]string{
75 mcpannotations.Exclude: "true",
76 },
77 RunE: func(cmd *cobra.Command, args []string) error {
78 client, err := f.GitLabClient()
79 if err != nil {
80 return err
81 }
83 repo, err := f.BaseRepo()
84 if err != nil {
85 return err
86 }
88 noVerify, err := cmd.Flags().GetBool("no-verify")
89 if err != nil {
90 return fmt.Errorf("unable to get no-verify flag: %w", err)
91 }
93 forceDownload, err := cmd.Flags().GetBool("force-download")
94 if err != nil {
95 return fmt.Errorf("unable to get force-download flag: %w", err)
96 }
98 all, err := cmd.Flags().GetBool("all")
99 if err != nil {
100 return fmt.Errorf("unable to get all flag: %w", err)
101 }
103 if all {
104 if len(args) > 0 && args[0] != "" {
105 return errors.New("all flag is not compatible with arguments")
106 }
108 outputDir, err := cmd.Flags().GetString("output-dir")
109 if err != nil {
110 return fmt.Errorf("unable to get output-dir flag: %w", err)
111 }
113 return downloadAllSecureFiles(cmd.Context(), f.IO(), client, repo.FullName(), outputDir, !noVerify, forceDownload)
114 } else {
115 outputDirSet := cmd.Flags().Changed("output-dir")
116 if outputDirSet {
117 return errors.New("output-dir flag is only compatible with all flag")
118 }
120 path, err := cmd.Flags().GetString("path")
121 if err != nil {
122 return fmt.Errorf("unable to get path flag: %w", err)
123 }
125 // Download securefile by Name
126 name, err := cmd.Flags().GetString("name")
127 if err != nil {
128 return fmt.Errorf("unable to get name flag: %w", err)
129 }
131 if name != "" {
132 if len(args) > 0 && args[0] != "" {
133 return errors.New("name flag is not compatible with arguments")
134 }
136 // If path wasn't explicitly set by user, use name as default
137 if !cmd.Flags().Changed("path") {
138 path = fmt.Sprintf("./%s", name)
139 }
141 return downloadSecureFileByName(cmd.Context(), f.IO(), client, name, repo.FullName(), path, !noVerify, forceDownload)
142 }
144 var fileID int64
145 // Check if --id is passed, else drop to positional argument
146 if cmd.Flags().Changed("id") {
147 fileID, err = cmd.Flags().GetInt64("id")
148 if err != nil {
149 return fmt.Errorf("unable to get id flag: %w", err)
150 }
151 } else {
152 // Guard against no args
153 if len(args) == 0 {
154 return errors.New("must provide fileID argument, --id or --name flag")
155 }
157 fileID, err = strconv.ParseInt(args[0], 10, 64)
158 if err != nil {
159 return fmt.Errorf("secure file ID must be an integer: %s", args[0])
160 }
161 }
163 return downloadSecureFile(cmd.Context(), f.IO(), client, fileID, repo.FullName(), path, !noVerify, forceDownload)
164 }
165 },
166 }
167 securefileDownloadCmd.Flags().StringP("path", "p", "./downloaded.tmp", "Path to download the secure file to, including filename and extension.")
168 securefileDownloadCmd.Flags().String("output-dir", ".", "Output directory for files downloaded with --all.")
169 securefileDownloadCmd.Flags().Int64("id", 0, "ID of the secure file to download.")
170 securefileDownloadCmd.Flags().String("name", "", "Name of the secure file to download. Saves the file with this name, or to the path specified by --path.")
171 securefileDownloadCmd.Flags().Bool("no-verify", false, "Do not verify the checksum of the downloaded file(s). Warning: when enabled, this setting allows the download of files that are corrupt or tampered with.")
172 securefileDownloadCmd.Flags().Bool("force-download", false, "Force download file(s) even if checksum verification fails. Warning: when enabled, this setting allows the download of files that are corrupt or tampered with.")
173 securefileDownloadCmd.Flags().Bool("all", false, "Download all of a project's secure files. Files are downloaded with their original name and file extension.")
175 securefileDownloadCmd.MarkFlagsMutuallyExclusive("no-verify", "force-download")
176 securefileDownloadCmd.MarkFlagsMutuallyExclusive("path", "output-dir")
177 securefileDownloadCmd.MarkFlagsMutuallyExclusive("path", "all")
178 securefileDownloadCmd.MarkFlagsMutuallyExclusive("id", "name", "all")
180 return securefileDownloadCmd
183func downloadSecureFileByName(ctx context.Context, ios *iostreams.IOStreams, client *gitlab.Client, fileName string, repoName, path string, verifyChecksum, forceDownload bool) (err error) {
184 root, name, err := utils.EnsureDestinationRoot(filepath.Clean(path))
185 if err != nil {
186 return err
187 }
188 defer func() { err = errors.Join(err, root.Close()) }()
190 secureFile, err := helpers.GetSecureFileByName(client, fileName, repoName)
191 if err != nil {
192 return err
193 }
195 if err := saveFile(ctx, ios, client, repoName, secureFile.ID, root, name, verifyChecksum, forceDownload); err != nil {
196 return err
197 }
199 ios.LogInfof("Downloaded secure file '%s' (Name: %s)\n", name, fileName)
200 return nil
203func downloadSecureFile(ctx context.Context, ios *iostreams.IOStreams, client *gitlab.Client, fileID int64, repoName, path string, verifyChecksum, forceDownload bool) (err error) {
204 root, name, err := utils.EnsureDestinationRoot(filepath.Clean(path))
205 if err != nil {
206 return err
207 }
208 defer func() { err = errors.Join(err, root.Close()) }()
210 if err := saveFile(ctx, ios, client, repoName, fileID, root, name, verifyChecksum, forceDownload); err != nil {
211 return err
212 }
214 ios.LogInfof("Downloaded secure file '%s' (ID: %d)\n", name, fileID)
215 return nil
218func downloadAllSecureFiles(ctx context.Context, ios *iostreams.IOStreams, client *gitlab.Client, repoName, outputDir string, verifyChecksum, forceDownload bool) error {
219 for file, err := range gitlab.Scan2(func(p gitlab.PaginationOptionFunc) ([]*gitlab.SecureFile, *gitlab.Response, error) {
220 return client.SecureFiles.ListProjectSecureFiles(repoName, nil, p, gitlab.WithContext(ctx))
221 }) {
222 if err != nil {
223 return fmt.Errorf("error fetching secure files: %w", err)
224 }
226 // The name comes from the API. An absolute outputDir has no
227 // working-directory root left to stop it escaping, so reject anything
228 // that is not a plain relative name. See https://go.dev/blog/osroot.
229 if !filepath.IsLocal(file.Name) {
230 return fmt.Errorf("error downloading secure file '%s' (ID: %d): name would write outside the output directory", file.Name, file.ID)
231 }
233 filePath := filepath.Join(outputDir, file.Name)
235 if err := downloadSecureFile(ctx, ios, client, file.ID, repoName, filePath, verifyChecksum, forceDownload); err != nil {
236 return fmt.Errorf("error downloading secure file '%s' (ID: %d): %w", file.Name, file.ID, err)
237 }
238 }
240 return nil
243func saveFile(ctx context.Context, ios *iostreams.IOStreams, apiClient *gitlab.Client, repoName string, fileID int64, root *os.Root, name string, verifyChecksum, forceDownload bool) (err error) {
244 contents, _, err := apiClient.SecureFiles.DownloadSecureFile(repoName, fileID, gitlab.WithContext(ctx))
245 if err != nil {
246 return fmt.Errorf("error downloading secure file: %w", err)
247 }
249 tempFile, err := utils.CreateTemp(root, strconv.FormatInt(fileID, 10))
250 if err != nil {
251 return fmt.Errorf("unable to create temporary file for downloaded secure file: %w", err)
252 }
253 // root.OpenFile reports the name joined onto the root, which root's own
254 // methods reject as escaping when the root is absolute. The temporary file
255 // is always a direct child of root, so its base name addresses it.
256 tempName := filepath.Base(tempFile.Name())
258 defer func() {
259 if closeErr := tempFile.Close(); closeErr != nil {
260 closeErr = fmt.Errorf("error closing temporary file: %w", closeErr)
261 err = errors.Join(err, closeErr)
262 }
263 if _, statErr := root.Stat(tempName); statErr == nil { // Cleanup the temp file if it hasn't been renamed
264 if removeErr := root.Remove(tempName); removeErr != nil {
265 removeErr = fmt.Errorf("error removing temporary file: %w", removeErr)
266 err = errors.Join(err, removeErr)
267 }
268 }
269 }()
271 if verifyChecksum {
272 file, _, err := apiClient.SecureFiles.ShowSecureFileDetails(repoName, fileID, gitlab.WithContext(ctx))
273 if err != nil {
274 return fmt.Errorf("error getting secure file details: %w", err)
275 }
277 hasher := sha256.New()
278 teeReader := io.TeeReader(contents, hasher)
280 if _, err := io.Copy(tempFile, teeReader); err != nil {
281 return fmt.Errorf("unable to write to temporary file for checksum verification: %w", err)
282 }
284 if checksum := hex.EncodeToString(hasher.Sum(nil)); checksum != file.Checksum {
285 if forceDownload {
286 ios.LogInfof("Checksum verification failed for %s: expected %s, got %s\n", file.Name, file.Checksum, checksum)
287 ios.LogInfo("Force-download selected, continuing to download file.")
288 } else {
289 return fmt.Errorf("checksum verification failed for %s: expected %s, got %s", file.Name, file.Checksum, checksum)
290 }
291 }
292 } else {
293 if _, err := io.Copy(tempFile, contents); err != nil {
294 return fmt.Errorf("unable to write to downloaded file: %w", err)
295 }
296 }
298 if err := root.Rename(tempName, name); err != nil {
299 return fmt.Errorf("unable to persist downloaded file contents: %w", err)
300 }
302 return err
Diagnostics8 git calls · 208 ms
CallStatusSizeTime0208 ms
discover200185 B3 ms
git.upload-pack discover
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=ls-refs
git.upstream.dur_ms=3
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 · hit3 ms
git.upload-pack ls-refs
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=ls-refs
git.upstream.dur_ms=3
git.response.bytes=59849
git.response.cache=HIT
git.response.duration_ms=3
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
fetchcombine:blob:none+tree:2 · deepen 12004.2 KiB · hit3 ms
git.upload-pack fetch
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=fetch
git.upstream.dur_ms=3
git.response.bytes=4273
git.response.cache=HIT
git.response.duration_ms=3
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:0 · deepen 1020032 KiB · hit3 ms
git.upload-pack fetch
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=fetch
git.upstream.dur_ms=3
git.response.bytes=32926
git.response.cache=HIT
git.response.duration_ms=3
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=44
Open pack map
fetchtree:02001.8 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=1857
git.response.cache=HIT
git.response.duration_ms=2
git.fetch.filter=tree:0
git.fetch.wants=dce174ff8c632a19d17eea99c8a9b7c37fb2b592
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=1857
git.pkt.payload.max=1830
git.sideband.band1.bytes=1830
git.sideband.band2.bytes=0
git.sideband.band3.bytes=0
git.pack.objects=1
git.pack.bytes=1830
git.pack.trailer=fb03183b7909876778f740d196d7516811003517
Open pack map
fetchtree:0200353 B · hit3 ms
git.upload-pack fetch
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=fetch
git.upstream.dur_ms=3
git.response.bytes=353
git.response.cache=HIT
git.response.duration_ms=3
git.fetch.filter=tree:0
git.fetch.wants=d9f8b91b7f75f6920fea2e149ed3fba5f61766da
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=353
git.pkt.payload.max=326
git.sideband.band1.bytes=326
git.sideband.band2.bytes=0
git.sideband.band3.bytes=0
git.pack.objects=1
git.pack.bytes=326
git.pack.trailer=353875a8d3dc1310585685b9eadd95754bcf8d98
Open pack map
fetchtree:0200141 B · hit3 ms
git.upload-pack fetch
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=fetch
git.upstream.dur_ms=3
git.response.bytes=141
git.response.cache=HIT
git.response.duration_ms=3
git.fetch.filter=tree:0
git.fetch.wants=e0642c2a3d3bc785eabed06d920f5c4643b09ab4
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=141
git.pkt.payload.max=114
git.sideband.band1.bytes=114
git.sideband.band2.bytes=0
git.sideband.band3.bytes=0
git.pack.objects=1
git.pack.bytes=114
git.pack.trailer=cce222a9c5a43e5630585282913fb178ee6774f4
Open pack map
fetch2003.2 KiB194 ms
git.upload-pack fetch
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=fetch
git.upstream.dur_ms=194
git.response.bytes=3301
git.response.cache=MISS
git.response.duration_ms=194
git.fetch.wants=e15ae8f2ee1dc301a166f755b600f0f0eddbe4df
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=3301
git.pkt.payload.max=3274
git.sideband.band1.bytes=3274
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
a5e31cc0d92e8682
Request
ff79cdfe…
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