escape_utils 1.2.0 → 1.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: d21e40641fb15698dc8d2bf394ae9ff766c99b65
-  data.tar.gz: 2e72c13029f33a6cf11fd6980915552e62fa4d6b
+SHA256:
+  metadata.gz: 7b4b256a1ceb8ed2f7e673d5e2081daafb36761d93d3ebe38c6a1b51017f7ed5
+  data.tar.gz: 23de0f72e4df0b9ddf1d6ca0063fcac74696dc7da429f4b8eb5200fb90ba6435
 SHA512:
-  metadata.gz: e095eec1d4b9580837a1d5af995f1c8a400c3dcca7ea1a8b3a4a3079809d4e72166b844b17791ab4c90c828be9d7b52331690f30ba88790f79ff18707ead49d6
-  data.tar.gz: e89851568b2650c982297e6af0ae66d506c165be8ff5a3ea1f158f6665d1e15a567f5219741f5e4ab2a78ae5f503b093e171a600088c446dc487024224e9202f
+  metadata.gz: 0d009060659e31a0d82073d8d6f870b174fc7647c34686d1168ac65bb6abf066043fb568c161850fb90a00ca0f0e55151874e0509089d62e92fb7c97d2187534
+  data.tar.gz: 6395d5b453930debba5b6eee4f5cc2440f2fc72f01d27c45987ecdcb461ff0edfd6ae15935f8ec9f50b010f5f4afcd4e419ee10a2bcdb995652b8be5688a316a

data/.github/workflows/ci.yml

@@ -0,0 +1,43 @@
+name: CI
+
+on: [push, pull_request]
+
+jobs:
+  rubies:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        ruby: [ ruby-head, '3.1', '3.0', '2.7', '2.6', '2.5' ]
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v2
+      - name: Set up Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: ${{ matrix.ruby }}
+      - name: Install dependencies
+        run: bundle install
+      - name: Run test
+        run: rake
+      - name: Install gem
+        run: rake install
+  platforms:
+    strategy:
+      matrix:
+        os: [macos, windows]
+        ruby: ['2.5']
+    runs-on: ${{ matrix.os }}-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v3
+      - name: Set up Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: ${{ matrix.ruby }}
+      - name: Install dependencies
+        run: bundle install
+      - name: Run test
+        run: bundle exec rake
+      - name: Install gem
+        run: bundle exec rake install

data/.gitignore

