settings

package
v0.21.1 Latest Latest
Warning

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

Go to latest
Published: Nov 10, 2026 License: Apache-2.0 Imports: 20 Imported by: 0

Documentation

Overview

Package settings is the one source of every setting: its env name, type, default, help, and whether the UI may change it. The server's validation, the settings page, configuration.md and .env.example all come from Defs.

Index

Constants

View Source
const (
	KeySourceEnv  = "env"
	KeySourceFile = "file"
)

Key sources.

View Source
const Channel = "skael_settings"

Channel is the NOTIFY channel a save signals on.

View Source
const DefaultStoragePath = "./data/skills"

DefaultStoragePath is where a filesystem store lives when STORAGE_PATH is unset and the install started on the filesystem.

View Source
const KeyFile = "master.key"

KeyFile is the name of the generated master key in the data directory.

View Source
const PlaceholderURL = "https://skael.example.com"

PlaceholderURL stands for the instance's public URL in a guide. The settings page replaces it with the real one.

View Source
const PollInterval = 30 * time.Second

PollInterval is how often a replica checks the version when no NOTIFY came.

Variables

View Source
var Defs = []Def{
	{Key: "public_url", Env: "PUBLIC_URL", Kind: KindURL, Section: "general", Label: "Public URL",
		Help:     "The URL people use to reach skael. Sign-in callbacks, email links and GitHub webhooks are built from it.",
		Required: "with SSO, SMTP or GitHub"},

	{Key: "signup.disabled", Env: "DISABLE_SIGNUP", Kind: KindBool, Section: "signup", Label: "Disable sign-up",
		Help:    "Refuses new password, Google and GitHub accounts. OIDC stays open, because the identity provider is the gate.",
		Default: "false"},
	{Key: "signup.allowed_domains", Env: "SIGNUP_ALLOWED_DOMAINS", Kind: KindList, Section: "signup", Label: "Allowed email domains",
		Help: "Comma-separated. A new account from any other domain is refused on every sign-in path."},

	{Key: "oidc.issuer", Env: "OIDC_ISSUER", Kind: KindURL, Section: "signin", Label: "OIDC issuer",
		Help: "The issuer URL of any OpenID Connect provider. The first sign-in creates a member, even with sign-up disabled."},
	{Key: "oidc.client_id", Env: "OIDC_CLIENT_ID", Kind: KindString, Section: "signin", Label: "OIDC client ID",
		Help: "From the application you register at the provider."},
	{Key: "oidc.client_secret", Env: "OIDC_CLIENT_SECRET", Kind: KindSecret, Section: "signin", Label: "OIDC client secret",
		Help: "From the application you register at the provider."},
	{Key: "google.client_id", Env: "GOOGLE_CLIENT_ID", Kind: KindString, Section: "signin", Label: "Google client ID",
		Help: "An OAuth client of type Web application in Google Cloud."},
	{Key: "google.client_secret", Env: "GOOGLE_CLIENT_SECRET", Kind: KindSecret, Section: "signin", Label: "Google client secret",
		Help: "From the same Google OAuth client."},
	{Key: "github.client_id", Env: "GITHUB_CLIENT_ID", Kind: KindString, Section: "signin", Label: "GitHub client ID",
		Help: "A GitHub OAuth App. The GitHub App for git sync and the import token are separate."},
	{Key: "github.client_secret", Env: "GITHUB_CLIENT_SECRET", Kind: KindSecret, Section: "signin", Label: "GitHub client secret",
		Help: "From the same GitHub OAuth App."},

	{Key: "smtp.host", Env: "SMTP_HOST", Kind: KindString, Section: "email", Label: "SMTP host",
		Help: "Turns on password reset and email change. For example smtp.postmarkapp.com or email-smtp.us-east-1.amazonaws.com."},
	{Key: "smtp.port", Env: "SMTP_PORT", Kind: KindInt, Section: "email", Label: "SMTP port",
		Help: "587 uses STARTTLS, 465 uses TLS from the first byte.", Default: "587", Min: num(1), Max: num(65535),
		Suggestions: []SettingsOption{{"587", "587 (STARTTLS)"}, {"465", "465 (TLS)"}, {"2525", "2525 (STARTTLS, when 587 is blocked)"}, {"25", "25 (relay)"}}},
	{Key: "smtp.username", Env: "SMTP_USERNAME", Kind: KindString, Section: "email", Label: "SMTP username",
		Help: "Leave empty for a relay without authentication."},
	{Key: "smtp.password", Env: "SMTP_PASSWORD", Kind: KindSecret, Section: "email", Label: "SMTP password",
		Help: "The SMTP password or the provider's API token."},
	{Key: "smtp.from", Env: "SMTP_FROM", Kind: KindString, Section: "email", Label: "From address",
		Help: "For example Skael <skael@example.com>. The provider must allow this sender."},

	{Key: "github_token", Env: "GITHUB_TOKEN", Kind: KindSecret, Section: "import", Label: "GitHub token",
		Help: "A personal access token for import. It raises GitHub's rate limit from 60 to 5000 requests an hour. Read-only public access is enough."},

	{Key: "external_scan.cmd", Env: "EXTERNAL_SCAN_CMD", Kind: KindString, Section: "scanning", Label: "External scanner command",
		Help: "Runs on every publish and import in addition to the built-in scanner. {dir} is the skill directory, and the command must print SARIF. The tool must be installed on the server.",
		Suggestions: []SettingsOption{
			{"gitleaks dir {dir} --report-format sarif --report-path /dev/stdout --exit-code 0", "gitleaks"},
			{"skill-scanner scan {dir} --format sarif", "Cisco skill-scanner"},
		}},
	{Key: "external_scan.timeout", Env: "EXTERNAL_SCAN_TIMEOUT", Kind: KindDuration, Section: "scanning", Label: "Scanner timeout",
		Help: "A Go duration, for example 60s or 2m.", Default: "60s"},

	{Key: "quality_floor", Env: "QUALITY_FLOOR", Kind: KindFloat, Section: "quality", Label: "Quality floor",
		Help:    "The minimum headline a verified evaluation must reach to release a held version. 0 accepts any verified report with a complete panel and no critical contract violation.",
		Default: "0", Min: num(0), Max: num(100), StrictEnv: true},

	{Key: "event_retention_days", Env: "EVENT_RETENTION_DAYS", Kind: KindInt, Section: "analytics", Label: "Event retention (days)",
		Help: "Activation events older than this are deleted daily. 0 keeps every event.", Default: "90", Min: num(0)},

	{Key: "activation.record_identity", Env: "ACTIVATION_RECORD_IDENTITY", Kind: KindBool, Section: "analytics", Label: "Record who ran a skill",
		Help:    "Stores the person whose key sent each activation. Off stores no person, only the model, the harness and a hash of the machine. Turn it off where a works council or monitoring rule requires it.",
		Default: "true", Scope: ScopeOrg},
	{Key: "activation.member_visibility", Env: "ACTIVATION_MEMBER_VISIBILITY", Kind: KindEnum, Section: "analytics", Label: "What members see",
		Help:    "Owners and admins always see everything recorded, and every member sees their own activations. Aggregates hide any model or harness that fewer than 5 people used.",
		Default: "aggregate", Scope: ScopeOrg,
		Options: []SettingsOption{{"aggregate", "Aggregates only"}, {"person", "Per person"}}},
	{Key: "webhooks.allow_private", Env: "WEBHOOK_ALLOW_PRIVATE", Kind: KindBool, Section: "webhooks", Label: "Allow private addresses",
		Help:    "Lets deliveries reach private addresses, loopback, shared address space and http URLs, for a consumer on your own network. Link-local addresses stay refused.",
		Default: "false"},

	{Key: "telemetry.enabled", Env: "TELEMETRY_ENABLED", Kind: KindBool, Section: "telemetry", Label: "Send the install ping",
		Help:    "Once a day, sends the skael version, the Postgres version, the number of workers and whether evaluation is set up, with a random install id. Never names, skills or email addresses.",
		Default: "true"},

	{Key: "rate_limit.auth", Env: "RATE_LIMIT_AUTH", Kind: KindInt, Section: "rate_limits", Label: "Sign-in requests per minute",
		Help: "For /api/auth/*, per IP address.", Default: "20", Min: num(1)},
	{Key: "rate_limit.events", Env: "RATE_LIMIT_EVENTS", Kind: KindInt, Section: "rate_limits", Label: "Activation events per minute",
		Help: "For POST /api/events, per API key, else per IP address.", Default: "600", Min: num(1)},
	{Key: "rate_limit.read", Env: "RATE_LIMIT_READ", Kind: KindInt, Section: "rate_limits", Label: "Reads per minute",
		Help: "For GET and HEAD, per API key, else per IP address.", Default: "300", Min: num(1)},
	{Key: "rate_limit.write", Env: "RATE_LIMIT_WRITE", Kind: KindInt, Section: "rate_limits", Label: "Writes per minute",
		Help: "For every other method, per API key, else per IP address.", Default: "60", Min: num(1)},
	{Key: "rate_limit.suites", Env: "RATE_LIMIT_SUITES", Kind: KindInt, Section: "rate_limits", Label: "Eval suite uploads per minute",
		Help: "For POST /api/eval/suites, which accepts up to 10 MB a call.", Default: "20", Min: num(1)},

	{Key: "database_url", Env: "DATABASE_URL", Kind: KindSecret, Section: "deployment", Label: "Database URL",
		Help: "The Postgres connection string.", Required: "yes", EnvOnly: true},
	{Key: "listen_addr", Env: "LISTEN_ADDR", Kind: KindString, Section: "deployment", Label: "Listen address",
		Help: "The HTTP listen address.", Default: ":8080", EnvOnly: true},
	{Key: "master_keys", Env: "SKAEL_MASTER_KEYS", Kind: KindSecret, Section: "deployment", Label: "Master keys",
		Help:    "Seals the secrets stored from the UI. Comma-separated id:base64key pairs of 32 bytes; the first seals, every one opens. Unset, the server generates a key file in the data directory.",
		EnvOnly: true},
	{Key: "data_dir", Env: "SKAEL_DATA_DIR", Kind: KindString, Section: "deployment", Label: "Data directory",
		Help:    "Where the server keeps the generated master key. Mount it on a volume. Unset uses the storage directory when STORAGE_PATH is a directory, else ./data.",
		EnvOnly: true},
	{Key: "cookie_secure", Env: "COOKIE_SECURE", Kind: KindBool, Section: "deployment", Label: "Secure cookie",
		Help:    "Marks the session cookie Secure. Needs TLS in front: a browser refuses a Secure cookie over plain HTTP, which breaks sign-in.",
		Default: "false", EnvOnly: true},
	{Key: "trusted_proxies", Env: "TRUSTED_PROXIES", Kind: KindList, Section: "deployment", Label: "Trusted proxies",
		Help:    "CIDR blocks or addresses whose X-Forwarded-For, X-Real-IP and X-Forwarded-Proto are believed. Empty trusts none. Behind a proxy, set it, or every client shares one rate-limit bucket.",
		EnvOnly: true},
	{Key: "cors_origins", Env: "CORS_ORIGINS", Kind: KindList, Section: "deployment", Label: "CORS origins",
		Help: "Comma-separated origins allowed to call the API from a browser.", EnvOnly: true},

	{Key: "storage_path", Env: "STORAGE_PATH", Kind: KindString, Section: "storage", Label: "Storage path",
		Help:    "Where archives live: a local directory, or s3://bucket/prefix. Unset on a new install stores archives in Postgres. An existing install keeps the store it started with.",
		EnvOnly: true},
	{Key: "s3.endpoint", Env: "S3_ENDPOINT", Kind: KindString, Section: "storage", Label: "S3 endpoint",
		Help: "Set for MinIO, R2 or Spaces. No AWS_* fallback.", Default: "s3.amazonaws.com", EnvOnly: true},
	{Key: "s3.region", Env: "S3_REGION", Kind: KindString, Section: "storage", Label: "S3 region",
		Help: "Falls back to AWS_REGION.", Default: "us-east-1", EnvOnly: true},
	{Key: "s3.access_key_id", Env: "S3_ACCESS_KEY_ID", Kind: KindSecret, Section: "storage", Label: "S3 access key ID",
		Help: "Falls back to AWS_ACCESS_KEY_ID. Set both keys or neither; omit both for an IAM role.", EnvOnly: true},
	{Key: "s3.secret_access_key", Env: "S3_SECRET_ACCESS_KEY", Kind: KindSecret, Section: "storage", Label: "S3 secret access key",
		Help: "Falls back to AWS_SECRET_ACCESS_KEY.", EnvOnly: true},
	{Key: "s3.use_path_style", Env: "S3_USE_PATH_STYLE", Kind: KindBool, Section: "storage", Label: "Path-style addressing",
		Help: "true for MinIO.", Default: "false", EnvOnly: true},
	{Key: "s3.use_ssl", Env: "S3_USE_SSL", Kind: KindBool, Section: "storage", Label: "Use TLS",
		Help: "TLS to the S3 endpoint.", Default: "true", EnvOnly: true},

	{Key: "db.max_conns", Env: "DB_MAX_CONNS", Kind: KindInt, Section: "database", Label: "Maximum connections",
		Help: "The most connections in the pool.", Default: "25", Min: num(1), EnvOnly: true},
	{Key: "db.min_conns", Env: "DB_MIN_CONNS", Kind: KindInt, Section: "database", Label: "Minimum connections",
		Help: "Idle connections the pool keeps.", Default: "5", Min: num(0), EnvOnly: true},
	{Key: "db.max_conn_lifetime", Env: "DB_MAX_CONN_LIFETIME", Kind: KindDuration, Section: "database", Label: "Connection lifetime",
		Help: "A connection closes after this long.", Default: "1h", EnvOnly: true},
	{Key: "db.max_conn_idle_time", Env: "DB_MAX_CONN_IDLE_TIME", Kind: KindDuration, Section: "database", Label: "Connection idle time",
		Help: "An idle connection closes after this long.", Default: "30m", EnvOnly: true},
	{Key: "db.health_check_period", Env: "DB_HEALTH_CHECK_PERIOD", Kind: KindDuration, Section: "database", Label: "Health check period",
		Help: "How often the pool checks its connections.", Default: "1m", EnvOnly: true},

	{Key: "log.level", Env: "LOG_LEVEL", Kind: KindEnum, Section: "logging", Label: "Log level",
		Help: "The lowest level written.", Default: "info", EnvOnly: true,
		Options: []SettingsOption{{"trace", "trace"}, {"debug", "debug"}, {"info", "info"}, {"warn", "warn"}, {"error", "error"}, {"fatal", "fatal"}, {"panic", "panic"}}},
	{Key: "log.format", Env: "LOG_FORMAT", Kind: KindEnum, Section: "logging", Label: "Log format",
		Help: "pretty writes colored console lines for development. Unset writes JSON.", EnvOnly: true,
		Options: []SettingsOption{{"pretty", "pretty"}, {"json", "json"}}},
	{Key: "log.pretty", Env: "LOG_PRETTY", Kind: KindBool, Section: "logging", Label: "Pretty logs",
		Help: "The same as LOG_FORMAT=pretty.", Default: "false", EnvOnly: true},
	{Key: "metrics.enabled", Env: "METRICS_ENABLED", Kind: KindBool, Section: "logging", Label: "Prometheus metrics",
		Help: "false removes the /metrics endpoint.", Default: "true", EnvOnly: true},

	{Key: "worker.endpoint", Env: "SKAEL_ENDPOINT", Kind: KindURL, Section: "worker", Label: "Server URL",
		Help: "The skael server the worker claims jobs from.", Required: "yes", EnvOnly: true, Binary: BinaryWorker},
	{Key: "worker.api_key", Env: "SKAEL_API_KEY", Kind: KindSecret, Section: "worker", Label: "API key",
		Help: "A key with permission to claim eval jobs. Settings → Workers → Add a worker creates one.", Required: "yes", EnvOnly: true, Binary: BinaryWorker},
	{Key: "worker.id", Env: "WORKER_ID", Kind: KindString, Section: "worker", Label: "Worker ID",
		Help: "Names this worker in leases and on the Workers page.", Default: "{hostname}-{pid}", EnvOnly: true, Binary: BinaryWorker},
	{Key: "worker.lease", Env: "WORKER_LEASE", Kind: KindDuration, Section: "worker", Label: "Lease",
		Help: "How long a claimed job is held before another worker may take it.", Default: "5m", EnvOnly: true, Binary: BinaryWorker},
	{Key: "worker.poll", Env: "WORKER_POLL", Kind: KindDuration, Section: "worker", Label: "Poll interval",
		Help: "How often an idle worker asks for a job and checks in.", Default: "15s", EnvOnly: true, Binary: BinaryWorker},
	{Key: "worker.work_root", Env: "WORKER_WORK_ROOT", Kind: KindString, Section: "worker", Label: "Work root",
		Help: "Where eval workspaces are built. Never mounted into a sandbox.", Default: "the OS temp directory", EnvOnly: true, Binary: BinaryWorker},
	{Key: "worker.run_root", Env: "WORKER_RUN_ROOT", Kind: KindString, Section: "worker", Label: "Run root",
		Help:     "Where session workspaces are created. They are bind-mounted into sandboxes, so in a container the path must be the same on the host. Required when containerized.",
		Required: "in a container", Default: "the OS temp directory", EnvOnly: true, Binary: BinaryWorker},
	{Key: "worker.concurrency", Env: "WORKER_CONCURRENCY", Kind: KindInt, Section: "worker", Label: "Session concurrency",
		Help: "Sandbox sessions at once within one eval.", Default: "1", Min: num(1), EnvOnly: true, Binary: BinaryWorker},
	{Key: "worker.grade_concurrency", Env: "WORKER_GRADE_CONCURRENCY", Kind: KindInt, Section: "worker", Label: "Judge concurrency",
		Help: "Judge calls at once. A judge call is bound by the account's rate limit, not by the host.", Default: "8", Min: num(1), EnvOnly: true, Binary: BinaryWorker},
	{Key: "worker.contest_parallel", Env: "WORKER_CONTEST_PARALLEL", Kind: KindInt, Section: "worker", Label: "Contest candidates at once",
		Help: "Each candidate runs its own sessions, so this multiplies the sandbox load.", Default: "2", Min: num(1), EnvOnly: true, Binary: BinaryWorker},

	{Key: "sandbox.driver", Env: "SANDBOX_DRIVER", Kind: KindEnum, Section: "sandbox", Label: "Sandbox driver",
		Help: "Where an eval session runs.", Default: "docker", EnvOnly: true, Binary: BinaryWorker,
		Options: []SettingsOption{{"docker", "docker (sibling containers on the local daemon)"}, {"kubernetes", "kubernetes (a pod through the cluster API)"}, {"northflank", "northflank (a service in a Northflank project)"}}},

	{Key: "sandbox.k8s.namespace", Env: "SANDBOX_K8S_NAMESPACE", Kind: KindString, Section: "sandbox_k8s", Label: "Namespace",
		Help: "The namespace session pods run in. It must hold nothing but session pods.", Required: "with kubernetes", EnvOnly: true, Binary: BinaryWorker},
	{Key: "sandbox.k8s.image", Env: "SANDBOX_K8S_IMAGE", Kind: KindString, Section: "sandbox_k8s", Label: "Image",
		Help: "The image a session pod runs. It must already be in a registry.", Default: "the published whetstone base image", EnvOnly: true, Binary: BinaryWorker},
	{Key: "sandbox.k8s.pull_secret", Env: "SANDBOX_K8S_PULL_SECRET", Kind: KindString, Section: "sandbox_k8s", Label: "Pull secret",
		Help: "An image pull secret in the namespace, for a private registry.", EnvOnly: true, Binary: BinaryWorker},
	{Key: "sandbox.k8s.runtime_class", Env: "SANDBOX_K8S_RUNTIME_CLASS", Kind: KindString, Section: "sandbox_k8s", Label: "Runtime class",
		Help: "runtimeClassName for a hardware-isolated runtime, for example kata.", EnvOnly: true, Binary: BinaryWorker},
	{Key: "sandbox.k8s.tolerations", Env: "SANDBOX_K8S_TOLERATIONS", Kind: KindString, Section: "sandbox_k8s", Label: "Tolerations",
		Help: `Tolerations for session and proxy pods, as a JSON list in the Kubernetes shape, for example [{"key":"dedicated","operator":"Equal","value":"evals","effect":"NoSchedule"}].`, EnvOnly: true, Binary: BinaryWorker},
	{Key: "sandbox.k8s.node_selector", Env: "SANDBOX_K8S_NODE_SELECTOR", Kind: KindString, Section: "sandbox_k8s", Label: "Node selector",
		Help: `Node labels session and proxy pods must match, as a JSON object, for example {"agentpool":"evals"}.`, EnvOnly: true, Binary: BinaryWorker},
	{Key: "sandbox.k8s.hardware_isolated", Env: "SANDBOX_K8S_HARDWARE_ISOLATED", Kind: KindString, Section: "sandbox_k8s", Label: "Hardware isolated",
		Help: "Asserts the runtime is hardware-isolated. " + trueOnly, EnvOnly: true, Binary: BinaryWorker},
	{Key: "sandbox.k8s.network_policy", Env: "SANDBOX_K8S_NETWORK_POLICY", Kind: KindString, Section: "sandbox_k8s", Label: "Network policy enforced",
		Help: "Asserts the cluster's CNI enforces NetworkPolicy. Check it with whetstone doctor --check-egress. " + trueOnly, EnvOnly: true, Binary: BinaryWorker},

	{Key: "sandbox.nf.token", Env: "SANDBOX_NF_TOKEN", Kind: KindSecret, Section: "sandbox_nf", Label: "API token",
		Help: "The Northflank API token.", Required: "with northflank", EnvOnly: true, Binary: BinaryWorker},
	{Key: "sandbox.nf.project", Env: "SANDBOX_NF_PROJECT", Kind: KindString, Section: "sandbox_nf", Label: "Project",
		Help: "Give sessions a project of their own: the driver deletes every service with its owner label.", Required: "with northflank", EnvOnly: true, Binary: BinaryWorker},
	{Key: "sandbox.nf.image", Env: "SANDBOX_NF_IMAGE", Kind: KindString, Section: "sandbox_nf", Label: "Image",
		Help: "The base image a session runs.", Default: "the published whetstone base image", EnvOnly: true, Binary: BinaryWorker},
	{Key: "sandbox.nf.registry_credential", Env: "SANDBOX_NF_REGISTRY_CREDENTIAL", Kind: KindString, Section: "sandbox_nf", Label: "Registry credential",
		Help: "A saved Northflank credential, for a private registry.", EnvOnly: true, Binary: BinaryWorker},
	{Key: "sandbox.nf.plan", Env: "SANDBOX_NF_PLAN", Kind: KindString, Section: "sandbox_nf", Label: "Plan",
		Help: "The resource plan of each session service.", Default: "nf-compute-20", EnvOnly: true, Binary: BinaryWorker},
	{Key: "sandbox.nf.cli", Env: "SANDBOX_NF_CLI", Kind: KindString, Section: "sandbox_nf", Label: "CLI path",
		Help: "The CLI the driver uses for workspace transfer.", Default: "northflank", EnvOnly: true, Binary: BinaryWorker},
	{Key: "sandbox.nf.allowed_domains", Env: "SANDBOX_NF_ALLOWED_DOMAINS", Kind: KindList, Section: "sandbox_nf", Label: "Allowed domains",
		Help: "The domains your project's egress policy permits.", Required: "for restricted runs", EnvOnly: true, Binary: BinaryWorker},
	{Key: "sandbox.nf.network_policy", Env: "SANDBOX_NF_NETWORK_POLICY", Kind: KindString, Section: "sandbox_nf", Label: "Network policy enforced",
		Help: "Asserts the project's egress policy enforces the allowed domains. " + trueOnly, EnvOnly: true, Binary: BinaryWorker},
	{Key: "sandbox.nf.hardware_isolated", Env: "SANDBOX_NF_HARDWARE_ISOLATED", Kind: KindString, Section: "sandbox_nf", Label: "Hardware isolated",
		Help: "Asserts the plan is hardware-isolated. " + trueOnly, EnvOnly: true, Binary: BinaryWorker},
}

