feat: External stylesheet caching

Ref: #314

Author: Stranger6667

CHANGELOG.md

@@ -2,6 +2,10 @@
 
 ## [Unreleased]
 
+### Added
+
+- External stylesheet caching. [#314](https://github.com/Stranger6667/css-inline/issues/314)
+
 ### Changed
 
 - Update `html5ever` to `0.27`.

README.md

@@ -38,6 +38,7 @@ into:
 - Inlines CSS from `style` and `link` tags
 - Removes `style` and `link` tags
 - Resolves external stylesheets (including local files)
+- Caching for external stylesheets
 - Works on Linux, Windows, and macOS
 - Supports HTML5 & CSS3
 - Bindings for [Python](https://github.com/Stranger6667/css-inline/tree/master/bindings/python), [Ruby](https://github.com/Stranger6667/css-inline/tree/master/bindings/ruby), [JavaScript](https://github.com/Stranger6667/css-inline/tree/master/bindings/javascript), [C](https://github.com/Stranger6667/css-inline/tree/master/bindings/c), and a [WebAssembly](https://github.com/Stranger6667/css-inline/tree/master/bindings/javascript/wasm) module to run in browsers.
@@ -177,6 +178,26 @@ fn main() -> css_inline::Result<()> {
 }
 ```
 
+You can also cache external stylesheets to avoid excessive network requests:
+
+```rust
+use std::num::NonZeroUsize;
+
+fn main() -> css_inline::Result<()> {
+    let inliner = css_inline::CSSInliner::options()
+        .cache(
+            // This is an LRU cache
+            css_inline::StylesheetCache::new(
+                NonZeroUsize::new(5).expect("Invalid cache size")
+            )
+        )
+        .build();
+    Ok(())
+}
+```
+
+Caching is disabled by default.
+
 ## Performance
 
 `css-inline` typically inlines HTML emails within hundreds of microseconds, though results may vary with input complexity.

bindings/c/CHANGELOG.md

@@ -2,6 +2,10 @@
 
 ## [Unreleased]
 
+### Added
+
+- External stylesheet caching. [#314](https://github.com/Stranger6667/css-inline/issues/314)
+
 ### Changed
 
 - Update `html5ever` to `0.27`.

bindings/c/README.md

@@ -36,6 +36,7 @@ into:
 - Inlines CSS from `style` and `link` tags
 - Removes `style` and `link` tags
 - Resolves external stylesheets (including local files)
+- Caching for external stylesheets
 - Works on Linux, Windows, and macOS
 - Supports HTML5 & CSS3
 

bindings/javascript/CHANGELOG.md

@@ -2,6 +2,10 @@
 
 ## [Unreleased]
 
+### Added
+
+- External stylesheet caching. [#314](https://github.com/Stranger6667/css-inline/issues/314)
+
 ## [0.13.2] - 2024-03-25
 
 ### Changed

bindings/javascript/README.md

@@ -37,6 +37,7 @@ into:
 - Inlines CSS from `style` and `link` tags
 - Removes `style` and `link` tags
 - Resolves external stylesheets (including local files)
+- Caching for external stylesheets
 - Works on Linux, Windows, and macOS
 - Supports HTML5 & CSS3
 - Tested on Node.js 18 & 20.

bindings/python/CHANGELOG.md

@@ -2,6 +2,10 @@
 
 ## [Unreleased]
 
+### Added
+
+- External stylesheet caching. [#314](https://github.com/Stranger6667/css-inline/issues/314)
+
 ### Changed
 
 - Update `html5ever` to `0.27`.

bindings/python/README.md

@@ -40,6 +40,7 @@ into:
 - Inlines CSS from `style` and `link` tags
 - Removes `style` and `link` tags
 - Resolves external stylesheets (including local files)
+- Caching for external stylesheets
 - Can process multiple documents in parallel
 - Works on Linux, Windows, and macOS
 - Supports HTML5 & CSS3

bindings/ruby/CHANGELOG.md

@@ -2,6 +2,10 @@
 
 ## [Unreleased]
 
+### Added
+
+- External stylesheet caching. [#314](https://github.com/Stranger6667/css-inline/issues/314)
+
 ### Changed
 
 - Update `html5ever` to `0.27`.

bindings/ruby/README.md

@@ -37,6 +37,7 @@ into:
 - Inlines CSS from `style` and `link` tags
 - Removes `style` and `link` tags
 - Resolves external stylesheets (including local files)
+- Caching for external stylesheets
 - Can process multiple documents in parallel
 - Works on Linux, Windows, and macOS
 - Supports HTML5 & CSS3

css-inline/Cargo.toml

@@ -22,15 +22,17 @@ rust-version = "1.65"
 name = "css-inline"
 
 [features]
-default = ["cli", "http", "file"]
+default = ["cli", "http", "file", "stylesheet-cache"]
 cli = ["pico-args", "rayon"]
 http = ["reqwest"]
 file = []
+stylesheet-cache = ["lru"]
 
 [dependencies]
 cssparser = "0.31.2"
 html5ever = "0.27.0"
 indexmap = "2.1"
+lru = { version = "0.12.3", optional = true }
 pico-args = { version = "0.3", optional = true }
 rayon = { version = "1.10", optional = true }
 reqwest = { version = "0.12.0", optional = true, default-features = false, features = ["rustls-tls", "blocking"] }

css-inline/src/lib.rs

@@ -35,14 +35,24 @@ mod resolver;
 
 pub use error::InlineError;
 use indexmap::IndexMap;
-use std::{borrow::Cow, fmt::Formatter, hash::BuildHasherDefault, io::Write, sync::Arc};
+use lru::{DefaultHasher, LruCache};
+use std::{
+    borrow::Cow,
+    fmt::Formatter,
+    hash::BuildHasherDefault,
+    io::Write,
+    sync::{Arc, Mutex},
+};
 
 use crate::html::ElementStyleMap;
 use hasher::BuildNoHashHasher;
 use html::Document;
 pub use resolver::{DefaultStylesheetResolver, StylesheetResolver};
 pub use url::{ParseError, Url};
 
+/// An LRU Cache for external stylesheets.
+pub type StylesheetCache<S = DefaultHasher> = LruCache<String, String, S>;
+
 /// Configuration options for CSS inlining process.
 #[allow(clippy::struct_excessive_bools)]
 pub struct InlineOptions<'a> {
@@ -59,6 +69,8 @@ pub struct InlineOptions<'a> {
     pub base_url: Option<Url>,
     /// Whether remote stylesheets should be loaded or not.
     pub load_remote_stylesheets: bool,
+    /// External stylesheet cache.
+    pub cache: Option<Mutex<StylesheetCache>>,
     // The point of using `Cow` here is Python bindings, where it is problematic to pass a reference
     // without dealing with memory leaks & unsafe. With `Cow` we can use moved values as `String` in
     // Python wrapper for `CSSInliner` and `&str` in Rust & simple functions on the Python side
@@ -79,6 +91,7 @@ impl<'a> std::fmt::Debug for InlineOptions<'a> {
             .field("keep_link_tags", &self.keep_link_tags)
             .field("base_url", &self.base_url)
             .field("load_remote_stylesheets", &self.load_remote_stylesheets)
+            .field("cache", &self.cache)
             .field("extra_css", &self.extra_css)
             .field("preallocate_node_capacity", &self.preallocate_node_capacity)
             .finish_non_exhaustive()
@@ -121,6 +134,17 @@ impl<'a> InlineOptions<'a> {
         self
     }
 
+    /// Set external stylesheet cache size.
+    #[must_use]
+    pub fn cache(mut self, cache: impl Into<Option<StylesheetCache>>) -> Self {
+        if let Some(cache) = cache.into() {
+            self.cache = Some(Mutex::new(cache));
+        } else {
+            self.cache = None;
+        }
+        self
+    }
+
     /// Set additional CSS to inline.
     #[must_use]
     pub fn extra_css(mut self, extra_css: Option<Cow<'a, str>>) -> Self {
@@ -158,6 +182,7 @@ impl Default for InlineOptions<'_> {
             keep_link_tags: false,
             base_url: None,
             load_remote_stylesheets: true,
+            cache: None,
             extra_css: None,
             preallocate_node_capacity: 32,
             resolver: Arc::new(DefaultStylesheetResolver),
@@ -247,7 +272,13 @@ impl<'a> CSSInliner<'a> {
     ///   - Remote stylesheet is not available;
     ///   - IO errors;
     ///   - Internal CSS selector parsing error;
+    ///
+    /// # Panics
+    ///
+    /// This function may panic if external stylesheet cache lock is poisoned, i.e. another thread
+    /// using the same inliner panicked while resolving external stylesheets.
     #[inline]
+    #[allow(clippy::too_many_lines)]
     pub fn inline_to<W: Write>(&self, html: &str, target: &mut W) -> Result<()> {
         let document =
             Document::parse_with_options(html.as_bytes(), self.options.preallocate_node_capacity);
@@ -285,9 +316,23 @@ impl<'a> CSSInliner<'a> {
             links.dedup();
             for href in &links {
                 let url = self.get_full_url(href);
+                if let Some(lock) = self.options.cache.as_ref() {
+                    let mut cache = lock.lock().expect("Cache lock is poisoned");
+                    if let Some(cached) = cache.get(url.as_ref()) {
+                        raw_styles.push_str(cached);
+                        raw_styles.push('\n');
+                        continue;
+                    }
+                }
+
                 let css = self.options.resolver.retrieve(url.as_ref())?;
                 raw_styles.push_str(&css);
                 raw_styles.push('\n');
+
+                if let Some(lock) = self.options.cache.as_ref() {
+                    let mut cache = lock.lock().expect("Cache lock is poisoned");
+                    cache.put(url.into_owned(), css);
+                }
             }
         }
         if let Some(extra_css) = &self.options.extra_css {
@@ -415,3 +460,15 @@ pub fn inline(html: &str) -> Result<String> {
 pub fn inline_to<W: Write>(html: &str, target: &mut W) -> Result<()> {
     CSSInliner::default().inline_to(html, target)
 }
+
+#[cfg(test)]
+mod tests {
+    use crate::{CSSInliner, InlineOptions};
+
+    #[test]
+    fn test_inliner_sync_send() {
+        fn assert_send<T: Send + Sync>() {}
+        assert_send::<CSSInliner<'_>>();
+        assert_send::<InlineOptions<'_>>();
+    }
+}

css-inline/src/main.rs

@@ -132,6 +132,8 @@ OPTIONS:
             keep_link_tags: args.keep_link_tags,
             base_url,
             load_remote_stylesheets: args.load_remote_stylesheets,
+            // TODO: Customize
+            cache: None,
             extra_css: args.extra_css.as_deref().map(Cow::Borrowed),
             preallocate_node_capacity: 32,
             resolver: Arc::new(DefaultStylesheetResolver),

css-inline/tests/test_inlining.rs

@@ -1,6 +1,11 @@
 #[macro_use]
 mod utils;
-use css_inline::{inline, CSSInliner, InlineOptions, Url};
+
+use css_inline::{inline, CSSInliner, InlineOptions, StylesheetCache, Url};
+use std::{
+    num::NonZeroUsize,
+    sync::{Arc, RwLock},
+};
 use test_case::test_case;
 
 #[cfg(not(feature = "file"))]
@@ -927,3 +932,54 @@ fn nth_child_selector() {
 </body></html>"#
     );
 }
+
+#[test]
+fn test_cache() {
+    let html = r#"
+<html>
+<head>
+<link href="http://127.0.0.1:1234/external.css" rel="stylesheet">
+<style>
+h2 { color: red; }
+</style>
+</head>
+<body>
+<h1>Big Text</h1>
+<h2>Smaller Text</h2>
+</body>
+</html>"#;
+
+    #[derive(Debug, Default)]
+    pub struct CustomStylesheetResolver {
+        hits: Arc<RwLock<usize>>,
+    }
+
+    impl css_inline::StylesheetResolver for CustomStylesheetResolver {
+        fn retrieve(&self, _: &str) -> css_inline::Result<String> {
+            let mut hits = self.hits.write().expect("Lock is poisoned");
+            *hits += 1;
+            Ok("h1 { color: blue; }".to_string())
+        }
+    }
+
+    let hits = Arc::new(RwLock::new(0));
+
+    let inliner = CSSInliner::options()
+        .resolver(Arc::new(CustomStylesheetResolver { hits: hits.clone() }))
+        .cache(StylesheetCache::new(NonZeroUsize::new(3).unwrap()))
+        .build();
+    for _ in 0..5 {
+        let inlined = inliner.inline(html);
+        assert_http(
+            inlined,
+            r#"<body>
+<h1 style="color: blue;">Big Text</h1>
+<h2 style="color: red;">Smaller Text</h2>
+
+</body></html>"#,
+        );
+    }
+
+    let hits = hits.read().expect("Lock is poisoned");
+    assert_eq!(*hits, 1);
+}