Class: Gem::Package

Relationships & Source Files
Namespace Children
Classes: DigestIO, Old, TarHeader, TarReader, TarTestCase, TarWriter
Exceptions: Error, FormatError, NonSeekableIO, PathError, TarInvalidError, TooLongFileName
Extension / Inclusion / Inheritance Descendants
Subclasses: Old
Super Chains via Extension / Inclusion / Inheritance
Instance Chain: self, UserInteraction, DefaultUserInteraction
Inherits:	Object
Defined in:	lib/rubygems/package.rb

Class Method Summary

.build(spec, skip_validation = false)
.new(gem) ⇒ Package constructor

Creates a new Package for the file at gem.

Instance Attribute Summary

#security_policy rw

The security policy used for verifying the contents of this package.
#spec rw

The spec for this gem.
#spec=(value) rw

Sets the Specification to use to build this package.
#checksums readonly

Checksums for the contents of the package.
#files readonly

The files in this package.

DefaultUserInteraction - Included

#ui	See DefaultUserInteraction.ui
#ui=	See DefaultUserInteraction.ui=

Instance Method Summary

#add_checksums(tar)

Adds a checksum for each entry in the gem to checksums.yaml.gz.
#build(skip_validation = false)

Builds this package based on the specification set by #spec=
#contents

A list of file names contained in this gem.
#extract_files(destination_dir, pattern = "*")

Extracts the files in this package into destination_dir
#gzip_to(io)

Gzips content written to gz_io to io.
#initialize(gem) ⇒ Package constructor

Creates a new package that will read or write to the file gem.
#read_checksums(gem)

Reads and loads checksums.yaml.gz from the tar file gem
#setup_signer

Prepares the gem for signing and checksum generation.
#verify

Verifies that this gem:
#verify_entry(entry)

Verifies entry in a .gem file.
#verify_files(gem)

Verifies the files of the gem

UserInteraction - Included

#alert	Displays an alert `statement`.
#alert_error	Displays an error `statement` to the error output location.
#alert_warning	Displays a warning `statement` to the warning output location.
#ask	Asks a `question` and returns the answer.
#ask_for_password	Asks for a password with a `prompt`
#ask_yes_no	Asks a yes or no `question`.
#choose_from_list	Asks the user to answer `question` with an answer from the given `list`.
#say	Displays the given `statement` on the standard output (or equivalent).
#terminate_interaction	Terminates the RubyGems process with the given `exit_code`
#verbose	Calls `say` with `msg` or the results of the block if really_verbose is true.

DefaultUserInteraction - Included

#use_ui

See DefaultUserInteraction.use_ui

Constructor Details

.new(gem) ⇒ `Package`

Creates a new Package for the file at gem. gem can also be provided as an IO object.

If gem is an existing file in the old format a Package::Old will be returned.

[ GitHub ]

# File 'lib/rubygems/package.rb', line 126


def self.new gem
  gem = if gem.is_a?(Gem::Package::Source)
          gem
        elsif gem.respond_to? :read
          Gem::Package::IOSource.new gem
        else
          Gem::Package::FileSource.new gem
        end

  return super(gem) unless Gem::Package == self
  return super unless gem.present?

  return super unless gem.start
  return super unless gem.start.include? 'MD5SUM ='

  Gem::Package::Old.new gem
end

#initialize(gem) ⇒ `Package`

Creates a new package that will read or write to the file gem.

[ GitHub ]

# File 'lib/rubygems/package.rb', line 147


def initialize gem # :notnew:
  @gem = gem

  @build_time      = Time.now
  @checksums       = {}
  @contents        = nil
  @digests         = Hash.new { |h, algorithm| h[algorithm] = {} }
  @files           = nil
  @security_policy = nil
  @signatures      = {}
  @signer          = nil
  @spec            = nil
end

Class Method Details

.build(spec, skip_validation = false)

[ GitHub ]

# File 'lib/rubygems/package.rb', line 109


def self.build spec, skip_validation=false
  gem_file = spec.file_name

  package = new gem_file
  package.spec = spec
  package.build skip_validation

  gem_file
end

Instance Attribute Details

