conf

Documentation

Overview

Package conf loads the user's TOML configuration file — endpoint overrides and named profiles — from the config directory. It is deliberately free of any dependency on the client package: callers pass their built-in defaults into Resolve, so conf never needs to know the production hosts.

Absent a config file, everything falls back to those defaults, so the CLI is zero-config out of the box. A profile lets a user point spur at a non-prod environment without touching code.

Index

• func DefaultPath() (string, error)
• func LoosePermissionsWarning(path string, c Config) string
• type Config
  • func Load(path string) (Config, error)
  • func LoadDefault() (Config, error)
  • func (c Config) Resolve(profile string, defaults Resolved) (Resolved, error)
• type EndpointOverrides
• type Profile
• type Resolved

Functions

func DefaultPath

func DefaultPath() (string, error)

DefaultPath returns the path to the default config file: $XDG_CONFIG_HOME/spur/config.toml, falling back to ~/.config/spur/config.toml.

func LoosePermissionsWarning

func LoosePermissionsWarning(path string, c Config) string

LoosePermissionsWarning returns a warning message when the config file at path stores an API token (top-level or in any profile) but is readable or writable by other users, or "" when there is nothing to warn about. The token is a credential: like ssh and gh, the CLI keeps working but tells the user to tighten the mode. File modes are not meaningful on Windows, so the check is skipped there.

Types

type Config

type Config struct {
	// Token is the API token used when neither SPUR_TOKEN nor a selected
	// profile supplies one. It is the config-file tier the token resolver
	// consults between the environment variable and the OS keychain.
	Token string `toml:"token"`
	// Endpoints are the top-level overrides, applied over the built-in
	// defaults for every invocation regardless of profile.
	Endpoints EndpointOverrides `toml:"endpoints"`
	// Profiles are named override sets. A selected profile's endpoints are
	// applied on top of the top-level ones.
	Profiles map[string]Profile `toml:"profiles"`
}

Config is the on-disk configuration, parsed from TOML.

func Load

func Load(path string) (Config, error)

Load reads and parses the TOML config at path. A missing or unreadable file is an error: use Load for an explicitly-requested path (--config), where a typo should fail loudly rather than silently fall through to defaults.

func LoadDefault

func LoadDefault() (Config, error)

LoadDefault loads from DefaultPath, tolerating a missing file by returning a zero Config. This is the zero-config path: no file means production defaults.

func (Config) Resolve

func (c Config) Resolve(profile string, defaults Resolved) (Resolved, error)

Resolve merges the config over defaults and returns the effective settings.

Precedence, lowest to highest: defaults → top-level (token + [endpoints]) → the selected profile's (token + [endpoints]). Empty override fields are skipped, so empty or absent sections change nothing. An empty profile name selects no profile; an unknown profile name is an error that lists the available profiles.

type EndpointOverrides

type EndpointOverrides struct {
	// API overrides the base URL of the Spur Context API.
	API string `toml:"api"`
	// Feeds overrides the base URL of the Spur Data Feeds API.
	Feeds string `toml:"feeds"`
	// Exports overrides the base URL of the Spur Exports API.
	Exports string `toml:"exports"`
}

EndpointOverrides holds base-URL overrides. A zero-value field means "leave the incoming default untouched", so empty or missing sections are no-ops.

type Profile

type Profile struct {
	// Token overrides the top-level token when this profile is selected, so a
	// user can keep a distinct token per environment.
	Token     string            `toml:"token"`
	Endpoints EndpointOverrides `toml:"endpoints"`
}

Profile is a named set of overrides selected with --profile.

type Resolved

type Resolved struct {
	// BaseURL is the base the shared client should talk to.
	BaseURL string
	// FeedsBaseURL is the base the shared client should use for feed requests.
	FeedsBaseURL string
	// ExportsBaseURL is the base the shared client should use for export
	// requests.
	ExportsBaseURL string
	// Token is the config-file API token, empty when the config supplies none.
	Token string
}

Resolved is the effective configuration after merging defaults, top-level overrides, and the selected profile.