Merge branch 'main' into fix/respect-testing

.github/workflows/ci-test-go.yml

@@ -119,11 +119,18 @@ jobs:
         timeout-minutes: 30
         run: make test-unit
 
+      - name: Set sonar artifact name
+        # For the core library, where the project directory is '.', we'll use "core" as artifact name.
+        # For the modules, we'll remove the slashes, keeping the name of the module
+        if: ${{ github.ref_name == 'main' && github.repository_owner == 'testcontainers' && inputs.platform == 'ubuntu-latest' && inputs.run-tests && !inputs.rootless-docker && !inputs.ryuk-disabled }}
+        run: |
+          echo "ARTIFACT_NAME=$(basename ${{ inputs.project-directory == '.' && 'core' || inputs.project-directory }})-${{ inputs.go-version }}-${{ inputs.platform }}" >> $GITHUB_ENV
+
       - name: Upload SonarCloud files
-        if: ${{ github.ref_name == 'main' && github.repository_owner == 'testcontainers' && inputs.run-tests && !inputs.rootless-docker }}
-        uses: actions/upload-artifact@a8a3f3ad30e3422c9c7b888a15615d19a852ae32 # v3
+        if: ${{ github.ref_name == 'main' && github.repository_owner == 'testcontainers' && inputs.platform == 'ubuntu-latest' && inputs.run-tests && !inputs.rootless-docker && !inputs.ryuk-disabled }}
+        uses: actions/upload-artifact@b4b15b8c7c6ac21ea08fcf65892d2ee8f75cf882 # v4.4.3
         with:
-          name: sonarcloud
+          name: sonarcloud-${{ env.ARTIFACT_NAME }}
           path: |
             ./sonar-project.properties
             ${{ inputs.project-directory }}/TEST-unit.xml

.github/workflows/ci.yml

@@ -134,9 +134,10 @@ jobs:
           # Disabling shallow clone is recommended for improving relevancy of reporting
           fetch-depth: 0
 
-      - uses: actions/download-artifact@9bc31d5ccc31df68ecc42ccf4149144866c47d8a # v3.0.2
+      - uses: actions/download-artifact@fa0a91b85d4f404e444e00e005971372dc801d16 # v4.1.8
         with:
-          name: sonarcloud
+          pattern: sonarcloud-*
+          merge-multiple: true
 
       - name: Analyze with SonarCloud
         uses: sonarsource/sonarcloud-github-action@49e6cd3b187936a73b8280d59ffd9da69df63ec9 # v2.1.1

.github/workflows/docker-moby-latest.yml

@@ -11,10 +11,6 @@ jobs:
       matrix:
         rootless-docker: [true, false]
         containerd-integration: [true, false]
-        # ghaction-setup-docker doesn't work with rootless yet
-        exclude:
-          - rootless-docker: true
-            containerd-integration: true
 
     name: "Core tests using latest moby/moby"
     runs-on: 'ubuntu-latest'
@@ -25,14 +21,6 @@ jobs:
           echo "docker_install_type=${{ matrix.rootless-docker == true && 'Rootless' || 'Rootful' }}" >> "$GITHUB_ENV"
           echo "containerd_integration=${{ matrix.containerd-integration == true && 'containerd' || '' }}" >> "$GITHUB_ENV"
 
-      - name: Setup rootless Docker
-        if: ${{ matrix.rootless-docker }}
-        uses: ScribeMD/rootless-docker@6bd157a512c2fafa4e0243a8aa87d964eb890886  # v0.2.2
-
-      - name: Remove Docker root socket
-        if: ${{ matrix.rootless-docker }}
-        run: sudo rm -rf /var/run/docker.sock
-
       - name: Check out code into the Go module directory
         uses: actions/checkout@692973e3d937129bcbf40652eb9f2f61becf3332 # v4
 
@@ -50,22 +38,17 @@ jobs:
         run: go mod tidy
 
       - name: Install Nightly Docker
-        # rootless not supported with ghaction-setup-docker yet
-        if: ${{ matrix.rootless-docker == false }}
         uses: crazy-max/ghaction-setup-docker@master
         with:
+          rootless: ${{ matrix.rootless-docker }}
+          version: type=image,tag=master
           daemon-config: |
             {
               "debug": true,
               "features": {
                 "containerd-snapshotter": ${{ matrix.containerd-integration }}
               }
             }
