varref

package
v0.4.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Sep 17, 2026 License: Apache-2.0 Imports: 9 Imported by: 0

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
${{ org.storage.<name> }}     org network share, only in a tile's storage:
                              lines (storagetiles.Resolve)
${{ stackr.<NAME> }}          value the server supplies about itself
                              (PROXY_IP, PROXY_CIDR, see platformVar)

vars, secrets, backups and storage 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

View Source
const (
	BucketVars    = "vars"
	BucketSecrets = "secrets"
	BucketBackups = "backups"
	BucketStorage = "storage"
)

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.

View Source
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

func EnvLines(ctx context.Context, store repo.Store, t *repo.Tile) ([]string, error)

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 HasRef

func HasRef(s string) bool

HasRef reports whether a value contains a reference expression.

func OrgStorageRef added in v0.2.0

func OrgStorageRef(line string) string

OrgStorageRef reports the share name when a storage: line mounts an org share, "" when it is a server pool line.

func Refs

func Refs(s string) []string

Refs returns the reference bodies in a value, in order of appearance.

func Reserved

func Reserved(slug string) bool

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.

func Unset

func Unset(err error) (string, bool)

Unset reports whether err is (or wraps) an unset reference, and which name.

Types

type Dep

type Dep struct {
	Kind string // tile | resource
	ID   string
	Slug string
}

Dep is one thing a tile's variables reference. Drives canvas edges.

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 Output

type Output struct {
	Name   string
	Kind   string // endpoint | variable | resource
	Secret bool
}

Output is one name a source publishes.

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 Parse

func Parse(body string) (Ref, error)

Parse decodes one reference body (the text between ${{ and }}).

func (Ref) IsBucket

func (r Ref) IsBucket() bool

IsBucket reports whether the ref points at a scope's own values rather than at a source in that scope.

func (Ref) WantSecret

func (r Ref) WantSecret() bool

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.

func (Resolved) Lines

func (r Resolved) Lines() []string

Lines renders the variables as sorted KEY=VALUE strings for container specs.

type Resolver

type Resolver struct {
	// contains filtered or unexported fields
}

Resolver resolves references against the store.

func New

func New(store repo.Store) *Resolver

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.

func (*Resolver) Resolve

func (rr *Resolver) Resolve(ctx context.Context, consumerTileID string, mode Mode) (Resolved, error)

Resolve expands every variable owned by the consumer tile.

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.

func Catalogue

func Catalogue(ctx context.Context, store repo.Store, consumerTileID string) ([]Source, error)

Catalogue lists what a consumer tile may reference: sibling tiles in its environment, the managed resources actually bound to it, and its stack's and org's variables. Unbound resources are left out, advertising them would suggest references that are guaranteed to fail.

func (Source) Expr

func (s Source) Expr(name string) string

Expr renders the reference expression for one of a source's outputs.

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

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL