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://gocloud.dev/concepts/urls/ for background information.

As

filevar does not support any types for As.

Example (OpenVariableFromURL)

package main

import (
	"context"
	"log"

	"gocloud.dev/runtimevar"
)

func main() {
	// PRAGMA: This example is used on gocloud.dev; PRAGMA comments adjust how it is shown and can be ignored.
	// PRAGMA: On gocloud.dev, add a blank import: _ "gocloud.dev/runtimevar/filevar"
	// PRAGMA: On gocloud.dev, hide lines until the next blank line.
	ctx := context.Background()

	// runtimevar.OpenVariable creates a *runtimevar.Variable from a URL.

	v, err := runtimevar.OpenVariable(ctx, "file:///path/to/config.txt?decoder=string")
	if err != nil {
		log.Fatal(err)
	}
	defer v.Close()
}

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 (OpenVariableFromURL)
• 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.

Example

package main

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

	"gocloud.dev/runtimevar"
	"gocloud.dev/runtimevar/filevar"
)

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("hello world")); err != nil {
		log.Fatal(err)
	}

	// Construct a *runtimevar.Variable pointing at f.
	v, err := filevar.OpenVariable(f.Name(), runtimevar.StringDecoder, 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)
	}
	// runtimevar.Snapshot.Value is decoded to a string.
	fmt.Println(snapshot.Value.(string))

}

Output:

hello world

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.