feat(schemas): SourceKind::Patched (unstable)

`SourceKind::Patched` represents a source patched by local patch files.

Author: weihanglo

Diff for: crates/cargo-util-schemas/src/core/mod.rs

@@ -7,4 +7,6 @@ pub use package_id_spec::PackageIdSpecError;
 pub use partial_version::PartialVersion;
 pub use partial_version::PartialVersionError;
 pub use source_kind::GitReference;
+pub use source_kind::PatchInfo;
+pub use source_kind::PatchInfoError;
 pub use source_kind::SourceKind;

Diff for: crates/cargo-util-schemas/src/core/package_id_spec.rs

@@ -7,6 +7,7 @@ use url::Url;
 use crate::core::GitReference;
 use crate::core::PartialVersion;
 use crate::core::PartialVersionError;
+use crate::core::PatchInfo;
 use crate::core::SourceKind;
 use crate::manifest::PackageName;
 use crate::restricted_names::NameValidationError;
@@ -145,6 +146,14 @@ impl PackageIdSpec {
                     kind = Some(SourceKind::Path);
                     url = strip_url_protocol(&url);
                 }
+                "patched" => {
+                    let patch_info =
+                        PatchInfo::from_query(url.query_pairs()).map_err(ErrorKind::PatchInfo)?;
+                    url.set_query(None);
+                    kind = Some(SourceKind::Patched(patch_info));
+                    // We don't strip protocol and leave `patch` as part of URL
+                    // in order to distinguish them.
+                }
                 kind => return Err(ErrorKind::UnsupportedProtocol(kind.into()).into()),
             }
         } else {
@@ -232,10 +241,16 @@ impl fmt::Display for PackageIdSpec {
                     write!(f, "{protocol}+")?;
                 }
                 write!(f, "{}", url)?;
-                if let Some(SourceKind::Git(git_ref)) = self.kind.as_ref() {
-                    if let Some(pretty) = git_ref.pretty_ref(true) {
-                        write!(f, "?{}", pretty)?;
+                match self.kind.as_ref() {
+                    Some(SourceKind::Git(git_ref)) => {
+                        if let Some(pretty) = git_ref.pretty_ref(true) {
+                            write!(f, "?{pretty}")?;
+                        }
                     }
+                    Some(SourceKind::Patched(patch_info)) => {
+                        write!(f, "?{}", patch_info.as_query())?;
+                    }
+                    _ => {}
                 }
                 if url.path_segments().unwrap().next_back().unwrap() != &*self.name {
                     printed_name = true;
@@ -314,13 +329,16 @@ enum ErrorKind {
 
     #[error(transparent)]
     PartialVersion(#[from] crate::core::PartialVersionError),
+
+    #[error(transparent)]
+    PatchInfo(#[from] crate::core::PatchInfoError),
 }
 
 #[cfg(test)]
 mod tests {
     use super::ErrorKind;
     use super::PackageIdSpec;
-    use crate::core::{GitReference, SourceKind};
+    use crate::core::{GitReference, PatchInfo, SourceKind};
     use url::Url;
 
     #[test]
@@ -599,6 +617,18 @@ mod tests {
             },
             "path+file:///path/to/my/project/foo#1.1.8",
         );
+
+        // Unstable
+        ok(
+            "patched+https://crates.io/foo?name=bar&version=1.2.0&patch=%2Fto%2Fa.patch&patch=%2Fb.patch#[email protected]",
+            PackageIdSpec {
+                name: String::from("bar"),
+                version: Some("1.2.0".parse().unwrap()),
+                url: Some(Url::parse("patched+https://crates.io/foo").unwrap()),
+                kind: Some(SourceKind::Patched(PatchInfo::new("bar".into(), "1.2.0".into(), vec!["/to/a.patch".into(), "/b.patch".into()]))),
+            },
+            "patched+https://crates.io/foo?name=bar&version=1.2.0&patch=%2Fto%2Fa.patch&patch=%2Fb.patch#[email protected]",
+        );
     }
 
     #[test]
@@ -651,5 +681,17 @@ mod tests {
         err!("@1.2.3", ErrorKind::NameValidation(_));
         err!("registry+https://github.com", ErrorKind::NameValidation(_));
         err!("https://crates.io/1foo#1.2.3", ErrorKind::NameValidation(_));
+        err!(
+            "patched+https://crates.io/foo?version=1.2.0&patch=%2Fb.patch#[email protected]",
+            ErrorKind::PatchInfo(_)
+        );
+        err!(
+            "patched+https://crates.io/foo?name=bar&patch=%2Fb.patch#[email protected]",
+            ErrorKind::PatchInfo(_)
+        );
+        err!(
+            "patched+https://crates.io/foo?name=bar&version=1.2.0&#[email protected]",
+            ErrorKind::PatchInfo(_)
+        );
     }
 }

Diff for: crates/cargo-util-schemas/src/core/source_kind.rs

@@ -1,4 +1,5 @@
 use std::cmp::Ordering;
+use std::path::PathBuf;
 
 /// The possible kinds of code source.
 #[derive(Debug, Clone, PartialEq, Eq, Hash)]
@@ -15,6 +16,8 @@ pub enum SourceKind {
     LocalRegistry,
     /// A directory-based registry.
     Directory,
+    /// A source with paths to patch files (unstable).
+    Patched(PatchInfo),
 }
 
 impl SourceKind {
@@ -27,6 +30,8 @@ impl SourceKind {
             SourceKind::SparseRegistry => None,
             SourceKind::LocalRegistry => Some("local-registry"),
             SourceKind::Directory => Some("directory"),
+            // Patched source URL already includes the `patched+` prefix, see `SourceId::new`
+            SourceKind::Patched(_) => None,
         }
     }
 }
@@ -107,6 +112,10 @@ impl Ord for SourceKind {
             (SourceKind::Directory, _) => Ordering::Less,
             (_, SourceKind::Directory) => Ordering::Greater,
 
+            (SourceKind::Patched(a), SourceKind::Patched(b)) => a.cmp(b),
+            (SourceKind::Patched(_), _) => Ordering::Less,
+            (_, SourceKind::Patched(_)) => Ordering::Greater,
+
             (SourceKind::Git(a), SourceKind::Git(b)) => a.cmp(b),
         }
     }
@@ -199,3 +208,101 @@ impl<'a> std::fmt::Display for PrettyRef<'a> {
         Ok(())
     }
 }
+
+/// Information to find the source package and patch files.
+#[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord, Hash)]
+pub struct PatchInfo {
+    /// Name of the package to be patched.
+    name: String,
+    /// Verision of the package to be patched.
+    version: String,
+    /// Absolute paths to patch files.
+    ///
+    /// These are absolute to ensure Cargo can locate them in the patching phase.
+    patches: Vec<PathBuf>,
+}
+
+impl PatchInfo {
+    pub fn new(name: String, version: String, patches: Vec<PathBuf>) -> PatchInfo {
+        PatchInfo {
+            name,
+            version,
+            patches,
+        }
+    }
+
+    /// Collects patch information from query string.
+    ///
+    /// * `name` --- Package name
+    /// * `version` --- Package exact version
+    /// * `patch` --- Paths to patch files. Mutiple occurrences allowed.
+    pub fn from_query(
+        query_pairs: impl Iterator<Item = (impl AsRef<str>, impl AsRef<str>)>,
+    ) -> Result<PatchInfo, PatchInfoError> {
+        let mut name = None;
+        let mut version = None;
+        let mut patches = Vec::new();
+        for (k, v) in query_pairs {
+            let v = v.as_ref();
+            match k.as_ref() {
+                "name" => name = Some(v.to_owned()),
+                "version" => version = Some(v.to_owned()),
+                "patch" => patches.push(PathBuf::from(v)),
+                _ => {}
+            }
+        }
+        let name = name.ok_or_else(|| PatchInfoError("name"))?;
+        let version = version.ok_or_else(|| PatchInfoError("version"))?;
+        if patches.is_empty() {
+            return Err(PatchInfoError("path"));
+        }
+        Ok(PatchInfo::new(name, version, patches))
+    }
+
+    /// As a URL query string.
+    pub fn as_query(&self) -> PatchInfoQuery<'_> {
+        PatchInfoQuery(self)
+    }
+
+    pub fn name(&self) -> &str {
+        self.name.as_str()
+    }
+
+    pub fn version(&self) -> &str {
+        self.version.as_str()
+    }
+
+    pub fn patches(&self) -> &[PathBuf] {
+        self.patches.as_slice()
+    }
+}
+
+/// A [`PatchInfo`] that can be `Display`ed as URL query string.
+pub struct PatchInfoQuery<'a>(&'a PatchInfo);
+
+impl<'a> std::fmt::Display for PatchInfoQuery<'a> {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        write!(f, "name=")?;
+        for value in url::form_urlencoded::byte_serialize(self.0.name.as_bytes()) {
+            write!(f, "{value}")?;
+        }
+        write!(f, "&version=")?;
+        for value in url::form_urlencoded::byte_serialize(self.0.version.as_bytes()) {
+            write!(f, "{value}")?;
+        }
+        for path in &self.0.patches {
+            write!(f, "&patch=")?;
+            let path = path.to_str().expect("utf8 patch").replace("\\", "/");
+            for value in url::form_urlencoded::byte_serialize(path.as_bytes()) {
+                write!(f, "{value}")?;
+            }
+        }
+
+        Ok(())
+    }
+}
+
+/// Error parsing patch info from URL query string.
+#[derive(Debug, thiserror::Error)]
+#[error("missing query string `{0}`")]
+pub struct PatchInfoError(&'static str);

Diff for: src/cargo/core/source_id.rs

@@ -419,6 +419,7 @@ impl SourceId {
                     .expect("path sources cannot be remote");
                 Ok(Box::new(DirectorySource::new(&path, self, gctx)))
             }
+            SourceKind::Patched(_) => todo!(),
         }
     }
 
@@ -665,6 +666,7 @@ impl fmt::Display for SourceId {
             }
             SourceKind::LocalRegistry => write!(f, "registry `{}`", url_display(&self.inner.url)),
             SourceKind::Directory => write!(f, "dir {}", url_display(&self.inner.url)),
+            SourceKind::Patched(_) => todo!(),
         }
     }
 }