stackconf

package
v0.2.0 Latest Latest
Warning

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

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

Documentation

Overview

Package stackconf parses stackr-compose.yml, declarative stack config, and resolves it into per-environment tile definitions. Parsing and merging are pure; fetching files and diffing against the database live elsewhere (the fetcher is injected, the diff engine is in plan.go).

Merge model: tiles are kept as raw YAML maps until after include- and environment-overlay merging, then decoded into typed TileConf. That is what makes sparse overlays trivial, an overlay only overrides the keys it mentions.

Index

Constants

View Source
const ApplyKind = "config.apply"

ApplyKind is the work-queue kind a config apply runs under.

View Source
const DefaultPath = "stackr-compose.yml"

DefaultPath is where the config file lives unless the stack says otherwise.

Variables

View Source
var ErrNoFile = errors.New("config file not found in repo")

ErrNoFile marks a bound stack whose repo has no config file, by design a no-op, not an error state.

View Source
var ErrNotBound = errors.New("stack has no config repo bound")

ErrNotBound marks a stack without a config binding.

Functions

func EnqueueApply

func EnqueueApply(ctx context.Context, q *workqueue.Queue, stack *repo.Stack, cp *repo.ConfigPlan, force bool) (string, error)

EnqueueApply is the one way a config apply is started. The dedupe key is the plan, not the stack: one push makes one plan per branch-bound env, and a stack-wide key left every plan but the last sitting "pending" with nothing to run it. Two approvals of the same plan still collapse into one apply.

func EnvLines

func EnvLines(env map[string]string) string

EnvLines renders a tile's env map as sorted KEY=VALUE lines, the storage format used by repo.Tile.Env.

func ExportYAML

func ExportYAML(r *Resolved) ([]byte, error)

ExportYAML renders the file. Two spaces, because that is what every example in the docs uses and a file a person will edit should look like the ones they learned from.

func FromInstance

func FromInstance(from string) string

FromInstance is the instance slug a from: address ends in.

func HumanYAML

func HumanYAML(err error) error

humanYAML rewrites yaml.v3's unknown-key errors for someone reading them on the config plan page. Its own wording names the Go type the decode targeted ("not found in type stackconf.TileConf"), which means nothing to a person editing YAML, and its line number counts lines in a re-marshalled fragment rather than in the file they wrote. Anything that is not an unknown key is passed through untouched: those messages are already about the YAML. HumanYAML is humanYAML for the org file, which decodes strictly the same way and leaked the same Go type names (orgconf.File, orgconf.StackRef).

func ParseDep

func ParseDep(line string) (slug, cond string, err error)

ParseDep decodes one depends_on line: "slug" or "slug:condition". Bare slug means started.

func ParseMiddlewares added in v0.2.0

func ParseMiddlewares(s string) map[string]RawMap

ParseMiddlewares reads the stack row's form back.

func PolicyFor

func PolicyFor(env *repo.Environment, protected bool) string

PolicyFor resolves an env's apply policy. Manual unless someone turned that env's own setting to auto, and the file's protected flag ratchets it back to manual either way. No env gets auto for free: the bottom rung used to, so a push reconciled it unattended, and a config change nobody pressed anything for is not something to inherit by position.

func RegisterApply

func RegisterApply(q *workqueue.Queue, a Applier)

RegisterApply wires the apply handler onto the queue.

Requeue on restart, because an apply is convergent by design: it re-loads the config, re-diffs against whatever state actually exists now, and reconciles, so running it again on a half-finished environment finishes the job. That is the same property the walk in execute already relies on.

func RenderMiddlewares added in v0.2.0

func RenderMiddlewares(m map[string]RawMap) string

RenderMiddlewares is the stack row's form of proxy.middlewares, "" for none. yaml sorts map keys, so the same file always renders the same text.

func ValidateDomains

func ValidateDomains(ds []DomainResConf) error

ValidateDomains rejects a blank or duplicated host before anything is planned.

func ValidateTileConf

func ValidateTileConf(name string, tc TileConf) error

func ValidateUIEdits

func ValidateUIEdits(v string) error

ValidateUIEdits accepts the two modes, or blank for "inherit / default".

Types

type Applier

type Applier struct {
	Planner Planner
	Ops     envops.Ops
	DBs     *managedtiles.Service
	Engine  *deploy.Engine
	Jobs    *jobs.Service
	// Backups reloads the backup scheduler after the file's `backup:` blocks
	// land. Nil in tests and wherever an apply is a pure-DB reconciliation.
	Backups *backup.Service

	// Deployed, when non-nil, collects the tiles this apply queued a deploy
	// for. The push webhook sets it and skips those tiles in its own branch
	// build: a push that changes both config and code used to queue two
	// builds of the same commit for a tile both paths touched.
	Deployed map[string]bool
	// contains filtered or unexported fields
}

Applier reconciles the database to a stack's resolved config: the terraform promise, after apply, state matches the file. Deploy/schedule/proxy side-effects run through the same services the UI uses; each is nil-safe so pure-DB reconciliation is unit-testable.

func (Applier) ApplyPlan

func (a Applier) ApplyPlan(ctx context.Context, stack *repo.Stack, cp *repo.ConfigPlan, force bool) (bool, error)

ApplyPlan re-loads the config for the stored plan's scope, re-diffs against current state, and reconciles. force=true (human approval) allows deletes and ignores per-env policy; force=false is the webhook auto path, it applies only when every touched env's policy is auto and nothing is destroyed, returning (false, nil) otherwise.

func (Applier) ApplyResolved

func (a Applier) ApplyResolved(ctx context.Context, stack *repo.Stack, resolved *Resolved, opts DiffOpts, force bool) (bool, error)

ApplyResolved reconciles the database to a caller-provided desired config instead of loading it from git, the entry point the UI-staging path uses (the desired config comes from StateToResolved + staged edits). It re-diffs against current state and runs the same gate + execute as ApplyPlan. force=true is human approval (allows deletes, ignores per-env policy); force=false applies only when nothing is destroyed and every touched env is auto, returning (false, nil) otherwise.

func (Applier) ApplyStaged

func (a Applier) ApplyStaged(ctx context.Context, stack *repo.Stack, env *repo.Environment, force bool) (bool, error)

ApplyStaged reconciles one env's staged config and clears that env's staged changes on success. force=true is human approval (allows deletes / ignores per-env policy).

func (Applier) CopyTile

func (a Applier) CopyTile(ctx context.Context, stack *repo.Stack, env *repo.Environment, slug string, tc TileConf, fields map[string]bool) error