Defs in page and docs order within each section.

View Source
var ErrNoKeys = errors.New("no master key can seal a secret; use an env: or file: reference")

ErrNoKeys means a secret literal cannot be sealed.

View Source
var Sections = []Section{
	{ID: "general", Title: "General", Binary: BinaryServer},
	{ID: "signup", Title: "Sign-up", Binary: BinaryServer},
	{ID: "signin", Title: "Sign-in providers", Binary: BinaryServer, Test: "oidc"},
	{ID: "email", Title: "Email", Binary: BinaryServer, Test: "smtp"},
	{ID: "import", Title: "Import", Binary: BinaryServer, Test: "github_token"},
	{ID: "scanning", Title: "Security scanning", Binary: BinaryServer, Test: "scanner"},
	{ID: "quality", Title: "Quality gate", Binary: BinaryServer},
	{ID: "analytics", Title: "Analytics", Binary: BinaryServer},
	{ID: "webhooks", Title: "Webhooks", Binary: BinaryServer},
	{ID: "telemetry", Title: "Install ping", Binary: BinaryServer},
	{ID: "rate_limits", Title: "Rate limits", Binary: BinaryServer},
	{ID: "deployment", Title: "Deployment", Binary: BinaryServer},
	{ID: "storage", Title: "Storage", Binary: BinaryServer},
	{ID: "database", Title: "Database pool", Binary: BinaryServer},
	{ID: "logging", Title: "Logging and metrics", Binary: BinaryServer},
	{ID: "worker", Title: "Worker", Binary: BinaryWorker},
	{ID: "sandbox", Title: "Sandbox driver", Binary: BinaryWorker},
	{ID: "sandbox_k8s", Title: "Kubernetes driver", Binary: BinaryWorker},
	{ID: "sandbox_nf", Title: "Northflank driver", Binary: BinaryWorker},
}

