qrtz is the processing language for hybrixd. It is used to handle routing requests. Each routing request spawns a process that follows qrtz steps to a result, or a failure.
A qrtz command always consists of 4 characters. The parameters are separated by spaces:
head parameter1 parameter2 ...
Recipes are JSON files that contain parameters and qrtz methods for asset handling, data source queries or actionable engines. A recipe, depending on what it does, fits in one of three categories: asset, source, or engine.
A source-recipe in principle contains only methods to query read-only data sources.
An engine-recipe contains methods to perform actions based on incoming data, business logic and often interfaces with other programming languages.
An asset-recipe contains methods to query value-related ledger or cryptocurrency API's. It returns path options to the hybrixd routing engine for users or machines to perform actions like, for example, querying the balance of an address.
The categories above make it easier to recognize the functionality of a recipe instantly, and analyze it from the proper context. Source and engine recipes are interpreted identically by the scheduler. However, they are available through separate paths: /source
and /engine
. Asset recipes are specifically tailored to be used in the context of decentralized banking and are available through the routing path: /asset
.
Every step in a qrtz recipe has the potential to alter the data of the process in which the script is running. Process data is available by using the dollar sign $
. It is also available as input to every new process step. It behaves like a variable in qrtz in that it can be read anywhere. However, the difference with a variable is that the data of the process can be changed by every step of the process. The design consideration is that this coaxes you to design your qrtz script with a concise data flow in mind.
Here is an example of some qrtz steps and the resulting data flow.
data 'Hello dog!' // data 'Hello dog!' - set the data of the process
drop -4 // data 'Hello ' - drops the last 4 characters
repl ' ' ' world!' // data 'Hello world!' - replaces the ' ' (space) by ' world!'
$
the main stream variable it is the output of the previous step. Use $$
to escape the dollar sign (for example in regular expressions).
$variable
Retrieve a property from the recipe scope (read only)or process scope if no recipe variable is found.
$local::variable
Use a local scope (maintained between all processes spawned from the same recipe).
$otherRecipe::variable
the recipe scope of another recipe (read-only)
${.property}
To retrieve a sub properties
of objects and arrays. For example: if data
is {a:{b:1}}}
then ${.a.b}
will
return 1
qrtz processes flow can be analyzed using the debug tool. These are only available to node operators with root access.
Adding the -d
flag to a cli api call will provide the debug output. This will illustrate the programe flow of all subprocesses and steps.
$ ./hybrixd /a/dummy/balance/wrongaddress -d pid: 1575447893066808 . ╻ /asset/dummy/balance/wrongaddress "Invalid address wrongaddress" .0 ┗┳ call validate/$1 "invalid" .0.0 ┣┳ /asset/dummy/validate/wrongaddress "invalid" .0.0.0 ┃┗┳ data '$addressRegex' "^_dummyaddress_$" .0.0.1 ┃ ┣ flow 'undefined' 1 3 "^_dummyaddress_$" .0.0.2 ┃ ┣ rout '/source/wavalidator/$symbol/$1' null .0.0.3 ┃ ┣ done null .0.0.4 ┃ ┣ data '$1' "wrongaddress" .0.0.5 ┃ ┣ regx '$addressRegex' 1 2 "wrongaddress" .0.0.6 ┃ ┣ done valid null .0.0.7 ┃ ┗ done invalid "invalid" .1 ┣ flow valid 2 1 "invalid" .2 ┣ fail "Invalid address $1" "Invalid address wrongaddress" .3 ┣ data '$1' null .4 ┣ flow _dummyaddress_ 2 1 null .5 ┣ stop 1,'Error: invalid address!' null .6 ┣ pass '10000.00000000' null .7 ┣ form null .8 ┣ done null
- $variables
- @labels
- Process steps that contain errors.
- Process steps that have not been executed.
An interactive debug interface is available through:
http://localhost:1111/proc/debug
This interface is similar to the cli interface but includes live updated progress views.qrtz can be ran as a shell and interactive mode.
./qrtz
Start qrtz in interactive mode
cat data ./qrtz -i
or ./qrtz < cat data
Pipe data to interactive mode
qrtz script.qrtz $1 $2
or ./qrtz -s script.qrtz $1 $2
Execute script with command parameters 1,2
qrtz $1 $2 < cat script.qrtz
or cat script.qrtz | qrtz $1 $2
Execute script provided trough pipe with command parameters 1,2
Create a file script.qrtz
with the following content:
data "hello $1" done
Then use the following to execute:
./qrtz script.qrtz "world"
This results in:
hello world
By adding a "shebang" the file can be made into a qrtz executable:
#!/$QRTZ_HOME/qrtz data "hello $1" done
Then use the following to execute:
./script.qrtz "world"
$ ./qrtz > data "hello world" hello world > quit $
Pass command line parameters:
$ ./qrtz universe > data "hello $1" hello universe > quit $