Documentation
¶
Overview ¶
Package settings holds the cascading defaults: server -> organization -> stack -> environment -> tile. A tile's explicit value always wins; zero/empty means "inherit from the level above"; the chain bottoms out in built-ins.
Index ¶
- type Level
- type Resolved
- func Above(levels []Level, kind string) Resolved
- func ForOrg(ctx context.Context, store repo.Store, orgID string) Resolved
- func ForServer(ctx context.Context, store repo.Store) Resolved
- func ForStack(ctx context.Context, store repo.Store, stackID string) Resolved
- func ForTile(ctx context.Context, store repo.Store, t *repo.Tile) Resolved
- func Resolve(levels ...Settings) Resolved
- func TryTile(ctx context.Context, store repo.Store, t *repo.Tile) (Resolved, error)
- type Settings
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Level ¶
Level is one rung of the cascade, named so a settings page can say where an inherited value came from.
func Levels ¶
Levels walks the chain down to the deepest id given and returns every rung, server first. The org is derived from the stack, and the stack from the environment, so a caller only ever names the level it is looking at.
A store error is returned, not swallowed. A level that fails to load looks exactly like a level that sets nothing, and for Protect that reads as "not protected": the caller has to know the difference (TryTile).
type Resolved ¶
type Resolved struct {
CronTimeoutMin int
CPULimit float64
MemLimitMB int
RunRetentionDays int
MetricRetentionHours int
// Protect gates every URL with basic auth. An empty user or password
// while on locks the URL rather than opening it (proxy.WriteApp).
Protect bool
ProtectUser string
ProtectPassword string
// NodeGroup is the resolved placement group, "" = anywhere.
NodeGroup string
// BuildNode is the node id builds run on, "" = the manager.
BuildNode string
// Work queue limits per kind.
CronRunConcurrency int
BackupRunConcurrency int
BackupRestoreConcurrency int
VolumeMoveConcurrency int
}
Resolved is the fully-cascaded result, every field concrete.
func Above ¶ added in v0.4.0
Above resolves the levels over the one of this kind, which is what a settings page shows as the inherited value.
func Resolve ¶
Resolve applies override levels in order (server, org, stack, env); later levels win where set.
func TryTile ¶ added in v0.4.0
TryTile is ForTile for callers that must tell a missing level from an unreadable one, which is everything reading Protect: a swallowed error resolves to "not protected" and publishes the URL.
func (Resolved) EffectiveGroup ¶
EffectiveGroup applies the cascade to a tile's own node_group: empty inherits the level above, which bottoms out in "anywhere".
func (Resolved) EffectiveLimits ¶
EffectiveLimits applies the cascade to a resource's explicit limits: zero means inherit the resolved default.
func (Resolved) EffectiveTimeout ¶
EffectiveTimeout applies the cascade to a cron timeout: <=0 inherits.
type Settings ¶
type Settings struct {
CronTimeoutMin *int `json:"cron_timeout_min,omitempty"`
CPULimit *float64 `json:"cpu_limit,omitempty"`
MemLimitMB *int `json:"mem_limit_mb,omitempty"`
RunRetentionDays *int `json:"run_retention_days,omitempty"`
MetricRetentionHours *int `json:"metric_retention_hours,omitempty"`
// Protect puts basic auth in front of every URL of every tile below this
// level. User and password travel as a pair: the nearest level that sets
// either supplies both (docs/plans/48-install-domains-and-basic-auth.md).
// The password is plain text or a ${{ }} reference.
Protect *bool `json:"protect,omitempty"`
ProtectUser *string `json:"protect_user,omitempty"`
ProtectPassword *string `json:"protect_password,omitempty"`
// NodeGroup constrains where tiles at this level may run, by the
// stackr.group node label. Empty string is an explicit "anywhere" that
// overrides a group set above (docs/plans/31-node-agent-open-questions.md,
// node groups).
NodeGroup *string `json:"node_group,omitempty"`
// BuildNode is the swarm node id image builds run on, instance-wide and
// only read at the server level. Empty means the manager, in a capped
// builder per org (docs/plans/37-builds.md).
BuildNode *string `json:"build_node,omitempty"`
// How many of each queued kind run at once, instance-wide and only read
// at the server level like BuildNode (docs/plans/33-workqueue.md).
CronRunConcurrency *int `json:"cron_run_concurrency,omitempty"`
BackupRunConcurrency *int `json:"backup_run_concurrency,omitempty"`
BackupRestoreConcurrency *int `json:"backup_restore_concurrency,omitempty"`
VolumeMoveConcurrency *int `json:"volume_move_concurrency,omitempty"`
}
Settings is one level's overrides. Nil field = inherit.
func Chain ¶
Chain is Levels' settings alone, ready for Resolve. A store error means no overrides, which is the right answer for the limits and placement fields: falling back to the built-in default is better than failing the caller. Anything that must not fail open goes through TryChain instead.
func Merge ¶
Merge folds submitted form values into an existing level's overrides. A key the form never submitted is left untouched, settings forms show a subset of the fields, and a partial form must not wipe the rest. A key submitted empty clears the override back to "inherit".
CPULimit and MemLimitMB accept an explicit 0, which means "unlimited" and is how a lower level overrides a limit set above it. The timeout and retention fields have no meaningful zero, so a non-positive value clears them instead.
func TryChain ¶ added in v0.4.0
func TryChain(ctx context.Context, store repo.Store, orgID, stackID, envID string) ([]Settings, error)
TryChain is Chain with the store error kept.
func (Settings) Check ¶ added in v0.4.0
Check refuses a level that sets half of the basic auth pair. Resolve takes user and password as one unit, so a level with only one of them resolves the other to empty, and proxy.WriteApp locks every URL below it behind a password nobody knows. Caught at the save, where the operator can see it.