Add timeout and stack guardrails

Author: rayokota

README.md

@@ -107,6 +107,36 @@ JSONata> (a & b)
 hello world
 ```
 
+## Guardrails
+
+JSONata is Turing-complete, so it's possible to write expressions that loop forever or exhaust memory. If you evaluate
+untrusted expressions, configure these guardrails (see the JS reference implementation's
+[guardrails docs](https://docs.jsonata.org/guardrails) for more background):
+
+- **Stack overflow** — the `stack` parameter caps the depth of the eval-apply cycle. Exceeding it raises `D1011`.
+- **Excessive execution time** — the `timeout` parameter (in milliseconds) catches tail-recursive infinite loops that
+  `stack` can't. Exceeding it raises `D1012`.
+- **Rogue regular expressions** — the `regex_engine` parameter lets you swap in a linear-time engine (e.g.
+  [`google-re2`](https://pypi.org/project/google-re2/)) to protect against [ReDoS](https://en.wikipedia.org/wiki/ReDoS),
+  since the `timeout` guardrail can't interrupt a regex match in progress.
+
+```python
+import re2  # pip install google-re2
+import jsonata
+from jsonata.regex_engine import RegexFlags
+
+
+def re2_regex_engine(pattern: str, flags: RegexFlags):
+    options = re2.Options()
+    options.case_sensitive = not flags.case_insensitive
+    options.one_line = not flags.multiline
+    return re2.compile(pattern, options)
+
+
+expr = jsonata.Jsonata("<JSONata expression>", re2_regex_engine, timeout=1000, stack=500)
+result = expr.evaluate(data)
+```
+
 ## Running Tests
 
 This project uses the repository of the reference implementation as a submodule. This allows referencing the current version of the unit tests. To clone this repository, run:

src/jsonata/functions.py

@@ -2228,22 +2228,45 @@ def function_eval(expr: Optional[str], focus: Optional[Any]) -> Optional[Any]:
         ast = None
         try:
             try:
+                # Only used to parse expr into an AST (ast.ast below); the
+                # actual evaluation reuses the enclosing instance directly
+                # (see below), so regex_engine here just needs to be valid
+                # for parsing -- it does not need to be evaluated against.
                 ast = jsonata.Jsonata(expr, enclosing.regex_engine)
             except Exception as err:
                 # error parsing the expression passed to $eval
                 # populateMessage(err)
                 raise jexception.JException("D3120", -1)
+
+            # Constructing `ast` overwrote Jsonata.CURRENT.jsonata as a side
+            # effect (see Jsonata.__init__); restore it to the enclosing
+            # instance before evaluating, so enclosing.eval()'s own
+            # get_per_thread_instance() lookup resolves correctly.
+            jsonata.Jsonata.CURRENT.jsonata = enclosing
+
             result = None
             try:
-                result = ast.evaluate(input, enclosing.environment)
+                # Evaluate ast.ast (the parsed tree) using the *enclosing*
+                # instance's low-level eval(), reusing enclosing.environment
+                # directly rather than calling ast.evaluate(input, environment)
+                # (which copies environment's bindings one level deep into a
+                # fresh child frame rooted at ast's own static frame). This
+                # mirrors jsonata-java's Functions.functionEval, which calls
+                # Jsonata.current.get().evaluate(ast.ast, input, env) rather
+                # than constructing a second, disconnected evaluation
+                # context. Reusing the environment directly means $eval sees
+                # bindings at every level of the enclosing scope chain (not
+                # just the immediate frame) and correctly inherits any
+                # stack/timeout guardrails registered on an ancestor frame,
+                # since Frame.lookup walks the parent chain.
+                result = enclosing.eval(ast.ast, input, enclosing.environment)
             except Exception as err:
                 # error evaluating the expression passed to $eval
                 # populateMessage(err)
                 raise jexception.JException("D3121", -1)
         finally:
-            # Restore the enclosing instance as current now that the nested
-            # expression's construction/evaluation (which needed CURRENT.jsonata
-            # to be the *inner* ast -- see Jsonata.get_per_thread_instance) is done.
+            # Restore the enclosing instance as current now that $eval's
+            # parsing/evaluation is done.
             jsonata.Jsonata.CURRENT.jsonata = enclosing
 
         return result

src/jsonata/jexception.py

@@ -175,6 +175,8 @@ def msg(error: str, location: int, arg1: Optional[Any], arg2: Optional[Any], det
         "T1007": "Attempted to partially apply a non-function. Did you mean ${{{token}}}?",
         "T1008": "Attempted to partially apply a non-function",
         "D1009": "Multiple key definitions evaluate to same key: {{value}}",
+        "D1011": "Stack overflow. Check for non-terminating recursive function.  Consider rewriting as tail-recursive",
+        "D1012": "Evaluation timeout after {{value}} milliseconds. Check for infinite loop",
         "T1010": "The matcher Object argument passed to Object {{token}} does not return the correct object structure",
         "T2001": "The left side of the {{token}} operator must evaluate to a number",
         "T2002": "The right side of the {{token}} operator must evaluate to a number",

src/jsonata/jsonata.py

@@ -72,7 +72,7 @@ def lookup(self, name: str) -> Optional[Any]:
         # @param timeout Timeout in millis
         # @param maxRecursionDepth Max recursion depth
         #         
-        def set_runtime_bounds(self, timeout: int, max_recursion_depth: int) -> None:
+        def set_runtime_bounds(self, timeout: Optional[int], max_recursion_depth: Optional[int]) -> None:
             timebox.Timebox(self, timeout, max_recursion_depth)
 
         def set_evaluate_entry_callback(self, cb: Callable) -> None:
@@ -1904,12 +1904,17 @@ def _static_initializer() -> None:
     #     compile JSONata regex literals. Every engine, including the
     #     default, must translate RegexFlags into its own native
     #     representation -- see jsonata.regex_engine.default_regex_engine.
+    # @param {Integer} timeout - max evaluation time in milliseconds, or None
+    #     for no limit. Raises D1012 if exceeded.
+    # @param {Integer} stack - max eval-apply recursion depth, or None for
+    #     no limit. Raises D1011 if exceeded.
     # @returns Evaluated expression
     # @throws jexception.JException An exception if an error occured.
     #
     @staticmethod
-    def jsonata(expression: Optional[str], regex_engine: RegexEngine = default_regex_engine) -> 'Jsonata':
-        return Jsonata(expression, regex_engine)
+    def jsonata(expression: Optional[str], regex_engine: RegexEngine = default_regex_engine,
+               timeout: Optional[int] = None, stack: Optional[int] = None) -> 'Jsonata':
+        return Jsonata(expression, regex_engine, timeout, stack)
 
     #
     # Internal constructor
@@ -1923,9 +1928,14 @@ def jsonata(expression: Optional[str], regex_engine: RegexEngine = default_regex
     timestamp: int
     input: Optional[Any]
     regex_engine: RegexEngine
+    timeout: Optional[int]
+    stack: Optional[int]
 
-    def __init__(self, expr: Optional[str], regex_engine: RegexEngine = default_regex_engine) -> None:
+    def __init__(self, expr: Optional[str], regex_engine: RegexEngine = default_regex_engine,
+                timeout: Optional[int] = None, stack: Optional[int] = None) -> None:
         self.regex_engine = regex_engine
+        self.timeout = timeout
+        self.stack = stack
         try:
             self.parser = Jsonata.get_parser()
             self.ast = self.parser.parse(expr, regex_engine)  # , optionsRecover);
@@ -1936,6 +1946,8 @@ def __init__(self, expr: Optional[str], regex_engine: RegexEngine = default_rege
             # populateMessage(err); // possible side-effects on `err`
             raise err
         self.environment = self.create_frame(Jsonata.static_frame)
+        if timeout is not None or stack is not None:
+            self.environment.set_runtime_bounds(timeout, stack)
 
         self.timestamp = timebox.Timebox.current_milli_time()  # will be overridden on each call to evalute()
 

src/jsonata/timebox.py

@@ -21,30 +21,31 @@
 #
 
 import time
+from typing import Optional
 
 from jsonata import jexception
 
 
 #
 # Configure max runtime / max recursion depth.
-# See Frame.setRuntimeBounds - usually not used directly
-# 
+# See Frame.set_runtime_bounds - usually not used directly
+#
 class Timebox:
     #
-    # Protect the process/browser from a runnaway expression
+    # Protect the process from a runaway expression
     # i.e. Infinite loop (tail recursion), or excessive stack growth
     #
     # @param {Object} expr - expression to protect
-    # @param {Number} timeout - max time in ms
-    # @param {Number} max_depth - max stack depth
+    # @param {Number} timeout - max time in ms, or None for no time limit
+    # @param {Number} max_depth - max stack depth, or None for no depth limit
     #
 
-    timeout: int
-    max_depth: int
+    timeout: Optional[int]
+    max_depth: Optional[int]
     time: int
     depth: int
 
-    def __init__(self, expr, timeout=10000, max_depth=100):
+    def __init__(self, expr, timeout: Optional[int] = None, max_depth: Optional[int] = None):
         self.timeout = timeout
         self.max_depth = max_depth
         self.time = Timebox.current_milli_time()
@@ -68,21 +69,12 @@ def exit_callback(exp, input, env, res):
         expr.set_evaluate_exit_callback(exit_callback)
 
     def check_runaway(self) -> None:
-        if self.depth > self.max_depth:
+        if self.max_depth is not None and self.depth > self.max_depth:
             # stack too deep
-            raise jexception.JException(
-                "Stack overflow error: Check for non-terminating recursive function.  Consider rewriting as tail-recursive. Depth=" + str(
-                    self.depth) + " max=" + str(self.max_depth), -1)
-            # stack: new Error().stack,
-            # code: "U1001"
-            # }
-        if Timebox.current_milli_time() - self.time > self.timeout:
+            raise jexception.JException("D1011", -1)
+        if self.timeout is not None and Timebox.current_milli_time() - self.time > self.timeout:
             # expression has run for too long
-            raise jexception.JException(
-                "Expression evaluation timeout: " + str(self.timeout) + "ms. Check for infinite loop", -1)
-            # stack: new Error().stack,
-            # code: "U1001"
-            # }
+            raise jexception.JException("D1012", -1, self.timeout)
 
     @staticmethod
     def current_milli_time() -> int: