settings

package
v0.4.1 Latest Latest
Warning

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

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

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

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type Level

type Level struct {
	Kind     string // server | org | stack | env
	Name     string
	Settings Settings
}

Level is one rung of the cascade, named so a settings page can say where an inherited value came from.

func Levels

func Levels(ctx context.Context, store repo.Store, orgID, stackID, envID string) ([]Level, error)

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

func Above(levels []Level, kind string) Resolved

Above resolves the levels over the one of this kind, which is what a settings page shows as the inherited value.

func ForOrg

func ForOrg(ctx context.Context, store repo.Store, orgID string) Resolved

ForOrg resolves server defaults + one org's overrides.

func ForServer

func ForServer(ctx context.Context, store repo.Store) Resolved

ForServer resolves the local server's defaults.

func ForStack

func ForStack(ctx context.Context, store repo.Store, stackID string) Resolved

ForStack resolves server -> org -> stack.

func ForTile

func ForTile(ctx context.Context, store repo.Store, t *repo.Tile) Resolved

ForTile resolves the full chain for one tile: server -> org -> stack -> env.

func Resolve

func Resolve(levels ...Settings) Resolved

Resolve applies override levels in order (server, org, stack, env); later levels win where set.

func TryTile added in v0.4.0

func TryTile(ctx context.Context, store repo.Store, t *repo.Tile) (Resolved, error)

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

func (r Resolved) EffectiveGroup(group string) string

EffectiveGroup applies the cascade to a tile's own node_group: empty inherits the level above, which bottoms out in "anywhere".

func (Resolved) EffectiveLimits

func (r Resolved) EffectiveLimits(cpu float64, memMB int) (float64, int)

EffectiveLimits applies the cascade to a resource's explicit limits: zero means inherit the resolved default.

func (Resolved) EffectiveTimeout

func (r Resolved) EffectiveTimeout(minutes int) int

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

func Chain(ctx context.Context, store repo.Store, orgID, stackID, envID string) []Settings

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

func Merge(s Settings, vals url.Values) Settings

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 Parse

func Parse(blob string) Settings

Parse decodes a settings JSON blob; bad or empty input is "no overrides".

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

func (s Settings) Check() error

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.

func (Settings) JSON

func (s Settings) JSON() string

JSON encodes for storage.

Jump to

Keyboard shortcuts

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