leptris 1.9.162.7 → 1.9.162.8

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 57f929ff4841376940854db6d4c56ed6e5d781ca031b2c24d6d431da168e58c5
-  data.tar.gz: 31770ff680d92ae5d6ab85ca295cab3c5786fcd443cef80acfb8b20d437d6db3
+  metadata.gz: ec940fa88dc62b9bd98c0268fb7769274c2b919cc34b63d15b8b9f846b4f6374
+  data.tar.gz: b8167cf9190c65b87d6cc91dd7c8a949343187eff563758c0b6c9c4c07c5c541
 SHA512:
-  metadata.gz: f3e15b12e18df6ed283c9aef8971b10a779155ca823ccffe0389493776d8c03735f1130a5c47e7c4057f8c8baf1864736971fcc9a7154dec865979544452e2ea
-  data.tar.gz: e5fcb4356b6ab0e18a97f89b14db6a7da02c49f79edb95661155c2858391a75eb27b1fb49617d325730e576dbc8896debcc91ec504543f68cdbec5b92e3a3cf4
+  metadata.gz: 3bbe8b668a992020233f5a7c5f9a26aed7701a227db29cf15e5e80209df45e5be0fbe0f32a9de6459dd9ebfb2e4f4c134c99c8282501a7291e7a8a1924118011
+  data.tar.gz: 39d84a702970ad1c02b369c3114c2d3abf0efbf98ffd5dd55e0c178326f68f9af1ac8946f84918a69b1fbc610e287f14c875feab8d24a339c7d01845a38a8ce0

data/CHANGELOG.md

