env

Commentary

added in 0.3.22

Special pre-processor function that loads enviroment variables in-place. This is useful for dynamically loading connection strings, ports, and anything else you might want to parameterize.

Calls to env run before any other functions are compiled and invoked. Their resolved values will then be validated against all of ShadowTraffic's normal schemas.

Because environment variables can only be strings, you can use the as parameter to cast values non-string types. ¹

If any environment variables are resolved to null or can't be cast to their target type, ShadowTraffic will stop and tell you what went wrong.

In cases where an environment variable isn't set, you can set an optional default value to fall back on. ²

If the value of the variable is sensitive, and you don't want it to be logged to the terminal, use the mask parameter to suppress it. ³

Note that pre-processing functions, like this one, don't evaluate function modifiers because they execute only once before runtime. So keys like elide and null are ignored.

---

Examples

Loading an env variable

Use env to load environment variables. By default, its type will be string.

For example, if KAFKA_TOPIC is set to transactions, this example will send events to the transactions topic.

{
    "topic": {
        "_gen": "env",
        "var": "KAFKA_TOPIC"
    },
    "value": 42
}

When you load environment variables, you should see messages like the following on the console:

✝ ***
✝ Replacing environment variable KAFKA_TOPIC at path [ "generators", 0, "topic" ]
✝ Replaced with "transactions"
✝ ***

Casting an env variable

Use as to cast enviroment variables to integer, double, or boolean.

{
    "topic": "sandbox",
    "value": {
        "_gen": "env",
        "var": "SPECIAL_NUMBER",
        "as": "double"
    }
}

You should see similiar output on the console describing how ShadowTraffic is handling the variable:

✝ ***
✝ Replacing environment variable SPECIAL_NUMBER at path [ "generators", 0, "value" ]
✝ Replaced with 42.0
✝ ***

Setting a default

Use default to provide a fallback value when the environment variable isn't set:

{
    "topic": "sandbox",
    "value": {
        "_gen": "env",
        "var": "BROKER_ADDRESS",
        "default": "localhost:9092"
    }
}

Masking an env variable

Use mask to suppress a variable, like a password, from being logged.

{
    "topic": "sandbox",
    "value": {
        "_gen": "env",
        "var": "SECRET",
        "mask": true
    }
}

The terminal will display:

✝ ***
✝ Replacing environment variable SECRET at path [ "generators", 0, "value" ]
✝ Replaced with << masked >>
✝ ***

---

Specification

JSON schema

{
    "type": "object",
    "properties": {
        "var": {
            "type": "string"
        },
        "as": {
            "type": "string",
            "enum": [
                "integer",
                "double",
                "boolean"
            ]
        },
        "default": {
            "type": "string"
        },
        "mask": {
            "type": "boolean"
        }
    },
    "required": [
        "var"
    ]
}