settings

package
v0.9.0-dev.50 Latest Latest
Warning

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

Go to latest
Published: Oct 22, 2026 License: AGPL-3.0 Imports: 23 Imported by: 0

Documentation

Overview

Package settings loads, holds and saves subflux's one configuration file: each section parsed by its owner, the result a Snapshot that is Unconfigured, Failed or Active, never a configuration beside a flag.

Index

Constants

This section is empty.

Variables

View Source
var (
	// ErrActivation is Save's answer when activate failed: the file is
	// restored and the previous settings stay live.
	ErrActivation = errors.New("settings: the saved settings could not be activated")
	// ErrClosed is Save's answer once Shutdown has begun.
	ErrClosed = errors.New("settings: shutting down")
	// ErrConflict is Save's answer to a base other than the live revision.
	ErrConflict = errors.New("settings: saved from an older revision")
)

Functions

This section is empty.

Types

type Active

type Active struct {
	Languages language.Policy
	Server    Server
}

Active is a configuration that parsed, one field per section.

type Mode

type Mode uint8

Mode is which of the three states a Snapshot is in.

const (
	// Unconfigured is no file: every section runs at its owner's defaults.
	Unconfigured Mode = iota + 1
	// Failed is a file that does not parse; Failure holds why.
	Failed
	// ModeActive is a file that parsed; Active holds it.
	ModeActive
)

func (Mode) MarshalText

func (m Mode) MarshalText() ([]byte, error)

MarshalText answers the mode's snake_case name and refuses the zero Mode.

func (*Mode) UnmarshalText

func (m *Mode) UnmarshalText(b []byte) error

UnmarshalText reads a snake_case mode name, refusing every other spelling.

type Registries

type Registries struct{}

Registries lists the adapter kinds each hand-walked section accepts.

type SaveCheck

type SaveCheck func(ctx context.Context, prev, next Active) []formschema.FieldError

SaveCheck is app's save-time check: Save runs it after the parse and before the write, under the Save's context, and Load never does. A non-empty answer refuses the Save as a parse error does, writing nothing. From a Failed or Unconfigured snapshot prev is the zero Active.

type Server

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

Server is the server section; its zero value trusts no proxy, allows every host and logs at INFO in JSON.

func (Server) AllowedHosts

func (s Server) AllowedHosts() []string

AllowedHosts is the canonical hosts of the allowed_hosts entries ParseHostList accepted, once each in file order, nil for none.

func (Server) Hosts

func (s Server) Hosts() *webhttp.HostPolicy

Hosts is webhttp.ParseHostList over allowed_hosts with WithLoopbackExempt(true), so a loopback peer naming a loopback Host is admitted: inactive only when no file exists or it is one mapping whose list is absent, null or empty. A list with any element but no valid entry, or a root-level failure, denies every Host, a loopback peer's included.

func (Server) LogFormat

func (s Server) LogFormat() string

LogFormat is json or text.

func (Server) LogLevel

func (s Server) LogLevel() slog.Level

LogLevel is the level the process logs at.

func (Server) TrustedProxies

func (s Server) TrustedProxies() []netip.Prefix

TrustedProxies answers a copy of the proxies whose forwarded address is believed.

type Service

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

Service holds the live snapshot and saves the file.

func NewService

func NewService(path string, r Registries, s Snapshot, activate func(context.Context, Active) error, check SaveCheck) *Service

NewService serves s, which Load(path, r) answered. activate makes a parsed configuration live, nil when nothing needs to; check may be nil.

func (*Service) Changed

func (s *Service) Changed() <-chan struct{}

Changed is signalled after every commit and every Diverged change: capacity 1, coalescing, read by app's change loop alone.

func (*Service) Diverged

func (s *Service) Diverged() bool

Diverged reports a failed restore after a failed activation: the file holds settings that are not live. A committed Save clears it.

func (*Service) Merge

func (s *Service) Merge(section string, entry *yaml.Node, parse func(expanded *yaml.Node) []formschema.FieldError) []formschema.FieldError

Merge fills each unchanged scalar of entry, an unsaved element of section's list, from the saved element with its id, then calls parse once with a private copy in which every ${SUBFLUX_...} is expanded, so a connection test parses and uses the saved secret server-side. parse must not be nil. The expanded copy lives only for that call: Merge returns no document, writes nothing and logs nothing. A field error names an unchanged path with no saved value, a refused shape or an unresolved variable, never a value; parse's own errors are returned as it gave them.

func (*Service) Save

func (s *Service) Save(ctx context.Context, doc *yaml.Node, base string) (Snapshot, []formschema.FieldError, error)

Save replaces the file with doc, a whole document as Document answers it, each unchanged scalar taken from the stored file, and makes it live. base is the Revision the document was read at; another is ErrConflict, checked first. A document that does not parse, a check that refuses it, or a file changed on disk since this service last read or wrote it answers the live snapshot and field errors, writing nothing. The write and activate run to the end whatever ctx does, and only Shutdown cancels them; a failed activate restores the file and answers ErrActivation.

func (*Service) Shutdown

func (s *Service) Shutdown(ctx context.Context) error

Shutdown refuses every later Save with ErrClosed and waits for the Save in progress. When ctx ends first it cancels that Save's write-and-activate context, which restores the file, and returns ctx's error without waiting for it; app closes the store only after Shutdown returns nil.

func (*Service) Snapshot

func (s *Service) Snapshot() Snapshot

Snapshot answers the live snapshot.

type Snapshot

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

Snapshot is one immutable reading of the file. Only Load and Service.Save build one, so a mode and a configuration never disagree. The zero Snapshot has no mode, and its Server denies every Host.

func Load

func Load(path string, r Registries) Snapshot

Load reads the file at path, an absolute path: absent is Unconfigured, and a file that does not parse is Failed. It never writes.

func (Snapshot) Active

func (s Snapshot) Active() (Active, bool)

Active answers the configuration when the mode is ModeActive.

func (Snapshot) Document

func (s Snapshot) Document() *yaml.Node

Document is a fresh deep copy, on every call, of the file as written, failing closed: a scalar keeps its text only where its section's parse marked it formschema.PlainTag or where it is wholly one ${NAME}; every other scalar is an empty scalar tagged formschema.UnchangedTag. Comments, anchors and aliases are dropped. It is nil when the file is absent or not one mapping. Revision names the same reading.

func (Snapshot) Failure

func (s Snapshot) Failure() ([]formschema.FieldError, bool)

Failure answers a copy of the field errors when the mode is Failed.

func (Snapshot) Mode

func (s Snapshot) Mode() Mode

Mode answers which state the snapshot is in.

func (Snapshot) Revision

func (s Snapshot) Revision() string

Revision names this reading of the file; a Save from a Document of another reading is refused with ErrConflict. It is "" for the zero Snapshot.

func (Snapshot) Server

func (s Snapshot) Server() (Server, bool)

Server is the server section in force: Active's, Unconfigured's defaults, or in Failed the section when its own parse succeeded; false only in Failed when it did not. A false Server is still the fail-closed value: no trusted proxy, and the host policy of the entries as written, or one denying every Host when the file failed at its root.

Jump to

Keyboard shortcuts

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