#checksums (readonly)

Checksums for the contents of the package

[ GitHub ]

# File 'lib/rubygems/package.rb', line 91


attr_reader :checksums

#files (readonly)

The files in this package. This is not the contents of the gem, just the files in the top-level container.

[ GitHub ]

# File 'lib/rubygems/package.rb', line 97


attr_reader :files

#security_policy (rw)

The security policy used for verifying the contents of this package.

[ GitHub ]

# File 'lib/rubygems/package.rb', line 102


attr_accessor :security_policy

#spec (rw)

The spec for this gem.

If this is a package for a built gem the spec is loaded from the gem and returned. If this is a package for a gem being built the provided spec is returned.

[ GitHub ]

# File 'lib/rubygems/package.rb', line 484


def spec
  verify unless @spec

  @spec
end

#spec=(value) (rw)

Sets the Specification to use to build this package.

[ GitHub ]

# File 'lib/rubygems/package.rb', line 107


attr_writer :spec

Instance Method Details

#add_checksums(tar)

Adds a checksum for each entry in the gem to checksums.yaml.gz.

[ GitHub ]

# File 'lib/rubygems/package.rb', line 164


def add_checksums tar
  Gem.load_yaml

  checksums_by_algorithm = Hash.new { |h, algorithm| h[algorithm] = {} }

  @checksums.each do |name, digests|
    digests.each do |algorithm, digest|
      checksums_by_algorithm[algorithm][name] = digest.hexdigest
    end
  end

  tar.add_file_signed 'checksums.yaml.gz', 0444, @signer do |io|
    gzip_to io do |gz_io|
      YAML.dump checksums_by_algorithm, gz_io
    end
  end
end

#build(skip_validation = false)

Builds this package based on the specification set by #spec=

[ GitHub ]

# File 'lib/rubygems/package.rb', line 231


def build skip_validation = false
  Gem.load_yaml
  require 'rubygems/security'

  @spec.mark_version
  @spec.validate unless skip_validation

  setup_signer

  @gem.with_write_io do |gem_io|
    Gem::Package::TarWriter.new gem_io do |gem|
      add_metadata gem
      add_contents gem
      add_checksums gem
    end
  end

  say <<-EOM
Successfully built RubyGem
Name: #{@spec.name}
Version: #{@spec.version}
File: #{File.basename @spec.cache_file}
EOM
ensure
  @signer = nil
end

#contents

A list of file names contained in this gem

[ GitHub ]

# File 'lib/rubygems/package.rb', line 261


def contents
  return @contents if @contents

  verify unless @spec

  @contents = []

  @gem.with_read_io do |io|
    gem_tar = Gem::Package::TarReader.new io

    gem_tar.each do |entry|
      next unless entry.full_name == 'data.tar.gz'

      open_tar_gz entry do |pkg_tar|
        pkg_tar.each do |contents_entry|
          @contents << contents_entry.full_name
        end
      end

      return @contents
    end
  end
end

#extract_files(destination_dir, pattern = "*")

Extracts the files in this package into destination_dir

If pattern is specified, only entries matching that glob will be extracted.

[ GitHub ]

# File 'lib/rubygems/package.rb', line 320


def extract_files destination_dir, pattern = "*"
  verify unless @spec

  FileUtils.mkdir_p destination_dir

  @gem.with_read_io do |io|
    reader = Gem::Package::TarReader.new io

    reader.each do |entry|
      next unless entry.full_name == 'data.tar.gz'

      extract_tar_gz entry, destination_dir, pattern

      return # ignore further entries
    end
  end
end

#gzip_to(io)

Gzips content written to gz_io to io.

[ GitHub ]

# File 'lib/rubygems/package.rb', line 385


def gzip_to io # :yields: gz_io
  gz_io = Zlib::GzipWriter.new io, Zlib::BEST_COMPRESSION
  gz_io.mtime = @build_time

  yield gz_io
ensure
  gz_io.close
end

#read_checksums(gem)

Reads and loads checksums.yaml.gz from the tar file gem

[ GitHub ]

# File 'lib/rubygems/package.rb', line 450


