zon-rb 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a2422c6a081bd6076413277434ed67b585057cba3858faf67b78e4f21efdfa74
-  data.tar.gz: e139d7d3da59ab7e82b7daca9267fb6b94c17b3437afbfb7bc21e67ca798682a
+  metadata.gz: 818004dd00ec5169c64a80953c55e2b49f9b92a7691aef46251463e671c8a033
+  data.tar.gz: 2519a754dd2e2cc19ee40c8dbfa7c2ae0370e5bd33fc6e69f7dcc0bebd56eb00
 SHA512:
-  metadata.gz: a235b0b85a9d90cd4f7f1a132abb87609f5f7c5575922de790818072ebb1d84e63fee96a62eee3757e57bf6433ca8e9d7ffff037e8ffdc1259d8e582b1b2343b
-  data.tar.gz: f5f160c938a43879d6b428cdb0d55ccead5ba9baaa9bf31362137dfe84f6e61a19021890d5bc9d1049e591dac9d55e39f0e1a0c4408a0bdf89ec31cac16b112a
+  metadata.gz: e03c8137c996cb03adc77ddebc0afbb95a6cb078f635052eb88dfb2b782365e7ca335aa5436560619b20e246d7693ba96860625943b780deb15c1a2386ef9472
+  data.tar.gz: 497d4a8b6b830abe6b533fdbb22407524616f5b44727d7c73d8a0f9e49105a7db6d2941396c3a904e4dcfc029c0f5157eb4dfe1db63b22248032d56052403344

data/README.md

