feat(mysql): move DSN to env var override with percent-encoding (Bug 1)

Phase 3 fix from issue torrust#410.

- Add percent-encoding = "2.0" to Cargo.toml
- TrackerServiceConfig: add optional database_path field (Some for MySQL, None
  for SQLite) with serde skip_serializing_if so it only appears in template
  context for MySQL
- EnvContext::new_with_mysql: percent-encode username and password using a custom
  USERINFO_ENCODE AsciiSet (encodes @, :, /, #, ?, %, + but NOT unreserved chars
  like _ so tracker_user stays tracker_user, not tracker%5Fuser)
- Build full MySQL DSN and store in tracker.database_path
- EnvContext::new_with_mysql: add mysql_host (String) and mysql_port (u16) params
  so the DSN can be constructed without needing domain types at the infra layer
- templates/docker-compose/.env.tera: add
  TORRUST_TRACKER_CONFIG_OVERRIDE_CORE__DATABASE__PATH inside the Tracker Service
  Configuration section (inside {%- if mysql %} block); move before MySQL section
- templates/docker-compose/docker-compose.yml.tera: inject the new env var into
  the tracker service environment section, conditionally on {%- if mysql %}
- templates/tracker/tracker.toml.tera: remove mysql path = line; replace with a
  comment explaining the env var override (no Tera tag needed — comment is static)
- TrackerContext: remove MysqlTemplateConfig struct and mysql field entirely; the
  MySQL case only needs database_driver = mysql now
- Add tests: percent-encoded DSN, alphanumeric DSN, database_path None for SQLite
- Update project_generator.rs test: hardcoded template updated and assertions
  changed to confirm driver = mysql and absence of path/password lines
- Update issue doc: mark all Phase 1-4 items [x]; add Phase 5 status note
- 2314 tests pass

Author: josecelano

Cargo.toml

@@ -50,6 +50,7 @@ clap = { version = "4.0", features = [ "derive" ] }
 derive_more = { version = "2.1", features = [ "display", "from" ] }
 figment = { version = "0.10", features = [ "json" ] }
 parking_lot = "0.12"
+percent-encoding = "2.0"
 rand = "0.9"
 reqwest = "0.12"
 rust-embed = "8.0"

docs/issues/410-bug-multiple-mysql-configuration-issues.md

@@ -35,14 +35,14 @@ value.
 
 ### Bug 1 — DSN in `tracker.toml`
 
-- [ ] Move the MySQL DSN out of `tracker.toml` and into an environment variable override,
+- [x] Move the MySQL DSN out of `tracker.toml` and into an environment variable override,
       consistent with `TORRUST_TRACKER_CONFIG_OVERRIDE_CORE__DATABASE__DRIVER` and
       `TORRUST_TRACKER_CONFIG_OVERRIDE_HTTP_API__ACCESS_TOKENS__ADMIN`
-- [ ] Build the percent-encoded DSN in Rust and expose it in the `.env` file as
+- [x] Build the percent-encoded DSN in Rust and expose it in the `.env` file as
       `TORRUST_TRACKER_CONFIG_OVERRIDE_CORE__DATABASE__PATH`
-- [ ] Pass the new env var into the tracker container via `docker-compose.yml.tera`
-- [ ] Remove the raw DSN line from `tracker.toml.tera` for the MySQL case
-- [ ] Remove the now-unused `MysqlTemplateConfig` from `TrackerContext`
+- [x] Pass the new env var into the tracker container via `docker-compose.yml.tera`
+- [x] Remove the raw DSN line from `tracker.toml.tera` for the MySQL case
+- [x] Remove the now-unused `MysqlTemplateConfig` from `TrackerContext`
 
 ### Bug 2 — Root password not configurable
 
@@ -55,8 +55,8 @@ value.
 
 ### Bug 3 — Reserved username not rejected
 
-- [ ] Add a `ReservedUsername` variant to `MysqlConfigError`
-- [ ] Reject `"root"` as the app DB username in `MysqlConfig::new()` with a clear,
+- [x] Add a `ReservedUsername` variant to `MysqlConfigError`
+- [x] Reject `"root"` as the app DB username in `MysqlConfig::new()` with a clear,
       actionable error message
 
 ## Specifications
