Merge branch 'main' into session-ids

* main: chore: define interfaces for file and project generation (testcontainers#1568) chore(deps): bump mkdocs-material from 8.2.7 to 9.2.6 (testcontainers#1567) chore(deps): bump the all group in /modules/neo4j with 1 update (testcontainers#1562) chore(deps): bump the all group in /modules/clickhouse with 1 update (testcontainers#1563) chore(deps): bump the all group in /modules/localstack with 1 update (testcontainers#1564) Update actions/github-script to 6.4.1 (testcontainers#1561) chore: Update Pipenv to use Python 3.8 (testcontainers#1558) feat: convert NATS example into a module (testcontainers#1559) chore(deps): bump the all group in /modulegen with 1 update (testcontainers#1554) modulegen: use cobra instead of native golang flag (testcontainers#1550)
mdelapenya · Sep 1, 2023 · 3f43bae · 3f43bae
2 parents b0d7e0d + 69a5d38
commit 3f43bae
Show file tree

Hide file tree

Showing 52 changed files with 1,391 additions and 692 deletions.
diff --git a/.github/dependabot.yml b/.github/dependabot.yml
@@ -82,17 +82,6 @@ updates:
         all:
             patterns:
                 - '*'
-    - package-ecosystem: gomod
-      directory: /examples/nats
-      schedule:
-        interval: monthly
-        day: sunday
-      open-pull-requests-limit: 3
-      rebase-strategy: disabled
-      groups:
-        all:
-            patterns:
-                - '*'
     - package-ecosystem: gomod
       directory: /examples/nginx
       schedule:
@@ -247,6 +236,17 @@ updates:
         all:
             patterns:
                 - '*'
+    - package-ecosystem: gomod
+      directory: /modules/nats
+      schedule:
+        interval: monthly
+        day: sunday
+      open-pull-requests-limit: 3
+      rebase-strategy: disabled
+      groups:
+        all:
+            patterns:
+                - '*'
     - package-ecosystem: gomod
       directory: /modules/neo4j
       schedule:

diff --git a/.github/workflows/ci-windows.yml b/.github/workflows/ci-windows.yml
@@ -13,11 +13,11 @@ jobs:
     timeout-minutes: 30
     steps:
       - name: Create pending status
-        uses: actions/github-script@0.9.0
+        uses: actions/github-script@6.4.1
         with:
           github-token: ${{ secrets.GITHUB_TOKEN }}
           script: |
-            github.repos.createStatus({
+            github.rest.repos.createCommitStatus({
               owner: context.repo.owner,
               repo: context.repo.repo,
               sha: context.payload.client_payload.pull_request.head.sha,
@@ -55,12 +55,12 @@ jobs:
           gotestsum --format short-verbose --rerun-fails=5 --packages="./..."  --junitfile TEST-unit.xml -- -timeout=30m
 
       - name: Create success status
-        uses: actions/github-script@0.9.0
+        uses: actions/github-script@6.4.1
         if: success()
         with:
           github-token: ${{secrets.GITHUB_TOKEN}}
           script: |
-            github.repos.createStatus({
+            github.rest.repos.createCommitStatus({
               owner: context.repo.owner,
               repo: context.repo.repo,
               sha: context.payload.client_payload.pull_request.head.sha,
@@ -70,12 +70,12 @@ jobs:
             })
 
       - name: Create failure status
-        uses: actions/github-script@0.9.0
+        uses: actions/github-script@6.4.1
         if: failure()
         with:
           github-token: ${{secrets.GITHUB_TOKEN}}
           script: |
-            github.repos.createStatus({
+            github.rest.repos.createCommitStatus({
               owner: context.repo.owner,
               repo: context.repo.repo,
               sha: context.payload.client_payload.pull_request.head.sha,

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -96,7 +96,7 @@ jobs:
       matrix:
         go-version: [1.20.x, 1.x]
         platform: [ubuntu-latest, macos-latest]
-        module: [artemis, clickhouse, compose, couchbase, k3s, localstack, mariadb, mongodb, mysql, neo4j, postgres, pulsar, redis, redpanda, vault]
+        module: [artemis, clickhouse, compose, couchbase, k3s, localstack, mariadb, mongodb, mysql, nats, neo4j, postgres, pulsar, redis, redpanda, vault]
     uses: ./.github/workflows/ci-test-go.yml
     with:
       go-version: ${{ matrix.go-version }}
@@ -111,7 +111,7 @@ jobs:
     needs: test-modules
     strategy:
       matrix:
-        module: [bigtable, cockroachdb, consul, datastore, firestore, nats, nginx, pubsub, spanner, toxiproxy]
+        module: [bigtable, cockroachdb, consul, datastore, firestore, nginx, pubsub, spanner, toxiproxy]
     uses: ./.github/workflows/ci-test-go.yml
     with:
       go-version: "1.20.x"

diff --git a/.vscode/.testcontainers-go.code-workspace b/.vscode/.testcontainers-go.code-workspace
@@ -25,10 +25,6 @@
             "name": "example / firestore",
             "path": "../examples/firestore"
         },
-        {
-            "name": "example / nats",
-            "path": "../examples/nats"
-        },
         {
             "name": "example / nginx",
             "path": "../examples/nginx"
@@ -81,6 +77,10 @@
             "name": "module / mysql",
             "path": "../modules/mysql"
         },
+        {
+            "name": "module / nats",
+            "path": "../modules/nats"
+        },
         {
             "name": "module / neo4j",
             "path": "../modules/neo4j"

diff --git a/Pipfile b/Pipfile
@@ -6,10 +6,10 @@ verify_ssl = true
 [dev-packages]
 
 [packages]
-mkdocs = "*"
-mkdocs-codeinclude-plugin = "*"
-mkdocs-material = "*"
-mkdocs-markdownextradata-plugin = "*"
+mkdocs = "==1.5.2"
+mkdocs-codeinclude-plugin = "==0.2.1"
+mkdocs-material = "==9.2.6"
+mkdocs-markdownextradata-plugin = "==0.2.5"
 
 [requires]
-python_version = "3.7"
+python_version = "3.8"
diff --git a/Pipfile.lock b/Pipfile.lock
diff --git a/docs/examples/nats.md b/docs/examples/nats.md
diff --git a/docs/modules/index.md b/docs/modules/index.md
@@ -28,12 +28,12 @@ We have provided a command line tool to generate the scaffolding for the code of
 
 ### Command line flags
 
-| Flag       | Type   | Required | Description                                                                                                                                                    |
-|------------|--------|----------|----------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| -name      | string | Yes      | Name of the module, use camel-case when needed. Only alphanumerical characters are allowed (leading character must be a letter).                               |
-| -image     | string | Yes      | Fully-qualified name of the Docker image to be used by the module (i.e. 'docker.io/org/project:tag')                                                           |
-| -title     | string | No       | A variant of the name supporting mixed casing (i.e. 'MongoDB'). Only alphanumerical characters are allowed (leading character must be a letter).               |
-| -as-module | bool   | No       | If set, the module will be generated as a Go module, under the modules directory. Otherwise, it will be generated as a subdirectory of the examples directory. |
+| Flag    | Short | Type   | Required | Description                                                                                                                                      |
+|---------|-------|--------|----------|--------------------------------------------------------------------------------------------------------------------------------------------------|
+| --name  | -n    | string | Yes      | Name of the module, use camel-case when needed. Only alphanumerical characters are allowed (leading character must be a letter).                 |
+| --image | -i    | string | Yes      | Fully-qualified name of the Docker image to be used by the module (i.e. 'docker.io/org/project:tag')                                             |
+| --title | -t    | string | No       | A variant of the name supporting mixed casing (i.e. 'MongoDB'). Only alphanumerical characters are allowed (leading character must be a letter). |
+
 
 ### What is this tool not doing?
 
@@ -45,13 +45,13 @@ We have provided a command line tool to generate the scaffolding for the code of
 From the [`modulegen` directory]({{repo_url}}/tree/main/modulegen), please run:
 
 ```shell
-go run . --name ${NAME_OF_YOUR_MODULE} --image "${REGISTRY}/${MODULE}:${TAG}" --title ${TITLE_OF_YOUR_MODULE}
+go run . new example --name ${NAME_OF_YOUR_MODULE} --image "${REGISTRY}/${MODULE}:${TAG}" --title ${TITLE_OF_YOUR_MODULE}
 ```
 
 or for creating a Go module:
 
 ```shell
-go run . --name ${NAME_OF_YOUR_MODULE} --image "${REGISTRY}/${MODULE}:${TAG}" --title ${TITLE_OF_YOUR_MODULE} --as-module
+go run . new module --name ${NAME_OF_YOUR_MODULE} --image "${REGISTRY}/${MODULE}:${TAG}" --title ${TITLE_OF_YOUR_MODULE}
 ```
 
 ### Adding types and methods to the module

diff --git a/docs/modules/nats.md b/docs/modules/nats.md
@@ -0,0 +1,89 @@
+# NATS
+
+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>
+
+## Introduction
+
+The Testcontainers module for NATS.
+
+## Adding this module to your project dependencies
+
+Please run the following command to add the NATS module to your Go dependencies:
+
+```
+go get github.com/testcontainers/testcontainers-go/modules/nats
+```
+
+## Usage example
+
+<!--codeinclude-->
+[Creating a NATS container](../../modules/nats/nats_test.go) inside_block:createNATSContainer
+<!--/codeinclude-->
+
+## Module reference
+
+The NATS module exposes one entrypoint function to create the NATS container, and this function receives two parameters:
+
+```golang
+func RunContainer(ctx context.Context, opts ...testcontainers.ContainerCustomizer) (*NATSContainer, error)
+```
+
+- `context.Context`, the Go context.
+- `testcontainers.ContainerCustomizer`, a variadic argument for passing options.
+
+### Container Options
+
+When starting the NATS container, you can pass options in a variadic way to configure it.
+
+#### Image
+
+If you need to set a different NATS Docker image, you can use `testcontainers.WithImage` with a valid Docker image
+for NATS. E.g. `testcontainers.WithImage("nats:2.9")`.
+
+#### Wait Strategies
+
+If you need to set a different wait strategy for NATS, you can use `testcontainers.WithWaitStrategy` with a valid wait strategy
+for NATS.
+
+!!!info
+    The default deadline for the wait strategy is 60 seconds.
+
+At the same time, it's possible to set a wait strategy and a custom deadline with `testcontainers.WithWaitStrategyAndDeadline`.
+
+#### Docker type modifiers
+
+If you need an advanced configuration for NATS, you can leverage the following Docker type modifiers:
+
+- `testcontainers.WithConfigModifier`
+- `testcontainers.WithHostConfigModifier`
+- `testcontainers.WithEndpointSettingsModifier`
+
+Please read the [Create containers: Advanced Settings](../features/creating_container.md#advanced-settings) documentation for more information.
+
+#### Set username and password
+
+If you need to set different credentials, you can use `WithUsername` and `WithPassword`
+options.  By default, the username, the password are not set.
+
+<!--codeinclude-->
+[Define NATS container with credentials](../../modules/nats/nats_test.go) inside_block:withCredentials
+<!--/codeinclude-->
+
+To establish the connection with the NATS container:
+
+<!--codeinclude-->
+[Connect using the credentials](../../modules/nats/nats_test.go) inside_block:connectWithCredentials
+<!--/codeinclude-->
+
+### Container Methods
+
+The NATS container exposes the following methods:
+
+#### ConnectionString
+
+This method returns the connection string to connect to the NATS container, using the default `4222` port.
+It's possible to pass extra parameters to the connection string, in a variadic way.
+
+<!--codeinclude-->
+[Get connection string](../../modules/nats/nats_test.go) inside_block:connectionString
+<!--/codeinclude-->
diff --git a/examples/nats/nats.go b/examples/nats/nats.go
diff --git a/mkdocs.yml b/mkdocs.yml
@@ -69,6 +69,7 @@ nav:
         - modules/mariadb.md
         - modules/mongodb.md
         - modules/mysql.md
+        - modules/nats.md
         - modules/neo4j.md
         - modules/postgres.md
         - modules/pulsar.md
@@ -82,7 +83,6 @@ nav:
         - examples/consul.md
         - examples/datastore.md
         - examples/firestore.md
-        - examples/nats.md
         - examples/nginx.md
         - examples/pubsub.md
         - examples/spanner.md

diff --git a/modulegen/cmd/modules/example.go b/modulegen/cmd/modules/example.go
@@ -0,0 +1,25 @@
+package modules
+
+import (
+	"github.com/spf13/cobra"
+
+	"github.com/testcontainers/testcontainers-go/modulegen/internal"
+)
+
+var newExampleCmd = &cobra.Command{
+	Use:   "example",
+	Short: "Create a new Example",
+	Long:  "Create a new Example",
+	RunE: func(cmd *cobra.Command, args []string) error {
+		return internal.Generate(tcModuleVar, false)
+	},
+}
+
+func init() {
+	newExampleCmd.Flags().StringVarP(&tcModuleVar.Name, nameFlag, "n", "", "Name of the example. Only alphabetical characters are allowed.")
+	newExampleCmd.Flags().StringVarP(&tcModuleVar.NameTitle, titleFlag, "t", "", "(Optional) Title of the example name, used to override the name in the case of mixed casing (Mongodb -> MongoDB). Use camel-case when needed. Only alphabetical characters are allowed.")
+	newExampleCmd.Flags().StringVarP(&tcModuleVar.Image, imageFlag, "i", "", "Fully-qualified name of the Docker image to be used by the example")
+
+	_ = newExampleCmd.MarkFlagRequired(imageFlag)
+	_ = newExampleCmd.MarkFlagRequired(nameFlag)
+}
diff --git a/modulegen/cmd/modules/flags.go b/modulegen/cmd/modules/flags.go
@@ -0,0 +1,7 @@
+package modules
+
+const (
+	imageFlag = "image"
+	nameFlag  = "name"
+	titleFlag = "title"
+)