config

package
v1.0.78 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Dec 14, 2025 License: Apache-2.0 Imports: 28 Imported by: 0

Documentation

Overview

Package config provides configuration loading and management utilities with support for file and KV store backends.

Index

Constants

View Source 
const WatcherSnapshotTTL = 5 * time.Minute

WatcherSnapshotTTL is the freshness window used by the admin APIs to treat watcher snapshots as "alive".

Variables

View Source 
var (
	// ErrDstMustBeNonNilPointer indicates that the destination must be a non-nil pointer.
	ErrDstMustBeNonNilPointer = errors.New("dst must be a non-nil pointer")
	// ErrDstMustBePointerToStruct indicates that the destination must be a pointer to a struct.
	ErrDstMustBePointerToStruct = errors.New("dst must be a pointer to a struct")
)

Functions

func ContextWithWatcher added in v1.0.55 

func ContextWithWatcher(ctx context.Context, watcherID string) context.Context

ContextWithWatcher annotates a context with the watcher ID.

func FieldsChangedByTag added in v1.0.55 

func FieldsChangedByTag(old, new interface{}, tag string, triggers map[string]bool) []string

FieldsChangedByTag returns a list of struct field names whose tag matches any value in triggers and whose values differ between old and new. Only compares top-level exported fields.

func LoadAndOverlayOrExit added in v1.0.55 

func LoadAndOverlayOrExit(ctx context.Context, kvMgr *KVManager, cfgLoader *Config, configPath string, cfg interface{}, errorMsg string)

LoadAndOverlayOrExit loads config and exits with cleanup on error

func MarkWatcherEvent added in v1.0.55 

func MarkWatcherEvent(id string, err error)

MarkWatcherEvent updates the last event timestamp for a watcher.

func MarkWatcherStopped added in v1.0.55 

func MarkWatcherStopped(id string, err error)

MarkWatcherStopped marks the watcher as stopped and records the last error if present.

func MergeOverlayBytes added in v1.0.55 

func MergeOverlayBytes(dst interface{}, overlay []byte) error

MergeOverlayBytes deep-merges a JSON document onto an existing config struct in memory. Fields present in overlay override destination; others remain unchanged.

func NewKVServiceClientFromEnv added in v1.0.55 

func NewKVServiceClientFromEnv(ctx context.Context, role models.ServiceRole) (proto.KVServiceClient, func() error, error)

NewKVServiceClientFromEnv dials the remote KV service using environment variables suitable for the given role. Returns nil without error when the environment is not configured for KV access.

func NewNATSClientFromEnv added in v1.0.55 

func NewNATSClientFromEnv(ctx context.Context, role models.ServiceRole) (kv.KVStore, error)

NewNATSClientFromEnv creates a direct NATS KV client from environment variables.

func NormalizeTLSPaths 

func NormalizeTLSPaths(tls *models.TLSConfig, certDir string)

NormalizeTLSPaths is a convenience function that normalizes TLS paths with default logging. This function exists for backward compatibility with existing code.

func RegisterWatcher added in v1.0.55 

func RegisterWatcher(reg WatcherRegistration) string

RegisterWatcher records watcher metadata and returns a watcher ID.

func ResetWatchersForTest added in v1.0.55 

func ResetWatchersForTest()

ResetWatchersForTest exposes a safe way for other packages to clear watcher state in tests.

func SanitizeTOML added in v1.0.55 

func SanitizeTOML(data []byte, deny []TOMLPath) []byte

SanitizeTOML drops lines containing sensitive keys from a TOML document without needing a full parser. It handles basic table headers ([table]) and key/value pairs (key = value). Multiline strings or inline tables are preserved unless the first line contains a denied key.

func SetWatcherUpdateHook added in v1.0.55 

func SetWatcherUpdateHook(fn func(info WatcherInfo))

SetWatcherUpdateHook registers a callback invoked whenever watcher state changes.

func ShouldUseKVFromEnv added in v1.0.55 

func ShouldUseKVFromEnv() bool

ShouldUseKVFromEnv reports whether the current environment is configured for KV-backed configuration.

func StartKVWatchLog added in v1.0.55 

