config

Documentation

Overview

Package config manages persistent user settings for pingtrace.

The on-disk format is a single JSON document stored at <UserConfigDir>/pingtrace/config.json. Values are addressed by dotted keys (for example, "ipinfo.token" or "thresholds.latency.yellow_ms"). Environment variables of the form PINGTRACE_<UPPER_DOTTED> override the file on read.

Index

• Variables
• func Defaults() map[string]any
• func Effective() (map[string]any, error)
• func Format(v any) string
• func Get(key string) (any, bool, error)
• func KeysByCategory() [][2]any
• func KnownKey(key string) bool
• func Load() (map[string]any, error)
• func Meta() map[string]KeyMeta
• func Path() (string, error)
• func Redact(key string, value any) any
• func Save(flat map[string]any) error
• func Set(key, value string) error
• func SortedKeys() []string
• func Unset(key string) error
• type KeyMeta

Variables

var CategoryOrder = []string{
	"Tokens & accounts",
	"DNS resolution",
	"Ping engine",
	"Traceroute engine",
	"MTR engine",
	"Color thresholds",
	"Other",
}

CategoryOrder is the display order used by `config list` and the interactive TUI. Keys not associated with any category fall under "Other".

var SecretKeys = map[string]bool{
	"ipinfo.token":    true,
	"peeringdb.token": true,
}

SecretKeys lists keys whose values must be redacted in human output unless the caller opts in.

Functions

func Defaults

func Defaults() map[string]any

Defaults returns the baseline configuration. Any key not present in the on-disk file falls back to these values.

func Effective

func Effective() (map[string]any, error)

Effective merges defaults, file, and env overrides. Env wins, file second, defaults last. Returned values are typed per the defaults map (numbers stay float64, strings stay string).

func Format

func Format(v any) string

Format renders a value for human output (numbers without trailing zeros, strings as-is).

func Get

func Get(key string) (any, bool, error)

Get returns the effective value for a single key.

func KeysByCategory

func KeysByCategory() [][2]any

KeysByCategory returns the known keys grouped by category, with each group sorted alphabetically. Categories follow CategoryOrder and any unknown ones are appended at the end.

func KnownKey

func KnownKey(key string) bool

KnownKey reports whether the key is part of the defaults set.

func Load

func Load() (map[string]any, error)

Load reads the config file. A missing file is not an error; callers receive an empty map and can layer Defaults on top.

func Meta

func Meta() map[string]KeyMeta

Meta returns the description table for every known key. Keep descriptions short (fits in a list view) and use Hint for the "go sign up" nudge or unit explanations.

func Path

func Path() (string, error)

Path returns the absolute path to the pingtrace config file. Honors PINGTRACE_CONFIG if set.

func Redact

func Redact(key string, value any) any

Redact returns "(unset)" for empty secrets and a masked form otherwise. Non-secret values pass through unchanged.

func Save

func Save(flat map[string]any) error

Save writes the supplied flat key/value map to the config file atomically (write to .tmp + rename). Parent directories are created with 0o700.

func Set

func Set(key, value string) error

Set persists key=value to the file. The value is coerced to the type implied by Defaults (numeric keys parse as float64).

func SortedKeys

func SortedKeys() []string

SortedKeys returns the defaults' keys in stable order for listing and tab-completion.

func Unset

func Unset(key string) error

Unset removes a key from the file (defaults / env still apply).

Types

type KeyMeta

type KeyMeta struct {
	Category    string
	Description string
	Hint        string
}

KeyMeta describes a single config key: which category it belongs to (used for grouping in the UI), a one-line description shown inline, and an optional hint URL or follow-up sentence (used for account-signup nudges on ipinfo / peeringdb).