selma 0.2.2 → 0.4.10

data/README.md

@@ -76,7 +76,7 @@ attributes: {
 
 # URL handling protocols to allow in specific attributes. By default, no
 # protocols are allowed. Use :relative in place of a protocol if you want
-# to allow relative URLs sans protocol.
+# to allow relative URLs sans protocol. Set to `:all` to allow any protocol.
 protocols: {
     "a" => { "href" => ["http", "https", "mailto", :relative] },
     "img" => { "href" => ["http", "https"] },
@@ -103,7 +103,11 @@ Here's an example which rewrites the `href` attribute on `a` and the `src` attri
 
 ```ruby
 class MatchAttribute
-  SELECTOR = Selma::Selector(match_element: %(a[href^="http:"], img[src^="http:"]"))
+  SELECTOR = Selma::Selector.new(match_element: %(a[href^="http:"], img[src^="http:"]"))
+
+  def selector
+    SELECTOR
+  end
 
   def handle_element(element)
     if element.tag_name == "a"
@@ -130,7 +134,6 @@ The `Selma::Selector` object has three possible kwargs:
 Here's an example for `handle_text_chunk` which changes strings in various elements which are _not_ `pre` or `code`:
 
 ```ruby
-
 class MatchText
   SELECTOR = Selma::Selector.new(match_text_within: "*", ignore_text_within: ["pre", "code"])
 
@@ -176,40 +179,145 @@ The `element` argument in `handle_element` has the following methods:
 - `after(content, as: content_type)`: Inserts `content` after the text. `content_type` is either `:text` or `:html` and determines how the content will be applied.
 - `replace(content, as: content_type)`: Replaces the text node with `content`. `content_type` is either `:text` or `:html` and determines how the content will be applied.
 
+## Security
+
+Theoretically, a malicious user can provide a very large document for processing, which can exhaust the memory of the host machine. To set a limit on how much string content is processed at once, you can provide `memory` options:
+
+```ruby
+Selma::Rewriter.new(options: { memory: { max_allowed_memory_usage: 1_000_000 } }) # ~1MB
+```
+
+The structure of the `memory` options looks like this:
+
+```ruby
+{
+  memory: {
+    max_allowed_memory_usage: 1000,
+    preallocated_parsing_buffer_size: 100,
+  }
+}
+```
+
+Note that `preallocated_parsing_buffer_size` must always be less than `max_allowed_memory_usage`. See [the`lol_html` project documentation](https://docs.rs/lol_html/1.2.1/lol_html/struct.MemorySettings.html) to learn more about the default values.
+
 ## Benchmarks
 
+When `bundle exec rake benchmark`, two different benchmarks are calculated. Here are those results on my machine.
+
+### Benchmarks for just the sanitization process
+
+Comparing Selma against popular Ruby sanitization gems:
+
+<!-- prettier-ignore-start -->
+<details>
+<pre>
+input size = 25309 bytes, 0.03 MB
+
+ruby 3.3.0 (2023-12-25 revision 5124f9ac75) [arm64-darwin23]
+Warming up --------------------------------------
+sanitize-sm 15.000 i/100ms
+selma-sm 127.000 i/100ms
+Calculating -------------------------------------
+sanitize-sm 157.643 (± 1.9%) i/s - 4.740k in 30.077172s
+selma-sm 1.278k (± 1.5%) i/s - 38.354k in 30.019722s
+
+Comparison:
+selma-sm: 1277.9 i/s
+sanitize-sm: 157.6 i/s - 8.11x slower
+
+input size = 86686 bytes, 0.09 MB
+
+ruby 3.3.0 (2023-12-25 revision 5124f9ac75) [arm64-darwin23]
+Warming up --------------------------------------
+sanitize-md 4.000 i/100ms
+selma-md 33.000 i/100ms
+Calculating -------------------------------------
+sanitize-md 40.034 (± 5.0%) i/s - 1.200k in 30.043322s
+selma-md 332.959 (± 2.1%) i/s - 9.999k in 30.045733s
+
+Comparison:
+selma-md: 333.0 i/s
+sanitize-md: 40.0 i/s - 8.32x slower
+
+input size = 7172510 bytes, 7.17 MB
+
+ruby 3.3.0 (2023-12-25 revision 5124f9ac75) [arm64-darwin23]
+Warming up --------------------------------------
+sanitize-lg 1.000 i/100ms
+selma-lg 1.000 i/100ms
+Calculating -------------------------------------
+sanitize-lg 0.141 (± 0.0%) i/s - 5.000 in 35.426127s
+selma-lg 3.963 (± 0.0%) i/s - 119.000 in 30.037386s
+
+Comparison:
+selma-lg: 4.0 i/s
+sanitize-lg: 0.1 i/s - 28.03x slower
+
+</pre>
+</details>
+<!-- prettier-ignore-end -->
+
+### Benchmarks for just the rewriting process
+
+Comparing Selma against popular Ruby HTML parsing gems:
+
+<!-- prettier-ignore-start -->
 <details>
 <pre>
-ruby test/benchmark.rb
-ruby test/benchmark.rb
+input size = 25309 bytes, 0.03 MB
+
+ruby 3.3.0 (2023-12-25 revision 5124f9ac75) [arm64-darwin23]
 Warming up --------------------------------------
-sanitize-document-huge
-                         1.000  i/100ms
- selma-document-huge     1.000  i/100ms
+nokogiri-sm 79.000 i/100ms
+nokolexbor-sm 295.000 i/100ms
+selma-sm 237.000 i/100ms
 Calculating -------------------------------------
-sanitize-document-huge
-                          0.257  (± 0.0%) i/s -      2.000  in   7.783398s
- selma-document-huge      4.602  (± 0.0%) i/s -     23.000  in   5.002870s
+nokogiri-sm 800.531 (± 2.2%) i/s - 24.016k in 30.016056s
+nokolexbor-sm 3.033k (± 3.6%) i/s - 91.155k in 30.094884s
+selma-sm 2.386k (± 1.6%) i/s - 71.574k in 30.001701s
+
+Comparison:
+nokolexbor-sm: 3033.1 i/s
+selma-sm: 2386.3 i/s - 1.27x slower
+nokogiri-sm: 800.5 i/s - 3.79x slower
+
+input size = 86686 bytes, 0.09 MB
+
+ruby 3.3.0 (2023-12-25 revision 5124f9ac75) [arm64-darwin23]
 Warming up --------------------------------------
-sanitize-document-medium
-                         2.000  i/100ms
-selma-document-medium
-                        22.000  i/100ms
+nokogiri-md 8.000 i/100ms
+nokolexbor-md 43.000 i/100ms
+selma-md 38.000 i/100ms
 Calculating -------------------------------------
-sanitize-document-medium
-                         28.676  (± 3.5%) i/s -    144.000  in   5.024669s
-selma-document-medium
-                        121.500  (±22.2%) i/s -    594.000  in   5.135410s
+nokogiri-md 85.013 (± 8.2%) i/s - 2.024k in 52.257472s
+nokolexbor-md 416.074 (±11.1%) i/s - 12.341k in 30.111613s
+selma-md 361.471 (± 4.7%) i/s - 10.830k in 30.033997s
+
+Comparison:
+nokolexbor-md: 416.1 i/s
+selma-md: 361.5 i/s - same-ish: difference falls within error
+nokogiri-md: 85.0 i/s - 4.89x slower
+
+input size = 7172510 bytes, 7.17 MB
+
+ruby 3.3.0 (2023-12-25 revision 5124f9ac75) [arm64-darwin23]
 Warming up --------------------------------------
-sanitize-document-small
-                        10.000  i/100ms
-selma-document-small    20.000  i/100ms
+nokogiri-lg 1.000 i/100ms
+nokolexbor-lg 1.000 i/100ms
+selma-lg 1.000 i/100ms
 Calculating -------------------------------------
-sanitize-document-small
-                        107.280  (± 0.9%) i/s -    540.000  in   5.033850s
-selma-document-small    118.867  (±31.1%) i/s -    540.000  in   5.080726s
+nokogiri-lg 0.805 (± 0.0%) i/s - 25.000 in 31.148730s
+nokolexbor-lg 2.194 (± 0.0%) i/s - 66.000 in 30.278108s
+selma-lg 5.541 (± 0.0%) i/s - 166.000 in 30.037197s
+
+Comparison:
+selma-lg: 5.5 i/s
+nokolexbor-lg: 2.2 i/s - 2.53x slower
+nokogiri-lg: 0.8 i/s - 6.88x slower
+
 </pre>
 </details>
+<!-- prettier-ignore-end -->
 
 ## Contributing
 

data/ext/selma/Cargo.toml

@@ -6,10 +6,13 @@ rust-version = "1.75.0"
 publish = false
 
 [dependencies]
-enum-iterator = "1.4"
+enum-iterator = "2.1"
 escapist = "0.0.2"
-magnus = "0.6"
-lol_html = "1.2"
+magnus = { version = "0.7", features = ["rb-sys"] }
+rb-sys = { version = "*", default-features = false, features = [
+    "stable-api-compiled-fallback",
+] }
+lol_html = "2.0"
 
 [lib]
 name = "selma"

data/ext/selma/src/html/element.rs

@@ -1,3 +1,5 @@
+use std::cell::RefCell;
+
 use crate::native_ref_wrap::NativeRefWrap;
 use lol_html::html_content::Element;
 use magnus::{exception, method, Error, Module, RArray, RClass, RHash, RString, Value};
@@ -8,16 +10,14 @@ struct HTMLElement {
 }
 
 #[magnus::wrap(class = "Selma::HTML::Element")]
-pub struct SelmaHTMLElement(std::cell::RefCell<HTMLElement>);
+pub struct SelmaHTMLElement(RefCell<HTMLElement>);
 
 /// SAFETY: This is safe because we only access this data when the GVL is held.
 unsafe impl Send for SelmaHTMLElement {}
 
 impl SelmaHTMLElement {
-    pub fn new(element: &mut Element, ancestors: &[String]) -> Self {
-        let (ref_wrap, _anchor) = NativeRefWrap::wrap_mut(element);
-
-        Self(std::cell::RefCell::new(HTMLElement {
+    pub fn new(ref_wrap: NativeRefWrap<Element<'static, 'static>>, ancestors: &[String]) -> Self {
+        Self(RefCell::new(HTMLElement {
             element: ref_wrap,
             ancestors: ancestors.to_owned(),
         }))
@@ -26,13 +26,12 @@ impl SelmaHTMLElement {
     fn tag_name(&self) -> Result<String, Error> {
         let binding = self.0.borrow();
 
-        if let Ok(e) = binding.element.get() {
-            Ok(e.tag_name())
-        } else {
-            Err(Error::new(
+        match binding.element.get() {
+            Ok(e) => Ok(e.tag_name().to_string()),
+            Err(_) => Err(Error::new(
                 exception::runtime_error(),
                 "`tag_name` is not available",
-            ))
+            )),
         }
     }
 
@@ -119,11 +118,13 @@ impl SelmaHTMLElement {
                 .iter()
                 .for_each(|attr| match hash.aset(attr.name(), attr.value()) {
                     Ok(_) => {}
-                    Err(err) => Err(Error::new(
-                        exception::runtime_error(),
-                        format!("AttributeNameError: {err:?}"),
-                    ))
-                    .unwrap(),
+                    Err(err) => panic!(
+                        "{:?}",
+                        Error::new(
+                            exception::runtime_error(),
+                            format!("AttributeNameError: {err:?}"),
+                        )
+                    ),
                 });
         }
         Ok(hash)
@@ -139,7 +140,10 @@ impl SelmaHTMLElement {
             .for_each(|ancestor| match array.push(RString::new(ancestor)) {
                 Ok(_) => {}
                 Err(err) => {
-                    Err(Error::new(exception::runtime_error(), format!("{err:?}"))).unwrap()
+                    panic!(
+                        "{:?}",
+                        Error::new(exception::runtime_error(), format!("{err:?}"))
+                    )
                 }
             });
 
@@ -224,24 +228,25 @@ impl SelmaHTMLElement {
         }
     }
 
-    fn remove_and_keep_content(&self) {
-        let mut binding = self.0.borrow_mut();
-
-        if let Ok(e) = binding.element.get_mut() {
-            e.remove_and_keep_content()
-        }
+    fn remove_and_keep_content(&self) -> Result<(), Error> {
+        self.0
+            .borrow_mut()
+            .element
+            .get_mut()
+            .unwrap()
+            .remove_and_keep_content();
+        Ok(())
     }
 
     fn is_removed(&self) -> Result<bool, Error> {
         let binding = self.0.borrow();
 
-        if let Ok(e) = binding.element.get() {
-            Ok(e.removed())
-        } else {
-            Err(Error::new(
+        match binding.element.get() {
+            Ok(e) => Ok(e.removed()),
+            Err(_) => Err(Error::new(
                 exception::runtime_error(),
                 "`is_removed` is not available",
-            ))
+            )),
         }
     }
 }

data/ext/selma/src/html/end_tag.rs

@@ -1,3 +1,5 @@
+use std::cell::RefCell;
+
 use crate::native_ref_wrap::NativeRefWrap;
 use lol_html::html_content::EndTag;
 use magnus::{method, Error, Module, RClass};
@@ -7,16 +9,14 @@ struct HTMLEndTag {
 }
 
 #[magnus::wrap(class = "Selma::HTML::EndTag")]
-pub struct SelmaHTMLEndTag(std::cell::RefCell<HTMLEndTag>);
+pub struct SelmaHTMLEndTag(RefCell<HTMLEndTag>);
 
 /// SAFETY: This is safe because we only access this data when the GVL is held.
 unsafe impl Send for SelmaHTMLEndTag {}
 
 impl SelmaHTMLEndTag {
-    pub fn new(end_tag: &mut EndTag) -> Self {
-        let (ref_wrap, _anchor) = NativeRefWrap::wrap(end_tag);
-
-        Self(std::cell::RefCell::new(HTMLEndTag { end_tag: ref_wrap }))
+    pub fn new(ref_wrap: NativeRefWrap<EndTag<'static>>) -> Self {
+        Self(RefCell::new(HTMLEndTag { end_tag: ref_wrap }))
     }
 
     fn tag_name(&self) -> String {

data/ext/selma/src/html/text_chunk.rs

@@ -1,23 +1,44 @@
+use std::cell::RefCell;
+
 use crate::native_ref_wrap::NativeRefWrap;
 use lol_html::html_content::{TextChunk, TextType};
 use magnus::{exception, method, Error, Module, RClass, Symbol, Value};
 
 struct HTMLTextChunk {
     text_chunk: NativeRefWrap<TextChunk<'static>>,
+    buffer: String,
+}
+
+macro_rules! clone_buffer_if_not_empty {
+    ($binding:expr, $buffer:expr) => {
+        if !$binding.buffer.is_empty() {
+            $buffer.clone_from(&$binding.buffer);
+        }
+    };
+}
+
+// if this is the first time we're processing this text chunk (buffer is empty),
+// we carry on. Otherwise, we need to use the buffer text, not the text chunk,
+// because lol-html is not designed in such a way to keep track of text chunks.
+macro_rules! set_text_chunk_to_buffer {
+    ($text_chunk:expr, $buffer:expr) => {
+        if !$buffer.is_empty() {
+            $text_chunk.set_str($buffer);
+        }
+    };
 }
 
 #[magnus::wrap(class = "Selma::HTML::TextChunk")]
-pub struct SelmaHTMLTextChunk(std::cell::RefCell<HTMLTextChunk>);
+pub struct SelmaHTMLTextChunk(RefCell<HTMLTextChunk>);
 
 /// SAFETY: This is safe because we only access this data when the GVL is held.
 unsafe impl Send for SelmaHTMLTextChunk {}
 
 impl SelmaHTMLTextChunk {
-    pub fn new(text_chunk: &mut TextChunk) -> Self {
-        let (ref_wrap, _anchor) = NativeRefWrap::wrap_mut(text_chunk);
-
-        Self(std::cell::RefCell::new(HTMLTextChunk {
+    pub fn new(ref_wrap: NativeRefWrap<TextChunk<'static>>) -> Self {
+        Self(RefCell::new(HTMLTextChunk {
             text_chunk: ref_wrap,
+            buffer: String::new(),
         }))
     }
 
@@ -54,7 +75,19 @@ impl SelmaHTMLTextChunk {
         }
     }
 
-    fn before(&self, args: &[Value]) -> Result<(), Error> {
+    fn is_removed(&self) -> Result<bool, Error> {
+        let binding = self.0.borrow();
+
+        match binding.text_chunk.get() {
+            Ok(tc) => Ok(tc.removed()),
+            Err(_) => Err(Error::new(
+                exception::runtime_error(),
+                "`is_removed` is not available",
+            )),
+        }
+    }
+
+    fn before(&self, args: &[Value]) -> Result<String, Error> {
         let mut binding = self.0.borrow_mut();
         let text_chunk = binding.text_chunk.get_mut().unwrap();
 
@@ -65,10 +98,10 @@ impl SelmaHTMLTextChunk {
 
         text_chunk.before(&text_str, content_type);
 
-        Ok(())
+        Ok(text_chunk.as_str().to_string())
     }
 
-    fn after(&self, args: &[Value]) -> Result<(), Error> {
+    fn after(&self, args: &[Value]) -> Result<String, Error> {
         let mut binding = self.0.borrow_mut();
         let text_chunk = binding.text_chunk.get_mut().unwrap();
 
@@ -79,21 +112,30 @@ impl SelmaHTMLTextChunk {
 
         text_chunk.after(&text_str, content_type);
 
-        Ok(())
+        Ok(text_chunk.as_str().to_string())
     }
 
-    fn replace(&self, args: &[Value]) -> Result<(), Error> {
+    fn replace(&self, args: &[Value]) -> Result<String, Error> {
         let mut binding = self.0.borrow_mut();
+        let mut buffer = String::new();
+
+        clone_buffer_if_not_empty!(binding, buffer);
+
         let text_chunk = binding.text_chunk.get_mut().unwrap();
 
+        set_text_chunk_to_buffer!(text_chunk, buffer);
+
         let (text_str, content_type) = match crate::scan_text_args(args) {
             Ok((text_str, content_type)) => (text_str, content_type),
             Err(err) => return Err(err),
         };
-
         text_chunk.replace(&text_str, content_type);
 
-        Ok(())
+        text_chunk.set_str(text_str.clone());
+
+        binding.buffer = text_chunk.as_str().to_string();
+
+        Ok(text_str)
     }
 }
 
@@ -108,6 +150,7 @@ pub fn init(c_html: RClass) -> Result<(), Error> {
     c_text_chunk.define_method("before", method!(SelmaHTMLTextChunk::before, -1))?;
     c_text_chunk.define_method("after", method!(SelmaHTMLTextChunk::after, -1))?;
     c_text_chunk.define_method("replace", method!(SelmaHTMLTextChunk::replace, -1))?;
+    c_text_chunk.define_method("removed?", method!(SelmaHTMLTextChunk::is_removed, 0))?;
 
     Ok(())
 }

data/ext/selma/src/native_ref_wrap.rs

@@ -1,15 +1,18 @@
-use std::{cell::Cell, marker::PhantomData, rc::Rc};
+use std::{
+    marker::PhantomData,
+    sync::{Arc, Mutex},
+};
 
-// NOTE: My Rust isn't good enough to know what any of this does,
-// but it was taken from https://github.com/cloudflare/lol-html/blob/1a1ab2e2bf896f815fe8888ed78ccdf46d7c6b85/js-api/src/lib.rs#LL38
+// NOTE: this was inspired from
+// https://github.com/worker-tools/html-rewriter-wasm/blob/92bafdfa34c809c37036f57cb282184cada3bbc9/src/handlers.rs
 
 pub struct Anchor<'r> {
-    poisoned: Rc<Cell<bool>>,
+    poisoned: Arc<Mutex<bool>>,
     lifetime: PhantomData<&'r mut ()>,
 }
 
 impl<'r> Anchor<'r> {
-    pub fn new(poisoned: Rc<Cell<bool>>) -> Self {
+    pub fn new(poisoned: Arc<Mutex<bool>>) -> Self {
         Anchor {
             poisoned,
             lifetime: PhantomData,
@@ -17,44 +20,46 @@ impl<'r> Anchor<'r> {
     }
 }
 
-// impl Drop for Anchor<'_> {
-//     fn drop(&mut self) {
-//         self.poisoned.replace(true);
-//     }
-// }
+impl Drop for Anchor<'_> {
+    fn drop(&mut self) {
+        *self.poisoned.lock().unwrap() = true;
+    }
+}
 
-// NOTE: wasm_bindgen doesn't allow structures with lifetimes. To workaround that
-// we create a wrapper that erases all the lifetime information from the inner reference
+// NOTE: So far as I understand it, there's no great way to work between lol_html's lifetimes and FFI.
+// To work around that, we create a wrapper that erases all the lifetime information from the inner reference
 // and provides an anchor object that keeps track of the lifetime in the runtime.
 //
 // When anchor goes out of scope, wrapper becomes poisoned and any attempt to get inner
 // object results in exception.
+#[derive(Clone)]
 pub struct NativeRefWrap<R> {
     inner_ptr: *mut R,
-    poisoned: Rc<Cell<bool>>,
+    poisoned: Arc<Mutex<bool>>,
 }
 
 impl<R> NativeRefWrap<R> {
-    pub fn wrap<I>(inner: &I) -> (Self, Anchor) {
+    pub fn wrap<I>(inner: &mut I) -> (Self, Anchor) {
         let wrap = NativeRefWrap {
-            inner_ptr: inner as *const I as *mut R,
-            poisoned: Rc::new(Cell::new(false)),
+            inner_ptr: inner as *mut I as *mut R,
+            poisoned: Arc::new(Mutex::new(false)),
         };
 
-        let anchor = Anchor::new(Rc::clone(&wrap.poisoned));
+        let anchor = Anchor::new(Arc::clone(&wrap.poisoned));
 
         (wrap, anchor)
     }
 
-    pub fn wrap_mut<I>(inner: &mut I) -> (Self, Anchor) {
-        let wrap = NativeRefWrap {
-            inner_ptr: inner as *mut I as *mut R,
-            poisoned: Rc::new(Cell::new(false)),
-        };
-
-        let anchor = Anchor::new(Rc::clone(&wrap.poisoned));
+    fn assert_not_poisoned(&self) -> Result<(), &'static str> {
+        if self.is_poisoned() {
+            Err("The object has been freed and can't be used anymore.")
+        } else {
+            Ok(())
+        }
+    }
 
-        (wrap, anchor)
+    pub fn is_poisoned(&self) -> bool {
+        *self.poisoned.lock().unwrap()
     }
 
     pub fn get(&self) -> Result<&R, &'static str> {
@@ -68,12 +73,4 @@ impl<R> NativeRefWrap<R> {
 
         Ok(unsafe { self.inner_ptr.as_mut() }.unwrap())
     }
-
-    fn assert_not_poisoned(&self) -> Result<(), &'static str> {
-        if self.poisoned.get() {
-            Err("The object has been freed and can't be used anymore.")
-        } else {
-            Ok(())
-        }
-    }
 }