versionsapi

Documentation

Overview

Versions API

The Versions API is a provides information about versions of Constellation components.

This package defines API types that represents objects of the versions API. The types provide helper methods for validation and commonly used operations on the information contained in the objects. Especially the paths used for the API are defined in these helper methods.

The package also provides helper functions that can be used in context of the versions API, e.g. to validate versions.

Index

• Constants
• func CanonicalizeRef(ref string) string
• func ValidateRef(ref string) error
• func ValidateStream(ref, stream string) error
• type Granularity
  • func GranularityFromString(s string) Granularity
  • func (g Granularity) MarshalJSON() ([]byte, error)
  • func (g Granularity) String() string
  • func (g *Granularity) UnmarshalJSON(data []byte) error
• type ImageInfo
  • func (i ImageInfo) JSONPath() string
  • func (i ImageInfo) URL() (string, error)
  • func (i ImageInfo) Validate() error
  • func (i ImageInfo) ValidateRequest() error
• type Latest
  • func (l Latest) JSONPath() string
  • func (l Latest) ShortPath() string
  • func (l Latest) URL() (string, error)
  • func (l Latest) Validate() error
  • func (l Latest) ValidateRequest() error
• type List
  • func (l List) Contains(version string) bool
  • func (l List) JSONPath() string
  • func (l List) StructuredVersions() []Version
  • func (l List) URL() (string, error)
  • func (l List) Validate() error
  • func (l List) ValidateRequest() error
• type Version
  • func NewVersionFromShortPath(shortPath string, kind VersionKind) (Version, error)
  • func (v Version) ArtifactPath() string
  • func (v Version) ArtifactURL() string
  • func (v Version) ListPath(gran Granularity) string
  • func (v Version) ListURL(gran Granularity) string
  • func (v Version) Major() string
  • func (v Version) MajorMinor() string
  • func (v Version) ShortPath() string
  • func (v Version) Validate() error
  • func (v Version) WithGranularity(gran Granularity) string
• type VersionKind
  • func VersionKindFromString(s string) VersionKind
  • func (k VersionKind) MarshalJSON() ([]byte, error)
  • func (k VersionKind) String() string
  • func (k *VersionKind) UnmarshalJSON(data []byte) error

Constants

const ReleaseRef = "-"

ReleaseRef is the ref used for release versions.

Functions

func CanonicalizeRef

func CanonicalizeRef(ref string) string

CanonicalizeRef returns the canonicalized ref for the given ref.

func ValidateRef

func ValidateRef(ref string) error

ValidateRef checks if the given ref is a valid ref. Canonicalize the ref before checking if it is valid.

func ValidateStream

func ValidateStream(ref, stream string) error

ValidateStream checks if the given stream is a valid stream for the given ref.

Types

type Granularity

type Granularity int

Granularity represents the granularity of a semantic version.

const (
	// GranularityUnknown is the default granularity.
	GranularityUnknown Granularity = iota
	// GranularityMajor is the granularity of a major version, e.g. "v1".
	// Lists with granularity "major" map from a major version to a list of minor versions.
	GranularityMajor
	// GranularityMinor is the granularity of a minor version, e.g. "v1.0".
	// Lists with granularity "minor" map from a minor version to a list of patch versions.
	GranularityMinor
	// GranularityPatch is the granularity of a patch version, e.g. "v1.0.0".
	// There are no lists with granularity "patch".
	GranularityPatch
)

func GranularityFromString

func GranularityFromString(s string) Granularity

GranularityFromString returns the granularity for the given string.

func (Granularity) MarshalJSON

func (g Granularity) MarshalJSON() ([]byte, error)

MarshalJSON marshals the granularity to JSON.

func (Granularity) String

func (g Granularity) String() string

String returns the string representation of the granularity.

func (*Granularity) UnmarshalJSON

func (g *Granularity) UnmarshalJSON(data []byte) error

UnmarshalJSON unmarshals the granularity from JSON.

type ImageInfo

type ImageInfo struct {
	// Ref is the reference name of the image.
	Ref string `json:"ref,omitempty"`
	// Stream is the stream name of the image.
	Stream string `json:"stream,omitempty"`
	// Version is the version of the image.
	Version string `json:"version,omitempty"`
	// AWS is a map of AWS regions to AMI IDs.
	AWS map[string]string `json:"aws,omitempty"`
	// Azure is a map of image types to Azure image IDs.
	Azure map[string]string `json:"azure,omitempty"`
	// GCP is a map of image types to GCP image IDs.
	GCP map[string]string `json:"gcp,omitempty"`
	// QEMU is a map of image types to QEMU image URLs.
	QEMU map[string]string `json:"qemu,omitempty"`
}

ImageInfo contains information about the OS images for a specific version.

func (ImageInfo) JSONPath

func (i ImageInfo) JSONPath() string

JSONPath returns the S3 JSON path for this object.

func (ImageInfo) URL

func (i ImageInfo) URL() (string, error)

URL returns the URL to the JSON file for this object.

func (ImageInfo) Validate

func (i ImageInfo) Validate() error

Validate checks if the image info is valid.

func (ImageInfo) ValidateRequest

func (i ImageInfo) ValidateRequest() error

ValidateRequest validates the request parameters of the list. The provider specific maps must be empty.

type Latest

type Latest struct {
	// Ref is the branch name this latest version belongs to.
	Ref string `json:"ref,omitempty"`
	// Stream is stream name this latest version belongs to.
	Stream string `json:"stream,omitempty"`
	// Kind is the kind of resource this latest version is for.
	Kind VersionKind `json:"kind,omitempty"`
	// Version is the latest version for this ref, stream and kind.
	Version string `json:"version,omitempty"`
}

