feat: more robust Reusable containers experience by mdelapenya · Pull Request #2768 · testcontainers/testcontainers-go

mdelapenya · 2024-09-04T16:20:21Z

What does this PR do?

This PR modifies the way the Reuse mode is implemented in the project, taking tc-java as the implementation reference. For that:

instead of passing Reuse plus the container name, we don't need to pass a container name anymore, only the Reuse field. This is a breaking change in terms of semantics.
we are calculating a hash of the container request just before the creation of the container.
we use github.com/mitchellh/hashstructure/v2 for the hash of the container request, with the following exceptions:
- functions in the struct are ignored (e.g. config modifiers). Please search for hash:"ignore" to identify them all.
- if the Files field contains a reference to a directory in the host, it won't participate in the calculation of the hash, as we don't want to traverse the directory getting the hash for the directory tree.
- for the real files in the Files field, we'll read their bytes and use them get a hash, which will be added to the struct hash.
for containers marked for reuse, two labels will be added:
- org.testcontainers.hash: the hash of the container request.
- org.testcontainers.copied_files.hash: the hash of the files copied to the container using the Files field in the container request.
those two labels will be used to check if a container exists in the docker daemon: the code will do a backoff search up-to 5 seconds (not configurable, maybe desired?), and if there is no container, it will create a new one. Else, the container will be reused. This backoff search is needed because we want to support the use case where multiple and different test processes start the same container, so they can "reuse" it.
the SessionID label of the container will be removed from the container request before the container is created, to not tell Ryuk this container must be terminated alongside the test session. Therefore, the container persists across test sessions.
the ReuseOrCreateContainer from the provider struct has been deprecated for removal in the upcoming releases.
the docs for Reuse has been updated, trying to make it clear the expectations around Reuse.
the tests have been updated too, to reflect the new state for Reuse.
modules are receving a functional option for marking module containers as reusable.

Why is it important?

Create a more consistent experience around reuse, based on the container state and not forcing the user to add a container name, that can be reused by mistake in a totally different container request.

We expect this change helps the community, but at the same time warn about its usage in parallel executions, as it could be the case that two concurrent test sessions get to the container creation at the same time, which could lead to the creation of two containers with the same request.

Related issues

Docs

Render URLs:

Reuse docs: https://deploy-preview-2768--testcontainers-go.netlify.app/features/creating_container/#reusable-container
Reuse option for modules: https://deploy-preview-2768--testcontainers-go.netlify.app/modules/chroma/#withreuse

Follow-ups

Please try out this branch, and read the docs so that they can be improved if needed 🙏

…ed files

Removing the sessionID label, it won't be pruned by Ryuk

netlify · 2024-09-04T16:20:39Z

✅ Deploy Preview for testcontainers-go ready!

Name	Link
🔨 Latest commit	`a1a51a4`
🔍 Latest deploy log	https://app.netlify.com/sites/testcontainers-go/deploys/678112aecce36200085dbee8
😎 Deploy Preview	https://deploy-preview-2768--testcontainers-go.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify site configuration.

mdelapenya · 2024-09-04T16:22:09Z

@stevenh as always, your wise 👀 are more than welcome!

mdelapenya · 2024-09-05T08:13:17Z

docker.go

+		// 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)


I see this as a potential configuration:

a property: testcontainers.reuse.search.timeout, and

an env var: TESTCONTAINERS_REUSE_SEARCH_TIMEOUT

Since the PR description says:

We expect this change helps the community, but at the same time warn about its usage in parallel executions, as it could be the case that two concurrent test sessions get to the container creation at the same time, which could lead to the creation of two containers with the same request.

wouldn't we want to accept this limitation and allow for the race condition with the current implementation?

Indeed. Added that comment as an idea for a potential follow-up

aaomidi · 2024-09-05T20:20:52Z

I wonder if this solves this bug: #2749

I'll do a small code review here as well. Thank you for this!

stevenh

Done an initial pass

stevenh · 2024-09-07T15:02:14Z

docker.go