func StartKVWatchLog(ctx context.Context, kvStore cfgkv.KVStore, key string, log logger.Logger)

StartKVWatchLog watches a KV key and logs when it changes. It owns the kvStore lifecycle: it will Close() it when ctx is done.

func StartKVWatchOverlay added in v1.0.55 

func StartKVWatchOverlay(ctx context.Context, kvStore cfgkv.KVStore, key string, dst interface{}, log logger.Logger, onChange func())

StartKVWatchOverlay watches a KV key and overlays JSON config bytes onto dst when updates arrive. If onChange is not nil, it is invoked after a successful merge. It also attempts an initial merge with the current KV value if present.

func TemplateStorageKey added in v1.0.55 

func TemplateStorageKey(desc ServiceDescriptor) string

TemplateStorageKey returns the canonical KV location for storing a descriptor's default template.

func ValidateConfig 

func ValidateConfig(cfg interface{}) error

ValidateConfig validates a configuration if it implements Validator.

func WatcherSnapshotKey added in v1.0.55 

func WatcherSnapshotKey(service, instanceID string) (string, error)

WatcherSnapshotKey returns the canonical KV key for a watcher record.

Types

type Config 

type Config struct {
	// contains filtered or unexported fields
}

Config holds the configuration loading dependencies.

func NewConfig 

func NewConfig(log logger.Logger) *Config

NewConfig initializes a new Config instance with a default file loader and logger. If logger is nil, creates a basic logger for config loading.

func (*Config) LoadAndValidate 

func (c *Config) LoadAndValidate(ctx context.Context, path string, cfg interface{}) error

LoadAndValidate loads a configuration, normalizes SecurityConfig paths if present, and validates it.

func (*Config) OverlayFromKV added in v1.0.55 

func (c *Config) OverlayFromKV(ctx context.Context, path string, dst interface{}) error

OverlayFromKV loads the config from KV and overlays it onto dst (which should already contain the file-loaded configuration). KV values override only the fields present in KV. If KV is not configured or the key is not found, this is a no-op.

func (*Config) OverlayPinned added in v1.0.55 

func (c *Config) OverlayPinned(ctx context.Context, pinnedPath string, cfg interface{}) error

OverlayPinned applies a pinned configuration file on top of the existing config. Fields present in the pinned file take precedence over both defaults and KV overlays.

func (*Config) SetKVStore 

func (c *Config) SetKVStore(store kv.KVStore)

SetKVStore sets the KV store to be used when CONFIG_SOURCE=kv.

type ConfigFormat added in v1.0.55 

type ConfigFormat string

ConfigFormat identifies how a service persists its configuration. 

const (
	ConfigFormatJSON ConfigFormat = "json"
	ConfigFormatTOML ConfigFormat = "toml"
)

func TemplateStorageKeyFor added in v1.0.55 

func TemplateStorageKeyFor(name string) (string, ConfigFormat, bool)

TemplateStorageKeyFor returns the template storage key for the provided descriptor name, if known.

type ConfigLoader 

type ConfigLoader interface {
	Load(ctx context.Context, path string, dst interface{}) error
}

Loader interface for loading configurations from various sources.

type ConfigScope added in v1.0.55 

type ConfigScope string

ConfigScope describes how a service scopes its configuration. 

const (
	ConfigScopeGlobal ConfigScope = "global"
	ConfigScopePoller ConfigScope = "poller"
	ConfigScopeAgent  ConfigScope = "agent"
)

type EnvConfigLoader added in v1.0.55 

type EnvConfigLoader struct {
	// contains filtered or unexported fields
}

EnvConfigLoader loads configuration from environment variables. It supports nested struct fields using underscore separation (e.g., CNPG_HOST maps to config.cnpg.host).

func NewEnvConfigLoader added in v1.0.55 

func NewEnvConfigLoader(log logger.Logger, prefix string) *EnvConfigLoader

NewEnvConfigLoader creates a new environment variable config loader.

func (*EnvConfigLoader) Load added in v1.0.55 

func (e *EnvConfigLoader) Load(_ context.Context, _ string, dst interface{}) error

