selma 0.2.2-x86_64-darwin → 0.4.1-x86_64-darwin

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: da44321197848529fd6fb90ec2b6265f17441d380efa47fd5836492d9ef616fb
-  data.tar.gz: 17e40218b475fda8e86dc160b04b5259ce2978c92ec4677cbf8b0e4db0f82b36
+  metadata.gz: 61454a1a26fdd81111379af2a15a22d58219c705e7d8af31dcfd495cbba7bb15
+  data.tar.gz: 8b37a785ccab776ba5c5a278fd8a548d3d72846b561fef5c1bb807d5d748eab4
 SHA512:
-  metadata.gz: 6f0174d4954d0e4f22fe0e89239bee643ea24f6c9c05652b2ce79935bf30529b74fcb66ba96eb6b4f4fbc56c1f3a44557d77033ee7fc47952deda885430bc6e3
-  data.tar.gz: eb7c917db6fc9085db53879fac0c5b1cc4843ca37c5931199e1fcf3f8e12da64959cf30fbf276f0bac8cc1da8f665e22c87621a12b15c5c9160f6d5d95867ec7
+  metadata.gz: 235dc124ab1faf1c3713d2f67b3a6ccc7c134791b4ca8613be8deaa7da9c7953042d8f2bceab5157bbc4893c0a7c4455a1b4c594e001d41b13049a671ad0bf28
+  data.tar.gz: 47c5f830c2ed780afd21e222e6a521b84e1deb84309e75c6a7a8d477d1a0f80684894403bff6bd83f517fef126a5900434e7cd98d450ec190d39f11cc8064450

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"
@@ -176,40 +180,142 @@ 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>
-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
+         sanitize-sm    15.000 i/100ms
+            selma-sm   127.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
+         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-document-medium
-                         2.000  i/100ms
-selma-document-medium
-                        22.000  i/100ms
+         sanitize-md     4.000 i/100ms
+            selma-md    33.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
+         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>
+input size = 25309 bytes, 0.03 MB
+
+ruby 3.3.0 (2023-12-25 revision 5124f9ac75) [arm64-darwin23]
+Warming up --------------------------------------
+         nokogiri-sm    79.000 i/100ms
+       nokolexbor-sm   295.000 i/100ms
+            selma-sm   237.000 i/100ms
+Calculating -------------------------------------
+         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 --------------------------------------
+         nokogiri-md     8.000 i/100ms
+       nokolexbor-md    43.000 i/100ms
+            selma-md    38.000 i/100ms
+Calculating -------------------------------------
+         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/lib/selma/config.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module Selma
+  module Config
+    OPTIONS = {
+      memory: {
+        max_allowed_memory_usage: nil,
+        preallocated_parsing_buffer_size: nil,
+      },
+    }
+  end
+end

data/lib/selma/sanitizer/config/default.rb

@@ -28,7 +28,7 @@ module Selma
 
         # 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: {},
 
         # An Array of element names whose contents will be removed. The contents

data/lib/selma/sanitizer/config/relaxed.rb

@@ -16,6 +16,7 @@ module Selma
           "colgroup",
           "data",
           "del",
+          "details",
           "div",
           "figcaption",
           "figure",

data/lib/selma/sanitizer.rb

@@ -66,7 +66,12 @@ module Selma
     end
 
     def allow_protocol(element, attr, protos)
-      protos = [protos] unless protos.is_a?(Array)
+      if protos.is_a?(Array)
+        raise ArgumentError, "`:all` must be passed outside of an array" if protos.include?(:all)
+      else
+        protos = [protos]
+      end
+
       set_allowed_protocols(element, attr, protos)
     end
 

data/lib/selma/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Selma
-  VERSION = "0.2.2"
+  VERSION = "0.4.1"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: selma
 version: !ruby/object:Gem::Version
-  version: 0.2.2
+  version: 0.4.1
 platform: x86_64-darwin
 authors:
 - Garen J. Torikian
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2024-01-03 00:00:00.000000000 Z
+date: 2024-07-15 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rake
@@ -51,6 +51,7 @@ files:
 - lib/selma/3.1/selma.bundle
 - lib/selma/3.2/selma.bundle
 - lib/selma/3.3/selma.bundle
+- lib/selma/config.rb
 - lib/selma/extension.rb
 - lib/selma/html.rb
 - lib/selma/rewriter.rb