feat: relax network deadlines from install, env, and doctor

Co-authored-by: Cursor 

Author: coreybutler

src/cmd/main.go

@@ -6,6 +6,7 @@ import (
 	"common/fs"
 	"common/license"
 	"common/notify"
+	"common/resolver"
 	"common/settings"
 	"common/system"
 	"common/verifycache"
@@ -32,6 +33,7 @@ var (
 )
 
 func main() {
+	resolver.OnDeadline = log.LogNetworkDeadline
 	if len(os.Args) < 2 {
 		os.Args = append(os.Args, "--help")
 	}

src/commands/env.go

@@ -15,6 +15,7 @@ import (
 	"nvm/bootstrap"
 	"nvm/commands/cache"
 	"nvm/constant"
+	"nvm/log"
 	"nvm/status"
 	"os"
 	"os/user"
@@ -33,22 +34,18 @@ var (
 	helpURL string = "https://docs.nvm-windows.com"
 )
 
-const remoteReachabilityTimeout = 1500 * time.Millisecond
-
-// Use common/http so Author mirrors (mirror.author.io) get Bearer access token.
-var reachabilityClient = nvmhttp.NewClient(remoteReachabilityTimeout)
-
 type Env struct {
 	constant.FlagJSON
+	RelaxDeadlines constant.RelaxDeadlines `optional:"" placeholder:"MS" help:"Relax network deadlines for this command. Omit a value to triple the configured budgets, or pass milliseconds."`
 }
 
 type installData struct {
-	Version    string            `json:"version"`
+	Version           string            `json:"version"`
 	BuildTime         string            `json:"build_time"`
 	BuildArchitecture string            `json:"build_architecture"`
 	InstallDir        string            `json:"path"`
-	Upgrade    string            `json:"upgrade"`
-	Variables  map[string]string `json:"variables"`
+	Upgrade           string            `json:"upgrade"`
+	Variables         map[string]string `json:"variables"`
 }
 
 type vmOps struct {
@@ -69,6 +66,10 @@ type vmOps struct {
 	VersionsCacheRoot     string          `json:"cache_root"`
 	CachedVersionsCount   int             `json:"cache_count"`
 	CachedVersionsSizeMB  int64           `json:"cache_size_mb"`
+	TimeoutCatalog        string          `json:"timeout_catalog_ms"`
+	TimeoutCatalogMirror  string          `json:"timeout_catalog_mirror_ms"`
+	TimeoutReachability   string          `json:"timeout_reachability_ms"`
+	TimeoutDownload       string          `json:"timeout_download_ms"`
 }
 
 // nodeRuntimeFlags reports shim-enforced Node.js CLI security flags.
@@ -135,6 +136,7 @@ var (
 )
 
 func (e *Env) Run(ctx *kong.Context, vars kong.Vars) error {
+	settings.UseRelax(e.RelaxDeadlines.Setting())
 	var spinner *status.Spinner
 	if !e.JSON {
 		spinner = status.NewSpinner("Analyzing environment")
@@ -249,6 +251,7 @@ func (e *Env) Run(ctx *kong.Context, vars kong.Vars) error {
 		}
 	}
 
+	budgets := settings.ActiveNetworkBudgets()
 	node_ping_results := runReachabilityChecks(cfg.NodeMirror, isNodeMirrorReachable)
 	npm_ping_results := runReachabilityChecks(cfg.NpmMirror, isNpmMirrorReachable)
 
@@ -289,7 +292,7 @@ func (e *Env) Run(ctx *kong.Context, vars kong.Vars) error {
 			BuildTime:         vars["buildTime"],
 			BuildArchitecture: buildArchitecture,
 			InstallDir:        path(programRoot),
-			Upgrade:    map[bool]string{true: "blocked", false: "allowed"}[cfg.DisableUpgrade],
+			Upgrade:           map[bool]string{true: "blocked", false: "allowed"}[cfg.DisableUpgrade],
 			// Variables: map[string]string{
 			// 	"NVM_HOME":      getUserEnvVar("NVM_HOME"),
 			// 	"NVM_NODE_PATH": getUserEnvVar("NVM_NODE_PATH"),
@@ -312,6 +315,10 @@ func (e *Env) Run(ctx *kong.Context, vars kong.Vars) error {
 			NpmGlobalModuleTotal:  moduleTotalCount,
 			NpmGlobalModuleUnique: moduleUniqueCount,
 			NpmModuleSizeMB:       moduleSizeBytes / (1024 * 1024),
+			TimeoutCatalog:        budgets.Catalog.Note(),
+			TimeoutCatalogMirror:  budgets.CatalogMirror.Note(),
+			TimeoutReachability:   budgets.Reachability.Note(),
+			TimeoutDownload:       budgets.Download.Note(),
 		},
 		Node: nodeFlags,
 		PackageManagers: packageManagersCfg{
@@ -453,10 +460,7 @@ func (e *Env) Run(ctx *kong.Context, vars kong.Vars) error {
 	// Node Mirrors
 	fmt.Fprintf(t, "%s%s Download Sources\t\n", indent(1), branch)
 	for i, mirror := range out.VersionManagement.NodeMirror {
-		reachable := ""
-		if !out.VersionManagement.NodeMirrorPingResult[mirror] {
-			reachable = " (unreachable)"
-		}
+		reachable := unreachableNote(out.VersionManagement.NodeMirrorPingResult[mirror], out.VersionManagement.TimeoutReachability)
 
 		if i == 0 {
 			fmt.Fprintf(t, "%s%s%s %s Node.js\t: %s%s\n", indent(1), line, indent(1), branch, mirror, reachable)
@@ -467,10 +471,7 @@ func (e *Env) Run(ctx *kong.Context, vars kong.Vars) error {
 
 	// npm Mirrors
 	for i, mirror := range out.VersionManagement.NpmMirror {
-		reachable := ""
-		if !out.VersionManagement.NpmMirrorPingResult[mirror] {
-			reachable = " (unreachable)"
-		}
+		reachable := unreachableNote(out.VersionManagement.NpmMirrorPingResult[mirror], out.VersionManagement.TimeoutReachability)
 
 		if i == 0 {
 			fmt.Fprintf(t, "%s%s%s %s npm\t: %s%s\n", indent(1), line, indent(1), end, mirror, reachable)
@@ -479,6 +480,12 @@ func (e *Env) Run(ctx *kong.Context, vars kong.Vars) error {
 		}
 	}
 
+	fmt.Fprintf(t, "%s%s Network deadlines\t\n", indent(1), branch)
+	fmt.Fprintf(t, "%s%s%s %s TimeoutCatalogMs\t: %s\n", indent(1), line, indent(1), branch, out.VersionManagement.TimeoutCatalog)
+	fmt.Fprintf(t, "%s%s%s %s TimeoutCatalogMirrorMs\t: %s\n", indent(1), line, indent(1), branch, out.VersionManagement.TimeoutCatalogMirror)
+	fmt.Fprintf(t, "%s%s%s %s TimeoutReachabilityMs\t: %s\n", indent(1), line, indent(1), branch, out.VersionManagement.TimeoutReachability)
+	fmt.Fprintf(t, "%s%s%s %s TimeoutDownloadMs\t: %s\n", indent(1), line, indent(1), end, out.VersionManagement.TimeoutDownload)
+
 	fmt.Fprintf(t, "%s%s Installed Versions\t\n", indent(1), branch)
 
 	// Active Version
@@ -960,9 +967,33 @@ func runReachabilityChecks(mirrors []string, checker func(string) bool) map[stri
 	return results
 }
 
+func unreachableNote(reachable bool, budget string) string {
+	if reachable {
+		return ""
+	}
+	if strings.Contains(budget, settings.SourceCommandFlag) {
+		return " (unreachable; phase=reachability " + budget + ")"
+	}
+	return " (unreachable)"
+}
+
+func reachabilityClient() *nvmhttp.Client {
+	return nvmhttp.NewClient(settings.ActiveNetworkBudgets().Reachability.Duration())
+}
+
+func noteReachabilityDeadline(url string, err error) {
+	if !nvmhttp.IsDeadline(err) {
+		return
+	}
+	b := settings.ActiveNetworkBudgets().Reachability
+	log.LogNetworkDeadline("reachability", url, b.Milliseconds, b.Source)
+}
+
 func isNodeMirrorReachable(url string) bool {
-	res, err := reachabilityClient.Head(url + "/index.tab")
+	target := strings.TrimRight(url, "/") + "/index.tab"
+	res, err := reachabilityClient().Head(target)
 	if err != nil {
+		noteReachabilityDeadline(target, err)
 		return false
 	}
 	defer res.Body.Close()
@@ -975,8 +1006,10 @@ func isNodeMirrorReachable(url string) bool {
 }
 
 func isNpmMirrorReachable(url string) bool {
-	res, err := reachabilityClient.Get(url + "/-/ping")
+	target := strings.TrimRight(url, "/") + "/-/ping"
+	res, err := reachabilityClient().Get(target)
 	if err != nil {
+		noteReachabilityDeadline(target, err)
 		return false
 	}
 	defer res.Body.Close()

src/commands/install/install.go

@@ -10,18 +10,20 @@ import (
 )
 
 type Install struct {
-	CopyFrom string `flag:"copy-from" help:"Copy the global modules from an existing Node.js installation to the new installation. This does affect the original version and does not verify module compatibility with the new version." placeholder:"VERSION"`
-	From     string `flag:"from" help:"Install global modules from the list of modules installed in an another Node.js version." placeholder:"VERSION"`
-	Notify   bool   `flag:"notify" hidden:"true" help:"Notify user when a version has been automatically installed."`
-	Cache    bool   `flag:"cache" help:"Save the download (offline cache)."`
-	NoCache  bool   `flag:"no-cache" help:"Install without caching. This is the default unless configured to always cache downloads."`
-	Force    bool   `flag:"force" help:"Force (re)install if the version already exists."`
-	Debug    bool   `flag:"debug" hidden:"true" help:"Write timing logs to the install directory for debugging."`
-	Insecure bool   `flag:"insecure" help:"Accept invalid TLS/SSL certs from download sources."`
+	CopyFrom       string                  `flag:"copy-from" help:"Copy the global modules from an existing Node.js installation to the new installation. This does affect the original version and does not verify module compatibility with the new version." placeholder:"VERSION"`
+	From           string                  `flag:"from" help:"Install global modules from the list of modules installed in an another Node.js version." placeholder:"VERSION"`
+	Notify         bool                    `flag:"notify" hidden:"true" help:"Notify user when a version has been automatically installed."`
+	Cache          bool                    `flag:"cache" help:"Save the download (offline cache)."`
+	NoCache        bool                    `flag:"no-cache" help:"Install without caching. This is the default unless configured to always cache downloads."`
+	Force          bool                    `flag:"force" help:"Force (re)install if the version already exists."`
+	Debug          bool                    `flag:"debug" hidden:"true" help:"Write timing logs to the install directory for debugging."`
+	Insecure       bool                    `flag:"insecure" help:"Accept invalid TLS/SSL certs from download sources."`
+	RelaxDeadlines constant.RelaxDeadlines `optional:"" placeholder:"MS" help:"Relax network deadlines for this command. Omit a value to triple the configured budgets, or pass milliseconds."`
 	constant.ArgVersion
 }
 
 func (s *Install) Run(ctx *kong.Context) error {
+	settings.UseRelax(s.RelaxDeadlines.Setting())
 	cfg := settings.Global()
 
 	var cacheRoot string

src/commands/sync.go

@@ -49,11 +49,15 @@ func (s *Upgrade) Run() error {
 }
 
 type Doctor struct {
-	Checks  []string `arg:"" optional:"" help:"Specific checks to run. If not specified, all checks will be run."`
-	Autofix bool     `flag:"autofix" help:"Automatically fix issues when possible."`
-	List    bool     `flag:"list" help:"List all available checks without running them."`
-	Update  bool     `flag:"update" help:"Force sync utility asset update before running checks."`
-	Force   bool     `flag:"force" help:"When upgrading, do not warn about processes that will be closed."`
+	Checks           []string                `arg:"" optional:"" help:"Specific checks to run. If not specified, all checks will be run."`
+	Autofix          bool                    `flag:"autofix" help:"Automatically fix issues when possible."`
+	List             bool                    `flag:"list" help:"List all available checks without running them."`
+	Update           bool                    `flag:"update" help:"Force sync utility asset update before running checks."`
+	Force            bool                    `flag:"force" help:"When upgrading, do not warn about processes that will be closed."`
+	RelaxDeadlines   constant.RelaxDeadlines `optional:"" placeholder:"MS" help:"Relax network deadlines for this command. Omit a value to triple the configured budgets, or pass milliseconds."`
+	MeasureDeadlines bool                    `flag:"measure-deadlines" help:"Time each download source and print min, average, and max."`
+	MeasureCount     int                     `flag:"measure-count" default:"3" help:"How many times to repeat each deadline measurement."`
+	AutoDeadlines    bool                    `flag:"auto-deadlines" help:"Measure deadlines and save HKCU values from the results."`
 	constant.FlagJSON
 }
 
@@ -76,6 +80,22 @@ func (c *Doctor) Run() error {
 	if c.Force {
 		args = append(args, "--force")
 	}
+	if c.RelaxDeadlines.Active() {
+		if c.RelaxDeadlines.Milliseconds() > 0 {
+			args = append(args, fmt.Sprintf("--relax-deadlines=%d", c.RelaxDeadlines.Milliseconds()))
+		} else {
+			args = append(args, "--relax-deadlines")
+		}
+	}
+	if c.MeasureDeadlines {
+		args = append(args, "--measure-deadlines")
+	}
+	if c.AutoDeadlines {
+		args = append(args, "--auto-deadlines")
+	}
+	if (c.MeasureDeadlines || c.AutoDeadlines) && c.MeasureCount > 0 {
+		args = append(args, "--measure-count", fmt.Sprintf("%d", c.MeasureCount))
+	}
 	if c.JSON {
 		args = append(args, "--json")
 	}

src/constant/relax.go

@@ -0,0 +1,49 @@
+package constant
+
+import (
+	"common/settings"
+	"fmt"
+	"strconv"
+	"strings"
+
+	"github.com/alecthomas/kong"
+)
+
+// RelaxDeadlines is --relax-deadlines.
+// A bare flag triples configured budgets. A positive integer is milliseconds.
+// Fields stay unexported so kong treats the value as one flag.
+type RelaxDeadlines struct {
+	active       bool
+	milliseconds int
+}
+
+func (r RelaxDeadlines) Active() bool { return r.active }
+
+func (r RelaxDeadlines) Milliseconds() int { return r.milliseconds }
+
+func (r RelaxDeadlines) Setting() settings.RelaxDeadlines {
+	return settings.RelaxDeadlines{Active: r.active, Milliseconds: r.milliseconds}
+}
+
+func (r *RelaxDeadlines) Decode(ctx *kong.DecodeContext) error {
+	r.active = true
+	raw, ok := tokenString(ctx.Scan.Peek().Value)
+	if !ok || raw == "" || strings.HasPrefix(raw, "-") {
+		return nil
+	}
+	n, err := strconv.Atoi(raw)
+	if err != nil {
+		return nil
+	}
+	if n <= 0 {
+		return fmt.Errorf("--relax-deadlines must be a positive number of milliseconds")
+	}
+	ctx.Scan.Pop()
+	r.milliseconds = n
+	return nil
+}
+
+func tokenString(v any) (string, bool) {
+	s, ok := v.(string)
+	return s, ok
+}

src/constant/relax_test.go

@@ -0,0 +1,47 @@
+package constant
+
+import (
+	"testing"
+
+	"github.com/alecthomas/kong"
+)
+
+func TestRelaxFlagParsing(t *testing.T) {
+	parse := func(args ...string) (RelaxDeadlines, []string) {
+		t.Helper()
+		var cli struct {
+			RelaxDeadlines RelaxDeadlines `optional:"" placeholder:"MS" help:"Relax network deadlines for this command."`
+			Version        []string       `arg:"" optional:""`
+		}
+		parser := kong.Must(&cli)
+		_, err := parser.Parse(args)
+		if err != nil {
+			t.Fatalf("parse %v: %v", args, err)
+		}
+		return cli.RelaxDeadlines, cli.Version
+	}
+
+	bare, version := parse("--relax-deadlines")
+	if !bare.Active() || bare.Milliseconds() != 0 {
+		t.Fatalf("bare = %+v", bare)
+	}
+	if len(version) != 0 {
+		t.Fatalf("bare consumed args: %v", version)
+	}
+
+	custom, version := parse("--relax-deadlines", "9000", "20")
+	if !custom.Active() || custom.Milliseconds() != 9000 {
+		t.Fatalf("custom = %+v", custom)
+	}
+	if len(version) != 1 || version[0] != "20" {
+		t.Fatalf("version = %v", version)
+	}
+
+	absent, version := parse("22")
+	if absent.Active() {
+		t.Fatal("flag should be absent")
+	}
+	if len(version) != 1 || version[0] != "22" {
+		t.Fatalf("version = %v", version)
+	}
+}

src/installer/download_error.go

@@ -2,9 +2,12 @@ package installer
 
 import (
 	nvmhttp "common/http"
+	"common/settings"
 	"fmt"
 	"net/http"
 	"strings"
+
+	"nvm/log"
 )
 
 func describeDownloadResultFailure(label, url string, result nvmhttp.DownloadResult) error {
@@ -38,6 +41,22 @@ func formatNodeMirrorDownloadFailure(version, archiveName string, mirrors []stri
 			mirrorNote,
 		)
 	}
+	if nvmhttp.IsDeadline(lastErr) {
+		b := settings.ActiveNetworkBudgets().Download
+		log.LogNetworkDeadline("download", "", b.Milliseconds, b.Source)
+		note := "TimeoutDownloadMs " + b.Note()
+		if settings.ActiveNetworkBudgets().Verbose {
+			note = "phase=download " + note
+		}
+		return fmt.Errorf(
+			"failed to download Node.js v%s (%s) from %s (%s): %w",
+			version,
+			archiveName,
+			mirrorNote,
+			note,
+			lastErr,
+		)
+	}
 	return fmt.Errorf(
 		"failed to download Node.js v%s (%s) from %s: %w",
 		version,