Latest is the latest version of a kind of resource.

func (Latest) JSONPath

func (l Latest) JSONPath() string

JSONPath returns the S3 JSON path for this object.

func (Latest) ShortPath

func (l Latest) ShortPath() string

ShortPath returns the short path of the latest version.

func (Latest) URL

func (l Latest) URL() (string, error)

URL returns the URL for this object.

func (Latest) Validate

func (l Latest) Validate() error

Validate checks if this latest version is valid.

func (Latest) ValidateRequest

func (l Latest) ValidateRequest() error

ValidateRequest checks if this latest version beside values that are fetched.

type List

type List struct {
	// Ref is the branch name the list belongs to.
	Ref string `json:"ref,omitempty"`
	// Stream is the update stream of the list.
	Stream string `json:"stream,omitempty"`
	// Granularity is the granularity of the base version of this list.
	// It can be either "major" or "minor".
	Granularity Granularity `json:"granularity,omitempty"`
	// Base is the base version of the list.
	// Every version in the list is a finer-grained version of this base version.
	Base string `json:"base,omitempty"`
	// Kind is the kind of resource this list is for.
	Kind VersionKind `json:"kind,omitempty"`
	// Versions is a list of all versions in this list.
	Versions []string `json:"versions,omitempty"`
}

List represents a list of versions for a kind of resource. It has a granularity of either "major" or "minor".

For example, a List with granularity "major" could contain the base version "v1" and a list of minor versions "v1.0", "v1.1", "v1.2" etc. A List with granularity "minor" could contain the base version "v1.0" and a list of patch versions "v1.0.0", "v1.0.1", "v1.0.2" etc.

func (List) Contains

func (l List) Contains(version string) bool

Contains returns true if the list contains the given version.

func (List) JSONPath

func (l List) JSONPath() string

JSONPath returns the S3 JSON path for this object.

func (List) StructuredVersions

func (l List) StructuredVersions() []Version

StructuredVersions returns the versions of the list as slice of Version structs.

func (List) URL

func (l List) URL() (string, error)

URL returns the URL for this object.

func (List) Validate

func (l List) Validate() error

Validate checks if the list is valid. This performs the following checks: - The ref is set. - The stream is supported. - The granularity is "major" or "minor". - The kind is supported. - The base version is a valid semantic version that matches the granularity. - All versions in the list are valid semantic versions that are finer-grained than the base version.

func (List) ValidateRequest

func (l List) ValidateRequest() error

ValidateRequest validates the request parameters of the list. The versions field must be empty.

type Version

type Version struct {
	Ref     string
	Stream  string
	Version string
	Kind    VersionKind
}

Version represents a version. A version has a ref, stream, version string and kind.

Notice that version is a meta object to the versions API and there isn't an actual corresponding object in the S3 bucket. Therefore, the version object doesn't have a URL or JSON path.

func NewVersionFromShortPath

func NewVersionFromShortPath(shortPath string, kind VersionKind) (Version, error)

NewVersionFromShortPath creates a new Version from a version short path.

func (Version) ArtifactPath

func (v Version) ArtifactPath() string

ArtifactPath returns the path to the artifacts stored for this version. The path points to a directory.

func (Version) ArtifactURL

func (v Version) ArtifactURL() string

ArtifactURL returns the URL to the artifacts stored for this version. The URL points to a directory.

func (Version) ListPath

func (v Version) ListPath(gran Granularity) string

ListPath returns the path of the list with the given granularity, this version is listed in. For example, assing GranularityMajor returns the path of the versions list that maps the major version of this version to its minor version. In case of an unknown granularity, an empty string is returned.

func (Version) ListURL

func (v Version) ListURL(gran Granularity) string

ListURL returns the URL of the list with the given granularity, this version is listed in. For example, assing GranularityMajor returns the URL of the versions list that maps the major version of this version to its minor version. In case of an unknown granularity, an empty string is returned.

func (Version) Major

func (v Version) Major() string

Major returns the major version corresponding to the version. For example, if the version is "v1.2.3", the major version is "v1".

func (Version) MajorMinor

func (v Version) MajorMinor() string

MajorMinor returns the major and minor version corresponding to the version. For example, if the version is "v1.2.3", the major and minor version is "v1.2".

func (Version) ShortPath

func (v Version) ShortPath() string

ShortPath returns the short path of the version.

func (Version) Validate

func (v Version) Validate() error

Validate validates the version.

func (Version) WithGranularity

func (v Version) WithGranularity(gran Granularity) string

WithGranularity returns the version with the given granularity.

For example, if the version is "v1.2.3" and the granularity is GranularityMajor, the returned version is "v1". This is a helper function for Major() and MajorMinor() and v.Version. In case of an unknown granularity, an empty string is returned.

type VersionKind

type VersionKind int

VersionKind represents the kind of resource the version versions.

const (
	// VersionKindUnknown is the default value for VersionKind.
	VersionKindUnknown VersionKind = iota
	// VersionKindImage is the kind for image versions.
	VersionKindImage
)

func VersionKindFromString

func VersionKindFromString(s string) VersionKind

VersionKindFromString returns the VersionKind for the given string.

func (VersionKind) MarshalJSON

func (k VersionKind) MarshalJSON() ([]byte, error)

MarshalJSON marshals the VersionKind to JSON.

func (VersionKind) String

func (k VersionKind) String() string

String returns the string representation of the VersionKind.

func (*VersionKind) UnmarshalJSON

func (k *VersionKind) UnmarshalJSON(data []byte) error

UnmarshalJSON unmarshals the VersionKind from JSON.