leptris 1.9.197.2-arm-linux

data/lib/leptris/xml/pull.rb

@@ -0,0 +1,212 @@
+# frozen_string_literal: true
+
+require "ffi"
+
+# Pull parsing (libleptris v1.6.0): a StAX-style cursor over a
+# document. Each #next advances one event; attributes are readable
+# only during the start_element event just returned.
+#
+#     Leptris::XML::Pull.parse(xml).each do |event|
+#       case event.type
+#       when :start_element then handle(event.name, event.attrs)
+#       when :text then handle(event.text)
+#       end
+#     end
+#
+module Leptris::XML::Pull
+  # Constructed positionally by the parser: the keyword-init
+  # variant cost ~220ns/event in batch drains (round XXI). Readers
+  # (event.type, event.attrs, ...) are unchanged.
+  Event = Struct.new(:type, :name, :text, :attrs)
+
+  TYPES = {
+    Leptris::XML::FFI::PULL_START_ELEMENT => :start_element,
+    Leptris::XML::FFI::PULL_END_ELEMENT => :end_element,
+    Leptris::XML::FFI::PULL_TEXT => :text,
+    Leptris::XML::FFI::PULL_COMMENT => :comment,
+    Leptris::XML::FFI::PULL_CDATA => :cdata,
+    Leptris::XML::FFI::PULL_PI => :pi,
+    Leptris::XML::FFI::PULL_END_DOCUMENT => :end_document,
+    Leptris::XML::FFI::PULL_ERROR => :error,
+    # Prefix events ride the stream ("" prefix = the default
+    # namespace): the engine has always delivered them; the map
+    # lacked the kinds, silently yielding nil-typed Events — which
+    # the staging guard then misread as corruption after the real
+    # engine fix landed (leptris/leptris#648's residual).
+    Leptris::XML::FFI::PULL_START_PREFIX => :start_prefix,
+    Leptris::XML::FFI::PULL_END_PREFIX => :end_prefix,
+  }.freeze
+
+  class Parser
+    def self.parse(xml_or_io)
+      xml = xml_or_io.is_a?(String) ? xml_or_io : xml_or_io.read
+      new(Leptris::XML::FFI.leptris_pull_new(xml, xml.bytesize))
+    end
+
+    def self.parse_file(path)
+      new(Leptris::XML::FFI.leptris_pull_new_file(path))
+    end
+
+    def initialize(handle)
+      raise Leptris::XML::ParseError, "leptris_pull_new failed" if handle.null?
+      @handle = handle
+    end
+
+    # Releases the C parser. Safe to call twice.
+    def free
+      return if @handle.nil?
+      Leptris::XML::FFI.leptris_pull_free(@handle)
+      @handle = nil
+    end
+
+    def each
+      return enum_for(:each) unless block_given?
+      loop do
+        event = next_event
+        break if event.nil?
+        yield event
+        break if event.type == :end_document || event.type == :error
+      end
+      self
+    end
+
+    # Bulk-delivers events (libleptris 1.9.7, upstream #589): ONE C
+    # call stages up to +max_count+ events — the per-event dispatch
+    # that made streaming ~145x slower than a DOM parse collapses to
+    # amortized noise. Per the engine's protocol, attributes are
+    # captured only for the LAST start_element of each batch
+    # (earlier starts in the same batch carry nil attrs — segment
+    # boundaries fall where they fall); use #each when every
+    # start's attrs must be captured.
+    def each_batch(max_count = 256)
+      return enum_for(:each_batch, max_count) unless block_given?
+      stride = Leptris::XML::FFI::PullEventStruct.size
+      type_off = 0
+      name_off = Leptris::XML::FFI::PullEventStruct.offset_of(:name)
+      text_off = Leptris::XML::FFI::PullEventStruct.offset_of(:text)
+      buffer = Leptris::XML::FFI.scratch_events(max_count)
+      while (n = Leptris::XML::FFI.leptris_pull_next_batch(
+               @handle, buffer, max_count)) > 0
+        events = Array.new(n) do |i|
+          base = i * stride
+          name_ptr = buffer.get_pointer(base + name_off)
+          text_ptr = buffer.get_pointer(base + text_off)
+          type = TYPES[buffer.get_int(base + type_off)]
+          name = name_ptr.null? ? nil :
+            name_ptr.read_string.force_encoding(Encoding::UTF_8)
+          # Staging-corruption guard (leptris/leptris#648): the C
+          # batch's staging arena misplaces record strings once the
+          # staged content crosses its block boundary (~185 bytes of
+          # attribute value under nested attr-carrying ancestors) —
+          # names come back empty, control-byte-laced, or
+          # invalid-encoding, and unknown type codes surface as nil.
+          # Element names can never look like that: fail loudly
+          # instead of delivering garbage, and point at the cursor
+          # path, which reads the same documents correctly.
+          if type.nil? ||
+             (name && (!name.valid_encoding? ||
+                       name.match?(/[\x00-\x08\x0e-\x1f]/))) ||
+             (%i[start_element end_element pi].include?(type) &&
+              (name.nil? || name.empty?))
+            raise Leptris::XML::Error,
+              "pull batch staging corruption (leptris/leptris#648) — " \
+              "use Parser#each (cursor) for this document"
+          end
+          text = text_ptr.null? ? nil :
+            text_ptr.read_string.force_encoding(Encoding::UTF_8)
+          text = Leptris::XML::FFI.read_pi_data(text) if type == :pi
+          Event.new(type, name, text, nil)
+        end
+        # The attr mirror holds the batch's most recent start.
+        last_start = nil
+        events.each_with_index do |event, i|
+          last_start = i if event.type == :start_element
+        end
+        events[last_start].attrs = capture_attrs if last_start
+        events.each { |event| yield event }
+        tail = events.last.type
+        break if tail == :end_document || tail == :error
+      end
+      self
+    end
+
+    # Hot-loop offsets: derived from PullEventStruct's layout (the
+    # struct stays the single source of truth for the ABI), read via
+    # get_int/get_pointer so the per-event struct-wrapper allocation
+    # disappears from streaming loops.
+    NAME_OFFSET = Leptris::XML::FFI::PullEventStruct.offset_of(:name)
+    TEXT_OFFSET = Leptris::XML::FFI::PullEventStruct.offset_of(:text)
+    private_constant :NAME_OFFSET, :TEXT_OFFSET
+
+    # Advances the cursor and returns the next Event, or nil after the
+    # end of the document. Attribute values are captured during
+    # start_element because the C accessors are valid only for the
+    # most recently returned event.
+    def next_event
+      raw = Leptris::XML::FFI.leptris_pull_next(@handle)
+      return nil if raw.null?
+      type = TYPES[raw.get_int(0)]
+      name_ptr = raw.get_pointer(NAME_OFFSET)
+      text_ptr = raw.get_pointer(TEXT_OFFSET)
+      attrs = type == :start_element ? capture_attrs : nil
+      text = text_ptr.null? ? nil :
+        text_ptr.read_string.force_encoding(Encoding::UTF_8)
+      text = Leptris::XML::FFI.read_pi_data(text) if type == :pi
+      Event.new(
+        type,
+        name_ptr.null? ? nil : name_ptr.read_string.force_encoding(Encoding::UTF_8),
+        text, attrs
+      )
+    end
+
+    private
+
+    # One count-only query plus one flat copy (leptris_pull_attrs,
+    # 1.9.7) — the char** wire format the SAX callbacks already use —
+    # replaces the 2N per-index dispatches.
+    def capture_attrs
+      total = Leptris::XML::FFI.leptris_pull_attrs(@handle, nil, 0)
+      return nil if total.zero?
+      buffer = Leptris::XML::FFI.scratch_pointers(2 * total)
+      copied = Leptris::XML::FFI.leptris_pull_attrs(@handle, buffer, total)
+      ptr_size = ::FFI.type_size(:pointer)
+      hash = {}
+      i = 0
+      while i < copied
+        name = buffer.get_pointer(2 * i * ptr_size).read_string
+          .force_encoding(Encoding::UTF_8)
+        value = buffer.get_pointer((2 * i + 1) * ptr_size).read_string
+          .force_encoding(Encoding::UTF_8)
+        hash[name] = value
+        i += 1
+      end
+      hash
+    end
+  end
+
+  def self.parse(xml_or_io, &block)
+    parser = Parser.parse(xml_or_io)
+    if block
+      begin
+        parser.each(&block)
+      ensure
+        parser.free
+      end
+    else
+      parser
+    end
+  end
+
+  def self.parse_file(path, &block)
+    parser = Parser.parse_file(path)
+    if block
+      begin
+        parser.each(&block)
+      ensure
+        parser.free
+      end
+    else
+      parser
+    end
+  end
+end

