key

Commentary

added in 0.1.0

Dynamically creates new instances of this generator, each identified by the value of key.

If key is a supplied with an array, the generator forks on each unique element. If key is supplied as a function, the generator runs for each uniquely returned value.

Only one instance of a generator will run at a time for each fork key. If the same value for key is produced while a generator is running, ShadowTraffic will ignore it.

key cannot be null. ShadowTraffic will stop and describe the error, since that is very likely a mistake.

The fork key for each generator can be accessed through the var forkKey.

---

Examples

Forking on an array

If the fork key is an array, it will create a generator instance for each element in the specified order.

{
    "topic": "sensors",
    "fork": {
        "key": [
            "sensor #1",
            "sensor #2",
            "sensor #3"
        ]
    },
    "value": {
        "id": {
            "_gen": "var",
            "var": "forkKey"
        }
    },
    "localConfigs": {
        "maxEvents": 1
    }
}

[
    {
        "id": "sensor #1"
    },
    {
        "id": "sensor #2"
    },
    {
        "id": "sensor #3"
    }
]

Forking on a function

If the fork key is a function, it will create a generator instance for each returned value.

{
    "topic": "sensors",
    "fork": {
        "key": {
            "_gen": "sequentialString",
            "expr": "sensor-~d"
        }
    },
    "value": {
        "id": {
            "_gen": "var",
            "var": "forkKey"
        }
    },
    "localConfigs": {
        "maxEvents": 1
    }
}

[
    {
        "id": "sensor-0"
    },
    {
        "id": "sensor-1"
    },
    {
        "id": "sensor-2"
    },
    {
        "id": "sensor-3"
    }
]

Forking on a lookup

If the fork key is a lookup function, it will by default create generator instances in the order the looked up data was created.

Further, if any fork instances terminate, new forks will use the earliest (first-created) available keys. In other words, lookup keys are both used and recycled in order.

You can override this behavior by setting an alternative strategy on your lookup function.

{
    "topic": "agents",
    "value": {
        "id": {
            "_gen": "sequentialString",
            "expr": "agent-~d"
        }
    },
    "localConfigs": {
        "maxEvents": 2
    }
}

[
    {
        "topic": "agents",
        "key": null,
        "value": {
            "id": "agent-0"
        },
        "headers": null
    },
    {
        "topic": "calls",
        "key": null,
        "value": {
            "callId": "call-0",
            "agentId": "agent-0"
        },
        "headers": null
    },
    {
        "topic": "agents",
        "key": null,
        "value": {
            "id": "agent-1"
        },
        "headers": null
    },
    {
        "topic": "calls",
        "key": null,
        "value": {
            "callId": "call-0",
            "agentId": "agent-1"
        },
        "headers": null
    },
    {
        "topic": "calls",
        "key": null,
        "value": {
            "callId": "call-0",
            "agentId": "agent-0"
        },
        "headers": null
    }
]

---

Specification

JSON schema

{
    "oneOf": [
        {
            "type": "array"
        },
        {
            "type": "object",
            "properties": {
                "_gen": {
                    "type": "string"
                }
            },
            "required": [
                "_gen"
            ]
        }
    ]
}