fix(compose): close docker clients to prevent goroutine leaks (#3661)

* fix(compose): close docker clients to prevent goroutine leaks

Close dockerCli.Client() and dockerClient in Down() to release
net/http persistConn.readLoop/writeLoop goroutines that were leaking
on every Up+Down cycle.

Store the *command.DockerCli instance in the DockerCompose struct so
its HTTP transport connections can be closed during teardown.
Previously the dockerCli was created in NewDockerComposeWith() but
never retained, so its HTTP client connections could not be released.

Adds TestDockerComposeGoroutineLeak to demonstrate the fix: it
snapshots goroutines before an Up+Down cycle and asserts that no
net/http persistConn goroutines remain afterward.

Fixes #2008

Co-Authored-By: Claude <noreply@anthropic.com>

* fix(compose): address code review feedback on goroutine leak fix

- Extract Close() method on DockerCompose for explicit resource cleanup,
  removing the close defer from Down() to keep teardown and resource
  release concerns separate. Down() is no longer single-use.
- Add go.uber.org/goleak as a direct dependency and replace the hand-rolled
  goroutineSnapshot/goroutineLeaks helpers with goleak.VerifyNone, which
  handles the buffer-growth loop, exponential retry and cleaner reporting.
- Use goleak.IgnoreCurrent() (snapshotted after NewDockerCompose) plus
  IgnoreTopFunction for Reaper goroutines to scope the leak check to
  goroutines introduced by the Up+Down lifecycle only.
- Call compose.Close() in t.Cleanup, after Down(), to release HTTP transport
  connections from both dockerCli.Client() and dockerClient.

Co-Authored-By: Claude <noreply@anthropic.com>

* fix(compose): address second round of code review feedback

- Make Close() idempotent by nil-ing dockerCli and dockerClient after
  closing them, so double-close is a no-op.
- Add TODO(#2008) comment on the IgnoreTopFunction filter explaining that
  it pins on an internal closure name that may change if Reaper is
  refactored, and should be removed when the Reaper leak is fixed.
- Register compose.Down in a t.Cleanup (LIFO after Close) so teardown
  runs even if the test panics after Up succeeds.

Co-Authored-By: Claude <noreply@anthropic.com>

---------

Co-authored-by: Claude <noreply@anthropic.com>

Author: mdelapenya

modules/compose/compose.go

@@ -182,6 +182,7 @@ func NewDockerComposeWith(opts ...ComposeStackOption) (*DockerCompose, error) {
 		logger:           composeOptions.Logger,
 		projectProfiles:  composeOptions.Profiles,
 		composeService:   composeService,
+		dockerCli:        dockerCli,
 		dockerClient:     dockerClient,
 		waitStrategies:   make(map[string]wait.Strategy),
 		containers:       make(map[string]*testcontainers.DockerContainer),

modules/compose/compose_api.go

@@ -15,6 +15,7 @@ import (
 
 	"github.com/compose-spec/compose-go/v2/cli"
 	"github.com/compose-spec/compose-go/v2/types"
+	"github.com/docker/cli/cli/command"
 	"github.com/docker/compose/v5/pkg/api"
 	"github.com/moby/moby/client"
 	"golang.org/x/sync/errgroup"
@@ -180,6 +181,10 @@ type DockerCompose struct {
 	// used to synchronize operations
 	lock sync.RWMutex
 
+	// dockerCli is the Docker CLI instance used internally by the compose service.
+	// It is stored here so its HTTP transport connections can be closed after Down().
+	dockerCli *command.DockerCli
+
 	// name/identifier of the stack that will be started
 	// by default a UUID will be used
 	name string
@@ -267,6 +272,34 @@ func (d *DockerCompose) Down(ctx context.Context, opts ...StackDownOption) error
 	return d.composeService.Down(ctx, d.name, options.DownOptions)
 }
 
+// Close releases the HTTP transport connections held by the internal Docker CLI
+// and the testcontainers Docker client, preventing net/http persistConn goroutine
+// leaks. Call Close after Down when the compose stack will no longer be used.
+func (d *DockerCompose) Close() error {
+	d.lock.Lock()
+	defer d.lock.Unlock()
+
+	var errs []error
+
+	if d.dockerCli != nil {
+		if cli := d.dockerCli.Client(); cli != nil {
+			if err := cli.Close(); err != nil {
+				errs = append(errs, fmt.Errorf("close docker cli client: %w", err))
+			}
+		}
+		d.dockerCli = nil
+	}
+
+	if d.dockerClient != nil {
+		if err := d.dockerClient.Close(); err != nil {
+			errs = append(errs, fmt.Errorf("close docker client: %w", err))
+		}
+		d.dockerClient = nil
+	}
+
+	return errors.Join(errs...)
+}
+
 func (d *DockerCompose) Up(ctx context.Context, opts ...StackUpOption) (err error) {
 	d.lock.Lock()
 	defer d.lock.Unlock()

modules/compose/compose_goroutine_test.go

@@ -0,0 +1,55 @@
+package compose
+
+import (
+	"context"
+	"testing"
+
+	"github.com/stretchr/testify/require"
+	"go.uber.org/goleak"
+)
+
+// TestDockerComposeGoroutineLeak verifies that calling Up() followed by Down()
+// and Close() does not leak net/http persistConn goroutines from the internal
+// Docker CLI HTTP transport.
+//
+// Before the fix, two goroutines per Up+Down cycle were leaked permanently:
+//
+//	net/http.(*persistConn).readLoop
+//	net/http.(*persistConn).writeLoop
+//
+// Note: Reaper (Ryuk) goroutines are intentionally excluded from this check;
+// they are a separate pre-existing issue tracked in the same issue but require
+// a distinct fix involving Reaper termination signal handling in Down().
+func TestDockerComposeGoroutineLeak(t *testing.T) {
+	path, _ := RenderComposeSimple(t)
+
+	compose, err := NewDockerCompose(path)
+	require.NoError(t, err, "NewDockerCompose()")
+
+	// Snapshot goroutines after NewDockerCompose establishes its initial
+	// Docker provider connection, so IgnoreCurrent covers the provider's
+	// keep-alive transport goroutines that pre-date the compose Up/Down cycle.
+	ignoreExisting := goleak.IgnoreCurrent()
+
+	// Register Close cleanup first so it runs last (t.Cleanup is LIFO).
+	// goleak.VerifyNone is called here so it runs after both Down and Close.
+	t.Cleanup(func() {
+		require.NoError(t, compose.Close(), "compose.Close()")
+		goleak.VerifyNone(t,
+			ignoreExisting,
+			// TODO(#2008): Remove this ignore when the Reaper goroutine leak is fixed.
+			// This references an internal anonymous closure that may change if Reaper is refactored.
+			goleak.IgnoreTopFunction("github.com/testcontainers/testcontainers-go.(*Reaper).connect.func1"),
+		)
+	})
+
+	ctx := context.Background()
+
+	require.NoError(t, compose.Up(ctx, Wait(true)), "compose.Up()")
+
+	// Register Down cleanup after Up so it runs before Close (t.Cleanup is LIFO).
+	// This ensures Down is called even if the test panics after Up succeeds.
+	t.Cleanup(func() {
+		require.NoError(t, compose.Down(ctx, RemoveOrphans(true), RemoveVolumes(true)), "compose.Down()")
+	})
+}

modules/compose/go.mod

@@ -13,6 +13,7 @@ require (
 	github.com/moby/moby/client v0.4.0
 	github.com/stretchr/testify v1.11.1
 	github.com/testcontainers/testcontainers-go v0.42.0
+	go.uber.org/goleak v1.3.0
 	go.yaml.in/yaml/v3 v3.0.4
 	golang.org/x/sync v0.20.0
 )