data/lib/leptris/xml/relaxng.rb

@@ -0,0 +1,126 @@
+# frozen_string_literal: true
+
+require "ffi"
+
+module Leptris::XML::RelaxNG
+  module_function
+
+  def parse(schema_xml)
+    Schema.parse(schema_xml)
+  end
+
+  def parse_file(path)
+    Schema.parse_file(path)
+  end
+
+  # A compiled RELAX NG schema (libleptris >= 1.9.115): Jing-parity
+  # validation against the standard DOM — parse once, validate any
+  # number of documents. Schema errors publish to the thread-global
+  # error channel, so failures raise with the engine's detail
+  # ("unknown pattern element: ...", "cannot open schema file ...").
+  #
+  #     rng = Leptris::XML::RelaxNG.parse(schema_xml)
+  #     rng.valid?(doc)      # => true/false
+  #     rng.validate(doc)    # => [] or ["1:0: error: element ..."]
+  #     rng.validate_errors(doc) # => [] or [{line:, column:, message:}]
+  #     rng.validate_report(doc) # => [] or [{kind:, message:, offender:, ...}]
+  #
+  class Schema
+    # GC-managed compiled handle.
+    class Handle < ::FFI::AutoPointer
+      def self.release(ptr)
+        Leptris::XML::FFI.leptris_rng_free(ptr)
+      end
+    end
+
+    # Compile a schema from XML text. Raises Error on a schema
+    # error (detail via leptris_last_error).
+    def self.parse(schema_xml)
+      xml = schema_xml.to_s
+      raw = Leptris::XML::FFI.leptris_rng_parse(xml, xml.bytesize, nil)
+      if raw.null?
+        raise Leptris::XML::Error,
+          "schema parse failed: #{Leptris::XML::FFI.leptris_last_error}"
+      end
+      new(Handle.new(raw))
+    end
+
+    # Compile from a file; <include href="..."> resolves relative to
+    # the file's directory (Jing's override rules apply).
+    def self.parse_file(path)
+      raw = Leptris::XML::FFI.leptris_rng_parse_file(path.to_s, nil)
+      if raw.null?
+        raise Leptris::XML::Error,
+          "schema parse failed: #{Leptris::XML::FFI.leptris_last_error}"
+      end
+      new(Handle.new(raw))
+    end
+
+    def initialize(handle)
+      @handle = handle
+    end
+
+    # Nokogiri shape: an array of error strings (the engine emits
+    # Jing's "line:col: error: message" form), empty when valid.
+    # libleptris 1.9.179 (#878): errors accumulate — every failure
+    # from the validate call is returned, not just the first.
+    def validate(document)
+      structured = validate_errors(document)
+      unless structured.empty?
+        return structured.map do |e|
+          e[:line] > 0 ? "#{e[:line]}:#{e[:column]}: error: #{e[:message]}"
+                        : e[:message]
+        end
+      end
+      # Invalid verdict with nothing accumulated: the back-compat
+      # single-error accessor is the last resort (nil-safe).
+      return [] if valid?(document)
+      [Leptris::XML::FFI.leptris_rng_error(@handle)].compact
+    end
+
+    def valid?(document)
+      Leptris::XML::FFI.leptris_rng_validate(@handle,
+                                             document.c_ptr) != 0
+    end
+
+    # Structured errors: [{ line:, column:, message: }] — the fields
+    # callers need for log formatting, instead of re-parsing the
+    # Jing-form strings from #validate. Empty when valid. Message,
+    # line, and column carry Jing's exact attribution (libleptris
+    # >= 1.9.179, upstream #878). Rendered from #validate_report —
+    # the single enumeration of the error surface.
+    def validate_errors(document)
+      validate_report(document).map do |r|
+        { line: r[:line], column: r[:column], message: r[:message] }
+      end
+    end
+
+    # The whole validation report, one C call (libleptris >= 1.9.190):
+    # [{ kind:, message:, offender:, line:, column: }] — empty when
+    # valid. `kind` is the #1126 failure-class taxonomy
+    # ("missing-required-attr", "attr-not-allowed", ...), `offender`
+    # the attributed element/attribute name (nil when unknown).
+    # Strings are read into Ruby copies before returning.
+    def validate_report(document)
+      ok = Leptris::XML::FFI.leptris_rng_validate(@handle,
+                                                  document.c_ptr)
+      return [] if ok != 0
+      out = ::FFI::MemoryPointer.new(:pointer)
+      count = Leptris::XML::FFI.leptris_rng_error_report(@handle, out)
+      return [] if count.zero?
+      base = out.read_pointer
+      return [] if base.null?
+      record = Leptris::XML::FFI::RngErrorRecord
+      Array.new(count) do |i|
+        r = record.new(base + i * record.size)
+        {
+          kind: r[:kind],
+          message: r[:message],
+          offender: r[:offender],
+          line: r[:line],
+          column: r[:column],
+        }
+      end
+    end
+  end
+end

