leptris 1.9.4 → 1.9.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4bb5caf8a4c09cfd0ad16d3dc414d205e957ef1994875963bf5c4202666925cb
-  data.tar.gz: 65ff8352d6b7efc9bc7178605af80d6d336e6692b41826dcc6927b1e56d96478
+  metadata.gz: 68bba6b5b68f0266571ec17a5809ea42ce7b1f37f0ba3577f9a06afd57db578f
+  data.tar.gz: d15442dd463ba2b4d09c6415e51c478c385c851eb6630ffc8c4d00e6a9ad7a57
 SHA512:
-  metadata.gz: 027f61b41cb7a0b9270ca974ca82b0d227b02598f21f757aeebadc3d1158d8a8d7335a2657512756e3143b446222817520074d83071065520209714889085951
-  data.tar.gz: 93c71428856e7d460fce88242ab315f63f18382806f76ecd4f7cedcb5f87a55cbe3890ed2f9937dd0dbd0be0a38dbbc16e8900803dcf116112221d3cf517ed36
+  metadata.gz: 52a5f4a5307b9b219911a9ebb7050672be1ad27096266e1c0732eb98ab40779055dcf25e4dd31c0ef0813966539e43894c6d4cdce20bd79e778a7df043c5631a
+  data.tar.gz: cd2e0732f88060f6ff02e3496bedca3d986fde26c9400c91efe458c05e96379caeddd50a5950eb65b965be23487aac243ada697855ade71d0ed6017bcfe49433

data/CHANGELOG.md