Sections in page and docs order.

Functions

func Check

func Check(changes []SettingsChange, env EnvFunc) error

Check validates changes against the registry and the environment.

func ConfigDocs

func ConfigDocs() string

ConfigDocs renders configuration.md.

func DataDir

func DataDir(snap *Snapshot) string

DataDir is SKAEL_DATA_DIR, else a local STORAGE_PATH, else ./data.

func EnvExample

func EnvExample() string

EnvExample renders .env.example.

func Guide

func Guide(section string) string

Guide returns the section's guide in Markdown, or "".

func IsReference added in v0.20.0

func IsReference(v string) bool

IsReference reports whether v is an env: or file: reference rather than a secret value.

func RegisterKeyRoutes

func RegisterKeyRoutes(api huma.API, keys *KeyService)

RegisterKeyRoutes serves the master key's state and the recovery action.

func RegisterRoutes

func RegisterRoutes(api huma.API, live *Live, archiveStore string)

RegisterRoutes serves the settings page to owners and admins. archiveStore names the archive store in effect.

func RegisterTestRoute

func RegisterTestRoute(api huma.API, live *Live, testers map[string]Tester)

RegisterTestRoute serves the test action of each section that has one.

func ResolveReference added in v0.20.0

func ResolveReference(ref string) (string, error)