@@ -7,4 +7,3 @@ doc/*
 tmp/
 Gemfile.lock
 vendor/*
-bin/

data/CHANGELOG.md

@@ -0,0 +1,23 @@
+# Unreleased
+
+# 1.3.0
+
+- Deprecate `EscapeUtils.escape_url` and `EscapeUtils.unescape_url` given that Ruby 2.5 provides an optimized `CGI.escape` and `CGI.unescape` with mostly similar performance.
+- Don't patch `URI.escape` and `URI.unescape` if they don't already exist.
+- Add `EscapeUtils.escape_html_once` and `EscapeUtils.rb_eu_escape_html_once_as_html_safe` as faster implementations of Rails `escape_once` helper.
+- Deprecate `escape_html` and `escape_html_as_html_safe` given that Ruby 2.5 optimized `GCI.escapeHTML` to be twice faster than the `EscapeUtils` implementation.
+- Deprecate `unescape_html` given that Ruby 2.5 optimized `GCI.unescapeHTML` to be only 40% slower than th `EscapeUtils` implementation.
+- Deprecate `escape_html_as_html_safe` as well.
+- Deprecate `EscapeUtils.html_safe`, there's no reason to escape for slashes `/` in 2022.
+
+# 1.2.2
+
+- Update EscapeUtils.escape_javascript to match Rails `escape_javascript`
+  Now escapes, Backquotes (```), Dollar (`$`), `U+2000` and `U+2001`
+- Make the Rack monkey patch a noop as it's no longer correct since circa 2011.
+- Require Ruby 2.5+
+- Stop escaping `~` like `CGI.escape` does since Ruby 2.5
+
+# 1.2.1
+
+- Historical version

data/Gemfile

@@ -1,3 +1,18 @@
 source 'https://rubygems.org'
 
+group :test do
+  gem 'rake-compiler'
+  gem 'minitest'
+  gem 'actionview'
+end
+
+group :benchmark do
+  gem 'benchmark-ips'
+  gem 'rack'
+  gem 'haml'
+  gem 'fast_xs'
+  gem 'actionpack'
+  gem 'url_escape'
+end
+
 gemspec

data/README.md

@@ -1,16 +1,16 @@
 # escape_utils
 
-Being as though we're all html escaping everything these days, why not make it faster?
+`EscapeUtils` used to provide optimized escaping function to replace the slow methods
+provided by Ruby. Since Ruby 2.5, the various `CGI` escape methods have been severely optimized
+and most `EscapeUtils` methods became irrelevant and were deprecated.
 
-For character encoding in 1.9, the output string's encoding is copied from the input string.
+It however still provide fast escaping and unescaping methods for URL (RFC 3986), Javascript, XML, as well as an "escape HTML once" method.
 
-It has monkey-patches for Rack::Utils, CGI, URI, ERB::Util and Haml and ActionView so you can drop this in and have your app start escaping fast as balls in no time
-
-It supports HTML, URL, URI and Javascript escaping/unescaping.
+It has monkey-patches for Rack::Utils, URI and ERB::Util so you can drop this in and have your app start escaping fast as balls in no time
 
 ## Installing
 
-Compatible with Ruby 1.9.3+
+Compatible with Ruby 2.5+
 
 ``` sh
 gem install escape_utils
@@ -22,72 +22,62 @@ escape_utils assumes all input is encoded as valid UTF-8. If you are dealing wit
 
 
 ``` ruby
-utf8_string = non_utf8_string.encode('UTF-8')
+utf8_string = non_utf8_string.encode(Encoding::UTF_8)
 ```
 
 ## Usage
 
 ### HTML
 
-#### Escaping
-
-``` ruby
-html = `curl -s http://maps.google.com`
-escaped_html = EscapeUtils.escape_html(html)
-```
+As of `escape_utils 1.3.0`, regular HTML escaping methods are deprecated. Ruby 2.5 introduced C implementations for `CGI.escapeHTML` and `CGI.unescapeHTML` which are respectively faster and almost as fast as `EscapeUtils`. Use that instead.
 
-By default escape_utils will escape `/` characters with `/`, but you can disable that by setting `EscapeUtils.html_secure = false`
-or per-call by passing `false` as the second parameter to `escape_html` like `EscapeUtils.escape_html(html, false)`
-
-For more information check out: http://www.owasp.org/index.php/XSS_(Cross_Site_Scripting)_Prevention_Cheat_Sheet#RULE_.231_-_HTML_Escape_Before_Inserting_Untrusted_Data_into_HTML_Element_Content
-
-#### Unescaping
-
-``` ruby
-html = `curl -s http://maps.google.com`
-escaped_html = EscapeUtils.escape_html(html)
-html = EscapeUtils.unescape_html(escaped_html)
-```
+To avoid double-escaping HTML entities, use `EscapeUtils.escape_html_once`.
 
 #### Monkey Patches
 
+Since historically, `HTML` monkey patches changed the return value for `ActiveSupport::SafeBuffer` instances, they are conserved for that purpose only, but they should be considered as deprecated as well.
+
 ``` ruby
-require 'escape_utils/html/rack' # to patch Rack::Utils
-require 'escape_utils/html/erb' # to patch ERB::Util
 require 'escape_utils/html/cgi' # to patch CGI
-require 'escape_utils/html/haml' # to patch Haml::Helpers
 ```
 
 ### URL
 
-Use (un)escape_uri to get RFC-compliant escaping (like PHP rawurlencode).
+Use `escape_uri` and `unescape` to get RFC 3986 compliant escaping (like PHP `rawurlencode` or `ERB::Util.url_encode`).
 
-Use (un)escape_url to get CGI escaping (where space is +).
+The difference with `CGI.escape` is that spaces (` `) are encoded as `%20` instead of `+`.
 
 #### Escaping
 
 ``` ruby
 url = "https://www.yourmom.com/cgi-bin/session.cgi?sess_args=mcEA~!!#*YH*>@!U"
-escaped_url = EscapeUtils.escape_url(url)
+escaped_url = EscapeUtils.escape_uri(url)
 ```
 
 #### Unescaping
 
 ``` ruby
 url = "https://www.yourmom.com/cgi-bin/session.cgi?sess_args=mcEA~!!#*YH*>@!U"
-escaped_url = EscapeUtils.escape_url(url)
-EscapeUtils.unescape_url(escaped_url) == url # => true
+escaped_url = EscapeUtils.escape_uri(url)
+EscapeUtils.unescape_uri(escaped_uri) == url # => true
 ```
 
 #### Monkey Patches
 
 ``` ruby
-require 'escape_utils/url/cgi' # to patch CGI
 require 'escape_utils/url/erb' # to patch ERB::Util
-require 'escape_utils/url/rack' # to patch Rack::Utils
 require 'escape_utils/url/uri' # to patch URI
 ```
 
+Note that `URI.escape` and `URI.unescape` were removed in Ruby 3.0. `'escape_utils/url/uri'` is a noop on Ruby 3+.
+
+### XML
+
+```ruby
+xml = `curl -s 'https://raw.githubusercontent.com/darcyliu/google-styleguide/master/cppguide.xml'`
+escaped_xml = EscapeUtils.escape_xml(xml)
+```
+
 ### Javascript
 
 #### Escaping
@@ -113,87 +103,54 @@ require 'escape_utils/javascript/action_view' # to patch ActionView::Helpers::Ja
 
 ## Benchmarks
 
-In my testing, escaping html is around 10-30x faster than the pure ruby implementations in wide use today.
-While unescaping html is around 40-100x faster than CGI.unescapeHTML which is also pure ruby.
-Escaping Javascript is around 16-30x faster.
+Escaping URL following RFC 3986 is 13-32x faster than the methods provided by Ruby.
+
+Escaping Javascript is around 13x faster than Rails `escape_javascript`.
+
+`EscapeUtils.escape_html_once` is about 17x faster than Rails `escape_once`.
 
 This output is from my laptop using the benchmark scripts in the benchmarks folder.
 
-### HTML
+### Javascript
 
 #### Escaping
 
 ```
-Rack::Utils.escape_html
- 9.650000   0.090000   9.740000 (  9.750756)
-Haml::Helpers.html_escape
- 9.310000   0.110000   9.420000 (  9.417317)
-ERB::Util.html_escape
- 5.330000   0.390000   5.720000 (  5.748394)
-CGI.escapeHTML
- 5.370000   0.380000   5.750000 (  5.791344)
-FasterHTMLEscape.html_escape
- 0.520000   0.010000   0.530000 (  0.539485)
-fast_xs_extra#fast_xs_html
- 0.310000   0.030000   0.340000 (  0.336734)
-EscapeUtils.escape_html
- 0.200000   0.050000   0.250000 (  0.258839)
+EscapeUtils.escape_javascript:                               1567.5 i/s
+ActionView::Helpers::JavaScriptHelper#escape_javascript:      116.8 i/s - 13.42x  (± 0.00) slower
 ```
 
 #### Unescaping
 
 ```
-CGI.unescapeHTML
- 16.520000   0.080000  16.600000 ( 16.853888)
-EscapeUtils.unescape_html
- 0.120000   0.040000   0.160000  (  0.162696)
+EscapeUtils.escape_javascript:    2.089k (± 3.0%) i/s -     10.530k in   5.044615s
 ```
 
-### Javascript
+I didn't look that hard, but I'm not aware of another ruby library that does Javascript unescaping to benchmark against. Anyone know of any?
+
+### URL
 
 #### Escaping
 
 ```
-ActionView::Helpers::JavaScriptHelper#escape_javascript
- 3.810000   0.100000   3.910000 (  3.925557)
-EscapeUtils.escape_javascript
- 0.200000   0.040000   0.240000 (  0.236692)
+EscapeUtils.escape_uri:       4019359.2 i/s
+fast_xs_extra#fast_xs_url:    2435949.2 i/s - 1.65x  (± 0.00) slower
+URI::DEFAULT_PARSER.escape:   288800.8 i/s - 13.92x  (± 0.00) slower
+ERB::Util.url_encode:         122373.5 i/s - 32.85x  (± 0.00) slower
 ```
 
 #### Unescaping
 
-I didn't look that hard, but I'm not aware of another ruby library that does Javascript unescaping to benchmark against. Anyone know of any?
-
-### URL
-
-#### Escaping
-
 ```
-ERB::Util.url_encode
- 0.520000   0.010000   0.530000 (  0.529277)
-Rack::Utils.escape
- 0.460000   0.010000   0.470000 (  0.466962)
-CGI.escape
- 0.440000   0.000000   0.440000 (  0.443017)
-URLEscape#escape
- 0.040000   0.000000   0.040000 (  0.045661)
-fast_xs_extra#fast_xs_url
- 0.010000   0.000000   0.010000 (  0.015429)
-EscapeUtils.escape_url
- 0.010000   0.000000   0.010000 (  0.010843)
+EscapeUtils.unescape_uri:    3866774.5 i/s
+fast_xs_extra#fast_uxs_url:  2438900.7 i/s - 1.59x  (± 0.00) slower
 ```
 
-#### Unescaping
+### HTML
+
+#### Escape once
 
 ```
-Rack::Utils.unescape
- 0.250000   0.010000   0.260000 (  0.257558)
-CGI.unescape
- 0.250000   0.000000   0.250000 (  0.257837)
-URLEscape#unescape
- 0.040000   0.000000   0.040000 (  0.031548)
-fast_xs_extra#fast_uxs_cgi
- 0.010000   0.000000   0.010000 (  0.006062)
-EscapeUtils.unescape_url
- 0.000000   0.000000   0.000000 (  0.005679)
+EscapeUtils.escape_html_once:                   2831.5 i/s
+ActionView::Helpers::TagHelper#escape_once:      161.4 i/s - 17.55x  (± 0.00) slower
 ```

data/Rakefile

@@ -1,12 +1,14 @@
+require 'bundler/gem_tasks'
 require 'rake/testtask'
 
 Rake::TestTask.new do |t|
-  t.pattern = "test/**/*_test.rb"
+  t.libs << "test"
+  t.libs << "lib"
+  t.test_files = FileList["test/**/*_test.rb"]
 end
 
 task :default => :test
 
