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 ¶
const Redacted = "********"
Redacted replaces the value of a secret field wherever Avero prints it.
const ReportSchemaID = "https://avero.dev/schema/config-report/v1"
ReportSchemaID names the schema that a JSON report follows. See config/schema.json.
Variables ¶
var ReportSchema []byte
ReportSchema holds config/schema.json. `avero doctor --json` emits a document that this schema accepts.
Functions ¶
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.
func (BaseConfig) Base ¶ added in v0.4.0
func (c BaseConfig) Base() BaseConfig
Base returns the base configuration.
The configuration of an application embeds BaseConfig, so it carries this method and avero.Serve reads the port, the secret and the shutdown grace of any application. An application writes no method of its own.
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.
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.
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 ¶
LoadFrom reads l into a new T and returns a report of every field. It returns a *FaultList when T holds a fault, together with the value the loader already filled and the report of every field it read before the fault. A caller such as `avero doctor` reads the value that did load beside the fault that did not.
func (*Report) MarshalJSON ¶
MarshalJSON emits the report with a stable schema. See AN-3.
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 ¶
Format writes the redaction. It ignores the verb, so no format string can print the value.
func (Secret) MarshalJSON ¶
MarshalJSON writes the redaction.
func (Secret) MarshalText ¶
MarshalText writes the redaction.