ResolveReference reads the secret an env:NAME or file:/path reference names, from this process's environment and filesystem.

func ValidReference

func ValidReference(ref string) error

ValidReference reports whether ref is env:NAME or file:/absolute/path.

Types

type Binary

type Binary string

Binary is the program that reads a setting.

const (
	BinaryServer Binary = "server"
	BinaryWorker Binary = "worker"
)

type Def

type Def struct {
	Key     string
	Env     string
	Kind    Kind
	Section string
	Label   string
	// Help is the one line under the field. Doc, when set, is the longer
	// description in configuration.md.
	Help     string
	Doc      string
	Default  string
	Required string
	// Options are the only values of an enum. Suggestions are presets for a
	// free value, such as a scanner command.
	Options     []SettingsOption
	Suggestions []SettingsOption
	Min, Max    *float64
	// EnvOnly settings are read before the database or would lock the admin
	// out; the UI shows them read-only.
	EnvOnly bool
	// StrictEnv refuses to start on an invalid env value instead of using
	// the default.
	StrictEnv bool
	Scope     Scope
	Binary    Binary
}

Def is one setting.

func Lookup

func Lookup(key string) *Def

Lookup returns the definition of key, or nil.

func (*Def) Validate

func (d *Def) Validate(raw string) error

Validate reports why raw is not a valid value of d. An empty value is valid: it means unset.

