leptris 1.9.21 → 1.9.23

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 01fef4edf0eca47c087e7c3e111952207c69c10ed75c367858f284f78b5c6753
-  data.tar.gz: 4b094de8b8b535e081fee40f7fd1117330ed0b28ad909043293c34071ae47335
+  metadata.gz: ec6d834f30c917e77000bf9784e85ecc59b8752c246f28bb6932bd003f0d45f9
+  data.tar.gz: a0cd90f99e074b719d9538dc3c1f245e85fc3185fbe693c5b4dab3bee405c77b
 SHA512:
-  metadata.gz: 92c89619228205696fe95555b1e2cb55032237ff82066651140824219994ae0e9a60829a6de0262e7a21de39fcb1655177575de18c9191bb52e50f7a1b772a21
-  data.tar.gz: 12862b063ed8f1c903c53f17de0e1d30f84b059c042a9f3ca1c786901af4189362f311f67fe51a1df0905a4b7e5e30d7638061293a9c5d3cfc238bd1856ba888
+  metadata.gz: d4de54e8c4cb0b5d3951a7c7ac63fc4ce4d97335597d923eb424f445cbaaa790fb27220563d6bbd65ca7490522f2a42423da5e28b199b9e16fcfeb638b148dfb
+  data.tar.gz: 797164d946ad51fde25139e6cbdcc45d9c86a18f5062b09a93c63e098f443ad4b48c1c1f8cce6d26b7f2583a7decd774954dbe4dbe77e4839ad3f5c9d9e3eab9

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.22] - 2026-08-27
+
+### Added
+
+- **libleptris 1.9.4 lockstep** (leptris/leptris#585, #586): Rakefile
+  pin bumped; symbol audit 242/242 attached-vs-exported with the ten
+  new functions.
+- **`SAX::Recorder`**: public chunked-event API over the C recorder —
+  `Recorder.parse(xml_or_io)` / `Recorder#feed` / `#each_event`
+  yield `kind, name, text, attrs, line, column` with UTF-8 strings,
+  drained as one bulk read per chunk (records via `read_bytes` +
+  `unpack` against the packed string arena — no per-event FFI
+  struct). NOT wired into `SAX::Parser#parse_memory`: measured
+  parity-to-−30% vs the callback path (per-parse recorder setup
+  scales with input size; findings and measurements filed upstream
+  as leptris/leptris#594). It remains the right shape for hosts
+  that drain bulk events per chunk.
+- **Iterparse v2** (#586): `Iterparse.parse` / `.parse_file` take
+  `mode:` — `:top_level` (v1: the root's completed children) or
+  `:full_document` (every element, post-order, child before parent).
+  `#namespace_uri(prefix)` / `#namespace_count` resolve prefixes on
+  the last yielded element's in-scope snapshot (call inside the run
+  block); `#error` reports truncated/malformed input.
+
+### Changed
+
+- **Iterparse lifecycle**: `#run` no longer frees in `ensure` — the
+  block form of `.parse`/`.parse_file` frees on return (Pull's
+  pattern), the no-block form returns a live iterator for explicit
+  `#free`. This fixes the `enum_for` path, which previously freed
+  the handle before the enumerator drove it, and lets `#error`
+  stay readable after the run (`#free` snapshots the terminal
+  message). Full-document mode measures +36% CPU over top-level —
+  proportional to yielding every element instead of root children.
+
+### Meta
+
+- Head-to-head vs published 1.9.21 (engine 1.9.0 vs 1.9.4): SAX
+  callback parsing and iterparse at parity across two passes; no
+  regression from the engine bump.
+
 ## [1.9.21] - 2026-08-27
 
 ### Changed

data/Rakefile

@@ -8,7 +8,7 @@ RSpec::Core::RakeTask.new(:spec)
 # Pin for `rake compile` and the platform-gem builds. Keep in lockstep
 # with .github/workflows/build.yml (which calls `rake compile`) and the
 # CHANGELOG when libleptris releases.
-LIBLEPTRIS_VERSION = "1.9.3"
+LIBLEPTRIS_VERSION = "1.9.4"
 
 CMAKE_FLAGS = %w[
   -DCMAKE_BUILD_TYPE=Release

data/lib/leptris/version.rb

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

data/lib/leptris/xml/ffi.rb

@@ -43,6 +43,7 @@ module Leptris
       typedef :pointer, :leptris_xpath_ns_set
       typedef :pointer, :leptris_xpath_compiled
       typedef :pointer, :leptris_xslt
+      typedef :pointer, :leptris_sax_recorder
       typedef :pointer, :leptris_pull_parser
       typedef :pointer, :leptris_iterparse
       typedef :pointer, :leptris_xpath_var_set
@@ -81,6 +82,33 @@ module Leptris
           :recover, :int
       end
 
+      # LeptrisSaxEventRecord (types.h, issue #585): fixed layout the
+      # header explicitly freezes for FFI mirrors. Strings are NOT
+      # inline — name/text/attrs slice the recorder's arena.
+      class SaxEventRecord < ::FFI::Struct
+        layout :kind, :uint8,
+               :reserved, [:uint8, 7],
+               :name_off, :uint32, :name_len, :uint32,
+               :text_off, :uint32, :text_len, :uint32,
+               :attrs_off, :uint32, :attr_count, :uint32,
+               :line, :uint32, :column, :uint32
+      end
+
+      SAX_EVENT_START_DOCUMENT = 0
+      SAX_EVENT_END_DOCUMENT   = 1
+      SAX_EVENT_START_ELEMENT  = 2
+      SAX_EVENT_END_ELEMENT    = 3
+      SAX_EVENT_CHARACTERS     = 4
+      SAX_EVENT_COMMENT        = 5
+      SAX_EVENT_CDATA          = 6
+      SAX_EVENT_PI             = 7
+      SAX_EVENT_START_PREFIX   = 8
+      SAX_EVENT_END_PREFIX     = 9
+      SAX_EVENT_ERROR          = 10
+
+      ITERPARSE_TOP_LEVEL      = 0
+      ITERPARSE_FULL_DOCUMENT  = 1
+
       # struct LeptrisPullEvent (leptris/sax.h): FFI::Struct derives
       # the field offsets from the layout, so ABI changes are a
       # one-line edit here instead of silent offset drift in callers.
@@ -499,6 +527,19 @@ module Leptris
         [:pointer, :pointer], :leptris_sax_parser
       attach_function :leptris_sax_parser_feed,
         [:leptris_sax_parser, :string, :size_t, :int], :int
+      # Chunked event recorder (libleptris 1.9.4, #585): buffers
+      # events C-side (fixed records + packed arena); the host
+      # drains in bulk — callbacks become O(chunks), not O(events).
+      attach_function :leptris_sax_recorder_new,
+        [], :leptris_sax_recorder
+      attach_function :leptris_sax_recorder_feed,
+        [:leptris_sax_recorder, :string, :size_t, :int], :int
+      attach_function :leptris_sax_recorder_records,
+        [:leptris_sax_recorder, :pointer], :pointer
+      attach_function :leptris_sax_recorder_arena,
+        [:leptris_sax_recorder, :pointer], :pointer
+      attach_function :leptris_sax_recorder_free,
+        [:leptris_sax_recorder], :void
       attach_function :leptris_sax_parser_free,
         [:leptris_sax_parser], :void
       attach_function :leptris_sax_parser_set_streaming,
@@ -528,6 +569,19 @@ module Leptris
         [:string], :leptris_iterparse
       attach_function :leptris_iterparse_next,
         [:leptris_iterparse], :leptris_element
+      # iterparse v2 (libleptris 1.9.4, #586): explicit yield mode
+      # (top-level children or full-document post-order), namespace
+      # resolution on the last yielded element, error channel.
+      attach_function :leptris_iterparse_new_ex,
+        [:string, :size_t, :int], :leptris_iterparse
+      attach_function :leptris_iterparse_new_file_ex,
+        [:string, :int], :leptris_iterparse
+      attach_function :leptris_iterparse_ns_count,
+        [:leptris_iterparse], :size_t
+      attach_function :leptris_iterparse_ns_uri,
+        [:leptris_iterparse, :string], :string
+      attach_function :leptris_iterparse_error,
+        [:leptris_iterparse], :string
       attach_function :leptris_iterparse_free,
         [:leptris_iterparse], :void
 

data/lib/leptris/xml/iterparse.rb

@@ -12,34 +12,78 @@ require "ffi"
 #       process(element)   # subtree valid until the next iteration
 #     end
 #
-# v1 limitation (upstream): element names are the QName as written;
-# namespace prefixes are not re-resolved — use the DOM path when
-# namespace URIs matter. The yielded elements have no parent
-# Document; #document returns nil and they must not outlive the
-# iteration.
+# v2 (libleptris 1.9.4, #586): an explicit yield mode —
+# :top_level (v1: the root's completed children) or
+# :full_document (every element in document-order completion —
+# post-order, child before parent, subtree attached) — plus
+# namespace resolution on the last yielded element and an error
+# channel for truncated input:
+#
+#     it = Leptris::XML::Iterparse.parse(xml, mode: :full_document)
+#     it.run do |el|
+#       it.namespace_uri("p")   # in scope on el, the last yielded
+#     end
+#     it.free
+#
+#     Leptris::XML::Iterparse.parse(xml) { |el| ... }.error
+#     # => nil, or the parse failure (readable after the run: the
+#     #    block form frees the iterator on return, snapshotting it)
+#
+# The yielded elements have no parent Document; #document returns
+# nil and they must not outlive the iteration.
 class Leptris::XML::Iterparse
+  MODES = {
+    top_level: Leptris::XML::FFI::ITERPARSE_TOP_LEVEL,
+    full_document: Leptris::XML::FFI::ITERPARSE_FULL_DOCUMENT,
+  }.freeze
+
   # NOTE: an IO argument is read fully into memory before the C
   # iterator starts — the bounded-memory path is parse_file (C-side
   # file streaming). The C API takes one (xml, len) buffer.
-  def self.parse(xml_or_io, &block)
+  def self.parse(xml_or_io, mode: :top_level, &block)
     xml = xml_or_io.respond_to?(:read) ? xml_or_io.read : xml_or_io.to_s
-    iterator = new(Leptris::XML::FFI.leptris_iterparse_new(xml, xml.bytesize))
-    iterator.run(&block)
+    iterator = new(Leptris::XML::FFI.leptris_iterparse_new_ex(
+      xml, xml.bytesize, mode_code(mode)))
+    return iterator unless block
+    begin
+      iterator.run(&block)
+    ensure
+      iterator.free
+    end
+    iterator
   end
 
-  def self.parse_file(path, &block)
-    iterator = new(Leptris::XML::FFI.leptris_iterparse_new_file(path))
-    iterator.run(&block)
+  def self.parse_file(path, mode: :top_level, &block)
+    iterator = new(Leptris::XML::FFI.leptris_iterparse_new_file_ex(
+      path, mode_code(mode)))
+    return iterator unless block
+    begin
+      iterator.run(&block)
+    ensure
+      iterator.free
+    end
+    iterator
+  end
+
+  def self.mode_code(mode)
+    MODES.fetch(mode) do
+      raise ArgumentError,
+        "mode must be :top_level or :full_document, got #{mode.inspect}"
+    end
   end
+  private_class_method :mode_code
 
   def initialize(handle)
     raise Leptris::XML::ParseError, "leptris_iterparse_new failed" if handle.null?
     @handle = handle
   end
 
+  # Yields completed elements until the document is exhausted or the
+  # parse fails (see #error). Does not free the iterator — the block
+  # form of .parse/.parse_file does, or call #free explicitly.
   def run
     return enum_for(:run) unless block_given?
-    loop do
+    while @handle
       ptr = Leptris::XML::FFI.leptris_iterparse_next(@handle)
       break if ptr.null?
       # document: nil — the subtree belongs to the iterator's pool,
@@ -48,13 +92,44 @@ class Leptris::XML::Iterparse
       yield Leptris::XML::Node.wrap(ptr, nil)
     end
     self
-  ensure
-    free
   end
 
+  # The URI bound to +prefix+ ("" for the default namespace) in the
+  # last yielded element's in-scope namespace snapshot, or nil when
+  # unbound (v2, #586). Valid only while the iterator is live —
+  # call it inside the #run block; nil after #free.
+  def namespace_uri(prefix)
+    return nil if @handle.nil?
+    Leptris::XML::FFI.leptris_iterparse_ns_uri(@handle, prefix.to_s)
+  end
+
+  # Number of namespace bindings in the last yielded element's
+  # scope. Valid only while the iterator is live; 0 after #free.
+  def namespace_count
+    return 0 if @handle.nil?
+    Leptris::XML::FFI.leptris_iterparse_ns_count(@handle)
+  end
+
+  # The parse error for malformed/truncated input, or nil when the
+  # document is well-formed and exhausted. Yielded elements stop at
+  # the failure point; #free snapshots the message so this stays
+  # readable after the block form of .parse returns.
+  def error
+    @handle ? live_error : @last_error
+  end
+
+  # Releases the C iterator. Safe to call twice.
   def free
     return if @handle.nil?
+    @last_error = live_error
     Leptris::XML::FFI.leptris_iterparse_free(@handle)
     @handle = nil
   end
+
+  private
+
+  def live_error
+    msg = Leptris::XML::FFI.leptris_iterparse_error(@handle)
+    msg.nil? || msg.empty? ? nil : msg
+  end
 end

data/lib/leptris/xml/sax/recorder.rb

@@ -0,0 +1,156 @@
+# frozen_string_literal: true
+
+require "ffi"
+
+# Chunked event recorder (libleptris 1.9.4, issue #585): a SAX
+# transport that buffers events C-side — fixed LeptrisSaxEventRecord
+# entries plus a packed string arena — and drains them in one bulk
+# read per fed chunk. The handler receives the identical calls the
+# callback API makes; only the transport changes, and the callback
+# count becomes O(chunks), not O(events): through FFI, per-event
+# C-to-Ruby dispatch cost more than the parse itself.
+#
+#     Leptris::XML::SAX::Recorder.parse(xml) do |kind, name, text, attrs|
+#       # kind: :start_element, :characters, ... (see KINDS)
+#     end
+#
+class Leptris::XML::SAX::Recorder
+  KINDS = {
+    Leptris::XML::FFI::SAX_EVENT_START_DOCUMENT => :start_document,
+    Leptris::XML::FFI::SAX_EVENT_END_DOCUMENT => :end_document,
+    Leptris::XML::FFI::SAX_EVENT_START_ELEMENT => :start_element,
+    Leptris::XML::FFI::SAX_EVENT_END_ELEMENT => :end_element,
+    Leptris::XML::FFI::SAX_EVENT_CHARACTERS => :characters,
+    Leptris::XML::FFI::SAX_EVENT_COMMENT => :comment,
+    Leptris::XML::FFI::SAX_EVENT_CDATA => :cdata,
+    Leptris::XML::FFI::SAX_EVENT_PI => :pi,
+    Leptris::XML::FFI::SAX_EVENT_START_PREFIX => :start_prefix,
+    Leptris::XML::FFI::SAX_EVENT_END_PREFIX => :end_prefix,
+    Leptris::XML::FFI::SAX_EVENT_ERROR => :error,
+  }.freeze
+
+  def self.open
+    raw = Leptris::XML::FFI.leptris_sax_recorder_new
+    if raw.null?
+      raise Leptris::XML::Error, "leptris_sax_recorder_new failed"
+    end
+    new(raw)
+  end
+
+  # One-shot parse over a complete document, yielding Record structs.
+  def self.parse(xml_or_io)
+    recorder = open
+    begin
+      if xml_or_io.respond_to?(:read)
+        recorder.feed_stream(xml_or_io) { |*args| yield(*args) }
+      else
+        recorder.feed(xml_or_io.to_s, final: true)
+        recorder.each_event { |*args| yield(*args) }
+      end
+    ensure
+      recorder.free
+    end
+  end
+
+  def initialize(handle)
+    @handle = handle
+  end
+
+  def free
+    return if @handle.nil?
+    Leptris::XML::FFI.leptris_sax_recorder_free(@handle)
+    @handle = nil
+  end
+
+  # Feed one chunk; records/arena reset at feed entry, so drain
+  # after every feed. Returns self.
+  def feed(chunk, final: false)
+    chunk = chunk.dup.force_encoding(Encoding::UTF_8)
+    rc = Leptris::XML::FFI.leptris_sax_recorder_feed(
+      @handle, chunk, chunk.bytesize, final ? 1 : 0)
+    rc
+  end
+
+  # Feed an IO in chunks, draining events after each chunk.
+  def feed_stream(io, chunk_size = 65_536, &block)
+    while (chunk = io.read(chunk_size))
+      feed(chunk)
+      each_event(&block)
+    end
+    feed("", final: true)
+    each_event(&block)
+  end
+
+  # Drains the current chunk's records: bulk-reads the record array
+  # and the packed arena (two FFI calls), then slices every string
+  # from the arena in Ruby — no per-string FFI.
+  def each_event
+    count_ptr = ::FFI::MemoryPointer.new(:size_t)
+    len_ptr = ::FFI::MemoryPointer.new(:size_t)
+    begin
+      records_ptr = Leptris::XML::FFI.leptris_sax_recorder_records(
+        @handle, count_ptr)
+      return self if records_ptr.null? || count_ptr.read_uint64.zero?
+
+      arena_ptr = Leptris::XML::FFI.leptris_sax_recorder_arena(
+        @handle, len_ptr)
+      arena = arena_ptr.read_bytes(len_ptr.read_uint64)
+      count = count_ptr.read_uint64
+
+      # The whole record block in ONE read: read_bytes + String#unpack
+      # (C-fast) — two FFI calls per chunk total (records + arena),
+      # the true bulk discipline. Template per record: kind byte,
+      # 7 pad, then the eight uint32 fields (little-endian hosts —
+      # the layout the header freezes for FFI mirrors).
+      stride = Leptris::XML::FFI::SaxEventRecord.size
+      fields = records_ptr.read_bytes(count * stride)
+        .unpack("C x7 V8" * count)
+
+      i = 0
+      while i < count
+        kind = KINDS[fields[i * 9]]
+        if kind
+          base = i * 9 + 1
+          yield kind,
+                slice(arena, fields[base], fields[base + 1]),
+                slice(arena, fields[base + 2], fields[base + 3]),
+                attrs_from(arena, fields[base + 4], fields[base + 5]),
+                fields[base + 6], fields[base + 7]
+        end
+        i += 1
+      end
+    ensure
+      count_ptr.free
+      len_ptr.free
+    end
+    self
+  end
+
+  private
+
+  # Zero-length slices are empty strings, not nil — the default
+  # namespace prefix is legitimately "" (START_PREFIX: name may be
+  # ""), matching the callback transport's delivery.
+  def slice(arena, off, len)
+    arena.byteslice(off, len).force_encoding(Encoding::UTF_8)
+  end
+
+  # attrs_off addresses name\0value\0... pairs, attr_count pairs;
+  # nil when the element carries none.
+  def attrs_from(arena, off, count)
+    return nil if count.zero?
+    hash = {}
+    pos = off
+    count.times do
+      name_end = arena.index("\0", pos)
+      name = arena.byteslice(pos, name_end - pos)
+      pos = name_end + 1
+      value_end = arena.index("\0", pos)
+      value = arena.byteslice(pos, value_end - pos)
+      pos = value_end + 1
+      hash[name.force_encoding(Encoding::UTF_8)] =
+        value.force_encoding(Encoding::UTF_8)
+    end
+    hash
+  end
+end

data/lib/leptris/xml/sax.rb

@@ -7,6 +7,7 @@ module Leptris
     module SAX
       autoload :Document, "leptris/xml/sax/document"
       autoload :Parser, "leptris/xml/sax/parser"
+      autoload :Recorder, "leptris/xml/sax/recorder"
     end
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: leptris
 version: !ruby/object:Gem::Version
-  version: 1.9.21
+  version: 1.9.23
 platform: ruby
 authors:
 - Ribose Inc.
@@ -99,6 +99,7 @@ files:
 - lib/leptris/xml/sax.rb
 - lib/leptris/xml/sax/document.rb
 - lib/leptris/xml/sax/parser.rb
+- lib/leptris/xml/sax/recorder.rb
 - lib/leptris/xml/searchable.rb
 - lib/leptris/xml/serialization.rb
 - lib/leptris/xml/text.rb