rxerces 0.6.1 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 957f224ac2dc4d0d487906c04554c8d956db8bb0dd3e3ad0c19b2b265b6d1e82
-  data.tar.gz: 5ca62e02d42580a8223497115b62468af9ce322947588c8530bafd66b942eedf
+  metadata.gz: b67969a411b4eb67c0eef75b5c32496a39f962fc8f1b67015eeaf8cb20555d21
+  data.tar.gz: 3597880bb07a892766f5717d979cc140416f28e4db5d92b562b173e3f3ec4027
 SHA512:
-  metadata.gz: c66c5fe4f359ab15e900c917d304c4c69a217239bc97883eefad8424777a5e804c963e9e25eb289fc1a2278d8ed931a058af1274efdaef8d6b7854a9fc4b731e
-  data.tar.gz: af997049f398faca77f2976c3931fbe82a9ee1c9d90795f0d65435613032f0a0e76913cc1667e75bb4ff95e260a9a79e1dd22838fd912f8e1e9a46976780a41b
+  metadata.gz: e7fa8c0ca9ace56ea3ec1f070340ae11ffa92e2090220099c5a7e7a25e069973ebc85fabbdda120f94dd59fdd1ad72cdbb16f735f48fea77d1dccadb0c7ee27d
+  data.tar.gz: 66b6e8eceb35d815b9fa08dfbb0581a3561891ec9f47976386188f3bac207470db7cb97ea9f9688eab13e7288cde2ff9784dcc5e604dc33d092af0ea12c28512

data/CHANGES.md

@@ -1,3 +1,20 @@
+## 0.7.0 - 3-Jan-2026
+* Added XPath validation to prevent XPath injection attacks, with checks for
+  unbalanced quotes, dangerous functions, encoded characters, and injection patterns.
+* Added XPath validation caching with LRU eviction for better performance.
+* Added configuration API for XPath validation caching.
+* Added configurable XPath expression maximum length.
+* Added RXerces.xalan_enabled? method to check Xalan availability.
+* Added Node#attribute_nodes method to get attribute nodes as an array.
+* Improved thread safety with mutex protection for Xerces/Xalan initialization.
+* Added XXE (XML External Entity) protection, disabled by default.
+* Improved exception handling with more specific error messages.
+* Fixed UTF-8 truncation issues in NodeSet#inspect.
+* Nodes are now automatically imported when adding children from different documents.
+* Added validation for Document.parse options hash.
+* Improved wrap_node function robustness.
+* Now uses mkmf-lite to check for Xalan installation.
+
 ## 0.6.1 - 20-Dec-2025
 * Added more Nokogiri compatibility methods: children, first_element_child,
   last_element_child, elements, at_xpath.

data/README.md

@@ -247,6 +247,34 @@ For full XPath 1.0 support, install the Xalan library.
 
 - `RXerces.XML(string)` - Parse XML string and return Document
 - `RXerces.parse(string)` - Alias for `XML`
+- `RXerces.xalan_enabled?` - Check if Xalan XPath 1.0 support is available
+
+#### XPath Validation Cache Configuration
+
+RXerces validates XPath expressions for security (preventing injection attacks). For high-volume applications, validated expressions are cached to avoid redundant validation overhead.
+
+```ruby
+# Check if caching is enabled (default: true)
+RXerces.cache_xpath_validation?  # => true
+
+# Disable caching (re-validates every query)
+RXerces.cache_xpath_validation = false
+
+# Re-enable caching
+RXerces.cache_xpath_validation = true
+
+# Get current cache size
+RXerces.xpath_validation_cache_size  # => 42
+
+# Get/set maximum cache size (default: 10,000)
+RXerces.xpath_validation_cache_max_size       # => 10000
+RXerces.xpath_validation_cache_max_size = 5000
+
+# Clear the cache
+RXerces.clear_xpath_validation_cache
+```
+
+**Performance note:** Caching provides ~7-9% speedup for repeated XPath queries by avoiding redundant validation. The cache is thread-safe.
 
 ### RXerces::XML::Document
 
@@ -341,7 +369,7 @@ sorry state of that library in general. Since nokogiri uses it under the hood,
 I thought it best to create an alternative.
 
 ## Copyright
-(C) 2025, Daniel J. Berger
+(C) 2025-2026, Daniel J. Berger
 All Rights Reserved
 
 ## Author

data/benchmarks/xpath_validation_cache_benchmark.rb