cronNeedsBuild reports whether any changed field feeds the built artifact. CopyTile writes tc onto an existing tile in env and deploys it: the compare panel's "Copy from <reference>". fields names what changed, in the update path's terms ("env", "image"). UI-managed stacks only; the caller gates.

func (Applier) Promote

func (a Applier) Promote(ctx context.Context, stack *repo.Stack, envSlug, commit string) error

Promote deploys the image built at commit to every git tile in one upper env, with no config apply behind it. A code-only push produces no config change, so there is no plan row to press; the ladder is what decides which envs can be promoted to.

The rungs come from the environment list, not from the config file at the commit: promoting an image has to keep working while the file does not load or a secret it declares is unset.

func (Applier) RenameStack

func (a Applier) RenameStack(ctx context.Context, stack *repo.Stack, name string, p *Plan) error

RenameStack moves the stack to the slug its file wants. Container and network names derive from the slug (envnet), so every tile's containers are stopped under the old name, the row is renamed, and running tiles are redeployed under the new one. Data survives: db and volume names are tile-id keyed. Tiles the plan deletes (and envs it tears down) stay stopped; tiles the plan also updates may deploy twice, correctness over thrift, a proxy-only update would otherwise leave its service down.

Exported because the API's PATCH /stacks/{id} needs exactly this: it used to write the new slug and stop there, so every running tile kept serving under its old service name while the panel resolved the new one, and the runtime swallows a stop against a service that is not there (runtime.ScaleService, errNoService). p may be an empty Plan: it only names the tiles and envs the rename should leave stopped because the same apply is deleting them.

func (Applier) RestartTile

func (a Applier) RestartTile(ctx context.Context, t *repo.Tile)

RestartTile is restartTile for the org file's own move applier, which tears down shared instances the same way and needs them back up the same way.

func (Applier) RunApplyJob

func (a Applier) RunApplyJob(ctx context.Context, j *workqueue.Job, p ApplyJob) error

RunApplyJob is the apply as the queue runs it. Exported so the registration above stays a three-line wiring function and this stays testable.

The error is written onto the plan row from here, with this job's context, which is the whole point of the move: every caller used to pass the HTTP request's context, so an apply that outlived the request was cancelled mid-way and the write recording that failed silently on the same dead context. The row kept the previous run's message and stayed pending.

func (Applier) StagedPlan

func (a Applier) StagedPlan(ctx context.Context, stack *repo.Stack, envSlug string) (*Plan, error)

StagedPlan diffs a stack's staged desired config against current state, scoped to one environment.

func (Applier) StagedResolved

func (a Applier) StagedResolved(ctx context.Context, stack *repo.Stack) (*Resolved, State, error)

StagedResolved builds a stack's desired config: the committed tiles (StateToResolved) with every staged change patched on top, in order.

type ApplyJob

type ApplyJob struct {
	StackID       string `json:"stack_id"`
	PlanID        string `json:"plan_id"`
	Force         bool   `json:"force"`
	PromoteEnv    string `json:"promote_env,omitempty"`
	PromoteCommit string `json:"promote_commit,omitempty"`
}

ApplyJob is the payload. Force is the human approval; false is the unattended webhook path, which applies only the environments whose policy is auto (Applier.holdManual).

PromoteEnv and PromoteCommit are set by the releases page's "apply the plan and promote": the images move only once the whole config has landed, and both halves belong to one job so a restart between them cannot leave the promote orphaned.

type BackupConf

type BackupConf struct {
	// Dest is ${{ org.backups.NAME }} or ${{ stackr.backups.NAME }}.
	Dest     string `yaml:"dest" json:"dest"`
	Schedule string `yaml:"schedule" json:"schedule"`
	// TZ names the zone the schedule is read in; the server's when absent.
	TZ string `yaml:"tz" json:"tz,omitempty"`
	// Keep is how many archives survive a prune; 0 keeps every one.
	Keep int `yaml:"keep" json:"keep,omitempty"`
	// Mode is what happens to the container while a volume is tarred:
	// pause (default), stop, or live. Volume tiles only; on a dump it is a
	// plan error rather than a silently ignored key.
	Mode string `yaml:"mode" json:"mode,omitempty"`
	// Enabled defaults to true; `enabled: false` keeps the schedule declared
	// and stops it firing.
	Enabled *bool `yaml:"enabled" json:"enabled,omitempty"`
}

BackupConf is a tile's backup schedule. The destination is a reference and never a literal: a destination carries the bucket credentials, and the file is in git.

Kind is not declared. A managed database is dumped with its engine's own tool; a tile with a volume gets a tar of the volume. There is no third answer, and asking the file to repeat it invites the two disagreeing.

func (BackupConf) On

func (b BackupConf) On() bool

On reports whether the schedule should fire, with the default applied.

type BaseConf

type BaseConf struct {
	Tiles map[string]RawMap `yaml:"tiles"`
}

BaseConf is the base: section.

type BuildConf

type BuildConf struct {
	Context    string `yaml:"context" json:"context,omitempty"`
	Dockerfile string `yaml:"dockerfile" json:"dockerfile,omitempty"`
}

type Change

type Change struct {
	Kind  string `json:"kind"` // create-env | update-env | delete-env | create | delete | update
	Env   string `json:"env"`
	Tile  string `json:"tile,omitempty"`
	Field string `json:"field,omitempty"` // update only
	Old   string `json:"old,omitempty"`
	New   string `json:"new,omitempty"`
	// Note is a consequence the approver has to see before clicking apply,
	// the data loss a db-engine replace causes, a narrowed sharing scope, a
	// dropped slice.
	Note string `json:"note,omitempty"`
	// Fields is what a create row is actually creating, for the plan page's
	// accordion: source, port, hosts, env keys, volumes, dependencies. Names
	// only, never values, the plan is stored in the database and a resolved
	// tile carries secrets.
	Fields []Field `json:"fields,omitempty"`
	// Input marks a row for a value the config declares and nobody has set.
	// The plan page opens it and puts the Set box inside, so a missing value
	// reads as a line of the diff instead of a banner over it.
	Input bool `json:"input,omitempty"`
	// Destroys marks a change that destroys data without deleting a tile,
	// today only a `uses:` entry leaving the file with on_remove: drop. It
	// exists so the gate can key on consequence rather than on Kind, which
	// would otherwise wave a slice drop through the auto-apply path.
	Destroys bool `json:"destroys,omitempty"`
}

Change is one line of a plan.

func GenChange

func GenChange(scope, name string) Change

GenChange is the row a `default: generated` secret renders as.

func InputChange

func InputChange(in Input) Change

InputChange is the plan row a declared-but-unset value renders as. Env carries the scope (stack | org), not an env slug: the value lives at the scope, and the row is the same wherever the plan is reviewed.