-	err = req.creatingHook(ctx)
-	if err != nil {
-		return nil, err
+	if req.Reuse {


question: Not sure about this, I would expect reused containers to still only persist while in use, is that the intent?

The edge case for shutdown while still in use, is addressed by reaper rework PRs, so it should be safe to remove this if the desired behaviour is to share between test runs that are within a reasonable window.

stevenh · 2024-09-07T15:06:03Z

docker.go

+		reuseContainerMx.Lock()
+		defer reuseContainerMx.Unlock()


question: This will lock for the duration of rest of the call, is that the intention?

docker.go

stevenh · 2024-09-07T15:53:10Z

request_hash.go

+				if !ok {
+					// Calculate the hash of the file content only if it is a file.
+					fileContent, err = os.ReadFile(f.HostFilePath)
+					if err != nil {


bug: this will lead to unexplained issues.

I see 🤔 . So it'd be ideal to get all the possible errors and fail the hash calculation, wouldn't it?

request_hash.go

stevenh · 2024-09-07T15:55:41Z

request_hash.go

+)
+
+// containerHash represents the hash of the container configuration
+type containerHash struct {


question: are two independent hashes needed.

request_hash.go

mdelapenya · 2024-09-10T10:06:32Z

@kiview I'm converting to draft until we discuss internally about the implications of switching from the container name-based approach to a hash-based approach. Will share here the discussion once it takes place.

docker.go

* main: (103 commits) feat(postgres): ssl for postgres (testcontainers#2473) feat(ollama): support calling the Ollama local process (testcontainers#2923) chore(deps): bump jinja2 from 3.1.4 to 3.1.5 (testcontainers#2935) chore(deps): bump sonarsource/sonarcloud-github-action (testcontainers#2933) feat(termination)!: make container termination timeout configurable (testcontainers#2926) chore(deps): bump slackapi/slack-github-action from 1.26.0 to 2.0.0 (testcontainers#2934) chore(deps): bump github/codeql-action from 3.25.15 to 3.28.0 (testcontainers#2932) feat(wait): log sub match callback (testcontainers#2929) fix: Handle nil value in CleanupNetwork (testcontainers#2928) fix: avoid double lock in DockerProvider.DaemonHost() (testcontainers#2900) feat!: build log writer for container request (testcontainers#2925) feat(gcloud)!: add support to seed data when using RunBigQueryContainer (testcontainers#2523) security(deps): bump golang.org/x/crypto from 0.28.0 to 0.31.0 (testcontainers#2916) chore(ci): add Github labels based on PR title (testcontainers#2914) chore(gha): Use official setup-docker-action (testcontainers#2913) chore(ci): enforce conventional commits syntax in PR titles (testcontainers#2911) feat(nats): WithConfigFile - pass a configuration file to nats server (testcontainers#2905) chore: enable implicit default logger only in testing with -v (testcontainers#2877) fix: container binds syntax (testcontainers#2899) refactor(cockroachdb): to use request driven options (testcontainers#2883) ...

ayuhito · 2025-03-17T00:50:56Z

instead of passing Reuse plus the container name, we don't need to pass a container name anymore, only the Reuse field. This is a breaking change in terms of semantics.

Would the container name still influence the final hash? I think it would be good to still have a way to differentiate the same container for certain cases (e.g. I have Postgres snapshots with different migrations and fixtures).

mdelapenya added 21 commits September 3, 2024 14:37

feat: calculate hash of a container request

4902c76

chore: run mod tidy

10daab5

feat: calculate the hash of a container request, considering the copi…

ed3e1fa

…ed files

chore: add labels for the container hashes

442dd4a

feat: reuse containers based on hashes

969fe59

docs: document reuse

c2f5e83

chore: add more tests for not hashing dir contents

dcbb467

fix: wait for the container to be created

c07b5dc

chore: simplify deprecation

d1d40ce

docs: improve docs for reuse

7aa26da

feat: do not remove the container with Ryuk

35da30a

Removing the sessionID label, it won't be pruned by Ryuk

docs: enrich reuse docs

0ffec34

feat: support modules to be reused

7a505ba

docs: refinement

a544bc0

chore: adjust tests

c9356ed

chore: adapt test to flakiness

1f66181

chore: calculate hash at the right time

31e54b9

chore: improve the subprocess tests

44b1b73

chore: make lint

781ade7

chore: no need to ignore Reuse

e975ae9

docs: warn about flakiness in concurrent executions

dd91901

mdelapenya requested a review from a team as a code owner September 4, 2024 16:20

mdelapenya added the breaking change Causing compatibility issues. label Sep 4, 2024

mdelapenya self-assigned this Sep 4, 2024

mdelapenya requested review from eddumelendez and kiview September 4, 2024 16:20

This was referenced Sep 4, 2024

[Bug]: Ryuk might shutdown reused Container while connected to it #2445

Open

[Feature]: Containers with Reuse should not be killed by Ryuk #2654

Open

[Enhancement]: Reuse flag to start exited or paused containers #2470

Open

mdelapenya mentioned this pull request Sep 4, 2024

[Enhancement]: Reuse flag for module Postgres #2726

Closed

mdelapenya commented Sep 5, 2024

View reviewed changes

docs: do not use postgres in funcitonal options

799ee15

stevenh requested changes Sep 7, 2024

View reviewed changes

mdelapenya marked this pull request as draft September 10, 2024 10:05

mdelapenya mentioned this pull request Sep 13, 2024

fix(reaper): refactor to allow retries and fix races #2728

Merged

mdelapenya commented Sep 24, 2024

View reviewed changes

docker.go Outdated Show resolved Hide resolved

mdelapenya added 12 commits January 8, 2025 11:50

chore: wrap error

c3c74c3

chore: combine if

6d5e655

chor: return notFound errors

702b457

chore: simplify test

b7b3a4f

chore: remove not needed if

8323081

chore: use faster strconv.FormatUint

98fdeb1

fix: use streaming to avoid copying the entire file in memory

1722fba

chore: handle errors in the hash function

4c13c2b

chore: avoid collitions when building the hash of the files

cecb112

chore: delete Reap label, not SessionID

d4fc593

fix: use faster strconv.FormatUint

a1a51a4

mdelapenya mentioned this pull request Mar 28, 2025

feat: add WithReuseByName for modifying Generic Container Requests #3064

Merged

mdelapenya mentioned this pull request Jan 8, 2026

[Bug]: Postgres dbName is ignored #3512

Open

Uh oh!

Conversation

mdelapenya commented Sep 4, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What does this PR do?

Why is it important?

Related issues

Docs

Follow-ups

Uh oh!

netlify bot commented Sep 4, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Deploy Preview for testcontainers-go ready!

Uh oh!

mdelapenya commented Sep 4, 2024

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

aaomidi commented Sep 5, 2024

Uh oh!

stevenh left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

mdelapenya commented Sep 10, 2024

Uh oh!

Uh oh!

ayuhito commented Mar 17, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

mdelapenya commented Sep 4, 2024 •

edited

Loading

netlify bot commented Sep 4, 2024 •

edited

Loading