env

README

Environment variable management

Package Goals:

Up-front check for existance and validity of all required config variables
Can output all variables used by a process on startup
Can export and import full env configurations
Seamlessly transition local testing environments to Kubernetes

Inspired by the simplicity and power of the standard library flag package, env works by first defining a set of variables in your program which will take the value of ENV variables.

This is extended with the envsvc package which is explicitly designed for use in service processes.

Example below:

package main

import (
	"fmt"
	"net/http"

	"github.com/sajari/env"
	"github.com/sajari/env/envsvc"
)

func main() {
	// Define variables...
	listen := env.BindAddr("LISTEN", "bind address for gRPC server")
	debug := env.BindAddr("LISTEN_DEBUG", "bind address for http debug server")
	apiKey := env.String("API_KEY", "key id for api authorisation")
	workers := env.Int("WORKERS", "number of parallel workers to start")

	// Parse them from the environment and exit if all env vars are not set
	envsvc.Parse()

	// Debug server (optional)
	http.ListenAndServe(*debug, nil)

	// Your code begins here!
}

By default String, Int, Bool, Duration are defined. We also have flag types BindAddr and DialAddr typically included in all of our services for exposing ports on server processes and dialing to other servers.

Extending this pattern

It’s also possible to define new variable types by implementing the Value interface (which is the same as in flag). You can also define separate sets of variables, rather than using the global functions in the env package.

Config export, generation and more

Inheriting a project and getting configured is simple. The above code example will exit if the env vars are not set. From an engineer perspective this is great, you immediately see why the service won't start and what you need to fix to get running.

The built-in --help flag tells you your options:

$ ./my-service --help
Usage of ./my-service:
  -env-check
    	check env variables
  -env-dump
    	dump env variables
  -env-dump-json
    	dump env variables in JSON format
  -env-dump-yaml
    	dump env variables in YAML format

So we can check which env vars are required:

$ ./my-service -env-check
missing env MY_SERVICE_LISTEN
missing env MY_SERVICE_LISTEN_DEBUG
missing env MY_SERVICE_API_KEY
missing env MY_SERVICE_WORKERS

Note: the env vars are prefixed with the service name to avoid clashes.

Ok that's useful, now we know what we need to get this service up and running. I'm lazy, so i want this done for me:

$ ./my-service -env-dump
# bind address for gRPC server
export MY_SERVICE_LISTEN=""       

# bind address for http debug server
export MY_SERVICE_LISTEN_DEBUG="" 

# key id for api authorisation
export MY_SERVICE_API_KEY=""      

# number of parallel workers to start
export MY_SERVICE_WORKERS=""

Excellent, now I have a workable set of environment parameters ready to be exported, note that they are currently blank. At this point the engineer has some options:

Create workable values (particularly if the owner)
Look for example values in the service repo (good practice)
Ask the service owner

So after making these up and adding them to my environment i can re-run the dump commmand to get the following:

$ ./my-service -env-dump
export MY_SERVICE_LISTEN=":1234"         # bind address for gRPC server
export MY_SERVICE_LISTEN_DEBUG=":5678"   # bind address for http debug server
export MY_SERVICE_API_KEY="abc"          # key id for api authorisation
export MY_SERVICE_WORKERS="4"            # number of parallel workers to start

We now have a fully working environment that will be validated on service start and can be exported and shared with other engineers as needed.

Expand ▾ Collapse ▴

Documentation

Overview ¶

Package env provides a standardised interface to environment variables, including parsing, validation and export checks.

Index ¶

Variables
func BindAddr(name, usage string) *string
func Bool(name string, usage string) *bool
func DialAddr(name, usage string) *string
func Duration(name string, usage string) *time.Duration
func Int(name string, usage string) *int
func Int64(name string, usage string) *int64
func Parse() error
func Path(name, usage string) *string
func String(name, usage string) *string
func StringRequired(name, usage string) *string
func URL(name, usage string) *url.URL
func Visit(fn func(*Var))
type Errors
- func (me Errors) Error() string
type Getter
type Value
type Var
type VarSet
- func NewVarSet(name string) *VarSet
- func (v *VarSet) BindAddr(name, usage string) *string
- func (v *VarSet) Bool(name string, usage string) *bool
- func (v *VarSet) DialAddr(name, usage string) *string
- func (v *VarSet) Duration(name string, usage string) *time.Duration
- func (v *VarSet) Int(name string, usage string) *int
- func (v *VarSet) Int64(name string, usage string) *int64
- func (v *VarSet) Name() string
- func (v *VarSet) Parse(g Getter) error
- func (v *VarSet) Path(name, usage string) *string
- func (v *VarSet) Prefix() string
- func (v *VarSet) String(name string, usage string) *string
- func (v *VarSet) StringRequired(name string, usage string) *string
- func (v *VarSet) URL(name, usage string) *url.URL
- func (v *VarSet) Var(value Value, name, usage string)
- func (v *VarSet) Visit(fn func(v *Var))

Constants ¶

This section is empty.

Variables ¶

View Source

var CmdName = func() string {
	return path.Base(os.Args[0])
}

CmdName is used to create the default variable set name.

View Source

var CmdVar = NewVarSet(CmdName())

CmdVar is the default variable set used for command-line based applications. The name of the variable set (and hence all variable prefixes) is given by CmdName.

Functions ¶

func BindAddr ¶

func BindAddr(name, usage string) *string

BindAddr defines a string variable with specified name, usage string validated as a bind address (host:port). The return value is the address of a string variable that stores the value of the variable.

