Documentation
¶
Overview ¶
Package ref provides functionality for interpreting and manipulating OCI references, including delineated data for scheme, registry, repository, name, tag, and digest that identifies an OCI object (or bottle). Additionally, facilities for indexing a repository to retrieve a list of tags is included.
Index ¶
- Constants
- Variables
- func ExtractScheme(procstr string) (string, string)
- func ResolveRegistry(inReg string) string
- type DeclRef
- type ListProvider
- type MatchType
- type Ref
- func (r Ref) API() string
- func (r Ref) APIString() string
- func (r Ref) AuthURL() string
- func (r Ref) CombineRepoName() string
- func (r Ref) IsEmpty() bool
- func (r Ref) IsInsecure() bool
- func (r Ref) Match(other Ref, matchType MatchType) bool
- func (r Ref) MountRef() string
- func (r Ref) RepoString() string
- func (r Ref) RepoStringWithScheme() string
- func (r Ref) String() string
- func (r Ref) StringWithScheme() string
- func (r Ref) TagOrDigest() string
- func (r Ref) URL() string
- type RepositoryListProvider
- type Set
- type SourceRef
- type Validator
Constants ¶
const ( // SchemeHTTP is the standard non-tls http url reference. SchemeHTTP = "http" // SchemeHTTPS is the standard tls http url reference. SchemeHTTPS = "https" // SchemeBottle defines a scheme for querying bottle location from a telemetry server. SchemeBottle = "bottle" // SchemeHash defines a scheme for querying bottle location from a telemetry server using hash uri format. SchemeHash = "hash" )
const ( // AnnotationSrcRef is an annotation key for a record containing the original source reference for a manifest. // This is what the user requested verbatim. AnnotationSrcRef = "vnd.act3-ace.manifest.source" // There is no OCI Spec annotation for this // AnnotationRefName is an annotation key for denoting the fully qualified name of an image. AnnotationRefName = ocispec.AnnotationRefName )
Variables ¶
var ErrRefListEmpty = errors.New("repository not found")
ErrRefListEmpty is an error returned when querying a list of registries, repositories, or refs that indicates that the resulting list was empty (Versus another kind of error).
Functions ¶
func ExtractScheme ¶
ExtractScheme looks for a transfer scheme prefix in the provided string, and returns the appropriate scheme string if found. Additionally, the portion of the string not including any scheme value is returned.
func ResolveRegistry ¶
ResolveRegistry resolves a registry hostname to a fully specified one, for instance docker.io to index.docker.io. this utilizes a configured map of registry hostnames accessed through ace-dt config. If no matching hostnames are discovered the input string is returned.
Types ¶
type DeclRef ¶
type DeclRef struct {
Ref
// contains filtered or unexported fields
}
DeclRef is an extension of Ref that adds tracking for a declaration string.
type ListProvider ¶
type ListProvider interface {
RepositoryListProvider
// RefList accepts a Ref defining a registry and a list of Repositories, and return a list of Ref that contains
// full references for all matching repositories on the registry, including all known tags. If repoList is empty
// a list of all known repositories is first obtained using the RepositoryListProvider.
RefList(ctx context.Context, registry Ref, repoList []string) ([]Ref, error)
}
ListProvider defines an interface for retrieving a full list of references based on a provided registry and list of repositories. An empty repository list should be interpreted as "all" repositories. The registry info is provided as a Ref in order to also include the communication scheme if necessary.
type MatchType ¶
type MatchType uint8
MatchType is a bitfield type that provides flags for what parts of a Ref object to match during a Match call.
const ( // RefMatchRepo indicates that a match should consider the repo portion of the reference. RefMatchRepo MatchType = 1 << iota // RefMatchReg indicates that a match should consider the registry portion of the reference. RefMatchReg // RefMatchTag Indicates that a match should consider the tag portion of the reference. RefMatchTag // RefMatchDigest indicates that a match should consider the digest portion of the reference. RefMatchDigest // RefMatchScheme indicates that a match should consider the scheme portion of the reference. RefMatchScheme // RefMatchRegRepo combines RefMatchRepo and RefMatchReg options. RefMatchRegRepo = RefMatchReg | RefMatchRepo // RefMatchAll combines RefMatchReg and RefMatchRepo and RefMatchTag options. RefMatchAll = RefMatchReg | RefMatchRepo | RefMatchTag )
type Ref ¶
type Ref struct {
Scheme string
Reg string
Repo string
Name string
Tag string
Digest string
Query string
Selectors []string
}
Ref is a bottle location reference, including scheme, registry, repository Name, and tag. The Query and Fragment members allows additional uri query terms to be parsed and stored.
func DefaultRefValidator ¶
DefaultRefValidator is the default validation function for parsed references, validating character sets appropriate for use with OCI spec references. Characters outside of the spec cause an error and empty Ref to be returned.
func FromString ¶
FromString parses a string representing a data bottle and returns a Ref object that identifies registry, repository, name, and tag. By default, each element is validated using a regular expression using DefaultRefValidator, but this behavior can be optionally overridden by supplying a RefValidator function. Note, the validator argument is specified as a variadic list to allow the default argument, only the first element of the list will be called.
func RepoFromString ¶
RepoFromString parses a string representing a data bottle and returns a Ref object that identifies registry and repository. This is similar to RefFromString, but is more tolerant of missing components, and doesn't treat name different from repository.
func SkipRefValidation ¶
SkipRefValidation is a helper validator that simply returns the provided ref, allowing validation to be skipped.
func (Ref) API ¶
API returns a ref formatted as an API appropriate URL (no tag info, but including api version `v2`).
func (Ref) APIString ¶
APIString for Ref returns an API string representation of a reference, including the 'v2' path element Note, this leaves off the scheme if defined.
func (Ref) AuthURL ¶
AuthURL returns a ref formatted as the base url used to authenticate a user with a registry. Example: https://us-central1-docker.pkg.dev
func (Ref) CombineRepoName ¶
CombineRepoName combines the repo and name values into one, unless repo and name are already the same.
func (Ref) IsEmpty ¶
IsEmpty will iterate over the fields in the given Ref struct r and return false if any field is a non-zero value.
func (Ref) IsInsecure ¶
IsInsecure returns true iff the reference scheme is set to "http".
func (Ref) Match ¶
Match compares the selector Ref to the provided other Ref and returns true if they match. matchType provides options that determine what portions of the Ref are considered.
func (Ref) MountRef ¶
MountRef returns a reference used by oras to discover cross-repo mount locations. https://github.com/opencontainers/distribution-spec/blob/main/spec.md#mounting-a-blob-from-another-repository.
func (Ref) RepoString ¶
RepoString returns the full repository value, including repo and name as appropriate.
func (Ref) RepoStringWithScheme ¶
RepoStringWithScheme returns the full repository value, including repo and name as appropriate, and including scheme for registry name.
func (Ref) String ¶
String for Ref returns a string representation of a reference Note, this leaves off the scheme if defined.
func (Ref) StringWithScheme ¶
StringWithScheme for Ref returns a string representation of a reference including the scheme if defined.
func (Ref) TagOrDigest ¶
TagOrDigest returns the tag or digest of a ref.
type RepositoryListProvider ¶
type RepositoryListProvider interface {
// RepositoryList retrieves a list of known repositories based on a ref containing a registry and transfer scheme
RepositoryList(registry Ref) ([]string, error)
}
RepositoryListProvider defines an interface for retrieving a string array list of repositories for a registry, as implemented by RegistryRepos. The registry info is provided as a Ref in order to also include the communication scheme if necessary.
type Set ¶
type Set interface {
Refs() []SourceRef
// RefByReg should return a map associating a list of SourceRef to a registry or other association
RefByReg() map[string][]SourceRef
}
Set defines an interface for retrieving a list of refs from a source provider. The Set is not a strict set, duplicates are possible and can be differentiated by retrieving the declaration matching the index of a given ref using the Decl function.
type SourceRef ¶
type SourceRef interface {
// GetRef returns the translated and parsed Ref structure for a SourceRef
GetRef() Ref
// GetDecl returns a string representing the original declaration of a reference (before translation to Ref)
GetDecl() string
}
SourceRef is an interface that provides a Ref object for a source, as well as a custom string that is intended to be an initial declaration. This enables a Ref to be resolved from a declaration, but have the original information preserved for additional purposes, such as maintaining a record of processed references.
func NewDeclaredRef ¶
NewDeclaredRef generates a SourceRef (internally, DeclRef) from a resolved bottle ref and an original declaration string.
func NewStringDeclaredRef ¶
NewStringDeclaredRef returns a SourceRef (internally, DeclRef) based on the string form declaration of a Ref. This function assumes that the declaration can be parsed to a Ref. If unsure, resolve the reference elsewhere and use NewDeclaredRef.
Source Files