filevar

Documentation

Overview

Package filevar provides a runtimevar implementation with variables backed by the filesystem. Use OpenVariable to construct a *runtimevar.Variable.

Configuration files can be updated using any commands (cp, mv) or tools/editors. This package does not guarantee read consistency since it does not have control over the writes. For example, some kinds of updates might result in filevar temporarily receiving an error or an empty value.

Known Issues:

• On macOS, if an empty file is copied into a configuration file, filevar will not detect the change.

URLs

For runtimevar.OpenVariable, filevar registers for the scheme "file". To customize the URL opener, or for more details on the URL format, see URLOpener. See https://github.com/eliben/gocdkx/concepts/urls/ for background information.

As

filevar does not support any types for As.

Example

package main

import (
	"context"
	"fmt"
	"io/ioutil"
	"log"

	"github.com/eliben/gocdkx/runtimevar"
	"github.com/eliben/gocdkx/runtimevar/filevar"
)

// MyConfig is a sample configuration struct.
type MyConfig struct {
	Server string
	Port   int
}

func main() {
	// Create a temporary file to hold our config.
	f, err := ioutil.TempFile("", "")
	if err != nil {
		log.Fatal(err)
	}
	if _, err := f.Write([]byte(`{"Server": "foo.com", "Port": 80}`)); err != nil {
		log.Fatal(err)
	}

	// Create a decoder for decoding JSON strings into MyConfig.
	decoder := runtimevar.NewDecoder(MyConfig{}, runtimevar.JSONDecode)

	// Construct a *runtimevar.Variable pointing at f.
	v, err := filevar.OpenVariable(f.Name(), decoder, nil)
	if err != nil {
		log.Fatal(err)
	}
	defer v.Close()

	// We can now read the current value of the variable from v.
	snapshot, err := v.Latest(context.Background())
	if err != nil {
		log.Fatal(err)
	}
	cfg := snapshot.Value.(MyConfig)
	fmt.Printf("%s running on port %d", cfg.Server, cfg.Port)

}

Output:

foo.com running on port 80

Example (OpenVariable)

package main

import (
	"context"
	"log"

	"github.com/eliben/gocdkx/runtimevar"
)

func main() {
	// OpenVariable creates a *runtimevar.Variable from a URL.
	ctx := context.Background()
	v, err := runtimevar.OpenVariable(ctx, "file:///path/to/config.json?decoder=json")
	if err != nil {
		log.Fatal(err)
	}

	snapshot, err := v.Latest(ctx)
	_, _ = snapshot, err
}

Index

• Constants
• func OpenVariable(path string, decoder *runtimevar.Decoder, opts *Options) (*runtimevar.Variable, error)
• type Options
• type URLOpener
  • func (o *URLOpener) OpenVariableURL(ctx context.Context, u *url.URL) (*runtimevar.Variable, error)

Examples

• Package
• Package (OpenVariable)

Constants

const Scheme = "file"

Scheme is the URL scheme filevar registers its URLOpener under on runtimevar.DefaultMux.

Functions

func OpenVariable

func OpenVariable(path string, decoder *runtimevar.Decoder, opts *Options) (*runtimevar.Variable, error)

OpenVariable constructs a *runtimevar.Variable backed by the file at path. The file holds raw bytes; provide a decoder to decode the raw bytes into the appropriate type for runtimevar.Snapshot.Value. See the runtimevar package documentation for examples of decoders.

Types

type Options

type Options struct {
	// WaitDuration controls the frequency of retries after an error. For example,
	// if the file does not exist. Defaults to 30 seconds.
	WaitDuration time.Duration
}

Options sets options.

type URLOpener

type URLOpener struct {
	// Decoder specifies the decoder to use if one is not specified in the URL.
	// Defaults to runtimevar.BytesDecoder.
	Decoder *runtimevar.Decoder

	// Options specifies the options to pass to OpenVariable.
	Options Options
}

URLOpener opens filevar URLs like "file:///path/to/config.json?decoder=json".

The URL's host+path is used as the path to the file to watch. If os.PathSeparator != "/", any leading "/" from the path is dropped and remaining '/' characters are converted to os.PathSeparator.

The following URL parameters are supported:

• decoder: The decoder to use. Defaults to URLOpener.Decoder, or runtimevar.BytesDecoder if URLOpener.Decoder is nil. See runtimevar.DecoderByName for supported values.

func (*URLOpener) OpenVariableURL

func (o *URLOpener) OpenVariableURL(ctx context.Context, u *url.URL) (*runtimevar.Variable, error)

OpenVariableURL opens the variable at the URL's path. See the package doc for more details.