Selection functions
stateMachine
Commentary
added in 0.0.5
stateful function
Generates data according to a set of states and transitions.
State machines can be used in two ways: either as regular functions, or as a top-level field that controls the entire generator.
For the former, when a state is triggered, its value is used in place. 1 For the latter, its value is merged into the generator to override its existing behavior. 2
For many use cases, it's common that each successive state needs to merge its previously generated event. Top-level state machines may be configured with a merge property to enable this behavior. 3
Examples
Basic state machine
Use a state machine like any other function. ShadowTraffic keeps track of the current state and advances it over time. States can transition indefinitely, or terminate, in which case the generator will go dormant and stop generating new events.
{
"_gen": "stateMachine",
"initial": "a",
"transitions": {
"a": "b",
"b": "c",
"c": "a"
},
"states": {
"a": 1,
"b": 2,
"c": 3
}
}
[
1,
2,
3,
1,
2
]
Top-level state machine
An optional top-level state machine may be defined for the generator. When present, the value of its state is merged into the entire generator output. This is useful when modeling change that affects many attributes, even including the output collection.
{
"generators": [
{
"topic": "customers",
"vars": {
"id": {
"_gen": "uniformDistribution",
"bounds": [
1,
10
]
}
},
"key": {
"_gen": "var",
"var": "id"
},
"value": {},
"stateMachine": {
"_gen": "stateMachine",
"initial": "a",
"transitions": {
"a": "b",
"b": "c",
"c": "a"
},
"states": {
"a": {
"value": {
"action": "start"
}
},
"b": {
"value": {
"action": "running"
}
},
"c": {
"value": {
"action": "stopped"
}
}
}
}
}
],
"connections": {
"kafka": {
"kind": "kafka",
"producerConfigs": {
"bootstrap.servers": "localhost:9092",
"key.serializer": "io.shadowtraffic.kafka.serdes.JsonSerializer",
"value.serializer": "io.shadowtraffic.kafka.serdes.JsonSerializer"
}
}
}
}
[
{
"topic": "customers",
"key": 1.3906161747424364,
"value": {
"action": "start"
},
"headers": null
},
{
"topic": "customers",
"key": 6.102332126254197,
"value": {
"action": "running"
},
"headers": null
},
{
"topic": "customers",
"key": 5.243105539761816,
"value": {
"action": "stopped"
},
"headers": null
},
{
"topic": "customers",
"key": 9.367015862769998,
"value": {
"action": "start"
},
"headers": null
},
{
"topic": "customers",
"key": 8.321629163914373,
"value": {
"action": "running"
},
"headers": null
}
]
Merge previous events
Top-level state machines can force their previously generated events into their body.
{
"topic": "sandbox",
"value": {
"a": 1
},
"stateMachine": {
"_gen": "stateMachine",
"initial": "s1",
"merge": {
"previous": true
},
"transitions": {
"s1": "s2",
"s2": "s3"
},
"states": {
"s1": {
"value": {
"b": 2
}
},
"s2": {
"value": {
"c": 3
}
},
"s3": {
"value": {
"d": 4
}
}
}
}
}
[
{
"a": 1,
"b": 2
},
{
"a": 1,
"b": 2,
"c": 3
},
{
"a": 1,
"b": 2,
"c": 3,
"d": 4
}
]
Sequential transitions
Instead of a map, transitions can also be specified as an array, describing the exact path to take through the state machine.
When specified in this form, you don't need to specify an initial state since it's obvious where to begin.
{
"_gen": "stateMachine",
"transitions": [
"s1",
"s2",
"s2",
"s3"
],
"states": {
"s1": {
"value": {
"a": 2
}
},
"s2": {
"value": {
"b": 3
}
},
"s3": {
"value": {
"c": 4
}
}
}
}
[
{
"a": 2
},
{
"b": 3
},
{
"b": 3
},
{
"c": 4
}
]
Repeated transitions
Optionally use state and times in an array of transitions to repeat states.
{
"_gen": "stateMachine",
"transitions": [
"s1",
{
"state": "s2",
"times": 3
},
"s3"
],
"states": {
"s1": {
"value": {
"a": 2
}
},
"s2": {
"value": {
"b": 3
}
},
"s3": {
"value": {
"c": 4
}
}
}
}
[
{
"a": 2
},
{
"b": 3
},
{
"b": 3
},
{
"b": 3
},
{
"c": 4
}
]
Functions in transitions
Both state and times can be functions. times is evaluated only once, and its value locked for the lifetime of the state machine. state is evaluated on each execution.
In this example, state s1 runs once, and then either s2 or s3 are visited as many as 4 times total.
{
"topic": "sandbox",
"varsOnce": {
"n": {
"_gen": "uniformDistribution",
"bounds": [
1,
5
]
}
},
"value": {},
"stateMachine": {
"_gen": "stateMachine",
"transitions": [
"s1",
{
"state": {
"_gen": "oneOf",
"choices": [
"s2",
"s3"
]
},
"times": {
"_gen": "var",
"var": "n"
}
}
],
"states": {
"s1": {
"value": {
"x": 1
}
},
"s2": {
"value": {
"x": 2
}
},
"s3": {
"value": {
"x": 3
}
}
}
}
}
[
{
"x": 1
},
{
"x": 2
},
{
"x": 3
},
{
"x": 3
},
{
"x": 3
}
]
Terminating state machines
Transition to the value null to terminate a state machine, and thus the generator.
{
"topic": "sandbox",
"value": {},
"stateMachine": {
"_gen": "stateMachine",
"initial": "s1",
"transitions": {
"s1": "s2",
"s2": null,
"s3": "s4"
},
"states": {
"s1": {
"value": {
"x": 1
}
},
"s2": {
"value": {
"x": 2
}
},
"s3": {
"value": {
"x": 3
}
},
"s4": {
"value": {
"x": 4
}
}
}
}
}
[
{
"x": 1
},
{
"x": 2
}
]
Overriding throttle values
Use localConfigs with throttleMs inside of a state to override the generator's default throttle value. This is useful if you want to make a particular state wait longer or shorter before transitioning to the next.
In this example, state s1 throttles for 2000 ms, the default, and s2 throttles for 500 ms.
{
"topic": "sandbox",
"value": {},
"stateMachine": {
"_gen": "stateMachine",
"initial": "s1",
"transitions": {
"s1": "s2",
"s2": "s1"
},
"states": {
"s1": {
"value": {
"x": 1
}
},
"s2": {
"value": {
"x": 2
},
"localConfigs": {
"throttleMs": 500
}
}
}
},
"localConfigs": {
"throttleMs": 2000
}
}
Specification
JSON schema
{
"type": "object",
"properties": {
"merge": {
"type": "object",
"properties": {
"previous": {
"type": "boolean"
}
},
"required": [
"previous"
]
},
"states": {
"type": "object"
}
},
"required": [
"transitions",
"states"
],
"anyOf": [
{
"properties": {
"initial": {
"type": "string"
},
"transitions": {
"type": "object"
}
},
"required": [
"initial"
]
},
{
"properties": {
"transitions": {
"type": "array",
"minItems": 1,
"items": {
"oneOf": [
{
"type": "string"
},
{
"type": "object",
"properties": {
"state": {
"oneOf": [
{
"type": "string"
},
{
"type": "object",
"properties": {
"_gen": {
"type": "string"
}
},
"required": [
"_gen"
]
}
]
},
"times": {
"oneOf": [
{
"type": "integer",
"minimum": 0
},
{
"type": "object",
"properties": {
"_gen": {
"type": "string"
}
},
"required": [
"_gen"
]
}
]
}
},
"required": [
"state",
"times"
]
}
]
}
}
}
}
]
}