Documentation

Overview

The tools package supports locating, parsing, and filtering Ubuntu tools metadata in simplestreams format. See http://launchpad.net/simplestreams and in particular the doc/README file in that project for more information about the file formats.

The tools package supports locating, parsing, and filtering Ubuntu tools metadata in simplestreams format. See http://launchpad.net/simplestreams and in particular the doc/README file in that project for more information about the file formats.

Index

Constants

View Source
const (
	// ImageIds is the simplestreams tools content type.
	ContentDownload = "content-download"

	// StreamsVersionV1 is used to construct the path for accessing streams data.
	StreamsVersionV1 = "v1"

	// IndexFileVersion is used to construct the streams index file.
	IndexFileVersion = 2
)
View Source
const (
	// Legacy release directory for Juju < 1.21.
	LegacyReleaseDirectory = "releases"

	// Used to specify the released tools metadata.
	ReleasedStream = "released"

	// Used to specify metadata for testing tools.
	TestingStream = "testing"

	// Used to specify the proposed tools metadata.
	ProposedStream = "proposed"

	// Used to specify the devel tools metadata.
	DevelStream = "devel"
)
View Source
const (
	WriteMirrors      = ShouldWriteMirrors(true)
	DoNotWriteMirrors = ShouldWriteMirrors(false)
)
View Source
const DoNotAllowRetry = false

Define some boolean parameter values.

Variables

AllMetadataStreams is the set of streams for which there will be simplestreams tools metadata.

View Source
var DefaultBaseURL = "https://streams.canonical.com/juju/tools"

This needs to be a var so we can override it for testing.

View Source
var ErrNoTools = errors.New("no tools available")

Functions

func Archive

func Archive(w io.Writer, dir string) error

Archive writes the executable files found in the given directory in gzipped tar format to w.

func FindExactTools

func FindExactTools(env environs.Environ, vers version.Number, series string, arch string) (t *coretools.Tools, err error)

FindExactTools returns only the tools that match the supplied version.

func FindTools

func FindTools(env environs.Environ, majorVersion, minorVersion int, stream string,
	filter coretools.Filter) (list coretools.List, err error)

FindTools returns a List containing all tools in the given stream, with a given major.minor version number available in the cloud instance, filtered by filter. If minorVersion = -1, then only majorVersion is considered. If no *available* tools have the supplied major.minor version number, or match the supplied filter, the function returns a *NotFoundError.

func FindToolsForCloud

func FindToolsForCloud(sources []simplestreams.DataSource, cloudSpec simplestreams.CloudSpec, stream string,
	majorVersion, minorVersion int, filter coretools.Filter) (list coretools.List, err error)

FindToolsForCloud returns a List containing all tools in the given stream, with a given major.minor version number and cloudSpec, filtered by filter. If minorVersion = -1, then only majorVersion is considered. If no *available* tools have the supplied major.minor version number, or match the supplied filter, the function returns a *NotFoundError.

func GetMetadataSources

func GetMetadataSources(env environs.Environ) ([]simplestreams.DataSource, error)

GetMetadataSources returns the sources to use when looking for simplestreams tools metadata for the given stream.

func MarshalToolsMetadataJSON

func MarshalToolsMetadataJSON(metadata map[string][]*ToolsMetadata, updated time.Time) (index, legacyIndex []byte, products map[string][]byte, err error)

MarshalToolsMetadataJSON marshals tools metadata to index and products JSON. updated is the time at which the JSON file was updated.

func MarshalToolsMetadataProductsJSON

func MarshalToolsMetadataProductsJSON(
	streamMetadata map[string][]*ToolsMetadata, updated time.Time,
) (out map[string][]byte, err error)

MarshalToolsMetadataProductsJSON marshals tools metadata to products JSON. updated is the time at which the JSON file was updated.

func MergeAndWriteMetadata

func MergeAndWriteMetadata(stor storage.Storage, toolsDir, stream string, tools coretools.List, writeMirrors ShouldWriteMirrors) error

MergeAndWriteMetadata reads the existing metadata from storage (if any), and merges it with metadata generated from the given tools list. The resulting metadata is written to storage.

func PreferredStream

func PreferredStream(vers *version.Number, forceDevel bool, stream string) string

PreferredStream returns the tools stream used to search for tools, based on the required version, whether devel mode is required, and any user specified stream.

func ProductMetadataPath

func ProductMetadataPath(stream string) string

ProductMetadataPath returns the tools product metadata path for the given stream.

func ReadAllMetadata

func ReadAllMetadata(store storage.StorageReader) (map[string][]*ToolsMetadata, error)

ReadAllMetadata returns the tools metadata from the given storage for all streams. The result is a map of metadata slices, keyed on stream.

func ReadList

func ReadList(stor storage.StorageReader, toolsDir string, majorVersion, minorVersion int) (coretools.List, error)

ReadList returns a List of the tools in store with the given major.minor version. If minorVersion = -1, then only majorVersion is considered. If store contains no such tools, it returns ErrNoMatches.

func RegisterToolsDataSourceFunc

func RegisterToolsDataSourceFunc(id string, f ToolsDataSourceFunc)

RegisterToolsDataSourceFunc registers an ToolsDataSourceFunc with the specified id, overwriting any function previously registered with the same id.

func ResolveMetadata

func ResolveMetadata(stor storage.StorageReader, toolsDir string, metadata []*ToolsMetadata) error

