Command and WebAssembly
The rule-cascade command and rule-cascade.wasm. One file each, no dependencies, the same engine from any language over a JSON Lines protocol.
The rule-cascade command is the Go runtime built as one static binary for Linux, macOS and
Windows on x86-64 and ARM64. rule-cascade.wasm is the same command built for WASI preview 1. Both
check and compile rulesets, evaluate requests, and serve the engine protocol: one JSON request
per line on standard input, one JSON response per line on standard output.
Supported versions: building needs Go 1.22 or later; the binary needs nothing. The module needs
a WASI preview 1 host; packages/go/wasi/run.mjs runs it under Node.js 20 or later. CI builds every
platform, runs the command on Linux, Windows and macOS, and runs the module under Node.js 22 and
wasmtime.
Install from the repository
git clone https://github.com/YarlisAISolutions/rule-cascade.git && cd rule-cascade/packages/go
go build -o dist/rule-cascade ./cmd/rule-cascade # this machine
GOOS=wasip1 GOARCH=wasm go build -o dist/rule-cascade.wasm ./cmd/rule-cascade # the module
sh scripts/build-all.sh # every platform and the module, with dist/SHA256SUMSCI uploads the binaries of every platform and the module as the artefact rule-cascade-commands.
Commands
| Command | Does |
|---|---|
rule-cascade version | Prints the version |
rule-cascade check <file>... | Lints each ruleset, loads it and runs its golden tests. Exit status 1 on any problem |
rule-cascade compile <file> [-o out.bundle.json] | Compiles a ruleset into a bundle |
rule-cascade manifest <file-or-bundle> [--channel client|server] | Prints a manifest; the default is client |
rule-cascade evaluate --bundle <bundle.json> [--channel server|client] [request.json|-] | Evaluates one request; exit status 0 whatever the decision |
rule-cascade engine [--conformance-operators] | Serves the engine protocol |
Evaluate from another language
Start one engine process, load the bundle once, then send one evaluate line per request:
BUNDLE=conformance/bundles/acme.payments.transfer.bundle.json
{
jq -c '{id: 0, command: "load", bundle: .}' "$BUNDLE"
echo '{"id":1,"command":"evaluate","ruleset":"acme.payments.transfer","request":{"entity":"Transfer","operation":"create","data":{"type":"domestic","amount":-5}}}'
} | rule-cascade engineEvery response is {"id": ..., "ok": true, "result": ...} or
{"id": ..., "ok": false, "error": {"code": ..., "message": ...}}. The commands are version,
load, manifest, evaluate, expression and compile, defined in
section 13 of the specification.
The same protocol under the WebAssembly module:
echo '{"id":1,"command":"expression","expr":{"op":"round","args":[2.675,2]}}' |
node packages/go/wasi/run.mjs packages/go/dist/rule-cascade.wasm engine
# {"id":1,"ok":true,"result":2.68}examples/engine-clients has a client in Python, Node.js, Ruby, PHP,
Java, shell, Rust, C# and PowerShell, and two that load the module in process.
Errors
| What | How it surfaces |
|---|---|
| A ruleset that fails a check | check prints LOAD FAILED and the codes, exit status 1; compile refuses it |
| A golden test that fails | check prints FAIL <test name> and the difference, exit status 1 |
| A request line that is not JSON, or not a valid request | {"ok": false, "error": {"code": "BAD_REQUEST", ...}}; the engine keeps running |
| A rule that cannot be evaluated | A blocking RULE-EVALUATION-ERROR finding in the result |
| A custom operator | Not available: operators cannot cross a process boundary, so rules that need one fail closed. Use a library, or build the command with your operators registered |
More
The Go package README covers YAML portability, every platform and the WebAssembly host; Engine clients covers performance (keep one process alive; about 7,000 evaluations per second per process in its measurement).