Documentation
¶
Overview ¶
Package xconf assembles ordered configuration layers against a schemapb schema. Defaults, coercion and validation run once after merging. Reloads publish only complete, validated snapshots.
Index ¶
- Variables
- func Decode[T any](s *Snapshot) (T, error)
- func LoadAs[T any](ctx context.Context, schema *sp.Schema, sources ...Source) (T, error)
- func Public(err error) error
- type Decoder
- type DegradedError
- type Edit
- type EditKind
- type Event
- type Layer
- type Loader
- type Location
- type Memory
- type Origin
- type Path
- type PublicError
- type ResilientOption
- type Runtime
- type Snapshot
- func (s *Snapshot) Baked() *sp.Baked
- func (s *Snapshot) Decode(target any) error
- func (s *Snapshot) Degraded() map[string]error
- func (s *Snapshot) Explain(path ...string) []Origin
- func (s *Snapshot) LoadedAt() time.Time
- func (s *Snapshot) Origins() map[string][]Origin
- func (s *Snapshot) Report() *sp.ResolveReport
- func (s *Snapshot) Revisions() map[string]string
- func (s *Snapshot) Validation() *sp.ValidationResult
- func (s *Snapshot) Version() uint64
- type Source
- type SourceError
- type SourceFunc
- type TypedRuntime
- type ValidationError
- type Watcher
Constants ¶
This section is empty.
Variables ¶
var ErrClosed = errors.New("xconf: runtime closed")
var ErrNotFound = errors.New("xconf: source not found")
Functions ¶
Types ¶
type Decoder ¶ added in v1.2.0
Decoder converts one document into an object and optional JSON-pointer locations. Decoders preserve numeric precision and do not apply schema defaults or validation. Each call must return independently owned data.
type DegradedError ¶ added in v1.4.0
DegradedError wraps a validation or typed decode failure that occurred while sources served stale layers, so recovery may resolve it. Degraded holds their raw errors (may contain secrets); Error() names the sources only.
func (*DegradedError) Error ¶ added in v1.4.0
func (e *DegradedError) Error() string
func (*DegradedError) Unwrap ¶ added in v1.4.0
func (e *DegradedError) Unwrap() error
type Event ¶ added in v1.2.0
Event carries the current valid snapshot, even after a failed reload. Changed paths are relative to the previous published version, not the last event a subscriber read. Slow subscribers receive the latest event, dropping intermediates.
type Layer ¶ added in v1.2.0
type Layer struct {
Values map[string]any
Revision string
Locations map[string]Location // keys are JSON pointers
Edits []Edit // applied in order after Values
// Stale reports a failing source: the layer is its last good one (or empty).
// The raw error is exposed only through Snapshot.Degraded.
Stale error
}
type Loader ¶ added in v1.2.0
type Loader struct {
// contains filtered or unexported fields
}
Loader holds an owned schema and compiled engine for repeated loads. Compile options (including custom formats and CEL cost limits) pass to schemapb.
type Memory ¶ added in v1.2.0
type Memory struct {
// contains filtered or unexported fields
}
Memory is a concurrent, watchable source useful for overrides and tests.
type Path ¶ added in v1.2.0
type Path []string
Path addresses an object member or list index. String returns a JSON pointer.
type PublicError ¶ added in v1.4.2
type PublicError struct{ Err error }
PublicError is a source error whose text names keys, paths or variables but never holds a configuration value, so SourceError shows it.
func (*PublicError) Error ¶ added in v1.4.2
func (e *PublicError) Error() string
func (*PublicError) Unwrap ¶ added in v1.4.2
func (e *PublicError) Unwrap() error
type ResilientOption ¶ added in v1.3.0
type ResilientOption func(*resilient)
func Backoff ¶ added in v1.3.0
func Backoff(min, max time.Duration) ResilientOption
Backoff bounds the retry delay, doubling from min to max. Default 1s..30s.
type Runtime ¶ added in v1.2.0
type Runtime struct {
// contains filtered or unexported fields
}
func (*Runtime) Close ¶ added in v1.2.0
Close cancels reads/watchers and waits for shutdown. Sources must honor context.
type Snapshot ¶ added in v1.2.0
type Snapshot struct {
// contains filtered or unexported fields
}
Snapshot owns immutable state. Accessors returning mutable data clone it.
func (*Snapshot) Degraded ¶ added in v1.3.0
Degraded returns the raw errors of sources serving stale layers, keyed by source name. It is empty when every source is healthy. Errors may contain secrets.
func (*Snapshot) Explain ¶ added in v1.2.0
Explain returns source writes followed by schema operations at this exact path. Records contain no values, including overridden values.
func (*Snapshot) Origins ¶ added in v1.2.2
Origins returns all provenance keyed by JSON pointer, including schema operations. The map and each history slice are independent copies. Records contain no values.
func (*Snapshot) Report ¶ added in v1.2.0
func (s *Snapshot) Report() *sp.ResolveReport
func (*Snapshot) Validation ¶ added in v1.2.0
func (s *Snapshot) Validation() *sp.ValidationResult
type Source ¶ added in v1.2.0
Source reads a complete partial layer. Read must honor ctx and return owned data (or data it will not mutate). The schema argument is an isolated copy. Sources must not apply schema defaults or require a complete configuration.
func AllowPaths ¶ added in v1.2.3
AllowPaths restricts a source to the given object/map paths and their subtrees. Segments are literal keys, not globs or dotted paths. No paths allows nothing; an empty Path allows everything. Paths are captured when the wrapper is made. Lists must be selected as a whole. Selecting a OneOf discriminator requires selecting its whole object, since changing it replaces the previous variant. Ancestor edits are projected onto allowed subtrees, preserving their siblings. Name, Revision, read errors and watch notifications pass through unchanged.
func Optional ¶ added in v1.2.0
Optional suppresses only ErrNotFound. Parse, permission and network errors fail.
func Poll ¶ added in v1.2.0
Poll adds periodic invalidation to a source. It does not cache failed reads.
func Resilient ¶ added in v1.3.0
func Resilient(source Source, opts ...ResilientOption) Source
Resilient keeps a remote source in effect while it is unavailable. Any Read error yields the last good layer (or an empty one) with Layer.Stale set, so the source never fails Open or Reload; Snapshot.Degraded reports it. While stale, the wrapper invalidates the runtime with exponential backoff until a Read succeeds. A failing inner Watch registration is retried in the background, followed by an invalidation to cover changes missed before it. ErrNotFound is a failure too; compose Resilient(Optional(source)) to treat a missing source as empty instead.
type SourceError ¶ added in v1.2.0
SourceError omits provider error text, which may contain secrets, unless the cause is a PublicError. The original error remains available via errors.Is/As/Unwrap.
func (*SourceError) Error ¶ added in v1.2.0
func (e *SourceError) Error() string
func (*SourceError) Unwrap ¶ added in v1.2.0
func (e *SourceError) Unwrap() error
type SourceFunc ¶ added in v1.2.0
SourceFunc adapts a custom reader. Name must be stable and unique in a loader.
func (SourceFunc) Name ¶ added in v1.2.0
func (s SourceFunc) Name() string
type TypedRuntime ¶ added in v1.2.0
TypedRuntime validates destination decoding before publishing each snapshot. Current returns a fresh value; callers can freely mutate its maps and slices.
func (*TypedRuntime[T]) Current ¶ added in v1.2.0
func (r *TypedRuntime[T]) Current() (T, error)
type ValidationError ¶ added in v1.2.0
type ValidationError struct {
Result *sp.ValidationResult
Report *sp.ResolveReport
}
ValidationError carries diagnostics without including input values in Error().
func (*ValidationError) Error ¶ added in v1.2.0
func (e *ValidationError) Error() string
Directories
¶
| Path | Synopsis |
|---|---|
|
contrib
|
|
|
decoders/json
module
|
|
|
decoders/toml
module
|
|
|
decoders/yaml
module
|
|
|
sources/consul
module
|
|
|
sources/directory
module
|
|
|
sources/dotenv
module
|
|
|
sources/env
module
|
|
|
sources/envfile
module
|
|
|
sources/etcd
module
|
|
|
sources/file
module
|
|
|
sources/flags
module
|
|
|
sources/fs
module
|
|
|
sources/http
module
|
|
|
sources/json
module
|
|
|
sources/kubernetes
module
|
|
|
sources/nats
module
|
|
|
sources/pflag
module
|
|
|
sources/reader
module
|
|
|
sources/s3
module
|
|
|
sources/toml
module
|
|
|
sources/vault
module
|
|
|
sources/yaml
module
|
|
|
internal
|
|
|
document
Package document contains shared bounded document reading for source adapters.
|
Package document contains shared bounded document reading for source adapters. |