feat: add validated Url type (#339)

Author: kingzcheung

cot/Cargo.toml

@@ -64,7 +64,7 @@ tower = { workspace = true, features = ["util"] }
 tower-livereload = { workspace = true, optional = true }
 tower-sessions = { workspace = true, features = ["memory-store"] }
 tracing.workspace = true
-url = { workspace = true, features = ["serde"], optional = true }
+url = { workspace = true, features = ["serde"] }
 
 [dev-dependencies]
 async-stream.workspace = true
@@ -97,7 +97,7 @@ ignored = [
 default = ["sqlite", "postgres", "mysql", "json"]
 full = ["default", "fake", "live-reload", "test"]
 fake = ["dep:fake"]
-db = ["dep:url", "dep:sea-query", "dep:sea-query-binder", "dep:sqlx"]
+db = ["dep:sea-query", "dep:sea-query-binder", "dep:sqlx"]
 sqlite = ["db", "sea-query/backend-sqlite", "sea-query-binder/sqlx-sqlite", "sqlx/sqlite"]
 postgres = ["db", "sea-query/backend-postgres", "sea-query-binder/sqlx-postgres", "sqlx/postgres"]
 mysql = ["db", "sea-query/backend-mysql", "sea-query-binder/sqlx-mysql", "sqlx/mysql"]

cot/src/common_types.rs

@@ -14,7 +14,9 @@ use cot::db::impl_mysql::MySqlValueRef;
 use cot::db::impl_postgres::PostgresValueRef;
 #[cfg(feature = "sqlite")]
 use cot::db::impl_sqlite::SqliteValueRef;
+use cot::form::FormFieldValidationError;
 use email_address::EmailAddress;
+use thiserror::Error;
 
 #[cfg(feature = "db")]
 use crate::db::{ColumnType, DatabaseField, DbValue, FromDbValue, SqlxValueRef, ToDbValue};
@@ -135,6 +137,219 @@ impl From<String> for Password {
     }
 }
 
+/// A validated URL wrapper.
+///
+/// This structure ensures that the contained URL is correctly formatted and
+/// complies with standard URL syntax rules. It wraps [`url::Url`] to provide
+/// validation upon construction through methods like [`Url::new`] and
+/// [`Url::from_str`], and exposes useful methods for accessing URL components
+/// or converting the URL into different representations.
+///
+/// # Behavior
+///
+/// - **Validation**: Both `new` and `from_str` ensure the input is a
+///   syntactically correct URL as defined by the WHATWG URL specification via
+///   the underlying [`url::Url`] parser.
+/// - **Normalization**: The internal URL is normalized (e.g., trailing slash
+///   added for HTTP URLs) during construction.
+///
+/// # Examples
+///
+/// ## Creating a Validated URL Using `new`
+///
+/// ```
+/// use cot::common_types::Url;
+///
+/// // Successful URL creation
+/// let url = Url::new("https://example.com").unwrap();
+///
+/// // Accessing the normalized URL string
+/// assert_eq!(url.as_str(), "https://example.com/");
+/// ```
+///
+/// ## Parsing a URL from a [`String`] Using `from_str`
+///
+/// ```
+/// use std::str::FromStr;
+///
+/// use cot::common_types::Url;
+///
+/// // Parse a valid URL string
+/// let url = Url::from_str("https://example.com").unwrap();
+///
+/// // Convert into owned string representation
+/// let url_string = url.into_string();
+/// assert_eq!(url_string, "https://example.com/");
+/// ```
+#[derive(Clone, Debug, PartialEq, Eq, PartialOrd, Ord, Hash)]
+pub struct Url(url::Url);
+
+impl Url {
+    /// Creates a new `Url` by parsing the input string.
+    ///
+    /// # Errors
+    ///
+    /// Returns [`UrlParseError`] if the input string is not a valid URL.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// use cot::common_types::Url;
+    ///
+    /// let valid_url = Url::new("https://example.com").unwrap();
+    /// ```
+    pub fn new<S: AsRef<str>>(s: S) -> Result<Url, UrlParseError> {
+        url::Url::from_str(s.as_ref())
+            .map(Self)
+            .map_err(UrlParseError)
+    }
+
+    /// Returns a string slice reference to the URL's string representation.
+    #[must_use]
+    pub fn as_str(&self) -> &str {
+        self.0.as_str()
+    }
+
+    /// Converts the `Url` into a owned `String` representation.
+    ///
+    /// # Examples
+    /// ```
+    /// use cot::common_types::Url;
+    ///
+    /// let url = Url::new("https://example.com").unwrap();
+    /// let url_string = url.into_string();
+    /// assert_eq!(url_string, "https://example.com/");
+    /// ```
+    #[must_use]
+    pub fn into_string(self) -> String {
+        self.0.into()
+    }
+    /// Returns the URL scheme (e.g., "http", "https").
+    ///
+    /// # Example
+    /// ```
+    /// use cot::common_types::Url;
+    ///
+    /// let url = Url::new("https://example.com").unwrap();
+    /// assert_eq!(url.scheme(), "https");
+    /// ```
+    #[must_use]
+    pub fn scheme(&self) -> &str {
+        self.0.scheme()
+    }
+
+    /// Returns the host part of the URL, if present.
+    ///
+    /// This typically includes the domain name or IP address.
+    /// # Example
+    /// ```
+    /// use cot::common_types::Url;
+    ///
+    /// let url = Url::new("https://example.com/path").unwrap();
+    /// assert_eq!(url.host(), Some("example.com"));
+    /// ```
+    #[must_use]
+    pub fn host(&self) -> Option<&str> {
+        self.0.host_str()
+    }
+
+    /// Returns the path component of the URL.
+    ///
+    /// This includes everything after the host and before the query or
+    /// fragment.
+    ///
+    /// # Example
+    /// ```
+    /// use cot::common_types::Url;
+    ///
+    /// let url = Url::new("https://example.com/foo/bar").unwrap();
+    /// assert_eq!(url.path(), "/foo/bar");
+    /// ```
+    #[must_use]
+    pub fn path(&self) -> &str {
+        self.0.path()
+    }
+
+    /// Returns the query string of the URL, if present.
+    ///
+    /// The query is the part that follows the '?' character.
+    ///
+    /// # Example
+    /// ```
+    /// use cot::common_types::Url;
+    ///
+    /// let url = Url::new("https://example.com?query=1").unwrap();
+    /// assert_eq!(url.query(), Some("query=1"));
+    /// ```
+    #[must_use]
+    pub fn query(&self) -> Option<&str> {
+        self.0.query()
+    }
+
+    /// Returns the fragment identifier of the URL, if present.
+    ///
+    /// The fragment is the part that follows the '#' character.
+    ///
+    /// # Example
+    /// ```
+    /// use cot::common_types::Url;
+    ///
+    /// let url = Url::new("https://example.com#section-1").unwrap();
+    /// assert_eq!(url.fragment(), Some("section-1"));
+    /// ```
+    #[must_use]
+    pub fn fragment(&self) -> Option<&str> {
+        self.0.fragment()
+    }
+}
+
+/// Implements string parsing for `Url`.
+///
+/// This allows a string to be parsed directly into a validated [`Url`]
+/// instance. The parsing process ensures that the input string is a
+/// syntactically valid URL.
+///
+/// # Errors
+///
+/// Returns [`UrlParseError`] if the input string is not a valid URL format.
+///
+/// # Examples
+///
+/// ```
+/// use std::str::FromStr;
+///
+/// use cot::common_types::Url;
+///
+/// // Parsing a valid URL string
+/// let url = Url::from_str("https://example.com").unwrap();
+/// assert_eq!(url.as_str(), "https://example.com/");
+///
+/// // Attempting to parse an invalid URL
+/// assert!(Url::from_str("not-a-url").is_err());
+/// ```
+impl FromStr for Url {
+    type Err = UrlParseError;
+
+    fn from_str(s: &str) -> Result<Self, Self::Err> {
+        Url::new(s)
+    }
+}
+
+/// A type that represents an error that occurs when parsing a URL.
+///
+/// This is returned by [`Url::new`] and [`Url::from_str`] when the input string
+/// is not a valid URL.
+#[derive(Debug, Error)]
+#[error(transparent)]
+#[expect(missing_copy_implementations)] // implementation detail
+pub struct UrlParseError(url::ParseError);
+
+impl From<UrlParseError> for FormFieldValidationError {
+    fn from(error: UrlParseError) -> Self {
+        FormFieldValidationError::from_string(error.to_string())
+    }
+}
+
 /// A validated email address.
 ///
 /// This is a newtype wrapper around [`EmailAddress`] that provides validation
@@ -154,7 +369,7 @@ impl From<String> for Password {
 /// // Convert using TryFrom
 /// let email = Email::try_from("user@example.com").unwrap();
 /// ```
-#[derive(Clone, Debug)]
+#[derive(Debug, Clone, PartialEq, Eq, Hash)]
 pub struct Email(EmailAddress);
 
 impl Email {
@@ -174,8 +389,10 @@ impl Email {
     /// let email = Email::new("user@example.com").unwrap();
     /// assert!(Email::new("invalid").is_err());
     /// ```
-    pub fn new<S: AsRef<str>>(email: S) -> Result<Email, email_address::Error> {
-        EmailAddress::from_str(email.as_ref()).map(Self)
+    pub fn new<S: AsRef<str>>(email: S) -> Result<Email, EmailParseError> {
+        EmailAddress::from_str(email.as_ref())
+            .map(Self)
+            .map_err(EmailParseError)
     }
 
     /// Returns the email address as a string.
@@ -320,7 +537,7 @@ impl Email {
 /// let email = Email::from_str("user@example.com").unwrap();
 /// ```
 impl FromStr for Email {
-    type Err = email_address::Error;
+    type Err = EmailParseError;
 
     fn from_str(s: &str) -> Result<Self, Self::Err> {
         Email::new(s)
@@ -337,7 +554,7 @@ impl FromStr for Email {
 /// let email = Email::try_from("user@example.com").unwrap();
 /// ```
 impl TryFrom<&str> for Email {
-    type Error = email_address::Error;
+    type Error = EmailParseError;
 
     fn try_from(value: &str) -> Result<Self, Self::Error> {
         Email::new(value)
@@ -355,13 +572,27 @@ impl TryFrom<&str> for Email {
 /// ```
 #[cfg(feature = "db")]
 impl TryFrom<String> for Email {
-    type Error = email_address::Error;
+    type Error = EmailParseError;
 
     fn try_from(value: String) -> Result<Self, Self::Error> {
         Email::new(value)
     }
 }
 
+/// A type that represents an error that occurs when parsing an email address.
+///
+/// This is returned by [`Email::new`] and [`Email::from_str`] when the input
+/// string is not a valid email address.
+#[derive(Debug, Error)]
+#[error(transparent)]
+pub struct EmailParseError(email_address::Error);
+
+impl From<EmailParseError> for FormFieldValidationError {
+    fn from(error: EmailParseError) -> Self {
+        FormFieldValidationError::from_string(error.to_string())
+    }
+}
+
 /// Implements database value conversion for `Email`.
 ///
 /// This allows a normalized `Email` to be stored in the database as a text
@@ -420,6 +651,20 @@ mod tests {
 
     use super::*;
 
+    #[test]
+    fn url_new() {
+        let parse_url = Url::new("https://example.com/").unwrap();
+        assert_eq!(parse_url.as_str(), "https://example.com/");
+        assert_eq!(parse_url.scheme(), "https");
+        assert_eq!(parse_url.host(), Some("example.com"));
+    }
+
+    #[test]
+    fn url_new_normalize() {
+        let parse_url = Url::new("https://example.com").unwrap();
+        assert_eq!(parse_url.as_str(), "https://example.com/"); // Normalizes to add trailing slash
+    }
+
     #[test]
     fn password_debug() {
         let password = Password::new("password");

cot/src/form.rs

@@ -220,12 +220,6 @@ impl FormFieldValidationError {
     }
 }
 
-impl From<email_address::Error> for FormFieldValidationError {
-    fn from(error: email_address::Error) -> Self {
-        FormFieldValidationError::from_string(error.to_string())
-    }
-}
-
 /// An enum indicating the target of a form validation error.
 #[derive(Debug)]
 pub enum FormErrorTarget<'a> {