refactor

- make bracket handling clearer
- improve field docs
- remove assert! as it is fine to not serialise everything in alternative forms.
  That's what canonical serialisation is there for.
- prefer strip instead of indexed operation

Author: Byron

gix-url/src/lib.rs

@@ -113,17 +113,39 @@ pub struct Url {
     /// The URL scheme.
     pub scheme: Scheme,
     /// The user to impersonate on the remote.
+    ///
+    /// Stored in decoded form: percent-encoded characters are decoded during parsing.
+    /// Re-encoded during canonical serialization, but written as-is in alternative form.
     pub user: Option<String>,
     /// The password associated with a user.
+    ///
+    /// Stored in decoded form: percent-encoded characters are decoded during parsing.
+    /// Re-encoded during canonical serialization. Cannot be serialized in alternative form (will panic in debug builds).
     pub password: Option<String>,
     /// The host to which to connect. Localhost is implied if `None`.
+    ///
+    /// IPv6 addresses are stored *without* brackets for SSH schemes, but *with* brackets for other schemes.
+    /// Brackets are automatically added during serialization when needed (e.g., when a port is specified with an IPv6 host).
     pub host: Option<String>,
     /// When serializing, use the alternative forms as it was parsed as such.
+    ///
+    /// Alternative forms include SCP-like syntax (`user@host:path`) and bare file paths.
+    /// When `true`, password and port cannot be serialized (will panic in debug builds).
     pub serialize_alternative_form: bool,
     /// The port to use when connecting to a host. If `None`, standard ports depending on `scheme` will be used.
     pub port: Option<u16>,
     /// The path portion of the URL, usually the location of the git repository.
     ///
+    /// Unlike `user` and `password`, paths are stored and serialized in their original form
+    /// without percent-decoding or re-encoding (e.g., `%20` remains `%20`, not converted to space).
+    ///
+    /// Path normalization during parsing:
+    /// - SSH/Git schemes: Leading `/~` is stripped (e.g., `/~repo` becomes `~repo`)
+    /// - SSH/Git schemes: Empty paths are rejected as errors
+    /// - HTTP/HTTPS schemes: Empty paths are normalized to `/`
+    ///
+    /// During serialization, SSH/Git URLs prepend `/` to paths not starting with `/`.
+    ///
     /// # Security Warning
     ///
     /// URLs allow paths to start with `-` which makes it possible to mask command-line arguments as path which then leads to
@@ -381,7 +403,7 @@ impl Url {
         out.write_all(self.scheme.as_str().as_bytes())?;
         out.write_all(b"://")?;
 
-        let needs_brackets = self.port.is_some() && self.host.as_ref().is_some_and(|h| Self::is_ipv6(h));
+        let needs_brackets = self.port.is_some() && self.host_needs_brackets();
 
         match (&self.user, &self.host) {
             (Some(user), Some(host)) => {
@@ -427,20 +449,19 @@ impl Url {
         Ok(())
     }
 
-    fn is_ipv6(host: &str) -> bool {
-        host.contains(':') && !host.starts_with('[')
+    fn host_needs_brackets(&self) -> bool {
+        fn is_ipv6(h: &str) -> bool {
+            h.contains(':') && !h.starts_with('[')
+        }
+        self.host.as_ref().is_some_and(|h| is_ipv6(h))
     }
 
     fn write_alternative_form_to(&self, out: &mut dyn std::io::Write) -> std::io::Result<()> {
-        let needs_brackets = self.host.as_ref().is_some_and(|h| Self::is_ipv6(h));
+        let needs_brackets = self.host_needs_brackets();
 
         match (&self.user, &self.host) {
             (Some(user), Some(host)) => {
                 out.write_all(user.as_bytes())?;
-                assert!(
-                    self.password.is_none(),
-                    "BUG: cannot serialize password in alternative form"
-                );
                 out.write_all(b"@")?;
                 if needs_brackets {
                     out.write_all(b"[")?;
@@ -466,7 +487,6 @@ impl Url {
                 ));
             }
         }
-        assert!(self.port.is_none(), "BUG: cannot serialize port in alternative form");
         if self.scheme == Scheme::Ssh {
             out.write_all(b":")?;
         }

gix-url/src/parse.rs

@@ -145,32 +145,29 @@ pub(crate) fn url(input: &BStr, protocol_end: usize) -> Result<crate::Url, Error
     // For SSH URLs, strip brackets from IPv6 addresses
     let host = if scheme == Scheme::Ssh {
         url.host.map(|mut h| {
-            // Check if we have bracketed IPv6 with trailing colon: "[::1]:"
-            if h.starts_with('[') {
-                if h.ends_with("]:") {
-                    // "[::1]:" -> "::1"  (strip brackets and colon)
-                    h = h[1..h.len() - 2].to_string();
-                } else if h.ends_with(']') {
-                    // "[::1]" -> "::1"  (just strip brackets)
-                    h = h[1..h.len() - 1].to_string();
+            // Bracketed IPv6 forms
+            if let Some(h2) = h.strip_prefix('[') {
+                if let Some(inner) = h2.strip_suffix("]:") {
+                    // "[::1]:" → "::1"
+                    h = inner.to_string();
+                } else if let Some(inner) = h2.strip_suffix(']') {
+                    // "[::1]" → "::1"
+                    h = inner.to_string();
                 }
             } else {
-                // For non-bracketed hosts, only strip trailing colon if it's not part of IPv6
-                // Count colons: if there's only one colon and it's at the end, strip it
-                // Otherwise (multiple colons or colon not at end), keep it
-                let colon_count = h.chars().filter(|&c| c == ':').count();
-                if colon_count == 1 && h.ends_with(':') {
-                    // Regular host with empty port "host:" -> "host"
-                    h = h[..h.len() - 1].to_string();
+                // Non-bracketed host: strip a single trailing colon
+                let colon_count = h.chars().filter(|&c| c == ':').take(2).count();
+                if colon_count == 1 {
+                    if let Some(inner) = h.strip_suffix(':') {
+                        h = inner.to_string();
+                    }
                 }
-                // For bare IPv6 with trailing colon "::1:", keep it as is (colon_count > 1)
             }
             h
         })
     } else {
         url.host
     };
-
     Ok(crate::Url {
         serialize_alternative_form: false,
         scheme,
@@ -232,8 +229,8 @@ pub(crate) fn scp(input: &BStr, colon: usize) -> Result<crate::Url, Error> {
 
     // For SCP-like SSH URLs, strip brackets from IPv6 addresses
     let host = url.host.map(|h| {
-        if h.starts_with('[') && h.ends_with(']') {
-            h[1..h.len() - 1].to_string()
+        if let Some(h) = h.strip_prefix("[").and_then(|h| h.strip_suffix("]")) {
+            h.to_string()
         } else {
             h
         }

gix-url/src/simple_url.rs

@@ -64,16 +64,12 @@ impl<'a> ParsedUrl<'a> {
         };
 
         // Parse authority: [user[:password]@]host[:port]
-        let (username, password, host, port) = if let Some(at_pos) = authority.rfind('@') {
+        let (username, password, host, port) = if let Some((user_info, host_port)) = authority.rsplit_once('@') {
             // Has user info
-            let user_info = &authority[..at_pos];
-            let host_port = &authority[at_pos + 1..];
-
-            let (user, pass) = if let Some(colon_pos) = user_info.find(':') {
-                let pass_str = &user_info[colon_pos + 1..];
+            let (user, pass) = if let Some((user, pass_str)) = user_info.split_once(':') {
                 // Treat empty password as None
                 let pass = if pass_str.is_empty() { None } else { Some(pass_str) };
-                (&user_info[..colon_pos], pass)
+                (user, pass)
             } else {
                 (user_info, None)
             };
@@ -145,10 +141,7 @@ impl<'a> ParsedUrl<'a> {
 
         // Handle regular host:port
         // Use rfind to find the last colon
-        if let Some(colon_pos) = host_port.rfind(':') {
-            let before_last_colon = &host_port[..colon_pos];
-            let after_last_colon = &host_port[colon_pos + 1..];
-
+        if let Some((before_last_colon, after_last_colon)) = host_port.rsplit_once(':') {
             // Check if this looks like a port (all digits after colon)
             // But avoid treating IPv6 addresses as host:port
             // IPv6 addresses have colons in the part before the last colon (e.g., "::1" has "::" before the last ":")

gix-url/tests/url/baseline.rs

@@ -43,10 +43,7 @@ fn parse_and_compare_baseline_urls() {
     println!(
         "\nBaseline tests: {passed}/{total} passed, {failed} failed, {expected_failures} expected failures (skipped)"
     );
-
-    if failed > 0 {
-        panic!("{failed} baseline test(s) failed");
-    }
+    assert_eq!(failed, 0, "{failed} baseline test(s) failed");
 }
 
 fn assert_urls_equal(expected: &baseline::GitDiagUrl<'_>, actual: &gix_url::Url) {