Embedded Rule Engine

Project roadmap

1. 01

   Design the rule format

   ~2h

   Write DESIGN.md: a rule has an id, a priority, a condition tree (all, any and not, combining comparisons on event fields with operators eq, ne, lt, gt, in, contains, matches (Lua patterns) and exists), actions (a name and parameters), and a stop flag. Rules are written in JSON or as Lua tables; show examples. Describe the evaluation order, what happens when a field is missing, and the reload behavior. Done when: DESIGN.md defines the format and evaluation with examples.

2. 02

   Load and validate rules

   ~2h

   Load rules from JSON (with a library such as lua-cjson or dkjson) or a Lua data file loaded in an empty environment. Validate every rule: unique ids, known operators, the right value types for each operator (such as a list for in), valid field paths (like event.user.country), and known actions. Report all problems with the rule id and the path inside the rule. Done when: valid rule files load, and invalid ones list every problem.

3. 03

   Compile rules into functions

   ~2.5h

   Turn each rule's condition tree into a Lua closure once, at load time (for example compiling eq into function(e) return get(e, path) == value end, and combining closures for all, any and not), and precompute sets for in so lookups are fast. Sort rules by priority. Done when: compiled rules give the same results as a simple interpreter of the tree on test events.

4. 04

   Evaluate events

   ~1.5h

   Write engine:evaluate(event) that runs rules in priority order, collects the actions of every matching rule, stops at a rule with the stop flag, and returns the actions plus the ids of the matching rules (for explaining decisions). Wrap each rule in pcall so one failing rule is logged and skipped. Done when: evaluating test events returns the expected actions and matching rules.

5. 05

   Reload and measure

   ~1.5h

   Add engine:reload(source) that loads, validates and compiles the new rules and swaps them in only if everything is valid, keeping the old rules otherwise. Measure evaluations per second with a few hundred rules and many events (with os.clock) and record them in README.md. Done when: invalid reloads keep the old rules, and README.md shows the performance.

6. 06

   Embed it in OpenResty

   ~2h

   Package the engine with a rockspec, and write an OpenResty example: load the rules in init_by_lua_block, build an event from each request (IP, path, method and headers) in access_by_lua_block, evaluate it, and apply actions such as deny (return 403) or add a header. Reload the rules from a local-only admin endpoint. Done when: requests matching a block rule get 403 in the OpenResty example, and others pass.

7. 07

   Test it

   ~2h

   Write busted tests: every operator (including missing fields and type mismatches), all, any and not combinations, priorities and stop, validation errors, a rule that errors at runtime, and reloading valid and invalid rules. Done when: busted passes.

Resources

• DocsProgramming in Lua: closures (first edition)
• DocsLua 5.4 reference manual
• DocsOpenResty: getting started
• DocsLuaRocks: creating a rock
• Docsbusted testing framework