Documentation
¶
Overview ¶
Package layout implements Artifactory repository layouts: the path patterns that tell the server which part of an artifact path is the organisation, module, base revision, integration revision, classifier and extension. A layout drives version search, snapshot cleanup and cross-layout copy, so it has to parse and build paths exactly as Artifactory does. The pattern syntax is documented at https://docs.jfrog.com/artifactory/docs/repository-layouts.md and summarised in docs/research/03-repository-configuration-model.md.
Index ¶
- Constants
- Variables
- func Org(orgPath string) string
- func OrgPath(org string) string
- func Translate(from, to *Layout, path string) (string, error)
- type Coordinates
- type Definition
- type Layout
- func (l *Layout) Build(v Values) (string, error)
- func (l *Layout) BuildDescriptor(v Values) (string, error)
- func (l *Layout) Definition() Definition
- func (l *Layout) Has(token string) bool
- func (l *Layout) IsDescriptor(path string) bool
- func (l *Layout) Match(path string) (Values, error)
- func (l *Layout) Prefixes(v Values) []string
- func (l *Layout) Read(fullPath string) (Coordinates, bool)
- func (l *Layout) VersionTokens() (*Layout, error)
- type LossError
- type Values
Constants ¶
const ( TokenOrg = "org" TokenOrgPath = "orgPath" TokenModule = "module" TokenBaseRev = "baseRev" TokenFolderItegRev = "folderItegRev" TokenFileItegRev = "fileItegRev" TokenClassifier = "classifier" TokenExt = "ext" TokenType = "type" )
Token names with a built-in meaning.
Variables ¶
var ErrLossy = errors.New("layout translation loses part of the path")
ErrLossy reports a translation between layouts that would land two source paths on one target path.
var ErrMissingValue = errors.New("missing value for layout token")
ErrMissingValue reports a Build call without a mandatory token value.
var ErrNoMatch = errors.New("path does not match layout")
ErrNoMatch reports a path that does not fit the layout.
var ErrPattern = errors.New("invalid layout pattern")
ErrPattern reports a malformed pattern.
var ErrUnbuildable = errors.New("layout cannot build a path")
ErrUnbuildable reports a Build of a pattern with a token outside the documented set, which a bundled layout drops (Lookup). Such a pattern has no place for that token's value, so every path it built would be the same literal text whatever the values, such as ansible-default's collections////--.tar.gz.
Functions ¶
func OrgPath ¶
OrgPath converts a dotted organisation into the slash form used by [orgPath]; Artifactory derives one from the other the same way.
func Translate ¶
Translate converts path from layout from to layout to, as a copy or move between repositories of different layouts does (suppressLayouts=0): the values from reads build to's pattern, its descriptor pattern for a descriptor. It answers ErrNoMatch when from does not read the path, and ErrMissingValue, ErrPattern or ErrUnbuildable when to cannot build one from what from reads; the caller keeps such a path as it is.
A translation must never land two source paths on one target path, or one version would overwrite another: go-default's v1.2.3-rc.1.zip and v1.2.3.zip would both be lib-1.2.3.zip in simple-default, which has no file revision. So the target path must lead back to the source path alone, or Translate answers a *LossError. The paths that lead back are those from builds out of what to reads in the target path, through either pattern of each; the source path must be one of them, and none of the others may translate to the same target. Two source paths that both passed would each be among the other's candidates, so at most one passes.
Types ¶
type Coordinates ¶
type Coordinates struct {
Org, Module, BaseRev, FolderItegRev, FileItegRev, Classifier, Ext string
}
Coordinates are what a layout reads from one file's path: the module identity the searches (decision 0012) and the format handlers (decision 0032) work with.
func (Coordinates) FileVersion ¶
func (c Coordinates) FileVersion() string
FileVersion is the file's own version: the base revision with the file's integration revision, as in 1.0-20260101.120000-1.
func (Coordinates) Integration ¶
func (c Coordinates) Integration() bool
Integration reports an integration (snapshot) version.
func (Coordinates) Version ¶
func (c Coordinates) Version() string
Version is the module version the file belongs to: the base revision with the folder's integration revision, or the file's when the folder has none, as in 1.0-SNAPSHOT.
type Definition ¶
type Definition struct {
Name string
ArtifactPathPattern string
DistinctiveDescriptorPathPattern bool
DescriptorPathPattern string
FolderIntegrationRevisionRegExp string
FileIntegrationRevisionRegExp string
}
Definition is a repository layout as stored in the configuration descriptor (repoLayouts.<name>).
func Bundled ¶
func Bundled() []Definition
Bundled returns the definitions of the layouts Artifactory ships, in the order the descriptor lists them.
type Layout ¶
type Layout struct {
// contains filtered or unexported fields
}
Layout is a compiled Definition.
func Compile ¶
func Compile(def Definition) (*Layout, error)
Compile parses the definition's patterns. The integration-revision regexps are substituted into [folderItegRev] and [fileItegRev] at compile time, so a layout with an empty regexp gets Artifactory's permissive ".+" and still matches. A token that is neither documented nor custom is an error, as Artifactory's layout editor reports it, so a layout the descriptor stores always reads the paths its author meant.
func Lookup ¶
Lookup compiles a bundled layout by name. Unlike Compile, it drops a token outside the documented set, as Artifactory's parser does when it matches a path, because 7.x ships layouts that use such tokens.
func (*Layout) Build ¶
Build renders an artifact path from token values. Optional groups are emitted only when every token inside them has a value; mandatory tokens without a value are an error, and so is a pattern with a token it drops (ErrUnbuildable).
func (*Layout) BuildDescriptor ¶
BuildDescriptor renders a descriptor path, or an error when the layout has no descriptor pattern or Build would refuse its pattern.
func (*Layout) Definition ¶
func (l *Layout) Definition() Definition
Definition returns the source definition.
func (*Layout) Has ¶
Has reports whether the artifact pattern uses token; org and orgPath stand for each other, as they do in Match and Build.
func (*Layout) IsDescriptor ¶
IsDescriptor reports whether the path matches the descriptor pattern.
func (*Layout) Match ¶
Match extracts token values from an artifact path. When the layout has a distinctive descriptor pattern that pattern is tried first, because a POM also matches the artifact pattern with ext=pom and the descriptor match is the more specific one.
func (*Layout) Prefixes ¶
Prefixes return the text every path the layout matches with the tokens in v starts with: the artifact pattern's, and the descriptor pattern's when there is one, each rendered up to its first optional group or token without a value. Values are copied as given, so one with * or ? makes a prefix a glob. A search narrows by them before Match decides.
func (*Layout) Read ¶
func (l *Layout) Read(fullPath string) (Coordinates, bool)
Read returns the coordinates the layout reads from a repository-relative file path; ok is false when the path does not fit the layout or lacks one of the three fields JFrog's repository-layouts page calls mandatory for module identification: organisation, module and base revision (ModuleInfo.isValid in 6.20). So a layout without [org] or [orgPath], such as cargo-default, reads no module.
func (*Layout) VersionTokens ¶
VersionTokens returns the layout a download path that may ask for a version token is read with: [INTEGRATION] and [RELEASE] also stand for either integration revision, as Artifactory reads a request (RepoLayoutUtils.getTokenRegExp with version tokens). A base revision already reads [RELEASE]. Without this, the lazy base revision would take in a following -[INTEGRATION], and the request would read as a release. The definition stays the layout's own.
type LossError ¶
type LossError struct {
From, To string // the layouts' names
Path string // the source path
Target string // the path the translation would give
Lost []string
Rival string
}
LossError is ErrLossy for one path: the tokens whose values the target layout has no place for, or, when every value survives but the paths still meet, another source path that translates to the same target.
Source Files