data/lib/leptris/xml/result_attr.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+# Attribute-kind item from an XPath result set (ruby#153): the
+# engine exposes synthetic attribute nodes whose name and value are
+# readable only through the live result handle — the NodeSet
+# captures both at materialization time and hands them to this
+# wrapper, so the faces stay usable after the result is freed.
+#
+#     doc.xpath("//item/@id").first.name  # => "id"
+#     doc.xpath("//item/@id").first.value # => "1"
+#
+class Leptris::XML::ResultAttr < Leptris::XML::Node
+  def initialize(c_ptr, document, name, value, parent: nil, node_type: nil)
+    super(c_ptr, document, parent: parent, node_type: node_type)
+    @attr_name = name
+    @attr_value = value
+  end
+
+  def name
+    @attr_name
+  end
+
+  # Nokogiri's Attr#value is the attribute's string value.
+  def value
+    @attr_value
+  end
+
+  def content
+    @attr_value
+  end
+
+  def to_s
+    @attr_value
+  end
+
+  def attribute?
+    true
+  end
+end

data/lib/leptris/xml/result_text.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+# Text-kind item from an XPath/XQuery sequence result: the engine
+# materializes sequence, map, and array items as synthetic text
+# nodes (leptris/types.h's internal kind 8) whose value is readable
+# only through the live result handle — the node-pointer accessors
+# return nothing for them. The NodeSet therefore captures the string
+# value at materialization time and hands it to this wrapper.
+#
+#     doc.xpath("for $w in //a return string($w/@v)").map(&:content)
+#     # => ["1", "2"]
+#
+class Leptris::XML::ResultText < Leptris::XML::Node
+  def initialize(c_ptr, document, value, parent: nil, node_type: nil)
+    super(c_ptr, document, parent: parent, node_type: node_type)
+    @value = value
+  end
+
+  def name
+    "text"
+  end
+
+  # The captured string: safe to read even after the owning result
+  # set has been collected (unlike pointer-backed reads).
+  def content
+    @value
+  end
+
+  def to_s
+    @value
+  end
+
+  def text?
+    true
+  end
+end

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

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+class Leptris::XML::SAX::Document
+  # Called when an XML declaration is parsed.
+  def xmldecl(version, encoding, standalone)
+  end
+
+  def start_document
+  end
+
+  def end_document
+  end
+
+  # Called at the beginning of an element.
+  # +attrs+ is an Array of [name, value] pairs in source order.
+  def start_element(name, attrs = [])
+  end
+
+  def end_element(name)
+  end
+
+  def characters(string)
+  end
+
+  def comment(string)
+  end
+
+  def cdata_block(string)
+  end
+
+  def processing_instruction(name, content)
+  end
+
+  def start_prefix_mapping(prefix, uri)
+  end
+
+  def end_prefix_mapping(prefix)
+  end
+
+  def warning(string)
+  end
+
+  def error(message, line = 0, column = 0)
+  end
+end

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