func PlanMove

func PlanMove(m Move, st MoveState) (change *Change, warning, err string)

PlanMove decides one entry: a rename change, a no-op warning, or an error. Exactly one of the three is non-empty.

func (Change) Declared

func (c Change) Declared() bool

Declared marks the rows finishPlan adds for values the config declares: one nobody has set, one the apply will mint. They are shown, never counted. A stack whose only row is an unset secret has nothing to apply, and counting it left that stack with a plan pending review forever.

type DefaultsConf

type DefaultsConf struct {
	CronTimeoutMin       *int     `yaml:"cron_timeout_min" json:"cron_timeout_min,omitempty"`
	CPULimit             *float64 `yaml:"cpu_limit" json:"cpu_limit,omitempty"`
	MemLimitMB           *int     `yaml:"mem_limit_mb" json:"mem_limit_mb,omitempty"`
	RunRetentionDays     *int     `yaml:"run_retention_days" json:"run_retention_days,omitempty"`
	MetricRetentionHours *int     `yaml:"metric_retention_hours" json:"metric_retention_hours,omitempty"`
	ProtectAutoDomains   *bool    `yaml:"protect_auto_domains" json:"protect_auto_domains,omitempty"`
	NodeGroup            *string  `yaml:"node_group" json:"node_group,omitempty"`
}

DefaultsConf is one level of the defaults cascade as the config file writes it. Every field is a pointer: nil is "say nothing here", which is what lets a level inherit rather than reset the level above to a zero value.

The same struct at org, stack and env level: one spelling everywhere, so a knob cannot mean one thing in stackr-org.yml and another in stackr-compose.yml.

func (DefaultsConf) Empty

func (d DefaultsConf) Empty() bool

Empty reports whether the file said nothing at this level, which is not the same as saying "inherit everything": a level that declares nothing leaves whatever the panel set alone.

func (DefaultsConf) SettingsJSON

func (d DefaultsConf) SettingsJSON() string

SettingsJSON renders the level for storage, the shape internal/stackrd/config/settings reads. build_node is deliberately not a config key: it is instance-wide and read only at the server level.

type DiffOpts

type DiffOpts struct {
	GitURL        string // the bound repo's clone URL, expected on built tiles
	Connector     string // the bound git connector id, fallback for tiles that don't name one
	DefaultBranch string // the bound branch, tile branch fallback

	// Domain-claim context (auto/apex): the slugs that feed generated names
	// and the resources this stack may claim under, nearest level first.
	// Zero-valued in pure unit tests, where only literal hosts appear.
	OrgSlug         string
	StackSlug       string
	DefaultEnv      string
	DomainResources []repo.DomainResource
	// ForeignOrgSlugs is every other organization's slug on this server. A
	// literal host may not start with one: config as code would otherwise be
	// the hole in the anti-squat rule the UI paths enforce.
	ForeignOrgSlugs map[string]bool

	// OnlyEnv restricts the diff to one environment (env-branch plans);
	// env-level create/delete of OTHER envs never appears in such a plan.
	OnlyEnv string
	// SkipEnvs excludes envs bound to their own branch from a stack-branch
	// plan, those are managed by their branch's plans.
	SkipEnvs map[string]bool
}

DiffOpts carries stack-level context the diff needs.

func (DiffOpts) OutOfScope

func (o DiffOpts) OutOfScope(envSlug string) bool

OutOfScope reports whether an env slug is outside this plan's scope. The same two-line rule half a dozen walks were writing out by hand, which is how the move planner came to have neither.

type DomainConf

type DomainConf struct {
	Host  string `yaml:"host" json:"host,omitempty"`
	Apex  string `yaml:"apex" json:"apex,omitempty"`
	Auto  bool   `yaml:"auto" json:"auto,omitempty"`
	Path  string `yaml:"path" json:"path,omitempty"`
	HTTPS *bool  `yaml:"https" json:"https,omitempty"` // nil = true
	// ForceHTTPS bounces plain HTTP onto the TLS router. Distinct from https:,
	// which is only "serve TLS here". nil = true, which is what serving TLS
	// alone used to do.
	ForceHTTPS *bool  `yaml:"force_https" json:"force_https,omitempty"`
	RedirectTo string `yaml:"redirect_to" json:"redirect_to,omitempty"`
	// Middlewares are appended after stackr's own auth and header ones: a
	// bare name is this stack's proxy.middlewares entry, stack/name another
	// stack's in the same org.
	Middlewares []string `yaml:"middlewares" json:"middlewares,omitempty"`
	Priority    int      `yaml:"priority" json:"priority,omitempty"`
	// Rule is a raw traefik rule that replaces the generated Host/PathPrefix
	// matcher. host: is still required: it picks the certificate.
	Rule string `yaml:"rule" json:"rule,omitempty"`
	// Port is the container port for this entry; 0 inherits the tile's.
	Port int `yaml:"port" json:"port,omitempty"`
}

DomainConf is one domain claim. Exactly one of Host / Apex / Auto is set: a literal host (as always), the bare host of a visible domain resource, or a generated name under the nearest visible resource. First listed is the primary, what STACKR_PUBLIC_URL resolves to.

func (DomainConf) ForceHTTPSOn

func (d DomainConf) ForceHTTPSOn() bool

ForceHTTPSOn reports whether plain HTTP is bounced; only meaningful when HTTPSOn is true.

func (DomainConf) HTTPSOn

func (d DomainConf) HTTPSOn() bool

type DomainResConf

type DomainResConf struct {
	Host string `yaml:"host"`
	// ACMEEmail is the Let's Encrypt account certificates under this resource
	// are issued on. Blank uses the instance's.
	ACMEEmail string `yaml:"acme_email,omitempty"`
	// IncludeEnvOnDefault keeps the default env's slug in generated names
	// (api.prod.stack.org instead of api.stack.org).
	IncludeEnvOnDefault bool `yaml:"include_env_on_default"`
}

DomainResConf is one declared domain resource. Hosts are unique across the whole server, so a clash is a plan error rather than an apply error.

type EnvConf

type EnvConf struct {
	Protected bool `yaml:"protected,omitempty"`
	// Color is how the panel draws this environment: a palette name
	// (violet, teal, amber, rose, sky, lime) or #rrggbb. See envcolor.
	Color string `yaml:"color,omitempty"`
	// Secrets an environment needs on top of the stack-level ones.
	Secrets []string `yaml:"secrets,omitempty"`
	// Defaults is this environment's level of the defaults cascade.
	Defaults DefaultsConf `yaml:"defaults,omitempty"`
	// ApplyPolicy is what a plan touching this environment does: "auto"
	// applies on its own, "manual" waits for a person. Empty is the per-rung
	// default (manual for the first environment, auto above it).
	ApplyPolicy string `yaml:"apply_policy,omitempty"`
	// Vars this environment sets, shadowing the stack-level vars: at
	// resolution time. Needs the map form of environments:, a list of names
	// has nowhere to carry it.
	Vars  map[string]string   `yaml:"vars,omitempty"`
	Tiles map[string]TileNode `yaml:"tiles,omitempty"`
}

