Documentation

Overview

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

    Index

    Constants

    View Source
    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"
    )

    Variables

    This section is empty.

    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.