config

Documentation

Index

• Constants
• func ApplyEnv(lookup EnvLookup, envName string, setter func(string) error) error
• func Load[T any](argv []string) (*T, []string, error)
• func MergeJSONFile(path string, dst proto.Message, secretFields ...string) (map[string]struct{}, error)
• func MergeJSONFileWithParsers(path string, dst proto.Message, parsers map[string]JSONFieldParser, ...) (map[string]struct{}, error)
• func ParseBool(raw string) (bool, error)
• func ParseBytes(raw string) ([]byte, error)
• func ParseEnum(raw string, mappings []*EnumMapping, typeName string) (int32, error)
• func ParseFloat32(raw string) (float32, error)
• func ParseFloat64(raw string) (float64, error)
• func ParseInt32(raw string) (int32, error)
• func ParseInt64(raw string) (int64, error)
• func ParseString(raw string) (string, error)
• func ParseUint32(raw string) (uint32, error)
• func ParseUint64(raw string) (uint64, error)
• func RedactBytes(value []byte) []byte
• func RedactIfSet[T comparable](value, replacement T) T
• func ValidateRequired(fieldName string, present bool) error
• type BootstrapResult
  • func ParseBootstrapArgs(argv []string, specs []*BootstrapSpec) (*BootstrapResult, error)
• type BootstrapSpec
• type EnumMapping
• type EnvLookup
• type JSONFieldParser
• type Spec
• type SpecProvider

Constants

const RedactedPlaceholder = "[REDACTED]"

RedactedPlaceholder is the canonical replacement value for masked strings.

const ReservedConfigFlag = "config"

ReservedConfigFlag is the flag name reserved for specifying the config file path.

Functions

func ApplyEnv

func ApplyEnv(lookup EnvLookup, envName string, setter func(string) error) error

ApplyEnv looks up envName and, if set, applies it via setter.

func Load

func Load[T any](argv []string) (*T, []string, error)

Load creates and populates a config of type T from argv.

T can be:

• A proto config message implementing SpecProvider (single config)
• A struct embedding one or more *ProtoConfig types (composite config)

When multiple configs are embedded, env var and bootstrap flag conflicts are detected and --config is disallowed.

func MergeJSONFile

func MergeJSONFile(path string, dst proto.Message, secretFields ...string) (map[string]struct{}, error)

MergeJSONFile overlays top-level JSON fields from path onto dst. This enables defaults -> file merge without dropping pre-populated defaults.

func MergeJSONFileWithParsers

func MergeJSONFileWithParsers(
	path string,
	dst proto.Message,
	parsers map[string]JSONFieldParser,
	secretFields ...string,
) (map[string]struct{}, error)

MergeJSONFileWithParsers overlays top-level JSON fields from path onto dst. Parsers can normalize selected fields before protojson unmarshaling.

func ParseBool

func ParseBool(raw string) (bool, error)

ParseBool parses a bool scalar.

func ParseBytes

func ParseBytes(raw string) ([]byte, error)

ParseBytes parses a bytes scalar from base64 text.

func ParseEnum

func ParseEnum(raw string, mappings []*EnumMapping, typeName string) (int32, error)

ParseEnum parses a case-insensitive enum value from mappings.

func ParseFloat32

func ParseFloat32(raw string) (float32, error)

ParseFloat32 parses a float32 scalar.

func ParseFloat64

func ParseFloat64(raw string) (float64, error)

ParseFloat64 parses a float64 scalar.

func ParseInt32

func ParseInt32(raw string) (int32, error)

ParseInt32 parses an int32 scalar.

func ParseInt64

func ParseInt64(raw string) (int64, error)

ParseInt64 parses an int64 scalar.

func ParseString

func ParseString(raw string) (string, error)

ParseString parses a string scalar from text.

func ParseUint32

func ParseUint32(raw string) (uint32, error)

ParseUint32 parses a uint32 scalar.

func ParseUint64

func ParseUint64(raw string) (uint64, error)

ParseUint64 parses a uint64 scalar.

func RedactBytes

func RedactBytes(value []byte) []byte

RedactBytes returns a masked byte slice for non-empty input.

func RedactIfSet

func RedactIfSet[T comparable](value, replacement T) T

RedactIfSet returns replacement when value is non-zero; otherwise it returns value.

func ValidateRequired

func ValidateRequired(fieldName string, present bool) error

ValidateRequired returns an error when a required field was never set.

Types

type BootstrapResult

type BootstrapResult struct {
	ConfigPath string
	Values     map[string]string
	Rest       []string
}

BootstrapResult holds parsed bootstrap values and remaining procedure args.

func ParseBootstrapArgs

func ParseBootstrapArgs(argv []string, specs []*BootstrapSpec) (*BootstrapResult, error)

ParseBootstrapArgs parses bootstrap flags from the argv prefix.

Only consecutive leading bootstrap flags are consumed. Parsing stops at the first non-bootstrap token, and the remaining slice is returned in Rest.

Supported forms:

• --config <path>
• --config=<path>
• --<bootstrap-flag> <value>
• --<bootstrap-flag>=<value>

type BootstrapSpec

type BootstrapSpec struct {
	Flag string
}

BootstrapSpec describes a bootstrap flag accepted by ParseBootstrapArgs. The flag name must be kebab-case without the leading "--".

type EnumMapping

type EnumMapping struct {
	Name   string
	Number int32
}

EnumMapping maps a string enum value to its numeric representation.

type EnvLookup

type EnvLookup func(string) (string, bool)

EnvLookup is compatible with os.LookupEnv.

type JSONFieldParser

type JSONFieldParser func(raw json.RawMessage) (any, error)

JSONFieldParser rewrites a top-level config JSON field before protojson unmarshaling. The returned value must be JSON-marshalable.

type Spec

type Spec struct {
	EnvNames       map[string]string // env var name -> field path
	BootstrapSpecs []*BootstrapSpec

	ApplyDefaults    func() error
	ApplyConfigFile  func(path string) error
	ApplyEnv         func(lookup EnvLookup) error
	ApplyBootstrap   func(values map[string]string) error
	ValidateRequired func() error
}

Spec holds config loading metadata and operations. Generated ConfigSpec() methods return this with closures capturing the config instance and its presence tracker.

All function fields must be non-nil; generated code guarantees this.

type SpecProvider

type SpecProvider interface {
	ConfigSpec() *Spec
}

SpecProvider is implemented by generated config messages.