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 FileInfo
• 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 Manifest, err error)
• type ManifestMode
• 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 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 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() io.ReadSeeker

	// 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"
	Files         []FileInfo  `json:"files,omitempty"`        // present only in deployed manifests
}

Manifest defines structure of manifest.json file.

func ReadManifest

func ReadManifest(r io.Reader) (manifest Manifest, err 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 Source

type Source interface {
	io.ReadSeeker

	// 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.
	Close(ctx context.Context, corrupt bool) error
}

Source is an underlying data source with CIPD package data.

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.