--

.github/workflows/build-and-test.yml

@@ -0,0 +1,12 @@
+name: build-and-test
+on: [push]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - uses: actions/setup-go@v3
+        with:
+          go-version: "1.18"
+      - run: go test --race --cover ./...

LICENCE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2022 lukejoshuapark
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

Populate.go

@@ -0,0 +1,91 @@
+package environment
+
+import (
+	"fmt"
+	"os"
+	"reflect"
+	"strings"
+)
+
+var configParsers = map[reflect.Type]reflect.Value{}
+var stringType = reflect.TypeOf("")
+var errorType = reflect.TypeOf((*error)(nil)).Elem()
+
+func UseParser(parserFunc interface{}) {
+	t := reflect.TypeOf(parserFunc)
+	if t.Kind() != reflect.Func {
+		panic(fmt.Sprintf(`cannot use "%v" as a parser function`, t))
+	}
+
+	if t.NumIn() != 1 || t.In(0) != stringType {
+		panic("parser functions must accept a single string as input")
+	}
+
+	if t.NumOut() < 1 || t.NumOut() > 2 {
+		panic("parser functions must return either T, or (T, error), where T can be any type but error")
+	}
+
+	if t.NumOut() == 2 && t.Out(1) != errorType {
+		panic("parser functions must return either T, or (T, error), where T can be any type but error")
+	}
+
+	if t.Out(0) == errorType {
+		panic("parser functions must return either T, or (T, error), where T can be any type but error")
+	}
+
+	configParsers[t.Out(0)] = reflect.ValueOf(parserFunc)
+}
+
+func Populate(into interface{}) error {
+	tPtr := reflect.TypeOf(into)
+	if tPtr.Kind() != reflect.Ptr {
+		return fmt.Errorf(`expected Populate to be called on a pointer type, not "%v"`, tPtr)
+	}
+
+	v := reflect.ValueOf(into).Elem()
+	t := v.Type()
+
+	for i := 0; i < t.NumField(); i++ {
+		f := t.Field(i)
+		tag, ok := f.Tag.Lookup("environment")
+		if !ok {
+			continue
+		}
+
+		spl := strings.Split(tag, ",")
+		if len(spl) < 1 || len(spl) > 2 {
+			continue
+		}
+
+		varName := strings.TrimSpace(spl[0])
+		varType := f.Type
+		varValue, ok := os.LookupEnv(varName)
+		if !ok {
+			if len(spl) < 2 {
+				return fmt.Errorf(`required environment variable "%v" for field "%v" on "%v" was missing`, varName, f.Name, t)
+			}
+
+			varValue = strings.TrimSpace(spl[1])
+		}
+
+		if varType == stringType {
+			v.Field(i).Set(reflect.ValueOf(varValue))
+			continue
+		}
+
+		parser, ok := configParsers[varType]
+		if !ok {
+			return fmt.Errorf(`the environment variable "%v" for field "%v" on "%v" was read, but no parser could be found for type "%v"`, varName, f.Name, t, varType)
+		}
+
+		result := parser.Call([]reflect.Value{reflect.ValueOf(varValue)})
+		if len(result) == 2 && !result[1].IsNil() {
+			err := result[1].Interface().(error)
+			return fmt.Errorf(`the environment variable "%v" for field "%v" on "%v" was read, but the parser for type "%v" failed: %w`, varName, f.Name, t, varType, err)
+		}
+
+		v.Field(i).Set(result[0])
+	}
+
+	return nil
+}

Populate_test.go

@@ -0,0 +1,99 @@
+package environment
+
+import (
+	"os"
+	"reflect"
+	"strconv"
+	"testing"
+
+	"github.com/lukejoshuapark/test"
+	"github.com/lukejoshuapark/test/is"
+)
+
+func TestPopulateBasic(t *testing.T) {
+	// Arrange.
+	configParsers = map[reflect.Type]reflect.Value{}
+	UseParser(ParseUInt16)
+	os.Setenv("SOME_STRING_VALUE", "1234")
+	os.Setenv("SOME_UINT16", "5678")
+
+	cfg := &BasicConfig{}
+
+	// Act.
+	err := Populate(cfg)
+
+	// Assert.
+	test.That(t, err, is.Nil)
+	test.That(t, cfg.SomeStringValue, is.EqualTo("1234"))
+	test.That(t, cfg.SomeUInt16, is.EqualTo(uint16(5678)))
+	test.That(t, cfg.SomeOptionalValue, is.EqualTo("9012"))
+}
+
+func TestPopulateRequiredVariableMissing(t *testing.T) {
+	// Arrange.
+	configParsers = map[reflect.Type]reflect.Value{}
+	UseParser(ParseUInt16)
+	os.Unsetenv("SOME_STRING_VALUE")
+	os.Setenv("SOME_UINT16", "5678")
+
+	cfg := &BasicConfig{}
+
+	// Act.
+	err := Populate(cfg)
+
+	// Assert.
+	test.That(t, err, is.NotNil)
+	test.That(t, err.Error(), is.EqualTo(`required environment variable "SOME_STRING_VALUE" for field "SomeStringValue" on "environment.BasicConfig" was missing`))
+}
+
+func TestPopulateMissingParser(t *testing.T) {
+	// Arrange.
+	configParsers = map[reflect.Type]reflect.Value{}
+	os.Setenv("SOME_STRING_VALUE", "1234")
+	os.Setenv("SOME_UINT16", "5678")
+
+	cfg := &BasicConfig{}
+
+	// Act.
+	err := Populate(cfg)
+
+	// Assert.
+	test.That(t, err, is.NotNil)
+	test.That(t, err.Error(), is.EqualTo(`the environment variable "SOME_UINT16" for field "SomeUInt16" on "environment.BasicConfig" was read, but no parser could be found for type "uint16"`))
+}
+
+func TestPopulateParserFailure(t *testing.T) {
+	// Arrange.
+	configParsers = map[reflect.Type]reflect.Value{}
+	UseParser(ParseUInt16)
+	os.Setenv("SOME_STRING_VALUE", "1234")
+	os.Setenv("SOME_UINT16", "567891")
+
+	cfg := &BasicConfig{}
+
+	// Act.
+	err := Populate(cfg)
+
+	// Assert.
+	test.That(t, err, is.NotNil)
+	test.That(t, err.Error(), is.EqualTo(`the environment variable "SOME_UINT16" for field "SomeUInt16" on "environment.BasicConfig" was read, but the parser for type "uint16" failed: strconv.ParseUint: parsing "567891": value out of range`))
+}
+
+// --
+
+func ParseUInt16(val string) (uint16, error) {
+	v, err := strconv.ParseUint(val, 10, 16)
+	if err != nil {
+		return 0, err
+	}
+
+	return uint16(v), nil
+}
+
+// --
+
+type BasicConfig struct {
+	SomeStringValue   string `environment:"SOME_STRING_VALUE"`
+	SomeUInt16        uint16 `environment:"SOME_UINT16"`
+	SomeOptionalValue string `environment:"SOME_OPTIONAL_VALUE,9012"`
+}

