Configuration without magic: env, flags, files, and a typed Config that fails at boot

Three sources, one ladder

Why does configuration need a precedence ladder at all? Because flags, environment variables, and files each have a different owner — and when they conflict, you need a rule that is obvious enough to debug at 3 a.m. Production Go services pull configuration from three places, each with a real constituency. Environment variables are the 12-factor baseline: per-deployment, no rebuild, native to every container orchestrator — but they are flat strings, invisible until you print them, and inherited by every child process. Flags serve operators: -help is living documentation, and a one-off override at the terminal beats editing a manifest. Files carry complex shapes — nested structures, lists, per-tenant maps — that die a thousand deaths when encoded into env strings, and they go through code review. The resolution order is a precedence ladder, most deliberate wins:

Parse once, validate eagerly

The discipline that prevents the Hook incident has two halves. First: configuration is read in exactly one place, at startup, into a typed struct — no os.Getenv below main. Second: validation is eager and fatal. A service that boots with garbage config fails at request time, hours or days later, under traffic; a service that refuses to boot fails inside the deploy, where rollouts halt automatically and old pods keep serving.

type Config struct {
	HTTPAddr     string
	CacheTimeout time.Duration
	DatabaseURL  Secret // see below
}

func Load(args []string) (Config, error) {
	cfg := Config{HTTPAddr: ":8080", CacheTimeout: 50 * time.Millisecond} // defaults

	if v, ok := os.LookupEnv("CACHE_TIMEOUT_MS"); ok { // unset and empty are different
		ms, err := strconv.Atoi(v)
		if err != nil || ms <= 0 {
			return Config{}, fmt.Errorf("CACHE_TIMEOUT_MS=%q: want a positive integer", v)
		}
		cfg.CacheTimeout = time.Duration(ms) * time.Millisecond
	}

	fs := flag.NewFlagSet("api", flag.ContinueOnError)
	fs.StringVar(&cfg.HTTPAddr, "http", cfg.HTTPAddr, "listen address") // flag beats env
	if err := fs.Parse(args); err != nil {
		return Config{}, err
	}
	return cfg, cfg.validate() // required fields, ranges, URL syntax — all now
}

LookupEnv is the load-bearing detail: Getenv cannot distinguish unset from set to empty, which is exactly the ambiguity that turned a missing variable into a silent zero. Handlers receive Config — or just the sub-struct they need — through constructors, so the dependency is visible in signatures and trivial to fake in tests.

Secrets do not belong in dumps

When you print a config struct — and you will, in a boot log or a crash report — every unprotected field is a leak vector. Config structs get printed: boot logs, crash reports, %+v in an error path, debug endpoints. Every one of those is a leak vector for the database password embedded in a DSN. Flags are worse — process arguments are world-readable in ps output on shared hosts. The Go-native containment is a named type whose formatting lies:

type Secret string

func (Secret) String() string       { return "[REDACTED]" }
func (Secret) LogValue() slog.Value { return slog.StringValue("[REDACTED]") }
func (s Secret) Reveal() string     { return string(s) } // explicit, greppable

// fmt %v, %s, %+v and slog all hit String/LogValue. json.Marshal does NOT —
// it reads the underlying string, so define MarshalJSON too if the struct
// can ever reach an encoder.

The Reveal() call is the point: every place the raw secret escapes is now a deliberate, searchable act instead of an accident of formatting. Reflection-based encoders bypass Stringer, so the honest version also implements MarshalJSON — teams discover this the day a support bundle with a serialized config lands in a ticket system.

Hot reload, honestly

File watching looks like an upgrade and is usually a downgrade. A restart applies config through the exact path you test on every deploy: parse, validate, refuse-or-serve. Reload creates a second path that runs rarely and under no test coverage: half-applied updates where some goroutines hold the old value, validation racing in-flight requests, fsnotify quirks around the symlink dance Kubernetes performs on ConfigMap updates, and a fleet where each pod picked up the change at a different moment. A rolling restart of a twenty-pod deployment costs a couple of minutes and zero new code paths. Reload earns its complexity in two places: fleets so large that restart storms cost real capacity, and values that change many times a day — which are feature flags, and belong in a flag service with explicit versioning and audit, not in a watched file.

Library config is a different problem

The typed-struct-at-boot pattern is for applications, which own main and can be exhaustive. Libraries face the opposite constraints: an exported API frozen by compatibility promises, callers who set two of fifteen knobs, and zero-value ambiguity — does Timeout: 0 mean “not set, use the default” or “deliberately no timeout”? Functional options resolve all three:

type Option func(*client)

func WithTimeout(d time.Duration) Option { return func(c *client) { c.timeout = d } }

func New(addr string, opts ...Option) (*Client, error) {
	c := &client{timeout: 5 * time.Second} // default lives here, unambiguous
	for _, o := range opts {
		o(c)
	}
	return c.validateAndBuild()
}

Unset means default because the option was never passed; new knobs never break existing call sites; validation runs at construction. Inside an application the same pattern is ceremony — a plain struct is greppable, exhaustive, and obvious.