func Bool ¶

func Bool(name string, usage string) *bool

Bool defines a bool variable with specified name and usage string. The return value is the address of a bool variable that stores the value of the variable.

func DialAddr ¶

func DialAddr(name, usage string) *string

DialAddr defines a string variable with specified name, usage string validated as a dial address (host:port). The return value is the address of a string variable that stores the value of the variable.

func Duration ¶

func Duration(name string, usage string) *time.Duration

Duration defines a time.Duration variable with specified name, usage string and validation checks. The return value is the address of a time.Duration variable that stores the value of the variable.

func Int ¶

func Int(name string, usage string) *int

Int defines an int variable with specified name and usage string. The return value is the address of an int variable that stores the value of the variable.

func Int64 ¶

func Int64(name string, usage string) *int64

Int64 defines an int64 variable with specified name and usage string. The return value is the address of an int variable that stores the value of the variable.

func Parse ¶

func Parse() error

Parse parses variables from the process environment.

func Path ¶

func Path(name, usage string) *string

Path defines a string variable with specified name, usage string validated as a local path. The return value is the address of a string variable that stores the value of the variable.

func String ¶

func String(name, usage string) *string

String defines a string variable with specified name, usage string and validation checks. The return value is the address of a string variable that stores the value of the variable.

func StringRequired ¶

func StringRequired(name, usage string) *string

StringRequired defines a required string variable with specified name and usage string.. The return value is the address of a string variable that stores the value of the variable.

func URL ¶

func URL(name, usage string) *url.URL

URL defines a string variable with specified name, usage string validated as a URL. The return value is the address of a URL variable that stores the value of the variable.

func Visit ¶

func Visit(fn func(*Var))

Visit visits the variables in the order in which they were defined, calling fn for each.

Types ¶

type Errors ¶

type Errors []error

Errors is returned from Parse.

func (Errors) Error ¶

func (me Errors) Error() string

Error implements error.

type Getter ¶

type Getter interface {
	// Get retrieves an evironment variable.
	Get(string) (string, bool)
}

Getter defines the Get method.

type Value ¶

type Value interface {
	// String is a string representation of the stored value.
	String() string

	// Set assigns a new value to a stored value from a string
	// representation.
	Set(string) error
}

Value is the interface to the dynamic value stored in Var.

type Var ¶

type Var struct {
	Name  string // name
	Usage string // help message
	Value Value  // value as set
}

Var represents the state of a variable.

type VarSet ¶

type VarSet struct {
	// contains filtered or unexported fields
}

VarSet contains a set of variables.

func NewVarSet ¶

func NewVarSet(name string) *VarSet

NewVarSet creates a new variable set with given name.

If name is non-empty, then all variables will have a strings.ToUpper(name)+"_" prefix.

func (*VarSet) BindAddr ¶

func (v *VarSet) BindAddr(name, usage string) *string

func (*VarSet) Bool ¶

func (v *VarSet) Bool(name string, usage string) *bool

Bool defines a bool variable with specified name, usage string and validation checks. The return value is the address of a bool variable that stores the value of the variable.

func (*VarSet) DialAddr ¶

func (v *VarSet) DialAddr(name, usage string) *string

func (*VarSet) Duration ¶

func (v *VarSet) Duration(name string, usage string) *time.Duration

Duration defines a time.Duration variable with specified name, usage string and validation checks. The return value is the address of a time.Duration variable that stores the value of the variable.

func (*VarSet) Int ¶

func (v *VarSet) Int(name string, usage string) *int

Int defines an int variable with specified name, usage string and validation checks. The return value is the address of an int variable that stores the value of the variable.

func (*VarSet) Int64 ¶

func (v *VarSet) Int64(name string, usage string) *int64

Int64 defines an int64 variable with specified name, usage string and validation checks. The return value is the address of an int variable that stores the value of the variable.

func (*VarSet) Name ¶

func (v *VarSet) Name() string

Name is the name of the variable set.

func (*VarSet) Parse ¶

func (v *VarSet) Parse(g Getter) error

Parse parses variables from the environment provided by the Getter.

func (*VarSet) Path ¶

func (v *VarSet) Path(name, usage string) *string

Path defines a string variable with specified name, usage string validated as a local path. The return value is the address of a string variable that stores the value of the variable.

func (*VarSet) Prefix ¶

func (v *VarSet) Prefix() string

Prefix applied to all variables when they are created.

func (*VarSet) String ¶

func (v *VarSet) String(name string, usage string) *string

String defines a string variable with specified name, usage string and validation checks. The return value is the address of a string variable that stores the value of the variable.

func (*VarSet) StringRequired ¶

func (v *VarSet) StringRequired(name string, usage string) *string

StringRequired defines a required string variable with specified name and usage string. The return value is the address of a string variable that stores the value of the variable.

func (*VarSet) URL ¶

func (v *VarSet) URL(name, usage string) *url.URL

URL defines a string variable with specified name, usage string validated as a URL. The return value is the address of a URL variable that stores the value of the variable.

func (*VarSet) Var ¶

func (v *VarSet) Var(value Value, name, usage string)

Var defines a variable with the specified name and usage string.

func (*VarSet) Visit ¶

func (v *VarSet) Visit(fn func(v *Var))

Visit visits the variables in the order in which they were defined, calling fn for each.

Source Files

View all

Directories

Path	Synopsis
envsvc Package envsvc provides convenience methods for using env with services.	Package envsvc provides convenience methods for using env with services.

?	: This menu
/	: Search site
f or F	: Jump to