feat: add configurable HTTP client timeouts via config file

<!-- markdownlint-disable MD041 -->

Introduce the `http.config.ocm.software/v1alpha1` config type for
controlling HTTP client timeouts (dial, TLS handshake, response header,
idle connection, keep-alive, and overall timeout). Timeouts are configured
exclusively through the OCM config file using Go duration strings. When
not set, `http.DefaultTransport` values are preserved unchanged.

- Add `httpcfgattr` package with Duration type (K8s-style marshal/unmarshal)
- Add `api/utils/httpclient` transport factory (clones DefaultTransport,
  selectively overrides from config)
- Wire HTTP settings into docker daemon and OCI registry clients
- Add integration tests using toxiproxy for timeout verification
- Update docs with new config type documentation

Fixes: #1731

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

Author: piotrjanik

api/datacontext/attrs/httpcfgattr/attr.go

@@ -0,0 +1,84 @@
+package httpcfgattr
+
+import (
+	"fmt"
+	"time"
+
+	"ocm.software/ocm/api/datacontext"
+	"ocm.software/ocm/api/utils/runtime"
+)
+
+const (
+	ATTR_KEY   = "ocm.software/ocm/api/datacontext/attrs/httptimeout"
+	ATTR_SHORT = "httpcfg"
+)
+
+func init() {
+	datacontext.RegisterAttributeType(ATTR_KEY, AttributeType{}, ATTR_SHORT)
+}
+
+type AttributeType struct{}
+
+func (a AttributeType) Name() string {
+	return ATTR_KEY
+}
+
+func (a AttributeType) Description() string {
+	return `
+*JSON*
+Configures HTTP client timeout settings for OCI registry and remote endpoint access.
+Settings are provided as a JSON document matching the ` + ConfigType + ` config type.
+
+For full control use the config file:
+<pre>
+    type: ` + ConfigType + `
+    global:
+      timeout: 0s
+      tcpDialTimeout: 30s
+      tcpKeepAlive: 30s
+      tlsHandshakeTimeout: 10s
+      idleConnTimeout: 90s
+</pre>
+`
+}
+
+func (a AttributeType) Encode(v interface{}, marshaller runtime.Marshaler) ([]byte, error) {
+	cfg, ok := v.(*Config)
+	if !ok {
+		return nil, fmt.Errorf("*Config required for %s, got %T", ATTR_SHORT, v)
+	}
+	return marshaller.Marshal(cfg)
+}
+
+func (a AttributeType) Decode(data []byte, unmarshaller runtime.Unmarshaler) (interface{}, error) {
+	var cfg Config
+	if err := unmarshaller.Unmarshal(data, &cfg); err != nil {
+		return nil, fmt.Errorf("failed to decode %s: %w", ATTR_SHORT, err)
+	}
+	return &cfg, nil
+}
+
+////////////////////////////////////////////////////////////////////////////////
+
+// Get returns the configured HTTP client config from the context.
+// If not set, DefaultConfig is returned.
+func Get(ctx datacontext.Context) *Config {
+	a := ctx.GetAttributes().GetAttribute(ATTR_KEY)
+	if a == nil {
+		return DefaultConfig()
+	}
+	switch v := a.(type) {
+	case *Config:
+		return v
+	case time.Duration:
+		// backward compat: old callers may have stored a plain time.Duration
+		return NewConfig(v)
+	default:
+		return DefaultConfig()
+	}
+}
+
+// Set stores the HTTP client config attribute in the context.
+func Set(ctx datacontext.Context, cfg *Config) error {
+	return ctx.GetAttributes().SetAttribute(ATTR_KEY, cfg)
+}

api/datacontext/attrs/httpcfgattr/attr_test.go

