starenv

README

starenv (*env) allows populating environmental variables from variety of sources, such as AWS Parameter Store, GPG encrypted files and more, with extreme ease.

For the impatient, import the autoload package and you're set:

package main

import (
	"fmt"
	"os"

	_ "github.com/oxplot/starenv/autoload"
)

func main() {
	fmt.Printf("GITHUB_TOKEN=%s\n", os.Getenv("GITHUB_TOKEN"))
}

and set the value of the environmental variable to load from Parameter Store:

$ export GITHUB_TOKEN=*ssm:/github_token
$ go run main.go
GITHUB_TOKEN=abcdef-1235143-abcdef-123-abcdef-12314

or from a GPG encrypted file:

$ export GITHUB_TOKEN=*gpg*file:github_token.gpg
$ go run main.go
GITHUB_TOKEN=abcdef-1235143-abcdef-123-abcdef-12314

why not ditch the file and embed its content:

$ export GITHUB_TOKEN=*gpg*b64:eNeO7D2rBrBOOcW6TuETyHdyPEOaAfdgaTzgOTSvROI=
$ go run main.go
GITHUB_TOKEN=abcdef-1235143-abcdef-123-abcdef-12314

and thanks to the amazing godotenv which is run as part of starenv's autoload package, you can even do:

$ echo 'GITHUB_TOKEN=*keyring:awesome_app/github_token' > .env
$ go run main.go
GITHUB_TOKEN=abcdef-1235143-abcdef-123-abcdef-12314

For a full list, see the docs.

Documentation

Overview

Package starenv implements populating environmental variables from variety of sources.

Usage

Simplest way to use starenv is to import the autoload package:

import _ "github.com/oxplot/starenv/autoload"

The above will iterate through all environmental variables looking for specially formatted values which tell it where to load the final values from. After the above is imported, you can use the usual os.Getenv() to get the value of environmental variables.

Ref Pipline

The source of a value is defined as a pipeline of "derefer" tags followed by the reference for the last derefer. Here is an example of a environmental variable specifying to load its value from a base64 encoded file and decrypt it using GPG:

GITHUB_TOKEN=*gpg*b64*file:~/.github_token

Each derefer is applied in reverse, starting with "file" which loads the content of "~/.github_token". "b64" then decodes it and finally "gpg" decrypts it.

If the value of an environmental variable starts with Loader.Star (which defaults to "*"), it is treated as a pipeline. Otherwise, it's treated as a literal value and left unchagned. In the unlikely case where a literal value starting with Loader.Star is needed, the following can be used:

GLOB_PAT=*:*.terraform

Here the blank derefer treats everything after "*:" as literal and returns it, thus leading to GLOB_PAT being set to "*.terraform".

Package autoload registers a set of derefers that are included in derefer package with appropriate tags. To have more control over tags and the timing of when the loading happens, you can register each derefer manually and call Load() to populate the env vars.

Any type that implements Derefer methods can be registered and used in the pipeline.

Index

• func Load() error
• func Register(tag string, d Derefer)
• type Derefer
• type DereferFunc
  • func (d DereferFunc) Deref(ref string) (string, error)
• type Loader
  • func NewLoader() *Loader
  • func (l *Loader) Load() error
  • func (l *Loader) Register(tag string, d Derefer)

Functions

func Load

func Load() error

Load iterates through all environmental variables and recursively derefs their values appropriately. Derefers must fist be registered with Register() function.

func Register

func Register(tag string, d Derefer)

Register maps a tag with a derefer on the default loader.

Types

type Derefer

type Derefer interface {
	Deref(ref string) (value string, err error)
}

Derefer is an interface that wraps Deref method.

Deref method is called with the recursively derefed value of all subsequent derefers in the pipeline. ref is therefore a literal by the time it's passed to this method.

type DereferFunc

type DereferFunc func(ref string) (string, error)

DereferFunc type is an adapter to allow use of ordinary functions as derefers.

func (DereferFunc) Deref

func (d DereferFunc) Deref(ref string) (string, error)

type Loader

type Loader struct {
	// Star is the prefix and separator of derefer tags which defaults to "*".
	Star string
	// contains filtered or unexported fields
}

Loader holds a registry of derefers which are looked up and applied to values of all environmental variables when Load() is called.

func NewLoader

func NewLoader() *Loader

NewLoader returns a new loader with empty "" tag mapped to to a passthrough derefer. This is needed to allow for environmental variable values which start with "*":

GLOB_PAT=*:*.terraform

The above will resolve to "*.terraform".

func (*Loader) Load

func (l *Loader) Load() error

Load iterates through all environmental variables and recursively derefs their values appropriately.

func (*Loader) Register

func (l *Loader) Register(tag string, d Derefer)

Register maps a tag with a derefer. Tags that include ":" are unusable.