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/Cargo.toml

@@ -35,7 +35,7 @@ serde = { version = "1", features = ["derive"], default-features = false }
 path = "../../css-inline"
 version = "*"
 default-features = false
-features = ["http", "file"]
+features = ["http", "file", "stylesheet-cache"]
 
 [target.'cfg(target_arch = "wasm32")'.dependencies.css-inline]
 path = "../../css-inline"

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`
 
@@ -125,6 +127,29 @@ This is useful if you want to keep `@media` queries for responsive emails in sep
 
 Such tags will be kept in the resulting HTML even if the `keep_style_tags` option is set to `false`.
 
+You can also cache external stylesheets to avoid excessive network requests:
+
+```typescript
+import { inline } from "@css-inline/css-inline";
+
+var inlined = inline(
+  `
+  <html>
+    <head>
+      <link href="http://127.0.0.1:1234/external.css" rel="stylesheet">
+      <style>h1 { color:red }</style>
+    </head>
+    <body>
+      <h1>Test</h1>
+    </body>
+  </html>
+  `,
+  { cache: { size: 5 } },
+);
+```
+
+Caching is disabled by default.
+
 ## WebAssembly
 
 `css-inline` also ships a WebAssembly module built with `wasm-bindgen` to run in browsers.
@@ -148,7 +173,7 @@ Such tags will be kept in the resulting HTML even if the `keep_style_tags` optio
 </script>
 ```
 
-**NOTE**: WASM module currently lacks support for fetching stylesheets from network or filesystem.
+**NOTE**: WASM module currently lacks support for fetching stylesheets from network or filesystem and caching.
 
 ## Performance
 

bindings/javascript/__test__/index.spec.ts

@@ -132,3 +132,33 @@ h2 { color: red; }
     inlinedHtml,
   );
 });
+
+test("cache external stylesheets", (t) => {
+  t.is(
+    inline(
+      `<html>
+<head>
+<link href="http://127.0.0.1:1234/external.css" rel="stylesheet">
+<link rel="alternate" type="application/rss+xml" title="RSS" href="/rss.xml">
+<style>
+h2 { color: red; }
+</style>
+</head>
+<body>
+<h1>Big Text</h1>
+<h2>Smaller Text</h2>
+</body>
+</html>`,
+      { cache: { size: 5 } },
+    ),
+    inlinedHtml,
+  );
+});
+
+test("invalid cache size", (t) => {
+  const error = t.throws(() => {
+    inline("", { cache: { size: 0 } });
+  });
+  t.is(error.code, "GenericFailure");
+  t.is(error.message, "Cache size must be an integer greater than zero");
+});

bindings/javascript/js-binding.d.ts

@@ -3,6 +3,10 @@
 
 /* auto-generated by NAPI-RS */
 