@@ -0,0 +1,67 @@
+package httpcfgattr_test
+
+import (
+	"time"
+
+	. "github.com/onsi/ginkgo/v2"
+	. "github.com/onsi/gomega"
+
+	"ocm.software/ocm/api/datacontext"
+	"ocm.software/ocm/api/datacontext/attrs/httpcfgattr"
+	"ocm.software/ocm/api/utils/runtime"
+)
+
+var _ = Describe("httpcfg attribute", func() {
+	var ctx datacontext.Context
+	attr := httpcfgattr.AttributeType{}
+	enc := runtime.DefaultJSONEncoding
+
+	BeforeEach(func() {
+		ctx = datacontext.New(nil)
+	})
+
+	Context("get and set", func() {
+		It("defaults to empty config with no timeout", func() {
+			cfg := httpcfgattr.Get(ctx)
+			Expect(cfg).NotTo(BeNil())
+			Expect(cfg.GetGlobal().GetTimeout()).To(Equal(time.Duration(0)))
+		})
+
+		It("sets and retrieves config", func() {
+			Expect(httpcfgattr.Set(ctx, httpcfgattr.NewConfig(5*time.Minute))).To(Succeed())
+			Expect(httpcfgattr.Get(ctx).GetGlobal().GetTimeout()).To(Equal(5 * time.Minute))
+		})
+	})
+
+	Context("encoding", func() {
+		It("encodes *Config to JSON", func() {
+			cfg := httpcfgattr.NewConfig(30 * time.Second)
+			data, err := attr.Encode(cfg, enc)
+			Expect(err).To(Succeed())
+			Expect(string(data)).To(ContainSubstring(`"timeout":"30s"`))
+		})
+
+		It("rejects non-*Config input", func() {
+			_, err := attr.Encode("invalid", enc)
+			Expect(err).To(HaveOccurred())
+			Expect(err.Error()).To(ContainSubstring("*Config required"))
+		})
+	})
+
+	Context("decoding", func() {
+		It("decodes JSON to *Config", func() {
+			raw := []byte(`{"type":"http.config.ocm.software/v1alpha1","global":{"timeout":"10s"}}`)
+			val, err := attr.Decode(raw, enc)
+			Expect(err).To(Succeed())
+			cfg, ok := val.(*httpcfgattr.Config)
+			Expect(ok).To(BeTrue())
+			Expect(cfg.GetGlobal().GetTimeout()).To(Equal(10 * time.Second))
+		})
+
+		It("rejects invalid JSON", func() {
+			_, err := attr.Decode([]byte(`{invalid`), enc)
+			Expect(err).To(HaveOccurred())
+			Expect(err.Error()).To(ContainSubstring("failed to decode"))
+		})
+	})
+})

api/datacontext/attrs/httpcfgattr/config.go

