fuchsia_url/
absolute_package_url.rs

1// Copyright 2022 The Fuchsia Authors. All rights reserved.
2// Use of this source code is governed by a BSD-style license that can be
3// found in the LICENSE file.
4
5use crate::errors::ParseError;
6use crate::parse::{PackageName, PackageVariant};
7use crate::{PinnedAbsolutePackageUrl, RepositoryUrl, UnpinnedAbsolutePackageUrl, UrlParts};
8use fuchsia_hash::Hash;
9
10/// A URL locating a Fuchsia package.
11/// Has the form "fuchsia-pkg://<repository>/<name>[/variant][?hash=<hash>]" where:
12///   * "repository" is a valid hostname
13///   * "name" is a valid package name
14///   * "variant" is an optional valid package variant
15///   * "hash" is an optional valid package hash
16/// https://fuchsia.dev/fuchsia-src/concepts/packages/package_url
17#[derive(Clone, Debug, PartialEq, Eq, PartialOrd, Ord, Hash)]
18pub enum AbsolutePackageUrl {
19    Unpinned(UnpinnedAbsolutePackageUrl),
20    Pinned(PinnedAbsolutePackageUrl),
21}
22
23impl AbsolutePackageUrl {
24    pub(crate) fn from_parts(parts: UrlParts) -> Result<Self, ParseError> {
25        let UrlParts { scheme, host, path, hash, resource } = parts;
26        let repo = RepositoryUrl::new(
27            scheme.ok_or(ParseError::MissingScheme)?,
28            host.ok_or(ParseError::MissingHost)?,
29        )?;
30        if resource.is_some() {
31            return Err(ParseError::CannotContainResource);
32        }
33        Self::new_with_path(repo, &path, hash)
34    }
35
36    /// Parse a "fuchsia-pkg://" URL that locates an optionally pinned package.
37    pub fn parse(url: &str) -> Result<Self, ParseError> {
38        Self::from_parts(UrlParts::parse(url)?)
39    }
40
41    /// Create an AbsolutePackageUrl from its component parts and a &str `path` that will be
42    /// validated.
43    pub fn new_with_path(
44        repo: RepositoryUrl,
45        path: &str,
46        hash: Option<Hash>,
47    ) -> Result<Self, ParseError> {
48        Ok(match hash {
49            None => Self::Unpinned(UnpinnedAbsolutePackageUrl::new_with_path(repo, path)?),
50            Some(hash) => Self::Pinned(PinnedAbsolutePackageUrl::new_with_path(repo, path, hash)?),
51        })
52    }
53
54    /// Create an AbsolutePackageUrl from its component parts.
55    pub fn new(
56        repo: RepositoryUrl,
57        name: PackageName,
58        variant: Option<PackageVariant>,
59        hash: Option<Hash>,
60    ) -> Self {
61        match hash {
62            None => Self::Unpinned(UnpinnedAbsolutePackageUrl::new(repo, name, variant)),
63            Some(hash) => Self::Pinned(PinnedAbsolutePackageUrl::new(repo, name, variant, hash)),
64        }
65    }
66
67    /// The optional hash of the package.
68    pub fn hash(&self) -> Option<Hash> {
69        match self {
70            Self::Unpinned(_) => None,
71            Self::Pinned(pinned) => Some(pinned.hash()),
72        }
73    }
74
75    pub fn name(&self) -> &PackageName {
76        match self {
77            Self::Unpinned(unpinned) => &unpinned.name(),
78            Self::Pinned(pinned) => pinned.name(),
79        }
80    }
81
82    /// The URL without the optional package hash.
83    pub fn as_unpinned(&self) -> &UnpinnedAbsolutePackageUrl {
84        match self {
85            Self::Unpinned(unpinned) => &unpinned,
86            Self::Pinned(pinned) => pinned.as_unpinned(),
87        }
88    }
89
90    /// The pinned URL, if the URL is pinned.
91    pub fn pinned(self) -> Option<PinnedAbsolutePackageUrl> {
92        match self {
93            Self::Unpinned(_) => None,
94            Self::Pinned(pinned) => Some(pinned),
95        }
96    }
97}
98
99// AbsolutePackageUrl does not maintain any invariants in addition to those already maintained by
100// its variants so this is safe.
101impl std::ops::Deref for AbsolutePackageUrl {
102    type Target = UnpinnedAbsolutePackageUrl;
103
104    fn deref(&self) -> &Self::Target {
105        match self {
106            Self::Unpinned(unpinned) => &unpinned,
107            Self::Pinned(pinned) => &pinned,
108        }
109    }
110}
111
112// AbsolutePackageUrl does not maintain any invariants in addition to those already maintained by
113// its variants so this is safe.
114impl std::ops::DerefMut for AbsolutePackageUrl {
115    fn deref_mut(&mut self) -> &mut Self::Target {
116        match self {
117            Self::Unpinned(unpinned) => unpinned,
118            Self::Pinned(pinned) => pinned,
119        }
120    }
121}
122
123impl std::str::FromStr for AbsolutePackageUrl {
124    type Err = ParseError;
125
126    fn from_str(url: &str) -> Result<Self, Self::Err> {
127        Self::parse(url)
128    }
129}
130
131impl std::convert::TryFrom<&str> for AbsolutePackageUrl {
132    type Error = ParseError;
133
134    fn try_from(value: &str) -> Result<Self, Self::Error> {
135        Self::parse(value)
136    }
137}
138
139impl std::convert::From<PinnedAbsolutePackageUrl> for AbsolutePackageUrl {
140    fn from(pinned: PinnedAbsolutePackageUrl) -> Self {
141        Self::Pinned(pinned)
142    }
143}
144
145impl std::convert::From<UnpinnedAbsolutePackageUrl> for AbsolutePackageUrl {
146    fn from(unpinned: UnpinnedAbsolutePackageUrl) -> Self {
147        Self::Unpinned(unpinned)
148    }
149}
150
151impl std::fmt::Display for AbsolutePackageUrl {
152    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
153        match self {
154            Self::Unpinned(unpinned) => write!(f, "{}", unpinned),
155            Self::Pinned(pinned) => write!(f, "{}", pinned),
156        }
157    }
158}
159
160impl serde::Serialize for AbsolutePackageUrl {
161    fn serialize<S: serde::Serializer>(&self, ser: S) -> Result<S::Ok, S::Error> {
162        self.to_string().serialize(ser)
163    }
164}
165
166impl<'de> serde::Deserialize<'de> for AbsolutePackageUrl {
167    fn deserialize<D>(de: D) -> Result<Self, D::Error>
168    where
169        D: serde::Deserializer<'de>,
170    {
171        let url = String::deserialize(de)?;
172        Ok(Self::parse(&url).map_err(|err| serde::de::Error::custom(err))?)
173    }
174}
175
176#[cfg(test)]
177mod tests {
178    use super::*;
179    use crate::errors::PackagePathSegmentError;
180    use assert_matches::assert_matches;
181    use std::convert::TryFrom as _;
182
183    #[test]
184    fn parse_err() {
185        for (url, err) in [
186            ("example.org/name", ParseError::MissingScheme),
187            ("//example.org/name", ParseError::MissingScheme),
188            ("///name", ParseError::MissingScheme),
189            ("/name", ParseError::MissingScheme),
190            ("name", ParseError::MissingScheme),
191            ("fuchsia-boot://example.org/name", ParseError::InvalidScheme),
192            ("fuchsia-pkg://", ParseError::MissingHost),
193            ("fuchsia-pkg://exaMple.org", ParseError::InvalidHost),
194            ("fuchsia-pkg://example.org/", ParseError::MissingName),
195            (
196                "fuchsia-pkg://example.org//",
197                ParseError::InvalidPathSegment(PackagePathSegmentError::Empty),
198            ),
199            ("fuchsia-pkg://example.org/name/variant/extra", ParseError::ExtraPathSegments),
200            ("fuchsia-pkg://example.org/name#resource", ParseError::CannotContainResource),
201        ] {
202            assert_matches!(
203                AbsolutePackageUrl::parse(url),
204                Err(e) if e == err,
205                "the url {:?}", url
206            );
207            assert_matches!(
208                url.parse::<AbsolutePackageUrl>(),
209                Err(e) if e == err,
210                "the url {:?}", url
211            );
212            assert_matches!(
213                AbsolutePackageUrl::try_from(url),
214                Err(e) if e == err,
215                "the url {:?}", url
216            );
217            assert_matches!(
218                serde_json::from_str::<AbsolutePackageUrl>(url),
219                Err(_),
220                "the url {:?}",
221                url
222            );
223        }
224    }
225
226    #[test]
227    fn parse_ok() {
228        for (url, host, name, variant, hash) in [
229            ("fuchsia-pkg://example.org/name", "example.org", "name", None, None),
230            ("fuchsia-pkg://example.org/name/variant", "example.org", "name", Some("variant"), None),
231            (
232            "fuchsia-pkg://example.org/name?hash=0000000000000000000000000000000000000000000000000000000000000000", "example.org", "name", None, Some("0000000000000000000000000000000000000000000000000000000000000000")),
233            ("fuchsia-pkg://example.org/name/variant?hash=0000000000000000000000000000000000000000000000000000000000000000", "example.org", "name", Some("variant"), Some("0000000000000000000000000000000000000000000000000000000000000000")),
234        ] {
235            let json_url = format!("\"{url}\"");
236
237            // Creation
238            let name = name.parse::<crate::PackageName>().unwrap();
239            let variant = variant.map(|v| v.parse::<crate::PackageVariant>().unwrap());
240            let hash = hash.map(|h| h.parse::<Hash>().unwrap());
241            let validate = |parsed: &AbsolutePackageUrl| {
242                assert_eq!(parsed.host(), host);
243                assert_eq!(parsed.name(), &name);
244                assert_eq!(parsed.variant(), variant.as_ref());
245                assert_eq!(parsed.hash(), hash);
246            };
247            validate(&AbsolutePackageUrl::parse(url).unwrap());
248            validate(&url.parse::<AbsolutePackageUrl>().unwrap());
249            validate(&AbsolutePackageUrl::try_from(url).unwrap());
250            validate(&serde_json::from_str::<AbsolutePackageUrl>(&json_url).unwrap());
251
252            // Stringification
253            assert_eq!(
254                AbsolutePackageUrl::parse(url).unwrap().to_string(),
255                url,
256                "the url {:?}",
257                url
258            );
259            assert_eq!(
260                serde_json::to_string(&AbsolutePackageUrl::parse(url).unwrap()).unwrap(),
261                json_url,
262                "the url {:?}",
263                url
264            );
265        }
266    }
267}
fuchsia_url/absolute_package_url.rs

fuchsia_url/
absolute_package_url.rs
