webui_parser/
css_link.rs

1// Copyright (c) Microsoft Corporation.
2// Licensed under the MIT license.
3
4//! Link-mode CSS filename and public href resolution.
5
6use crate::{AssetFileNameTemplate, ParserError, Result, DEFAULT_ASSET_FILE_NAME_TEMPLATE};
7use std::collections::HashMap;
8use std::sync::{Arc, Mutex};
9
10/// Default Link-mode CSS filename template.
11pub const DEFAULT_CSS_FILE_NAME_TEMPLATE: &str = DEFAULT_ASSET_FILE_NAME_TEMPLATE;
12
13/// Configures Link-mode CSS filenames and public hrefs.
14#[derive(Debug, Clone)]
15pub struct CssLinkOptions {
16    file_name_template: AssetFileNameTemplate,
17    public_base: Option<String>,
18    cache: Arc<Mutex<HashMap<String, CssLinkHref>>>,
19}
20
21/// Resolved Link-mode CSS asset path data.
22#[derive(Debug, Clone, PartialEq, Eq)]
23pub struct CssLinkHref {
24    /// Local filename emitted by build output.
25    pub filename: String,
26    /// Public href used in parser/handler `<link>` tags.
27    pub href: String,
28}
29
30impl CssLinkOptions {
31    /// Create validated Link-mode CSS options.
32    ///
33    /// # Errors
34    ///
35    /// Returns [`ParserError::Css`] when the template contains unknown tokens,
36    /// unsafe path bytes, or an unsafe public base.
37    pub fn try_new(file_name_template: String, public_base: Option<String>) -> Result<Self> {
38        let file_name_template =
39            AssetFileNameTemplate::try_new(file_name_template, "css_file_name_template")
40                .map_err(|error| ParserError::Css(error.to_string()))?;
41        if let Some(base) = public_base.as_deref() {
42            validate_css_public_base(base)?;
43        }
44        Ok(Self {
45            file_name_template,
46            public_base,
47            cache: Arc::new(Mutex::new(HashMap::new())),
48        })
49    }
50
51    /// Resolve the local filename and public href for a component stylesheet.
52    ///
53    /// Results are cached by component tag. A `CssLinkOptions` value should be
54    /// scoped to one build/component registry where each tag maps to exactly
55    /// one stylesheet.
56    #[must_use]
57    pub fn resolve(&self, tag_name: &str, css_content: &str) -> CssLinkHref {
58        {
59            let cache = self
60                .cache
61                .lock()
62                .unwrap_or_else(std::sync::PoisonError::into_inner);
63            if let Some(cached) = cache.get(tag_name) {
64                return cached.clone();
65            }
66        }
67
68        let filename = self
69            .file_name_template
70            .resolve(tag_name, "css", css_content.as_bytes());
71        let href = match self.public_base.as_deref() {
72            Some(base) => join_css_public_base(base, &filename),
73            None => filename.clone(),
74        };
75        let resolved = CssLinkHref { filename, href };
76
77        let mut cache = self
78            .cache
79            .lock()
80            .unwrap_or_else(std::sync::PoisonError::into_inner);
81        cache
82            .entry(tag_name.to_string())
83            .or_insert_with(|| resolved.clone())
84            .clone()
85    }
86
87    /// File name template used for Link-mode CSS files.
88    #[must_use]
89    pub fn file_name_template(&self) -> &str {
90        self.file_name_template.file_name_template()
91    }
92
93    /// Optional public base prepended to Link-mode CSS hrefs.
94    #[must_use]
95    pub fn public_base(&self) -> Option<&str> {
96        self.public_base.as_deref()
97    }
98}
99
100impl Default for CssLinkOptions {
101    fn default() -> Self {
102        Self {
103            file_name_template: AssetFileNameTemplate::new_unchecked(
104                DEFAULT_CSS_FILE_NAME_TEMPLATE.to_string(),
105            ),
106            public_base: None,
107            cache: Arc::new(Mutex::new(HashMap::new())),
108        }
109    }
110}
111
112impl PartialEq for CssLinkOptions {
113    fn eq(&self, other: &Self) -> bool {
114        self.file_name_template == other.file_name_template && self.public_base == other.public_base
115    }
116}
117
118impl Eq for CssLinkOptions {}
119
120fn validate_css_public_base(base: &str) -> Result<()> {
121    if base.is_empty() {
122        return Err(ParserError::Css(
123            "css_public_base cannot be empty".to_string(),
124        ));
125    }
126    if contains_invalid_href_byte(base) {
127        return Err(ParserError::Css(
128            "css_public_base cannot contain quotes, angle brackets, backslashes, or whitespace"
129                .to_string(),
130        ));
131    }
132    Ok(())
133}
134
135fn join_css_public_base(base: &str, css_filename: &str) -> String {
136    let mut href = String::with_capacity(base.len() + css_filename.len() + 1);
137    href.push_str(base);
138    if !base.ends_with('/') {
139        href.push('/');
140    }
141    href.push_str(css_filename);
142    href
143}
144
145fn contains_invalid_href_byte(value: &str) -> bool {
146    value
147        .bytes()
148        .any(|b| matches!(b, b'"' | b'\'' | b'<' | b'>' | b'\\') || b.is_ascii_whitespace())
149}
150
151#[cfg(test)]
152#[allow(clippy::disallowed_methods)]
153mod tests {
154    use super::*;
155
156    #[test]
157    fn default_template_does_not_require_hash() {
158        let options = CssLinkOptions::default();
159        assert!(!options.file_name_template.uses_hash());
160        let resolved = options.resolve("my-card", ".card { color: red; }");
161        assert_eq!(resolved.filename, "my-card.css");
162    }
163
164    #[test]
165    fn hash_template_uses_content_hash() {
166        let options = CssLinkOptions::try_new("[name]-[hash].[ext]".to_string(), None).unwrap();
167        assert!(options.file_name_template.uses_hash());
168        let first = options.resolve("my-card", ".card { color: red; }");
169        let second = options.resolve("other-card", ".card { color: blue; }");
170
171        assert!(first.filename.starts_with("my-card-"));
172        assert!(second.filename.starts_with("other-card-"));
173        assert_ne!(
174            first.filename.rsplit_once('-').map(|(_, hash)| hash),
175            second.filename.rsplit_once('-').map(|(_, hash)| hash)
176        );
177    }
178
179    #[test]
180    fn filename_template_rejects_filesystem_unsafe_characters() {
181        for template in [
182            "[name]:[hash].[ext]",
183            "[name]*[hash].[ext]",
184            "[name]?[hash].[ext]",
185            "[name]|[hash].[ext]",
186            "résumé-[hash].[ext]",
187        ] {
188            let result = CssLinkOptions::try_new(template.to_string(), None);
189            assert!(result.is_err(), "template should be rejected: {template}");
190        }
191    }
192}
webui_parser/css_link.rs

webui_parser/
css_link.rs