@@ -285,37 +285,39 @@ Tasks are ordered from simplest to most complex.
 
 ### Phase 3: Move DSN to env var override and add URL-encoding (Bug 1)
 
-- [ ] Add `percent-encoding` to `Cargo.toml`
-- [ ] `TrackerServiceConfig` (`env/context.rs`): add optional database path field
-- [ ] `EnvContext::new_with_mysql`: percent-encode username and password with
-      `utf8_percent_encode(..., NON_ALPHANUMERIC)`, build the full DSN string, store in
-      the new field
-- [ ] `TrackerContext` (`tracker_config/context.rs`): remove `MysqlTemplateConfig` and
+- [x] Add `percent-encoding` to `Cargo.toml`
+- [x] `TrackerServiceConfig` (`env/context.rs`): add optional database path field
+- [x] `EnvContext::new_with_mysql`: percent-encode username and password with
+      `utf8_percent_encode(..., USERINFO_ENCODE)` (custom AsciiSet preserving RFC 3986
+      unreserved chars), build the full DSN string, store in the new field
+- [x] `TrackerContext` (`tracker_config/context.rs`): remove `MysqlTemplateConfig` and
       the MySQL branch that builds it
-- [ ] `templates/docker-compose/.env.tera`: add
-      `TORRUST_TRACKER_CONFIG_OVERRIDE_CORE__DATABASE__PATH` inside `{%- if mysql %}`
-- [ ] `templates/docker-compose/docker-compose.yml.tera`: inject the new env var into
-      the tracker service `environment:` section, conditionally on
-      `{%- if database.mysql %}`
-- [ ] `templates/tracker/tracker.toml.tera`: remove the MySQL `path =` line; add a
+- [x] `templates/docker-compose/.env.tera`: add
+      `TORRUST_TRACKER_CONFIG_OVERRIDE_CORE__DATABASE__PATH` inside `{%- if mysql %}`,
+      placed in the Tracker Service Configuration section
+- [x] `templates/docker-compose/docker-compose.yml.tera`: inject the new env var into
+      the tracker service `environment:` section, conditionally on `{%- if mysql %}`
+- [x] `templates/tracker/tracker.toml.tera`: remove the MySQL `path =` line; add a
       comment explaining that the connection path is injected via the env var override
 
 ### Phase 4: Tests
 
-- [ ] `mysql.rs`: add `it_should_reject_root_as_username` unit test (Phase 1)
-- [ ] `env/context.rs`: add test that `new_with_mysql` produces a correctly
+- [x] `mysql.rs`: add `it_should_reject_root_as_username` unit test (Phase 1)
+- [x] `env/context.rs`: add test that `new_with_mysql` produces a correctly
       percent-encoded DSN for a password containing special characters
-- [ ] `env/context.rs`: add test that `new` (SQLite) leaves the database path field as
+- [x] `env/context.rs`: add test that `new` (SQLite) leaves the database path field as
       `None`
-- [ ] `tracker_config/context.rs`: remove or update the test that referenced
+- [x] `tracker_config/context.rs`: remove or update the test that referenced
       `mysql_password` on `MysqlTemplateConfig`
-- [ ] Run `cargo test` to verify all tests pass
+- [x] Run `cargo test` to verify all tests pass (2314 passed)
 
 ### Phase 5: Linting and pre-commit
 
 - [ ] Run linters: `cargo run --bin linter all`
 - [ ] Run pre-commit: `./scripts/pre-commit.sh`
 
+> **Status**: Phases 1–4 complete and committed. Phase 5 pending.
+
 ## Acceptance Criteria
 
 > **Note for Contributors**: These criteria define what the PR reviewer will check.
@@ -328,10 +330,10 @@ Tasks are ordered from simplest to most complex.
 
 **Task-Specific Criteria — Bug 3 (reserved username)**:
 