Load implements ConfigLoader by reading from environment variables.

type FileConfigLoader 

type FileConfigLoader struct {
	// contains filtered or unexported fields
}

FileConfigLoader loads configuration from a local JSON file.

func (*FileConfigLoader) Load 

func (f *FileConfigLoader) Load(_ context.Context, path string, dst interface{}) error

Load implements ConfigLoader by reading and unmarshaling a JSON file.

type KVConfigLoader 

type KVConfigLoader struct {
	// contains filtered or unexported fields
}

KVConfigLoader loads configuration from a KV store.

func NewKVConfigLoader 

func NewKVConfigLoader(store kv.KVStore, log logger.Logger) *KVConfigLoader

NewKVConfigLoader creates a new KVConfigLoader with the given KV store and logger.

func (*KVConfigLoader) Load 

func (k *KVConfigLoader) Load(ctx context.Context, path string, dst interface{}) error

Load implements ConfigLoader by fetching and unmarshaling data from the KV store.

type KVManager added in v1.0.55 

type KVManager struct {
	// contains filtered or unexported fields
}

KVManager handles KV store operations for configuration management

func NewKVManagerFromEnv added in v1.0.55 

func NewKVManagerFromEnv(ctx context.Context, role models.ServiceRole) (*KVManager, error)

NewKVManagerFromEnv creates a KV manager from environment variables.

func NewKVManagerFromEnvWithRetry added in v1.0.55 

func NewKVManagerFromEnvWithRetry(ctx context.Context, role models.ServiceRole, log logger.Logger) (*KVManager, error)

NewKVManagerFromEnvWithRetry blocks until a KV manager can be created or the configured timeout expires.

func (*KVManager) BootstrapConfig added in v1.0.55 

func (m *KVManager) BootstrapConfig(ctx context.Context, kvKey string, configPath string, cfg interface{}) error

BootstrapConfig stores default config in KV if it doesn't exist. It prefers reading sanitized defaults from the on-disk config file to keep the canonical KV copy aligned with baked manifests.

func (*KVManager) Close added in v1.0.55 

func (m *KVManager) Close() error

Close closes the KV client connection

func (*KVManager) LoadAndOverlay added in v1.0.55 

func (m *KVManager) LoadAndOverlay(ctx context.Context, cfgLoader *Config, configPath string, cfg interface{}) error

LoadAndOverlay loads config from file and overlays KV values

func (*KVManager) OverlayConfig added in v1.0.55 

func (m *KVManager) OverlayConfig(ctx context.Context, kvKey string, cfg interface{}) error

OverlayConfig merges the KV entry identified by kvKey onto the provided config struct.

func (*KVManager) PublishWatcherSnapshot added in v1.0.55 

func (m *KVManager) PublishWatcherSnapshot(ctx context.Context, info WatcherInfo) error

PublishWatcherSnapshot stores watcher metadata in KV so that remote processes can read it.

func (*KVManager) Put added in v1.0.55 

func (m *KVManager) Put(ctx context.Context, key string, value []byte, ttl time.Duration) error

Put writes arbitrary data to the backing KV store using the manager's credentials.

func (*KVManager) PutIfAbsent added in v1.0.55 

func (m *KVManager) PutIfAbsent(ctx context.Context, key string, value []byte, ttl time.Duration) (bool, error)

PutIfAbsent writes the provided value only if the key does not already exist. Returns true when the key was created.

func (*KVManager) RepairConfigPlaceholders added in v1.0.55 

func (m *KVManager) RepairConfigPlaceholders(ctx context.Context, desc ServiceDescriptor, configPath string, cfg interface{}) error

RepairConfigPlaceholders overwrites placeholder KV values with the sanitized config file defaults. It only mutates the KV entry when descriptor-critical fields still contain obvious placeholder values such as localhost bindings. This keeps the operation idempotent for real operator edits.

func (*KVManager) SetupConfigLoader added in v1.0.55 

func (m *KVManager) SetupConfigLoader(cfgLoader *Config)

SetupConfigLoader configures a Config instance with KV store if available

func (*KVManager) StartWatch added in v1.0.55 

