settings

type Choice struct {
	// Value is what is stored.
	Value string `json:"value"`

	// Label is what is shown.
	Label string `json:"label"`

	// Help explains the consequence of this option, not what it is called.
	//
	// Optional, but the reason the type has it: "strict" tells somebody nothing, and "refuse a file whose segment count
	// disagrees" tells them whether they want it.
	Help string `json:"help,omitempty"`
}

type Effect string

type Kind string

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

type Setting struct {
	// Key identifies it, dotted and stable: "data.retentionDays".
	//
	// Stable because it is what the file is keyed by. Renaming one silently abandons whatever an operator had set, so the
	// rename path is a migration rather than an edit.
	Key string `json:"key"`

	// Group and Subgroup place it in the interface.
	//
	// Two levels and no more. A third level is how a settings page becomes something you navigate rather than read.
	Group    string `json:"group"`
	Subgroup string `json:"subgroup"`

	// Label is the control's caption, in sentence case and without a trailing colon.
	Label string `json:"label"`

	// Help says what the setting does and what happens if it is wrong.
	//
	// Required. The whole reason settings were flags for so long is that a flag comes with a line of help text and a form
	// field does not, so the form is the thing that has to be made to carry it.
	Help string `json:"help"`

	// Kind is what sort of value it is.
	Kind Kind `json:"kind"`

	// Widget is how to draw it.
	Widget Widget `json:"widget"`

	// Effect says when a change takes hold.
	Effect Effect `json:"effect"`

	// Default is the value when nothing has been set.
	//
	// Typed to match Kind - bool, int, string, or []string - and checked by the drift test rather than trusted.
	Default any `json:"default"`

	// Min and Max bound a number. Both nil means unbounded.
	Min *int `json:"min,omitempty"`
	Max *int `json:"max,omitempty"`

	// Unit is what the number counts: "days", "percent", "MB".
	//
	// On the control rather than only in the help, because a box containing 30 is ambiguous and a box containing 30 next to
	// the word "days" is not.
	Unit string `json:"unit,omitempty"`

	// Choices are the options for KindChoice.
	Choices []Choice `json:"choices,omitempty"`

	// Language is the syntax for KindCode: "yaml" or "javascript".
	Language string `json:"language,omitempty"`

	// Flag names the command-line flag that seeds this setting, without its dash.
	//
	// Recorded so the interface can say where a value came from, and so a flag that disagrees with the file can be reported
	// by name at startup instead of as a mystery.
	Flag string `json:"flag,omitempty"`

	// Advanced hides it behind a disclosure.
	//
	// For settings that are real but that most installations should not touch. Hidden rather than absent, because a setting
	// nobody can find is one they will instead ask for as a feature.
	Advanced bool `json:"advanced,omitempty"`

	// PerServer marks a setting that names something on one machine (a certificate's path, an address to listen on, its
	// own name). In a cluster every server shares one settings file, so these are left out of it and each server takes
	// them from its own command line.
	PerServer bool `json:"perServer,omitempty"`

	// Sensitive marks a setting whose change is worth an audit entry beyond the ordinary.
	//
	// Anything that alters who can get in or what leaves the building.
	Sensitive bool `json:"sensitive,omitempty"`

	// Validate checks a value beyond its kind and bounds. Nil when kind and bounds are the whole story.
	//
	// Not serialised: the interface cannot run it, and pretending otherwise would mean writing the same rule twice. The
	// interface catches what it can and the server is what refuses.
	Validate func(any) error `json:"-"`
}

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

type Widget string