config

package
v0.2.1 Latest Latest
Warning

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

Go to latest
Published: Sep 9, 2026 License: MIT Imports: 14 Imported by: 0

Documentation

Overview

Package config loads a configuration struct from environment variables.

Load reads every field, collects every fault, and returns a report that names the source of each value. It does not stop at the first fault. See the SDD, section 6, S1.

The loader uses reflection one time at start. No request path calls it.

Index

Constants

View Source
const Redacted = "********"

Redacted replaces the value of a secret field wherever Avero prints it.

View Source
const ReportSchemaID = "https://avero.dev/schema/config-report/v1"

ReportSchemaID names the schema that a JSON report follows. See config/schema.json.

Variables

View Source
var ReportSchema []byte

ReportSchema holds config/schema.json. `avero doctor --json` emits a document that this schema accepts.

Functions

func Exit

func Exit(w io.Writer, err error) int

Exit writes err to w and returns the process exit code. It returns 0 for a nil error and 1 for any fault. The caller owns the call to os.Exit, because Avero owns lifecycle in one place.

func Load

func Load[T any](ctx context.Context) (*T, error)

Load reads the process environment into a new T. It returns a *FaultList when T holds a fault. Call Exit to print the faults and to get the exit code.

Types

type BaseConfig

type BaseConfig struct {
	// Port is the port that the HTTP server binds.
	Port int `env:"PORT" default:"8080"`
	// LogLevel is one of debug, info, warn or error.
	LogLevel string `env:"LOG_LEVEL" default:"info"`
	// LogFormat is json or text.
	LogFormat string `env:"LOG_FORMAT" default:"json"`
	// ShutdownGrace is the deadline that Stop receives. See the SDD, S2.
	ShutdownGrace time.Duration `env:"SHUTDOWN_GRACE" default:"15s"`
	// MigrateOnBoot applies pending migrations at start. See the SDD, 5.3.
	MigrateOnBoot bool `env:"MIGRATE_ON_BOOT" default:"false"`
	// Env is the deployment environment, such as development or production.
	Env string `env:"AVERO_ENV" default:"development"`
	// Secret signs the cookies that Avero owns: the CSRF token and the flash
	// that carries a toast across a redirect. auth-all owns the
	// authentication session and holds its own secret.
	//
	// It is required, so a missing secret stops the process before it serves.
	// See DX-8. Use at least 32 bytes, for example the output of
	// `openssl rand -hex 32`. Call Reveal to read the value.
	Secret Secret `env:"AVERO_SECRET,required,secret"`
	// OTel holds the standard OpenTelemetry variables.
	OTel OTelConfig `env:"OTEL"`
}

BaseConfig holds the variables that every Avero application reads. Embed it in the application configuration struct. An embedded struct takes no prefix, so PORT stays PORT.

type Fault

type Fault struct {
	// Path is the struct field, qualified by the configuration type.
	Path string `json:"path"`
	// Name is the environment variable.
	Name string `json:"name"`
	// Message states the fault.
	Message string `json:"message"`
	// Repair states what to do. It is one sentence.
	Repair string `json:"repair"`
}

Fault describes one configuration fault. It names the environment variable, states what went wrong, and states the repair in one sentence. See DX-7.

func (*Fault) Error

func (f *Fault) Error() string

Error returns the message and the repair on two lines.

type FaultList

type FaultList struct {
	Faults []*Fault `json:"faults"`
	// Report lists every field that the loader read before it stopped. It
	// lets `avero doctor` print the whole table beside the faults.
	Report *Report `json:"report,omitempty"`
}

FaultList holds every fault that one load found. The loader never stops at the first fault.

func (*FaultList) Error

func (l *FaultList) Error() string

Error returns a count and one entry for each fault.

func (*FaultList) Unwrap

func (l *FaultList) Unwrap() []error

Unwrap returns each fault so that errors.As reaches a single one.

type Field

