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.

Source Files

View all Source files

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
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.