-- [ ] `MysqlConfig::new()` returns `Err(MysqlConfigError::ReservedUsername)` when
+- [x] `MysqlConfig::new()` returns `Err(MysqlConfigError::ReservedUsername)` when
       username is `"root"`
-- [ ] `MysqlConfigError::ReservedUsername` has a `help()` message with an actionable fix
-- [ ] A unit test for the reserved username rejection exists and passes
+- [x] `MysqlConfigError::ReservedUsername` has a `help()` message with an actionable fix
+- [x] A unit test for the reserved username rejection exists and passes
 
 **Task-Specific Criteria — Bug 2 (root password)**:
 
@@ -349,20 +351,20 @@ Tasks are ordered from simplest to most complex.
 
 **Task-Specific Criteria — Bug 1 (DSN in tracker.toml)**:
 
-- [ ] The rendered `tracker.toml` for a MySQL deployment does **not** contain the
+- [x] The rendered `tracker.toml` for a MySQL deployment does **not** contain the
       database password
-- [ ] The rendered `.env` file contains
+- [x] The rendered `.env` file contains
       `TORRUST_TRACKER_CONFIG_OVERRIDE_CORE__DATABASE__PATH` with a correctly
       percent-encoded DSN when MySQL is configured
-- [ ] The rendered `.env` file does **not** contain
+- [x] The rendered `.env` file does **not** contain
       `TORRUST_TRACKER_CONFIG_OVERRIDE_CORE__DATABASE__PATH` when SQLite is configured
-- [ ] The rendered `docker-compose.yml` injects
+- [x] The rendered `docker-compose.yml` injects
       `TORRUST_TRACKER_CONFIG_OVERRIDE_CORE__DATABASE__PATH` into the tracker service
       environment when MySQL is configured
-- [ ] A MySQL password containing URL-reserved characters (e.g. `@`, `+`, `/`) produces
-      a valid, correctly encoded DSN in the `.env` file
-- [ ] A MySQL password with only alphanumeric characters is rendered unchanged
-- [ ] `MysqlTemplateConfig` no longer exists in `tracker_config/context.rs`
+- [x] A MySQL password containing URL-reserved characters (e.g. `@`, `+`, `/`) produces
+      a valid, correctly encoded DSN in the `.env` file (verified with `tracker_p@ss!word#1`)
+- [x] A MySQL password with only alphanumeric characters is rendered unchanged
+- [x] `MysqlTemplateConfig` no longer exists in `tracker_config/context.rs`
 - [ ] `cargo machete` reports no unused dependencies
 
 ## Manual E2E Verification Test

src/application/services/rendering/docker_compose.rs

