package cfg¶

import "github.com/cloudboss/unobin/pkg/sdk/cfg"

Package cfg is the typed vocabulary a Go library uses to declare its configuration. Each wrapper carries the decoded value alongside its schema info (description, default, validation) for one field. Only wrappers in this package satisfy the Value constraint, so a library author cannot place a bare Go type as the element of a List, Map, or Set.

Functions¶

func Decode¶

func Decode(ct Registration, raw map[string]any) (any, error)

Decode populates a fresh instance returned by ct.New() with values from raw. Field names match in kebab form (AssumeRole reads from "assume-role"). A non-pointer wrapper field is required; a pointer to a wrapper is optional and falls back to the wrapper's Default when the key is absent. An unknown key in raw is an error.

Atomic wrappers (String, Integer, Number, Boolean), List, Map, Object, and nested struct recursion are supported. A struct composes another configuration through a named field only; an anonymous field is an error, so a field is never silently keyed by its type name.

func DigestView¶

func DigestView(fields []typecheck.ObjectField, defaults []lang.DefaultSpec) string

DigestView returns a deterministic digest for a config schema view.

func ValidateConfigurationType¶

func ValidateConfigurationType(ct Registration) error

ValidateConfigurationType verifies that every reachable field in a fresh New() instance is a wrapper from this package or a struct whose fields recurse to wrappers. Call this from a library's unit tests to catch misuse at go-test time. The runtime calls it at library load to fail fast on a misdeclared configuration.

Types¶

type Any¶

type Any struct {
    Value       any
    Description string
    Validate    Validator
}

type Boolean¶

type Boolean struct {
    Value       bool
    Description string
    Default     bool
}

type ConfigurationType¶

type ConfigurationType[C any] struct {
    Description string
    New         func() C
}

ConfigurationType registers a library's configuration. New returns a pointer to a fresh configuration struct. The decoder populates its fields from stack inputs. The struct's fields must be wrapper types from this package or nested structs whose fields are wrapper types; the schema walker rejects any other field type at library load. Description appears in the schema commands.

func (*ConfigurationType[C]) DescriptionText¶

func (ct *ConfigurationType[C]) DescriptionText() string

func (*ConfigurationType[C]) Empty¶

func (ct *ConfigurationType[C]) Empty() bool

func (*ConfigurationType[C]) NewAny¶

func (ct *ConfigurationType[C]) NewAny() any

func (*ConfigurationType[C]) ValueType¶

func (ct *ConfigurationType[C]) ValueType() reflect.Type

type Field¶

type Field struct {
    Name        string
    Type        string
    Optional    bool
    Description string

    // Fields lists an object-typed field's own fields in declaration
    // order, so help output can show nested structure. Empty for any
    // other type.
    Fields []Field
}

Field describes one field of a configuration struct, for the factory's own help output.

func Describe¶

func Describe(ct Registration) []Field

Describe lists the fields of the configuration struct behind ct in declaration order, walking the value New returns the same way the decoder does: kebab-case names, a pointer field is optional, and a nested struct reads as an object whose own fields fill Fields. Anonymous fields are skipped here; Decode rejects them. Descriptions come from whatever the zero value sets. Returns nil when there is no configuration to describe.

type Integer¶

type Integer struct {
    Value       int64
    Description string
    Default     int64
    Validate    Validator
}

type LibraryConfigView¶

type LibraryConfigView struct {
    Fields       []typecheck.ObjectField
    Defaults     []lang.DefaultSpec
    Empty        bool
    SchemaDigest string
}

LibraryConfigView is the config schema in the form used by input and type checking.

func View¶

func View(ct Registration) (LibraryConfigView, error)

View converts a config registration into the schema view used by library-config inputs. A nil registration returns the zero view; an empty struct registration returns Empty=true and a stable digest.

type List¶

type List[T Value] struct {
    Value       []T
    Description string
    Default     []T
    Element     T
    Validate    Validator
}

Element supplies the schema info (description, default, validator) applied to each item. Its own Value is ignored.

type Map¶

type Map[T Value] struct {
    Value       map[string]T
    Description string
    Default     map[string]T
    Element     T
    Validate    Validator
}

type Null¶

type Null struct {
    Description string
}

type Number¶

type Number struct {
    Value       float64
    Description string
    Default     float64
    Validate    Validator
}

type Object¶

type Object[T any] struct {
    Value       T
    Description string
    Validate    Validator
}

Object wraps a user struct in a position that requires a Value, such as the element type of a List or Map. T must be a struct whose fields are wrapper types or nested structs; the schema walker rejects any other field type at library load. An optional nested struct at the top level of a Configuration uses a plain *Struct and does not need this wrapper.

type Registration¶

type Registration interface {
    DescriptionText() string
    NewAny() any
    ValueType() reflect.Type
    Empty() bool
}

Registration is the type-erased view of a library's configuration. Library authors use ConfigurationType with a concrete type parameter; runtime packages consume this interface.

type String¶

type String struct {
    Value       string
    Description string
    Default     string
    Validate    Validator
}

type Validator¶

type Validator interface {
    Check(any) error
    Describe() ValidatorDesc
}

Validator runs after decode to check that a value meets a library author's constraints. Describe returns a structured form so the schema commands and editor tooling can render the constraint declaratively rather than as an opaque function.

type ValidatorDesc¶

type ValidatorDesc struct {
    Kind   string
    Params map[string]any
}

ValidatorDesc names a validator's kind and parameters. Standard kinds include "pattern", "range", "length", "enum", "all", and "custom"; introspection tools render the known kinds to their UB modifier and fall back to the description text for "custom".

type Value¶

type Value interface {
    // contains filtered or unexported methods
}

Value is the constraint for any type that may appear as the element of a List, Map, or Set, or as a standalone field on a Configuration. The unexported marker keeps the constraint closed to wrappers defined here.