type Field struct {
	// Path is the struct field, such as DB.Host.
	Path string `json:"path"`
	// Name is the environment variable, such as DB_HOST.
	Name string `json:"name"`
	// Type is the Go type of the field, such as int.
	Type string `json:"type"`
	// Value is the value as text. A secret field reads Redacted.
	Value string `json:"value"`
	// Source states where the value came from.
	Source Source `json:"source"`
	// Secret marks a field that the loader redacts.
	Secret bool `json:"secret"`
	// Required marks a field that the loader demands.
	Required bool `json:"required"`
}

Field is one row of a report.

type Loader

type Loader struct {
	// Lookup returns the value of a variable and reports whether it is set.
	Lookup func(name string) (string, bool)
}

Loader reads the values. Give it a Lookup to read from something other than the process environment. A nil Lookup reads os.LookupEnv.

type OTelConfig

type OTelConfig struct {
	// ServiceName names the service in a trace and in a metric.
	ServiceName string `env:"SERVICE_NAME" default:""`
	// ExporterOTLPEndpoint is the collector address.
	ExporterOTLPEndpoint url.URL `env:"EXPORTER_OTLP_ENDPOINT" default:""`
	// ExporterOTLPProtocol is grpc or http/protobuf.
	ExporterOTLPProtocol string `env:"EXPORTER_OTLP_PROTOCOL" default:"http/protobuf"`
	// TracesExporter is otlp or none.
	TracesExporter string `env:"TRACES_EXPORTER" default:"none"`
	// MetricsExporter is otlp or none.
	MetricsExporter string `env:"METRICS_EXPORTER" default:"none"`
}

OTelConfig holds the standard OTEL_* variables. The default exporter is none, so an application produces no telemetry until a person asks for it. See the SDD, S3.

type Report

type Report struct {
	// Fields holds one row for each field, in declaration order.
	Fields []Field `json:"fields"`
}

Report lists every field of a configuration struct with its value and its source. `avero doctor` prints it. A secret value never appears.

func LoadFrom

func LoadFrom[T any](ctx context.Context, l Loader) (*T, *Report, error)

LoadFrom reads l into a new T and returns a report of every field. It returns a *FaultList when T holds a fault. The report is complete for a successful load. It is nil for a fault.

func (*Report) Field

func (r *Report) Field(path string) (Field, bool)

Field returns the row with this path.

func (*Report) MarshalJSON

func (r *Report) MarshalJSON() ([]byte, error)

MarshalJSON emits the report with a stable schema. See AN-3.

func (*Report) String

func (r *Report) String() string

String returns a table with a header row and one row for each field.

type Secret

type Secret string

Secret holds a value that must never reach a log line, a trace attribute, an error message or the doctor output. Every print verb gives Redacted. Call Reveal to read the value.

A field marked `env:"NAME,secret"` is redacted in the report and in every fault message whatever its type. Give the field the type Secret to redact it in a `%v` format of the configuration struct as well.

func (Secret) Format

func (s Secret) Format(f fmt.State, _ rune)

Format writes the redaction. It ignores the verb, so no format string can print the value.

func (Secret) LogValue

func (s Secret) LogValue() slog.Value

LogValue writes the redaction into a slog record.

func (Secret) MarshalJSON

func (s Secret) MarshalJSON() ([]byte, error)

MarshalJSON writes the redaction.

func (Secret) MarshalText

func (s Secret) MarshalText() ([]byte, error)

MarshalText writes the redaction.

func (Secret) Reveal

func (s Secret) Reveal() string

Reveal returns the value. Call it only where the value is used.

func (Secret) String

func (s Secret) String() string

String returns the redaction.

type Source

type Source string

Source states where a value came from.

const (
	// SourceEnv marks a value that an environment variable supplied.
	SourceEnv Source = "env"
	// SourceDefault marks a value that a default tag supplied.
	SourceDefault Source = "default"
	// SourceAbsent marks a field that no variable and no default supplied.
	SourceAbsent Source = "absent"
)

Jump to

Keyboard shortcuts

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