chore: refine HTTP client timeout docs and simplify integration tests

Clarify documentation on `timeout` behavior and its independence from transport-level settings. Simplify OCI registry timeout integration tests by consolidating duplicate setups and removing unused toxic configurations.

Signed-off-by: Piotr Janik <piotr.janik@sap.com>

Author: piotrjanik

api/datacontext/attrs/httpcfgattr/config.go

@@ -54,8 +54,14 @@ func NewDuration(d time.Duration) *Duration {
 // All timeout values use Duration (Go duration strings in config).
 // If not set (nil), the http.DefaultTransport value from the Go
 // standard library is used.
+//
+// Note: Timeout controls the overall http.Client deadline and is
+// independent of the transport-level timeouts below. Setting Timeout
+// alone does NOT override TCPDialTimeout, TLSHandshakeTimeout, etc.
 type HTTPSettings struct {
-	// Timeout is the overall HTTP client timeout.
+	// Timeout is the overall http.Client timeout — the maximum duration
+	// for the entire request including connection, TLS, headers, and body.
+	// It does NOT serve as a fallback for transport-level timeouts.
 	// If not set, http.Client uses no timeout (0).
 	Timeout *Duration `json:"timeout,omitempty"`
 
@@ -209,4 +215,8 @@ HTTP client settings:
 All timeout values are Go duration strings (e.g. "30s", "5m", "1h").
 Use "0s" to disable a specific timeout. If not set, the <code>http.DefaultTransport</code>
 values from the Go standard library are used.
+
+Note: <code>timeout</code> controls the overall <code>http.Client</code> request deadline and is
+independent of the transport-level settings. Setting only <code>timeout</code> does not
+affect <code>tcpDialTimeout</code>, <code>tlsHandshakeTimeout</code>, or other transport timeouts.
 `

api/oci/extensions/repositories/ocireg/timeout_integration_test.go

@@ -77,6 +77,28 @@ var _ = Describe("Registry timeout:", Ordered, func() {
 
 		env = NewTestEnv(envhelper.FileSystem(osfs.New()))
 
+		// Create temp dir and CTF for all tests.
+		tempDir, err = os.MkdirTemp("", "ocm-timeout-*")
+		Expect(err).To(Succeed())
+
+		ctfDir = filepath.Join(tempDir, "ctf")
+		constructorFile := filepath.Join(tempDir, "constructor.yaml")
+		constructor := `components:
+  - name: ` + componentName + `
+    version: ` + componentVersion + `
+    provider:
+      name: test
+`
+		Expect(os.WriteFile(constructorFile, []byte(constructor), 0o644)).To(Succeed())
+
+		buf := bytes.NewBuffer(nil)
+		Expect(env.CatchOutput(buf).Execute(
+			"add", "componentversions",
+			"--create",
+			"--file", ctfDir,
+			constructorFile,
+		)).To(Succeed())
+
 		log.Info("Toxic Registry ready", "proxy", proxyHost, "ctf", ctfDir)
 	})
 
@@ -106,30 +128,6 @@ var _ = Describe("Registry timeout:", Ordered, func() {
 		return cfgFile
 	}
 
-	It("creates component version", func() {
-		var err error
-		tempDir, err = os.MkdirTemp("", "ocm-timeout-*")
-		Expect(err).To(Succeed())
-
-		ctfDir = filepath.Join(tempDir, "ctf")
-		constructorFile := filepath.Join(tempDir, "constructor.yaml")
-		constructor := `components:
-  - name: ` + componentName + `
-    version: ` + componentVersion + `
-    provider:
-      name: test
-`
-		Expect(os.WriteFile(constructorFile, []byte(constructor), 0o644)).To(Succeed())
-
-		buf := bytes.NewBuffer(nil)
-		Expect(env.CatchOutput(buf).Execute(
-			"add", "componentversions",
-			"--create",
-			"--file", ctfDir,
-			constructorFile,
-		)).To(Succeed())
-	})
-
 	It("fails when timeout is shorter than proxy latency", func() {
 		addLatency(proxy, 30_000, "upstream")
 		defer removeToxic(proxy, "latency")
@@ -166,12 +164,11 @@ var _ = Describe("Registry timeout:", Ordered, func() {
 	})
 
 	It("fails when response headers can't arrive within configured time", func() {
-		addBandwidth(proxy, 1, "downstream")
-		defer removeToxic(proxy, "bandwidth")
-		addLatency(proxy, 3_000, "downstream")
+		addLatency(proxy, 5_000, "downstream")
 		defer removeToxic(proxy, "latency")
 
-		cfgFile := writeHTTPConfig(`"responseHeaderTimeout":"1s"`)
+		// Cap overall timeout to prevent retries from dragging out.
+		cfgFile := writeHTTPConfig(`"responseHeaderTimeout":"1s","timeout":"8s"`)
 		registryURL := "http://" + proxyHost
 		err := env.Execute(
 			"--config", cfgFile,
@@ -188,8 +185,8 @@ var _ = Describe("Registry timeout:", Ordered, func() {
 	})
 
 	It("succeeds when response header timeout is generous enough", func() {
-		addBandwidth(proxy, 1, "downstream")
-		defer removeToxic(proxy, "bandwidth")
+		addLatency(proxy, 2_000, "downstream")
+		defer removeToxic(proxy, "latency")
 
 		cfgFile := writeHTTPConfig(`"responseHeaderTimeout":"30s"`)
 		registryURL := "http://" + proxyHost
@@ -219,20 +216,6 @@ var _ = Describe("Registry timeout:", Ordered, func() {
 		))
 	})
 
-	It("succeeds with generous tcp-dial-timeout", func() {
-		addLatency(proxy, 500, "upstream")
-		defer removeToxic(proxy, "latency")
-
-		cfgFile := writeHTTPConfig(`"tcpDialTimeout":"10s"`)
-		registryURL := "http://" + proxyHost
-		buf := bytes.NewBuffer(nil)
-		Expect(env.CatchOutput(buf).Execute(
-			"--config", cfgFile,
-			"transfer", "componentversions",
-			ctfDir+"//"+componentName+":"+componentVersion,
-			registryURL,
-		)).To(Succeed())
-	})
 })
 
 func addLatency(proxy *toxiproxy.Proxy, latencyMs int, stream string) {
@@ -242,13 +225,6 @@ func addLatency(proxy *toxiproxy.Proxy, latencyMs int, stream string) {
 	Expect(err).To(Succeed())
 }
 
-func addBandwidth(proxy *toxiproxy.Proxy, rateKBps int, stream string) {
-	_, err := proxy.AddToxic("bandwidth", "bandwidth", stream, 1.0, toxiproxy.Attributes{
-		"rate": rateKBps,
-	})
-	Expect(err).To(Succeed())
-}
-
 func removeToxic(proxy *toxiproxy.Proxy, name string) {
 	Expect(proxy.RemoveToxic(name)).To(Succeed())
 }