feat(atlaslocal): add MongoDB Atlas Local module

docs/modules/mongodb-atlaslocal.md

@@ -0,0 +1,188 @@
+# MongoDB Atlas Local
+
+Not available until the next release <a href="https://github.com/testcontainers/testcontainers-go"><span class="tc-version">:material-tag: main</span></a>
+
+## Introduction
+
+The MongoDB Atlas Local module for Testcontainers lets you spin up a local MongoDB Atlas instance in Docker using
+[mongodb/mongodb-atlas-local](https://hub.docker.com/r/mongodb/mongodb-atlas-local) for integration tests and
+development. This module supports SCRAM authentication, init scripts, and custom log file mounting.
+
+This module differs from the standard modules/mongodb Testcontainers module, allowing users to spin up a full local
+Atlas-like environment complete with Atlas Search and Atlas Vector Search.
+
+## Adding this module to your project dependencies
+
+Please run the following command to add the MongoDB Atlas Local module to your Go dependencies:
+
+```
+go get github.com/testcontainers/testcontainers-go/modules/mongodb/atlaslocal
+```
+
+## Usage example
+
+<!--codeinclude-->
+[Creating a MongoDB Atlas Local container](../../modules/mongodb/atlaslocal/examples_test.go) inside_block:runMongoDBAtlasLocalContainer
+<!--/codeinclude-->
+
+## Module Reference
+
+### Run function
+
+- Not available until the next release <a href="https://github.com/testcontainers/testcontainers-go"><span class="tc-version">:material-tag: main</span></a>
+
+The `atlaslocal` module exposes one entrypoint function to create the MongoDB Atlas Local container, and this
+function receives three parameters:
+
+```golang
+func Run(ctx context.Context, img string, opts ...testcontainers.ContainerCustomizer) (*Container, error)
+```
+
+- `context.Context`, the Go context.
+- `string`, the Docker image to use.
+- `testcontainers.ContainerCustomizer`, a variadic argument for passing options.
+
+#### Image
+
+Use the second argument in the `Run` function to set a valid Docker image.
+In example: `Run(context.Background(), "mongodb/mongodb-atlas-local:latest")`.
+
+### Container Options
+
+When starting the MongoDB Atlas Local container, you can pass options in a variadic way to configure it.
+
+#### WithUsername
+
+- Not available until the next release <a href="https://github.com/testcontainers/testcontainers-go"><span class="tc-version">:material-tag: main</span></a>
+
+This functional option sets the initial username to be created when the container starts, populating the
+`MONGODB_INITDB_ROOT_USERNAME` environment variable. You cannot mix this option with `WithUsernameFile`, as it will
+result in an error.
+
+#### WithPassword
+
+- Not available until the next release <a href="https://github.com/testcontainers/testcontainers-go"><span class="tc-version">:material-tag: main</span></a>
+
+This functional option sets the initial password to be created when the container starts, populating the
+`MONGODB_INITDB_ROOT_PASSWORD` environment variable. You cannot mix this option with `WithPasswordFile`, as it will
+result in an error.
+
+#### WithUsernameFile
+
+- Not available until the next release <a href="https://github.com/testcontainers/testcontainers-go"><span class="tc-version">:material-tag: main</span></a>
+
+This functional option mounts a local file as the MongoDB root username secret at `/run/secrets/mongo-root-username`
+and sets the `MONGODB_INITDB_ROOT_USERNAME_FILE` environment variable. The path must be absolute and exist; no-op if
+empty.
+
+#### WithPasswordFile
+
+- Not available until the next release <a href="https://github.com/testcontainers/testcontainers-go"><span class="tc-version">:material-tag: main</span></a>
+
+This functional option mounts a local file as the MongoDB root password secret at `/run/secrets/mongo-root-password` and
+sets the `MONGODB_INITDB_ROOT_PASSWORD_FILE` environment variable. The path must be absolute and exist; no-op if empty.
+
+#### WithNoTelemetry
+
+- Not available until the next release <a href="https://github.com/testcontainers/testcontainers-go"><span class="tc-version">:material-tag: main</span></a>
+
+This functional option disables the telemetry feature of MongoDB Atlas Local, setting the `DO_NOT_TRACK` environment
+variable to `1`.
+
+#### WithInitDatabase
+
+- Not available until the next release <a href="https://github.com/testcontainers/testcontainers-go"><span class="tc-version">:material-tag: main</span></a>
+
+This functional option allows you to specify a database name to be initialized when the container starts, populating
+the `MONGODB_INITDB_DATABASE` environment variable.
+
+#### WithInitScripts
+
+- Not available until the next release <a href="https://github.com/testcontainers/testcontainers-go"><span class="tc-version">:material-tag: main</span></a>
+
+Mounts a directory into `/docker-entrypoint-initdb.d`, running `.sh`/`.js` scripts on startup. Calling this function
+multiple times mounts only the latest directory.
+
+#### WithMongotLogFile
+
+- Not available until the next release <a href="https://github.com/testcontainers/testcontainers-go"><span class="tc-version">:material-tag: main</span></a>
+
+This functional option writes the mongot logs to `/tmp/mongot.log` inside the container. See
+`(*Container).ReadMongotLogs` to read the logs locally.
+
+#### WithMongotLogToStdout
+
+- Not available until the next release <a href="https://github.com/testcontainers/testcontainers-go"><span class="tc-version">:material-tag: main</span></a>
+
+This functional option writes the mongot logs to `/dev/stdout` inside the container. See
+`(*Container).ReadMongotLogs` to read the logs locally.
+
+#### WithMongotLogToStderr
+
+- Not available until the next release <a href="https://github.com/testcontainers/testcontainers-go"><span class="tc-version">:material-tag: main</span></a>
+
+This functional option writes the mongot logs to `/dev/stderr` inside the container. See
+`(*Container).ReadMongotLogs` to read the logs locally.
+
+#### WithRunnerLogFile
+
+- Not available until the next release <a href="https://github.com/testcontainers/testcontainers-go"><span class="tc-version">:material-tag: main</span></a>
+
+This functional option writes the runner logs to `/tmp/runner.log` inside the container. See
+`(*Container).ReadRunnerLogs` to read the logs locally.
+
+#### WithRunnerLogToStdout
+
+- Not available until the next release <a href="https://github.com/testcontainers/testcontainers-go"><span class="tc-version">:material-tag: main</span></a>
+
+This functional option writes the runner logs to `/dev/stdout` inside the container. See
+`(*Container).ReadRunnerLogs` to read the logs locally.
+
+#### WithRunnerLogToStderr
+
+- Not available until the next release <a href="https://github.com/testcontainers/testcontainers-go"><span class="tc-version">:material-tag: main</span></a>
+
+This functional option writes the runner logs to `/dev/stderr` inside the container. See
+`(*Container).ReadRunnerLogs` to read the logs locally.
+
+{% include "../features/common_functional_options_list.md" %}
+
+### Container Methods
+
+The MongoDB Atlas Local container exposes the following methods:
+
+
+#### ConnectionString
+
+- Not available until the next release <a href="https://github.com/testcontainers/testcontainers-go"><span class="tc-version">:material-tag: main</span></a>
+
+The `ConnectionString` method returns the connection string to connect to the MongoDB Atlas Local container.
+It returns a string with the format `mongodb://<host>:<port>[/<db>]/?directConnection=true[&authSource=admin]`.
+
+It can be used to configure a MongoDB client (`go.mongodb.org/mongo-driver/v2/mongo`), e.g.:
+
+<!--codeinclude-->
+[Using ConnectionString with the MongoDB client](../../modules/mongodb/atlaslocal/examples_test.go) inside_block:connectToMongo
+<!--/codeinclude-->
+
+#### ReadMongotLogs
+
+- Not available until the next release <a href="https://github.com/testcontainers/testcontainers-go"><span class="tc-version">:material-tag: main</span></a>
+
+The `ReadMongotLogs` returns a reader for the log solution specified when constructing the container.
+
+
+<!--codeinclude-->
+[Using ReadMongotLogs with the MongoDB client](../../modules/mongodb/atlaslocal/examples_test.go) inside_block:mongotLogsRead
+<!--/codeinclude-->
+
+#### ReadRunnerLogs
+
+- Not available until the next release <a href="https://github.com/testcontainers/testcontainers-go"><span class="tc-version">:material-tag: main</span></a>
+
+The `ReadRunnerLogs` returns a reader for the log solution specified when constructing the container.
+
+
+<!--codeinclude-->
+[Using ReadRunnerLogs with the MongoDB client](../../modules/mongodb/atlaslocal/examples_test.go) inside_block:runnerLogsRead
+<!--/codeinclude-->

mkdocs.yml

@@ -100,6 +100,7 @@ nav:
         - modules/milvus.md
         - modules/minio.md
         - modules/mockserver.md
+        - modules/mongodb-atlaslocal.md
         - modules/mongodb.md
         - modules/mssql.md
         - modules/mysql.md

modules/mongodb/atlaslocal/atlaslocal.go

@@ -0,0 +1,144 @@
+package atlaslocal
+
+import (
+	"context"
+	"fmt"
+	"io"
+	"net/url"
+	"os"
+
+	"github.com/testcontainers/testcontainers-go"
+	"github.com/testcontainers/testcontainers-go/wait"
+)
+
+const defaultPort = "27017/tcp"
+
+// Container represents the MongoDBAtlasLocal container type used in the module.
+type Container struct {
+	testcontainers.Container
+	userOpts options
+}
+
+// Run creates an instance of the MongoDBAtlasLocal container type.
+func Run(ctx context.Context, img string, opts ...testcontainers.ContainerCustomizer) (*Container, error) {
+	userOpts := options{}
+	for _, opt := range opts {
+		if apply, ok := opt.(Option); ok {
+			if err := apply(&userOpts); err != nil {
+				return nil, fmt.Errorf("apply option: %w", err)
+			}
+		}
+	}
+
+	if err := userOpts.validate(); err != nil {
+		return nil, fmt.Errorf("validate options: %w", err)
+	}
+
+	moduleOpts := []testcontainers.ContainerCustomizer{ // Set the defaults
+		testcontainers.WithExposedPorts(defaultPort),
+		testcontainers.WithWaitStrategy(wait.ForAll(wait.ForListeningPort(defaultPort), wait.ForHealthCheck())),
+		testcontainers.WithEnv(userOpts.env()),
+		testcontainers.WithFiles(userOpts.files...),
+	}
+
+	moduleOpts = append(moduleOpts, opts...)
+
+	container, err := testcontainers.Run(ctx, img, moduleOpts...)
+	var c *Container
+	if container != nil {
+		c = &Container{Container: container, userOpts: userOpts}
+	}
+
+	if err != nil {
+		return c, fmt.Errorf("run container: %w", err)
+	}
+
+	return c, nil
+}
+
+// ConnectionString returns the connection string for the MongoDB Atlas Local
+// container. If you provide a username and a password, the connection string
+// will also include them.
+func (ctr *Container) ConnectionString(ctx context.Context) (string, error) {
+	endpoint, err := ctr.PortEndpoint(ctx, defaultPort, "")
+	if err != nil {
+		return "", fmt.Errorf("port endpoint: %w", err)
+	}
+
+	uri := &url.URL{
+		Scheme: "mongodb",
+		Host:   endpoint,
+		Path:   "/",
+	}
+
+	// If MONGODB_INITDB_DATABASE is set, use it as the default database in the
+	// connection string.
+	if db := ctr.userOpts.database; db != "" {
+		uri.Path, err = url.JoinPath("/", db)
+		if err != nil {
+			return "", fmt.Errorf("join path: %w", err)
+		}
+	}
+
+	user, err := ctr.userOpts.parseUsername()
+	if err != nil {
+		return "", fmt.Errorf("parse username: %w", err)
+	}
+
+	password, err := ctr.userOpts.parsePassword()
+	if err != nil {
+		return "", fmt.Errorf("parse password: %w", err)
+	}
+
+	if user != "" && password != "" {
+		uri.User = url.UserPassword(user, password)
+	}
+
+	q := uri.Query()
+	q.Set("directConnection", "true")
+	if user != "" && password != "" {
+		q.Set("authSource", "admin")
+	}
+
+	uri.RawQuery = q.Encode()
+
+	return uri.String(), nil
+}
+
+// ReadMongotLogs returns a reader for mongot logs in the container. Reads from
+// stdout/stderr or /tmp/mongot.log if configured.
+//
+// This method return the os.ErrNotExist sentinel error if it is called with
+// no log file configured.
+func (ctr *Container) ReadMongotLogs(ctx context.Context) (io.ReadCloser, error) {
+	path := ctr.userOpts.mongotLogPath
+	if path == "" {
+		return nil, os.ErrNotExist
+	}
+
+	switch path {
+	case "/dev/stdout", "/dev/stderr":
+		return ctr.Logs(ctx)
+	default:
+		return ctr.CopyFileFromContainer(ctx, path)
+	}
+}
+
+// ReadRunnerLogs() returns a reader for runner logs in the container. Reads
+// from stdout/stderr or /tmp/runner.log if configured.
+//
+// This method return the os.ErrNotExist sentinel error if it is called with
+// no log file configured.
+func (ctr *Container) ReadRunnerLogs(ctx context.Context) (io.ReadCloser, error) {
+	path := ctr.userOpts.runnerLogPath
+	if path == "" {
+		return nil, os.ErrNotExist
+	}
+
+	switch path {
+	case "/dev/stdout", "/dev/stderr":
+		return ctr.Logs(ctx)
+	default:
+		return ctr.CopyFileFromContainer(ctx, path)
+	}
+}