ResolveMetadata resolves incomplete metadata by fetching the tools from storage and computing the size and hash locally.

func Sort

func Sort(metadata []*ToolsMetadata)

Sort sorts a slice of ToolsMetadata in ascending order of their version in order to ensure the results of Fetch are ordered deterministically.

func StorageName

func StorageName(vers version.Binary, stream string) string

StorageName returns the name that is used to store and retrieve the given version of the juju tools.

func ToolsContentId

func ToolsContentId(stream string) string

ToolsContentId returns the tools content id for the given stream.

func ToolsURL

func ToolsURL(source string) (string, error)

ToolsURL returns a valid tools URL constructed from source. source may be a directory, or a URL like file://foo or http://foo.

func UnregisterToolsDataSourceFunc

func UnregisterToolsDataSourceFunc(id string)

UnregisterToolsDataSourceFunc unregisters an ToolsDataSourceFunc with the specified id.

func ValidateToolsMetadata

func ValidateToolsMetadata(params *ToolsMetadataLookupParams) ([]string, *simplestreams.ResolveInfo, error)

ValidateToolsMetadata attempts to load tools metadata for the specified cloud attributes and returns any tools versions found, or an error if the metadata could not be loaded.

func WriteMetadata

func WriteMetadata(stor storage.Storage, streamMetadata map[string][]*ToolsMetadata, streams []string, writeMirrors ShouldWriteMirrors) error

WriteMetadata writes the given tools metadata for the specified streams to the given storage. streamMetadata contains all known metadata so that the correct index files can be written. Only product files for the specified streams are written.

Types

type BundleToolsFunc

type BundleToolsFunc func(w io.Writer, forceVersion *version.Number) (version.Binary, string, error)

BundleToolsFunc is a function which can bundle all the current juju tools in gzipped tar format to the given writer.

var BundleTools BundleToolsFunc = bundleTools

Override for testing.

type MetadataFile

type MetadataFile struct {
	Path string
	Data []byte
}

type ShouldWriteMirrors

type ShouldWriteMirrors bool

type ToolsConstraint

type ToolsConstraint struct {
	simplestreams.LookupParams
	Version      version.Number
	MajorVersion int
	MinorVersion int
}

ToolsConstraint defines criteria used to find a tools metadata record.

func NewGeneralToolsConstraint

func NewGeneralToolsConstraint(majorVersion, minorVersion int, params simplestreams.LookupParams) *ToolsConstraint

NewGeneralToolsConstraint returns a ToolsConstraint for tools with matching major/minor version numbers.

func NewVersionedToolsConstraint

func NewVersionedToolsConstraint(vers version.Number, params simplestreams.LookupParams) *ToolsConstraint

NewVersionedToolsConstraint returns a ToolsConstraint for a tools with a specific version.

func (*ToolsConstraint) IndexIds

func (tc *ToolsConstraint) IndexIds() []string

IndexIds generates a string array representing product ids formed similarly to an ISCSI qualified name (IQN).

func (*ToolsConstraint) ProductIds

func (tc *ToolsConstraint) ProductIds() ([]string, error)

ProductIds generates a string array representing product ids formed similarly to an ISCSI qualified name (IQN).

type ToolsDataSourceFunc

type ToolsDataSourceFunc func(environs.Environ) (simplestreams.DataSource, error)

ToolsDataSourceFunc is a function type that takes an environment and returns a simplestreams datasource.

ToolsDataSourceFunc will be used in GetMetadataSources. Any error satisfying errors.IsNotSupported will be ignored; any other error will be cause GetMetadataSources to fail.

type ToolsMetadata

type ToolsMetadata struct {
	Release  string `json:"release"`
	Version  string `json:"version"`
	Arch     string `json:"arch"`
	Size     int64  `json:"size"`
	Path     string `json:"path"`
	FullPath string `json:"-"`
	FileType string `json:"ftype"`
	SHA256   string `json:"sha256"`
}

ToolsMetadata holds information about a particular tools tarball.

func Fetch

func Fetch(
	sources []simplestreams.DataSource, cons *ToolsConstraint,
	onlySigned bool) ([]*ToolsMetadata, *simplestreams.ResolveInfo, error)

Fetch returns a list of tools for the specified cloud matching the constraint. The base URL locations are as specified - the first location which has a file is the one used. Signed data is preferred, but if there is no signed data available and onlySigned is false, then unsigned data is used.

func MergeMetadata

func MergeMetadata(tmlist1, tmlist2 []*ToolsMetadata) ([]*ToolsMetadata, error)

MergeMetadata merges the given tools metadata. If metadata for the same tools version exists in both lists, an entry with non-empty size/SHA256 takes precedence; if the two entries have different sizes/hashes, then an error is returned.

func MetadataFromTools

func MetadataFromTools(toolsList coretools.List, toolsDir string) []*ToolsMetadata

MetadataFromTools returns a tools metadata list derived from the given tools list. The size and sha256 will not be computed if missing.

func ReadMetadata

func ReadMetadata(store storage.StorageReader, stream string) ([]*ToolsMetadata, error)

ReadMetadata returns the tools metadata from the given storage for the specified stream.

func (*ToolsMetadata) String

func (t *ToolsMetadata) String() string

type ToolsMetadataLookupParams

type ToolsMetadataLookupParams struct {
	simplestreams.MetadataLookupParams
	Version string
	Major   int
	Minor   int
}

ToolsMetadataLookupParams is used to query metadata for matching tools.

Directories

Path Synopsis