gemvault 0.1.4 → 0.2.0

data/lib/gemvault/gem_extraction.rb

@@ -0,0 +1,41 @@
+require "rubygems/package"
+require "tempfile"
+require "stringio"
+require_relative "vault"
+
+module Gemvault
+  # Shared vault behavior: turn a gem entry (stored or on disk) into gemspecs
+  # and temporary files. Host classes must implement #gem_data(entry) and
+  # #gem_entries.
+  module GemExtraction
+    def with_gem_file(entry)
+      data = gem_data(entry)
+      Tempfile.create(["vault_gem", ".gem"]) do |tmpfile|
+        tmpfile.binmode
+        tmpfile.write(data)
+        tmpfile.flush
+        yield tmpfile.path
+      end
+    end
+
+    def spec_from_blob(entry)
+      bytes = gem_data(entry)
+      io = StringIO.new(bytes)
+      Gem::Package.new(io).spec
+    end
+
+    def specs
+      gem_entries.map { |entry| spec_from_blob(entry) }
+    end
+
+    private
+
+    def spec_from_gem_file(gem_path)
+      begin
+        Gem::Package.new(gem_path.to_s).spec
+      rescue StandardError => e
+        raise Vault::InvalidGemError, "Invalid gem file #{gem_path}: #{e.message}"
+      end
+    end
+  end
+end

data/lib/gemvault/gem_reference/any_version.rb

@@ -1,7 +1,11 @@
 module Gemvault
-  class GemReference
+  module GemReference
+    ##
     # Matches every version of a named gem stored in the vault.
-    class AnyVersion < GemReference
+    class AnyVersion < Data.define(:name)
+      include GemReference
+
+      def matches?(gem) = gem.name == name
     end
   end
 end

data/lib/gemvault/gem_reference/parser.rb

@@ -0,0 +1,44 @@
+require "rubygems/version"
+
+module Gemvault
+  module GemReference
+    ##
+    # Turns raw CLI input into the GemReference that selects it. Input is either
+    # a bare name ("foo") or a combined NAME-VERSION ("foo-1.2.3"); an explicit
+    # +version+ overrides any version embedded in the input. A name and version
+    # yield a SpecificVersion, a lone name an AnyVersion, and a non-exact version
+    # a NonExactVersionError.
+    class Parser < Data.define(:input, :version)
+      def initialize(input:, version: nil) = super
+
+      def call
+        boundary = version_boundary
+        name = boundary ? input[0...boundary] : input
+        embedded_version = boundary && input[(boundary + 1)..]
+        build(name:, version_string: version || embedded_version)
+      end
+
+      private
+
+      def build(name:, version_string:)
+        return AnyVersion.new(name:) if version_string.nil?
+
+        raise_non_exact(version_string) unless Gem::Version.correct?(version_string)
+
+        SpecificVersion.new(name:, version: Gem::Version.new(version_string))
+      end
+
+      def version_boundary
+        hyphen = input.rindex("-")
+        return nil unless hyphen
+
+        trailing = input[(hyphen + 1)..]
+        hyphen if Gem::Version.correct?(trailing)
+      end
+
+      def raise_non_exact(version_string)
+        raise NonExactVersionError, "Version must be an exact version (got: #{version_string.inspect})"
+      end
+    end
+  end
+end

data/lib/gemvault/gem_reference/specific_version.rb

@@ -1,29 +1,13 @@
 module Gemvault
