Documentation
¶
Overview ¶
Package filewatcher provides a go implementation of baseplate's FileWatcher: https://baseplate.readthedocs.io/en/stable/baseplate/file_watcher.html
Example ¶
This example demonstrates how to use filewatcher.
package main
import (
"context"
"encoding/json"
"io"
"time"
"github.com/reddit/baseplate.go/filewatcher"
"github.com/reddit/baseplate.go/log"
)
func main() {
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]interface{}
// Wrap a json decoder as parser
parser := func(f io.Reader) (interface{}, 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,
filewatcher.Config{
Path: path,
Parser: parser,
Logger: log.ErrorWithSentryWrapper(),
},
)
if err != nil {
log.Fatal(err)
}
getData := func() dataType {
return data.Get().(dataType)
}
// Whenever you need to use the parsed data, just call getData():
_ = getData()
}
Output:
Index ¶
Examples ¶
Constants ¶
const DefaultMaxFileSize = 1024 * 1024
DefaultMaxFileSize is the default MaxFileSize used when it's <= 0.
It's 1MiB, which is following the size limit of Apache ZooKeeper nodes.
Variables ¶
var InitialReadInterval = time.Second / 2
InitialReadInterval is the interval to keep retrying to open the file when creating a new file watcher, when the file was not initially available.
It's intentionally defined as a variable instead of constant, so that the caller can tweak its value when needed.
Functions ¶
This section is empty.
Types ¶
type Config ¶
type Config struct {
// The path to the file to be watched, required.
Path string
// The parser to parse the data load, required.
Parser Parser
// Optional. When non-nil, it will be used to log errors,
// either returned by parser or by the underlying file system watcher.
// Please note that this does not include errors returned by the first parser
// call, which will be returned directly.
Logger log.Wrapper
// Optional. When <=0 DefaultMaxFileSize will be used instead.
// This limits the size of the file that will be read into memory and sent to
// the parser, to limit memory usage.
// If the file content is larger than MaxFileSize,
// we don't treat that as an error,
// but the parser will only receive the first MaxFileSize bytes of content.
//
// The reasons behind the decision of not treating them as an error are:
// 1. Some parsers only read up to what they need (example: json),
// so extra garbage after that won't cause any problems.
// 2. For parsers that won't work when they only receive partial data,
// this will cause them to return an error,
// which will be logged and we won't update the parsed data,
// so it's essentially the same as treating those as errors.
// 3. Getting the real size of the content without actually reading them could
// be tricky. Only send partial data to parsers is a more robust solution.
MaxFileSize int64
}
Config defines the config to be used in New function.
type FileWatcher ¶ added in v0.2.1
type FileWatcher interface {
// Get returns the latest, parsed data from the FileWatcher.
Get() interface{}
// Stop stops the FileWatcher.
//
// After Stop 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 Stop multiple times.
// Calls after the first one are essentially no-op.
Stop()
}
FileWatcher loads and parses data from a file and watches for changes to that file in order to refresh it's stored data.
type MockFileWatcher ¶ added in v0.2.1
type MockFileWatcher struct {
// contains filtered or unexported fields
}
MockFileWatcher is an implementation of FileWatcher that does not actually read from a file, it simply returns the data given to it when it was initialized with NewMockFilewatcher. It provides an additional Update method that allows you to update this data after it has been created.
func NewMockFilewatcher ¶ added in v0.2.1
func NewMockFilewatcher(r io.Reader, parser Parser) (*MockFileWatcher, error)
NewMockFilewatcher returns a pointer to a new MockFileWatcher object initialized with the given io.Reader and Parser.
func (*MockFileWatcher) Get ¶ added in v0.2.1
func (fw *MockFileWatcher) Get() interface{}
Get returns the parsed data.
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.
Please note that Parser should always return the consistent type. Inconsistent type will cause panic, as does returning nil data and nil error.
type Result ¶
type Result struct {
// contains filtered or unexported fields
}
Result is the return type of New. Use Get function to get the actual data.
func New ¶
New creates a new file watcher.
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.
When logger is non-nil, it will be used to log errors, either returned by parser or by the underlying file system watcher. Please note that this does not include errors returned by the first parser call, which will be returned directly.
Source Files