runtime

Table of Contents generated with DocToc

• Goruntime
  • Overview
  • Installation
  • Building
  • Usage
    • Intended Use
    • Components
      • Loader
      • Snapshot
    • Example of Usage

Goruntime

Overview

Goruntime is a Go client for Runtime application level feature flags and configuration.

Installation

go get github.com/lyft/goruntime

Building

make bootstrap && make tests

Usage

In order to start using goruntime, import it to your project with:

import "github.com/lyft/runtime"

Intended Use

The runtime system is meant to support small amounts of data, such as feature flags, kill switches, regional configuration, experiment settings, etc. Individual files should typically contain a single key/value pair (filename as key, content as value).

Components

The runtime system is composed of a Loader interface and a Snapshot interface. The Snapshot holds a version of the runtime data from disk, and is used to retrieve information from that data. The Loader loads the current snapshot, and gets file system updates when the runtime data gets updated.

Loader

The Loader interface is defined like this:

type IFace interface {
	// @return Snapshot the current snapshot. This reference is safe to use forever, but will grow
	//         stale so should not be stored beyond when it is immediately needed.
	Snapshot() snapshot.IFace

	// Add a channel that will be written to when a new snapshot is available. "1" will be written
	// to the channel as a sentinel.
	// @param callback supplies the callback to add.
	AddUpdateCallback(callback chan<- int)
}

To create a new Loader:

import (
        "github.com/lyft/goruntime/loader"
        "github.com/lyft/gostats"
)

// for full docs on gostats visit https://github.com/lyft/gostats
store := stats.NewDefaultStore()
runtime := loader.New("runtime_path", "runtime_subdirectory", store.Scope("runtime"))

The Loader will use filesystem events to update the filesystem snapshot it has.

Snapshot

The Snapshot interface is defined like this:

type IFace interface {
	FeatureEnabled(key string, defaultValue uint64) bool

	// Fetch raw runtime data based on key.
	// @param key supplies the key to fetch.
	// @return const std::string& the value or empty string if the key does not exist.
	Get(key string) string

	// Fetch an integer runtime key.
	// @param key supplies the key to fetch.
	// @param defaultValue supplies the value to return if the key does not exist or it does not
	//        contain an integer.
	// @return uint64 the runtime value or the default value.
	GetInteger(key string, defaultValue uint64) uint64

	// Fetch all keys inside the snapshot.
	// @return []string all of the keys.
	Keys() []string

	Entries() map[string]*entry.Entry

	SetEntry(string, *entry.Entry)
}

A Snapshot is composed of a map of Entrys. Each entry represents a file in the runtime path. The Snapshot can be used to Get the value of an entry (or GetInteger if the file contains an integer).

Keys are built by joining paths with . relative to the runtime subdirectory. For example if this is your filesystem:

/runtime/
└── config
    ├── file1
    └── more_files
        ├── file2
        └── file3

And the runtime loader is setup like so:

store := stats.NewDefaultStore()
runtime := loader.New("/runtime", "config", stats.Scope("runtime"))

The values in all three files can be obtained the following way:

s := runtime.Snapshot()
s.Get("file1")
s.Get("more_files.file2")
//Supposed file3 contains an integer, or you want to use a default integer if file3 does not contain one
s.GetInteger("more_files.file3", 8)