feat: External stylesheet caching

Ref: #314
Signed-off-by: Dmitry Dygalo <[email protected]>

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)
+- Optionally caches 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.
@@ -99,6 +100,7 @@ fn main() -> css_inline::Result<()> {
 - `keep_link_tags`. Specifies whether to keep "link" tags after inlining. Default: `false`
 - `base_url`. The base URL used to resolve relative URLs. If you'd like to load stylesheets from your filesystem, use the `file://` scheme. Default: `None`
 - `load_remote_stylesheets`. Specifies whether remote stylesheets should be loaded. Default: `true`
+- `cache`. Specifies cache for external stylesheets. Default: `None`
 - `extra_css`. Extra CSS to be inlined. Default: `None`
 - `preallocate_node_capacity`. **Advanced**. Preallocates capacity for HTML nodes during parsing. This can improve performance when you have an estimate of the number of nodes in your HTML document. Default: `32`
 
@@ -177,6 +179,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)
+- Optionally caches external stylesheets
 - Works on Linux, Windows, and macOS
 - Supports HTML5 & CSS3
 
@@ -112,6 +113,7 @@ Possible configurations:
 - `keep_link_tags`. Specifies whether to keep "link" tags after inlining. Default: `false`
 - `base_url`. The base URL used to resolve relative URLs. If you'd like to load stylesheets from your filesystem, use the `file://` scheme. Default: `NULL`
 - `load_remote_stylesheets`. Specifies whether remote stylesheets should be loaded. Default: `true`
+- `cache`. Specifies caching options for external stylesheets. Default: `NULL` - TODO
 - `extra_css`. Extra CSS to be inlined. Default: `NULL`
 - `preallocate_node_capacity`. **Advanced**. Preallocates capacity for HTML nodes during parsing. This can improve performance when you have an estimate of the number of nodes in your HTML document. Default: `32`
 

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)
+- Optionally caches external stylesheets
 - Works on Linux, Windows, and macOS
 - Supports HTML5 & CSS3
 - Tested on Node.js 18 & 20.
@@ -82,6 +83,7 @@ var inlined = inline(
 - `keepLinkTags`. Specifies whether to keep "link" tags after inlining. Default: `false`
 - `baseUrl`. The base URL used to resolve relative URLs. If you'd like to load stylesheets from your filesystem, use the `file://` scheme. Default: `null`
 - `loadRemoteStylesheets`. Specifies whether remote stylesheets should be loaded. Default: `true`
+- `cache`. Specifies caching options for external stylesheets (for example, `{size: 5}`). Default: `null`
 - `extraCss`. Extra CSS to be inlined. Default: `null`
 - `preallocateNodeCapacity`. **Advanced**. Preallocates capacity for HTML nodes during parsing. This can improve performance when you have an estimate of the number of nodes in your HTML document. Default: `32`
 

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)
+- Optionally caches external stylesheets
 - Can process multiple documents in parallel
 - Works on Linux, Windows, and macOS
 - Supports HTML5 & CSS3
@@ -117,6 +118,7 @@ inliner.inline("...")
 - `keep_link_tags`. Specifies whether to keep "link" tags after inlining. Default: `False`
 - `base_url`. The base URL used to resolve relative URLs. If you'd like to load stylesheets from your filesystem, use the `file://` scheme. Default: `None`
 - `load_remote_stylesheets`. Specifies whether remote stylesheets should be loaded. Default: `True`
+- `cache`. Specifies caching options for external stylesheets (for example, `{"size": 5}`). Default: `null`
 - `extra_css`. Extra CSS to be inlined. Default: `None`
 - `preallocate_node_capacity`. **Advanced**. Preallocates capacity for HTML nodes during parsing. This can improve performance when you have an estimate of the number of nodes in your HTML document. Default: `32`
 

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)
+- Optionally caches external stylesheets
 - Can process multiple documents in parallel
 - Works on Linux, Windows, and macOS
 - Supports HTML5 & CSS3
@@ -98,6 +99,7 @@ inliner.inline("...")
 - `keep_link_tags`. Specifies whether to keep "link" tags after inlining. Default: `False`
 - `base_url`. The base URL used to resolve relative URLs. If you'd like to load stylesheets from your filesystem, use the `file://` scheme. Default: `nil`
 - `load_remote_stylesheets`. Specifies whether remote stylesheets should be loaded. Default: `True`
+- `cache`. Specifies caching options for external stylesheets (for example, `{size => 5}`). Default: `null`
 - `extra_css`. Extra CSS to be inlined. Default: `nil`
 - `preallocate_node_capacity`. **Advanced**. Preallocates capacity for HTML nodes during parsing. This can improve performance when you have an estimate of the number of nodes in your HTML document. Default: `32`
 

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,6 +35,8 @@ mod resolver;
 
 pub use error::InlineError;
 use indexmap::IndexMap;