EnvConf is one environment: base overlays plus its own tiles.

type EnvMap

type EnvMap map[string]string

EnvMap tolerates scalar YAML values of any type (PORT: 8080 without quotes) by stringifying them.

func (*EnvMap) UnmarshalYAML

func (m *EnvMap) UnmarshalYAML(n *yaml.Node) error

type EnvState

type EnvState struct {
	Tiles map[string]TileState // by slug
	// Color is the env row's own colour, "" when it has none.
	Color string
	// ApexHosts is the visible domain resources' bare hosts, so the
	// serializer can round-trip an apex claim as the intent, not a literal.
	ApexHosts map[string]bool
}

type EnvsNode

type EnvsNode struct {
	Order []string
	Envs  map[string]EnvConf
}

EnvsNode accepts both forms:

environments: [production, staging]
environments: {production: {...}, staging: {...}}

Order is preserved, the first environment is the default.

func (EnvsNode) MarshalYAML

func (e EnvsNode) MarshalYAML() (any, error)

MarshalYAML writes environments back in the map form, in ladder order. The list form is lossy the moment an environment carries anything of its own, and the order is the ladder, so it is never sorted.

func (*EnvsNode) UnmarshalYAML

func (e *EnvsNode) UnmarshalYAML(n *yaml.Node) error

type Fetcher

type Fetcher func(path string) ([]byte, error)

Fetcher loads an included file's raw bytes by repo-relative path.

type Field

type Field struct {
	Name  string `json:"name"`
	Value string `json:"value"`
}

Field is one line of a create row's detail.

type File

type File struct {
	Version int      `yaml:"version"`
	Stack   string   `yaml:"stack"`
	PREnvs  *PREnvs  `yaml:"pr_envs,omitempty"`
	Include []string `yaml:"include,omitempty"`
	// Secrets names the values this stack needs but does not carry, never
	// values, the file is in git. Declared once at stack level, valued per
	// env (unless env_versions: false). A bare key keeps today's semantics:
	// set out of band, standing plan warning while unset.
	Secrets SecretsNode `yaml:"secrets,omitempty"`
	// Vars are stack-wide plain values, read as ${{ stack.vars.NAME }}. Unlike
	// secrets: the value lives in the file, so this is for things that are
	// configuration, not credentials. An environment's own vars: shadows one.
	Vars map[string]string `yaml:"vars,omitempty"`
	// Defaults is this stack's level of the defaults cascade (server -> org ->
	// stack -> env -> tile). Same keys at every level; see
	// internal/stackrd/config/settings.
	Defaults DefaultsConf `yaml:"defaults,omitempty"`
	// Moved declares renames: map keys are identity to the differ, so without
	// it a renamed key plans a delete and a create, which for a tile with a
	// volume destroys data. See moved.go.
	Moved        []MovedEntry `yaml:"moved,omitempty"`
	Environments EnvsNode     `yaml:"environments"`
	// Shared is the stack-scoped tiles, managed instances shared by every
	// env. Scope is structural: an entry here is stack-scoped, a tile under an
	// environment is env-scoped. The instance row physically lives in the
	// default (first) environment.
	Shared map[string]RawMap `yaml:"shared,omitempty"`
	// Base is tiles defined once that land in EVERY static env. An env entry
	// with the same name is a sparse overlay (mergeMaps) or an exclusion
	// (false). Unlike shared:, each env gets its own copy, base slices are
	// per-env logical dbs.
	Base BaseConf `yaml:"base,omitempty"`
	// Domains are the stack's own domain resources, the bases its tiles
	// generate per-environment hostnames under (envops.AutoHost). Declaring
	// them here is what lets a managed stack own its own hostnames instead of
	// borrowing its org's.
	Domains []DomainResConf `yaml:"domains,omitempty"`
	// UIEdits: what the panel does with an edit to a field this file owns,
	// block (default) or stage. Blank inherits the org file's defaults:.
	UIEdits string `yaml:"ui_edits,omitempty"`
	// Proxy carries raw traefik middlewares this stack's domains, and other
	// stacks' in the org, can name (middlewares.go).
	Proxy ProxyConf `yaml:"proxy,omitempty"`
}

File is the parsed (but not yet resolved) config file.

func ExportFile

func ExportFile(r *Resolved) *File

ExportFile turns a Resolved into the file that would produce it.

func Parse

func Parse(data []byte) (*File, error)

Parse decodes and validates one file (includes not yet loaded).

type FileList

type FileList []string

FileList is the files: key, repo files shipped into the container. YAML accepts the map form (repo/path: /container/path[:template]) or a plain list of "repo/path:/container/path[:template]" lines; internally it is always the line form, sorted for the map case so rows and diffs stay canonical.

func (*FileList) UnmarshalYAML

func (f *FileList) UnmarshalYAML(n *yaml.Node) error

type FileSource

type FileSource interface {
	FileContents(ctx context.Context, cn *repo.Connector, repoFull, ref, path string) ([]byte, error)
	DefaultBranch(ctx context.Context, cn *repo.Connector, repoFull string) (string, error)
	HeadSHA(ctx context.Context, cn *repo.Connector, repoFull, ref string) (string, error)
}

FileSource fetches files from the bound repo (implemented by githubapp).

type Input

type Input struct {
	Scope    string `json:"scope"` // stack | org
	Name     string `json:"name"`
	Secret   bool   `json:"secret,omitempty"`
	Required bool   `json:"required,omitempty"`
	// Blocked is the blast radius as "env/tile": the tiles that read the
	// value plus everything downstream of them, none of which will come up
	// until it is set. Empty for org-scope inputs, their readers live in
	// stacks this plan cannot see.
	Blocked []string `json:"blocked,omitempty"`
}

Input is a value the config declares and nobody has set. It is not an error: the file says the name exists, the apply makes it exist, and the plan page offers a box to fill it in. Blocking the apply instead would mean a stack could never be stood up from its own config, which is the whole point of declaring it there.

type LimitsConf

type LimitsConf struct {
	CPU      float64 `yaml:"cpu" json:"cpu,omitempty"`
	MemoryMB int     `yaml:"memory_mb" json:"memory_mb,omitempty"`
}

type Move

type Move struct {
	Kind string // tile | env
	From string
	To   string
}

