Allow container socket paths to be configured via config file

Author: kantord

pkg/container/docker/sdk/client_unix.go

@@ -44,7 +44,7 @@ func newPlatformClient(socketPath string) (*http.Client, []client.Opt) {
 }
 
 // findPlatformContainerSocket finds a container socket path on Unix systems
-func findPlatformContainerSocket(rt runtime.Type) (string, runtime.Type, error) {
+func findPlatformContainerSocket(rt runtime.Type, overrides socketPathConfig) (string, runtime.Type, error) {
 	// First check for custom socket paths via environment variables
 	if customSocketPath := os.Getenv(PodmanSocketEnv); customSocketPath != "" {
 		//nolint:gosec // G706: socket path from trusted environment variable
@@ -76,6 +76,17 @@ func findPlatformContainerSocket(rt runtime.Type) (string, runtime.Type, error)
 		return customSocketPath, runtime.TypeDocker, nil
 	}
 
+	// Check config file overrides (after env vars, before auto-detection)
+	if overrides.podmanSocket != "" {
+		return resolveConfigSocket(overrides.podmanSocket, runtime.TypePodman, "Podman")
+	}
+	if overrides.dockerSocket != "" {
+		return resolveConfigSocket(overrides.dockerSocket, runtime.TypeDocker, "Docker")
+	}
+	if overrides.colimaSocket != "" {
+		return resolveConfigSocket(overrides.colimaSocket, runtime.TypeDocker, "Colima")
+	}
+
 	if rt == runtime.TypePodman {
 		socketPath, err := findPodmanSocket()
 		if err == nil {
@@ -254,3 +265,12 @@ func findColimaSocket() (string, error) {
 
 	return "", fmt.Errorf("colima socket not found in standard locations")
 }
+
+// resolveConfigSocket validates that a config-supplied socket path exists and returns it.
+func resolveConfigSocket(socketPath string, rt runtime.Type, runtimeName string) (string, runtime.Type, error) {
+	slog.Debug("using socket from config", "runtime", runtimeName, "path", socketPath)
+	if _, err := os.Stat(socketPath); err != nil {
+		return "", rt, fmt.Errorf("invalid %s socket path from config: %w", runtimeName, err)
+	}
+	return socketPath, rt, nil
+}

pkg/container/docker/sdk/client_unix_test.go

@@ -0,0 +1,46 @@
+// SPDX-FileCopyrightText: Copyright 2025 Stacklok, Inc.
+// SPDX-License-Identifier: Apache-2.0
+
+//go:build !windows
+
+package sdk
+
+import (
+	"os"
+	"path/filepath"
+	"testing"
+
+	"github.com/stretchr/testify/require"
+
+	"github.com/stacklok/toolhive/pkg/container/runtime"
+)
+
+func makeTempSocket(t *testing.T) string {
+	t.Helper()
+	p := filepath.Join(t.TempDir(), "test.sock")
+	require.NoError(t, os.WriteFile(p, nil, 0600))
+	return p
+}
+
+func TestFindContainerSocket_ConfigOverride(t *testing.T) {
+	t.Parallel()
+	socketPath := makeTempSocket(t)
+
+	gotPath, gotRuntime, err := findContainerSocket(runtime.TypeDocker, socketPathConfig{dockerSocket: socketPath})
+
+	require.NoError(t, err)
+	require.Equal(t, socketPath, gotPath)
+	require.Equal(t, runtime.TypeDocker, gotRuntime)
+}
+
+func TestFindContainerSocket_EnvVarPrecedence(t *testing.T) {
+	// not parallel — t.Setenv cannot be called in parallel tests
+	envPath := makeTempSocket(t)
+	t.Setenv(DockerSocketEnv, envPath)
+
+	gotPath, gotRuntime, err := findContainerSocket(runtime.TypeDocker, socketPathConfig{dockerSocket: makeTempSocket(t)})
+
+	require.NoError(t, err)
+	require.Equal(t, envPath, gotPath)
+	require.Equal(t, runtime.TypeDocker, gotRuntime)
+}

pkg/container/docker/sdk/client_windows.go

@@ -59,7 +59,7 @@ func newPlatformClient(pipePath string) (*http.Client, []client.Opt) {
 }
 
 // findPlatformContainerSocket finds a container socket path on Windows
-func findPlatformContainerSocket(rt runtime.Type) (string, runtime.Type, error) {
+func findPlatformContainerSocket(rt runtime.Type, overrides socketPathConfig) (string, runtime.Type, error) {
 	// First check for custom socket paths via environment variables
 	if customPipePath := os.Getenv(PodmanSocketEnv); customPipePath != "" {
 		//nolint:gosec // G706: pipe path from trusted environment variable
@@ -89,6 +89,15 @@ func findPlatformContainerSocket(rt runtime.Type) (string, runtime.Type, error)
 		return customPipePath, runtime.TypeDocker, nil
 	}
 
+	// Check config file overrides (after env vars, before auto-detection).
+	// Colima is not supported on Windows.
+	if overrides.podmanSocket != "" {
+		return resolveConfigPipe(overrides.podmanSocket, runtime.TypePodman, "Podman")
+	}
+	if overrides.dockerSocket != "" {
+		return resolveConfigPipe(overrides.dockerSocket, runtime.TypeDocker, "Docker")
+	}
+
 	if rt == runtime.TypePodman {
 		// Try Podman named pipe with timeout
 		ctx, cancel := context.WithTimeout(context.Background(), pipeConnectionTimeout)
@@ -117,3 +126,16 @@ func findPlatformContainerSocket(rt runtime.Type) (string, runtime.Type, error)
 
 	return "", "", ErrRuntimeNotFound
 }
+
+// resolveConfigPipe validates that a config-supplied named pipe path is connectable and returns it.
+func resolveConfigPipe(pipePath string, rt runtime.Type, runtimeName string) (string, runtime.Type, error) {
+	slog.Debug("using pipe from config", "runtime", runtimeName, "path", pipePath)
+	ctx, cancel := context.WithTimeout(context.Background(), pipeConnectionTimeout)
+	defer cancel()
+	conn, err := winio.DialPipeContext(ctx, pipePath)
+	if err != nil {
+		return "", rt, fmt.Errorf("invalid %s pipe path from config: %w", runtimeName, err)
+	}
+	conn.Close()
+	return pipePath, rt, nil
+}

pkg/container/docker/sdk/factory.go

@@ -8,8 +8,12 @@ import (
 	"context"
 	"fmt"
 	"log/slog"
+	"os"
+	"path/filepath"
 
+	"github.com/adrg/xdg"
 	"github.com/docker/docker/client"
+	"gopkg.in/yaml.v3"
 
 	"github.com/stacklok/toolhive/pkg/container/runtime"
 )
@@ -49,15 +53,64 @@ const (
 
 var supportedSocketPaths = []runtime.Type{runtime.TypePodman, runtime.TypeDocker, runtime.TypeColima}
 
+// socketPathConfig holds optional socket path overrides loaded from config.
+type socketPathConfig struct {
+	podmanSocket string
+	dockerSocket string
+	colimaSocket string
+}
+
+// containerRuntimeOverrides is a minimal config shape for reading socket path
+// overrides from the ToolHive config file. A full pkg/config import is not
+// possible here due to an import cycle through pkg/transport -> pkg/container.
+type containerRuntimeOverrides struct {
+	ContainerRuntime struct {
+		DockerSocket string `yaml:"docker_socket,omitempty"`
+		PodmanSocket string `yaml:"podman_socket,omitempty"`
+		ColimaSocket string `yaml:"colima_socket,omitempty"`
+	} `yaml:"container_runtime,omitempty"`
+}
+
+// loadSocketOverrides reads socket path overrides from the ToolHive config file.
+// Best-effort: returns empty overrides on any error so auto-detection takes over.
+func loadSocketOverrides() socketPathConfig {
+	configPath, err := xdg.ConfigFile("toolhive/config.yaml")
+	if err != nil {
+		slog.Debug("failed to resolve config path for socket overrides", "error", err)
+		return socketPathConfig{}
+	}
+
+	// #nosec G304: path is derived from XDG config dir, not user input.
+	data, err := os.ReadFile(filepath.Clean(configPath))
+	if err != nil {
+		slog.Debug("failed to read config file for socket overrides", "error", err)
+		return socketPathConfig{}
+	}
+
+	var cfg containerRuntimeOverrides
+	if err := yaml.Unmarshal(data, &cfg); err != nil {
+		slog.Debug("failed to parse config file for socket overrides", "error", err)
+		return socketPathConfig{}
+	}
+
+	return socketPathConfig{
+		dockerSocket: cfg.ContainerRuntime.DockerSocket,
+		podmanSocket: cfg.ContainerRuntime.PodmanSocket,
+		colimaSocket: cfg.ContainerRuntime.ColimaSocket,
+	}
+}
+
 // NewDockerClient creates a new container client
 func NewDockerClient(ctx context.Context) (*client.Client, string, runtime.Type, error) {
 	var lastErr error
 
+	overrides := loadSocketOverrides()
+
 	// We try to find a container socket for the given runtime
 	// We try Podman first, then Docker as fallback
 	for _, sp := range supportedSocketPaths {
 		// Try to find a container socket for the given runtime
-		socketPath, runtimeType, err := findContainerSocket(sp)
+		socketPath, runtimeType, err := findContainerSocket(sp, overrides)
 		if err != nil {
 			//nolint:gosec // G706: runtime type from internal config
 			slog.Debug("failed to find socket", "runtime", sp, "error", err)
@@ -105,7 +158,7 @@ func newClientWithSocketPath(ctx context.Context, socketPath string) (*client.Cl
 }
 
 // findContainerSocket finds a container socket path, preferring Podman over Docker
-func findContainerSocket(rt runtime.Type) (string, runtime.Type, error) {
+func findContainerSocket(rt runtime.Type, overrides socketPathConfig) (string, runtime.Type, error) {
 	// Use platform-specific implementation
-	return findPlatformContainerSocket(rt)
+	return findPlatformContainerSocket(rt, overrides)
 }