feat: convert pulsar example into a Go module

.github/dependabot.yml

@@ -66,12 +66,6 @@ updates:
         interval: monthly
       open-pull-requests-limit: 3
       rebase-strategy: disabled
-    - package-ecosystem: gomod
-      directory: /examples/pulsar
-      schedule:
-        interval: monthly
-      open-pull-requests-limit: 3
-      rebase-strategy: disabled
     - package-ecosystem: gomod
       directory: /examples/redis
       schedule:
@@ -108,3 +102,9 @@ updates:
         interval: monthly
       open-pull-requests-limit: 3
       rebase-strategy: disabled
+    - package-ecosystem: gomod
+      directory: /modules/pulsar
+      schedule:
+        interval: monthly
+      open-pull-requests-limit: 3
+      rebase-strategy: disabled

.github/workflows/pulsar-example.yml → .github/workflows/module-pulsar.yml

@@ -1,4 +1,4 @@
-name: Pulsar example pipeline
+name: Pulsar module pipeline
 
 on: [push, pull_request]
 
@@ -24,15 +24,15 @@ jobs:
         uses: actions/checkout@v3
 
       - name: modVerify
-        working-directory: ./examples/pulsar
+        working-directory: ./modules/pulsar
         run: go mod verify
 
       - name: modTidy
-        working-directory: ./examples/pulsar
+        working-directory: ./modules/pulsar
         run: make tools-tidy
 
       - name: gotestsum
-        working-directory: ./examples/pulsar
+        working-directory: ./modules/pulsar
         run: make test-unit
 
       - name: Run checker

docs/modules/pulsar.md