Move is a parsed entry: the kind, and the two slugs.

func ParseMoves

func ParseMoves(entries []MovedEntry, kinds ...string) ([]Move, error)

ParseMoves validates the list and splits every entry into kind and slugs. kinds is what this file type may address, named in the error so the author is not left guessing.

type MoveBlock

type MoveBlock struct {
	TileID   string `json:"tile_id"`
	Tile     string `json:"tile"`
	Env      string `json:"env"`
	FromNode string `json:"from_node"`
	ToGroup  string `json:"to_group"`
}

MoveBlock is one pinned tile standing between a plan and its apply.

type MoveState

type MoveState struct {
	// HasFrom and HasTo report whether a live row carries that slug.
	HasFrom, HasTo bool
	// Declared reports whether the file declares the target. A move whose
	// target is not declared is a rename followed by a delete in disguise.
	Declared bool
}

MoveState is what the planner needs to decide each entry's fate, without this package having to know how a caller stores things.

type MovedEntry

type MovedEntry struct {
	From string `yaml:"from" json:"from"`
	To   string `yaml:"to" json:"to"`
}

MovedEntry is one rename. Both sides are kind-dotted names in the file's own scope ("tile.web", "env.staging"): a stack file must never be able to declare a move in another stack, so there are no org:stack: path prefixes.

type PREnvs

type PREnvs struct {
	// nil = inherit the panel setting. A plain bool made `pr_envs: {tiles: ...}`
	// silently disable PR envs, since the file wins over the panel.
	Enabled *bool `yaml:"enabled"`
	Comment *bool `yaml:"comment"`
	Status  *bool `yaml:"status"`
	// Against limits which PR target branches spawn an env (empty = any).
	Against []string `yaml:"against"`
	// Tiles overlays the base tiles exactly like an environment's entries do
	// (sparse patch or false = exclusion).
	Tiles map[string]TileNode `yaml:"tiles"`
}

PREnvs mirrors envops.PRConfig plus the PR env's tile template. A PR env is base + Tiles, built purely from the file, never cloned from a live env, so panel drift can't leak into previews.

type Plan

type Plan struct {
	Changes []Change `json:"changes"`
	Errors  []string `json:"errors,omitempty"`
	// Warnings do not block an apply. A declared secret with no value is the
	// case they exist for: the config is legitimate, the stack simply is not
	// configured yet, and refusing to apply would mean a stack could never be
	// stood up before its credentials were in place. The deploy of a tile that
	// actually reads the missing value still fails, an unresolved reference
	// is never run.
	Warnings []string `json:"warnings,omitempty"`
	// GenSecrets is the `default: generated` secrets that still have no value.
	// Minting them is real work, so they make a plan non-empty: a commit whose
	// only change is a new generated secret used to plan "clean", which the
	// auto-apply path skips, so the secret sat unminted until some unrelated
	// tile change finally dragged an apply along.
	GenSecrets []string `json:"gen_secrets,omitempty"`

	// Inputs is the declared-but-unset values the plan page can collect before
	// the apply. Rendered as boxes, never as blockers.
	Inputs []Input `json:"inputs,omitempty"`
	// Moves are pinned tiles whose node group the file has changed, whose
	// home node is not in the new group. They block the apply until each one
	// has been moved, because a group change on a pinned tile is a request to
	// put its data on a different machine and nothing but a copy can do that
	// (docs/plans/31-node-agent-open-questions.md, step 8). The plan page
	// renders one row per move with the same Move modal the tile drawer uses.
	Moves []MoveBlock `json:"moves,omitempty"`
	// contains filtered or unexported fields
}

Plan is the full diff of desired config vs current state.

func Diff

func Diff(r *Resolved, s State, opts DiffOpts) *Plan

Diff computes the plan: desired (resolved config) vs current (state).

func ParsePlan

func ParsePlan(cp *repo.ConfigPlan) *Plan

ParsePlan decodes a stored plan's JSON blob.

func (*Plan) Destructive

func (p *Plan) Destructive() bool

Destructive reports whether applying would delete anything.

func (*Plan) Empty

func (p *Plan) Empty() bool

func (*Plan) InputsFirst

func (p *Plan) InputsFirst()

InputsFirst floats the input rows to the top, then the generated ones. What the reviewer can act on before approving comes before what the apply does on its own.

func (*Plan) Summary

func (p *Plan) Summary() string

Summary renders a one-line plan description ("3 to add, 1 to change, 2 to destroy", the terraform phrasing, because it works).

type Planner

type Planner struct {
	Store repo.Store
	Src   FileSource
}

Planner loads a stack's config from its bound repo, diffs it against the database, and stores the result as a ConfigPlan.

func (Planner) BadRefs

func (pl Planner) BadRefs(ctx context.Context, stack *repo.Stack, r *Resolved, onlyEnv string, skip map[string]bool) []string

BadRefs reports ${{ ... }} references the config declares that could not resolve after an apply, malformed, pointing at a source the file doesn't declare, or naming a stack/org variable nobody has set. Plan errors, because applying them produces tiles that refuse to deploy.

Apply calls this too (not just plan): a webhook push plans and applies in one go, so a gate that only ran at plan time never ran at all for that path.

func (Planner) BranchBoundEnvs

func (pl Planner) BranchBoundEnvs(ctx context.Context, stack *repo.Stack) (map[string]string, error)

BranchBoundEnvs returns the stack's static envs carrying their own config branch, as slug → branch.

func (Planner) DeclaredInputs

func (pl Planner) DeclaredInputs(ctx context.Context, stack *repo.Stack, r *Resolved, onlyEnv string, skip map[string]bool) []Input

DeclaredInputs is the declared secrets nobody has set, minus the generated ones the apply mints on its own, the boxes the plan page offers. Same walk as SecretIssues, kept separate so its four callers stay unchanged.

func (Planner) LoadResolved

func (pl Planner) LoadResolved(ctx context.Context, stack *repo.Stack, branch string) (*Resolved, error)

LoadResolved fetches and resolves the stack's config file at branch. Returns ErrNoFile when the file is absent.

func (Planner) Opts

func (pl Planner) Opts(ctx context.Context, stack *repo.Stack, branch, onlyEnv string, skip map[string]bool) DiffOpts

Opts builds the DiffOpts shared by plan and apply. skip/only scope the diff.

func (Planner) Preview

func (pl Planner) Preview(ctx context.Context, stack *repo.Stack, fetchBranch, applyBranch, onlyEnv string, skip map[string]bool) (*Plan, error)

Preview computes a plan without storing it, used for PR comments. The config file is read from fetchBranch (the PR head) but diffed as if it were applied from applyBranch (the merge target), so tile-branch fallbacks don't show phantom changes. onlyEnv/skip scope exactly like the stored-plan paths.

