pkg

Documentation

Overview

Package pkg contains interfaces and struct related to CIPD package files.

Index

• Constants
• func ValidateInstallMode(mode InstallMode) error
• func WriteManifest(m *Manifest, w io.Writer) error
• type BytesSource
  • func NewBytesSource(b []byte) *BytesSource
  • func (bs *BytesSource) Close(ctx context.Context, corrupt bool) error
  • func (bs *BytesSource) ReadAt(p []byte, off int64) (n int, err error)
  • func (bs *BytesSource) Size() int64
• type FileInfo
• type FileSource
  • func NewFileSource(path string) (*FileSource, error)
  • func (fs *FileSource) Close(ctx context.Context, corrupt bool) error
  • func (fs *FileSource) ReadAt(p []byte, off int64) (n int, err error)
  • func (fs *FileSource) Size() int64
• type InstallMode
  • func PickInstallMode(im InstallMode) (InstallMode, error)
  • func (m *InstallMode) Set(value string) error
  • func (m InstallMode) String() string
• type Instance
• type Manifest
  • func ReadManifest(r io.Reader) (Manifest, error)
• type ManifestMode
• type ReadSeekerSource
  • func NewReadSeekerSource(r io.ReadSeeker) (*ReadSeekerSource, error)
  • func (r *ReadSeekerSource) Close(ctx context.Context, corrupt bool) error
  • func (r *ReadSeekerSource) ReadAt(data []byte, off int64) (int, error)
  • func (r *ReadSeekerSource) Size() int64
• type Source
• type VersionFile

Constants

const (
	// ServiceDir is a name of the directory inside the package zip file reserved
	// for cipd stuff.
	ServiceDir = ".cipdpkg"

	// ManifestName is a full name of the manifest file inside the package.
	ManifestName = ServiceDir + "/manifest.json"

	// ManifestFormatVersion is a version to write to the manifest file.
	ManifestFormatVersion = "1.1"
)

Functions

func ValidateInstallMode

func ValidateInstallMode(mode InstallMode) error

ValidateInstallMode returns non nil if install mode is invalid.

Valid modes are: "" (client will pick platform default), "copy" (aka InstallModeCopy), "symlink" (aka InstallModeSymlink).

func WriteManifest

func WriteManifest(m *Manifest, w io.Writer) error

WriteManifest encodes and writes manifest JSON to io.Writer.

Types

type BytesSource

type BytesSource struct {
	// contains filtered or unexported fields
}

BytesSource implements Source on top of a byte buffer.

func NewBytesSource

func NewBytesSource(b []byte) *BytesSource

NewBytesSource returns a Source implemented on top of a byte buffer.

func (*BytesSource) Close

func (bs *BytesSource) Close(ctx context.Context, corrupt bool) error

func (*BytesSource) ReadAt

func (bs *BytesSource) ReadAt(p []byte, off int64) (n int, err error)

func (*BytesSource) Size

func (bs *BytesSource) Size() int64

type FileInfo

type FileInfo struct {
	// Name is slash separated file path relative to a package root.
	Name string `json:"name"`

	// Size is a size of the file. 0 for symlinks.
	Size uint64 `json:"size"`

	// Executable is true if the file is executable.
	//
	// Only used for Linux\Mac archives. False for symlinks.
	Executable bool `json:"executable,omitempty"`

	// Writable is true if the file is user-writable.
	Writable bool `json:"writable,omitempty"`

	// ModTime is Unix timestamp with modification time of the file as it is set
	// inside CIPD package.
	//
	// May be 0 if the package was built without preserving the modification
	// times.
	ModTime int64 `json:"modtime,omitempty"`

	// WinAttrs is a string representation of extra windows file attributes.
	//
	// Only used for Win archives.
	WinAttrs string `json:"win_attrs,omitempty"`

	// Symlink is a path the symlink points to or "" if the file is not a symlink.
	Symlink string `json:"symlink,omitempty"`

	// Hash of the file body in the same format as used for instance IDs (i.e. a
	// base64 string that encodes both the algorithm and the digest).
	//
	// See common.ObjectRefToInstanceID for more info. Uses the best algorithm
	// available at the time of the package unpacking.
	//
	// Empty for symlink files. May also be empty in older manifests.
	Hash string `json:"hash,omitempty"`
}

FileInfo describes a file that was extracted from a CIPD package.

It is derived (based on zip info headers and actual contents of the files) by ExtractFiles when it unpacks the CIPD package. FileInfo structs are *not* stored in an explicit form in manifest.json inside the package. They are present only in manifest.json files on disk, representing already unpacked packages.

type FileSource

type FileSource struct {
	// contains filtered or unexported fields
}

FileSource implements Source on top of a file system file.

func NewFileSource

func NewFileSource(path string) (*FileSource, error)