type EnvFunc

type EnvFunc func(string) (string, bool)

EnvFunc is os.LookupEnv, injectable for tests.

type ErrInvalid

type ErrInvalid struct{ Msg string }

ErrInvalid is a change the registry refuses. Its message is for the user.

func (*ErrInvalid) Error

func (e *ErrInvalid) Error() string

type KeyService

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

KeyService checks the master key at start and recovers from a lost one.

func NewKeyService

func NewKeyService(pool *pgxpool.Pool, key *MasterKey, live *Live, sources ...SealedSource) *KeyService

NewKeyService returns the service. sources are the other sealed stores.

func (*KeyService) EnsureCanary

func (k *KeyService) EnsureCanary(ctx context.Context) error

EnsureCanary seals a canary under the active key if it has none.

func (*KeyService) Reset

func (k *KeyService) Reset(ctx context.Context, actor string) error

Reset discards every secret that no longer opens and every canary of a lost key, and seals a canary under the active key.

func (*KeyService) Status

func (k *KeyService) Status(ctx context.Context) (KeyStatus, error)

Status checks every canary and every sealed secret.

type KeyStatus

type KeyStatus struct {
	Source      string       `json:"source"`
	Path        string       `json:"path,omitempty"`
	KeyID       string       `json:"key_id"`
	Fingerprint string       `json:"fingerprint"`
	Missing     []string     `json:"missing"`
	Unreadable  []Unreadable `json:"unreadable"`
}

