env

package module
v0.6.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Jan 4, 2022 License: MIT Imports: 9 Imported by: 0

README

env GoDoc

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.

Documentation

Overview

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

Index

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 Float32 added in v0.6.0

func Float32(name string, usage string) *float32

Float32 defines an float32 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 Float64 added in v0.6.0

func Float64(name string, usage string) *float64

Float64 defines an float64 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 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 added in v0.2.0

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 added in v0.3.0

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

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 (*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

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 (*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) Float32 added in v0.6.0

func (v *VarSet) Float32(name string, usage string) *float32

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

func (*VarSet) Float64 added in v0.6.0

func (v *VarSet) Float64(name string, usage string) *float64

Float64 defines an float64 variable with specified name, usage string and validation checks. The return value is the address of an float64 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 added in v0.2.0

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 added in v0.3.0

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.

Directories

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

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL