From 729a853e2f43a557cd46ab2e68cde5341b40f1e2 Mon Sep 17 00:00:00 2001 From: Patrick East Date: Thu, 28 May 2020 15:50:01 -0700 Subject: [PATCH] compile: Change name of result var for wasm binary Previously it was being bound to `$result` but this was then stripped out of the resultset by the planner. To avoid this issue we need the variable to not be seen as a wildcard or generated var. The new one is just `result`. The documentation is also now updated to show this behavior. The various client SDK's can strip it out as needed. The idea is that this is going to just be a part of the built WASM binary format. Anyone building with the lower level API's using ad-hoc queries will not need to worry about anything changing. Fixes: #2441 Signed-off-by: Patrick East --- compile/compile.go | 4 +++- docs/content/wasm.md | 28 +++++++++++++++++++++++++++- 2 files changed, 30 insertions(+), 2 deletions(-) diff --git a/compile/compile.go b/compile/compile.go index bfe43c0893..7da4a6b438 100644 --- a/compile/compile.go +++ b/compile/compile.go @@ -34,6 +34,8 @@ const ( TargetWasm = "wasm" ) +const wasmResultVar = ast.Var("result") + var validTargets = map[string]struct{}{ TargetRego: struct{}{}, TargetWasm: struct{}{}, @@ -300,7 +302,7 @@ func (c *Compiler) compileWasm(ctx context.Context) error { } store := inmem.NewFromObject(c.bundle.Data) - resultSym := ast.VarTerm(ast.WildcardPrefix + "__result__") + resultSym := ast.NewTerm(wasmResultVar) cr, err := rego.New( rego.ParsedQuery(ast.NewBody(ast.Equality.Expr(resultSym, c.entrypointrefs[0]))), diff --git a/docs/content/wasm.md b/docs/content/wasm.md index 7e38eda00e..130a7913a7 100644 --- a/docs/content/wasm.md +++ b/docs/content/wasm.md @@ -33,14 +33,40 @@ You can compile Rego policies into Wasm modules using the `opa build` subcommand For example, the `opa build` command below compiles the `example.rego` file into a Wasm module and packages it into an OPA bundle. The `wasm` target requires exactly -one entrypoint (specified by `-e`). +one entrypoint rule (specified by `-e`). ```bash opa build -t wasm -e example/allow example.rego ``` +The output of a Wasm module built this way contain the `result` of evaluating the +entrypoint rule. For example: +```json +[ + { + "result": + } +] +``` + +The output of policy evaluation is a set of variable assignments. The variable +assignments specify values that satisfy the expressions in the policy query +(i.e., if the variables in the query are replaced with the values from the +assignments, all of the expressions in the query would be defined and not +false.) + +When policies are compiled into Wasm, the user provides the path of the policy +decision that should be exposed by the Wasm module. The policy decision is +assigned to a variable named `result`. The policy decision can be ANY JSON value +(boolean, string, object, etc.) but there will be at-most-one assignment. This +means that callers should first check if the set of variable assignments is +empty (indicating an undefined policy decision) otherwise they should select the +`"result"` key out of the variable assignment set. + > For more information on `opa build` run `opa build --help`. +## Advanced Compiling Options + You can also compile Rego policies into Wasm modules from Go using the lower-level [rego](https://godoc.org/github.com/open-policy-agent/opa/rego#Rego.Compile) API that produces raw Wasm executables and the higher-level [compile]() API that