Documentation
¶
Overview ¶
Package loader provides a file-system based resource loader with live updates.
The loader watches one or more filesystem locations for resource files (for example: cryptographic keys, configuration blobs, certificates) and keeps an in-memory key->bytes storage synchronized with the file system. It supports configurable KeyID extraction strategies, optional extension filtering, recursive (subfolder) watching and event filtering.
Key concepts
- Location (path): a directory that the loader has been instructed to watch.
- KeyID: the identifier under which a file's contents are stored in the storage backend. The KeyID is derived from the file path using a configurable strategy (see KeyIDType).
- Storage: a pluggable key->[]byte storage implementing keyvalue.StringToBytesStorage. By default, an in-memory storage is used.
- Watcher: a filesystem watcher (fsnotify based) that forwards events to the loader so it can add/update/remove resources in storage.
Behavior
- On Start the loader performs an initial scan of all configured locations and loads every file that matches the configured rules into storage.
- Subsequent file system events (create/write/remove/rename by default) are processed and the storage is updated accordingly.
- Files that are directories, unreadable, empty or that do not match the KeyID extraction rules are skipped.
- Temporary editors that create files with suffix "~" are handled: the trailing "~" is ignored for both the file path and the computed KeyID.
Typical usage
ldr, err := Create(
OnPath("/etc/keys"),
WithExtension(".pem"),
WithKeyIDType(FileNameWithoutExtension),
)
if err != nil { ... }
if err := ldr.Start(); err != nil { ... }
defer ldr.Close()
The package is suitable for hot-reloading workloads where files on disk represent resources that should be immediately reflected in memory.
Index ¶
- Variables
- type KeyIDType
- type Loader
- type Option
- func ForOperations(ops ...fsnotify.Op) Option
- func OnPath(path string) Option
- func OnPaths(paths ...string) Option
- func WatchSubfolders(enabled bool) Option
- func WithExtension(value string) Option
- func WithKeyIDType(value KeyIDType) Option
- func WithStorage(storage keyvalue.StringToBytesStorage) Option
Constants ¶
This section is empty.
Variables ¶
var ( // ErrStorageNotSpecified is returned when a nil storage is passed to WithStorage. ErrStorageNotSpecified = errors.New("storage not specified") )
Functions ¶
This section is empty.
Types ¶
type KeyIDType ¶
type KeyIDType uint32
KeyIDType defines how the loader generates Key IDs from file paths.
Different strategies are available depending on how keys should be identified.
const ( // FileNameWithoutExtension uses the base file name without its extension // as the Key ID. // // Example: // Path: /tmp/keys/signing.pem // Extension: .pem // KeyID: signing FileNameWithoutExtension KeyIDType = 1 << iota // FileNameWithExtension uses the base file name including its extension // as the Key ID. // // Example: // Path: /tmp/keys/signing.pem // KeyID: signing.pem FileNameWithExtension // FileFullPathRelativeToLocation uses the file path relative to the // configured root location as the Key ID. // // Example: // Location: /tmp/keys // Path: /tmp/keys/sub/key.pem // KeyID: /sub/key.pem FileFullPathRelativeToLocation // FileFullPath uses the absolute file path as the Key ID. // // Example: // Path: /tmp/keys/sub/key.pem // KeyID: /tmp/keys/sub/key.pem FileFullPath )
type Loader ¶
type Loader struct {
// contains filtered or unexported fields
}
Loader watches a directory for resource files and maintains a key–value store of file contents, indexed by Key IDs.
func Create ¶
Create initializes a Loader that watches the given location for files.
Options may be provided to customize KeyID extraction, file extension handling, and storage backend.
Example:
ldr, err := loader.Create(
"/etc/keys",
loader.WithExtension(".pem"),
loader.WithKeyIDType(loader.FileNameWithoutExtension),
)
if err != nil {
log.Fatal(err)
}
if err := ldr.Start(); err != nil {
log.Fatal(err)
}
defer ldr.Close()
func (*Loader) AddPath ¶ added in v1.4.4
AddPath adds a new path to the notifier. It must be called before Start. The path must exist on the filesystem, otherwise an error is returned.
func (*Loader) Close ¶ added in v1.4.4
Close stops the watcher and releases resources. Safe to call multiple times.
func (*Loader) Start ¶ added in v1.4.4
Start starts the file system watcher and performs an initial load of all resources.
Returns an error if the watcher cannot be started or if resources cannot be loaded.
func (*Loader) Storage ¶
func (l *Loader) Storage() keyvalue.ReadOnlyStringToBytesStorage
Storage returns a read-only view of the Loader’s storage. Consumers can use this to retrieve key data without modifying the internal storage.
type Option ¶
Option represents a configuration option for Loader.
func ForOperations ¶ added in v1.4.4
ForOperations returns an Option that configures a Loader to only consider specific filesystem operations for triggering events.
The provided operations (ops) are combined into a set. Only events matching one of these operations will be processed by the Loader. Supported operations are defined in fsnotify.Op:
fsnotify.Create, fsnotify.Write, fsnotify.Remove, fsnotify.Rename, fsnotify.Chmod
This Option can be passed to a Loader during creation to filter events according to your requirements.
func WatchSubfolders ¶ added in v1.4.4
WatchSubfolders enables or disables recursive monitoring of subfolders.
By default, fsnotify does not watch subfolders of a directory automatically. When enabled, this option ensures that all nested directories are included in the watch scope, so events such as file creation, modification, renaming, or deletion inside subdirectories will also be detected. Parameters:
- enabled: set to true to include subfolders in the watch, false to restrict watching only to the top-level directory.
func WithExtension ¶
WithExtension configures the file extension that identifies relevant files.
If the extension is missing a leading ".", it will be added automatically. The extension must not be empty, otherwise ErrExtensionIsEmpty is returned.
This option is only used when KeyIDType is FileNameWithoutExtension.
func WithKeyIDType ¶
WithKeyIDType configures the KeyID extraction strategy. The default KeyIDType is FileFullPath.
func WithStorage ¶
func WithStorage(storage keyvalue.StringToBytesStorage) Option
WithStorage configures the storage backend used by Loader.
If storage is nil, ErrStorageNotSpecified is returned. By default, an in-memory storage is used.
Source Files