From 44fac8934a3b92cc4bfb87dead31f90aa75683ee Mon Sep 17 00:00:00 2001
From: binarycat <binarycat@envs.net>
Date: Sun, 25 Aug 2024 12:09:58 -0400
Subject: [PATCH] explain the options curl passes to bootstrap

also fixes a discrepency where the rust side doesn't use -L

must not be merged before #129134

docs are only on the rust side, since duplicated prose
has a tendancy to get out-of-sync, and also because there
are talks of removing the python script all together eventually.
---
 src/bootstrap/bootstrap.py         |  4 ++++
 src/bootstrap/src/core/download.rs | 19 +++++++++++++++++--
 2 files changed, 21 insertions(+), 2 deletions(-)

diff --git a/src/bootstrap/bootstrap.py b/src/bootstrap/bootstrap.py
index c19134b4594f..1de010dc08a4 100644
--- a/src/bootstrap/bootstrap.py
+++ b/src/bootstrap/bootstrap.py
@@ -115,6 +115,10 @@ def _download(path, url, probably_big, verbose, exception):
         extra_flags = []
         if curl_version() > (7, 70):
             extra_flags = [ "--retry-all-errors" ]
+        # options should be kept in sync with
+        # src/bootstrap/src/core/download.rs
+        # for consistency.
+        # they are also more compreprensivly explained in that file.
         run(["curl", option] + extra_flags + [
             "-L", # Follow redirect.
             "-y", "30", "-Y", "10",    # timeout if speed is < 10 bytes/sec for > 30 seconds
diff --git a/src/bootstrap/src/core/download.rs b/src/bootstrap/src/core/download.rs
index b5c55854eff5..038ca320e6b6 100644
--- a/src/bootstrap/src/core/download.rs
+++ b/src/bootstrap/src/core/download.rs
@@ -227,20 +227,35 @@ impl Config {
     fn download_http_with_retries(&self, tempfile: &Path, url: &str, help_on_error: &str) {
         println!("downloading {url}");
         // Try curl. If that fails and we are on windows, fallback to PowerShell.
+        // options should be kept in sync with
+        // src/bootstrap/src/core/download.rs
+        // for consistency
         let mut curl = command("curl");
         curl.args([
+            // follow redirect
+            "-L",
+            // timeout if speed is < 10 bytes/sec for > 30 seconds
             "-y",
             "30",
             "-Y",
-            "10", // timeout if speed is < 10 bytes/sec for > 30 seconds
+            "10",
+            // timeout if cannot connect within 30 seconds
             "--connect-timeout",
-            "30", // timeout if cannot connect within 30 seconds
+            "30",
+            // output file
             "-o",
             tempfile.to_str().unwrap(),
+            // if there is an error, don't restart the download,
+            // instead continue where it left off.
             "--continue-at",
             "-",
+            // retry up to 3 times.  note that this means a maximum of 4
+            // attempts will be made, since the first attempt isn't a *re*try.
             "--retry",
             "3",
+            // -S: show errors, even if -s is specified
+            // -R: set timestamp of downloaded file to that of the server
+            // -f: fail on non-ok http status
             "-SRf",
         ]);
         // Don't print progress in CI; the \r wrapping looks bad and downloads don't take long enough for progress to be useful.