Spellout - Simple expressions (set) evaluation microservice

  • Free software
  • Docker image cooked and ready to pull (only 5.8Mb!)

Pull the docker image:

docker pull lucasepe/spellout:v0.5.0

By default the microservice will listen to port number 8171:

docker run --publish 8171:8171 --rm lucasepe/spellout:v0.5.0

You can use the SPELLOUT_PORT environment variable to change the listening port:

docker run --env SPELLOUT_PORT=6890 --publish 6890:6890 --rm lucasepe/spellout:v0.5.0

The underlying engine is the great Gval (Go eVALuate) library.

Spellout can evaluate expressions with parameters, arimethetic, logical, and string operations:

  • basic expression: 10 > 0
  • parameterized expression: foo > 0
  • nested parameterized expression: foo.bar > 0
  • arithmetic expression: (requests_made * requests_succeeded / 100) >= 90
  • string expression: http_response_body == "service is ok"
  • float64 expression: (mem_used / total_mem) * 100

It can easily be extended with custom functions or operators:

  • custom date comparator: date(`2014-01-02`) > date(`2014-01-01 23:59:59`)
  • string length: strlen("someReallyLongInputString") <= 16

…and much more! For all the features checkout Gval (Go eVALuate) project.

Spellout API

Method URI
GET /ping
POST /v1/api/eval
POST /v1/api/matches

GET /ping

Health check endpoint - perform any checks, quickly return 200 OK and “.” as response body.

POST /v1/api/eval

Evaluate the specified expression.

Request body is a JSON object with two fields:

  • facts: JSON object used to fill the expression variables
  • expression: valid Gval (Go eVALuate) expression
POST /v1/api/eval
{
   "facts":{
      "foo":{
         "bar":34
      }
   },
   "expression":"foo.bar / 100"
}

output:

{
  "result": 0.34
}

another example

POST /v1/api/eval
{
   "facts":{
      "user":{
         "name":"Pinco Pallo",
         "email":"pinco.pallo@gmail.com",
         "age":45
      }
   },
   "expression":"\"Hello \" + user.name + \"!\""
}

output:

{
  "result": "Hello Pinco Pallo!"
}

POST /v1/api/matches

Evaluate a set of rules against the specified facts.

Request body is a JSON object with two fields:

  • facts: JSON object used to fill the expression variables
  • rules: array of rule objects

where each rule is a JSON object with the following properties:

  • priority: rule order of execution
  • name: rule unique name
  • expression: rule valid Gval (Go eVALuate) expression
POST /v1/api/matches
{
   "facts":{
      "requests_made":300,
      "requests_succeeded":281
   },
   "rules":[
      {
         "name":"Rule 1",
         "priority":2,
         "expression":"(requests_made * requests_succeeded / 100) >= 1500"
      },
      {
         "name":"Rule 2",
         "priority":1,
         "expression":"requests_made >= 100"
      }
   ]
}

output:

{
  "result": {
    "matches": false,
    "details": {
      "Rule 1": false,
      "Rule 2": true
    }
  }
}

as you can see matches will be true if and only if all the rules return true.

If you want to customize this microservice or want to deploy really microservices like this, contact me.