KeyStatus is the master key's state.

func (KeyStatus) Degraded

func (s KeyStatus) Degraded() bool

Degraded reports whether a key is lost or a secret no longer opens.

type Keys

type Keys interface {
	Opener
	Seal(plain []byte, aad string) (string, error)
	Enabled() bool
}

Keys seals and opens secrets. platform.Keyring implements it.

type Kind

type Kind string

Kind is how a value is parsed and edited.

const (
	KindString   Kind = "string"
	KindURL      Kind = "url"
	KindBool     Kind = "bool"
	KindInt      Kind = "int"
	KindFloat    Kind = "float"
	KindDuration Kind = "duration"
	KindEnum     Kind = "enum"
	KindList     Kind = "list"
	KindSecret   Kind = "secret"
)

type Live

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

Live holds the current snapshot. A save on any replica reaches every replica through NOTIFY, and the version poll catches a missed notification.

func NewLive

func NewLive(store *Store, env EnvFunc, keys Opener) *Live

NewLive returns a Live over store. Call Load before Get.

func Static

func Static(env map[string]string) *Live

Static returns a Live with no store, resolved from env alone. It serves spec generation and tests.

func (*Live) Env

func (l *Live) Env() EnvFunc

Env returns the environment the snapshot resolves against.

func (*Live) Get