+export interface StylesheetCache {
+  /** Cache size. */
+  size: number
+}
 export interface Options {
   /**
    * Whether to inline CSS from "style" tags.
@@ -19,6 +23,8 @@ export interface Options {
   baseUrl?: string
   /** Whether remote stylesheets should be loaded or not. */
   loadRemoteStylesheets?: boolean
+  /** An LRU Cache for external stylesheets. */
+  cache?: StylesheetCache
   /** Additional CSS to inline. */
   extraCss?: string
   /**

bindings/javascript/src/options.rs

@@ -13,6 +13,15 @@ fn parse_url(url: Option<String>) -> std::result::Result<Option<css_inline::Url>
     })
 }
 
+#[cfg(not(target_arch = "wasm32"))]
+#[cfg_attr(not(target_arch = "wasm32"), napi(object))]
+#[allow(clippy::struct_excessive_bools)]
+#[derive(Debug, Default)]
+pub struct StylesheetCache {
+    /// Cache size.
+    pub size: u32,
+}
+
 #[cfg_attr(
     target_arch = "wasm32",
     derive(serde::Deserialize),
@@ -35,6 +44,9 @@ pub struct Options {
     pub base_url: Option<String>,
     /// Whether remote stylesheets should be loaded or not.
     pub load_remote_stylesheets: Option<bool>,
+    #[cfg(not(target_arch = "wasm32"))]
+    /// An LRU Cache for external stylesheets.
+    pub cache: Option<StylesheetCache>,
     /// Additional CSS to inline.
     pub extra_css: Option<String>,
     /// Pre-allocate capacity for HTML nodes during parsing.
@@ -53,6 +65,22 @@ impl TryFrom<Options> for css_inline::InlineOptions<'_> {
             base_url: parse_url(value.base_url)?,
             load_remote_stylesheets: value.load_remote_stylesheets.unwrap_or(true),
             extra_css: value.extra_css.map(Cow::Owned),
+            #[cfg(not(target_arch = "wasm32"))]
+            cache: {
+                if let Some(cache) = value.cache {
+                    let size =
+                        std::num::NonZeroUsize::new(cache.size as usize).ok_or_else(|| {
+                            let reason =
+                                "Cache size must be an integer greater than zero".to_string();
+                            napi::Error::from_reason(reason)
+                        })?;
+                    Some(std::sync::Mutex::new(css_inline::StylesheetCache::new(
+                        size,
+                    )))
+                } else {
+                    None
+                }
+            },
             preallocate_node_capacity: if let Some(capacity) = value.preallocate_node_capacity {
                 usize::try_from(capacity).map_err(|_| {
                     let reason = "Invalid capacity".to_string();

bindings/javascript/wasm/index.js

@@ -33,18 +33,6 @@ heap.push(void 0, null, true, false);
 function getObject(idx) {
   return heap[idx];
 }
-var heap_next = heap.length;
-function dropObject(idx) {
-  if (idx < 132)
-    return;
-  heap[idx] = heap_next;
-  heap_next = idx;
-}
-function takeObject(idx) {
-  const ret = getObject(idx);
-  dropObject(idx);
-  return ret;
-}
 var WASM_VECTOR_LEN = 0;
 var cachedUint8Memory0 = null;
 function getUint8Memory0() {
@@ -116,6 +104,7 @@ function getStringFromWasm0(ptr, len) {
   ptr = ptr >>> 0;
   return cachedTextDecoder.decode(getUint8Memory0().subarray(ptr, ptr + len));
 }
+var heap_next = heap.length;
 function addHeapObject(obj) {
   if (heap_next === heap.length)
     heap.push(heap.length + 1);
@@ -124,6 +113,17 @@ function addHeapObject(obj) {
   heap[idx] = obj;
   return idx;
 }
+function dropObject(idx) {
+  if (idx < 132)
+    return;
+  heap[idx] = heap_next;
+  heap_next = idx;
+}
+function takeObject(idx) {
+  const ret = getObject(idx);
+  dropObject(idx);
+  return ret;
+}
 var cachedFloat64Memory0 = null;
 function getFloat64Memory0() {
   if (cachedFloat64Memory0 === null || cachedFloat64Memory0.byteLength === 0) {
@@ -261,9 +261,6 @@ function __wbg_get_imports() {
     const ret = getObject(arg0) === void 0;
     return ret;
   };
-  imports.wbg.__wbindgen_object_drop_ref = function(arg0) {
-    takeObject(arg0);
-  };
   imports.wbg.__wbindgen_string_get = function(arg0, arg1) {
     const obj = getObject(arg1);
     const ret = typeof obj === "string" ? obj : void 0;
@@ -306,6 +303,9 @@ function __wbg_get_imports() {
     const ret = +getObject(arg0);
     return ret;
   };
+  imports.wbg.__wbindgen_object_drop_ref = function(arg0) {
+    takeObject(arg0);
+  };
   imports.wbg.__wbg_length_1d25fa9e4ac21ce7 = function(arg0) {
     const ret = getObject(arg0).length;
     return ret;