Documentation
¶
Overview ¶
Package loader provides a file-system–based key loader with live updates.
It monitors a directory for resource files (such as signing keys), extracts a key identifier (KeyID) from file paths based on configurable rules, and stores the file contents in a key–value storage backend.
Typical use cases include:
- Cryptographic key management
- Dynamic configuration loading
- Hot-reloading of resources from disk
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