-gem 'rake-compiler', '>= 0.7.5'
 require "rake/extensiontask"
 
 Rake::ExtensionTask.new('escape_utils') do |ext|

data/benchmark/html_escape_once.rb

@@ -0,0 +1,25 @@
+# encoding: utf-8
+
+require 'rubygems'
+require 'bundler/setup'
+require 'benchmark/ips'
+
+require 'escape_utils'
+require 'active_support/core_ext/string/output_safety'
+
+url = "https://en.wikipedia.org/wiki/Succession_to_the_British_throne"
+html = `curl -s #{url}`
+html = html.force_encoding('utf-8')
+puts "Escaping #{html.bytesize} bytes of html from #{url}"
+
+Benchmark.ips do |x|
+  x.report "EscapeUtils.escape_html_once" do
+    EscapeUtils.escape_html_once(html)
+  end
+
+  x.report "ActionView::Helpers::TagHelper#escape_once" do # Rails expose it as ERB::Util.html_escape_once
+    ERB::Util.html_escape_once(html)
+  end
+
+  x.compare!(order: :baseline)
+end

data/benchmark/javascript_escape.rb

@@ -13,7 +13,7 @@ end
 
 url = "http://ajax.googleapis.com/ajax/libs/dojo/1.4.3/dojo/dojo.xd.js.uncompressed.js"
 javascript = `curl -s #{url}`
