Documentation
¶
Overview ¶
Package config provides runtime configuration entries and store interface.
Index ¶
- Constants
- func DescribeValue(v any) string
- func KnownType(t string) bool
- func ParseBool(s string) (bool, error)
- func ParseFloat(s string) (float64, error)
- func ParseInt(s string) (int, error)
- func ValidateValue(valueType string, v any) error
- type Entry
- type EntryVersion
- type ListOpts
- type Service
- func (s *Service) Bool(ctx context.Context, key string, defaultVal bool) bool
- func (s *Service) Delete(ctx context.Context, key, appID string) error
- func (s *Service) Duration(ctx context.Context, key string, defaultVal time.Duration) time.Duration
- func (s *Service) Float(ctx context.Context, key string, defaultVal float64) float64
- func (s *Service) Get(ctx context.Context, key, appID string) (*Entry, error)
- func (s *Service) Int(ctx context.Context, key string, defaultVal int) int
- func (s *Service) JSON(ctx context.Context, key string, target any) error
- func (s *Service) List(ctx context.Context, appID string, opts ListOpts) ([]*Entry, error)
- func (s *Service) Notify(ctx context.Context, key string, oldValue, newValue any)
- func (s *Service) Set(ctx context.Context, key string, value any, appID string, opts ...SetOption) error
- func (s *Service) String(ctx context.Context, key, defaultVal string) string
- func (s *Service) Watch(key string, cb WatchCallback)
- type ServiceOption
- type SetOption
- type Store
- type ValidationError
- type ValueResolver
- type WatchCallback
Constants ¶
const ( TypeString = "string" TypeInt = "int" TypeFloat = "float" TypeBool = "bool" TypeJSON = "json" TypeDuration = "duration" )
The value types a config entry can carry and the write service accepts. Entry.ValueType is a free-form label in the store, so an entry stored with any other label is read-only to the write service.
Variables ¶
This section is empty.
Functions ¶
func DescribeValue ¶
DescribeValue names v's kind ("a string", "an object", "null") without echoing its value, which for a bad value could be anything the caller sent. It is what the write service uses to word a refusal.
func ParseFloat ¶
ParseFloat tries to parse a string as a float64.
func ValidateValue ¶
ValidateValue reports whether v is an acceptable value for an entry of type valueType. No backend checks: an int entry holding "abc" is stored happily, and every typed read then silently answers the caller's fallback.
A value that arrives through JSON is a float64, so int accepts a float64 with no fractional part, up to 2^53 in magnitude, as well as any Go integer. duration is a string time.ParseDuration accepts. nil is refused for every type except json, where it is the JSON null.
An unknown valueType returns a *ValidationError naming "valueType". Any other refusal is a plain error describing the value; the caller knows which field it came from and wraps it.
Types ¶
type Entry ¶
type Entry struct {
core.Entity
ID id.ID `json:"id"`
Key string `json:"key"`
Value any `json:"value"`
ValueType string `json:"value_type"`
Version int64 `json:"version"`
Description string `json:"description"`
AppID string `json:"app_id"`
Metadata map[string]string `json:"metadata,omitempty"`
}
Entry represents a runtime configuration entry.
type EntryVersion ¶
type EntryVersion struct {
ID id.ID `json:"id"`
ConfigKey string `json:"config_key"`
AppID string `json:"app_id"`
Version int64 `json:"version"`
Value any `json:"value"`
CreatedBy string `json:"created_by"`
CreatedAt time.Time `json:"created_at"`
}
EntryVersion represents a historical version of a config entry.
type ListOpts ¶
type ListOpts struct {
Limit int
Offset int
AppID string
// KeyPrefix restricts the list to keys that start with it, matched as a
// literal: %, _ and regex characters carry no special meaning. Empty
// means every key.
KeyPrefix string
}
ListOpts configures list queries for config entries.
type Service ¶
type Service struct {
// contains filtered or unexported fields
}
Service provides type-safe config reading, writing, and watch support.
func NewService ¶
func NewService(store Store, opts ...ServiceOption) *Service
NewService creates a config service.
func (*Service) Bool ¶
Bool returns a boolean config value. Returns defaultVal on error or type mismatch.
func (*Service) Duration ¶
Duration returns a time.Duration config value. Returns defaultVal on error or type mismatch. Parses from a string using time.ParseDuration (e.g. "5s", "1m30s").
func (*Service) Float ¶
Float returns a float64 config value. Returns defaultVal on error or type mismatch. Handles float64, int, and int64.
func (*Service) Int ¶
Int returns an integer config value. Returns defaultVal on error or type mismatch. Handles int, float64 (from JSON), and int64.
func (*Service) JSON ¶
JSON reads a config value and unmarshals it into target. target must be a pointer. Returns an error if the config is not found or the value cannot be converted to JSON and unmarshaled into target.
func (*Service) Notify ¶
Notify runs the watchers registered for key, exactly as Set does after a write. It exists for the write service (package configmgr), which writes through the store itself and so must tell watchers what changed: oldValue is nil for a create, newValue nil for a delete.
func (*Service) Set ¶
func (s *Service) Set(ctx context.Context, key string, value any, appID string, opts ...SetOption) error
Set creates or updates a config entry, auto-versioning on update.
func (*Service) String ¶
String returns a string config value. Returns defaultVal on error or type mismatch.
func (*Service) Watch ¶
func (s *Service) Watch(key string, cb WatchCallback)
Watch registers a callback that fires when the given config key is updated via Set.
type ServiceOption ¶
type ServiceOption func(*Service)
ServiceOption configures the Service.
func WithAppID ¶
func WithAppID(appID string) ServiceOption
WithAppID sets the default app ID for the config service.
func WithResolver ¶
func WithResolver(r ValueResolver) ServiceOption
WithResolver sets the override resolver for tenant-aware config resolution.
type SetOption ¶
type SetOption func(*setConfig)
SetOption configures a Set operation.
func WithDescription ¶
WithDescription sets the description on the config entry.
func WithMetadata ¶
WithMetadata sets metadata on the config entry.
func WithValueType ¶
WithValueType sets an explicit value type label (e.g. "string", "int", "json").
type Store ¶
type Store interface {
// GetConfig retrieves a config entry by key and app ID.
GetConfig(ctx context.Context, key, appID string) (*Entry, error)
// SetConfig creates or updates a config entry. A new version is created on update.
SetConfig(ctx context.Context, e *Entry) error
// DeleteConfig removes a config entry.
DeleteConfig(ctx context.Context, key, appID string) error
// ListConfig returns the config entries for an app in key order, filtered
// by opts.KeyPrefix and then paged. An empty result is an empty slice,
// never nil.
ListConfig(ctx context.Context, appID string, opts ListOpts) ([]*Entry, error)
// GetConfigVersion retrieves a specific version of a config entry.
GetConfigVersion(ctx context.Context, key, appID string, version int64) (*Entry, error)
// ListConfigVersions returns all versions of a config entry.
ListConfigVersions(ctx context.Context, key, appID string) ([]*EntryVersion, error)
// CountConfig returns the total number of config entries for an app,
// independent of any paging.
CountConfig(ctx context.Context, appID string) (int64, error)
// CountConfigMatching returns the number of config entries for an app
// that match opts.KeyPrefix. Limit and Offset are ignored, so it is the
// total behind a page returned by ListConfig with the same opts.
CountConfigMatching(ctx context.Context, appID string, opts ListOpts) (int64, error)
}
Store defines the persistence interface for runtime configuration.
type ValidationError ¶
ValidationError is a refusal of caller input. Field names the part of the request at fault in the wire's own spelling, so a handler can hand it straight to the client.
func (*ValidationError) Error ¶
func (e *ValidationError) Error() string
Error returns "config: <field>: <message>".
Source Files