Documentation
¶
Overview ¶
Package version parses the version specifiers that follow a name (#VERSION, :LABEL, ~SHIFT) for every cloud product.
Three grammars cover the products: NumericGrammar (integer versions), OpaqueGrammar (opaque version ids, optionally with staging labels), and BareGrammar (unversioned; the whole argument is the name). products.go binds each product to one of them (AWSParameterStore, AWSSecretsManager, GoogleCloudSecretManager, AzureKeyVault, AzureAppConfiguration). Each versioned grammar's Suffix rebuilds the suffix that callers hand to the use cases.
Version specification grammar:
<name><absolute>?<shift>*
Where:
- <name> is the parameter/secret name (required)
- <absolute> is a type-specific absolute version specifier (optional)
- <shift> is ~ or ~N for relative version shift (optional, repeatable)
Examples:
- Numeric: /my/param, /my/param#3, /my/param~1, /my/param#5~2
- Opaque: my-secret, my-secret#abc123, my-secret:AWSCURRENT, my-secret~1
Index ¶
Constants ¶
This section is empty.
Variables ¶
var ( // ErrInvalidAWSSecretsManagerID is returned when # is not followed by an AWS // Secrets Manager version ID. ErrInvalidAWSSecretsManagerID = errors.New("# must be followed by a version ID") // ErrInvalidAWSSecretsManagerLabel is returned when : is not followed by an AWS // Secrets Manager staging label. ErrInvalidAWSSecretsManagerLabel = errors.New(": must be followed by a label") // ErrGoogleCloudSecretManagerLabelUnsupported is returned when a :LABEL specifier is // used for Google Cloud Secret Manager, which has no staging labels. ErrGoogleCloudSecretManagerLabelUnsupported = errors.New( ": staging labels are not supported for Google Cloud Secret Manager " + "(versions are integers or \"latest\")", ) // ErrInvalidAzureKeyVaultID is returned when # is not followed by an Azure Key // Vault version id. ErrInvalidAzureKeyVaultID = errors.New("# must be followed by a version id") // ErrAzureKeyVaultLabelUnsupported is returned when a :LABEL specifier is used // for Azure Key Vault, which has no staging labels. ErrAzureKeyVaultLabelUnsupported = errors.New( ": staging labels are not supported for Azure Key Vault " + "(versions are opaque ids or the current version)", ) )
Product-specific errors.
var ( // AWSParameterStore is the AWS Systems Manager Parameter Store grammar: // integer versions, name#VERSION~SHIFT. AWSParameterStore = NumericGrammar{} // AWSSecretsManager is the AWS Secrets Manager grammar: opaque version ids // plus staging labels, name#VERSION / name:LABEL, then ~SHIFT. AWSSecretsManager = OpaqueGrammar{ // contains filtered or unexported fields } // GoogleCloudSecretManager is the Google Cloud Secret Manager grammar: integer // versions ("latest" is the zero spec) and no staging labels, so a ':' // specifier is rejected before any API call. GoogleCloudSecretManager = NumericGrammar{/* contains filtered or unexported fields */} // AzureKeyVault is the Azure Key Vault grammar: opaque 32-character hex version // ids and no staging labels, so a ':' specifier is rejected before any API // call. AzureKeyVault = OpaqueGrammar{ // contains filtered or unexported fields } // AzureAppConfiguration is the Azure App Configuration grammar. The service is // unversioned and a key may contain ':' (the ASP.NET hierarchy separator), // '#' and '~', so the whole argument is the key. AzureAppConfiguration = BareGrammar{} )
The grammar of each cloud product.
var ErrEmptySpec = errors.New("empty specification")
ErrEmptySpec is returned for an empty or whitespace-only specification.
var ErrInvalidNumericVersion = errors.New("# must be followed by a version number")
ErrInvalidNumericVersion is returned when # is not followed by a version number.
Functions ¶
This section is empty.
Types ¶
type BareAbsolute ¶ added in v1.10.0
type BareAbsolute struct{}
BareAbsolute is empty: a bare grammar has no absolute version specifier. It exists only to satisfy the shared Spec type parameter.
type BareGrammar ¶ added in v1.10.0
type BareGrammar struct{}
BareGrammar takes the whole argument as the name, for an unversioned service whose names may contain '#', ':' and '~'.
type BareSpec ¶ added in v1.10.0
type BareSpec = Spec[BareAbsolute]
BareSpec is a spec parsed with a BareGrammar.
Grammar: <name> (the whole argument is the name; nothing is split off)
Examples: my-key, /app/config, Logging:LogLevel:Default, weird#key, a~b.
type NumericAbsolute ¶ added in v1.10.0
type NumericAbsolute struct {
Version *int64 // Explicit version number (#VERSION)
}
NumericAbsolute is the absolute specifier of a numeric grammar: an optional integer version (#VERSION).
func (NumericAbsolute) IsSet ¶ added in v1.10.0
func (a NumericAbsolute) IsSet() bool
IsSet reports whether an explicit #VERSION was given.
type NumericGrammar ¶ added in v1.10.0
type NumericGrammar struct {
// contains filtered or unexported fields
}
NumericGrammar parses integer versions (#VERSION) plus ~SHIFT, the grammar of services whose versions count up from 1.
func (NumericGrammar) Parse ¶ added in v1.10.0
func (g NumericGrammar) Parse(input string) (*NumericSpec, error)
Parse parses a version specification string.
Shift syntax (Git-like, repeatable):
- ~ go back 1 version
- ~N go back N versions (e.g., ~2)
- ~~ go back 2 versions (same as ~1~1)
- ~1~2 cumulative: go back 3 versions
func (NumericGrammar) Split ¶ added in v1.10.0
func (g NumericGrammar) Split(input string) (name, suffix string, err error)
Split parses input and returns its name plus the rebuilt suffix (Suffix), the pair the use cases take.
func (NumericGrammar) Suffix ¶ added in v1.10.0
func (NumericGrammar) Suffix(spec *NumericSpec) string
Suffix reconstructs the version-spec suffix (the part after the name) from a parsed spec, so that spec.Name+Suffix(spec) re-parses to an equivalent spec. It is what callers hand to provider.Reader.Resolve alongside the name.
Examples: {Version:3} -> "#3"; {Shift:2} -> "~2"; {Version:5, Shift:2} -> "#5~2"; {} -> "" (latest).
type NumericSpec ¶ added in v1.10.0
type NumericSpec = Spec[NumericAbsolute]
NumericSpec is a spec parsed with a NumericGrammar.
Grammar: <name>[#<N>]<shift>*
- #<N> optional version number (0 or 1)
- <shift> ~ or ~<N>, repeatable (0 or more, cumulative)
Examples: /my/param, /my/param#3, /my/param~1, /my/param#5~2, /my/param~~.
type OpaqueAbsolute ¶ added in v1.10.0
type OpaqueAbsolute struct {
ID *string // Version ID (#VERSION)
Label *string // Staging label (:LABEL)
}
OpaqueAbsolute is the absolute specifier of an opaque grammar: an optional version id (#VERSION) or, where the grammar allows labels, a staging label (:LABEL). At most one of them is set.
func (OpaqueAbsolute) IsSet ¶ added in v1.10.0
func (a OpaqueAbsolute) IsSet() bool
IsSet reports whether an explicit #VERSION or :LABEL was given.
type OpaqueGrammar ¶ added in v1.10.0
type OpaqueGrammar struct {
// contains filtered or unexported fields
}
OpaqueGrammar parses opaque version ids (#VERSION), optional staging labels (:LABEL), and ~SHIFT, the grammar of services whose version ids carry no order.
func (OpaqueGrammar) Parse ¶ added in v1.10.0
func (g OpaqueGrammar) Parse(input string) (*OpaqueSpec, error)
Parse parses a version specification string.
Shift syntax (Git-like, repeatable):
- ~ go back 1 version
- ~N go back N versions
- ~~ go back 2 versions (same as ~1~1)
- ~1~2 cumulative: go back 3 versions
func (OpaqueGrammar) Split ¶ added in v1.10.0
func (g OpaqueGrammar) Split(input string) (name, suffix string, err error)
Split parses input and returns its name plus the rebuilt suffix (Suffix), the pair the use cases take.
func (OpaqueGrammar) Suffix ¶ added in v1.10.0
func (OpaqueGrammar) Suffix(spec *OpaqueSpec) string
Suffix reconstructs the version-spec suffix (the part after the name) from a parsed spec, so that spec.Name+Suffix(spec) re-parses to an equivalent spec. It is what callers hand to provider.Reader.Resolve alongside the name.
Examples: {ID:"abc"} -> "#abc"; {Label:"AWSCURRENT", Shift:1} -> ":AWSCURRENT~1"; {Shift:2} -> "~2"; {} -> "" (current).
type OpaqueSpec ¶ added in v1.10.0
type OpaqueSpec = Spec[OpaqueAbsolute]
OpaqueSpec is a spec parsed with an OpaqueGrammar.
Grammar: <name>[#<id> | :<label>]<shift>*
- #<id> optional version ID (0 or 1, mutually exclusive with :LABEL)
- :<label> optional staging label, only where the grammar has labels
- <shift> ~ or ~<N>, repeatable (0 or more, cumulative)
Examples: my-secret, my-secret#abc123, my-secret:AWSCURRENT, my-secret~1.
type Spec ¶
type Spec[A any] struct { Name string // Parameter/secret name (e.g., "/my/param", "my-secret") Absolute A // Absolute version specifier (type-specific, zero value if not specified) Shift int // Relative shift amount (0 means no shift, positive means go back N versions) }
Spec represents a parsed version specification. The type parameter A holds grammar-specific absolute version info (NumericAbsolute, OpaqueAbsolute, or BareAbsolute).
func (*Spec[A]) ShiftSuffix ¶ added in v1.10.0
ShiftSuffix renders the shift clause ("~N", or "" without a shift), the tail of the suffix each service's Suffix rebuilds from a parsed spec.
Source Files