def read_checksums gem
  Gem.load_yaml

  @checksums = gem.seek 'checksums.yaml.gz' do |entry|
    Zlib::GzipReader.wrap entry do |gz_io|
      Gem::SafeYAML.safe_load gz_io.read
    end
  end
end

#setup_signer

Prepares the gem for signing and checksum generation. If a signing certificate and key are not present only checksum generation is set up.

[ GitHub ]

# File 'lib/rubygems/package.rb', line 464


def setup_signer
  passphrase = ENV['GEM_PRIVATE_KEY_PASSPHRASE']
  if @spec.signing_key then
    @signer = Gem::Security::Signer.new @spec.signing_key, @spec.cert_chain, passphrase
    @spec.signing_key = nil
    @spec.cert_chain = @signer.cert_chain.map { |cert| cert.to_s }
  else
    @signer = Gem::Security::Signer.new nil, nil, passphrase
    @spec.cert_chain = @signer.cert_chain.map { |cert| cert.to_pem } if
      @signer.cert_chain
  end
end

#verify

Verifies that this gem:

Contains a valid gem specification
Contains a contents archive
The contents archive is not corrupt

After verification the gem specification from the gem is available from #spec

[ GitHub ]

# File 'lib/rubygems/package.rb', line 500


def verify
  @files     = []
  @spec      = nil

  @gem.with_read_io do |io|
    Gem::Package::TarReader.new io do |reader|
      read_checksums reader

      verify_files reader
    end
  end

  verify_checksums @digests, @checksums

  @security_policy.verify_signatures @spec, @digests, @signatures if
    @security_policy

  true
rescue Gem::Security::Exception
  @spec = nil
  @files = []
  raise
rescue Errno::ENOENT => e
  raise Gem::Package::FormatError.new e.message
rescue Gem::Package::TarInvalidError => e
  raise Gem::Package::FormatError.new e.message, @gem
end

#verify_entry(entry)

Verifies entry in a .gem file.

[ GitHub ]

# File 'lib/rubygems/package.rb', line 550


def verify_entry entry
  file_name = entry.full_name
  @files << file_name

  case file_name
  when /\.sig$/ then
    @signatures[$`] = entry.read if @security_policy
    return
  else
    digest entry
  end

  case file_name
  when /^metadata(.gz)?$/ then
    load_spec entry
  when 'data.tar.gz' then
    verify_gz entry
  end
rescue => e
  message = "package is corrupt, exception while verifying: " +
            "#{e.message} (#{e.class})"
  raise Gem::Package::FormatError.new message, @gem
end

#verify_files(gem)

Verifies the files of the gem

[ GitHub ]

# File 'lib/rubygems/package.rb', line 577


def verify_files gem
  gem.each do |entry|
    verify_entry entry
  end

  unless @spec then
    raise Gem::Package::FormatError.new 'package metadata is missing', @gem
  end

  unless @files.include? 'data.tar.gz' then
    raise Gem::Package::FormatError.new \
            'package content (data.tar.gz) is missing', @gem
  end

  if duplicates = @files.group_by {|f| f }.select {|k,v| v.size > 1 }.map(&:first) and duplicates.any?
    raise Gem::Security::Exception, "duplicate files in the package: (#{duplicates.map(&:inspect).join(', ')})"
  end
end

Class: Gem::Package

Class Method Summary

Instance Attribute Summary

DefaultUserInteraction - Included

Instance Method Summary

UserInteraction - Included

DefaultUserInteraction - Included

Constructor Details

.new(gem) ⇒ Package

#initialize(gem) ⇒ Package

Class Method Details

.build(spec, skip_validation = false)

Instance Attribute Details

#checksums (readonly)

#files (readonly)

#security_policy (rw)

#spec (rw)

#spec=(value) (rw)

Instance Method Details

#add_checksums(tar)

#build(skip_validation = false)

#contents

#extract_files(destination_dir, pattern = "*")

#gzip_to(io)

#read_checksums(gem)

#setup_signer

#verify

#verify_entry(entry)

#verify_files(gem)

.new(gem) ⇒ `Package`

#initialize(gem) ⇒ `Package`