feat(api): configurable upload timeout, default 10m (#160)

* feat(api): add ClientConfig with configurable upload timeout (default 10m)

* feat(config): plumb api.uploadTimeout through config

* test(config): add GetAPIConfig coverage (defaults + override)

Author: fank

cmd/ocap_recorder/main.go

@@ -289,14 +289,15 @@ func loadConfig() (err error) {
 }
 
 func initAPIClient() {
-	serverURL := viper.GetString("api.serverUrl")
-	if serverURL == "" {
+	apiCfg := config.GetAPIConfig()
+	if apiCfg.ServerURL == "" {
 		Logger.Info("API server URL not configured, upload disabled")
 		return
 	}
 
-	apiKey := viper.GetString("api.apiKey")
-	apiClient = api.New(serverURL, apiKey)
+	apiClient = api.NewWithConfig(apiCfg.ServerURL, apiCfg.APIKey, api.ClientConfig{
+		UploadTimeout: apiCfg.UploadTimeout,
+	})
 
 	if err := apiClient.Healthcheck(); err != nil {
 		Logger.Info("OCAP Frontend is offline", "error", err)

internal/api/client.go

@@ -18,19 +18,42 @@ import (
 // PathPrefix is the API path prefix appended to the base server URL.
 const PathPrefix = "/api"
 
+// DefaultUploadTimeout is the default upload timeout when the caller
+// does not provide one. It covers the full request (including body
+// streaming), so it must be generous enough for tens-of-MB uploads
+// across a slow reverse proxy.
+const DefaultUploadTimeout = 10 * time.Minute
+
+// ClientConfig configures the API client. All fields are optional —
+// zero values resolve to sensible defaults.
+type ClientConfig struct {
+	// UploadTimeout is the maximum duration for the total upload request
+	// (including streaming the body). Defaults to DefaultUploadTimeout.
+	UploadTimeout time.Duration
+}
+
 // Client handles communication with the OCAP web frontend.
 type Client struct {
 	baseURL    string
 	apiKey     string
 	httpClient *http.Client
 }
 
-// New creates a new API client.
+// New creates a new API client with default configuration.
 func New(baseURL, apiKey string) *Client {
+	return NewWithConfig(baseURL, apiKey, ClientConfig{})
+}
+
+// NewWithConfig creates a new API client with custom configuration.
+func NewWithConfig(baseURL, apiKey string, cfg ClientConfig) *Client {
+	timeout := cfg.UploadTimeout
+	if timeout <= 0 {
+		timeout = DefaultUploadTimeout
+	}
 	return &Client{
 		baseURL:    strings.TrimRight(baseURL, "/") + PathPrefix,
 		apiKey:     apiKey,
-		httpClient: &http.Client{Timeout: 30 * time.Second},
+		httpClient: &http.Client{Timeout: timeout},
 	}
 }
 

internal/api/client_test.go

@@ -6,6 +6,7 @@ import (
 	"net/http/httptest"
 	"os"
 	"testing"
+	"time"
 
 	"github.com/OCAP2/extension/v5/pkg/core"
 	"github.com/stretchr/testify/assert"
@@ -193,6 +194,27 @@ func TestUpload_InvalidURL(t *testing.T) {
 	assert.Contains(t, err.Error(), "failed to create request")
 }
 
+func TestNew_DefaultTimeouts(t *testing.T) {
+	c := New("http://localhost:5000", "secret")
+	require.NotNil(t, c)
+	assert.NotNil(t, c.httpClient)
+	// Backwards-compat default preserved: 10 minutes.
+	assert.Equal(t, 10*time.Minute, c.httpClient.Timeout)
+}
+
+func TestNewWithConfig_CustomTimeout(t *testing.T) {
+	c := NewWithConfig("http://localhost:5000", "secret", ClientConfig{
+		UploadTimeout: 2 * time.Minute,
+	})
+	require.NotNil(t, c)
+	assert.Equal(t, 2*time.Minute, c.httpClient.Timeout)
+}
+
+func TestNewWithConfig_ZeroTimeoutUsesDefault(t *testing.T) {
+	c := NewWithConfig("http://localhost:5000", "secret", ClientConfig{UploadTimeout: 0})
+	assert.Equal(t, 10*time.Minute, c.httpClient.Timeout)
+}
+
 func writeTestFile(path string, content []byte) error {
 	return os.WriteFile(path, content, 0644)
 }

internal/config/config.go

@@ -28,6 +28,10 @@ func Load(configDir string) error {
 
 	viper.SetDefault("api.serverUrl", "http://localhost:5000")
 	viper.SetDefault("api.apiKey", "")
+	// 10 minute default — generous enough for multi-hundred-MB uploads across
+	// a reverse proxy without being so long that a dead backend hangs the save
+	// worker forever.
+	viper.SetDefault("api.uploadTimeout", "10m")
 
 	viper.SetDefault("db.host", "localhost")
 	viper.SetDefault("db.port", "5432")
@@ -113,3 +117,17 @@ func GetOTelConfig() OTelConfig {
 	_ = viper.UnmarshalKey("otel", &cfg)
 	return cfg
 }
+
+// APIConfig holds HTTP client configuration for the OCAP web API.
+type APIConfig struct {
+	ServerURL     string        `json:"serverUrl" mapstructure:"serverUrl"`
+	APIKey        string        `json:"apiKey" mapstructure:"apiKey"`
+	UploadTimeout time.Duration `json:"uploadTimeout" mapstructure:"uploadTimeout"`
+}
+
+// GetAPIConfig returns the HTTP API client configuration.
+func GetAPIConfig() APIConfig {
+	var cfg APIConfig
+	_ = viper.UnmarshalKey("api", &cfg)
+	return cfg
+}

internal/config/config_test.go

@@ -45,6 +45,7 @@ func TestLoad_DefaultValues(t *testing.T) {
 	assert.Equal(t, "./ocaplogs", viper.GetString("logsDir"))
 	assert.Equal(t, "http://localhost:5000", viper.GetString("api.serverUrl"))
 	assert.Equal(t, "", viper.GetString("api.apiKey"))
+	assert.Equal(t, "10m", viper.GetString("api.uploadTimeout"))
 	assert.Equal(t, "localhost", viper.GetString("db.host"))
 	assert.Equal(t, "5432", viper.GetString("db.port"))
 	assert.Equal(t, "postgres", viper.GetString("db.username"))
@@ -127,6 +128,39 @@ func TestGetStorageConfig_Override(t *testing.T) {
 	assert.Equal(t, 10*time.Minute, sc.SQLite.DumpInterval)
 }
 
+func TestGetAPIConfig_Defaults(t *testing.T) {
+	t.Cleanup(viper.Reset)
+
+	dir := t.TempDir()
+	require.NoError(t, os.WriteFile(filepath.Join(dir, "ocap_recorder.cfg.json"), []byte(`{}`), 0644))
+	require.NoError(t, Load(dir))
+
+	cfg := GetAPIConfig()
+	assert.Equal(t, "http://localhost:5000", cfg.ServerURL)
+	assert.Equal(t, "", cfg.APIKey)
+	assert.Equal(t, 10*time.Minute, cfg.UploadTimeout)
+}
+
+func TestGetAPIConfig_Override(t *testing.T) {
+	t.Cleanup(viper.Reset)
+
+	dir := t.TempDir()
+	cfgJSON := `{
+		"api": {
+			"serverUrl": "http://example.com:8080",
+			"apiKey": "mykey",
+			"uploadTimeout": "5m"
+		}
+	}`
+	require.NoError(t, os.WriteFile(filepath.Join(dir, "ocap_recorder.cfg.json"), []byte(cfgJSON), 0644))
+	require.NoError(t, Load(dir))
+
+	cfg := GetAPIConfig()
+	assert.Equal(t, "http://example.com:8080", cfg.ServerURL)
+	assert.Equal(t, "mykey", cfg.APIKey)
+	assert.Equal(t, 5*time.Minute, cfg.UploadTimeout)
+}
+
 func TestGetOTelConfig_Defaults(t *testing.T) {
 	t.Cleanup(viper.Reset)
 

ocap_recorder.cfg.json.example

@@ -4,7 +4,8 @@
   "defaultTag": "TvT",
   "api": {
     "serverUrl": "http://127.0.0.1:5000",
-    "apiKey": "same-secret"
+    "apiKey": "same-secret",
+    "uploadTimeout": "10m"
   },
   "db": {
     "host": "127.0.0.1",