Skip to content

Escape params 2x faster with half the allocations, using CGI.escape - #1727

Merged
iMacTia merged 3 commits into
lostisland:mainfrom
czj:perf/escape-with-cgi
Oct 26, 2026
Merged

iMacTia merged 3 commits into
lostisland:mainfrom
czj:perf/escape-with-cgi

Conversation

@czj

@czj czj commented Oct 23, 2026 •

Copy link
Copy Markdown
Contributor

Description

Utils.escape runs for every key and value encoded by NestedParamsEncoder and FlatParamsEncoder. It does a block gsub, then an unpack/join/upcase per escaped character, then a second gsub for spaces. CGI.escape escapes exactly the same unreserved set (a-zA-Z0-9 . ~ _ -, space as +) in C. Faraday already loads cgi/escape for CGI.unescape (#1623), and CGI.escape has left ~ alone since Ruby 2.5.

CGI.escape works on bytes, so the fast path is limited to UTF-8, US-ASCII and BINARY: in Shift_JIS, Big5, GBK or CP949, a multibyte character can end with an ASCII byte ('ア' is "\x83A"), which ESCAPE_RE escapes and CGI.escape doesn't. It also takes plain String instances only: CGI.escape returns a SafeBuffer as is when nothing needs escaping, and rejects objects whose to_s isn't a String (the suite's FakeSafeBuffer). Invalid byte sequences and UTF-16 strings, which CGI.escape would escape where ESCAPE_RE raises, keep the regexp path too. So every input behaves exactly as before, and ESCAPE_RE and the public API are unchanged.

Measured on Ruby 4.0.9 with benchmark-ips and memory_profiler, main (d494fce) against this branch, average of two runs:

objects before → after throughput before → after
Utils.escape, 16 words 35 → 17 (−51%) 128k → 259k i/s (×2.0)
NestedParamsEncoder.encode, 8 params 64 → 45 (−30%) 63k → 89k i/s (×1.42)
NestedParamsEncoder.encode, nested hash with arrays 78 → 62 (−21%) 76k → 98k i/s (×1.29)
FlatParamsEncoder.encode, 8 params 55 → 36 (−35%) 68k → 95k i/s (×1.40)
Benchmark script (ruby -Ilib bench.rb)
require 'faraday'
require 'benchmark/ips'
require 'memory_profiler'
words = %w[user_id 12345 page 2 per_page 50 q hello\ world sort created_at order desc lang fr-FR token abc~def]
params = words.each_slice(2).to_h
nested = { 'filter' => { 'tags' => %w[a b c], 'q' => 'hello world' }, 'page' => 2, 'ids' => [1, 2, 3] }
cases = {
  'Utils.escape, 16 words' => -> { words.each { Faraday::Utils.escape(it) } },
  'Nested, 8 params' => -> { Faraday::NestedParamsEncoder.encode(params) },
  'Nested, nested hash' => -> { Faraday::NestedParamsEncoder.encode(nested) },
  'Flat, 8 params' => -> { Faraday::FlatParamsEncoder.encode(params) },
}
cases.each do |name, job|
  objects = MemoryProfiler.report { job.call }.total_allocated
  ips = Benchmark.ips(quiet: true) { |x| x.config(warmup: 2, time: 8); x.report(name, &job) }.entries.first.ips
  puts format('%-26s %4d objects  %8.1fk i/s', name, objects, ips / 1000)
end

Todos

  • Tests: new specs in utils_spec compare the output with the regexp implementation byte for byte, and cover reserved and unreserved characters, multibyte UTF-8, other encodings (including Shift_JIS and GBK characters with an ASCII trailing byte, thanks Copilot), result encoding, String subclasses, a literal + versus a space, default_space_encoding = '%20', non-String values, and the raise on invalid bytes and UTF-16. One spec each in nested_spec and flat_spec. I also compared both implementations on 6.2M strings, every byte and two-byte sequence in every encoding Ruby knows, invalid ones included: identical result, encoding, class and exception.
  • bundle exec rspec: 689 unit examples, 0 failures. RuboCop: no offenses.

Additional Notes

If you'd rather call CGI.escape directly and accept escaping invalid strings instead of raising, the fallback branch can go away.


🤖 Generated with Claude Code, but prompted, read, and verified by @czj, a caring human :)

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@czj czj changed the title Escape params with CGI.escape Escape params 2.6x faster with 40% fewer allocations, using CGI.escape Oct 23, 2026
@iMacTia
iMacTia requested a balanced review from Copilot October 25, 2026 10:32
@iMacTia
iMacTia self-requested a review October 25, 2026 10:33

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Changes recommended

The fast path changes output for valid Shift_JIS characters, breaking the intended byte-for-byte compatibility.

1 open issue
What changed in this PR

This PR optimizes Faraday’s shared parameter escaping with CGI.escape, reducing work in both flat and nested query encoding while aiming to preserve existing behavior.

Changes:

  • Adds a CGI fast path with a regexp fallback for unsupported inputs.
  • Adds utility specs covering escaping, encodings, conversion, and error behavior.
  • Adds escaping regression coverage for both parameter encoders.
File Description
spec/​faraday/​utils_spec.rb Adds escaping compatibility and edge-case specs.
spec/​faraday/​params_encoders/​nested_spec.rb Tests escaping nested keys and values.
spec/​faraday/​params_encoders/​flat_spec.rb Tests escaping flat keys and values.
lib/​faraday/​utils.rb Introduces the CGI escaping fast path and regexp fallback.

Review effort: Balanced

Comment thread lib/faraday/utils.rb Outdated
str = str.to_s
# CGI.escape needs a String and works on raw bytes: anything else, including
# strings ESCAPE_RE can't scan (and raises on), keeps the regexp path.
if str.is_a?(String) && str.valid_encoding? && str.encoding.ascii_compatible?

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I was surprised at first, but it looks like Encoding::Shift_JIS#ascii_compatible? does indeed resolve to true 🤔, I guess that means it's a bit too permissive. But limiting to ASCII_8BIT and US_ASCII feels a bit too restrictive.

@czj I'm no encoding expert to be honest, so I'll defer to you. Would limiting this to ASCII_8BIT and US_ASCII take away most of the performance gains, or simply work the same in the vast majority of requests?

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Good catch, and it goes beyond Shift_JIS: Big5, GBK, GB18030, CP949 and their variants can all end a multibyte character with an ASCII byte, which CGI.escape works byte by byte and leaves alone.

@iMacTia to your question: limiting it to ASCII-8BIT and US-ASCII would take away almost all of the gain, because string literals, JSON and Rails params are UTF-8. On 16 typical params, the old code takes 0.83 s, this PR 0.37 s, and ASCII-8BIT + US-ASCII only 0.85 s.

UTF-8 is safe by design, though: every byte of a multibyte character is ≥ 0x80, so escaping bytes or characters always gives the same output. So 84cfd4b keeps the fast path for UTF-8, US-ASCII and BINARY, and every other encoding goes back to the regexp. I then compared both implementations on 6.2M strings in every encoding Ruby knows, invalid byte sequences and UTF-16 included: same result, encoding, class and exception every time. The ア and 許 cases are now in utils_spec.rb.

Thanks a lot for the kind words and the review!

Comment thread lib/faraday/utils.rb Resolved
@iMacTia

iMacTia commented Oct 25, 2026

Copy link
Copy Markdown
Member

Thank you @czj, this code sits on the hot path, so any performance gain is always appreciated and the strategy of optimising for the majority of cases while keeping the slower fallback for the others makes a lot of sense.

I've left a couple of comments asking for clarification, please forgive my encoding ignorance 😄

In Shift_JIS, Big5, GBK, GB18030 and CP949, a multibyte character can end
with an ASCII byte: 'ア' is "\x83A" in Shift_JIS. CGI.escape works on bytes
and leaves that 'A' alone, while ESCAPE_RE escapes the whole character
(%83A vs %83%41). Every other encoding keeps the regexp path.

The fast path also takes String instances only: CGI.escape returns a String
subclass such as ActiveSupport::SafeBuffer as is when nothing needs escaping,
where the regexp path returned a plain String.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@czj czj changed the title Escape params 2.6x faster with 40% fewer allocations, using CGI.escape Escape params 2x faster with half the allocations, using CGI.escape Oct 25, 2026
@iMacTia
iMacTia merged commit 41666c6 into lostisland:main Oct 26, 2026
16 checks passed
@czj
czj deleted the perf/escape-with-cgi branch October 26, 2026 09:37
@czj

czj commented Oct 26, 2026

Copy link
Copy Markdown
Contributor Author

Thanks for the merge @iMacTia !

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants