omnizip 0.4.6 → 0.4.8

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7dc6e02021b3915af5f65944e4d734bd3f95a5624b2a01c30100b6bbc36d5856
-  data.tar.gz: 998838c2bd3df94ced6617b9d199a0f2eab552e332d285bdc6819860fef50324
+  metadata.gz: 58a7dba25317b98c16b22362275b4dc813c37346359a98b6797bb51cf2c05a04
+  data.tar.gz: 7db43532ecbb62cd66a7daac98daf0da9b13fc1076b843b592020c1c69d679e5
 SHA512:
-  metadata.gz: f02b277ef180e076b5e0deb3847ed4cdf3f2a83abf829095779cdbfbdbc811891c8d9db9e000fb071c1d3bc164bd3cf4f031b8e19207b7d6e48232a21bf573dc
-  data.tar.gz: 4d20378f2973be45cc1cb691894b9c54916c1f5546d45a64a5143feaf8cabf0e053d8d604b8f30b6534d123ad12084021d9815b82945f78f5bfacd64f4daef96
+  metadata.gz: ec0c3490a5b88ff20b9f03404d14da7a40ee4d9ab2e432737ad7e2e497ddaeac33be3a670fbcb9c66ede17ca393fab38e3c9ca12b8948705a12544f990577762
+  data.tar.gz: 2aa7b51d4127e8495a8d6e862862942aedbc9d139907d7fef2d3502b3914cbf861599a889928784b773e187eb3a00d3ed0a2ee9bebe6ed7a84506fdd96727771

data/.rubocop_todo.yml

@@ -138,6 +138,8 @@ Metrics/AbcSize:
 # AllowedMethods: refine
 Metrics/BlockLength:
   Max: 81
+  Exclude:
+    - "lib/tasks/platform_gems.rake"
 
 # Offense count: 5
 # Configuration parameters: CountBlocks, CountModifierForms.

data/CHANGELOG.md