README.md

@@ -0,0 +1,110 @@
+![](icon.png)
+
+# environment
+
+Automatically retrieves values from environment variables into a configuration
+structure.
+
+## Usage Example
+
+```go
+package main
+
+import (
+	"github.com/lukejoshuapark/environment"
+)
+
+type Config struct {
+	Hostname string `environment:"APP_HOSTNAME,example.com"`
+	Username string `environment:"APP_USERNAME"`
+	Password string `environment:"APP_PASSWORD"`
+}
+
+func main() {
+	cfg := &Config{}
+	if err := environment.Populate(cfg); err != nil {
+		// Failed to populate the provided structure.
+		return
+	}
+
+	// cfg has now been populated from environment variables.
+}
+```
+
+## Parsers
+
+It is often useful to be able to represent richer types than `string` in our
+configuration, even though we are forced to provide these values in `string`
+form through environment variables.
+
+Consider the scenario where we might want to source a port number from our
+environment variables:
+
+```go
+type Config struct {
+	Hostname string `environment:"APP_HOSTNAME,example.com"`
+	Port     uint16 `environment:"APP_PORT,8080"` // Non-string type.
+	Username string `environment:"APP_USERNAME"`
+	Password string `environment:"APP_PASSWORD"`
+}
+```
+
+By default, `environment.Populate` won't know how to handle the `uint16` in this
+struct and will fail.  To show `environment.Populate` how to handle this type,
+we can use a parser:
+
+```go
+func ParseUInt16(val string) (uint16, error) {
+	n, err := strconv.ParseUint(val, 10, 16)
+	if err != nil {
+		return 0, err
+	}
+
+	return uint16(n), nil
+}
+
+environment.UseParser(ParseUInt16)
+```
+
+You can define a parser function for any type you like.  An example of a more
+complex parser than can read base64 encoded Ed25519 private keys is provided
+below:
+
+```go
+func ParseEd25519PrivateKey(val string) (ed25519.PrivateKey, error) {
+	rawKey, err := base64.StdEncoding.DecodeString(val)
+	if err != nil {
+		return nil, fmt.Errorf("could not base64 decode private key: %w", err)
+	}
+
+	if len(rawKey) != ed25519.SeedSize {
+		return nil, fmt.Errorf("expected a key length of %v bytes, but was %v bytes", ed25519.SeedSize, len(rawKey))
+	}
+
+	return ed25519.NewKeyFromSeed(rawKey), nil
+}
+
+environment.UseParser(ParseEd25519PrivateKey)
+```
+
+## Optional Environment Variables
+
+By default, fields tagged with `environment` are required - if the
+corresponding environment variable is not set, `Populate` will return a non-nil
+error when processing.
+
+If instead you'd like to have a field be optional, you can provide a default
+value by suffixing a comma and the default string value for that field.
+
+This can be seen above for the `Hostname` field.  If `APP_HOSTNAME` is set in
+the environment, its value will be assigned to the `Hostname` field.  Otherwise,
+the value `"example.com"` will be assigned.
+
+Note that default values are assigned prior to parsing.  Because of this, for
+non-string types, you must provide a default value in string form that can
+successfully be parsed by the parser for that type.
+
+---
+
+Icons made by [Freepik](https://www.flaticon.com/authors/freepik) from
+[www.flaticon.com](https://www.flaticon.com/).

go.mod

@@ -0,0 +1,5 @@
+module github.com/lukejoshuapark/environment
+
+go 1.18
+
+require github.com/lukejoshuapark/test v1.0.3

go.sum

@@ -0,0 +1,2 @@
+github.com/lukejoshuapark/test v1.0.3 h1:hG3Qm3oD/+fitXHCUyvIWQLHXCbGdGMadXA2gpynOJs=
+github.com/lukejoshuapark/test v1.0.3/go.mod h1:aL/NFkmy+G4US2C+KgWjpToW8cz3WfeDHL120BxJmAM=