func (Planner) PreviewBundle

func (pl Planner) PreviewBundle(ctx context.Context, stack *repo.Stack, main []byte, files map[string][]byte, onlyEnv string) (*Plan, error)

PreviewBundle computes a plan from a posted config bundle without storing it, the CLI's local dry-run. The stack must be bound: the diff runs as if the bundle were applied from the stack's bound branch, so tile-branch fallbacks match a real apply. Envs pinned to their own branch are skipped with a warning (their plan comes from that branch), unless onlyEnv names one. Unlike Preview, this merges SecretIssues/GenSecrets, same set as plan().

func (Planner) Run

func (pl Planner) Run(ctx context.Context, stack *repo.Stack, sha string) ([]*repo.ConfigPlan, error)

Run plans the config at the stack's bound branch and stores one row: one commit, one plan, covering the whole stack and every env it declares. Envs bound to their own branch are skipped, RunEnv covers those. sha (optional) records which push triggered it.

It used to write one row per rung, the stack-scoped row carrying the bottom rung and every env above it getting its own. That made a config plan a promotion rung, which it is not: a plan is one diff of one commit, and moving an image up the ladder is a separate thing that lives on the releases page (docs/plans/34-apply-and-review-fixes.md, decision 1).

func (Planner) RunAll

func (pl Planner) RunAll(ctx context.Context, stack *repo.Stack, sha string) ([]*repo.ConfigPlan, error)

RunAll is "re-plan this stack": the stack-scoped plan plus a plan for every env pinned to its own branch, which Run deliberately skips. Every plan it produced comes back, stack-scoped one first, a caller that reports only the first would tell someone "one change" while a branch-bound staging env has a deletion queued. A failure on one env does not sink the rest.

Not the webhook's path: a push re-plans only what that branch drives, which is a different (narrower) set. This is the "re-plan everything" button, used by the panel, the API, and the post-secret-change refresh.

func (Planner) RunEnv

func (pl Planner) RunEnv(ctx context.Context, stack *repo.Stack, env *repo.Environment, sha string) (*repo.ConfigPlan, error)

RunEnv produces and stores a plan scoped to one env, read from that env's own config branch.

func (Planner) SecretIssues

func (pl Planner) SecretIssues(ctx context.Context, stack *repo.Stack, r *Resolved, onlyEnv string, skip map[string]bool) (errs, warns, gen []string)

SecretIssues checks declared secrets against stored values. One thing errors: an env override on a secret pinned stack-wide (env_versions: false), refused loudly rather than silently ignored, because the file contradicts itself. Everything missing only warns and comes back as an Input for the plan page to collect, including `required`, which says the stack needs the value to run, not that it may not be created. A stack has to be applicable before its credentials exist, or you could never stand one up from an empty panel.

Values are never checked for content and never printed. The file declares only that a name must exist.

func (Planner) Snapshot

func (pl Planner) Snapshot(ctx context.Context, stack *repo.Stack) (State, error)

Snapshot builds the diffable State from the database: static envs and their tiles/domains. Ephemeral (PR) envs are never config-managed.

func (Planner) StackBranch

func (pl Planner) StackBranch(ctx context.Context, stack *repo.Stack) (string, error)

StackBranch resolves the branch a stack-scoped plan reads from.

func (Planner) StagingOpts

func (pl Planner) StagingOpts(ctx context.Context, stack *repo.Stack, envSlug string) DiffOpts

StagingOpts is the diff context for UI staging: no bound git repo (tiles carry their own source via the serializer), plus the domain-claim context so auto/apex entries resolve. Scoped to one env.

type ProxyConf added in v0.2.0

type ProxyConf struct {
	Middlewares map[string]RawMap `yaml:"middlewares,omitempty"`
}

ProxyConf is the proxy: block.

type RawMap

type RawMap map[string]any

RawMap is a tile body kept unmerged. Decoding to TileConf happens after all merging (includes, overlays) is done.

type Resolved

type Resolved struct {
	Stack string
	// UIEdits is the file's ui_edits:, blank when it says nothing (the org
	// default then applies). See repo.Stack.UIEdits.
	UIEdits string
	// Domains is the stack's declared domain resources, stack-level (not per
	// env), so an env-scoped plan leaves them alone entirely.
	Domains []DomainResConf
	// Middlewares is proxy.middlewares, stack-level like Domains.
	Middlewares map[string]RawMap
	PREnvs      *PREnvs
	EnvOrder    []string // the ladder: first = default environment; the home (repo.HomeSlug) is not on it
	// DefaultEnv is the file's bottom rung, set by Load. Diff prefers it over
	// the store's idea of the default: on a first apply the envs the file
	// declares may not exist yet, and the store's first env can be one the
	// org file created in a different order. Empty for a Resolved built from
	// live state, where the store order is the truth.
	DefaultEnv string
	// Vars is the file's stack-level vars:, plain values only.
	Vars map[string]string
	// Defaults is the file's stack-level defaults:.
	Defaults DefaultsConf
	// Moves are the file's validated moved: entries.
	Moves []Move
	Envs  map[string]ResolvedEnv
	// PRTemplate is the tile set a PR env is built from (base + pr_envs.tiles),
	// nil when pr_envs is absent. Deliberately NOT in Envs, it must never look
	// like a static env to drift detection or the default-env pick.
	PRTemplate *ResolvedEnv
}

Resolved is the final product: per-environment tile sets, ready to diff.

func Load

func Load(data []byte, fetch Fetcher) (*Resolved, error)

Load parses data, pulls includes via fetch (merged in order, later wins), and resolves environment overlays.

func StateToResolved

func StateToResolved(stackName string, s State) *Resolved

StateToResolved serializes a live State (the current DB tiles) into a Resolved config that diffs clean against that same State. It is the basis for UI staging: the committed desired state is *derivable* from the tiles, staged edits patch this Resolved, and the existing Diff/execute engine reconciles, no second reconcile path.

It is the read-side inverse of applyTileConf; the two must stay in sync or a live env won't round-trip to an empty diff (see TestStateToResolvedRoundTrip).

multi-line quoted env values don't round-trip exactly because canonEnv (the differ's env comparison) is lossy for them. Single-line env, the overwhelming norm, is exact. The fix belongs in canonEnv, not here.

type ResolvedEnv