-  class GemReference
-    # Matches one exact version of a named gem. `version:` is always a
-    # Gem::Version (never nil, never a String) `.parse` validates and
-    # constructs it before calling `.new`.
-    class SpecificVersion < GemReference
-      attr_reader :version
-
-      def initialize(name:, version:)
-        super(name: name)
-        @version = version
-      end
-
-      def ==(other)
-        super && version == other.version
-      end
-      alias eql? ==
-
-      def hash
-        [self.class, name, version].hash
-      end
-
-      def deconstruct_keys(keys)
-        data = { name: name, version: version }
-        keys.nil? ? data : data.slice(*keys)
-      end
+  module GemReference
+    ##
+    # Matches one exact version of a named gem. +version+ is always a
+    # Gem::Version (never nil, never a String); GemReference.parse validates and
+    # constructs it before calling .new.
+    class SpecificVersion < Data.define(:name, :version)
+      include GemReference
+
+      def matches?(gem) = gem.name == name && gem.version == version.to_s
     end
   end
 end

data/lib/gemvault/gem_reference.rb

@@ -1,54 +1,22 @@
 require "rubygems/version"
-require_relative "gem_reference/any_version"
-require_relative "gem_reference/specific_version"
 
 module Gemvault
-  # A reference to a gem in a vault. Abstract base class for two concrete
-  # kinds: AnyVersion (no version constraint) and SpecificVersion (an exact
-  # Gem::Version). Not instantiable directly. `.parse` is the factory that
-  # turns raw CLI input into one of the two subclasses.
-  class GemReference
+  ##
+  # The role shared by every reference to a gem in a vault: it decides whether
+  # it +matches?+ a given GemEntry. Two value objects play the role --
+  # AnyVersion (no version constraint) and SpecificVersion (an exact
+  # Gem::Version). Players +include GemReference+ to declare the role; the
+  # +matches?+ contract is enforced by the "a gem reference" shared examples.
+  # +parse+ is the factory that turns raw CLI input into a player.
+  module GemReference
     class NonExactVersionError < StandardError; end
 
     def self.parse(input, version: nil)
-      base_name, embedded = split_name_version(input)
-      version_string = version || embedded
-      return AnyVersion.new(name: base_name) if version_string.nil?
-      unless Gem::Version.correct?(version_string)
-        raise NonExactVersionError, "Version must be an exact version (got: #{version_string.inspect})"
-      end
-
-      SpecificVersion.new(name: base_name, version: Gem::Version.new(version_string))
-    end
-
-    def self.split_name_version(input)
-      idx = input.rindex("-")
-      return [input, nil] unless idx && Gem::Version.correct?(input[(idx + 1)..])
-
-      [input[0...idx], input[(idx + 1)..]]
-    end
-    private_class_method :split_name_version
-
-    attr_reader :name
-
-    def initialize(name:)
-      raise NotImplementedError, "abstract base use AnyVersion or SpecificVersion" if instance_of?(GemReference)
-
-      @name = name
-    end
-
-    def ==(other)
-      self.class == other.class && name == other.name
-    end
-    alias eql? ==
-
-    def hash
-      [self.class, name].hash
-    end
-
-    def deconstruct_keys(keys)
-      data = { name: name }
-      keys.nil? ? data : data.slice(*keys)
+      Parser.new(input:, version:).call
     end
   end
 end
+
+require_relative "gem_reference/parser"
+require_relative "gem_reference/any_version"
+require_relative "gem_reference/specific_version"

data/lib/gemvault/manifest.rb