@@ -107,6 +107,7 @@ impl DockerComposeTemplateRenderingService {
             DatabaseConfig::Mysql(mysql_config) => self.create_mysql_contexts(
                 admin_token.to_string(),
                 tracker,
+                mysql_config.host().to_string(),
                 mysql_config.port(),
                 mysql_config.database_name().to_string(),
                 mysql_config.username().to_string(),
@@ -214,6 +215,7 @@ impl DockerComposeTemplateRenderingService {
         &self,
         admin_token: String,
         tracker: TrackerServiceContext,
+        host: String,
         port: u16,
         database_name: String,
         username: String,
@@ -228,6 +230,8 @@ impl DockerComposeTemplateRenderingService {
             database_name.clone(),
             username.clone(),
             password.clone(),
+            host,
+            port,
         );
 
         let mysql_config = MysqlSetupConfig {

src/infrastructure/templating/docker_compose/template/wrappers/env/context.rs

@@ -7,10 +7,34 @@
 //! - Tracker service configuration
 //! - `MySQL` service configuration (optional)
 
+use percent_encoding::{utf8_percent_encode, AsciiSet, CONTROLS};
 use serde::Serialize;
 
 use crate::infrastructure::templating::TemplateMetadata;
 
+/// Characters that must be percent-encoded in the userinfo (user/password) part of a MySQL DSN URL.
+///
+/// Encodes delimiters that have structural meaning in the URL authority component:
+/// - `@` — userinfo/host separator
+/// - `:` — user/password separator in the DSN
+/// - `/` — path separator
+/// - `#` — fragment delimiter
+/// - `?` — query delimiter
+/// - `%` — percent-encoding prefix (must itself be encoded)
+/// - `+` — interpreted as space in some URL parsers
+///
+/// Unreserved characters per RFC 3986 (`-`, `_`, `.`, `~`) and ASCII alphanumerics
+/// are NOT encoded, so common usernames like `tracker_user` remain readable.
+const USERINFO_ENCODE: AsciiSet = CONTROLS
+    .add(b' ')
+    .add(b':')
+    .add(b'@')
+    .add(b'/')
+    .add(b'#')
+    .add(b'?')
+    .add(b'%')
+    .add(b'+');
+
 /// Configuration for the Tracker service
 ///
 /// Contains environment variables for the Torrust Tracker container.
@@ -21,6 +45,13 @@ pub struct TrackerServiceConfig {
     /// Database driver type ("sqlite3" or "mysql")
     /// Controls which config template the container entrypoint uses
     pub database_driver: String,
+    /// Percent-encoded MySQL DSN for `TORRUST_TRACKER_CONFIG_OVERRIDE_CORE__DATABASE__PATH`
+    ///
+    /// Only populated when MySQL is configured; `None` for SQLite.
+    /// Username and password are percent-encoded with `NON_ALPHANUMERIC` to handle
+    /// URL-reserved characters (e.g. `@`, `+`, `/`, `:`).
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub database_path: Option<String>,
 }
 
 /// Configuration for the `MySQL` service
@@ -105,6 +136,7 @@ impl EnvContext {
             tracker: TrackerServiceConfig {
                 api_admin_token: tracker_api_admin_token,
                 database_driver: "sqlite3".to_string(),
+                database_path: None,
             },
             mysql: None,
             grafana: None,
@@ -119,8 +151,10 @@ impl EnvContext {
     /// * `tracker_api_admin_token` - The admin token for tracker API authentication
     /// * `mysql_root_password` - `MySQL` root password
     /// * `mysql_database` - `MySQL` database name
-    /// * `mysql_user` - `MySQL` user
-    /// * `mysql_password` - `MySQL` password
+    /// * `mysql_user` - `MySQL` username (percent-encoded in the DSN)
+    /// * `mysql_password` - `MySQL` password (percent-encoded in the DSN)
+    /// * `mysql_host` - `MySQL` host (e.g. `"mysql"`, `"localhost"`)
+    /// * `mysql_port` - `MySQL` port (typically `3306`)
     ///
     /// # Examples
     ///
@@ -137,6 +171,8 @@ impl EnvContext {
     ///     "tracker_db".to_string(),
     ///     "tracker_user".to_string(),
     ///     "user_pass".to_string(),
+    ///     "mysql".to_string(),
+    ///     3306,
     /// );
     /// assert_eq!(context.tracker.database_driver, "mysql");
     /// assert!(context.mysql.is_some());
@@ -149,12 +185,20 @@ impl EnvContext {
         mysql_database: String,
         mysql_user: String,
         mysql_password: String,
+        mysql_host: String,
+        mysql_port: u16,
     ) -> Self {
+        let encoded_user = utf8_percent_encode(&mysql_user, &USERINFO_ENCODE).to_string();
+        let encoded_password = utf8_percent_encode(&mysql_password, &USERINFO_ENCODE).to_string();
+        let database_path = format!(
+            "mysql://{encoded_user}:{encoded_password}@{mysql_host}:{mysql_port}/{mysql_database}"
+        );
         Self {
             metadata,
             tracker: TrackerServiceConfig {
                 api_admin_token: tracker_api_admin_token,
                 database_driver: "mysql".to_string(),
+                database_path: Some(database_path),
             },
             mysql: Some(MySqlServiceConfig {
                 root_password: mysql_root_password,
@@ -277,6 +321,8 @@ mod tests {
             "tracker_db".to_string(),
             "tracker_user".to_string(),
             "user_pass".to_string(),
+            "mysql".to_string(),
+            3306,
         );
 
         assert_eq!(context.tracker.api_admin_token, "AdminToken456");
@@ -312,6 +358,8 @@ mod tests {
             "db".to_string(),
             "user".to_string(),
             "pass".to_string(),
+            "mysql".to_string(),
+            3306,
         );
 
         let serialized = serde_json::to_string(&context).unwrap();
@@ -339,6 +387,8 @@ mod tests {
             "tracker_db".to_string(),
             "tracker_user".to_string(),
             "user_pass".to_string(),
+            "mysql".to_string(),
+            3306,
         );
 
         // Backward compatible getter methods
@@ -349,4 +399,58 @@ mod tests {
         assert_eq!(context.mysql_user(), Some("tracker_user"));
         assert_eq!(context.mysql_password(), Some("user_pass"));
     }
+
+    #[test]
+    fn it_should_produce_percent_encoded_dsn_for_password_with_special_chars() {
+        let metadata = create_test_metadata();
+        // password contains URL-reserved characters: @ : / +
+        let context = EnvContext::new_with_mysql(
+            metadata,
+            "Token123".to_string(),
+            "root_pass".to_string(),
+            "tracker".to_string(),
+            "tracker_user".to_string(),
+            "p@ss:w/ord+1".to_string(),
+            "mysql".to_string(),
+            3306,
+        );
+
+        let database_path = context.tracker.database_path.as_deref().unwrap();
+        // @ -> %40, : -> %3A, / -> %2F, + -> %2B
+        // _ in username is NOT encoded (unreserved per RFC 3986)
+        assert_eq!(
+            database_path,
+            "mysql://tracker_user:p%40ss%3Aw%2Ford%2B1@mysql:3306/tracker"
+        );
+    }
+
+    #[test]
+    fn it_should_produce_unencoded_dsn_for_alphanumeric_password() {
+        let metadata = create_test_metadata();
+        let context = EnvContext::new_with_mysql(
+            metadata,
+            "Token123".to_string(),
+            "root_pass".to_string(),
+            "tracker".to_string(),
+            "tracker_user".to_string(),
+            "plainpassword123".to_string(),
+            "mysql".to_string(),
+            3306,
+        );
+
+        let database_path = context.tracker.database_path.as_deref().unwrap();
+        // Alphanumeric password and underscore username are not encoded
+        assert_eq!(
+            database_path,
+            "mysql://tracker_user:plainpassword123@mysql:3306/tracker"
+        );
+    }
+
+    #[test]
+    fn it_should_leave_database_path_none_for_sqlite() {
+        let metadata = create_test_metadata();
+        let context = EnvContext::new(metadata, "Token123".to_string());
+
+        assert!(context.tracker.database_path.is_none());
+    }
 }

src/infrastructure/templating/tracker/template/renderer/project_generator.rs

@@ -316,9 +316,10 @@ mod tests {
             .expect("Failed to read tracker.toml");
 
         assert!(content.contains(r#"driver = "mysql""#));
-        assert!(
-            content.contains("path = \"mysql://tracker_user:secure_pass@mysql:3306/tracker_db\"")
-        );
+        // DSN is no longer in tracker.toml — it is injected via
+        // TORRUST_TRACKER_CONFIG_OVERRIDE_CORE__DATABASE__PATH in .env
+        assert!(!content.contains("path = \"mysql://"));
+        assert!(!content.contains("secure_pass"));
     }
 
     #[test]
@@ -401,7 +402,7 @@ driver = "{{ database_driver }}"
 {% if database_driver == "sqlite3" %}
 path = "/var/lib/torrust/tracker/database/{{ tracker_database_name }}"
 {% elif database_driver == "mysql" %}
-path = "mysql://{{ mysql_user }}:{{ mysql_password }}@{{ mysql_host }}:{{ mysql_port }}/{{ mysql_database }}"
+{# DSN is injected via TORRUST_TRACKER_CONFIG_OVERRIDE_CORE__DATABASE__PATH in .env #}
 {% endif %}
 
 {% for udp_tracker in udp_trackers %}