func (m *KVManager) StartWatch(ctx context.Context, kvKey string, cfg interface{}, logger logger.Logger, onReload func())

StartWatch sets up KV watching with hot-reload functionality.

func (*KVManager) StartWatchWithPinned added in v1.0.55 

func (m *KVManager) StartWatchWithPinned(ctx context.Context, kvKey string, cfg interface{}, logger logger.Logger, pinnedPath string, cfgLoader *Config, onReload func())

StartWatchWithPinned watches KV updates and reapplies the pinned config on every change. pinnedPath should point to the pinned overlay file; cfgLoader is used for validation/normalization.

type KeyContext added in v1.0.55 

type KeyContext struct {
	AgentID  string
	PollerID string
}

KeyContext supplies identity information used to resolve scoped KV keys.

type ServiceDescriptor added in v1.0.55 

type ServiceDescriptor struct {
	Name           string
	DisplayName    string
	ServiceType    string
	Scope          ConfigScope
	KVKey          string
	KVKeyTemplate  string
	Format         ConfigFormat
	CriticalFields []string
}

ServiceDescriptor captures metadata about a managed service configuration.

func ServiceDescriptorByType added in v1.0.55 

func ServiceDescriptorByType(serviceType string, scope ConfigScope) (ServiceDescriptor, bool)

ServiceDescriptorByType returns the descriptor matching a service type within the provided scope.

func ServiceDescriptorFor added in v1.0.55 

func ServiceDescriptorFor(name string) (ServiceDescriptor, bool)

ServiceDescriptorFor returns the descriptor for a named service if it exists.

func ServiceDescriptors added in v1.0.55 

func ServiceDescriptors() []ServiceDescriptor

ServiceDescriptors returns the known service descriptors in deterministic order.

func (ServiceDescriptor) ResolveKVKey added in v1.0.55 

func (sd ServiceDescriptor) ResolveKVKey(ctx KeyContext) (string, error)

ResolveKVKey returns the KV key for the descriptor within the provided context.

type TOMLPath added in v1.0.55 

type TOMLPath struct {
	Table string
	Key   string
}

TOMLPath identifies a specific key inside an optional table (e.g. table="outputs.prometheus", key="token"). Use Table="*" to match keys in any table or Key="*" to drop an entire table.

type Validator 

type Validator interface {
	Validate() error
}

Validator interface for configurations that need validation.

type WatcherInfo added in v1.0.55 

type WatcherInfo struct {
	ID         string        `json:"id"`
	Service    string        `json:"service"`
	InstanceID string        `json:"instance_id"`
	Scope      ConfigScope   `json:"scope"`
	KVKey      string        `json:"kv_key"`
	StartedAt  time.Time     `json:"started_at"`
	LastEvent  time.Time     `json:"last_event,omitempty"`
	Status     WatcherStatus `json:"status"`
	LastError  string        `json:"last_error,omitempty"`
}

WatcherInfo exposes runtime metadata for an active watcher.

func ListWatchers added in v1.0.55 

func ListWatchers() []WatcherInfo

ListWatchers returns a snapshot of registered watchers.

type WatcherRegistration added in v1.0.55 

type WatcherRegistration struct {
	Service string
	Scope   ConfigScope
	KVKey   string
	// InstanceID uniquely identifies the process publishing watcher state (agent_id, poller_id, etc.)
	InstanceID string
}

WatcherRegistration describes metadata recorded for a KV watcher.

type WatcherSnapshot added in v1.0.55 

type WatcherSnapshot struct {
	WatcherInfo
	UpdatedAt time.Time `json:"updated_at"`
}

WatcherSnapshot is the serialized representation stored in KV.

type WatcherStatus added in v1.0.55 

type WatcherStatus string

WatcherStatus captures the current state for a KV watcher. 

const (
	WatcherStatusRunning WatcherStatus = "running"
	WatcherStatusStopped WatcherStatus = "stopped"
	WatcherStatusError   WatcherStatus = "error"
)

Source Files

View all Source files

Directories

Path Synopsis
Package kv provides interfaces for key-value store configuration management.
 Package kv provides interfaces for key-value store configuration management.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.