func (l *Live) Get() *Snapshot

Get returns the current snapshot.

func (*Live) Load

func (l *Live) Load(ctx context.Context) error

Load reads the store and publishes a new snapshot.

func (*Live) OnChange

func (l *Live) OnChange(fn func(*Snapshot))

OnChange registers fn to run after each new snapshot.

func (*Live) Store

func (l *Live) Store() *Store

Store returns the store, or nil for a static Live.

func (*Live) Watch

func (l *Live) Watch(ctx context.Context)

Watch reloads on every NOTIFY and every PollInterval until ctx ends.

type MasterKey

type MasterKey struct {
	Keys      *platform.Keyring
	Source    string
	Path      string
	Generated bool
}

MasterKey is the keyring in effect and where it came from.

func EnsureMasterKey

func EnsureMasterKey(cfg *platform.Config, snap *Snapshot) (*MasterKey, error)

EnsureMasterKey returns SKAEL_MASTER_KEYS when set. Otherwise it reads the key file in the data directory, and writes a new key there when none exists.

type Opener

type Opener interface {
	Open(value, aad string) ([]byte, error)
}

Opener opens a sealed value. platform.Keyring implements it.

type Resolved

type Resolved struct {
	Def    *Def
	Value  string
	Source Source
	// Reference is the env: or file: reference a secret was read from.
	Reference string
	// Problem says why a configured value is not in effect, such as an
	// invalid env value or a reference that names nothing.
	Problem string
	// Unreadable is a sealed secret that no master key opens.
	Unreadable bool
	UpdatedBy  string
	UpdatedAt  time.Time
}

Resolved is one setting's effective value and where it came from.

type Scope

type Scope string

Scope is who owns a setting. On a self-hosted install the one org is the instance.

const (
	ScopeInstance Scope = "instance"
	ScopeOrg      Scope = "org"
)

type SealedSource

type SealedSource interface {
	Unreadable(ctx context.Context) ([]Unreadable, error)
	Discard(ctx context.Context, actor string) error
}

SealedSource is a feature that stores sealed secrets outside the settings table.

type Section

type Section struct {
	ID     string
	Title  string
	Binary Binary
	// Test names the section's test action, if it has one.
	Test string
}

Section groups settings on the page and in the docs.

func SectionByID

func SectionByID(id string) *Section

SectionByID returns the section, or nil.

type SettingsBody

type SettingsBody struct {
	Version  int64             `json:"version"`
	Sections []SettingsSection `json:"sections"`
	// ArchiveStore is the store in effect: a directory, an s3:// URL, or postgres.
	ArchiveStore string `json:"archive_store"`
}

func Body

func Body(snap *Snapshot) SettingsBody

Body is the whole settings page for snap.

type SettingsChange

type SettingsChange struct {
	Key       string  `json:"key"`
	Value     *string `json:"value,omitempty"`
	Reference *string `json:"reference,omitempty"`
	Clear     bool    `json:"clear,omitempty"`
}