type ResolvedEnv struct {
	Protected bool
	Color     string
	// ApplyPolicy is the env's apply_policy:, "" for the per-rung default.
	ApplyPolicy string
	// Defaults is the env's own rung of the defaults cascade.
	Defaults DefaultsConf
	// Declared is what this env's own overlay sets per tile: flattened keys
	// ("image", "env.PORT"). A difference between environments the file
	// declares is on purpose, so the compare panel marks it intended.
	Declared map[string]map[string]bool
	// Secrets is the stack-level declarations plus this env's own (bare) ones.
	Secrets map[string]SecretConf
	// Vars is this env's own vars: only, not merged with the stack's. The
	// resolver does the shadowing, so an env row is written only where the
	// file actually declares one.
	Vars  map[string]string
	Tiles map[string]TileConf
}

type SecretConf

type SecretConf struct {
	// Default: "" = set out of band; "generated" = minted on the first apply
	// that finds it unset, then stable forever, later applies never touch
	// it, and changing the generation knobs never rotates an existing value.
	Default        string `yaml:"default" json:"default,omitempty"`
	Length         int    `yaml:"length" json:"length,omitempty"` // generated only; 0 = 32
	IncludeNumbers bool   `yaml:"include_numbers" json:"include_numbers,omitempty"`
	IncludeSymbols bool   `yaml:"include_symbols" json:"include_symbols,omitempty"`
	// Required: apply refuses while unset (instead of warning and deploying
	// services that crash without the value).
	Required bool `yaml:"required" json:"required,omitempty"`
	// EnvVersions (default true): each env holds its own value; generation
	// mints one per env. false = one stack-wide value, env overrides refused.
	EnvVersions *bool `yaml:"env_versions" json:"env_versions,omitempty"`
}

SecretConf is one declared secret's options. The zero value is a bare declaration: set out of band, warn while unset.

func (SecretConf) GenLength

func (sc SecretConf) GenLength() int

GenLength is the generation length with the default applied.

func (SecretConf) PerEnv

func (sc SecretConf) PerEnv() bool

PerEnv is EnvVersions with the default applied.

type SecretsNode

type SecretsNode map[string]SecretConf

SecretsNode is the secrets: map. A key with a null body is a bare declaration.

func (SecretsNode) MarshalYAML

func (sn SecretsNode) MarshalYAML() (any, error)

MarshalYAML keeps declared secrets in a stable order. A bare declaration writes as a null body, which is how the grammar spells "set out of band".

func (*SecretsNode) UnmarshalYAML

func (sn *SecretsNode) UnmarshalYAML(n *yaml.Node) error

type SliceState

type SliceState struct {
	Instance     string // the providing instance's slug (identity compare)
	Engine       string // the instance's engine: its SliceName rule normalises the file's name
	InstancePath string // dotted display form, relative where possible
	Name         string // db/bucket name inside the instance
	OnRemove     string // row policy: "" | detach | drop
	Public       bool
}

SliceState is a live slice as the differ sees it.

type State

type State struct {
	Envs map[string]EnvState // by slug; ephemeral envs must not be included
	// DomainRes is the stack's OWN domain resources (level "stack"). Org and
	// instance rows are inherited, not owned, so the stack file never deletes
	// them. Stack-level, so an env-scoped plan ignores them.
	DomainRes []repo.DomainResource
	// AllDomainRes is every resource on the server, for the uniqueness check.
	AllDomainRes []repo.DomainResource
	// OrgConnectors is the ids of the connectors this stack's org owns. A
	// tile's connector: is a raw id straight out of the file, and the token it
	// mints clones private repositories, so naming another org's id has to be
	// a plan error rather than a silent fallback at deploy time.
	OrgConnectors map[string]bool
	// AllDomains is every tile domain on the server: host+path is unique
	// (idx_domains_host_path), so a claim on a host another tile routes must
	// fail in the plan, not as a constraint error mid-apply.
	AllDomains []repo.Domain
	// StackSlug and Middlewares are the stack row's slug and stored
	// proxy.middlewares. OrgMiddlewares is every other stack's names in the
	// org by slug; MiddlewareUsers is the other stacks' tiles naming one of
	// this stack's, by name.
	StackSlug       string
	Middlewares     string
	OrgMiddlewares  map[string]map[string]bool
	MiddlewareUsers map[string][]string
}

State is a snapshot of what a stack currently looks like in the database. Building it (DB reads) happens at the caller; diffing stays pure.

type TileConf