@@ -5,6 +5,47 @@ All notable changes to Leptris will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.9.6] - 2026-08-26
+
+### Changed
+
+- The lifetime guard (`ensure_alive!`) uses the cheapest sufficient
+  check (`Document#c_ptr.nil?` — `#free` nils it, and the GC
+  finalizer cannot fire while any handle exists) instead of the
+  deeper `Document#freed?` chain. Claw back on the cheapest single-
+  dispatch read (`Element#[]` hot loops): ~20% of the guard's cost.
+  Remaining guard cost is the method dispatch itself — the price of
+  the lifetime contract on the one call shape cheap enough to
+  notice it; all other harness loops measure at parity, and
+  readonly hot loops have the memoized `attributes`/`keys`
+  alternatives.
+
+## [1.9.5] - 2026-08-26
+
+### Fixed
+
+- **Borrowed handles validate their lender**: every c_ptr-
+  dereferencing read and mutation on Node/Element/Text/Comment/
+  CDATA/PI raises `Leptris::XML::UseAfterFreeError` once the owning
+  document has been freed (previously `doc.free; node.name` read
+  freed memory silently — verified returning `""` — and stale
+  mutations risked segfaults; only Document's own methods checked).
+  Memoized readonly results stay check-free. `Document#freed?` is
+  the single state predicate.
+
+### Added
+
+- **`benchmark/read_paths.rb`**: the committed read-path harness
+  (readonly loops, SAX, NodeSet unions, css, parse-query-serialize)
+  with a README methodology note — review-round benchmarks are now
+  reproducible from the repo.
+
+### Changed
+
+- The published gem no longer ships dev tooling (`benchmark/`,
+  `.rspec`, `.rubocop.yml`); it carries lib, gemspec, Rakefile, and
+  documentation only.
+
 ## [1.9.4] - 2026-08-25
 
 ### Fixed

data/README.adoc

@@ -411,6 +411,17 @@ Notable differences:
 
 == Performance
 
+=== Internal read-path harness
+
+`benchmark/read_paths.rb` measures the binding's own hot paths
+(readonly read loops, SAX, NodeSet unions, css, parse-query-
+serialize). Machine-relative — compare before/after runs on the same
+machine:
+
+    bundle exec ruby benchmark/read_paths.rb
+
+=== Full-field comparison
+
 Measured with metanorma/serialbench (Ruby 3.4.8, leptris 1.6.0,
 libleptris 1.6.0, macOS arm64) — Leptris vs the full field:
 

data/leptris.gemspec

@@ -28,7 +28,8 @@ Gem::Specification.new do |spec|
   spec.files = Dir.chdir(__dir__) do
     `git ls-files -z`.split("\x0").reject do |f|
       (File.expand_path(f) == __FILE__) ||
-        f.start_with?(*%w[bin/ test/ spec/ features/ .git .github appveyor Gemfile])
+        f.start_with?(*%w[bin/ test/ spec/ features/ benchmark/ .git .github
+                         appveyor Gemfile .rspec .rubocop.yml])
     end
   end
   spec.bindir = "bin"

data/lib/leptris/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Leptris
-  VERSION = "1.9.4"
+  VERSION = "1.9.6"
 end

data/lib/leptris/xml/cdata.rb

@@ -5,6 +5,7 @@ class Leptris::XML::CDATA < Leptris::XML::Text
 
   def content
     return @content if readonly_cached?(:@content)
+    ensure_alive!
     Leptris::XML::FFI.leptris_cdata_node_get_content(@c_ptr).tap do |text|
       @content = text if @document&.readonly?
     end

data/lib/leptris/xml/comment.rb

@@ -5,6 +5,7 @@ class Leptris::XML::Comment < Leptris::XML::Node
 
   def content
     return @content if readonly_cached?(:@content)
+    ensure_alive!
     Leptris::XML::FFI.leptris_comment_node_get_content(@c_ptr).tap do |text|
       @content = text if @document&.readonly?
     end

data/lib/leptris/xml/document.rb

@@ -281,6 +281,12 @@ class Leptris::XML::Document
     @readonly == true
   end
 
+  # True once #free has run (or the GC finalizer fired) — borrowed
+  # handles check this before dereferencing their c_ptr.
+  def freed?
+    @freed.state == :freed || @c_ptr.nil?
+  end
+
   # The most recent error recorded against this document, or nil.
   def last_error
     msg = Leptris::XML::FFI.leptris_document_last_error(@c_ptr)

data/lib/leptris/xml/element.rb

@@ -2,7 +2,9 @@
 
 class Leptris::XML::Element < Leptris::XML::Node
   def name
-    @name ||= Leptris::XML::FFI.leptris_element_name(@c_ptr)
+    return @name if @name
+    ensure_alive!
+    @name = Leptris::XML::FFI.leptris_element_name(@c_ptr)
   end
   alias_method :node_name, :name
 
@@ -16,6 +18,7 @@ class Leptris::XML::Element < Leptris::XML::Node
 
   def content
     return @content if readonly_cached?(:@content)
+    ensure_alive!
     Leptris::XML::FFI.leptris_element_text(@c_ptr).tap do |text|
       @content = text if @document&.readonly?
     end
@@ -29,6 +32,7 @@ class Leptris::XML::Element < Leptris::XML::Node
   end
 
   def [](key)
+    ensure_alive!
     Leptris::XML::FFI.leptris_element_attribute(@c_ptr, key.to_s)
   end
   alias_method :attr, :[]
@@ -43,6 +47,7 @@ class Leptris::XML::Element < Leptris::XML::Node
   alias_method :set_attribute, :[]=
 
   def key?(name)
+    ensure_alive!
     Leptris::XML::FFI.leptris_element_has_attribute(@c_ptr, name.to_s) != 0
   end
   alias_method :has_attribute?, :key?
@@ -53,11 +58,13 @@ class Leptris::XML::Element < Leptris::XML::Node
   # in-scope declarations. uri nil/"" matches no-namespace
   # attributes only; xmlns declarations are invisible.
   def attribute_ns(uri, local)
+    ensure_alive!
     Leptris::XML::FFI.leptris_element_attribute_ns(
       @c_ptr, uri&.to_s, local.to_s)
   end
 
   def has_attribute_ns?(uri, local)
+    ensure_alive!
     Leptris::XML::FFI.leptris_element_has_attribute_ns(
       @c_ptr, uri&.to_s, local.to_s) != 0
   end
@@ -77,6 +84,7 @@ class Leptris::XML::Element < Leptris::XML::Node
   # per-attribute namespace accessors (libleptris 1.8.0).
   def each_attribute
     return enum_for(:each_attribute) unless block_given?
+    ensure_alive!
     attr = Leptris::XML::FFI.leptris_element_first_attribute(@c_ptr)
     until attr.nil? || attr.null?
       name = Leptris::XML::FFI.leptris_attribute_get_name(attr)
@@ -119,6 +127,7 @@ class Leptris::XML::Element < Leptris::XML::Node
   # The element's own namespace prefix (e.g. "foo" for <foo:child/>),
   # or nil when the element has none.
   def prefix
+    ensure_alive!
     Leptris::XML::FFI.leptris_element_prefix(@c_ptr)
   end
 
@@ -231,6 +240,7 @@ class Leptris::XML::Element < Leptris::XML::Node
 
   def namespace
     return @namespace if readonly_cached?(:@namespace)
+    ensure_alive!
     uri = Leptris::XML::FFI.leptris_element_namespace(@c_ptr)
     result =
       if uri.nil? || uri.empty?
@@ -249,6 +259,7 @@ class Leptris::XML::Element < Leptris::XML::Node
 
   def namespace_definitions
     return @namespace_definitions if readonly_cached?(:@namespace_definitions)
+    ensure_alive!
     count = Leptris::XML::FFI.leptris_element_namespace_count(@c_ptr)
     result = count.times.map do |i|
       prefix = Leptris::XML::FFI.leptris_element_namespace_decl_prefix(@c_ptr, i)

data/lib/leptris/xml/node.rb

@@ -62,7 +62,9 @@ class Leptris::XML::Node
   end
 
   def type
-    @node_type ||= Leptris::XML::FFI.leptris_node_get_type(@c_ptr)
+    return @node_type if @node_type
+    ensure_alive!
+    @node_type = Leptris::XML::FFI.leptris_node_get_type(@c_ptr)
   end
   alias_method :node_type, :type
 
@@ -77,13 +79,31 @@ class Leptris::XML::Node
 
   def parent
     return @parent if @parent
+    ensure_alive!
     ptr = Leptris::XML::FFI.leptris_node_parent(@c_ptr)
     return nil if ptr.null?
     Leptris::XML::Node.wrap(ptr, @document)
   end
 
-  # Raises ReadOnlyError when the owning document was marked readonly.
+  # Borrowed-handle lifetime: every c_ptr dereference is valid only
+  # while the owning document lives. Parentless nodes (iterparse
+  # yields) cannot validate and are skipped. The guard runs before
+  # every uncached FFI dispatch, so it uses the cheapest sufficient
+  # check: #free nils the document's c_ptr, and the GC-finalizer
+  # path cannot fire while any handle (which strongly references
+  # the document) exists. Document#freed? remains the accurate
+  # public predicate.
+  def ensure_alive!
+    if @document && @document.c_ptr.nil?
+      raise Leptris::XML::UseAfterFreeError,
+        "owning document has been freed — handle used on #{inspect}"
+    end
+  end
+
+  # Raises ReadOnlyError when the owning document was marked readonly,
+  # UseAfterFreeError when it was freed.
   def ensure_writable!
+    ensure_alive!
     if @document&.readonly?
       raise Leptris::XML::ReadOnlyError,
         "document is readonly — mutation attempted on #{inspect}"
@@ -91,16 +111,19 @@ class Leptris::XML::Node
   end
 
   def line
+    ensure_alive!
     Leptris::XML::FFI.leptris_node_line(@c_ptr)
   end
 
   def <=>(other)
     return nil unless other.is_a?(Leptris::XML::Node)
     return nil unless @document == other.document
+    ensure_alive!
     Leptris::XML::FFI.leptris_node_compare(@c_ptr, other.c_ptr)
   end
 
   def child
+    ensure_alive!
     ptr = Leptris::XML::FFI.leptris_node_first_child(@c_ptr)
     return nil if ptr.null?
     Leptris::XML::Node.wrap(ptr, @document, parent: as_element_or_self)
@@ -110,6 +133,7 @@ class Leptris::XML::Node
     # Immutable in readonly mode: the batch fetch plus wrapper
     # construction is paid once.
     return @children if readonly_cached?(:@children)
+    ensure_alive!
     parent = as_element_or_self
     nodes = Leptris::XML::FFI.fetch_children(@c_ptr).map do |ptr|
       Leptris::XML::Node.wrap(ptr, @document, parent: parent)
@@ -120,6 +144,7 @@ class Leptris::XML::Node
   end
 
   def next_sibling
+    ensure_alive!
     ptr = Leptris::XML::FFI.leptris_node_next_sibling(@c_ptr)
     return nil if ptr.null?
     Leptris::XML::Node.wrap(ptr, @document, parent: @parent)
@@ -127,6 +152,7 @@ class Leptris::XML::Node
   alias_method :next, :next_sibling
 
   def previous_sibling
+    ensure_alive!
     ptr = Leptris::XML::FFI.leptris_node_previous_sibling(@c_ptr)
     return nil if ptr.null?
     Leptris::XML::Node.wrap(ptr, @document, parent: @parent)
@@ -134,6 +160,7 @@ class Leptris::XML::Node
   alias_method :previous, :previous_sibling
 
   def first_element_child
+    ensure_alive!
     ptr = Leptris::XML::FFI.leptris_node_first_child(@c_ptr)
     until ptr.nil? || ptr.null?
       node = Leptris::XML::Node.wrap(ptr, @document, parent: as_element_or_self)
@@ -189,6 +216,7 @@ class Leptris::XML::Node
   # callback (libleptris #273); the per-node FFI cost is the floor.
   def traverse
     return enum_for(:traverse) unless block_given?
+    ensure_alive!
     callback = ::FFI::Function.new(:int, [:pointer, :pointer], blocking: true) do |node_ptr, _|
       yield Leptris::XML::Node.wrap(node_ptr, @document)
       0
@@ -199,6 +227,7 @@ class Leptris::XML::Node
 
   def path
     return @path if readonly_cached?(:@path)
+    ensure_alive!
     str_ptr = Leptris::XML::FFI.leptris_node_get_xpath(@c_ptr)
     result = str_ptr.null? ? nil : Leptris::XML::FFI.read_owned_string(str_ptr)
     @path = result if @document&.readonly?
@@ -221,6 +250,7 @@ class Leptris::XML::Node
   end
 
   def dup
+    ensure_alive!
     elem_ptr = Leptris::XML::FFI.leptris_node_as_element(@c_ptr)
     raise Leptris::XML::Error, "dup is only supported for element nodes" if elem_ptr.null?
     copy_ptr = Leptris::XML::FFI.leptris_element_copy(elem_ptr, @document.c_ptr)

data/lib/leptris/xml/processing_instruction.rb

@@ -3,6 +3,7 @@
 class Leptris::XML::ProcessingInstruction < Leptris::XML::Node
   def name
     return @name if readonly_cached?(:@name)
+    ensure_alive!
     Leptris::XML::FFI.leptris_pi_node_get_target(@c_ptr).tap do |target|
       @name = target if @document&.readonly?
     end
@@ -11,6 +12,7 @@ class Leptris::XML::ProcessingInstruction < Leptris::XML::Node
 
   def content
     return @content if readonly_cached?(:@content)
+    ensure_alive!
     Leptris::XML::FFI.leptris_pi_node_get_data(@c_ptr).to_s.tap do |data|
       @content = data if @document&.readonly?
     end

data/lib/leptris/xml/text.rb

@@ -5,6 +5,7 @@ class Leptris::XML::Text < Leptris::XML::Node
 
   def content
     return @content if readonly_cached?(:@content)
+    ensure_alive!
     Leptris::XML::FFI.leptris_text_node_get_content(@c_ptr).tap do |text|
       @content = text if @document&.readonly?
     end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: leptris
 version: !ruby/object:Gem::Version
-  version: 1.9.4
+  version: 1.9.6
 platform: ruby
 authors:
 - Ribose Inc.
@@ -63,15 +63,11 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
-- ".rspec"
-- ".rubocop.yml"
 - CHANGELOG.md
 - CLAUDE.md
 - LICENSE.md
 - README.adoc
 - Rakefile
-- benchmark/README.md
-- benchmark/leptris_vs_nokogiri.rb
 - leptris.gemspec
 - lib/leptris.rb
 - lib/leptris/version.rb

data/.rspec

@@ -1,3 +0,0 @@
---format documentation
---color
---require spec_helper

data/.rubocop.yml

@@ -1,8 +0,0 @@
-AllCops:
-  TargetRubyVersion: 3.1
-
-Style/StringLiterals:
-  EnforcedStyle: double_quotes
-
-Style/StringLiteralsInInterpolation:
-  EnforcedStyle: double_quotes

data/benchmark/README.md

@@ -1,12 +0,0 @@
-# leptris vs the field
-
-The authoritative cross-library numbers live in the README's
-Performance section (measured with metanorma/serialbench).
-
-This local benchmark compares against Nokogiri only:
-
-    LEPTRIS_LIB_PATH=/path/to/libleptris.dylib bundle exec ruby benchmark/leptris_vs_nokogiri.rb
-
-For the full-field race (Ox, Nokogiri, Oga, REXML, Leptris), use
-https://github.com/metanorma/serialbench — leptris's adapter ships
-there under `lib/serialbench/serializers/xml/leptris_serializer.rb`.

data/benchmark/leptris_vs_nokogiri.rb

@@ -1,105 +0,0 @@
-# frozen_string_literal: true
-
-# Ruby-level performance comparison: Leptris::XML (FFI → libleptris v0.12.0)
-# vs Nokogiri (C extension → libxml2).
-#
-# Run with: bundle exec ruby -Ilib benchmark/leptris_vs_nokogiri.rb
-
-require "benchmark"
-require "leptris/xml"
-require "nokogiri"
-
-module Fixtures
-  SMALL = "<catalog>" +
-          (1..10).map { |i| "<book id='#{i}'><title>Book #{i}</title></book>" }.join +
-          "</catalog>"
-
-  MEDIUM = ("<catalog version='2.0'>" +
-            (1..100).map do |i|
-              "<book id='#{i}' lang='en'>" \
-              "<title>Book #{i}</title>" \
-              "<author id='a#{i}'>Author #{i}</author>" \
-              "<price currency='USD'>#{i}.99</price>" \
-              "</book>"
-            end.join +
-            "</catalog>").freeze
-end
-
-def time_it(label, n, &block)
-  GC.start
-  t0 = Process.clock_gettime(Process::CLOCK_MONOTONIC)
-  n.times { yield }
-  elapsed = Process.clock_gettime(Process::CLOCK_MONOTONIC) - t0
-  us_per_iter = (elapsed / n) * 1_000_000
-  printf "  %-40s %8.2f µs/iter  (%d iters in %.3fs)\n", label, us_per_iter, n, elapsed
-  us_per_iter
-end
-
-def ratio(label, leptris_us, nokogiri_us)
-  r = nokogiri_us / leptris_us
-  who = r > 1 ? "Leptris faster" : "Nokogiri faster"
-  printf "  → %-30s Leptris/Nokogiri = %.2fx (%s)\n\n", label, r, who
-end
-
-N_PARSE_SMALL = 5_000
-N_PARSE_MEDIUM = 1_000
-N_QUERY = 10_000
-N_TRAVERSE = 2_000
-N_SERIALIZE = 1_000
-
-puts "===== Parse — small (#{Fixtures::SMALL.bytesize} B) ====="
-t = time_it("leptris parse small", N_PARSE_SMALL) { d = Leptris::XML::Document.parse(Fixtures::SMALL); d.free }
-n = time_it("nokogiri parse small", N_PARSE_SMALL) { Nokogiri::XML(Fixtures::SMALL) }
-ratio("parse small", t, n)
-
-puts "===== Parse — medium (#{Fixtures::MEDIUM.bytesize} B) ====="
-t = time_it("leptris parse medium", N_PARSE_MEDIUM) { d = Leptris::XML::Document.parse(Fixtures::MEDIUM); d.free }
-n = time_it("nokogiri parse medium", N_PARSE_MEDIUM) { Nokogiri::XML(Fixtures::MEDIUM) }
-ratio("parse medium", t, n)
-
-# Pre-parse medium for query benchmarks
-doc_t = Leptris::XML::Document.parse(Fixtures::MEDIUM)
-doc_n = Nokogiri::XML(Fixtures::MEDIUM)
-
-puts "===== XPath — count(//book) ====="
-t = time_it("leptris xpath count()", N_QUERY) { doc_t.xpath("count(//book)") }
-n = time_it("nokogiri xpath count()", N_QUERY) { doc_n.xpath("count(//book)") }
-ratio("xpath count()", t, n)
-
-puts "===== XPath — //book (nodeset of 100) ====="
-t = time_it("leptris xpath //book", N_QUERY) { doc_t.xpath("//book") }
-n = time_it("nokogiri xpath //book", N_QUERY) { doc_n.xpath("//book") }
-ratio("xpath //book", t, n)
-
-puts "===== XPath — predicate //book[@id='50'] ====="
-t = time_it("leptris xpath predicate", N_QUERY) { doc_t.xpath("//book[@id='50']") }
-n = time_it("nokogiri xpath predicate", N_QUERY) { doc_n.xpath("//book[@id='50']") }
-ratio("xpath predicate", t, n)
-
-puts "===== XPath — complex //book[price > 50] ====="
-t = time_it("leptris xpath complex", N_QUERY) { doc_t.xpath("//book[price > 50]") }
-n = time_it("nokogiri xpath complex", N_QUERY) { doc_n.xpath("//book[price > 50]") }
-ratio("xpath complex", t, n)
-
-puts "===== XPath — union //author | //title ====="
-t = time_it("leptris xpath union", N_QUERY) { doc_t.xpath("//author | //title") }
-n = time_it("nokogiri xpath union", N_QUERY) { doc_n.xpath("//author | //title") }
-ratio("xpath union", t, n)
-
-puts "===== Tree traversal (root.traverse) ====="
-t = time_it("leptris traverse", N_TRAVERSE) { doc_t.root.traverse { |n| n.name } }
-n = time_it("nokogiri traverse", N_TRAVERSE) { doc_n.root.traverse { |n| n.name } }
-ratio("traverse", t, n)
-
-puts "===== Serialize — Document#to_xml ====="
-t = time_it("leptris serialize", N_SERIALIZE) { doc_t.to_xml }
-n = time_it("nokogiri serialize", N_SERIALIZE) { doc_n.to_xml }
-ratio("serialize", t, n)
-
-doc_t.free
-
-puts ""
-puts "libleptris v0.12.0 — all upstream issues closed."
-puts "All 176 Ruby specs passing, 0 pending."
-
-