@@ -0,0 +1,144 @@
+# frozen_string_literal: true
+
+# DOM-backed SAX dispatch (leptris-ruby#95): the engine's streaming
+# attribute buffer corrupts leading attribute pairs when several
+# nested ancestor levels each carry attributes — the callback
+# transport, the recorder's packed arena, AND the pull parser all
+# deliver the loss on the issue fixture (verified), while the DOM
+# parser reads the same bytes correctly. Until the engine fix
+# lands, SAX::Parser delivers from a DOM parse: same call shapes as
+# the streaming transports — attach-only-overridden kinds,
+# one-argument start_element arity, QName element names ("p:a"),
+# UTF-8 strings, PI-data normalization.
+#
+# The walk is lean by construction: elements wrap (identity, name
+# and prefix memos); every other child kind is read straight from
+# its pointer — content getters per node type, never a wrapper.
+module Leptris::XML::SAX::DomDispatch
+  module_function
+
+  def parse(handler, dispatched, string)
+    doc = Leptris::XML::Document.parse(string)
+    begin
+      dispatch(handler, dispatched, doc)
+    ensure
+      doc.free
+    end
+  end
+
+  def dispatch(handler, dispatched, doc)
+    handler.start_document if dispatched[:start_document]
+    doc_node = doc.node
+    if doc_node
+      visit_children(doc_node.c_ptr, doc, handler, dispatched,
+                     element_parent: false)
+    end
+    handler.end_document if dispatched[:end_document]
+    self
+  end
+
+  NODE = Leptris::XML::FFI
+  ELEMENT = Leptris::XML::FFI::NODE_ELEMENT
+  TEXT = Leptris::XML::FFI::NODE_TEXT
+  COMMENT = Leptris::XML::FFI::NODE_COMMENT
+  CDATA = Leptris::XML::FFI::NODE_CDATA
+  PI = Leptris::XML::FFI::NODE_PI
+
+  def visit_children(c_ptr, doc, handler, dispatched, element_parent: true)
+    wants_text_kinds = dispatched[:characters] ||
+                       dispatched[:comment] ||
+                       dispatched[:cdata] || dispatched[:pi]
+    if element_parent && !wants_text_kinds
+      # Element-only handlers under an element: the element batch
+      # hands out element pointers with no per-child get_type
+      # (round XXIII's path) — text/comments/PIs are never fetched.
+      # (The document node is not an element handle — the typed
+      # walk serves it.)
+      Leptris::XML::FFI.fetch_element_children(c_ptr).each do |child_ptr|
+        visit_element(
+          Leptris::XML::Node.wrap(child_ptr, doc, node_type: ELEMENT),
+          handler, dispatched)
+      end
+      return
+    end
+    pointers, kinds = Leptris::XML::FFI.fetch_children(c_ptr)
+    pointers.each_with_index do |child_ptr, i|
+      case kinds[i]
+      when ELEMENT
+        visit_element(
+          Leptris::XML::Node.wrap(child_ptr, doc, node_type: ELEMENT),
+          handler, dispatched)
+      when TEXT
+        if dispatched[:characters]
+          handler.characters(utf8(NODE.leptris_text_node_get_content(child_ptr)))
+        end
+      when CDATA
+        if dispatched[:cdata]
+          handler.cdata_block(utf8(NODE.leptris_cdata_node_get_content(child_ptr)))
+        end
+      when COMMENT
+        if dispatched[:comment]
+          handler.comment(utf8(NODE.leptris_comment_node_get_content(child_ptr)))
+        end
+      when PI
+        if dispatched[:pi]
+          handler.processing_instruction(
+            utf8(NODE.leptris_pi_node_get_target(child_ptr)),
+            Leptris::XML::FFI.read_pi_data(
+              utf8(NODE.leptris_pi_node_get_data(child_ptr))))
+        end
+      end
+    end
+  end
+
+  def visit_element(element, handler, dispatched)
+    qname = element.prefix ? "#{element.prefix}:#{element.name}" : element.name
+    if dispatched[:start_prefix]
+      element.namespace_definitions.each do |ns|
+        handler.start_prefix_mapping(ns.prefix.to_s, ns.href.to_s)
+      end
+    end
+    if dispatched[:start_element]
+      if dispatched[:start_element] == :one_arg
+        handler.start_element(qname)
+      else
+        handler.start_element(qname, declared_pairs(element))
+      end
+    end
+    visit_children(element.c_ptr, element.document, handler, dispatched)
+    handler.end_element(qname) if dispatched[:end_element]
+    if dispatched[:end_prefix]
+      element.namespace_definitions.reverse_each do |ns|
+        handler.end_prefix_mapping(ns.prefix.to_s)
+      end
+    end
+  end
+
+  # start_element's pairs with xmlns declarations carried — the
+  # engine's streaming contract reports declarations among the
+  # attribute pairs at their byte positions. Since libleptris
+  # 1.9.18 (upstream #635, closing leptris-ruby#99's documented
+  # difference), the raw qname-ordered list reproduces the exact
+  # interleave.
+  def declared_pairs(element)
+    Leptris::XML::FFI.fetch_attributes_raw(element.c_ptr)
+  end
+
+  # [name, value] pairs in source order, read straight from the
+  # attribute chain — no Attr objects, no hash.
+  def attr_pairs(c_ptr)
+    pairs = []
+    attr = Leptris::XML::FFI.leptris_element_first_attribute(c_ptr)
+    until attr.nil? || attr.null?
+      pairs << [utf8(Leptris::XML::FFI.leptris_attribute_get_name(attr)),
+                utf8(Leptris::XML::FFI.leptris_attribute_get_value(
+                  c_ptr, attr))]
+      attr = Leptris::XML::FFI.leptris_attribute_next(attr)
+    end
+    pairs
+  end
+
+  def utf8(str)
+    str.nil? ? nil : str.force_encoding(Encoding::UTF_8)
+  end
+end