@@ -0,0 +1,78 @@
+require "json"
+require "digest"
+require_relative "gem_entry"
+
+module Gemvault
+  # The manifest.json stored as the first entry of a Tarvault. Records each
+  # gem's identity, timestamp, and SHA256 digest so listing and integrity
+  # checks never require reading every gem blob.
+  class Manifest < Data.define(:created_at, :records, :format_version)
+    FILENAME = "manifest.json".freeze
+    FORMAT_VERSION = 2
+
+    # One stored gem: its identity (a GemEntry) plus the integrity digest and
+    # encryption flag the manifest keeps alongside it.
+    class StoredGem < Data.define(:gem, :sha256, :encrypted)
+      def self.from_h(hash)
+        hash => { name:, version:, platform:, created_at:, sha256:, encrypted: }
+        entry = GemEntry.new(name:, version:, platform:, created_at:)
+        new(gem: entry, sha256:, encrypted:)
+      end
+
+      def filename = gem.filename
+
+      def matches?(bytes) = Manifest.digest(bytes) == sha256
+
+      def to_h
+        {
+          name: gem.name, version: gem.version, platform: gem.platform,
+          created_at: gem.created_at, sha256:, encrypted:
+        }
+      end
+    end
+
+    def self.digest(bytes) = Digest::SHA256.hexdigest(bytes)
+
+    def self.empty(created_at:) = new(created_at:, records: [])
+
+    def self.parse(json)
+      data = JSON.parse(json, symbolize_names: true)
+      records = data.fetch(:gems, []).map { |gem| StoredGem.from_h(gem) }
+      format_version = (data[:vault_version] || FORMAT_VERSION).to_i
+      new(created_at: data[:created_at], records:, format_version:)
+    end
+
+    def initialize(created_at:, records:, format_version: FORMAT_VERSION)
+      super
+    end
+
+    def with_record(record) = with(records: records + [record])
+
+    def without(dropped) = with(records: records - dropped)
+
+    def find(entry)
+      records.find { |record| record.gem.same_identity_as?(entry) }
+    end
+
+    def matching(reference)
+      records.select { |record| reference.matches?(record.gem) }
+    end
+
+    def size = records.size
+
+    def gem_entries
+      records.map(&:gem).sort_by { |gem| [gem.name, gem.version] }
+    end
+
+    def to_h
+      {
+        vault_version: FORMAT_VERSION,
+        format: "tarvault",
+        created_at:,
+        gems: records.map(&:to_h),
+      }
+    end
+
+    def to_json(*_args) = JSON.pretty_generate(to_h)
+  end
+end

data/lib/gemvault/tarball.rb

@@ -0,0 +1,53 @@
+require "rubygems/package"
+require "tempfile"
+require "pathname"
+require_relative "archive_entry"
+
+module Gemvault
+  # The tar file backing a Tarvault. Reads named members and rewrites the whole
+  # archive atomically: tar has no index and the leading manifest entry changes
+  # size on every mutation, so mutation means a full rewrite.
+  class Tarball
+    def initialize(path)
+      @path = Pathname(path)
+    end
+
+    def read(name)
+      entries.find { |entry| entry.name == name }&.bytes
+    end
+
+    def entries
+      each_entry.map { |member| ArchiveEntry.new(name: member.full_name, bytes: member.read) }
+    end
+
+    def write(entries)
+      Tempfile.create(["tarvault", ".tar"], @path.dirname) do |tmp|
+        write_entries(io: tmp, entries:)
+        tmp.flush
+        tmp.fsync
+        tmp.close
+        Pathname(tmp.path).rename(@path)
+      end
+    end
+
+    private
+
+    def each_entry(&block)
+      return enum_for(:each_entry) unless block
+
+      @path.open("rb") do |io|
+        Gem::Package::TarReader.new(io) { |reader| reader.each_entry(&block) }
+      end
+    end
+
+    def write_entries(io:, entries:)
+      Gem::Package::TarWriter.new(io) do |writer|
+        entries.each { |entry| add_entry(writer:, entry:) }
+      end
+    end
+
+    def add_entry(writer:, entry:)
+      writer.add_file_simple(entry.name, 0o644, entry.bytes.bytesize) { |dest| dest.write(entry.bytes) }
+    end
+  end
+end

data/lib/gemvault/tarvault.rb

