Equation exposes a minimal environment to allow safe execution of Ruby code represented via a custom expression language.
A rules engine for your Ruby app! Use a constrained and relatively safe language to express logic for your Ruby app, without having to write Ruby. This allows you to use text (e.g. in a configuration file or database) to store logic in a way that can be updated independently from your code faster than it takes for a deploy without opening extra security vulnerabilities.
Use cases include:
Modeled loosely after Symfony Expression Language.
Take a look at the examples directory for some demonstrations of Equation's capabilities. The main example is a web application firewall for Rails; rules can be managed from any ActiveStorage compatible backend (e.g. filesystem, Amazon AWS, etc) and updated independently of application code, allowing for faster and more expressive blocking logic without having to wait for a deploy to go through.
In this example, we'll use a rule to determine whether a request should be dropped or not. While the rule here is hardcoded into the program, it could just as easily be pulled from a database, some redis cache, etc instead. Rules can also be cached, saving you an extra parsing step.
require 'equation'
# set up the execution environment and give it access to the rails request object
engine = EquationEngine.new(default: {
age: 12,
username: "OMAR",
request: request
})
suspicious_request = engine.eval(rule: '$request.path == "/api/login" && $request.remote_ip == "1.2.3.4" && $username == "OMAR"')
if suspicious_request
# log some things, notify some people
end
Because Equation is modeled after Symfony Expression Language, it supports a lot of the same features. For a more exhaustive list, check out the tests.
"hello world"
0
, -10
, 0.5
[403, 404]
or ["yes", "no", "maybe"]
; can be mixed typestrue
, false
nil
Variables are only made available to the engine at initialization. For example, given this setup code:
engine = EquationEngine.new(default: {name: "OMAR", age: 12})
These variables and all their properties are accessible from within rules:
$name == "OMAR" # true
$name.length # 4
$name.reverse # RAMO
Like variables, methods are only made available to the engine at initialization. They can take any number and type of arguments, including variables or return values from other methods.
engine = EquationEngine.new(default: {age: 12}, methods: {is_even: ->(n) {n%2==0}})
is_even
can now be called as follows:
is_even(5) # false
is_even($age) # true
$name == "Dumpling" && $age >= 12
$name in ["Dumpling", "Meatball"] || $age == 12
lib/equation_grammar.treetop
. Equation is built using treetop.bundle exec rake build_grammar
to generate the corresponding parser Ruby code.bundle exec rake spec
to run tests.