NewFileSource opens a file for reading and returns it as a *FileSource.

func (*FileSource) Close

func (fs *FileSource) Close(ctx context.Context, corrupt bool) error

func (*FileSource) ReadAt

func (fs *FileSource) ReadAt(p []byte, off int64) (n int, err error)

func (*FileSource) Size

func (fs *FileSource) Size() int64

type InstallMode

type InstallMode string

InstallMode defines how to install a package.

const (
	// InstallModeSymlink is default (for backward compatibility).
	//
	// In this mode all files are extracted to .cipd/*/... and then symlinked to
	// the site root directory. Version switch happens atomically.
	InstallModeSymlink InstallMode = "symlink"

	// InstallModeCopy is used when files should be directly copied.
	//
	// This mode is always used on Windows (and can be optionally) used on
	// other OSes. If installation is aborted midway, the package may end up
	// in inconsistent state.
	InstallModeCopy InstallMode = "copy"
)

func PickInstallMode

func PickInstallMode(im InstallMode) (InstallMode, error)

PickInstallMode validates the install mode and picks the correct default for the platform if no install mode is given.

func (*InstallMode) Set

func (m *InstallMode) Set(value string) error

Set is called by 'flag' package when parsing command line options.

func (InstallMode) String

func (m InstallMode) String() string

String is needed to conform to flag.Value interface.

type Instance

type Instance interface {
	// Pin identifies package name and concreted instance ID of this package file.
	Pin() common.Pin

	// Files returns a list of files to deploy with the package.
	//
	// One of them (named ManifestName) is the manifest file.
	Files() []fs.File

	// Source returns a reader that reads raw package data.
	Source() Source

	// Close can be used to indicate to the storage (filesystem and/or cache)
	// layer that this instance is actually bad. The storage layer can then
	// evict/revoke, etc. the bad file.
	Close(ctx context.Context, corrupt bool) error
}

Instance represents an open CIPD package file (with manifest inside).

It owns the underlying raw data source and closes it whenever it is closed itself.

type Manifest

type Manifest struct {
	FormatVersion string      `json:"format_version"`
	PackageName   string      `json:"package_name"`
	VersionFile   string      `json:"version_file,omitempty"` // where to put JSON with info about deployed package
	InstallMode   InstallMode `json:"install_mode,omitempty"` // how to install: "copy" or "symlink"

	ActualInstallMode InstallMode `json:"actual_install_mode,omitempty"` // how this specific package was actually installed
	Files             []FileInfo  `json:"files,omitempty"`
}

Manifest defines structure of manifest.json file.

func ReadManifest

func ReadManifest(r io.Reader) (Manifest, error)

ReadManifest reads and decodes manifest JSON from io.Reader.

type ManifestMode

type ManifestMode bool

ManifestMode is used to indicate presence of absence of manifest when calling various functions.

Just to improve code readability, since Func(..., WithManifest) is less cryptic than Func(..., true).

const (
	// WithoutManifest indicates the function should skip manifest.
	WithoutManifest ManifestMode = false
	// WithManifest indicates the function should handle manifest.
	WithManifest ManifestMode = true
)

type ReadSeekerSource

type ReadSeekerSource struct {
	// contains filtered or unexported fields
}

ReadSeekerSource implements Source on top of an io.ReadSeeker.

Useful for compatibility with the previous CIPD client API.

All reads will be serialized. To gain any benefits from parallelization, switch to using Source interface directly instead of using io.ReadSeeker.

func NewReadSeekerSource

func NewReadSeekerSource(r io.ReadSeeker) (*ReadSeekerSource, error)

NewReadSeekerSource returns a Source implemented on top of an io.ReadSeeker.

func (*ReadSeekerSource) Close

func (r *ReadSeekerSource) Close(ctx context.Context, corrupt bool) error

func (*ReadSeekerSource) ReadAt

func (r *ReadSeekerSource) ReadAt(data []byte, off int64) (int, error)

func (*ReadSeekerSource) Size

func (r *ReadSeekerSource) Size() int64

type Source

type Source interface {
	io.ReaderAt

	// Size returns the package file size.
	Size() int64

	// Close can be used to indicate to the storage (filesystem and/or cache)
	// layer that this source is actually bad. The storage layer can then evict
	// the bad file.
	//
	// The context is used for logging.
	Close(ctx context.Context, corrupt bool) error
}

Source is an underlying data source with CIPD package data.

All errors are assumed to be IO errors and may be returned unannotated. Higher layers of the CIPD client will annotated them.

type VersionFile

type VersionFile struct {
	PackageName string `json:"package_name"`
	InstanceID  string `json:"instance_id"`
}

VersionFile describes JSON file with package version information that's deployed to a path specified in 'version_file' attribute of the manifest.