@@ -0,0 +1,212 @@
+package httpcfgattr
+
+import (
+	"encoding/json"
+	"time"
+
+	"github.com/mandelsoft/goutils/errors"
+
+	cfgcpi "ocm.software/ocm/api/config/cpi"
+	"ocm.software/ocm/api/utils/runtime"
+)
+
+const (
+	ConfigType         = "http" + cfgcpi.OCM_CONFIG_TYPE_SUFFIX
+	ConfigTypeV1Alpha1 = ConfigType + runtime.VersionSeparator + "v1alpha1"
+)
+
+func init() {
+	cfgcpi.RegisterConfigType(cfgcpi.NewConfigType[*Config](ConfigType, configUsage))
+	cfgcpi.RegisterConfigType(cfgcpi.NewConfigType[*Config](ConfigTypeV1Alpha1, configUsage))
+}
+
+// Duration is a wrapper around time.Duration which supports correct
+// marshaling to YAML and JSON as a Go duration string (e.g. "30s", "5m").
+type Duration struct {
+	time.Duration
+}
+
+// UnmarshalJSON implements the json.Unmarshaller interface.
+func (d *Duration) UnmarshalJSON(b []byte) error {
+	var str string
+	if err := json.Unmarshal(b, &str); err != nil {
+		return err
+	}
+	pd, err := time.ParseDuration(str)
+	if err != nil {
+		return err
+	}
+	d.Duration = pd
+	return nil
+}
+
+// MarshalJSON implements the json.Marshaler interface.
+func (d Duration) MarshalJSON() ([]byte, error) {
+	return json.Marshal(d.Duration.String())
+}
+
+// NewDuration creates a pointer to a Duration.
+func NewDuration(d time.Duration) *Duration {
+	return &Duration{Duration: d}
+}
+
+// HTTPSettings contains the timeout settings for HTTP clients.
+// 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.
+type HTTPSettings struct {
+	// Timeout is the overall HTTP client timeout.
+	// If not set, http.Client uses no timeout (0).
+	Timeout *Duration `json:"timeout,omitempty"`
+
+	// TCPDialTimeout is the time limit for establishing a TCP connection.
+	TCPDialTimeout *Duration `json:"tcpDialTimeout,omitempty"`
+
+	// TCPKeepAlive is the interval between TCP keep-alive probes.
+	TCPKeepAlive *Duration `json:"tcpKeepAlive,omitempty"`
+
+	// TLSHandshakeTimeout is the maximum time to wait for a TLS handshake.
+	TLSHandshakeTimeout *Duration `json:"tlsHandshakeTimeout,omitempty"`
+
+	// ResponseHeaderTimeout is the time limit to wait for response headers.
+	ResponseHeaderTimeout *Duration `json:"responseHeaderTimeout,omitempty"`
+
+	// IdleConnTimeout is the maximum time an idle connection remains open.
+	IdleConnTimeout *Duration `json:"idleConnTimeout,omitempty"`
+}
+
+// Config describes the configuration for HTTP client settings.
+type Config struct {
+	runtime.ObjectVersionedType `json:",inline"`
+
+	// Global settings apply to all HTTP requests unless overridden per-host.
+	Global *HTTPSettings `json:"global,omitempty"`
+}
+
+// NewConfig creates a new HTTP config with the given overall timeout.
+func NewConfig(timeout time.Duration) *Config {
+	return &Config{
+		ObjectVersionedType: runtime.NewVersionedTypedObject(ConfigType),
+		Global: &HTTPSettings{
+			Timeout: NewDuration(timeout),
+		},
+	}
+}
+
+// DefaultHTTPSettings returns an empty HTTPSettings.
+// When no fields are set, consumers should fall back to http.DefaultTransport defaults.
+func DefaultHTTPSettings() *HTTPSettings {
+	return &HTTPSettings{}
+}
+
+// DefaultConfig returns a Config with empty settings.
+func DefaultConfig() *Config {
+	return &Config{
+		ObjectVersionedType: runtime.NewVersionedTypedObject(ConfigType),
+		Global:              DefaultHTTPSettings(),
+	}
+}
+
+// MergeHTTPSettings merges src into dst. Non-nil fields in src override dst.
+func MergeHTTPSettings(dst, src *HTTPSettings) *HTTPSettings {
+	if dst == nil {
+		dst = &HTTPSettings{}
+	}
+	if src == nil {
+		return dst
+	}
+	if src.Timeout != nil {
+		dst.Timeout = src.Timeout
+	}
+	if src.TCPDialTimeout != nil {
+		dst.TCPDialTimeout = src.TCPDialTimeout
+	}
+	if src.TCPKeepAlive != nil {
+		dst.TCPKeepAlive = src.TCPKeepAlive
+	}
+	if src.TLSHandshakeTimeout != nil {
+		dst.TLSHandshakeTimeout = src.TLSHandshakeTimeout
+	}
+	if src.ResponseHeaderTimeout != nil {
+		dst.ResponseHeaderTimeout = src.ResponseHeaderTimeout
+	}
+	if src.IdleConnTimeout != nil {
+		dst.IdleConnTimeout = src.IdleConnTimeout
+	}
+	return dst
+}
+
+// Merge merges src into dst. Non-nil fields in src.Global override dst.Global.
+func Merge(dst, src *Config) *Config {
+	if dst == nil {
+		dst = &Config{ObjectVersionedType: runtime.NewVersionedTypedObject(ConfigType)}
+	}
+	if src == nil {
+		return dst
+	}
+	dst.Global = MergeHTTPSettings(dst.Global, src.Global)
+	return dst
+}
+
+// GetGlobal returns the Global settings. If nil, returns empty HTTPSettings
+// so that consumers fall back to http.DefaultTransport defaults.
+func (c *Config) GetGlobal() *HTTPSettings {
+	if c == nil || c.Global == nil {
+		return &HTTPSettings{}
+	}
+	return c.Global
+}
+
+// GetTimeout returns the overall HTTP client timeout.
+// Returns 0 (disabled) if not set.
+func (s *HTTPSettings) GetTimeout() time.Duration {
+	if s == nil || s.Timeout == nil {
+		return 0
+	}
+	return s.Timeout.Duration
+}
+
+func (a *Config) GetType() string {
+	return ConfigType
+}
+
+func (a *Config) ApplyTo(ctx cfgcpi.Context, target interface{}) error {
+	t, ok := target.(cfgcpi.Context)
+	if !ok {
+		return cfgcpi.ErrNoContext(ConfigType)
+	}
+	existing := getFromContext(t)
+	merged := Merge(existing, a)
+	return errors.Wrapf(t.GetAttributes().SetAttribute(ATTR_KEY, merged), "applying config failed")
+}
+
+func getFromContext(ctx cfgcpi.Context) *Config {
+	attr := ctx.GetAttributes().GetAttribute(ATTR_KEY)
+	if attr == nil {
+		return nil
+	}
+	if c, ok := attr.(*Config); ok {
+		return c
+	}
+	return nil
+}
+
+const configUsage = `
+The config type <code>` + ConfigType + `</code> can be used to configure
+HTTP client settings:
+
+<pre>
+    type: ` + ConfigType + `
+    global:
+      timeout: 0s
+      tcpDialTimeout: 30s
+      tcpKeepAlive: 30s
+      tlsHandshakeTimeout: 10s
+      responseHeaderTimeout: 0s
+      idleConnTimeout: 90s
+</pre>
+
+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.
+`