Documentation
¶
Overview ¶
Package varref resolves ${{ ... }} references in tile variables. It is the single resolver behind deploys, compose runs, database tiles, cron and config-plan validation, API previews and CLI export, a second implementation would be a second set of rules about who may read what.
Reference forms:
${{ tile.<slug>.<output> }} tile or managed resource in the consumer's env
${{ stack.<slug>.<output> }} stack-scoped singleton
${{ org.<slug>.<output> }} org-scoped singleton
${{ stack.vars.<name> }} stack-wide plain variable
${{ stack.secrets.<name> }} stack-wide secret
${{ org.vars.<name> }} org-wide plain variable
${{ org.secrets.<name> }} org-wide secret
${{ stackr.<NAME> }} value the server supplies about itself
(PROXY_IP, PROXY_CIDR, see platformVar)
vars, secrets and backups are reserved slugs: a tile or shared instance may not take one, or ${{ stack.vars.X }} would be ambiguous. The two-part ${{ stack.<name> }} / ${{ org.<name> }} forms are gone; they are parse errors naming the replacement.
Nothing here silently degrades: a reference that is missing, malformed, ambiguous, cyclic, cross-org, unbound or (in Scoped mode) secret is an error. An unresolved reference must never reach a container.
Index ¶
- Constants
- func EnvLines(ctx context.Context, store repo.Store, t *repo.Tile) ([]string, error)
- func HasRef(s string) bool
- func Refs(s string) []string
- func Reserved(slug string) bool
- func ScopeVarsUsed(ctx context.Context, store repo.Store, scope string, tileIDs []string) map[string]bool
- func Unset(err error) (string, bool)
- type Dep
- type Mode
- type Output
- type Ref
- type Resolved
- type Resolver
- type Source
- type UnsetError
Constants ¶
const ( BucketVars = "vars" BucketSecrets = "secrets" BucketBackups = "backups" )
Reserved slugs. They sit where a source slug would, so nothing else may be named one: Reserved gates tile and shared-instance names at validation time.
const ( // PlatformProxyIP is traefik's own address on the consumer env's network, // exact, but only until traefik is recreated and docker hands it another. PlatformProxyIP = "PROXY_IP" // PlatformProxyCIDR is that network's whole subnet. Survives any traefik // restart, at the cost of trusting every container on the network. PlatformProxyCIDR = "PROXY_CIDR" )
Values the platform supplies about itself, as opposed to anything a user stored. Closed set, checked at parse time: an unknown name under this scope can only ever be a typo, and it is better to say so than to resolve empty.
Variables ¶
This section is empty.
Functions ¶
func EnvLines ¶
EnvLines is the shorthand for callers that run a container they cannot attach to extra networks, compose projects, db tiles. It therefore refuses to return values that need one: those hostnames provably won't resolve inside that container, and starting it anyway just moves the failure somewhere harder to read. Callers that can attach (the deploy engine) use Resolve directly and honour Networks.
func Reserved ¶
Reserved reports whether a slug is one of the reference buckets. The list itself lives in repo so handlers can gate a name without importing the resolver.
func ScopeVarsUsed ¶
func ScopeVarsUsed(ctx context.Context, store repo.Store, scope string, tileIDs []string) map[string]bool
ScopeVarsUsed reports which stack- or org-scoped variable names the given tiles reference, the bucket forms `${{ stack.vars.NAME }}` and `${{ stack.secrets.NAME }}` (and their org counterparts), not a singleton reference, which points at a tile rather than a variable. Both buckets count: the canvas draws one card per name, secret or not.
Deliberately not a Resolve pass: the canvas only needs to know that a name is mentioned, and resolving would decrypt secrets, hit every referenced source and fail whenever a reference is broken. Drawing an edge for a reference that doesn't resolve is the right behaviour here, the wire is what the user wrote, and the deploy path is what refuses it.
Types ¶
type Mode ¶
type Mode int
Mode picks how much the caller is allowed to see. Scoping rules, env containment, stack/org membership, resource bindings, cross-org rejection, apply in BOTH modes; the only difference is secret values.
const ( // System is the deploy path: containers need real values, so secrets resolve. System Mode = iota // Scoped is an external read (API preview, CLI export, autocomplete) by a // caller without secrets:read. A secret-derived value is an error, not an // omission, silently dropping it hands out a half-built environment that // looks complete. Scoped )
type Ref ¶
type Ref struct {
Scope string // tile | stack | org | stackr
Slug string // source slug, or a reserved bucket (vars, secrets, backups)
Name string // output or variable name
Source string // original text, for error messages
}
Ref is a parsed reference body.
func (Ref) IsBucket ¶
IsBucket reports whether the ref points at a scope's own values rather than at a source in that scope.
func (Ref) WantSecret ¶
WantSecret reports whether a bucket ref asked for the secret namespace.
type Resolved ¶
type Resolved struct {
Vars map[string]string
Deps []Dep
Networks []string // shared docker networks the consumer must join
}
Resolved is a consumer tile's fully-expanded environment plus what the deploy engine needs to make those values reachable.
type Resolver ¶
type Resolver struct {
// contains filtered or unexported fields
}
Resolver resolves references against the store.
func (*Resolver) ExpandStrings ¶
func (rr *Resolver) ExpandStrings(ctx context.Context, consumerTileID string, mode Mode, in []string) ([]string, error)
ExpandStrings resolves references inside arbitrary strings the consumer tile owns, volume lines and command overrides, which are not variables and so never pass through Resolve. Strings without references come back untouched; any failure is an error under the same never-run-unresolved contract as Resolve. Network/dependency side effects are not reported: a path or argv fragment is not an address the container must reach.
type Source ¶
type Source struct {
Scope string // tile | stack | org | stackr
Slug string // source slug, or the vars/secrets bucket
Kind string
Outputs []Output
}
Source is one thing a tile may reference, with the names it publishes. The scope-wide values come as two sources, Slug "vars" and Slug "secrets", so the expression a suggestion inserts is right without threading the secret flag through Expr. Values are deliberately absent: the catalogue drives autocomplete, which must be safe to serve to a caller that may not read secrets.
type UnsetError ¶
type UnsetError struct {
Source string // the reference as written
Scope string // stack | org
Bucket string // vars | secrets, "" when the caller didn't come from a ref
Name string
}
scopeVar resolves ${{ stack.vars.<name> }}, ${{ stack.secrets.<name> }} and their org counterparts. The bucket in the reference must match the row's secret flag: a mismatch is a config fault, not an unset value. UnsetError is the one resolution failure that is not a fault in the config: the file names a value and nobody has set it yet. Everything else here is a typo or a broken wire; this is a stack that is simply not configured, which the plan already said it was allowed to be. Typed so the deploy engine can park the tile as waiting instead of painting the card red.
func (*UnsetError) Error ¶
func (e *UnsetError) Error() string