-javascript = javascript.force_encoding('utf-8') if javascript.respond_to?(:force_encoding)
+javascript = javascript.force_encoding('utf-8')
 puts "Escaping #{javascript.bytesize} bytes of javascript, from #{url}"
 
 Benchmark.ips do |x|

data/benchmark/javascript_unescape.rb

@@ -8,7 +8,7 @@ require 'escape_utils'
 
 url = "http://ajax.googleapis.com/ajax/libs/dojo/1.4.3/dojo/dojo.xd.js.uncompressed.js"
 javascript = `curl -s #{url}`
-javascript = javascript.force_encoding('utf-8') if javascript.respond_to?(:force_encoding)
+javascript = javascript.force_encoding('utf-8')
 escaped_javascript = EscapeUtils.escape_javascript(javascript)
 puts "Escaping #{escaped_javascript.bytesize} bytes of javascript, from #{url}"
 

data/benchmark/url_decode.rb

@@ -0,0 +1,28 @@
+# encoding: utf-8
+
+require 'rubygems'
+require 'bundler/setup'
+require 'benchmark/ips'
+
+require 'rack'
+require 'cgi'
+require 'url_escape'
+require 'fast_xs_extra'
+require 'escape_utils'
+
+url = "https://www.yourmom.com/cgi-bin/session.cgi?sess_args=mYHcEA  dh435dqUs0moGHeeAJTSLLbdbcbd9ef----,574b95600e9ab7d27eb0bf524ac68c27----"
+url = url.force_encoding('us-ascii')
+escaped_url = EscapeUtils.escape_uri(url)
+puts "Escaping a #{url.bytesize} byte URL"
+
+Benchmark.ips do |x|
+  x.report "EscapeUtils.unescape_uri" do
+    EscapeUtils.unescape_uri(escaped_url)
+  end
+
+  x.report "fast_xs_extra#fast_uxs_url" do
+    url.fast_xs_url
+  end
+
+  x.compare!(order: :baseline)
+end