@@ -5,6 +5,23 @@ 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.162.8] - 2026-09-14
+
+### Added
+
+- **Zero-setup TruffleRuby/JRuby (#160)**: the `ruby`-platform gem
+  now vendors `libleptris` + `libutf8proc` for arm64/x86_64-darwin
+  and x86_64/aarch64-linux (plus musl fallbacks) under
+  `lib/leptris/vendor/<platform>/`; `FFI.libleptris_candidates`
+  probes them first at require time. Both engines activate and
+  load with no system library and no env vars — the release
+  assembly gathers the binaries from every platform build leg.
+  MRI behavior is unchanged (platform gems resolve first); a
+  forced `--platform ruby` MRI install also works via the vendor
+  tree. Fixed a split-library hazard along the way: the native
+  read layer now resolves the exact image the FFI layer loads
+  (two differently-pathed copies split per-document state).
+
 ## [1.9.162.7] - 2026-09-14
 
 ### Added

data/README.adoc

@@ -60,20 +60,21 @@ export LEPTRIS_LIB_PATH=/usr/local/lib/libleptris.dylib
 If Leptris can't find the library at startup, every `parse` call raises
 `LoadError`.
 
-=== Alternative engines: TruffleRuby and JRuby (#160)
+=== Alternative engines: TruffleRuby and JRuby (#160) — zero setup
 
-The gem ships a plain `ruby`-platform variant alongside the precompiled
-platform gems, so Bundler activates `leptris` on TruffleRuby and JRuby
-(the binding is FFI-based — no MRI C extension anywhere). Those engines
-filter out precompiled platform gems at activation and always resolve
-the `ruby` variant, which does not vendor the native library:
+The `ruby`-platform variant (what TruffleRuby and JRuby resolve)
+vendors precompiled `libleptris` + `libutf8proc` binaries for the
+common engine platforms under `lib/leptris/vendor/`:
 
-1. Install `libleptris` on the host — build from source (above) or set
-   `LEPTRIS_LIB_PATH=/path/to/libleptris.{so,dylib}`.
-2. `gem install leptris` (or `bundle install`) — activation succeeds
-   like on MRI, and FFI loads the system library at require time.
+- `arm64-darwin`, `x86_64-darwin`
+- `x86_64-linux`, `aarch64-linux` (glibc; the musl variants are
+  tried as fallback for Alpine hosts)
 
-The startup `LoadError` names this remedy when the library is missing.
+`gem install leptris` just works on both engines — the FFI layer
+selects the matching vendored binary at require time (the binding
+is FFI-based; no MRI C extension anywhere). `LEPTRIS_LIB_PATH`
+still overrides, and a system library remains the fallback for
+OSes the variant does not carry.
 
 == Parsing
 

data/Rakefile

@@ -189,9 +189,15 @@ task "gem:native:any" do
   sh "rake platform:any gem"
 end
 
-desc "Define the gem task to build the pure-Ruby gem"
+desc "Define the gem task to build the ruby-platform gem"
 task "platform:any" do
   spec = Gem::Specification::load("leptris.gemspec").dup
+  # Zero-setup TruffleRuby/JRuby (#160): per-OS binaries staged
+  # under lib/leptris/vendor/<platform>/ by the release assembly
+  # (or by hand: cp from each platform build). Absent on a plain
+  # checkout — the variant then carries no binaries and the
+  # system-library / LEPTRIS_LIB_PATH path applies as before.
+  spec.files += Dir.glob("lib/leptris/vendor/**/*")
   task = Gem::PackageTask.new(spec)
   task.define
 end

data/TODO.perf/01-ext-accelerated-default-reads.md

@@ -0,0 +1,18 @@
+# 01 — Ext-accelerated default reads (no FFI marshaling on hot paths)
+
+Status: TODO
+
+The default binding's hot reads each pay FFI per-call marshaling
+(:string returns allocate through FFI, args marshal through the
+boundary — ~200-500ns vs ~50ns for a direct ext call). The native
+bundle already dlsyms every reader; add address-based C functions
+the DEFAULT binding classes call when the bundle is loaded:
+
+- Element#name / #content / #[]
+- Node#children / #element_children (bulk: one C pass allocating
+  binding wrappers — the bulk_wrap shape, 1.27-1.30x measured)
+- Element#expanded_name (three out-params today)
+
+Gate: suite green with AND without the bundle; drift-record rows
+(attr reads 1.88x, text 6.18x) must improve; cold-walk gate must
+not regress (cold-walk-regression-gate memory).

data/TODO.perf/02-auto-enable-native-layer.md

@@ -0,0 +1,15 @@
+# 02 — Auto-enable the native layer when the bundle is present
+
+Status: TODO
+
+Today `require "leptris/xml/native_layer"` is opt-in. End-state:
+`require "leptris"` quietly probes for the vendored native.bundle
+and, when present, activates the acceleration (01 makes the
+default classes benefit). Silent fallback to FFI when absent
+(ruby-variant on TruffleRuby/JRuby, custom builds). The explicit
+native_layer require remains the parallel-API entry
+(NativeNode builders).
+
+Requires: 01 (so auto-enable accelerates the DEFAULT API, not a
+parallel one), and a divergence test — same specs pass in both
+modes (the suite already runs both; make it explicit).

data/TODO.perf/03-bulk-xpath-result-materialization.md

@@ -0,0 +1,13 @@
+# 03 — Bulk XPath result materialization
+
+Status: TODO
+
+NodeSet#fetch materializes results per node (wrap per item +
+ResultText/ResultAttr captures). The #185 profile counted
+NodeSet#initialize at 2.8% and Class#new 11.7% of walk wall —
+result materialization shares that class of cost. Batch via the
+ext: one C pass over leptris_xpath_result_get_node(i) building
+the Ruby array with kinds, capturing text values in C.
+
+Gate: xpath-heavy specs unchanged; xpath row (28,878 ips small)
+improves on the battery.

data/TODO.perf/04-ext-bound-serialization.md

@@ -0,0 +1,11 @@
+# 04 — Serialization buffer cycle in C
+
+Status: TODO
+
+FFI.serialize_into_string does the two-call sized protocol
+(needed probe, then copy) with Ruby-side buffer management per
+to_xml call. Bind the cycle in the ext: one C function taking the
+ffi_function pointer + node address, returning a Ruby String.
+
+Gate: serialize row (3.24x baseline) improves; c14n specs
+byte-identical.

data/TODO.perf/05-native-surface-completion.md

@@ -0,0 +1,12 @@
+# 05 — Complete the NativeNode read surface
+
+Status: TODO
+
+Missing on NativeNode vs Element: #attributes (bulk attr hash),
+#attribute_nodes, #namespaces / #prefix, #line / #byte_offset,
+#inner_html / #to_xml (delegate to binding serialization), write
+faces beyond add_child (set_attribute, set_text, remove). Reads
+first; writes stay FFI (cold) unless measured otherwise.
+
+Gate: native_layer specs mirror the binding feature specs;
+descriptor_walk parity where applicable.

data/TODO.perf/06-perf-battery-native-legs.md

@@ -0,0 +1,10 @@
+# 06 — Native-layer legs in the perf battery + drift record
+
+Status: TODO
+
+benchmark/ gains native-layer legs (walk/build/attr rows via
+NativeNode beside the binding rows) so the drift record tracks
+both surfaces; TODO.restructure/17's record gains a native table.
+
+Gate: one command (rake benchmark:all or the two scripts) emits
+both tables; load-gated per the shared-machine discipline.

data/lib/leptris/version.rb

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

data/lib/leptris/xml/ffi.rb

@@ -7,6 +7,50 @@ module Leptris
     module FFI
       extend ::FFI::Library
 
+      # The per-OS vendor directory of the ruby-platform gem
+      # (zero-setup TruffleRuby/JRuby, #160): binaries for the
+      # common engines' OSes under lib/leptris/vendor/<platform>/.
+      # Returns [] in platform gems (no vendor tree) and on
+      # OSes the variant does not carry.
+      # Dir-name candidates for a RUBY_PLATFORM string, in
+      # preference order (glibc before musl — dlopen falls through
+      # on musl hosts).
+      def self.vendor_platforms_for(ruby_platform)
+        case ruby_platform
+        when /arm64.*darwin|aarch64.*darwin/ then %w[arm64-darwin]
+        when /x86_64.*darwin/ then %w[x86_64-darwin]
+        when /aarch64.*linux/ then %w[aarch64-linux aarch64-linux-musl]
+        when /x86_64.*linux/ then %w[x86_64-linux x86_64-linux-musl]
+        else []
+        end
+      end
+
+      def self.vendor_dirs
+        vendor_platforms_for(RUBY_PLATFORM)
+          .map { |d| File.expand_path("../../leptris/vendor/#{d}", __dir__) }
+          .select { |dir| File.directory?(dir) }
+      end
+
+      # THE libleptris candidate list, in order — shared with the
+      # native read layer's resolve!. Single source of truth is
+      # load-bearing: two differently-pathed copies of the library
+      # load as two images with split per-document state.
+      def self.libleptris_candidates
+        [
+          ENV["LEPTRIS_LIB_PATH"],
+          *vendor_dirs.flat_map { |d|
+            %w[libleptris.dylib libleptris.so libleptris.dll]
+              .map { |n| File.join(d, n) }
+          },
+          File.expand_path("../../libleptris.dylib", __dir__),
+          File.expand_path("../../libleptris.so", __dir__),
+          File.expand_path("../../libleptris.dll", __dir__),
+          "/usr/local/lib/libleptris.dylib",
+          "/usr/local/lib/libleptris.so",
+          "leptris",
+        ].compact
+      end
+
       # libleptris links utf8proc via @rpath (TODO.restructure/20
       # — fn:normalize-unicode). dlopen the VENDORED utf8proc
       # FIRST: once its install name is loaded, dyld resolves
@@ -17,6 +61,10 @@ module Leptris
       # never consults it.
       begin
         ffi_lib [
+          *Leptris::XML::FFI.vendor_dirs.flat_map { |d|
+            %w[libutf8proc.3.dylib libutf8proc.so.3 libutf8proc.so
+               utf8proc.dll].map { |n| File.join(d, n) }
+          },
           File.expand_path("../../libutf8proc.3.dylib", __dir__),
           File.expand_path("../../libutf8proc.so.3", __dir__),
           File.expand_path("../../libutf8proc.so", __dir__),
@@ -29,15 +77,7 @@ module Leptris
       # Issue leptris-ruby#49: name the remedy when the library is
       # missing (ruby-platform gem without a vendored libleptris).
       begin
-        ffi_lib [
-          ENV["LEPTRIS_LIB_PATH"],
-          File.expand_path("../../libleptris.dylib", __dir__),
-          File.expand_path("../../libleptris.so", __dir__),
-          File.expand_path("../../libleptris.dll", __dir__),
-          "/usr/local/lib/libleptris.dylib",
-          "/usr/local/lib/libleptris.so",
-          "leptris",
-        ].compact
+        ffi_lib Leptris::XML::FFI.libleptris_candidates
       rescue LoadError => e
         raise LoadError, <<~MSG
           leptris: cannot load the vendored libleptris library.

data/lib/leptris/xml/native_layer.rb

@@ -29,29 +29,26 @@ rescue LoadError => e
 end
 
 module Leptris::XML::Native
-  LIB_CANDIDATES = [
-    ENV["LEPTRIS_LIB_PATH"],
-    File.expand_path("../../libleptris.dylib", __dir__),
-    File.expand_path("../../libleptris.so", __dir__),
-    File.expand_path("../../libleptris.dll", __dir__),
-    "libleptris",
-  ].compact.freeze
+  # FFI.libleptris_candidates is the single source of truth — the
+  # native layer MUST dlsym the exact image the FFI layer loaded,
+  # or two library instances split per-document state.
+  def self.lib_candidates
+    Leptris::XML::FFI.libleptris_candidates
+  end
 end
 
-candidates = Leptris::XML::Native::LIB_CANDIDATES
+candidates = Leptris::XML::Native.lib_candidates
 resolved = candidates.any? do |path|
-  resolved = Leptris::XML::Native::LIB_CANDIDATES.any? do |path|
-    begin
-      Leptris::XML::NativeNode.resolve!(path)
-      true
-    rescue RuntimeError
-      false
-    end
+  begin
+    Leptris::XML::NativeNode.resolve!(path)
+    true
+  rescue RuntimeError
+    false
   end
-  raise LoadError,
-    "leptris: native layer loaded but libleptris could not be " \
-    "resolved from #{candidates.inspect}" unless resolved
 end
+raise LoadError,
+  "leptris: native layer loaded but libleptris could not be " \
+  "resolved from #{candidates.inspect}" unless resolved
 
 class Leptris::XML::Document
   # Separate identity cache for NativeNodes so binding Node.wrap

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: leptris
 version: !ruby/object:Gem::Version
-  version: 1.9.162.7
+  version: 1.9.162.8
 platform: ruby
 authors:
 - Ribose Inc.
@@ -69,6 +69,12 @@ files:
 - LICENSE.md
 - README.adoc
 - Rakefile
+- TODO.perf/01-ext-accelerated-default-reads.md
+- TODO.perf/02-auto-enable-native-layer.md
+- TODO.perf/03-bulk-xpath-result-materialization.md
+- TODO.perf/04-ext-bound-serialization.md
+- TODO.perf/05-native-surface-completion.md
+- TODO.perf/06-perf-battery-native-legs.md
 - TODO.restructure/01-constraint-compliance-audit.md
 - TODO.restructure/02-deep-copy-seam.md
 - TODO.restructure/03-evaluation-context-seam.md
@@ -101,6 +107,18 @@ files:
 - ext/leptris/native/native.c
 - leptris.gemspec
 - lib/leptris.rb
+- lib/leptris/vendor/aarch64-linux-musl/libleptris.so
+- lib/leptris/vendor/aarch64-linux-musl/libutf8proc.so.3
+- lib/leptris/vendor/aarch64-linux/libleptris.so
+- lib/leptris/vendor/aarch64-linux/libutf8proc.so.3
+- lib/leptris/vendor/arm64-darwin/libleptris.dylib
+- lib/leptris/vendor/arm64-darwin/libutf8proc.3.dylib
+- lib/leptris/vendor/x86_64-darwin/libleptris.dylib
+- lib/leptris/vendor/x86_64-darwin/libutf8proc.3.dylib
+- lib/leptris/vendor/x86_64-linux-musl/libleptris.so
+- lib/leptris/vendor/x86_64-linux-musl/libutf8proc.so.3
+- lib/leptris/vendor/x86_64-linux/libleptris.so
+- lib/leptris/vendor/x86_64-linux/libutf8proc.so.3
 - lib/leptris/version.rb
 - lib/leptris/xml.rb
 - lib/leptris/xml/attr.rb