+#[cfg(feature = "stylesheet-cache")]
+use lru::{DefaultHasher, LruCache};
 use std::{borrow::Cow, fmt::Formatter, hash::BuildHasherDefault, io::Write, sync::Arc};
 
 use crate::html::ElementStyleMap;
@@ -43,6 +45,10 @@ use html::Document;
 pub use resolver::{DefaultStylesheetResolver, StylesheetResolver};
 pub use url::{ParseError, Url};
 
+/// An LRU Cache for external stylesheets.
+#[cfg(feature = "stylesheet-cache")]
+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 +65,9 @@ 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.
+    #[cfg(feature = "stylesheet-cache")]
+    pub cache: Option<std::sync::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
@@ -73,12 +82,18 @@ pub struct InlineOptions<'a> {
 
 impl<'a> std::fmt::Debug for InlineOptions<'a> {
     fn fmt(&self, f: &mut Formatter<'_>) -> std::fmt::Result {
-        f.debug_struct("InlineOptions")
+        let mut debug = f.debug_struct("InlineOptions");
+        debug
             .field("inline_style_tags", &self.inline_style_tags)
             .field("keep_style_tags", &self.keep_style_tags)
             .field("keep_link_tags", &self.keep_link_tags)
             .field("base_url", &self.base_url)
-            .field("load_remote_stylesheets", &self.load_remote_stylesheets)
+            .field("load_remote_stylesheets", &self.load_remote_stylesheets);
+        #[cfg(feature = "stylesheet-cache")]
+        {
+            debug.field("cache", &self.cache);
+        }
+        debug
             .field("extra_css", &self.extra_css)
             .field("preallocate_node_capacity", &self.preallocate_node_capacity)
             .finish_non_exhaustive()
@@ -121,6 +136,18 @@ impl<'a> InlineOptions<'a> {
         self
     }
 
+    /// Set external stylesheet cache.
+    #[must_use]
+    #[cfg(feature = "stylesheet-cache")]
+    pub fn cache(mut self, cache: impl Into<Option<StylesheetCache>>) -> Self {
+        if let Some(cache) = cache.into() {
+            self.cache = Some(std::sync::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 +185,8 @@ impl Default for InlineOptions<'_> {
             keep_link_tags: false,
             base_url: None,
             load_remote_stylesheets: true,
+            #[cfg(feature = "stylesheet-cache")]
+            cache: None,
             extra_css: None,
             preallocate_node_capacity: 32,
             resolver: Arc::new(DefaultStylesheetResolver),
@@ -247,7 +276,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 +320,25 @@ impl<'a> CSSInliner<'a> {
             links.dedup();
             for href in &links {
                 let url = self.get_full_url(href);
+                #[cfg(feature = "stylesheet-cache")]
+                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');
+
+                #[cfg(feature = "stylesheet-cache")]
+                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 +466,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

@@ -62,6 +62,9 @@ OPTIONS:
     --load-remote-stylesheets
         Whether remote stylesheets should be loaded or not.
 
+    --no-cache
+        Disable caching of remote stylesheets.
+
     --extra-css
         Additional CSS to inline.
 
@@ -79,6 +82,8 @@ OPTIONS:
         extra_css: Option<String>,
         output_filename_prefix: Option<OsString>,
         load_remote_stylesheets: bool,
+        #[cfg(feature = "stylesheet-cache")]
+        no_cache: bool,
         files: Vec<String>,
     }
 
@@ -117,6 +122,8 @@ OPTIONS:
             extra_css: args.opt_value_from_str("--extra-css")?,
             output_filename_prefix: args.opt_value_from_str("--output-filename-prefix")?,
             load_remote_stylesheets: args.contains("--load-remote-stylesheets"),
+            #[cfg(feature = "stylesheet-cache")]
+            no_cache: args.contains("--no-cache"),
             files: args.free()?,
         };
         let base_url = match parse_url(args.base_url) {
@@ -132,6 +139,16 @@ OPTIONS:
             keep_link_tags: args.keep_link_tags,
             base_url,
             load_remote_stylesheets: args.load_remote_stylesheets,
+            #[cfg(feature = "stylesheet-cache")]
+            cache: {
+                if args.no_cache {
+                    None
+                } else {
+                    Some(std::sync::Mutex::new(css_inline::StylesheetCache::new(
+                        std::num::NonZeroUsize::new(5).expect("Invalid cache size"),
+                    )))
+                }
+            },
             extra_css: args.extra_css.as_deref().map(Cow::Borrowed),
             preallocate_node_capacity: 32,
             resolver: Arc::new(DefaultStylesheetResolver),