SettingsChange is one edit. Exactly one of Value, Reference and Clear applies.

type SettingsField

type SettingsField struct {
	Key         string           `json:"key"`
	Env         string           `json:"env"`
	Kind        Kind             `json:"kind"`
	Label       string           `json:"label"`
	Help        string           `json:"help"`
	Default     string           `json:"default"`
	Options     []SettingsOption `json:"options"`
	Suggestions []SettingsOption `json:"suggestions"`
	Min         *float64         `json:"min,omitempty"`
	Max         *float64         `json:"max,omitempty"`
	EnvOnly     bool             `json:"env_only"`
	Scope       Scope            `json:"scope"`
	Source      Source           `json:"source"`
	LockedBy    string           `json:"locked_by,omitempty"`
	Value       string           `json:"value"`
	IsSet       bool             `json:"is_set"`
	Reference   string           `json:"reference,omitempty"`
	Problem     string           `json:"problem,omitempty"`
	UpdatedBy   string           `json:"updated_by,omitempty"`
	UpdatedAt   time.Time        `json:"updated_at,omitzero"`
}

func Field

func Field(r *Resolved) SettingsField

Field is the wire form of one resolved setting. A secret never leaves the server: only whether it is set and its reference do.

type SettingsOption

type SettingsOption struct {
	Value string `json:"value"`
	Label string `json:"label"`
}

SettingsOption is one known value with the label the UI shows for it.

type SettingsSection

type SettingsSection struct {
	ID     string          `json:"id"`
	Title  string          `json:"title"`
	Binary Binary          `json:"binary"`
	Test   string          `json:"test,omitempty"`
	Guide  string          `json:"guide"`
	Fields []SettingsField `json:"fields"`
}

type SettingsUpdateBody

type SettingsUpdateBody struct {
	Changes []SettingsChange `json:"changes" minItems:"1" maxItems:"100"`
}

type Snapshot

type Snapshot struct {
	Version int64
	// contains filtered or unexported fields
}

Snapshot is every setting at one version. It never changes once built.

func LoadConfig

func LoadConfig(env EnvFunc) (*platform.Config, *Snapshot, error)

LoadConfig reads the env-only settings the server needs before its database. A StrictEnv setting with an invalid value is a start error.

func Resolve

func Resolve(version int64, env EnvFunc, stored map[string]Stored, keys Opener) *Snapshot

Resolve builds a snapshot. An env var wins over a stored value and locks it.

func (*Snapshot) Bool

func (s *Snapshot) Bool(key string) bool

Bool returns key as a bool.

func (*Snapshot) Duration

func (s *Snapshot) Duration(key string) time.Duration

Duration returns key as a duration, or 0.

func (*Snapshot) Float

func (s *Snapshot) Float(key string) float64

Float returns key as a float, or 0.

func (*Snapshot) Get

func (s *Snapshot) Get(key string) *Resolved

Get returns the resolved setting, or nil for an unknown key.

func (*Snapshot) Int

func (s *Snapshot) Int(key string) int

Int returns key as an int, or 0.

func (*Snapshot) List

func (s *Snapshot) List(key string) []string

List returns key split on commas, trimmed, without empty items.

func (*Snapshot) Problems

func (s *Snapshot) Problems() []*Resolved

Problems returns every setting whose configured value is not in effect.

func (*Snapshot) String

func (s *Snapshot) String(key string) string

String returns the effective value of key.

type Source

type Source string

Source is where a resolved value came from.

const (
	SourceDefault Source = "default"
	SourceUI      Source = "ui"
	SourceEnv     Source = "env"
)

type Store

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

Store reads and writes the settings table.

func NewStore

func NewStore(pool *pgxpool.Pool, keys Keys) *Store

NewStore returns a store that seals secrets with keys.

func (*Store) Apply

func (s *Store) Apply(ctx context.Context, actor string, changes []SettingsChange, env EnvFunc) error

Apply writes changes in one transaction, records each in the audit log, bumps the version and notifies every replica.

func (*Store) Load

func (s *Store) Load(ctx context.Context) (map[string]Stored, int64, error)

Load returns every stored row and the version they belong to.

func (*Store) Version

func (s *Store) Version(ctx context.Context) (int64, error)

Version returns the current settings version.

type Stored

type Stored struct {
	Value     string
	Sealed    string
	UpdatedBy string
	UpdatedAt time.Time
}

Stored is one row of the settings table. A secret keeps either a reference in Value or a sealed literal in Sealed.

type TestResult

type TestResult struct {
	OK      bool   `json:"ok"`
	Message string `json:"message"`
}

TestResult is what a section's test action found.

type Tester

type Tester func(ctx context.Context, snap *Snapshot, actorEmail string) TestResult

Tester runs one section's test against the current settings.

type Unreadable

type Unreadable struct {
	Name string `json:"name"`
	// Where says where to issue the secret again.
	Where string `json:"where"`
}

Unreadable is one stored secret that no longer opens.

Jump to

Keyboard shortcuts

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