@@ -0,0 +1,139 @@
+require "time"
+require "pathname"
+require_relative "vault"
+require_relative "vault_session"
+require_relative "gem_extraction"
+require_relative "manifest"
+require_relative "tarball"
+require_relative "archive_entry"
+require_relative "gem_entry"
+require_relative "gem_reference"
+
+module Gemvault
+  # A Tarvault: a tarball whose first entry is manifest.json and whose
+  # remaining entries are .gem files. Portable, dependency-free storage.
+  class Tarvault
+    extend VaultSession
+    include GemExtraction
+
+    attr_reader :path
+
+    def initialize(path, create: false)
+      @path = Pathname(path).expand_path
+      @archive = Tarball.new(@path)
+      @closed = false
+      create ? create_vault! : load_manifest!
+    end
+
+    def add(gem_path, created_at: nil)
+      gem_path = Pathname(gem_path).expand_path
+      raise Vault::NotFoundError, "Gem file not found: #{gem_path}" unless gem_path.file?
+
+      spec = spec_from_gem_file(gem_path)
+      entry = GemEntry.from_spec(spec, created_at: created_at || timestamp)
+      raise_if_duplicate(entry)
+      store(entry:, bytes: gem_path.binread)
+    end
+
+    def remove(reference)
+      dropped = @manifest.matching(reference)
+      return 0 if dropped.empty?
+
+      @manifest = @manifest.without(dropped)
+      remaining = survivors_excluding(dropped)
+      rewrite(remaining)
+      dropped.size
+    end
+
+    def gem_data(entry)
+      record = @manifest.find(entry)
+      raise Vault::NotFoundError, "Gem not found: #{entry}" unless record
+
+      bytes = @archive.read(record.filename)
+      raise Vault::Error, "Integrity check failed for #{record.filename}" unless record.matches?(bytes)
+
+      bytes
+    end
+
+    def gem_entries
+      @manifest.gem_entries
+    end
+
+    def format_version
+      @manifest.format_version
+    end
+
+    def size
+      @manifest.size
+    end
+
+    def close
+      @closed = true
+    end
+
+    def closed?
+      @closed
+    end
+
+    private
+
+    def create_vault!
+      raise Vault::Error, "Vault already exists: #{@path}" if @path.exist?
+
+      @manifest = Manifest.empty(created_at: timestamp)
+      rewrite([])
+    end
+
+    def load_manifest!
+      begin
+        raise Vault::NotFoundError, "Vault not found: #{@path}" unless @path.exist?
+
+        @manifest = Manifest.parse(read_manifest_json)
+        Vault.assert_readable!(version: @manifest.format_version, path: @path)
+      rescue JSON::ParserError, Gem::Package::TarInvalidError, ArgumentError, Errno::EINVAL
+        raise Vault::Error, "Not a valid Tarvault: #{@path}"
+      end
+    end
+
+    def read_manifest_json
+      json = @archive.read(Manifest::FILENAME)
+      raise Vault::Error, "Not a valid Tarvault (missing manifest): #{@path}" unless json
+
+      json
+    end
+
+    def store(entry:, bytes:)
+      record = build_record(entry:, bytes:)
+      @manifest = @manifest.with_record(record)
+      rewrite(survivors + [ArchiveEntry.new(name: record.filename, bytes:)])
+    end
+
+    def rewrite(gems)
+      manifest_entry = ArchiveEntry.new(name: Manifest::FILENAME, bytes: @manifest.to_json)
+      @archive.write([manifest_entry] + gems)
+    end
+
+    def survivors
+      @archive.entries.reject { |entry| entry.name == Manifest::FILENAME }
+    end
+
+    def survivors_excluding(dropped)
+      names = dropped.map(&:filename)
+      survivors.reject { |entry| names.include?(entry.name) }
+    end
+
+    def build_record(entry:, bytes:)
+      Manifest::StoredGem.new(gem: entry, sha256: Manifest.digest(bytes), encrypted: false)
+    end
+
+    def raise_if_duplicate(entry)
+      return unless @manifest.find(entry)
+
+      raise Vault::DuplicateGemError, "Gem already in vault: #{entry}"
+    end
+
+    def timestamp
+      Time.now.utc.strftime("%Y-%m-%d %H:%M:%S")
+    end
+  end
+end