@@ -0,0 +1,157 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Benchmark comparing XPath performance with and without validation caching
+#
+# This benchmark measures the overhead of XPath expression validation
+# and demonstrates the performance benefit of caching validated expressions.
+
+require "benchmark/ips"
+require "rxerces"
+
+puts "=" * 70
+puts "XPath Validation Cache Benchmarks"
+puts "=" * 70
+puts
+
+# Build a moderately sized document
+def build_xml(num_items)
+  items = (1..num_items).map do |i|
+    category = %w[fiction science history biography].sample
+    <<~ITEM
+      <item id="#{i}" category="#{category}">
+        <title>Item #{i}</title>
+        <price>#{(rand * 50).round(2)}</price>
+        <stock>#{rand(100)}</stock>
+      </item>
+    ITEM
+  end.join("\n")
+
+  <<~XML
+    <?xml version="1.0" encoding="UTF-8"?>
+    <catalog>
+      #{items}
+    </catalog>
+  XML
+end
+
+xml = build_xml(500)
+doc = RXerces::XML::Document.parse(xml)
+
+puts "Document size: #{xml.bytesize} bytes"
+puts "Xalan enabled: #{RXerces.xalan_enabled?}"
+puts
+
+# Define various XPath expressions to test
+xpath_expressions = [
+  "//item",
+  "//item[@category='fiction']",
+  "//item/title",
+  "//item[price > 25]",
+  "//item[@id='100']",
+  "/catalog/item[1]",
+  "//item[contains(title, 'Item')]",
+  "//item[stock < 50]/title",
+]
+
+puts "-" * 70
+puts "Single XPath expression, repeated queries (same expression)"
+puts "-" * 70
+puts
+
+single_xpath = "//item[@category='fiction']"
+
+Benchmark.ips do |x|
+  x.config(time: 5, warmup: 2)
+
+  x.report("with cache (default)") do
+    RXerces.cache_xpath_validation = true
+    doc.xpath(single_xpath)
+  end
+
+  x.report("without cache") do
+    RXerces.cache_xpath_validation = false
+    doc.xpath(single_xpath)
+  end
+
+  x.compare!
+end
+
+# Reset to default
+RXerces.cache_xpath_validation = true
+RXerces.clear_xpath_validation_cache
+
+puts
+puts "-" * 70
+puts "Multiple different XPath expressions (round-robin)"
+puts "-" * 70
+puts
+
+Benchmark.ips do |x|
+  x.config(time: 5, warmup: 2)
+
+  x.report("with cache") do |times|
+    RXerces.cache_xpath_validation = true
+    times.times do |i|
+      doc.xpath(xpath_expressions[i % xpath_expressions.length])
+    end
+  end
+
+  x.report("without cache") do |times|
+    RXerces.cache_xpath_validation = false
+    times.times do |i|
+      doc.xpath(xpath_expressions[i % xpath_expressions.length])
+    end
+  end
+
+  x.compare!
+end
+
+# Reset
+RXerces.cache_xpath_validation = true
+RXerces.clear_xpath_validation_cache
+
+puts
+puts "-" * 70
+puts "High-volume scenario: 1000 queries with same expression"
+puts "-" * 70
+puts
+
+iterations = 1000
+test_xpath = "//item[price > 20]"
+
+Benchmark.ips do |x|
+  x.config(time: 5, warmup: 2)
+
+  x.report("with cache (1000 queries)") do
+    RXerces.cache_xpath_validation = true
+    iterations.times { doc.xpath(test_xpath) }
+  end
+
+  x.report("without cache (1000 queries)") do
+    RXerces.cache_xpath_validation = false
+    iterations.times { doc.xpath(test_xpath) }
+  end
+
+  x.compare!
+end
+
+# Reset
+RXerces.cache_xpath_validation = true
+RXerces.clear_xpath_validation_cache
+
+puts
+puts "-" * 70
+puts "Cache statistics after benchmark"
+puts "-" * 70
+puts
+
+# Run some queries to populate cache
+xpath_expressions.each { |xp| doc.xpath(xp) }
+
+puts "Cache size: #{RXerces.xpath_validation_cache_size}"
+puts "Cache max size: #{RXerces.xpath_validation_cache_max_size}"
+puts "Cache enabled: #{RXerces.cache_xpath_validation?}"
+puts
+puts "=" * 70
+puts "Benchmark complete!"

data/benchmarks/xpath_validation_micro_benchmark.rb

