Documentation
¶
Overview ¶
Package rel is the pure release model: versions, digests, tags, and tag plans.
Parse functions construct domain values. PlanTags decides which immutable exact tag and moving channel tags a candidate release may apply. The package performs no I/O and depends only on the standard library.
Index ¶
Constants ¶
This section is empty.
Variables ¶
var ( // ErrImmutableTag reports that an exact version tag already points at // another digest. ErrImmutableTag = errors.New("immutable tag conflict") // ErrChannelCorrupt reports missing version annotation, an out-of-line // channel, or equal versions with different digests. ErrChannelCorrupt = errors.New("corrupt channel state") // ErrStateIncomplete reports that a required channel is missing from // [ChannelState.Channels]. ErrStateIncomplete = errors.New("incomplete channel state") )
Sentinel errors returned by PlanTags.
Functions ¶
This section is empty.
Types ¶
type Action ¶
type Action string
Action is the planned outcome for one tag.
const ( // ActionCreate means the tag must be applied to the candidate digest. ActionCreate Action = "create" // ActionAccept means the tag already resolves to the candidate digest. ActionAccept Action = "accept" // ActionRetain means the channel stays on a newer release. ActionRetain Action = "retain" )
type Channel ¶
type Channel struct {
// Scope is the channel's advancement rule.
Scope Scope
// Tag is the registry tag for this channel.
Tag Tag
}
Channel is one moving tag together with its advancement rule.
func ChannelsFor ¶
ChannelsFor returns the moving channels for v, in planning order.
The result is always minor "MAJOR.MINOR", major "MAJOR", then latest "latest". Tags are formatted from decimal version components or the literal "latest", which cannot produce an invalid OCI tag.
type ChannelState ¶
type ChannelState struct {
// Exact is the observed state of the candidate's exact version tag.
Exact TagState
// Channels is the observed state of each moving channel. Every channel
// from [ChannelsFor] must be present as a key.
Channels map[Channel]TagState
}
ChannelState is the observed state of the exact tag and every channel.
type Decision ¶
type Decision struct {
// Tag is the registry tag this decision applies to.
Tag Tag
// Scope is the tag's classification.
Scope Scope
// Action is the planned outcome.
Action Action
}
Decision is the planned action for one tag.
type Digest ¶
type Digest string
Digest is a lowercase sha256:<64 hex> image digest.
The only constructor is ParseDigest, which requires the sha256: prefix and normalizes uppercase hex. The zero value is invalid.
func ParseDigest ¶
ParseDigest constructs a Digest from a sha256:<hex> string.
The sha256: prefix is required. The hex part must be exactly hex.EncodedLen of sha256.Size hexadecimal digits. Uppercase hex is normalized to lowercase. Any other prefix, length, or charset is rejected.
type Secret ¶
type Secret struct {
// contains filtered or unexported fields
}
Secret holds a credential that must not appear in logs or encodings.
Secret.Reveal is the only way to read the payload. String, GoString, and the marshal methods always return [redacted], including for an empty value.
func (Secret) MarshalJSON ¶
MarshalJSON returns the JSON string [redacted].
func (Secret) MarshalText ¶
MarshalText returns [redacted].
type Tag ¶
type Tag string
Tag is a validated OCI image tag.
The only constructor is ParseTag. The zero value is invalid.
type TagPlan ¶
type TagPlan struct {
// Version is the candidate release version.
Version Version
// Digest is the candidate image digest.
Digest Digest
// Decisions are the exact tag and each channel, in planning order.
Decisions []Decision
}
TagPlan is the complete set of tag decisions for one candidate.
func PlanTags ¶
func PlanTags(v Version, digest Digest, current ChannelState) (TagPlan, error)
PlanTags decides which tags a candidate release may apply.
The exact tag is decided first, then each channel from ChannelsFor in order. A zero digest is rejected. A channel missing from current.Channels is ErrStateIncomplete. An exact tag on another digest is ErrImmutableTag. A missing version annotation, an out-of-line channel, and equal versions with different digests are ErrChannelCorrupt.
type TagState ¶
type TagState struct {
// Present reports whether the tag currently resolves.
Present bool
// Digest is the resolved digest. It is meaningful only when Present.
Digest Digest
// HasVersion reports whether a version annotation was read.
HasVersion bool
// Version is the annotated version. It is meaningful only when HasVersion.
Version Version
}
TagState is the observed registry state of one tag.
type Version ¶
type Version struct {
// Major is the leftmost version component.
Major uint64
// Minor is the middle version component.
Minor uint64
// Patch is the rightmost version component.
Patch uint64
}
Version is a canonical stable MAJOR.MINOR.PATCH triple.
The only constructor is ParseVersion. The zero value is 0.0.0, which is a valid version.
func ParseVersion ¶
ParseVersion constructs a Version from a stable MAJOR.MINOR.PATCH string.
The grammar is exactly three decimal components with no leading zeros (except the value 0), no v prefix, no sign, no prerelease, and no build metadata. A component that does not fit in uint64 is rejected. Error text names the problem and echoes the input.
func (Version) Compare ¶
Compare reports the order of v and other.
It returns -1 if v is less, 0 if they are equal, and +1 if v is greater. Components are compared as major, then minor, then patch.
func (Version) Tag ¶
Tag returns the exact-version registry tag, which equals Version.String.
A decimal triple always starts with a digit and contains only digits and dots, so the result is a valid OCI tag.
Source Files