Skip to content
generated from dogmatiq/template-go

Declarative environment variable validation for Go.

License

Notifications You must be signed in to change notification settings

dogmatiq/ferrite

Folders and files

NameName
Last commit message
Last commit date

Latest commit

c40bb23 · Aug 16, 2024
Jul 15, 2024
Aug 16, 2024
Nov 29, 2022
Jul 29, 2022
Jul 30, 2024
Aug 16, 2024
Jan 28, 2024
Mar 11, 2023
Mar 11, 2023
Aug 16, 2024
Aug 16, 2024
Mar 14, 2024
Aug 16, 2024
Mar 13, 2024
Aug 16, 2024
Aug 16, 2024
Aug 16, 2024
Mar 13, 2024
Aug 16, 2024
Mar 13, 2024
Aug 16, 2024
Aug 16, 2024
Aug 16, 2024
Mar 13, 2024
Aug 16, 2024
Mar 13, 2024
Aug 16, 2024
Mar 13, 2024
Aug 16, 2024
Mar 13, 2024
Aug 16, 2024
Mar 14, 2024
Aug 16, 2024
Mar 13, 2024
Aug 16, 2024
Mar 13, 2024
Jul 15, 2024
Jul 31, 2022
Jul 31, 2022
Aug 16, 2024
Aug 7, 2024
Jun 11, 2023
Jun 11, 2023
Jun 6, 2023
Jul 30, 2024
Aug 16, 2024
Jun 11, 2023
Aug 13, 2023
Aug 13, 2023
Aug 13, 2023
Mar 14, 2023
Jun 11, 2023
Jun 11, 2023
Jun 11, 2023
Jun 11, 2023
Jun 11, 2023
Jun 11, 2023
Jun 11, 2023
Jun 11, 2023

Repository files navigation

Ferrite

A type-safe, declarative environment variable validation system for Go.

Documentation Latest Version Build Status Code Coverage

Getting Started

This example demonstrates how to declare an environment variable that produces a time.Duration value, but Ferrite supports many different variable types, as described in the examples.

First, describe the application's environment variables using Ferrite's "builder" interfaces. This is typically done at the package-scope of the main package.

var httpTimeout = ferrite.
    Duration("HTTP_TIMEOUT", "the maximum duration of each HTTP request").
    WithDefault(10 * time.Second).
    Required()

Next, initialize Ferrite in the application's main() function before any other code is executed so that it may halt execution when the environment is invalid.

func main() {
    ferrite.Init()

    // existing application logic ...
}

Finally, read the environment variable's value by calling the Value() method.

timeout := httpTimeout.Value()
ctx, cancel := context.WithTimeout(context.Background(), timeout)
defer cancel()

// do HTTP request ...

Modes of Operation

By default, calling Init() operates in "validation" mode. There are several other modes that can be used to gain insight into the application's use of environment variables.

Modes are selected by setting the FERRITE_MODE environment variable.

validate mode

This is the default mode. If one or more environment variables are invalid, this mode renders a description of all declared environment variables and their associated values and validation failures to STDERR, then exits the process with a non-zero exit code.

It also shows warnings if deprecated environment variables are used.

usage/markdown mode

This mode renders Markdown documentation about the environment variables to STDOUT. The output is designed to be included in the application's README.md file or a similar file.

export/dotenv mode

This mode renders environment variables to STDOUT in a format suitable for use with tools like dotenv and the env_file directive in Docker compose files.

Other Implementations

Austenite is a TypeScript library with similar features to Ferrite.