modules: align the module API surface for 0.2.0 (audit group A)

Uniform pass-through matrix across all seven modules: Redis gains
env/label/network(x2)/alias/reuse/startup_timeout/startup_attempts,
Kafka gains with_label, RabbitMQ and MongoDB gain with_env + with_label.
Env ownership is guarded where append-order cannot protect it: Redis
rejects with_env REDISCLI_AUTH alongside a password at render (the key
is read by exec'd redis-cli, where the FIRST duplicate wins) and
MongoDB rejects MONGO_INITDB_ROOT_* (keyfile requirement under
--replSet).

Command-arg spelling unified: with_command_arg (single) /
with_command_args (batch) on Redis and the MySQL family. PostgreSQL's
connection_string(scheme) split into connection_string() +
connection_string_with_scheme() - a string argument to
connection_string(...) now always means the database (MongoDB), never
the scheme. with_startup_timeout is a per-phase budget everywhere:
MongoDB's PRIMARY poll derives from it (chunked ~15s execs; the hook's
steady_clock deadline is the one authority - the buffered exec runs
with the transport deadline disabled) instead of a fixed ~20s cap. New
umbrella header testcontainers/modules.hpp, compile-checked by the
Redis unit TU.

Pipeline: MSVC 559 units, live module suite 34/34, WSL gcc 553 units,
clang-tidy and clang-format clean. Opus review applied: the mongo
chunking rationale misattributed the safety to the transport idle
deadline; reworded in code and feature-notes.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0141x8KrNdD9NfmCh1vSMbpg

Author: cppudge

docs/feature-notes.md

@@ -428,7 +428,16 @@ module: `with_customizer(fn)` queues a callback over the underlying `GenericImag
 render time AFTER the module's own rendering (what it sets wins — the same precedence idea
 as `with_create_body_patch` over typed fields), and `to_generic()` renders the full config
 into a plain `GenericImage` for when a raw `Container` is wanted. Each module documents the
-small surface it owns (cmd/env keys); everything else passes through untouched. Opt-in by
+small surface it owns (cmd/env keys); everything else passes through untouched. Aligned in
+the pre-0.2.0 audit pass (2026-07-12): every module surfaces the same curated pass-through
+set — env / label / network (name or `Network`) / network-alias / reuse / startup-timeout /
+startup-attempts; `with_startup_timeout` is a PER-PHASE budget (one phase for most modules;
+Kafka and MongoDB run a second, hook-driven phase with a fresh allowance of the same size);
+command-line arguments use one spelling pair wherever they apply (`with_command_arg` single
+/ `with_command_args` batch — Redis and the MySQL family); and a string argument to
+`connection_string(...)` always means the DATABASE (MongoDB) — scheme variants get their
+own name (PostgreSQL's `connection_string_with_scheme`). `testcontainers/modules.hpp` is
+the modules umbrella header (compile-checked by the Redis unit TU). Opt-in by
 include + link: headers under `include/testcontainers/modules/`, target
 `testcontainers::modules` — the one spelling that means the same thing on both consumption
 paths. Around it the paths differ: the plain-CMake install exports
@@ -450,10 +459,14 @@ wait (a log wait races the listener; a raw TCP probe false-positives through Doc
 Desktop's host proxy). `with_password` renders `{"redis-server","--requirepass",pw}` AND
 sets container-level `REDISCLI_AUTH`, so the unchanged probe — and any `redis-cli` the user
 execs — authenticates automatically (honored by redis-cli ≥ 4.0.10; the pin is far past
-it). `with_command_args` appends server arguments after `--requirepass`; argv[0] stays
+it). `with_command_arg[s]` append server arguments after `--requirepass`; argv[0] stays
 `redis-server` so the official entrypoint's protected-mode handling keeps applying. The
 module owns the container command (iff a password or args are set) and the `REDISCLI_AUTH`
-env key — nothing else. `connection_string(db = 0)` renders
+env key — nothing else. The env key is guarded, not just documented: `with_env` carrying
+REDISCLI_AUTH alongside a password throws at render — the key is read by EXEC'D redis-cli,
+where the FIRST duplicate of a key wins, so the append-last ordering that protects the DB
+modules' bash-read credential keys could not make the module's entry win here.
+`connection_string(db = 0)` renders
 `redis://[:pass@]host:port[/db]`; database selection is client-side in Redis, so there is
 no server-side database setter. Known limits: a config FILE must be the first server
 argument, so a config file combined with `with_password` is unsupported (drop to a
@@ -481,7 +494,8 @@ executable (a non-executable .sh is *sourced* into the entrypoint's shell, where
 editing a script changes the reuse hash). `with_config_option` renders `postgres -c k=v`;
 `with_wait` REPLACES the default probe (a customizer-added wait runs in addition).
 `StartedPostgreSQL` adds `conninfo()` (libpq keyword/value with its quoting rules; the
-password keyword omitted when empty) beside the URI `connection_string(scheme)`, and
+password keyword omitted when empty) beside the URI `connection_string()` /
+`connection_string_with_scheme()`, and
 `exec_sql()` through the in-container psql (`-X -tA`, local-socket trust — no password).
 Curated pass-throughs (env / label / network / alias / reuse / timeout / attempts) forward
 to the embedded builder; everything else rides `with_customizer`.