-          version: type=image,tag=master
-
-      - name: Install test Docker
-        if: ${{ matrix.rootless-docker }}
-        run: curl https://get.docker.com | CHANNEL=test sh
 
       - name: go test
         timeout-minutes: 30

.github/workflows/scorecards.yml

@@ -43,7 +43,7 @@ jobs:
       # Upload the results as artifacts (optional). Commenting out will disable uploads of run results in SARIF
       # format to the repository Actions tab.
       - name: "Upload artifact"
-        uses: actions/upload-artifact@a8a3f3ad30e3422c9c7b888a15615d19a852ae32 # v3.1.3
+        uses: actions/upload-artifact@b4b15b8c7c6ac21ea08fcf65892d2ee8f75cf882 # v4.4.3
         with:
           name: SARIF file
           path: results.sarif

Makefile

@@ -1,5 +1,12 @@
 include ./commons-test.mk
 
+.PHONY: lint-all
+lint-all:
+	$(MAKE) lint
+	$(MAKE) -C modulegen lint
+	$(MAKE) -C examples lint-examples
+	$(MAKE) -C modules lint-modules
+
 .PHONY: test-all
 test-all: tools test-tools test-unit
 

docker.go

@@ -1185,6 +1185,18 @@ func (p *DockerProvider) CreateContainer(ctx context.Context, req ContainerReque
 			return nil, fmt.Errorf("expose host ports: %w", err)
 		}
 
+		defer func() {
+			if err != nil && con == nil {
+				// Container setup failed so ensure we clean up the sshd container too.
+				ctr := &DockerContainer{
+					provider:       p,
+					logger:         p.Logger,
+					lifecycleHooks: []ContainerLifecycleHooks{sshdForwardPortsHook},
+				}
+				err = errors.Join(ctr.terminatingHook(ctx))
+			}
+		}()
+
 		defaultHooks = append(defaultHooks, sshdForwardPortsHook)
 	}
 
@@ -1623,17 +1635,23 @@ func (p *DockerProvider) ensureDefaultNetwork(ctx context.Context) (string, erro
 		return "", fmt.Errorf("network list: %w", err)
 	}
 
+	// TODO: remove once we have docker context support via #2810
+	// Prefer the default bridge network if it exists.
+	// This makes the results stable as network list order is not guaranteed.
 	for _, net := range networkResources {
 		switch net.Name {
 		case p.defaultBridgeNetworkName:
 			p.defaultNetwork = p.defaultBridgeNetworkName
 			return p.defaultNetwork, nil
 		case ReaperDefault:
 			p.defaultNetwork = ReaperDefault
-			return p.defaultNetwork, nil
 		}
 	}
 
