Documentation
¶
Overview ¶
Package filewatcher provides a go implementation of baseplate's FileWatcher: https://baseplate.readthedocs.io/en/stable/api/baseplate/lib/file_watcher.html
Example ¶
This example demonstrates how to use filewatcher.
const (
// The path to the file.
path = "/opt/data.json"
// Timeout on the initial read.
timeout = time.Second * 30
)
// The type of the parsed data
type dataType map[string]any
// Wrap a json decoder as parser
parser := func(f io.Reader) (dataType, error) {
var data dataType
err := json.NewDecoder(f).Decode(&data)
return data, err
}
ctx, cancel := context.WithTimeout(context.Background(), timeout)
defer cancel()
data, err := filewatcher.New(ctx, path, parser)
if err != nil {
log.Fatal(err)
}
// Whenever you need to use the parsed data, just call data.Get():
_ = data.Get()
Index ¶
Examples ¶
Constants ¶
const ( // DefaultFSEventsDelay is the default FSEventsDelay used when creating a new // FileWatcher. DefaultFSEventsDelay = 1 * time.Second // DefaultPollingInterval is the default PollingInterval used when creating a // new FileWatcher. DefaultPollingInterval = 30 * time.Second // DefaultInitialReadInterval is the default InitialReadInterval used when // creating a new FileWatcher. DefaultInitialReadInterval = time.Second / 2 // DefaultMaxFileSize is the default MaxFileSize used when it's <= 0. // // It's 10 MiB, with hard limit multiplier of 10. DefaultMaxFileSize = 10 << 20 HardLimitMultiplier = 10 )
Default option values
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type DirParser ¶
A DirParser is a callback function that will be called when the watched directory has its content changed or is read for the first time.
Use WrapDirParser to wrap it into a Parser to be used with FileWatcher.
type FileWatcher ¶
type FileWatcher[T any] interface { // Close stops the FileWatcher // // After Close is called you won't get any updates on the file content, // but you can still call Get to get the last content before stopping. // // It's OK to call Close multiple times. // Calls after the first one are essentially no-op. // // Close never return an error. io.Closer // Get returns the latest, parsed data from the FileWatcher. Get() T }
FileWatcher loads and parses data from a file or directory, and watches for changes in order to refresh its stored data.
type Option ¶
type Option func(*opts)
Option used in New.
func WithFSEventsDelay ¶
WithFSEventsDelay sets the delay between receiving the fs events and actually reading and parsing the changes.
It's used to avoid short bursts of fs events (for example, when watching a directory) causing reading and parsing repetively.
Defaut to DefaultFSEventsDelay.
func WithFileSizeLimit ¶
WithFileSizeLimit sets the soft file size limit, with the hard limit being 10x (see HardLimitMultiplier) of the set soft limit.
This is completely ignored when DirParser is used.
If the soft limit is violated, the violation will be reported via slog at error level and prometheus counter of limitopen_softlimit_violation_total, but it does not stop the normal parsing process.
If the hard limit is violated, The loading of the file will fail immediately.
Default to DefaultMaxFileSize.
func WithInitialReadInterval ¶
WithInitialReadInterval sets the interval to keep retrying to open the file when creating a new FileWatcher, when the file was not initially available.
Default to DefaultInitialReadInterval.
func WithOptions ¶
WithOptions is a sugar to curry zero or more options.
func WithPollingInterval ¶
WithPollingInterval sets the interval to check file changes proactively.
Default to DefaultPollingInterval. To disable polling completely, set it to a negative value.
Without polling, filewatcher relies solely on fs events from the parent directory. This works for most cases but will not work in the cases that the parent directory will be remount upon change (for example, k8s ConfigMap).
type Parser ¶
A Parser is a callback function to be called when a watched file has its content changed, or is read for the first time.
func WrapDirParser ¶
WrapDirParser wraps a DirParser for a directory to a Parser.
When using FileWatcher to watch a directory instead of a single file, you MUST use WrapDirParser instead of any other Parser implementations.
type Result ¶
type Result[T any] struct { // contains filtered or unexported fields }
Result is the return type of New. Use Get function to get the actual data.
func New ¶
func New[T any](ctx context.Context, path string, parser Parser[T], options ...Option) (*Result[T], error)
New creates a new FileWatcher.
If the path is not available at the time of calling, it blocks until the file becomes available, or context is cancelled, whichever comes first.
func (*Result[T]) Close ¶
Close stops the FileWatcher.
After Close is called you won't get any updates on the file content, but you can still call Get to get the last content before stopping.
It's OK to call Close multiple times. Calls after the first one are essentially no-op.
Close never returns an error.
Source Files
Directories