loadJsonFile

Commentary

added in 0.4.16

Special pre-processor function that loads JSON from another file. This is useful for splitting a large configuration into pieces so you can selectively pull in fragments, like constants or entire connection blocks.

This function requires only one parameter, file, and it must be a fully-qualified path to the file inside the ShadowTraffic Docker container. So be sure to volume mount these files in addition to your base configuration.

You can also supply a data parameter to do simple primitive substitutions according to the Mustache spec. This is provided as a convenience. If you need something more sophisticated, use something like Jinja directly.

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.

---

Caveats

Static data

Note that the contents of data must either be static data or further preprocessor functions. Runtime functions won't be applied before data is passed into the loaded file. For example, in the configuration below, x will not receive the value 1, 2, or 3, but the raw oneOf map, which is probably not what you want.

{
    "_gen": "loadJsonFile",
    "file": "/data/subfile.json",
    "data": {
        "x": {
            "_gen": "oneOf",
            "choices": [1, 2, 3]
        }
    }
}

Instead, rewrite it so that the contents of subfile.json references a top-level variable.

---

Examples

Loading a file

Specify the file with a fully qualified path.

{
    "topic": "sandbox",
    "value": {
        "_gen": "loadJsonFile",
        "file": "/path/to/file.json"
    }
}

When you load JSON files, you should see messages like the following on the console:

✝ ***
✝ Replacing JSON file /path/to/file.json at path [ "generators", 0, "value", "choices" ]
✝ ***

Substitute fields

Use data to substitute primitives into the target file where names are denoted with {{ name }} expressions.

For example, /path/to/file.json should contain {{ variable }} and {{ expresssion }}, and will have "foo" and 42 substituted respectively.

{
    "topic": "sandbox",
    "value": {
        "_gen": "loadJsonFile",
        "file": "/path/to/file.json",
        "data": {
            "variable": "foo",
            "expression": 42
        }
    }
}

Env variables as data

Before loadJsonFile runs, all other preprocessors run. In this example, the environment variable PORT is evaluated as data before it loads the secondary JSON file.

{
    "topic": "sandbox",
    "value": {
        "_gen": "loadJsonFile",
        "file": "/path/to/file.json",
        "data": {
            "port": {
                "_gen": "env",
                "var": "PORT"
            }
        }
    }
}

---

Specification

JSON schema

{
    "type": "object",
    "properties": {
        "file": {
            "type": "string"
        }
    },
    "required": [
        "file"
    ]
}