@@ -114,6 +114,18 @@ manifest = Zon::Zig::Manifest.new o
 # ...
 ```
 
+### Zig Package Hash
+
+Given a path `pdir` that points to the root of a Zig package, one can calculate the packages hash using the `Zon::Hasher`:
+
+```ruby
+hasher = Zon::Zig::Hasher.new pdir
+hasher.hash
+# Hash with the format nnnn-vvvv-XXXX..XXXX
+# e.g.: uuid-0.4.0-oOieIR2AAAChAUVBY4ABjYI1XN0EbVALmiN0JIlggC3i
+result = hasher.result
+```
+
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.

data/lib/zon/hasher.rb

@@ -0,0 +1,176 @@
+require "digest"
+require "find"
+require "base64"
+
+module Zon
+  module Zig
+    ##
+    # Produces a package hash of the format: $name-$semver-$hashplus
+    #
+    # Along with 200 bits of a SHA-256, a package hash includes:
+    # - package name
+    # - package version
+    # - id component of the package fingerprint
+    # - total unpacked size on disk
+    #
+    # The following steps are taken to calculate the hash:
+    # 1. Read the list of included paths from the manifest, i.e. files that are part of the package.
+    # 2. Resolve the paths:
+    #     - for directories: include all files that are within the directory or a child dir.
+    #     - for files: include the file
+    #     - for symlinks: TODO
+    # 3. Sort the paths by:
+    #     1. Lexographical order
+    #     2. by length
+    # 4. For every included file:
+    #     - Calculate a SHA-256 over: RELATIVE_PATH_FROM_PKG_ROOT || 0x0000 || DATA
+    #     - Record the file size in bytes
+    #     - TODO: the 0x0000 will probably change in the future
+    # 5. Calculate a SHA-256 sum over all calculated file hashes
+    #     - respecting the previously mentioned sorting rules.
+    # 6. Sum up the sizes of all files into a u32 (sizes that don't fit into a 32-bit unsingned integer will be saturated with the value 2**32 - 1)
+    # 7. Produce the package hash
+    class Hasher
+      attr_reader :paths, :total_size, :digest
+
+      SUPPORTED_ZIG_VERSIONS = ["0.14.0", "0.14.1", "0.15.1", "0.15.2"]
+
+      def initialize(package_path, manifest_name: "build.zig.zon")
+        # Make sure we have a valid path to work with
+        @package_path = package_path
+        raise ArgumentError, "not a directory '#{@package_path}'" if not Dir.exist? @package_path
+
+        manifest_path = File.join(@package_path, manifest_name)
+        raise ArgumentError, "no manifest '#{manifest_name}' in '#{@package_path}'" if not File.exist? manifest_path
+
+        @manifest = Zon.parse(File.open(manifest_path))
+        raise ArgumentError, "no 'paths' field in ZON manifest '#{manifest_path}'" if not @manifest.key? :paths
+        raise ArgumentError, "no 'name' field in ZON manifest '#{manifest_path}'" if not @manifest.key? :name
+        raise ArgumentError, "no 'version' field in ZON manifest '#{manifest_path}'" if not @manifest.key? :version
+        raise ArgumentError, "no 'fingerprint' field in ZON manifest '#{manifest_path}'" if not @manifest.key? :fingerprint
+        
+        @paths = []
+        @results = {}
+        @total_size = 0
+        @digest = nil
+
+        @manifest[:paths].each do |path|
+          full_path = File.join(@package_path, path)
+
+          if File.directory? full_path
+            f = Find.find(full_path)
+            f.each do |p|
+              next if File.directory? p
+              
+              pstr = p.delete_prefix(@package_path)[1..]
+              @paths.append(pstr) if not @paths.include? pstr
+            end
+          elsif File.file? full_path or File.symlink? full_path
+            pstr = full_path.delete_prefix(@package_path)[1..]
+            @paths.append(pstr) if not @paths.include? pstr
+          end
+        end
+
+        @paths = @paths.sort_by { |str| [str, -str.length] }
+      end
+
+      def name
+        String(@manifest[:name])
+      end
+
+      def version
+        @manifest[:version]
+      end
+
+      def hash
+        @total_size = 0
+        @digest = nil
+        
+        # Hash all files individually  
+        @paths.each do |str|
+          @results[str] = Zon::Zig::Hasher::hash_file(@package_path, str)
+        end 
+
+        sha2 = Digest::SHA2.new
+
+        @paths.each do |str|
+          res = @results[str]
+
+          @total_size += res[:size]
+          sha2.update [res[:digest]].pack('H*')
+        end
+
+        @digest = sha2.hexdigest
+      end
+      
+      ##
+      # Get the ID part of the fingerprint
+      def get_id
+        @manifest[:fingerprint] & 0xffffffff
+      end
+      
+      ##
+      # Get the calculated, total size of the unpacked package.
+      def get_saturated_size
+        max_uint32 = 2**32 - 1
+
+        if @total_size > max_uint32
+          max_uint32
+        else
+          @total_size
+        end
+      end
+
+      def result
+        Zon::Zig::Hasher::make_hash(@digest, name, version, get_id, get_saturated_size)
+      end
+      
+      ##
+      # Produces $name-$semver-$hashplus
+      #
+      # - name is the name field from a build.zig.zon manifest. It is expected
+      # to be at most 32 bytes long and a valid Zig identifier.
+      # - semver is the version field from a build.zig.zon manifest. It is expected
+      # to be at most 32 bytes long.
+      # - hashplus is a base64 (urlsafe and nopad) encoded, 33-byte string:
+      #     - Pacakge ID (4) || Decompressed Size (4) || Digest0, Digest1, ..., Digest24
+      def self.make_hash(digest, name, semver, id, size)
+        raise ArgumentError, "name '#{name}' is expected to be at most 32 bytes long but it is #{name.bytesize} bytes" if name.bytesize > 32
+        raise ArgumentError, "semver '#{semver}' is expected to be at most 32 bytes long but it is #{semver.bytesize} bytes" if semver.bytesize > 32
+
+        hash_plus = [id].pack("V")
+        hash_plus += [size].pack("V")
+        hash_plus += [digest].pack('H*')[0..24]
+
+        "#{name}-#{semver}-#{Base64.urlsafe_encode64(hash_plus, padding: false)}"
+      end
+
+      def self.hash_file(package_path, path)
+        sha2 = Digest::SHA2.new    
+        sha2.update path
+
+        full_path = File.join(package_path, path)
+
+        if File.file? full_path
+          f = File.open full_path
+          data = f.read
+          file_size = data.bytesize
+          
+          # Hard-coded false executable bit: https://github.com/ziglang/zig/issues/17463
+          sha2.update "\x00\x00"
+          sha2.update data
+        elsif File.symlink? full_path
+          link_name = File.readlink full_path
+          sha2.update link_name
+        end
+
+        # TODO: symlink
+
+        {
+          digest: sha2.hexdigest,
+          size: file_size,
+        }
+      end
+    end
+  end
+end

data/lib/zon/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Zon
-  VERSION = "0.2.0"
+  VERSION = "0.3.0"
 end

data/lib/zon/zig.rb

@@ -16,6 +16,7 @@ module Zon
         raise "Missing '.name'" if not zon[:name]
         raise "Missing '.version'" if not zon[:version]
         raise "Missing '.fingerprint'" if not zon[:fingerprint]
+        raise "Missing '.paths'" if not zon[:paths]
 
         if zon[:dependencies]
           zon[:dependencies].each do |key, value|

data/lib/zon.rb

@@ -5,6 +5,7 @@ require_relative "zon/lexer"
 require_relative "zon/parser"
 require_relative "zon/serializer"
 require_relative "zon/zig"
+require_relative "zon/hasher"
 
 ##
 # Zig Object Notation (ZON) de-/serializer.

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: zon-rb
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - David P. Sugar
 bindir: exe
 cert_chain: []
-date: 2025-09-27 00:00:00.000000000 Z
+date: 2025-10-19 00:00:00.000000000 Z
 dependencies: []
 description: This gem allows you to translate Zig Object Notation (ZON) data into
   Ruby objects and vice versa.
@@ -24,6 +24,7 @@ files:
 - README.md
 - Rakefile
 - lib/zon.rb
+- lib/zon/hasher.rb
 - lib/zon/lexer.rb
 - lib/zon/parser.rb
 - lib/zon/serializer.rb