+	if p.defaultNetwork != "" {
+		return p.defaultNetwork, nil
+	}
+
 	// Create a bridge network for the container communications.
 	_, err = p.client.NetworkCreate(ctx, ReaperDefault, network.CreateOptions{
 		Driver:     Bridge,

docs/contributing.md

@@ -1,16 +1,93 @@
 # Contributing
 
-* Star the project on [Github](https://github.com/testcontainers/testcontainers-go) and help spread the word :)
-* Join our [Slack workspace](http://slack.testcontainers.org)
-* [Post an issue](https://github.com/testcontainers/testcontainers-go/issues) if you find any bugs
-* Contribute improvements or fixes using a [Pull Request](https://github.com/testcontainers/testcontainers-go/pulls). If you're going to contribute, thank you! Please just be sure to:
-    * discuss with the authors on an issue ticket prior to doing anything big.
-    * follow the style, naming and structure conventions of the rest of the project.
-    * make commits atomic and easy to merge.
-    * when updating documentation, please see [our guidance for documentation contributions](contributing_docs.md).
-    * when updating the `go.mod` file, please run `make tidy-all` to ensure all modules are updated. It will run `golangci-lint` with the configuration set in the root directory of the project. Please be aware that the lint stage could fail if this is not done.
-    * apply format running `make lint`
-        * For examples: `make -C examples lint`
-        * For modules: `make -C modules lint`
-    * verify all tests are passing. Build and test the project with `make test-all` to do this.
-        * For a given module or example, go to the module or example directory and run `make test`.
+`Testcontainers for Go` is open source, and we love to receive contributions from our community — you!
+
+There are many ways to contribute, from writing tutorials or blog posts, improving the documentation, submitting bug reports and feature requests, or writing code for the core library or for a technology module.
+
+In any case, if you like the project, please star the project on [Github](https://github.com/testcontainers/testcontainers-go/stargazers) and help spread the word :)
+Also join our [Slack workspace](http://slack.testcontainers.org) to get help, share your ideas, and chat with the community.
+
+## Questions
+
+GitHub is reserved for bug reports and feature requests; it is not the place for general questions.
+If you have a question or an unconfirmed bug, please visit our [Slack workspace](https://testcontainers.slack.com/);
+feedback and ideas are always welcome.
+
+## Code contributions
+
+If you have a bug fix or new feature that you would like to contribute, please find or open an [issue](https://github.com/testcontainers/testcontainers-go/issues) first.
+It's important to talk about what you would like to do, as there may already be someone working on it,
+or there may be context to be aware of before implementing the change.
+
+Next would be to fork the repository and make your changes in a feature branch. **Please do not commit changes to the `main` branch**,
+otherwise we won't be able to contribute to your changes directly in the PR.
+
+### Submitting your changes
+
+Please just be sure to:
+
+* follow the style, naming and structure conventions of the rest of the project.
+* make commits atomic and easy to merge.
+* use [conventional commits](https://www.conventionalcommits.org/en/v1.0.0/) for the PR title. This will help us to understand the nature of the changes, and to generate the changelog after all the commits in the PR are squashed.
+* use [conventional commits](https://www.conventionalcommits.org/en/v1.0.0/) for your commit messages, as it improves the readability of the commit history, and the review process.
+* unless necessary, please try to **avoid pushing --force** to the published branch you submitted a PR from, as it makes it harder to review the changes from a given previous state.
+* apply format running `make lint-all`. It will run `golangci-lint` for the core and modules with the configuration set in the root directory of the project. Please be aware that the lint stage on CI could fail if this is not done.
+    * For linting just the modules: `make -C modules lint-modules`
+    * For linting just the examples: `make -C examples lint-examples`
+    * For linting just the modulegen: `make -C modulegen lint`
+* verify all tests are passing. Build and test the project with `make test-all` to do this.
+    * For a given module or example, go to the module or example directory and run `make test`.
+    * If you find an `ld warning` message on MacOS, you can ignore it. It is a indeed a warning: https://github.com/golang/go/issues/61229
+> === Errors
+> ld: warning: '/private/var/folders/3y/8hbf585d4yl6f8j5yzqx6wz80000gn/T/go-link-2319589277/000018.o' has malformed LC_DYSYMTAB, expected 98 undefined symbols to start at index 1626, found 95 undefined symbols starting at index 1626
+
+* when updating the `go.mod` file, please run `make tidy-all` to ensure all modules are updated.
+
+## Documentation contributions
+
+The _Testcontainers for Go_ documentation is a static site built with [MkDocs](https://www.mkdocs.org/).
+We use the [Material for MkDocs](https://squidfunk.github.io/mkdocs-material/) theme, which offers a number of useful extensions to MkDocs.
+
+We publish our documentation using Netlify.
+
+### Adding code snippets
+
+To include code snippets in the documentation, we use the [codeinclude plugin](https://github.com/rnorth/mkdocs-codeinclude-plugin), which uses the following syntax:
+
+> &lt;!--codeinclude--&gt;<br/>
+> &#91;Human readable title for snippet&#93;(./relative_path_to_example_code.go) targeting_expression<br/>
+> &#91;Human readable title for snippet&#93;(./relative_path_to_example_code.go) targeting_expression<br/>
+> &lt;!--/codeinclude--&gt;<br/>
+
+Where each title snippet in the same `codeinclude` block would represent a new tab
+in the snippet, and each `targeting_expression` would be:
+
+- `block:someString` or
+- `inside_block:someString`
+
+Please refer to the [codeinclude plugin documentation](https://github.com/rnorth/mkdocs-codeinclude-plugin) for more information.
+
+### Previewing rendered content
+
+#### Using Python locally
+
+From the root directory of the repository, you can use the following command to build and serve the documentation locally:
+
+```shell
+make serve-docs
+```
+
+It will use a Python's virtual environment to install the required dependencies and start a local server at `http://localhost:8000`.
+
+Once finished, you can destroy the virtual environment with the following command:
+
+```shell
+make clean-docs
+```
+
+#### PR Preview deployments
+
+Note that documentation for pull requests will automatically be published by Netlify as 'deploy previews'.
+These deployment previews can be accessed via the `deploy/netlify` check that appears for each pull request.
+
+Please check the Github comment Netlify posts on the PR for the URL to the deployment preview.

docs/features/creating_container.md

@@ -106,8 +106,8 @@ _Testcontainers for Go_ allows you to define your own lifecycle hooks for better
 
 You'll be able to pass multiple lifecycle hooks at the `ContainerRequest` as an array of `testcontainers.ContainerLifecycleHooks`. The `testcontainers.ContainerLifecycleHooks` struct defines the following lifecycle hooks, each of them backed by an array of functions representing the hooks:
 
-* `PreBuilds` - hooks that are executed before the container is built
-* `PostBuilds` - hooks that are executed after the container is built
+* `PreBuilds` - hooks that are executed before the image is built. This hook is only available when creating a container from a Dockerfile
+* `PostBuilds` - hooks that are executed after the image is built. This hook is only available when creating a container from a Dockerfile
 * `PreCreates` - hooks that are executed before the container is created
 * `PostCreates` - hooks that are executed after the container is created
 * `PreStarts` - hooks that are executed before the container is started

docs/features/wait/introduction.md

@@ -15,6 +15,7 @@ Below you can find a list of the available wait strategies that you can use:
 - [Log](./log.md)
 - [Multi](./multi.md)
 - [SQL](./sql.md)
+- [TLS](./tls.md)
 
 ## Startup timeout and Poll interval
 
@@ -25,3 +26,8 @@ If the default 60s timeout is not sufficient, it can be updated with the `WithSt
 Besides that, it's possible to define a poll interval, which will actually stop 100 milliseconds the test execution.
 
 If the default 100 milliseconds poll interval is not sufficient, it can be updated with the `WithPollInterval(pollInterval time.Duration)` function.
+
+## Modifying request strategies
+
+It's possible for options to modify `ContainerRequest.WaitingFor` using
+[Walk](walk.md).

docs/features/wait/tls.md

@@ -0,0 +1,31 @@
+# TLS Strategy
+
+TLS Strategy waits for one or more files to exist in the container and uses them
+and other details to construct a `tls.Config` which can be used to create secure
+connections.
+
+It supports:
+
+- x509 PEM Certificate loaded from a certificate / key file pair.
+- Root Certificate Authorities aka RootCAs loaded from PEM encoded files.
+- Server name.
+- Startup timeout to be used in seconds, default is 60 seconds.
+- Poll interval to be used in milliseconds, default is 100 milliseconds.
+
+## Waiting for certificate pair
+
+The following snippets show how to configure a request to wait for certificate
+pair to exist once started and then read the
+[tls.Config](https://pkg.go.dev/crypto/tls#Config), alongside how to copy a test
+certificate pair into a container image using a `Dockerfile`.
+
+It should be noted that copying certificate pairs into an images is only an
+example which might be useful for testing with testcontainers-go and should not
+be done with production images as that could expose your certificates if your
+images become public.
+
+<!--codeinclude-->
+[Wait for certificate](../../../wait/tls_test.go) inside_block:waitForTLSCert
+[Read TLS Config](../../../wait/tls_test.go) inside_block:waitTLSConfig
+[Dockerfile with certificate](../../../wait/testdata/http/Dockerfile)
+<!--/codeinclude-->

docs/features/wait/walk.md

@@ -0,0 +1,19 @@
+# Walk
+
+Walk walks the strategies tree and calls the visit function for each node.
+
+This allows modules to easily amend default wait strategies, updating or
+removing specific strategies based on requirements of functional options.
+
+For example removing a TLS strategy if a functional option enabled insecure mode
+or changing the location of the certificate based on the configured user.
+
+If visit function returns `wait.VisitStop`, the walk stops.
+If visit function returns `wait.VisitRemove`, the current node is removed.
+
+## Walk removing entries
+
+The following example shows how to remove a strategy based on its type.
+<!--codeinclude-->
+[Remove FileStrategy entries](../../../wait/walk_test.go) inside_block:walkRemoveFileStrategy
+<!--/codeinclude-->

docs/modules/localstack.md

@@ -103,6 +103,7 @@ For further reference on the SDK v1, please check out the AWS docs [here](https:
 ### Using the AWS SDK v2
 
 <!--codeinclude-->
+[EndpointResolver](../../modules/localstack/v2/s3_test.go) inside_block:awsResolverV2
 [AWS SDK v2](../../modules/localstack/v2/s3_test.go) inside_block:awsSDKClientV2
 <!--/codeinclude-->