@@ -0,0 +1,168 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Micro-benchmark isolating XPath validation overhead
+#
+# This benchmark focuses specifically on measuring the validation
+# overhead by using very simple documents and minimal XPath execution time.
+
+require "benchmark/ips"
+require "rxerces"
+
+puts "=" * 70
+puts "XPath Validation Cache Micro-Benchmarks"
+puts "=" * 70
+puts
+puts "Xalan enabled: #{RXerces.xalan_enabled?}"
+puts
+
+# Use a tiny document to minimize XPath execution time
+tiny_xml = "<r><a/></r>"
+tiny_doc = RXerces::XML::Document.parse(tiny_xml)
+
+# Generate many unique XPath expressions to prevent any caching benefit
+def generate_unique_xpaths(count)
+  count.times.map { |i| "//a[#{i + 1} = #{i + 1}]" }
+end
+
+puts "-" * 70
+puts "Test 1: Same expression repeated (cache hit scenario)"
+puts "-" * 70
+puts
+
+simple_xpath = "//a"
+
+# Clear cache and warm up
+RXerces.clear_xpath_validation_cache
+
+Benchmark.ips do |x|
+  x.config(time: 5, warmup: 2)
+
+  x.report("cached (repeated)") do
+    RXerces.cache_xpath_validation = true
+    tiny_doc.xpath(simple_xpath)
+  end
+
+  x.report("uncached (repeated)") do
+    RXerces.cache_xpath_validation = false
+    tiny_doc.xpath(simple_xpath)
+  end
+
+  x.compare!
+end
+
+puts
+puts "-" * 70
+puts "Test 2: Many unique expressions (cache miss then hit vs always validate)"
+puts "-" * 70
+puts
+
+unique_xpaths = generate_unique_xpaths(100)
+RXerces.clear_xpath_validation_cache
+
+Benchmark.ips do |x|
+  x.config(time: 5, warmup: 2)
+
+  x.report("cached (100 unique, round-robin)") do |times|
+    RXerces.cache_xpath_validation = true
+    times.times { |i| tiny_doc.xpath(unique_xpaths[i % 100]) }
+  end
+
+  x.report("uncached (100 unique, round-robin)") do |times|
+    RXerces.cache_xpath_validation = false
+    times.times { |i| tiny_doc.xpath(unique_xpaths[i % 100]) }
+  end
+
+  x.compare!
+end
+
+puts
+puts "-" * 70
+puts "Test 3: Pure validation overhead measurement (validation-only calls)"
+puts "-" * 70
+puts
+
+# Measure how long validation itself takes by comparing many XPath calls
+# with a small vs large expression (validation time scales with expression length)
+
+short_xpath = "//a"
+long_xpath = "//a[@x='1' and @y='2' and @z='3'][position() > 0 and position() < 100][contains(text(), 'test')]"
+
+RXerces.clear_xpath_validation_cache
+
+puts "Short XPath: #{short_xpath.length} chars"
+puts "Long XPath: #{long_xpath.length} chars"
+puts
+
+Benchmark.ips do |x|
+  x.config(time: 5, warmup: 2)
+
+  x.report("short xpath (cached)") do
+    RXerces.cache_xpath_validation = true
+    tiny_doc.xpath(short_xpath)
+  end
+
+  x.report("short xpath (uncached)") do
+    RXerces.cache_xpath_validation = false
+    tiny_doc.xpath(short_xpath)
+  end
+
+  x.report("long xpath (cached)") do
+    RXerces.cache_xpath_validation = true
+    tiny_doc.xpath(long_xpath)
+  end
+
+  x.report("long xpath (uncached)") do
+    RXerces.cache_xpath_validation = false
+    tiny_doc.xpath(long_xpath)
+  end
+
+  x.compare!
+end
+
+puts
+puts "-" * 70
+puts "Test 4: High-frequency scenario (10,000 queries, same expression)"
+puts "-" * 70
+puts
+
+RXerces.clear_xpath_validation_cache
+iterations = 10_000
+
+require "benchmark"
+
+puts "Running #{iterations} XPath queries..."
+puts
+
+RXerces.cache_xpath_validation = true
+RXerces.clear_xpath_validation_cache
+cached_time = Benchmark.realtime do
+  iterations.times { tiny_doc.xpath(simple_xpath) }
+end
+
+RXerces.cache_xpath_validation = false
+uncached_time = Benchmark.realtime do
+  iterations.times { tiny_doc.xpath(simple_xpath) }
+end
+
+puts "With cache:    #{cached_time.round(4)}s (#{(iterations / cached_time).round(1)} queries/sec)"
+puts "Without cache: #{uncached_time.round(4)}s (#{(iterations / uncached_time).round(1)} queries/sec)"
+puts "Difference:    #{((uncached_time - cached_time) * 1000).round(2)}ms (#{((uncached_time / cached_time - 1) * 100).round(2)}% overhead)"
+
+puts
+puts "-" * 70
+puts "Cache statistics"
+puts "-" * 70
+puts
+
+RXerces.cache_xpath_validation = true
+RXerces.clear_xpath_validation_cache
+
+# Populate with test expressions
+unique_xpaths.each { |xp| tiny_doc.xpath(xp) }
+
+puts "Expressions cached: #{RXerces.xpath_validation_cache_size}"
+puts "Max cache size: #{RXerces.xpath_validation_cache_max_size}"
+puts
+puts "=" * 70
+puts "Benchmark complete!"