data/benchmark/url_encode.rb

@@ -0,0 +1,37 @@
+# encoding: utf-8
+
+require 'rubygems'
+require 'bundler/setup'
+require 'benchmark/ips'
+
+require 'rack'
+require 'erb'
+require 'cgi'
+require 'url_escape'
+require 'fast_xs_extra'
+require 'escape_utils'
+
+url = "https://www.yourmom.com/cgi-bin/session.cgi?sess_args=mYHcEA  dh435dqUs0moGHeeAJTSLLbdbcbd9ef----,574b95600e9ab7d27eb0bf524ac68c27----"
+puts "Escaping a #{url.bytesize} byte URL times"
+
+Benchmark.ips do |x|
+  x.report "EscapeUtils.escape_uri" do
+    EscapeUtils.escape_uri(url)
+  end
+
+  x.report " URI::DEFAULT_PARSER.escape" do
+     URI::DEFAULT_PARSER.escape(url)
+  end
+
+  x.report "ERB::Util.url_encode" do |times|
+    times.times do
+      ERB::Util.url_encode(url)
+    end
+  end
+
+  x.report "fast_xs_extra#fast_xs_url" do
+    url.fast_xs_url
+  end
+
+  x.compare!(order: :baseline)
+end

data/benchmark/xml_escape.rb

@@ -7,23 +7,19 @@ require 'benchmark/ips'
 require 'fast_xs'
 require 'escape_utils'
 
-url = "http://google-styleguide.googlecode.com/svn/trunk/cppguide.xml"
+url = "https://raw.githubusercontent.com/darcyliu/google-styleguide/master/cppguide.xml"
 xml = `curl -s #{url}`
-xml = xml.force_encoding('binary') if xml.respond_to?(:force_encoding)
+xml = xml.force_encoding('binary')
 puts "Escaping #{xml.bytesize} bytes of xml, from #{url}"
 
 Benchmark.ips do |x|
-  x.report "fast_xs" do |times|
-    times.times do
-      xml.fast_xs
-    end
+  x.report "EscapeUtils.escape_xml" do
+    EscapeUtils.escape_xml(xml)
   end
 
-  x.report "EscapeUtils.escape_xml" do |times|
-    times.times do
-      EscapeUtils.escape_xml(xml)
-    end
+  x.report "fast_xs" do
+    xml.fast_xs
   end
 
-  x.compare!
+  x.compare!(order: :baseline)
 end

data/bin/console

@@ -0,0 +1,8 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "escape_utils"
+
+require "irb"
+IRB.start(__FILE__)

data/escape_utils.gemspec

@@ -16,16 +16,5 @@ Gem::Specification.new do |s|
   s.description = %q{Quickly perform HTML, URL, URI and Javascript escaping/unescaping}
   s.test_files = `git ls-files test`.split("\n")
 
-  s.required_ruby_version = ">= 1.9.3"
-
-  # tests
-  s.add_development_dependency 'rake-compiler', ">= 0.7.5"
-  s.add_development_dependency 'minitest', ">= 5.0.0"
-  # benchmarks
-  s.add_development_dependency 'benchmark-ips'
-  s.add_development_dependency 'rack'
-  s.add_development_dependency 'haml'
-  s.add_development_dependency 'fast_xs'
-  s.add_development_dependency 'actionpack'
-  s.add_development_dependency 'url_escape'
+  s.required_ruby_version = ">= 2.5"
 end