@@ -7,6 +7,37 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+- Archive-level tier for every handler: tar, cpio, iso, xar, 7z and
+  rar3/4/5 (with `password:` passthrough) route list(names) and
+  read_entry through the cdylib's whole-archive surface, falling back
+  to the Ruby readers on any Rust error or a missing library. rpm
+  rides the tier for read_entry once the dylib is ≥ 0.21.111 (which
+  strips the cpio `./` prefix so its entry names match the Ruby
+  handler's); rpm list and OLE stay pure-Ruby — OLE is a pinned model
+  divergence (Ruby lists top-level entries, Rust flattens the storage
+  tree), documented in the capability matrix and pinned by the new
+  cross-implementation differential spec.
+
+### Added
+- Prebuilt-binary distribution (parsanol model): platform gems
+  (x86_64/aarch64/arm Linux glibc+musl, arm64/x86_64 macOS,
+  x64/aarch64-mingw-ucrt, x64-mingw32) now vendor the prebuilt
+  `omnizip-ffi` cdylib — `gem install omnizip` gives Rust
+  acceleration with zero compilation on those platforms. The plain
+  `ruby` gem and every platform without a binary (JRuby,
+  TruffleRuby, anything else) stay fully functional on the pure-Ruby
+  core. The cdylibs are cross-built by omnizip-rs's release-binary
+  workflow and attached to each `omnizip-ffi-v*` release;
+  `rake platform_gems:build` packages them and `gem-build.yml`
+  smoke-tests each installed gem (tier active + pure-Ruby path with
+  `OMNIZIP_NO_RUST=1`).
+- `OMNIZIP_NO_RUST=1` kill switch forces the pure-Ruby core
+  everywhere; `Library.resolve_path` (public now) prefers the
+  vendored cdylib over dev checkouts; `Library.dylib_version`
+  reports the Rust release a loaded cdylib was built from
+  (`ozip_version`, new in omnizip-rs 0.21.109).
+
 ### Fixed
 - PPMd works for the first time: the pure-Ruby ppmd7 core cannot
   decode its own output (root-only decoder, 100-symbol cap — proven)

data/README.adoc

@@ -28,6 +28,28 @@ It provides both a command-line interface and a programmatic Ruby API, making it
 
 See link:readme-docs/compression-algorithms.adoc[Compression Algorithms Guide] for detailed information.
 
+==== Rust Acceleration (prebuilt, zero compilation)
+
+Where the platform gem exists, `gem install omnizip` ships a prebuilt
+`omnizip-ffi` cdylib and the codec + archive tiers route through it
+automatically — no Rust toolchain, no compilation:
+
+* x86_64-linux, aarch64-linux, arm-linux (glibc and musl)
+* arm64-darwin, x86_64-darwin
+* x64-mingw-ucrt, aarch64-mingw-ucrt, x64-mingw32
+
+Everywhere else — including JRuby/TruffleRuby and any platform without
+a binary — the gem stays fully functional on its pure-Ruby core (the
+acceleration is strictly optional). Three escape hatches:
+
+* `OMNIZIP_NO_RUST=1` — force the pure-Ruby core everywhere.
+* `OMNIZIP_FFI_DYLIB=/path/to/libomnizip_ffi` — load a specific build.
+* `rake rust:build` — build and vendor the cdylib yourself from a
+  checkout (developers).
+
+Any Rust-side failure also falls back to the Ruby core mid-operation,
+so `auto` mode is never worse than pure Ruby.
+
 ==== SDK-Compatible LZMA Mode (v0.2.0)
 
 Omnizip now provides SDK-compatible LZMA encoding and decoding for full XZ/LZMA tool compatibility.

data/lib/omnizip/archive_handlers/cpio_handler.rb

@@ -20,6 +20,11 @@ module Omnizip
       end
 
       def list(path, details: false, **_)
+        unless details
+          tier_names = Omnizip::Backends.archive_entry_names(path)
+          return tier_names if tier_names
+        end
+
         entries = Omnizip::Formats::Cpio.list(path)
         if details
           entries.map do |e|
@@ -32,6 +37,9 @@ module Omnizip
       end
 
       def read_entry(path, entry_name, **_)
+        tier = Omnizip::Backends.archive_read_entry(path, entry_name)
+        return tier unless tier.nil?
+
         entry = Omnizip::Formats::Cpio.list(path)
           .find { |e| e.name == entry_name }
         unless entry

data/lib/omnizip/archive_handlers/iso_handler.rb

@@ -20,6 +20,11 @@ module Omnizip
       end
 
       def list(path, details: false, **_)
+        unless details
+          tier_names = Omnizip::Backends.archive_entry_names(path)
+          return tier_names if tier_names
+        end
+
         entries = Omnizip::Formats::Iso.list(path)
         if details
           entries.map do |e|
@@ -32,6 +37,9 @@ module Omnizip
       end
 
       def read_entry(path, entry_name, **_)
+        tier = Omnizip::Backends.archive_read_entry(path, entry_name)
+        return tier unless tier.nil?
+
         entry = Omnizip::Formats::Iso.list(path)
           .find { |e| e.full_path == entry_name }
         unless entry

data/lib/omnizip/archive_handlers/rar_handler.rb

@@ -29,6 +29,11 @@ module Omnizip
       end
 
       def list(path, details: false, **_)
+        unless details
+          tier_names = Omnizip::Backends.archive_entry_names(path)
+          return tier_names if tier_names
+        end
+
         reader = Omnizip::Formats::Rar::Reader.new(path).open
         entries = reader.list_files
         if details
@@ -43,6 +48,9 @@ module Omnizip
       end
 
       def read_entry(path, entry_name, password: nil, **_)
+        tier = Omnizip::Backends.archive_read_entry(path, entry_name, password: password)
+        return tier unless tier.nil?
+
         Dir.mktmpdir("omnizip-rar-entry") do |dir|
           dest = File.join(dir, "entry")
           Omnizip::Formats::Rar::Decompressor.extract_entry(

data/lib/omnizip/archive_handlers/rpm_handler.rb

@@ -29,6 +29,9 @@ module Omnizip
       end
 
       def read_entry(path, entry_name, **_)
+        tier = Omnizip::Backends.archive_read_entry(path, entry_name)
+        return tier unless tier.nil?
+
         Dir.mktmpdir("omnizip-rpm-entry") do |dir|
           Omnizip::Formats::Rpm.extract(path, dir)
           dest = File.join(dir, entry_name)

data/lib/omnizip/archive_handlers/seven_zip_handler.rb

@@ -25,6 +25,11 @@ module Omnizip
       end
 
       def list(path, details: false, **options)
+        unless details
+          tier_names = Omnizip::Backends.archive_entry_names(path, password: options[:password])
+          return tier_names if tier_names
+        end
+
         with_reader(path, options) do |reader|
           entries = reader.list_files
           if details
@@ -40,6 +45,9 @@ module Omnizip
       end
 
       def read_entry(path, entry_name, **options)
+        tier = Omnizip::Backends.archive_read_entry(path, entry_name, password: options[:password])
+        return tier unless tier.nil?
+
         with_reader(path, options) do |reader|
           entry = reader.list_files.find { |e| e.name == entry_name }
           raise Errno::ENOENT, "Entry not found: #{entry_name}" unless entry

data/lib/omnizip/archive_handlers/tar_handler.rb

@@ -22,6 +22,11 @@ module Omnizip
       end
 
       def list(path, details: false, **_)
+        unless details
+          tier_names = Omnizip::Backends.archive_entry_names(path)
+          return tier_names if tier_names
+        end
+
         entries = Omnizip::Formats::Tar.list(path)
         if details
           entries.map do |entry|
@@ -58,7 +63,10 @@ module Omnizip
         end
       end
 
-      def read_entry(path, entry_name)
+      def read_entry(path, entry_name, **_)
+        tier = Omnizip::Backends.archive_read_entry(path, entry_name)
+        return tier unless tier.nil?
+
         data = nil
         Omnizip::Formats::Tar.open(path) do |reader|
           entry = reader.entries.find { |e| e.name == entry_name }

data/lib/omnizip/archive_handlers/xar_handler.rb

@@ -21,6 +21,11 @@ module Omnizip
       end
 
       def list(path, details: false, **_)
+        unless details
+          tier_names = Omnizip::Backends.archive_entry_names(path)
+          return tier_names if tier_names
+        end
+
         entries = Omnizip::Formats::Xar.list(path)
         if details
           entries.map do |e|
@@ -33,6 +38,9 @@ module Omnizip
       end
 
       def read_entry(path, entry_name, **_)
+        tier = Omnizip::Backends.archive_read_entry(path, entry_name)
+        return tier unless tier.nil?
+
         Dir.mktmpdir("omnizip-xar-entry") do |dir|
           Omnizip::Formats::Xar.extract(path, dir)
           dest = File.join(dir, entry_name)

data/lib/omnizip/backends.rb

@@ -96,15 +96,18 @@ module Omnizip
 
       # Whole-archive tier helpers: nil means "Rust unavailable or
       # entry not found — caller falls back to the Ruby reader".
-      def archive_entry_names(path)
-        Omnizip::Implementations::Rust::Archive.open(File.binread(path)) { |a| return a.entry_names }
+      # Encrypted formats (rar, 7z) pass password:.
+      def archive_entry_names(path, password: nil)
+        Omnizip::Implementations::Rust::Archive.open(File.binread(path), password: password) do |a|
+          return a.entry_names
+        end
       rescue Omnizip::Implementations::Rust::Archive::LibraryMissing, Omnizip::Implementations::Rust::Error, StandardError
         nil
       end
 
       # rubocop:disable-next Lint/ReturnInVoidContext
-      def archive_read_entry(path, entry_name)
-        Omnizip::Implementations::Rust::Archive.open(File.binread(path)) do |a|
+      def archive_read_entry(path, entry_name, password: nil)
+        Omnizip::Implementations::Rust::Archive.open(File.binread(path), password: password) do |a|
           idx = a.entry_names.index(entry_name)
           return nil if idx.nil?
 

data/lib/omnizip/implementations/rust/library.rb

@@ -76,30 +76,47 @@ module Omnizip
             }
           end
 
-          private
-
-          def open
-            path = resolve_path
-            return nil if path.nil?
-
-            handle = Fiddle.dlopen(path.to_s)
-            funcs = function_table.each_with_object({}) do |(key, (name, args, ret)), h|
-              h[key] = Fiddle::Function.new(handle[name], args, ret)
-            end
-            new(funcs, handle)
-          rescue StandardError => e # includes Fiddle::DLError
-            warn "omnizip: rust backend unavailable (#{e.message}); using pure Ruby" if ENV["OMNIZIP_BACKEND"] == "rust"
+          # The Rust release the loaded cdylib was built from (e.g.
+          # "0.21.108"), read through the ozip_version symbol — the
+          # platform-gem smoke gate asserts it matches. nil when the
+          # library is absent or predates the symbol.
+          def dylib_version
+            handle = instance&.instance_handle
+            return nil if handle.nil?
+
+            func = Fiddle::Function.new(handle["ozip_version"], [], Fiddle::TYPE_VOIDP)
+            ptr = func.call
+            ptr.null? ? nil : ptr.to_s
+          rescue StandardError
             nil
           end
 
-          def resolve_path
+          # Resolve the cdylib path. Precedence:
+          #
+          #   1. OMNIZIP_NO_RUST=1 — hard kill switch (always nil, so
+          #      the pure-Ruby core handles everything; also the smoke
+          #      gate for "works without Rust").
+          #   2. OMNIZIP_FFI_DYLIB — explicit path (developer override).
+          #   3. vendor/ — the prebuilt cdylib. Platform gems ship it
+          #      here and `rake rust:build` writes here; rubygems
+          #      already matched the platform at install time, so no
+          #      runtime architecture probing is needed and the wrong
+          #      arch cannot be picked.
+          #   4. ext/ (legacy location).
+          #   5. A sibling omnizip-rs checkout.
+          #
+          # `dirs` overrides 3-5 (spec seam: staged candidate paths).
+          def resolve_path(dirs = nil)
+            return nil if ENV.fetch("OMNIZIP_NO_RUST", nil) == "1"
+
             explicit = ENV.fetch("OMNIZIP_FFI_DYLIB", nil)
             return Pathname.new(explicit) if explicit && File.file?(explicit)
 
-            candidates = [
+            candidates = dirs || [
+              Pathname.new(__dir__).join("../../../../vendor"),
               Pathname.new(__dir__).join("../../../../ext/libomnizip_ffi"),
-              sibling_checkout,
-            ].compact.flatten
+              *sibling_checkout,
+            ]
 
             %w[.dylib .so .dll].each do |ext|
               candidates.each do |dir|
@@ -110,6 +127,22 @@ module Omnizip
             nil
           end
 
+          private
+
+          def open
+            path = resolve_path
+            return nil if path.nil?
+
+            handle = Fiddle.dlopen(path.to_s)
+            funcs = function_table.each_with_object({}) do |(key, (name, args, ret)), h|
+              h[key] = Fiddle::Function.new(handle[name], args, ret)
+            end
+            new(funcs, handle)
+          rescue StandardError => e # includes Fiddle::DLError
+            warn "omnizip: rust backend unavailable (#{e.message}); using pure Ruby" if ENV["OMNIZIP_BACKEND"] == "rust"
+            nil
+          end
+
           # A sibling omnizip-rs checkout: ../omnizip-rs relative to
           # this gem's repository root.
           def sibling_checkout

data/lib/omnizip/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Omnizip
-  VERSION = "0.4.6"
+  VERSION = "0.4.8"
 end

data/lib/tasks/platform_gems.rake

@@ -0,0 +1,147 @@
+# frozen_string_literal: true
+
+# Build per-platform gems that vendor a prebuilt omnizip-ffi cdylib,
+# so `gem install omnizip` gives Rust acceleration with zero
+# compilation (parsanol distribution model, adopted 2026-09-21).
+#
+#   # after downloading the release-binary artifacts:
+#   gh release download omnizip-ffi-v0.21.108 -R omnizip/omnizip-rs \
+#     -p 'libomnizip_ffi-*.tar.gz' -D artifacts
+#   bundle exec rake platform_gems:build DIR=artifacts
+#
+# Each target tarball maps to one rubygems platform; the built gems
+# land in pkg/. The plain `ruby` platform gem keeps shipping without
+# a binary (pure-Ruby core; OMNIZIP_NO_RUST=1 disables the tier).
+
+# rust target → rubygems platform (keep in sync with
+# omnizip-rs .github/workflows/release-binary.yml)
+PLATFORM_GEM_TARGETS = {
+  "x86_64-unknown-linux-gnu" => "x86_64-linux",
+  "aarch64-unknown-linux-gnu" => "aarch64-linux",
+  "arm-unknown-linux-gnueabihf" => "arm-linux",
+  "x86_64-unknown-linux-musl" => "x86_64-linux-musl",
+  "aarch64-unknown-linux-musl" => "aarch64-linux-musl",
+  "arm-unknown-linux-musleabihf" => "arm-linux-musl",
+  "aarch64-apple-darwin" => "arm64-darwin",
+  "x86_64-apple-darwin" => "x86_64-darwin",
+  "x86_64-pc-windows-msvc" => "x64-mingw-ucrt",
+  "aarch64-pc-windows-msvc" => "aarch64-mingw-ucrt",
+  "x86_64-pc-windows-gnu" => "x64-mingw32",
+}.freeze
+
+namespace :platform_gems do
+  desc "Build one platform gem: TARGET=<rust target> DYLIB=<cdylib path>"
+  task :one do
+    target = ENV.fetch("TARGET") { abort "TARGET=<rust target> required" }
+    dylib = ENV.fetch("DYLIB") { abort "DYLIB=<cdylib path> required" }
+    platform = PLATFORM_GEM_TARGETS[target] or abort "unknown target #{target} (see lib/tasks/platform_gems.rake)"
+    out = build_platform_gem(platform, dylib)
+    puts "built: #{out}"
+  end
+
+  desc "Build platform gems for every tarball in DIR=libomnizip_ffi-<target>.tar.gz"
+  task :build do
+    dir = ENV.fetch("DIR") { abort "DIR=<artifacts dir> required" }
+    # Snapshot the pristine file list once. Gem::Specification.load
+    # caches by path and returns the SAME object on every call, so a
+    # per-call load + files += would leak the previous platform's
+    # cdylib into the next gem.
+    gem_root = File.expand_path("../..", __dir__)
+    base_spec = Gem::Specification.load(File.join(gem_root, "omnizip.gemspec"))
+    abort "omnizip.gemspec failed to load" unless base_spec
+    base_files = base_spec.files.select { |rel| File.file?(File.join(gem_root, rel)) }.freeze
+
+    Dir.glob(File.join(dir, "libomnizip_ffi-*.tar.gz")).each do |tarball|
+      target = File.basename(tarball, ".tar.gz").delete_prefix("libomnizip_ffi-")
+      platform = PLATFORM_GEM_TARGETS[target] or abort "no rubygems platform mapping for #{target}"
+      require "tmpdir"
+      Dir.mktmpdir do |tmp|
+        binary = extract_binary(tarball, tmp)
+        out = build_platform_gem(platform, binary, base_files)
+        puts "built: #{out} (#{File.size(out)} bytes)"
+      end
+    end
+  end
+
+  desc "Push every already-built platform gem under pkg/ to rubygems (idempotent)"
+  task :release do
+    require "rake"
+    require "rubygems/package"
+    gem_root = File.expand_path("../..", __dir__)
+    pkg = File.join(gem_root, "pkg")
+    gems = Dir.glob(File.join(pkg, "omnizip-*.gem"))
+    abort "no platform gems under #{pkg} — run platform_gems:build first" if gems.empty?
+
+    # Pushes only what's already built in pkg/. Invoked by the
+    # platform-gem push job, which dispatches the trusted
+    # release.yml with next_version=skip + release_command override
+    # so the cimas reusable workflow authenticates via the
+    # already-trusted OIDC configuration and runs this task verbatim.
+    #
+    # Idempotent against re-push of an already-published version
+    # (cimas reusable handles "already been pushed" via the
+    # gem-idempotent-push-guard action).
+    gems.each do |path|
+      puts "pushing #{File.basename(path)}"
+      run_gem_push(path)
+    end
+  end
+
+  def extract_binary(tarball, tmp)
+    system("tar", "-xzf", tarball, "-C", tmp) or abort "tar failed for #{tarball}"
+    Dir.glob(File.join(tmp, "*")).first or abort "empty tarball #{tarball}"
+  end
+
+  def run_gem_push(path)
+    require "rubygems/command/push_command"
+    cmd = Gem::Command::PushCommand.new
+    cmd.invoke("push", path)
+  rescue StandardError => e
+    raise if !/already been pushed|Repushing of gem versions is not allowed/i.match?(e.message)
+
+    warn "skip (already published): #{File.basename(path)}"
+  end
+
+  # Stage the tracked gem files plus the vendored cdylib, flip the
+  # gemspec platform, and build. `base_files` is the pristine
+  # gemspec file list (frozen); we ASSIGN a fresh list every call
+  # rather than mutating via +=, because Gem::Specification.load
+  # hands back a cached object.
+  def build_platform_gem(platform, dylib, base_files = nil)
+    require "fileutils"
+    require "rubygems/package"
+    require "tmpdir"
+
+    gem_root = File.expand_path("../..", __dir__)
+    spec = Gem::Specification.load(File.join(gem_root, "omnizip.gemspec"))
+    abort "omnizip.gemspec failed to load" unless spec
+    base_files ||= spec.files.select { |rel| File.file?(File.join(gem_root, rel)) }
+
+    Dir.mktmpdir do |tmp|
+      stage = File.join(tmp, "stage")
+      base_files.each do |rel|
+        dst = File.join(stage, rel)
+        FileUtils.mkdir_p(File.dirname(dst))
+        FileUtils.cp(File.join(gem_root, rel), dst)
+      end
+
+      vendored = "vendor/libomnizip_ffi#{File.extname(dylib)}"
+      FileUtils.mkdir_p(File.join(stage, "vendor"))
+      FileUtils.cp(dylib, File.join(stage, vendored))
+      abort "staged cdylib missing: #{vendored}" unless File.file?(File.join(stage, vendored))
+
+      spec.platform = Gem::Platform.new(platform)
+      spec.files = base_files + [vendored]
+      spec.test_files = []
+
+      Dir.chdir(stage) do
+        Gem::Package.build(spec)
+      end
+      built = Dir.glob(File.join(stage, "omnizip-*.gem")).first or
+        abort "gem build produced nothing for #{platform}"
+      FileUtils.mkdir_p(File.join(gem_root, "pkg"))
+      FileUtils.mv(built, File.join(gem_root, "pkg", File.basename(built)))
+      File.join(gem_root, "pkg", File.basename(built))
+    end
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: omnizip
 version: !ruby/object:Gem::Version
-  version: 0.4.6
+  version: 0.4.8
 platform: ruby
 authors:
 - Ribose Inc.
@@ -724,6 +724,7 @@ files:
 - lib/omnizip/zip/input_stream.rb
 - lib/omnizip/zip/output_stream.rb
 - lib/tasks/msi_test_files.rake
+- lib/tasks/platform_gems.rake
 - lib/tasks/rust_backend.rake
 - readme-docs/advanced-features.adoc
 - readme-docs/api-usage.adoc