@@ -508,7 +522,7 @@ names). 500ms poll (each attempt is a fresh exec connection; 200ms is churn agai
 measured in tens of seconds). Init scripts and `.cnf` drop-ins reuse the PostgreSQL
 staging rules (NNNN- registration-order prefix, extension whitelist, .sh 0755;
 `/etc/mysql/conf.d` names must end in .cnf — the include glob skips others silently).
-`with_command_arg` values become the container cmd verbatim (the entrypoints forward
+`with_command_arg[s]` values become the container cmd verbatim (the entrypoints forward
 '-'-prefixed args to the server binary). Both `connection_string()`s emit the **mysql://**
 scheme — MariaDB speaks the MySQL wire protocol and URL-parsing clients widely reject
 "mariadb://"; `root_password()` documents the root≡user invariant at call sites. Known
@@ -593,16 +607,21 @@ set (`--replSet rs0 --bind_ip_all`): transactions and change streams are why the
 exists, a standalone rejects both, and the whole cost is a ~1–2s election on top of the
 boot. There is deliberately no standalone mode and no auth surface — MongoDB requires a
 cluster keyfile the moment auth meets a replica set, so MONGO_INITDB_ROOT_* is a
-boot-breaker under --replSet (the header warns customizer users off it; initdb.d scripts
-are equally unsupported — they trigger a temporary double-start whose log line would
-release the wait early). Boot choreography: log wait "Waiting for connections" (exact 4.4+
-casing; appears exactly once since nothing triggers the initdb phase) → listening_port
-(proves the HOST side of the mapping) → a started hook that execs `rs.initiate({_id, 
-members: [{_id: 0, host: '127.0.0.1:27017'}]})` (deterministic self-check member address;
-AlreadyInitialized tolerated for pre-initiated volumes and reuse) and then polls
-`db.hello().isWritablePrimary` in-shell (200×100ms ≈ 20s cap) — the PRIMARY wait cannot be
-a wait strategy because waits run before hooks, i.e. before rs.initiate exists. THE DSN
-decision: `connection_string()` emits
+boot-breaker under --replSet (`with_env` rejects both root keys at render; the header
+warns customizer users off them; initdb.d scripts are equally unsupported — they trigger
+a temporary double-start whose log line would release the wait early). Boot choreography:
+log wait "Waiting for connections" (exact 4.4+ casing; appears exactly once since nothing
+triggers the initdb phase) → listening_port (proves the HOST side of the mapping) → a
+started hook that execs `rs.initiate({_id, members: [{_id: 0, host:
+'127.0.0.1:27017'}]})` (deterministic self-check member address; AlreadyInitialized
+tolerated for pre-initiated volumes and reuse) and then polls
+`db.hello().isWritablePrimary` in-shell on 100ms ticks under a fresh phase budget (the
+configured startup timeout — the same per-phase contract as Kafka's two-phase boot),
+chunked into execs of ~15s so the wall-clock phase deadline is re-evaluated between
+chunks and a transiently failing mongosh retries (the buffered exec itself runs with the
+transport deadline disabled — the hook's steady_clock deadline is the one authority) —
+the PRIMARY wait cannot be a wait strategy because waits run before hooks, i.e. before
+rs.initiate exists. THE DSN decision: `connection_string()` emits
 `mongodb://host:port/<db>?directConnection=true` and NEVER `replicaSet=` —
 direct mode pins single-server behavior in every spec-compliant driver instead of relying
 on per-driver legacy defaults (the "works in tc-java, ServerSelectionTimeoutError in

docs/public-api-test-coverage.md

@@ -332,15 +332,18 @@ three has a Windows-mode test (file modes and privileged exec are Unix concepts
 Module images are Linux-only, so the Windows columns are n/a by construction —
 the `tc_module_tests` exe runs on the Windows CI job solely to prove the engine
 guards self-skip. Rendering rules (cmd/env ownership, customizer precedence,
-idempotence) are unit-tested per module via `to_generic()`.
+idempotence) are unit-tested per module via `to_generic()`. The modules umbrella
+header (`testcontainers/modules.hpp`) is compile-checked by the Redis unit TU,
+which includes it in place of the individual header.
 
 | Function | Works on Linux | Works on Windows | Integration-tested (Linux) | Integration-tested (Windows) |
 |---|---|---|---|---|
 | `GenericImage::with_image` (core setter) | ✅ | ✅ | ❌ (unit-tested: GenericImage.WithImageReplacesReferenceKeepingOptions; every module `with_image` uses it) | ❌ |
 | `RedisContainer()` defaults + `start()` | ✅ | n/a (Linux image) | ✅ RedisModule.StartsServesAndBuildsDsn | n/a |
 | `RedisContainer::with_image` | ✅ | n/a | ❌ (unit-tested: RedisModuleConfig.WithImageRewritesReference) | n/a |
 | `RedisContainer::with_password` | ✅ | n/a | ✅ RedisModule.PasswordIsEnforcedAndWired | n/a |
-| `RedisContainer::with_command_args` | ✅ | n/a | ✅ RedisModule.CommandArgsReachTheServer | n/a |
+| `RedisContainer::with_command_arg[s]` | ✅ | n/a | ✅ RedisModule.CommandArgsReachTheServer (batch form; single twin unit-tested: RedisModuleConfig.CommandArgSingleTwinAccumulates) | n/a |
+| `RedisContainer` pass-throughs (env/label/network/alias/reuse/timeout/attempts) | ✅ | n/a | ❌ (unit-tested: RedisModuleConfig.PassThroughsLandOnTheImage, RedisModuleConfig.ManagedAuthEnvConflictThrowsAtRender; thin forwards to core setters, each integration-tested under GenericImage above) | n/a |
 | `RedisContainer::with_customizer` | ✅ | n/a | ❌ (unit-tested: RedisModuleConfig.CustomizerRunsLastAndWins — pure rendering, no daemon interaction of its own) | n/a |
 | `RedisContainer::to_generic` | ✅ | n/a | ❌ (unit-tested: RedisModuleConfig.* — `start()` goes through it) | n/a |
 | `StartedRedis::host` / `port` / `connection_string` / `password` | ✅ | n/a | ✅ RedisModule.StartsServesAndBuildsDsn, RedisModule.PasswordIsEnforcedAndWired | n/a |
@@ -353,12 +356,12 @@ idempotence) are unit-tested per module via `to_generic()`.
 | `PostgreSQLContainer::with_wait` / `with_env` | ✅ | n/a | ❌ (unit-tested: PostgreSQLModuleConfig.CustomWaitReplacesDefaultProbe, PostgreSQLModuleConfig.CredentialTrioAppendedLastWinsOverRawEnv) | n/a |
 | `PostgreSQLContainer` other pass-throughs (label/network/alias/timeout/attempts) | ✅ | n/a | ❌ (thin forwards to core setters, each integration-tested under GenericImage above) | n/a |
 | `PostgreSQLContainer::with_customizer` / `to_generic` | ✅ | n/a | ✅ PostgreSQLModule.CustomizerReachesCreateBody | n/a |
-| `StartedPostgreSQL::host` / `port` / `connection_string` / `conninfo` | ✅ | n/a | ✅ PostgreSQLModule.DefaultsStartAndConnect, PostgreSQLModule.HostSidePgHandshake | n/a |
+| `StartedPostgreSQL::host` / `port` / `connection_string[_with_scheme]` / `conninfo` | ✅ | n/a | ✅ PostgreSQLModule.DefaultsStartAndConnect, PostgreSQLModule.HostSidePgHandshake | n/a |
 | `StartedPostgreSQL::exec_sql` | ✅ | n/a | ✅ every PostgreSQLModule test | n/a |
 | `MySQLContainer()` defaults + `start()` | ✅ | n/a | ✅ MySQLModule.DefaultsBootAndConnect | n/a |
 | `MySQLContainer::with_username/password/database` (incl. root modes) | ✅ | n/a | ✅ MySQLModule.CustomCredsAndOrderedInitScripts, MySQLModule.RootOnlyModes | n/a |
 | `MySQLContainer::with_init_script` (host file / in-memory) | ✅ | n/a | ✅ MySQLModule.CustomCredsAndOrderedInitScripts | n/a |
-| `MySQLContainer::with_command_arg` | ✅ | n/a | ✅ MySQLModule.CharsetCommandArg | n/a |
+| `MySQLContainer::with_command_arg[s]` | ✅ | n/a | ✅ MySQLModule.CharsetCommandArg (batch twin unit-tested: MySqlFamilyConfig.CommandArgsBecomeCmd) | n/a |
 | `MySQLContainer::with_config_file` | ✅ | n/a | ❌ (unit-tested staging: MySqlFamilyConfig.InitScriptsAndConfigFilesStageOrderedAndValidated; the copy mechanics are MariaDB-integration-tested — shared core) | n/a |
 | `MariaDBContainer()` defaults + `start()` (healthcheck.sh wait) | ✅ | n/a | ✅ MariaDBModule.DefaultsBootAndConnect | n/a |
 | `MariaDBContainer::with_init_script` / `with_config_file` | ✅ | n/a | ✅ MariaDBModule.InitScriptAndConfigFile | n/a |
@@ -367,7 +370,7 @@ idempotence) are unit-tested per module via `to_generic()`.
 | `KafkaContainer()` defaults + `start()` (two-phase boot) | ✅ | n/a | ✅ KafkaModule.StartsAndExposesBootstrap, KafkaModule.AdvertisedListenersCarryMappedPort (the mapped-port money test), KafkaModule.ProduceConsumeRoundTrip | n/a |
 | `KafkaContainer::with_topic` | ✅ | n/a | ✅ KafkaModule.WithTopicPreCreatesPartitions | n/a |
 | `KafkaContainer::with_network` / `with_network_alias` (advertised internal listener) | ✅ | n/a | ✅ KafkaModule.TwoContainersOverNetwork | n/a |
-| `KafkaContainer::with_env` / `with_cluster_id` / `with_customizer` / `to_generic` + detail helpers | ✅ | n/a | ❌ (unit-tested: KafkaModuleConfig.*, KafkaDetail.* — env order, cluster-id validation, starter script, placeholder command, topics label) | n/a |
+| `KafkaContainer::with_env` / `with_label` / `with_cluster_id` / `with_customizer` / `to_generic` + detail helpers | ✅ | n/a | ❌ (unit-tested: KafkaModuleConfig.*, KafkaDetail.* — env order, label order vs the reserved topics label, cluster-id validation, starter script, placeholder command) | n/a |
 | `StartedKafka` getters (`bootstrap_servers` bare host:port, `internal_bootstrap_servers`, `cluster_id`) | ✅ | n/a | ✅ KafkaModule.StartsAndExposesBootstrap, KafkaModule.TwoContainersOverNetwork | n/a |
 | `RabbitMQContainer()` defaults + `start()` (ordered log→exec readiness) | ✅ | n/a | ✅ RabbitMQModule.DefaultsStartAndUrls | n/a |
 | `RabbitMQContainer::with_username/password/vhost` | ✅ | n/a | ✅ RabbitMQModule.CustomCredentialsAndVhost | n/a |

include/testcontainers/modules.hpp

@@ -0,0 +1,14 @@
+#pragma once
+
+/// Umbrella header for the ecosystem modules (namespace
+/// testcontainers::modules; link testcontainers::modules). The core API has
+/// its own umbrella, testcontainers/testcontainers.hpp — the module headers
+/// pull in only the core pieces they build on.
+
+#include "testcontainers/modules/KafkaContainer.hpp"
+#include "testcontainers/modules/MariaDBContainer.hpp"
+#include "testcontainers/modules/MongoDBContainer.hpp"
+#include "testcontainers/modules/MySQLContainer.hpp"
+#include "testcontainers/modules/PostgreSQLContainer.hpp"
+#include "testcontainers/modules/RabbitMQContainer.hpp"
+#include "testcontainers/modules/RedisContainer.hpp"

include/testcontainers/modules/KafkaContainer.hpp

@@ -79,6 +79,14 @@ class KafkaContainer {
         return *this;
     }
 
+    /// Attach a metadata label. The module's reuse-visibility label
+    /// (`org.testcontainers.kafka.topics`) is applied after these, so it
+    /// wins on a duplicate key.
+    KafkaContainer& with_label(std::string key, std::string value) {
+        image_.with_label(std::move(key), std::move(value));
+        return *this;
+    }
+
     /// Set the KRaft cluster id: 22 characters of URL-safe base64 (a 16-byte
     /// UUID, e.g. from `kafka-storage.sh random-uuid`). Defaults to a fixed
     /// module-wide id, which keeps restarts and container reuse
@@ -145,8 +153,8 @@ class KafkaContainer {
     }
 
     /// Register a callback that customizes the underlying `GenericImage` —
-    /// the channel for options this module does not surface (labels, pull
-    /// policy, mounts, ...). Customizers run when the config is rendered
+    /// the channel for options this module does not surface (pull policy,
+    /// mounts, ...). Customizers run when the config is rendered
     /// (`start()` / `to_generic()`), in registration order, AFTER the
     /// module's own rendering. Caveats: the boot choreography lives in the
     /// rendered command, wait, and started hook — replacing any of them

include/testcontainers/modules/MariaDBContainer.hpp

@@ -7,6 +7,7 @@
 #include <string>
 #include <string_view>
 #include <utility>
+#include <vector>
 
 #include "testcontainers/Container.hpp"
 #include "testcontainers/GenericImage.hpp"
@@ -102,6 +103,15 @@ class MariaDBContainer {
         return *this;
     }
 
+    /// Append several server options at once — the batch twin of
+    /// `with_command_arg`. Repeatable; calls accumulate in order.
+    MariaDBContainer& with_command_args(std::vector<std::string> args) {
+        for (std::string& arg : args) {
+            opts_.command_args.push_back(std::move(arg));
+        }
+        return *this;
+    }
+
     /// Copy a .cnf file into /etc/mysql/conf.d (included by the image's
     /// configuration; the name must end in ".cnf" or this throws). Copied
     /// with mode 0644 — the server ignores world-writable config files.

include/testcontainers/modules/MongoDBContainer.hpp

@@ -77,6 +77,22 @@ class MongoDBContainer {
 
     // --- Pass-throughs to the underlying builder ---
 
+    /// Set an extra environment variable (TZ and friends). Do not set
+    /// MONGO_INITDB_ROOT_USERNAME / MONGO_INITDB_ROOT_PASSWORD here: an
+    /// auth-enabled replica-set member refuses to start without a cluster
+    /// keyfile (see the class note), so `start()` throws up front on either
+    /// key. The other MONGO_INITDB_* keys only affect initdb.d scripts,
+    /// which this module deliberately does not stage.
+    MongoDBContainer& with_env(std::string key, std::string value) {
+        image_.with_env(std::move(key), std::move(value));
+        return *this;
+    }
+
+    MongoDBContainer& with_label(std::string key, std::string value) {
+        image_.with_label(std::move(key), std::move(value));
+        return *this;
+    }
+
     /// Join a user-defined network; peers resolve this container by
     /// name/alias at `<alias>:27017` (kPort, not the mapped host port).
     MongoDBContainer& with_network(std::string network) {
@@ -98,9 +114,11 @@ class MongoDBContainer {
         return *this;
     }
 
-    /// Budget for the container-level readiness phase (default: 60s; the
-    /// replica-set initiation that follows carries its own ~20s cap). Image
-    /// pull time does not count against it.
+    /// Budget for EACH of the two startup phases — the container-level
+    /// readiness wait, and the replica-set initiation (rs.initiate + the
+    /// PRIMARY election poll) that follows it — so the worst-case total is
+    /// about twice this. Default 60s per phase. Image pull time does not
+    /// count against it.
     MongoDBContainer& with_startup_timeout(std::chrono::milliseconds timeout) {
         image_.with_startup_timeout(timeout);
         return *this;
@@ -137,8 +155,9 @@ class MongoDBContainer {
     /// hatch when you need a raw `Container` instead of a StartedMongoDB.
     /// Extend the result, don't rebuild it: replacing the command or the
     /// hooks disables the replica-set choreography. Throws Error on an
-    /// invalid config (a replica-set name outside [A-Za-z0-9_-]) before any
-    /// daemon contact.
+    /// invalid config (a replica-set name outside [A-Za-z0-9_-];
+    /// MONGO_INITDB_ROOT_* env set through with_env) before any daemon
+    /// contact.
     GenericImage to_generic() const;
 
     /// Create and start the container, initiate the replica set, and wait

include/testcontainers/modules/MySQLContainer.hpp

@@ -7,6 +7,7 @@
 #include <string>
 #include <string_view>
 #include <utility>
+#include <vector>
 
 #include "testcontainers/Container.hpp"
 #include "testcontainers/GenericImage.hpp"
@@ -113,6 +114,15 @@ class MySQLContainer {
         return *this;
     }
 
+    /// Append several server options at once — the batch twin of
+    /// `with_command_arg`. Repeatable; calls accumulate in order.
+    MySQLContainer& with_command_args(std::vector<std::string> args) {
+        for (std::string& arg : args) {
+            opts_.command_args.push_back(std::move(arg));
+        }
+        return *this;
+    }
+
     /// Copy a configuration file into /etc/mysql/conf.d, which the image's
     /// my.cnf includes. The file name must end in ".cnf" (the include glob;
     /// anything else throws here). Copied with mode 0644 — the server