feat: more robust Reusable containers experience

container.go

@@ -102,7 +102,7 @@ type FromDockerfile struct {
 	// BuildOptionsModifier Modifier for the build options before image build. Use it for
 	// advanced configurations while building the image. Please consider that the modifier
 	// is called after the default build options are set.
-	BuildOptionsModifier func(*types.ImageBuildOptions)
+	BuildOptionsModifier func(*types.ImageBuildOptions) `hash:"ignore"`
 }
 
 type ContainerFile struct {
@@ -141,6 +141,7 @@ type ContainerRequest struct {
 	RegistryCred            string // Deprecated: Testcontainers will detect registry credentials automatically
 	WaitingFor              wait.Strategy
 	Name                    string // for specifying container name
+	Reuse                   bool   // For reusing an existing container
 	Hostname                string
 	WorkingDir              string                                     // specify the working directory of the container
 	ExtraHosts              []string                                   // Deprecated: Use HostConfigModifier instead
@@ -161,10 +162,10 @@ type ContainerRequest struct {
 	ShmSize                 int64                                      // Amount of memory shared with the host (in bytes)
 	CapAdd                  []string                                   // Deprecated: Use HostConfigModifier instead. Add Linux capabilities
 	CapDrop                 []string                                   // Deprecated: Use HostConfigModifier instead. Drop Linux capabilities
-	ConfigModifier          func(*container.Config)                    // Modifier for the config before container creation
-	HostConfigModifier      func(*container.HostConfig)                // Modifier for the host config before container creation
-	EnpointSettingsModifier func(map[string]*network.EndpointSettings) // Modifier for the network settings before container creation
-	LifecycleHooks          []ContainerLifecycleHooks                  // define hooks to be executed during container lifecycle
+	ConfigModifier          func(*container.Config)                    `hash:"ignore"` // Modifier for the config before container creation
+	HostConfigModifier      func(*container.HostConfig)                `hash:"ignore"` // Modifier for the host config before container creation
+	EnpointSettingsModifier func(map[string]*network.EndpointSettings) `hash:"ignore"` // Modifier for the network settings before container creation
+	LifecycleHooks          []ContainerLifecycleHooks                  `hash:"ignore"` // define hooks to be executed during container lifecycle
 	LogConsumerCfg          *LogConsumerConfig                         // define the configuration for the log producer and its log consumers to follow the logs
 }
 

docker.go

@@ -15,6 +15,7 @@ import (
 	"os"
 	"path/filepath"
 	"regexp"
+	"strconv"
 	"sync"
 	"time"
 
@@ -1205,29 +1206,82 @@ func (p *DockerProvider) CreateContainer(ctx context.Context, req ContainerReque
 		combineContainerHooks(defaultHooks, origLifecycleHooks),
 	}
 
-	err = req.creatingHook(ctx)
-	if err != nil {
-		return nil, err
+	var resp container.CreateResponse
+	if req.Reuse {
+		// we must protect the reusability of the container in the case it's invoked
+		// in a parallel execution, via ParallelContainers or t.Parallel()
+		reuseContainerMx.Lock()
+		defer reuseContainerMx.Unlock()
+
+		// Remove the Reap label from the request, as we don't want Ryuk to control
+		// the container lifecycle in the case of reusing containers.
+		delete(req.Labels, core.LabelReap)
+
+		// calculate the hash, and add the labels, just before creating the container
+		hash, err := req.hash()
+		if err != nil {
+			return nil, fmt.Errorf("hash container request: %w", err)
+		}
+
+		req.Labels[core.LabelContainerHash] = strconv.FormatUint(hash.Hash, 10)
+		req.Labels[core.LabelCopiedFilesHash] = strconv.FormatUint(hash.FilesHash, 10)
+
+		// in the case different test programs are creating a container with the same hash,
+		// we must check if the container is already created. For that we wait up to 5 seconds
+		// for the container to be created. If the error means the container is not found, we
+		// can proceed with the creation of the container.
+		// This is needed because we need to synchronize the creation of the container across
+		// different test programs.
+		c, err := p.waitContainerCreationInTimeout(ctx, hash, 5*time.Second)
+		if err != nil && !errdefs.IsNotFound(err) {
+			// another error occurred different from not found, so we return the error
+			return nil, fmt.Errorf("wait container creation: %w", err)
+		}
+
+		// Create a new container if the request is to reuse the container, but there is no container found by hash
+		if c != nil {
+			resp.ID = c.ID
+
+			// replace the logging messages for reused containers:
+			// we know the first lifecycle hook is the logger hook,
+			// so it's safe to replace its first message for reused containers.
+			req.LifecycleHooks[0].PreCreates[0] = func(ctx context.Context, req ContainerRequest) error {
+				Logger.Printf("🔥 Reusing container: %s", resp.ID[:12])
+				return nil
+			}
+			req.LifecycleHooks[0].PostCreates[0] = func(ctx context.Context, c Container) error {
+				Logger.Printf("🔥 Container reused: %s", resp.ID[:12])
+				return nil
+			}
+		}
 	}
 
-	resp, err := p.client.ContainerCreate(ctx, dockerInput, hostConfig, networkingConfig, platform, req.Name)
-	if err != nil {
-		return nil, fmt.Errorf("container create: %w", err)
-	}
-
-	// #248: If there is more than one network specified in the request attach newly created container to them one by one
-	if len(req.Networks) > 1 {
-		for _, n := range req.Networks[1:] {
-			nw, err := p.GetNetwork(ctx, NetworkRequest{
-				Name: n,
-			})
-			if err == nil {
-				endpointSetting := network.EndpointSettings{
-					Aliases: req.NetworkAliases[n],
-				}
-				err = p.client.NetworkConnect(ctx, nw.ID, resp.ID, &endpointSetting)
-				if err != nil {
-					return nil, fmt.Errorf("network connect: %w", err)
+	// If the container was not found by hash, create a new one
+	if resp.ID == "" {
+		err = req.creatingHook(ctx)
+		if err != nil {
+			return nil, err
+		}
+
+		resp, err = p.client.ContainerCreate(ctx, dockerInput, hostConfig, networkingConfig, platform, req.Name)
+		if err != nil {
+			return nil, fmt.Errorf("container create: %w", err)
+		}
+
+		// #248: If there is more than one network specified in the request attach newly created container to them one by one
+		if len(req.Networks) > 1 {
+			for _, n := range req.Networks[1:] {
+				nw, err := p.GetNetwork(ctx, NetworkRequest{
+					Name: n,
+				})
+				if err == nil {
+					endpointSetting := network.EndpointSettings{
+						Aliases: req.NetworkAliases[n],
+					}
+					err = p.client.NetworkConnect(ctx, nw.ID, resp.ID, &endpointSetting)
+					if err != nil {
+						return nil, fmt.Errorf("network connect: %w", err)
+					}
 				}
 			}
 		}
@@ -1280,13 +1334,38 @@ func (p *DockerProvider) findContainerByName(ctx context.Context, name string) (
 	if len(containers) > 0 {
 		return &containers[0], nil
 	}
-	return nil, nil
+	return nil, errdefs.NotFound(fmt.Errorf("container not found by name: %s", name))
+}
+
+func (p *DockerProvider) findContainerByHash(ctx context.Context, ch containerHash) (*types.Container, error) {
+	filter := filters.NewArgs(
+		filters.Arg("label", fmt.Sprintf("%s=%d", core.LabelContainerHash, ch.Hash)),
+		filters.Arg("label", fmt.Sprintf("%s=%d", core.LabelCopiedFilesHash, ch.FilesHash)),
+	)
+
+	containers, err := p.client.ContainerList(ctx, container.ListOptions{Filters: filter})
+	if err != nil {
+		return nil, err
+	}
+	defer p.Close()
+
+	if len(containers) > 0 {
+		return &containers[0], nil
+	}
+	return nil, errdefs.NotFound(fmt.Errorf("container not found by hash: %s", ch.String()))
 }
 
-func (p *DockerProvider) waitContainerCreation(ctx context.Context, name string) (*types.Container, error) {
+func (p *DockerProvider) waitContainerCreation(ctx context.Context, hash containerHash) (*types.Container, error) {
+	return p.waitContainerCreationInTimeout(ctx, hash, 5*time.Second)
+}
+
+func (p *DockerProvider) waitContainerCreationInTimeout(ctx context.Context, hash containerHash, timeout time.Duration) (*types.Container, error) {
+	exp := backoff.NewExponentialBackOff()
+	exp.MaxElapsedTime = timeout
+
 	return backoff.RetryNotifyWithData(
 		func() (*types.Container, error) {
-			c, err := p.findContainerByName(ctx, name)
+			c, err := p.findContainerByHash(ctx, hash)
 			if err != nil {
 				if !errdefs.IsNotFound(err) && isPermanentClientError(err) {
 					return nil, backoff.Permanent(err)
@@ -1295,11 +1374,11 @@ func (p *DockerProvider) waitContainerCreation(ctx context.Context, name string)
 			}
 
 			if c == nil {
-				return nil, errdefs.NotFound(fmt.Errorf("container %s not found", name))
+				return nil, errdefs.NotFound(fmt.Errorf("container %v not found", hash))
 			}
 			return c, nil
 		},
-		backoff.WithContext(backoff.NewExponentialBackOff(), ctx),
+		backoff.WithContext(exp, ctx),
 		func(err error, duration time.Duration) {
 			if errdefs.IsNotFound(err) {
 				return
@@ -1309,8 +1388,14 @@ func (p *DockerProvider) waitContainerCreation(ctx context.Context, name string)
 	)
 }
 
+// Deprecated: it will be removed in the next major release.
 func (p *DockerProvider) ReuseOrCreateContainer(ctx context.Context, req ContainerRequest) (con Container, err error) {
-	c, err := p.findContainerByName(ctx, req.Name)
+	hash, err := req.hash()
+	if err != nil {
+		return nil, fmt.Errorf("hash container request: %w", err)
+	}
+
+	c, err := p.findContainerByHash(ctx, hash)
 	if err != nil {
 		return nil, err
 	}
@@ -1322,7 +1407,7 @@ func (p *DockerProvider) ReuseOrCreateContainer(ctx context.Context, req Contain
 		if !createContainerFailDueToNameConflictRegex.MatchString(err.Error()) {
 			return nil, err
 		}
-		c, err = p.waitContainerCreation(ctx, req.Name)
+		c, err = p.waitContainerCreation(ctx, hash)
 		if err != nil {
 			return nil, err
 		}

docker_test.go

@@ -2142,7 +2142,7 @@ func TestDockerProvider_waitContainerCreation_retries(t *testing.T) {
 			// give a chance to retry
 			ctx, cancel := context.WithTimeout(context.Background(), 1*time.Second)
 			defer cancel()
-			_, _ = p.waitContainerCreation(ctx, "someID")
+			_, _ = p.waitContainerCreation(ctx, containerHash{})
 
 			assert.Positive(t, m.containerListCount)
 			assert.Equal(t, tt.shouldRetry, m.containerListCount > 1)

docs/features/common_functional_options.md

@@ -32,7 +32,7 @@ postgres, err = postgresModule.Run(ctx, "postgres:15-alpine", testcontainers.Wit
 If you need to access a port that is already running in the host, you can use `testcontainers.WithHostPortAccess` for example:
 
 ```golang
-postgres, err = postgresModule.Run(ctx, "postgres:15-alpine", testcontainers.WithHostPortAccess(8080))
+ctr, err = tcmodule.Run(ctx, "your-image:your-tag", testcontainers.WithHostPortAccess(8080))
 ```
 
 To understand more about this feature, please read the [Exposing host ports to the container](/features/networking/#exposing-host-ports-to-the-container) documentation.
@@ -70,7 +70,7 @@ useful context instead of appearing out of band.
 ```golang
 func TestHandler(t *testing.T) {
     logger := TestLogger(t)
-    ctr, err := postgresModule.Run(ctx, "postgres:15-alpine", testcontainers.WithLogger(logger))
+    ctr, err := yourModule.Run(ctx, "your-image:your-tag", testcontainers.WithLogger(logger))
     CleanupContainer(t, ctr)
     require.NoError(t, err)
     // Do something with container.
@@ -136,6 +136,18 @@ If you want to attach your containers to a throw-away network, you can use the `
 
 In the case you need to retrieve the network name, you can use the `Networks(ctx)` method of the `Container` interface, right after it's running, which returns a slice of strings with the names of the networks where the container is attached.
 
+#### WithReuse
+
+- Not available until the next release of testcontainers-go <a href="https://github.com/testcontainers/testcontainers-go"><span class="tc-version">:material-tag: main</span></a>
+
+If you want to reuse a container across different test executions, you can use `testcontainers.WithReuse` option. This option will keep the container running after the test execution, so it can be reused by any other test sharing the same `ContainerRequest`. As a result, the container is not terminated by Ryuk.
+
+```golang
+ctr, err = tcmodule.Run(ctx, "your-image:your-tag", testcontainers.WithReuse())
+```
+
+Please read the [Reuse containers](/features/creating_container#reusable-container) documentation for more information.
+
 #### Docker type modifiers
 
 If you need an advanced configuration for the container, you can leverage the following Docker type modifiers:
@@ -144,14 +156,14 @@ If you need an advanced configuration for the container, you can leverage the fo
 - `testcontainers.WithHostConfigModifier`
 - `testcontainers.WithEndpointSettingsModifier`
 
-Please read the [Create containers: Advanced Settings](/features/creating_container.md#advanced-settings) documentation for more information.
+Please read the [Create containers: Advanced Settings](/features/creating_container#advanced-settings) documentation for more information.
 
 #### Customising the ContainerRequest
 
 This option will merge the customized request into the module's own `ContainerRequest`.
 
 ```go
-container, err := Run(ctx, "postgres:13-alpine",
+ctr, err := Run(ctx, "your-image:your-tag",
     /* Other module options */
     testcontainers.CustomizeRequest(testcontainers.GenericContainerRequest{
         ContainerRequest: testcontainers.ContainerRequest{