type TileConf struct {
	Type   string     `yaml:"type" json:"type"` // service (default) | cron | function | managed | volume; from: implies slice
	Build  *BuildConf `yaml:"build" json:"build,omitempty"`
	Branch string     `yaml:"branch" json:"branch,omitempty"`
	Image  string     `yaml:"image" json:"image,omitempty"`
	// Git source. Config-managed stacks leave these empty and inherit the
	// bound repo/connector (via DiffOpts); UI-managed tiles carry them
	// explicitly so a UI git service round-trips through create + diff.
	GitURL          string       `yaml:"git_url" json:"git_url,omitempty"`
	Connector       string       `yaml:"connector" json:"connector,omitempty"`
	Port            int          `yaml:"port" json:"port,omitempty"`
	Domains         []DomainConf `yaml:"domains" json:"domains,omitempty"`
	Env             EnvMap       `yaml:"env" json:"env,omitempty"`
	Limits          *LimitsConf  `yaml:"limits" json:"limits,omitempty"`
	Healthcheck     string       `yaml:"healthcheck" json:"healthcheck,omitempty"`
	SecurityHeaders bool         `yaml:"security_headers" json:"security_headers,omitempty"`
	Volumes         []string     `yaml:"volumes" json:"volumes,omitempty"`
	WatchPaths      []string     `yaml:"watch_paths" json:"watch_paths,omitempty"` // regex per line, "!" prefix = ignore
	// Backup is this tile's backup schedule, one per tile. Nil means the file
	// says nothing; on a config-owned tile that is a delete, same as any other
	// key it stops declaring.
	Backup *BackupConf `yaml:"backup" json:"backup,omitempty"`
	// UpdatePolicy: registry-watcher behavior for image-source tiles,
	// "off" (default), "notify" (badge + notification) or "auto" (redeploy).
	UpdatePolicy string `yaml:"update_policy" json:"update_policy,omitempty"`
	// WaitForCI parks push auto-deploys until the commit's checks pass
	// (git-source tiles).
	WaitForCI bool `yaml:"wait_for_ci" json:"wait_for_ci,omitempty"`
	// Service build/routing extras editable from the settings form. These are
	// modeled so UI settings edits stage through the config engine.
	BuildArgs       string `yaml:"build_args" json:"build_args,omitempty"`
	PublishedPorts  string `yaml:"published_ports" json:"published_ports,omitempty"`
	TraefikOverride string `yaml:"traefik_override" json:"traefik_override,omitempty"`
	BasicAuthUser   string `yaml:"basic_auth_user" json:"basic_auth_user,omitempty"`
	BasicAuthHash   string `yaml:"basic_auth_hash" json:"basic_auth_hash,omitempty"` // bcrypt; staged from the form pre-hashed
	// Container runtime fields (services; shm_size_mb also applies to managed
	// instances). Restart is "" or "always" (restart on any exit),
	// "on-failure", or "no" (runtime.NormalizeRestart); Devices lines
	// are "host[:container[:perms]]"; User is docker's --user.
	User       string   `yaml:"user" json:"user,omitempty"`
	ShmSizeMB  int      `yaml:"shm_size_mb" json:"shm_size_mb,omitempty"`
	Privileged bool     `yaml:"privileged" json:"privileged,omitempty"`
	Devices    []string `yaml:"devices" json:"devices,omitempty"`
	Restart    string   `yaml:"restart" json:"restart,omitempty"`
	// Placement (docs/plans/31-node-agent-open-questions.md, step 8).
	// Replicas above 1 on a tile holding a volume is a config error, not
	// something quietly forced back to 1: one mounter per volume, always.
	// NodeGroup constrains the tile to nodes labelled stackr.group=<x>;
	// empty inherits from the env, stack and org.
	Replicas  int    `yaml:"replicas" json:"replicas,omitempty"`
	NodeGroup string `yaml:"node_group" json:"node_group,omitempty"`
	// Docker-native healthcheck knobs for Healthcheck, in seconds (0 = default).
	HealthInterval    int `yaml:"healthcheck_interval" json:"healthcheck_interval,omitempty"`
	HealthTimeout     int `yaml:"healthcheck_timeout" json:"healthcheck_timeout,omitempty"`
	HealthRetries     int `yaml:"healthcheck_retries" json:"healthcheck_retries,omitempty"`
	HealthStartPeriod int `yaml:"healthcheck_start_period" json:"healthcheck_start_period,omitempty"`
	// function: run again whenever its own deploy finishes (manual Run now
	// always works).
	RunOnDeploy bool `yaml:"run_on_deploy" json:"run_on_deploy,omitempty"`
	// DependsOn: startup-order dependencies, "slug" or "slug:condition"
	// (started, the default | healthy | completed). Honored on bulk starts
	// (config apply); a manual single-tile deploy does not wait.
	DependsOn []string `yaml:"depends_on" json:"depends_on,omitempty"`
	// Files ships repo files into the container: map or line form, fetched
	// from the tile's git coordinates at deploy, bind-mounted read-only;
	// :template runs the varref resolver over the file bytes.
	Files FileList `yaml:"files" json:"files,omitempty"`
	// Storage attaches declared storage sub-paths (§2.7):
	// "storage-slug/path-name:/mount[:ro]" per entry.
	Storage []string `yaml:"storage" json:"storage,omitempty"`
	// cron (command is shared: a cron's one-shot line or a service's CMD override)
	Schedule       string `yaml:"schedule" json:"schedule,omitempty"`
	Command        string `yaml:"command" json:"command,omitempty"`
	TimeoutMinutes int    `yaml:"timeout_minutes" json:"timeout_minutes,omitempty"`
	AllowOverlap   bool   `yaml:"allow_overlap" json:"allow_overlap,omitempty"`
	// db
	Engine string `yaml:"engine" json:"engine,omitempty"`
	// ExternalPort publishes the instance on the host (0 = internal only).
	ExternalPort int `yaml:"external_port" json:"external_port,omitempty"`
	// Scope is structural in the file (shared: = stack, under an env = env),
	// so it is not a YAML key, resolve() sets it. It stays on the JSON side
	// because UI-staging patches and the serializer still carry it explicitly
	// (org included: org-scoped instances are panel/CLI-owned and invisible to
	// Snapshot until org-level config exists).
	Scope string `yaml:"-" json:"scope,omitempty"`
	// volume
	Attach string `yaml:"attach" json:"attach,omitempty"` // tile slug mounting this volume ("" = detached)
	Path   string `yaml:"path" json:"path,omitempty"`     // container mount path
	// slice: a logical db / bucket cut from a managed instance. The config
	// key is the reference slug (${{ tile.<key>.<OUTPUT> }}); From addresses
	// the instance (dotted: instance | stack.instance | org.stack.instance |
	// org.stack.env.instance, partial forms resolve from the current
	// context). Presence of from: is what makes an entry a slice; type: is
	// implied ("slice").
	From string `yaml:"from" json:"from,omitempty"`
	// Name is the db/bucket name inside the instance; "" = the config key.
	Name string `yaml:"name" json:"name,omitempty"`
	// OnRemove: keep (default) leaves the data when the entry leaves the
	// file; drop destroys it.
	OnRemove string `yaml:"on_remove" json:"on_remove,omitempty"`
	// Public gives the slice a public-read policy (s3 only).
	Public bool `yaml:"public" json:"public,omitempty"`
}

TileConf is one fully-merged tile definition. The json tags mirror the yaml ones so UI-staging patches (stored as JSON) merge onto a serialized tile under the same field names, see internal/stackrd/config/stackconf/staging.go.

func DecodeTile

func DecodeTile(raw RawMap) (TileConf, error)

DecodeTile / ValidateTileConf are the exported halves of tile decoding for the org config layer, same strict decode, same rules, no second grammar.

func TileConfOf

func TileConfOf(ts TileState, cur EnvState) TileConf

TileConfOf serializes a single tile to its config form, the exported entry the UI-staging handlers use to build a settings patch from an edited tile. cur supplies the env's tiles for volume attach resolution (pass a zero EnvState for services/crons, which don't need it).

func (TileConf) SliceName

func (tc TileConf) SliceName(key string) string

SliceName is the slice's db/bucket name with the default applied.

type TileNode

type TileNode struct {
	Excluded bool
	Raw      RawMap
}

TileNode is an entry under an environment's tiles: either an exclusion (false/null, meaningful in pr_envs.overrides) or a tile body.

func (TileNode) MarshalYAML

func (t TileNode) MarshalYAML() (any, error)

MarshalYAML writes a tile body, or `false` for an exclusion.

func (*TileNode) UnmarshalYAML

func (t *TileNode) UnmarshalYAML(n *yaml.Node) error

type TileState

type TileState struct {
	Tile    repo.Tile
	Domains []repo.Domain
	// Slice marks this entry as a live provisioned slice (logical db /
	// bucket) rather than a tile row, slices share the tile slug namespace.
	// Resolved in Snapshot because turning provision rows back into
	// addresses takes store lookups, and Diff is a pure function.
	Slice *SliceState
}

Jump to

Keyboard shortcuts

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