@@ -0,0 +1,96 @@
+# Apache Pulsar
+
+Testcontainers can be used to automatically create [Apache Pulsar](https://pulsar.apache.org) containers without external services.
+
+It's based on the official Apache Pulsar docker image, so it is recommended to read the [official guide](https://pulsar.apache.org/docs/next/getting-started-docker/).
+
+## Adding this module to your project dependencies
+
+Please run the following command to add the LocalStack module to your Go dependencies:
+
+```
+go get github.com/testcontainers/testcontainers-go/modules/pulsar
+```
+
+## Usage example
+
+Create a `Pulsar` container to use it in your tests:
+
+<!--codeinclude-->
+[Creating a Pulsar container](../../modules/pulsar/pulsar_test.go) inside_block:startPulsarContainer
+<!--/codeinclude-->
+
+where the `tt.opts` are the options to configure the container. See the [Container Options](#container-options) section for more details.
+
+Then you can retrieve the broker and the admin url:
+
+<!--codeinclude-->
+[Get broker and admin urls](../../modules/pulsar/pulsar_test.go) inside_block:getPulsarURLs
+<!--/codeinclude-->
+
+## Container Options
+
+When starting the Pulsar container, you can pass options in a variadic way to configure it.
+
+### Pulsar Image
+If you need to set a different Pulsar image you can use the `WithPulsarImage`.
+
+<!--codeinclude-->
+[Set Pulsar image](../../modules/pulsar/pulsar_test.go) inside_block:setPulsarImage
+<!--/codeinclude-->
+
+### Pulsar Configuration
+If you need to set Pulsar configuration variables you can use the `WithPulsarEnv` to set Pulsar environment variables: the `PULSAR_PREFIX_` prefix will be automatically added for you.
+
+For example, if you want to enable `brokerDeduplicationEnabled`:
+
+<!--codeinclude-->
+[Set configuration variables](../../modules/pulsar/pulsar_test.go) inside_block:addPulsarEnv
+<!--/codeinclude-->
+
+It will result in the `PULSAR_PREFIX_brokerDeduplicationEnabled=true` environment variable being set in the container request.
+
+### Pulsar IO
+
+If you need to test Pulsar IO framework you can enable the Pulsar Functions Worker with the `WithFunctionsWorker` option:
+
+<!--codeinclude-->
+[Create a Pulsar container with functions worker](../../modules/pulsar/pulsar_test.go) inside_block:withFunctionsWorker
+<!--/codeinclude-->
+
+### Pulsar Transactions
+
+If you need to test Pulsar Transactions you can enable the transactions feature:
+
+<!--codeinclude-->
+[Create a Pulsar container with transactions](../../modules/pulsar/pulsar_test.go) inside_block:withTransactions
+<!--/codeinclude-->
+
+### Log consumers
+If you need to collect the logs from the Pulsar container, you can add your own LogConsumer with the `WithLogConsumers` function, which accepts a variadic argument of LogConsumers.
+
+<!--codeinclude-->
+[Adding LogConsumers](../../modules/pulsar/pulsar_test.go) inside_block:withLogConsumers
+<!--/codeinclude-->
+
+An example of a LogConsumer could be the following:
+
+<!--codeinclude-->
+[Example LogConsumer](../../modules/pulsar/pulsar_test.go) inside_block:logConsumerForTesting
+<!--/codeinclude-->
+
+!!!warning
+    You will need to explicitly stop the producer in your tests.
+
+If you want to know more about LogConsumers, please check the [Following Container Logs](../features/follow_logs.md) documentation.
+
+## Advanced configuration
+
+In the case you need a more advanced settings regarding the config, host config and endpoint settings Docker types, you can leverage the modifier functions that are available in
+the ContainerRequest. The Pulsar container exposes a way to interact with those modifiers in a simple manner, using the aforementioned options in the `StartContainer` function:
+
+<!--codeinclude-->
+[Advanced Docker settings](../../modules/pulsar/pulsar_test.go) inside_block:advancedDockerSettings
+<!--/codeinclude-->
+
+Please check out the [Advanced Settings](../features/creating_container.md#advanced-settings) for creating containers documentation.

mkdocs.yml

@@ -50,6 +50,7 @@ nav:
     - Modules:
         - modules/index.md
         - modules/localstack.md
+        - modules/pulsar.md
     - Examples:
         - examples/index.md
         - examples/bigtable.md
@@ -62,7 +63,6 @@ nav:
         - examples/nginx.md
         - examples/postgres.md
         - examples/pubsub.md
-        - examples/pulsar.md
         - examples/redis.md
         - examples/spanner.md
         - examples/toxiproxy.md

examples/pulsar/go.mod → modules/pulsar/go.mod

@@ -1,9 +1,11 @@
-module github.com/testcontainers/testcontainers-go/examples/pulsar
+module github.com/testcontainers/testcontainers-go/modules/pulsar
 
 go 1.18
 
 require (
 	github.com/apache/pulsar-client-go v0.9.0
+	github.com/docker/docker v23.0.0+incompatible
+	github.com/stretchr/testify v1.8.1
 	github.com/testcontainers/testcontainers-go v0.18.0
 	gotest.tools/gotestsum v1.9.0
 )
@@ -23,9 +25,9 @@ require (
 	github.com/cespare/xxhash/v2 v2.1.2 // indirect
 	github.com/containerd/containerd v1.6.18 // indirect
 	github.com/danieljoos/wincred v1.1.2 // indirect
+	github.com/davecgh/go-spew v1.1.1 // indirect
 	github.com/dnephin/pflag v1.0.7 // indirect
 	github.com/docker/distribution v2.8.1+incompatible // indirect
-	github.com/docker/docker v23.0.0+incompatible // indirect
 	github.com/docker/go-connections v0.4.0 // indirect
 	github.com/docker/go-units v0.5.0 // indirect
 	github.com/dvsekhvalnov/jose2go v1.5.0 // indirect
@@ -56,13 +58,13 @@ require (
 	github.com/opencontainers/runc v1.1.3 // indirect
 	github.com/pierrec/lz4 v2.0.5+incompatible // indirect
 	github.com/pkg/errors v0.9.1 // indirect
+	github.com/pmezard/go-difflib v1.0.0 // indirect
 	github.com/prometheus/client_golang v1.12.2 // indirect
 	github.com/prometheus/client_model v0.2.0 // indirect
 	github.com/prometheus/common v0.32.1 // indirect
 	github.com/prometheus/procfs v0.7.3 // indirect
 	github.com/sirupsen/logrus v1.9.0 // indirect
 	github.com/spaolacci/murmur3 v1.1.0 // indirect
-	github.com/stretchr/objx v0.5.0 // indirect
 	go.uber.org/atomic v1.7.0 // indirect
 	golang.org/x/mod v0.6.0-dev.0.20220419223038-86c51ed26bb4 // indirect
 	golang.org/x/net v0.7.0 // indirect
@@ -75,5 +77,6 @@ require (
 	google.golang.org/genproto v0.0.0-20220617124728-180714bec0ad // indirect
 	google.golang.org/grpc v1.47.0 // indirect
 	google.golang.org/protobuf v1.28.0 // indirect
+	gopkg.in/yaml.v3 v3.0.1 // indirect
 	gotest.tools/v3 v3.4.0 // indirect
 )

examples/pulsar/go.sum → modules/pulsar/go.sum

@@ -439,6 +439,7 @@ github.com/stretchr/testify v1.7.0/go.mod h1:6Fq8oRcR53rry900zMqJjRRixrwX3KX962/
 github.com/stretchr/testify v1.7.1/go.mod h1:6Fq8oRcR53rry900zMqJjRRixrwX3KX962/h/Wwjteg=
 github.com/stretchr/testify v1.8.0/go.mod h1:yNjHg4UonilssWZ8iaSj1OCr/vHnekPRkoO+kdMU+MU=
 github.com/stretchr/testify v1.8.1 h1:w7B6lhMri9wdJUVmEZPGGhZzrYTPvgJArz7wNPgYKsk=
+github.com/stretchr/testify v1.8.1/go.mod h1:w2LPCIKwWwSfY2zedu0+kehJoqGctiVI29o6fzry7u4=
 github.com/subosito/gotenv v1.2.0/go.mod h1:N0PQaV/YGNqwC0u51sEeR/aUtSLEXKX9iv69rRypqCw=
 github.com/syndtr/gocapability v0.0.0-20200815063812-42c35b437635/go.mod h1:hkRG7XYTFWNJGYcbNJQlaLq0fg1yr4J4t/NcTQtrfww=
 github.com/urfave/cli v1.22.1/go.mod h1:Gos4lmkARVdJ6EkW0WaNv/tZAAMe9V7XWyB60NtXRu0=