Documentation
¶
Overview ¶
Package setup holds the onboarding and configuration services: the documents the local API returns and the pure reads that build the same documents from state files when no server is running. Presentations (CLI, TUI, web) render these documents; they never compute next actions, order or validation themselves.
See decision 0006 and spec/features/configuration-parity#REQ:json-equals-api.
Index ¶
- Constants
- Variables
- func FallbackAddress(port int) string
- func NormalizeOrigins(origins []string) []string
- func ParseOrigins(value string) ([]string, *envelope.Error)
- func ParsePort(value, source string) (int, *envelope.Error)
- func PrimaryAddress(port int) string
- func ResolvePort(flagPort int, getenv paths.Getenv, config Config) (port int, explicit bool, err *envelope.Error)
- func UnknownConfigKey(key string) *envelope.Error
- func ValidPort(port int) bool
- type Badge
- type Config
- type ConfigChange
- type ConfigDocument
- type CopyRef
- type HomeDocument
- type HomeOption
- type Server
- type ServerConfig
- type ServerDocument
- type Status
Constants ¶
const ( KeyServerPort = "server.port" // KeyServerCORS lists the browser app origins allowed to call /v1/… and // /token with bearer tokens (capability 25, CLI only: exception E7). KeyServerCORS = "server.cors" )
Configuration keys. Telemetry and the global context follow in later increments.
const ( MinPort = 1 MaxPort = 65535 )
MinPort and MaxPort bound every port ovdb accepts, from a flag, an environment variable, `ovdb config set server.port` or the TUI's own pre-submit check — one place so the range cannot drift between them.
const ( StateRunning = "running" StateNotRunning = "not_running" StateStopping = "stopping" // only in the shutdown response )
Server states.
const ConfigFile = "config.yaml"
ConfigFile is the configuration file in OVDB home.
const EnvPort = "OVDB_PORT"
EnvPort overrides the configured port for one shell.
Variables ¶
var Keys = []string{KeyServerPort, KeyServerCORS}
Keys lists the supported keys, for usage errors.
Functions ¶
func FallbackAddress ¶
FallbackAddress is the address that works where *.localhost does not.
func NormalizeOrigins ¶ added in v0.9.0
NormalizeOrigins cleans origins read from a hand-edited config.yaml the way ParseOrigins cleans CLI input, dropping entries that are not origins (and a trailing slash, which browsers never send).
func ParseOrigins ¶ added in v0.9.0
ParseOrigins parses a comma-separated list of browser origins (scheme://host[:port], http or https, nothing after the host). An empty value clears the list.
func ParsePort ¶
ParsePort validates a port number given through source (a flag, variable or key name).
func PrimaryAddress ¶
PrimaryAddress is the address people open.
func ResolvePort ¶
func ResolvePort(flagPort int, getenv paths.Getenv, config Config) (port int, explicit bool, err *envelope.Error)
ResolvePort applies --port > OVDB_PORT > server.port > 6832 (REQ:port-precedence). explicit is true for the flag and the variable, which must match a running server's port.
func UnknownConfigKey ¶
UnknownConfigKey is invalid_argument naming the supported keys.
Types ¶
type Badge ¶ added in v0.9.0
type Badge struct {
Tone string `json:"tone"` // ok, warn, neutral
LabelKey string `json:"label_key"`
}
Badge is a server state as presentations show it: a tone and a copy key.
func StateBadge ¶ added in v0.9.0
StateBadge maps a server state to its badge.
type Config ¶
type Config struct {
Server ServerConfig `yaml:"server,omitempty" json:"server"`
}
Config is config.yaml. Unset values are omitted and mean "default".
func LoadConfig ¶
LoadConfig reads config.yaml; a missing file is the empty configuration.
type ConfigChange ¶
ConfigChange is the body of PUT /api/local/v1/config.
type ConfigDocument ¶
type ConfigDocument struct {
Schema int `json:"schema"`
Config Config `json:"config"`
// Changed is set on a change's result: false when the value was
// already the one asked for, so nothing needs a restart.
Changed *bool `json:"changed,omitempty"`
Next []envelope.Next `json:"next"`
}
ConfigDocument is the body of GET/PUT /api/local/v1/config and the --json output of `ovdb config get|set`.
func ApplyConfigChange ¶
func ApplyConfigChange(dirs paths.Dirs, change ConfigChange, serverRunning bool) (ConfigDocument, error)
ApplyConfigChange validates change, writes config.yaml owner-only and returns the resulting document. The caller must be the home's single writer: the running server, or a client holding home.lock (serverRunning false).
func NewConfigDocument ¶
func NewConfigDocument(config Config, changedWhileRunning bool) ConfigDocument
NewConfigDocument wraps config. A change made while the server runs gets the restart that applies it as its next action.
type CopyRef ¶ added in v0.9.0
CopyRef is copy a presentation renders: a catalogue key and its params.
type HomeDocument ¶ added in v0.9.0
type HomeDocument struct {
Schema int `json:"schema"`
StatusLine []CopyRef `json:"status_line"`
QuestionKey string `json:"question_key"`
Options []HomeOption `json:"options"`
}
HomeDocument is the body of GET /api/local/v1/home: the status line and the implemented Home options in the founder's order (first-run-onboarding#REQ:home-menu-options, REQ:home-status-line). The TUI and the web console both render it, so neither builds the menu.
func NewHome ¶ added in v0.9.0
func NewHome(server Server) HomeDocument
NewHome builds Home for server. Options appear here only once they are implemented; later increments insert theirs in the founder's order.
type HomeOption ¶ added in v0.9.0
type HomeOption struct {
ID string `json:"id"`
Group string `json:"group"` // primary, secondary
LabelKey string `json:"label_key"`
WebLabelKey string `json:"web_label_key,omitempty"`
DescriptionKey string `json:"description_key,omitempty"`
Badge *Badge `json:"badge,omitempty"`
}
HomeOption is one Home menu option. LabelKey is the terminal wording; WebLabelKey, when set, replaces it in the web console, which cannot start the server that serves it (parity E1).
type Server ¶
type Server struct {
State string `json:"state"`
Address string `json:"address"`
FallbackAddress string `json:"fallback_address"`
Port int `json:"port"`
Version string `json:"version,omitempty"`
PID int `json:"pid,omitempty"`
StartedAt *time.Time `json:"started_at,omitempty"`
Log string `json:"log"`
}
Server describes the local OVDB server in status and server documents. It carries no uptime: a start time keeps two reads of the same server byte-identical, and presentations format the uptime from it.
func RunningServer ¶
RunningServer describes the server recorded in record.
type ServerConfig ¶
type ServerConfig struct {
Port int `yaml:"port,omitempty" json:"port,omitempty"`
CORS []string `yaml:"cors,omitempty" json:"cors,omitempty"`
}
ServerConfig is the server section of config.yaml.
type ServerDocument ¶
type ServerDocument struct {
Schema int `json:"schema"`
Server Server `json:"server"`
Next []envelope.Next `json:"next"`
}
ServerDocument is the body of GET /api/local/v1/server and the --json output of `ovdb server start|stop|restart|status`. Next holds the commands that change the server's state, so every presentation shows the same ones (the web console cannot run them itself: parity E1 and E2).
func NewServerDocument ¶
func NewServerDocument(server Server) ServerDocument
NewServerDocument wraps server in its document.
type Status ¶
type Status struct {
Schema int `json:"schema"`
Version string `json:"version"`
Locations paths.Dirs `json:"locations"`
Server Server `json:"server"`
Next []envelope.Next `json:"next"`
}
Status is the body of GET /api/local/v1/status and of `ovdb status --json` (first-run-onboarding#REQ:status-command). Later increments add databases, context, demo, skills and telemetry as they are implemented.
Source Files