From 6a960a12669cdbd32999bfa71ede03af8cbe917d Mon Sep 17 00:00:00 2001
From: Torin Sandall <torinsandall@gmail.com>
Date: Tue, 16 Nov 2021 16:31:23 -0800
Subject: [PATCH] docs: Add section on built-in function errors

Fixes #3686

Signed-off-by: Torin Sandall <torinsandall@gmail.com>
---
 docs/content/policy-language.md | 43 +++++++++++++++++++++++++++++++++
 docs/content/rest-api.md        |  2 ++
 2 files changed, 45 insertions(+)

diff --git a/docs/content/policy-language.md b/docs/content/policy-language.md
index 0f1a055ecb..96675214e6 100644
--- a/docs/content/policy-language.md
+++ b/docs/content/policy-language.md
@@ -1783,6 +1783,49 @@ them to avoid naming conflicts, e.g., `org.example.special_func`.
 See the [Policy Reference](../policy-reference#built-in-functions) document for
 details on each built-in function.
 
+### Errors
+
+By default, built-in function calls that encounter runtime errors evaluate to
+undefined (which can usually be treated as `false`) and do not halt policy
+evaluation. This ensures that built-in functions can be called with invalid
+inputs without causing the entire policy to stop evaluating.
+
+In most cases, policies do not have to implement any kind of error handling
+logic. If error handling is required, the built-in function call can be negated
+to test for undefined. For example:
+
+```live:eg/errors:module:merge_down
+allow {
+  io.jwt.verify_hs256(input.token, "secret")
+  [_, payload, _] := io.jwt.decode(input.token)
+  payload.role == "admin"
+}
+
+reason["invalid JWT supplied as input"] {
+  not io.jwt.decode(input.token)
+}
+```
+```live:eg/errors:input:merge_down
+{
+    "token": "a poorly formatted token"
+}
+```
+```live:eg/errors:output
+```
+
+If you wish to disable this behaviour and instead have built-in function call
+errors treated as exceptions that halt policy evaluation enable "strict built-in
+errors" in the caller:
+
+API | Flag
+--- | ---
+`POST v1/data` (HTTP) | `strict-builtin-errors` query parameter
+`GET v1/data` (HTTP) | `strict-builtin-errors` query parameter
+`opa eval` (CLI) | `--strict-builtin-errors`
+`opa run` (REPL) | `> strict-builtin-errors`
+`rego` Go module | `rego.StrictBuiltinErrors(true)` option
+Wasm | Not Available
+
 ## Example Data
 
 The rules below define the content of documents describing a simplistic deployment environment. These documents are referenced in other sections above.
diff --git a/docs/content/rest-api.md b/docs/content/rest-api.md
index fcb80aee9a..d37c395af3 100644
--- a/docs/content/rest-api.md
+++ b/docs/content/rest-api.md
@@ -730,6 +730,7 @@ The path separator is used to access values inside object and array documents. I
 - **explain** - Return query explanation in addition to result. Values: **full**.
 - **metrics** - Return query performance metrics in addition to result. See [Performance Metrics](#performance-metrics) for more detail.
 - **instrument** - Instrument query evaluation and return a superset of performance metrics in addition to result. See [Performance Metrics](#performance-metrics) for more detail.
+- **strict-builtin-errors** - Treat built-in function call errors as fatal and return an error immediately.
 
 #### Status Codes
 
@@ -830,6 +831,7 @@ The request body contains an object that specifies a value for [The input Docume
 - **explain** - Return query explanation in addition to result. Values: **full**.
 - **metrics** - Return query performance metrics in addition to result. See [Performance Metrics](#performance-metrics) for more detail.
 - **instrument** - Instrument query evaluation and return a superset of performance metrics in addition to result. See [Performance Metrics](#performance-metrics) for more detail.
+- **strict-builtin-errors** - Treat built-in function call errors as fatal and return an error immediately.
 
 #### Status Codes