Improve crate documentation (microsoft#111)

- Document QueryResults - Delete snippets folder - Document Value Signed-off-by: Anand Krishnamoorthi <[email protected]>
anakrish · Jan 19, 2024 · 6eca85b · 6eca85b
1 parent f3884e8
commit 6eca85b
Show file tree

Hide file tree

Showing 17 changed files with 1,418 additions and 235 deletions.
diff --git a/.github/workflows/rust.yml b/.github/workflows/rust.yml
@@ -27,11 +27,13 @@ jobs:
     - name: Clippy
       run: cargo clippy --all-targets --no-deps -- -Dwarnings
     - name: Run tests
-      run: cargo test --verbose
+      run: cargo test -r --verbose
     - name: Build (MUSL)
       run: cargo build --verbose --all-targets --target x86_64-unknown-linux-musl
     - name: Run tests (MUSL)
-      run: cargo test --verbose --target x86_64-unknown-linux-musl
+      run: cargo test -r --verbose --target x86_64-unknown-linux-musl
+    - name: Run tests (ACI)
+      run: cargo test -r --test aci
     - name: Run tests (OPA Conformance)
       run: >-
-        cargo test --test opa -- $(tr '\n' ' ' < tests/opa.passing)
+        cargo test -r --test opa -- $(tr '\n' ' ' < tests/opa.passing)
diff --git a/Cargo.toml b/Cargo.toml
@@ -82,6 +82,7 @@ uuid = { version = "1.6.1", features = ["v4", "fast-rng"], optional = true }
 jsonschema = { version = "0.17.1", default-features = false, optional = true }
 chrono = { version = "0.4.31", optional = true }
 chrono-tz = { version = "0.8.5", optional = true }
+document-features = "0.2.8"
 
 
 [dev-dependencies]

diff --git a/README.md b/README.md
@@ -24,11 +24,11 @@ fn main() -> Result<()> {
     // Filename to be associated with the policy.
     "hello.rego".to_string(),
 
-	// Rego policy that just sets a message.
-	r#"
-	   package test
-	   message = "Hello, World!"
-	"#.to_string()
+    // Rego policy that just sets a message.
+    r#"
+       package test
+       message = "Hello, World!"
+    "#.to_string()
   )?;
 
   // Evaluate the policy, fetch the message and print it.
@@ -39,6 +39,25 @@ fn main() -> Result<()> {
 }
 ```
 
+Regorus is designed with [Confidential Computing](https://confidentialcomputing.io/about/) in mind. In Confidential Computing environments,
+it is important to be able to control exactly what is being run. Regorus allows enabling and disabling various components using cargo 
+features. By default all features are enabled.
+
+The default build of regorus example program is 6.4M:
+```bash
+$ cargo build -r --example regorus; strip target/release/examples/regorus; ls -lh target/release/examples/regorus
+$ cargo build -r --example regorus; strip target/release/examples/regorus; ls -lh target/release/examples/regorus
+-rwxr-xr-x  1 anand  staff   6.4M Jan 19 11:23 target/release/examples/regorus*
+```
+
+
+When all features except for `yaml` are disabled, the binary size drops down to 2.9M.
+```bash
+$ cargo build -r --example regorus --features "yaml" --no-default-features; strip target/release/examples/regorus; ls -lh target/release/examples/regorus
+-rwxr-xr-x  1 anand  staff   2.9M Jan 19 11:26 target/release/examples/regorus*
+```
+
+
 Regorus passes the [OPA v0.60.0 test-suite](https://www.openpolicyagent.org/docs/latest/ir/#test-suite) barring a few
 builtins. See [OPA Conformance](#opa-conformance) below.
 
@@ -228,6 +247,7 @@ They are captured in the following [github issues](https://github.com/microsoft/
 The grammar used by Regorus to parse Rego policies is described in [grammar.md](https://github.com/microsoft/regorus/blob/main/docs/grammar.md)
 in both [W3C EBNF](https://www.w3.org/Notation.html) and [RailRoad Diagram](https://en.wikipedia.org/wiki/Syntax_diagram) formats.
 
+
 ## Contributing
 
 This project welcomes contributions and suggestions.  Most contributions require you to agree to a

diff --git a/docs/builtins.md b/docs/builtins.md
diff --git a/snippets/2.rego b/snippets/2.rego
diff --git a/src/builtins/debugging.rs b/src/builtins/debugging.rs
@@ -28,11 +28,14 @@ fn print(span: &Span, _params: &[Ref<Expr>], args: &[Value], _strict: bool) -> R
     let mut msg = String::default();
     for a in args {
         match a {
-            Value::Undefined => msg += "<undefined>",
-            _ => msg += format!("{a}").as_str(),
+            Value::Undefined => msg += " <undefined>",
+            Value::String(s) => msg += &format!(" {s}"),
+            _ => msg += &format!(" {a}"),
         };
     }
 
-    span.message("print", msg.as_str());
+    if !msg.is_empty() {
+        println!("{}", &msg[1..]);
+    }
     Ok(Value::Bool(true))
 }
diff --git a/src/builtins/encoding.rs b/src/builtins/encoding.rs
@@ -3,14 +3,16 @@
 
 use crate::ast::{Expr, Ref};
 use crate::builtins;
+#[allow(unused)]
 use crate::builtins::utils::{
     ensure_args_count, ensure_object, ensure_string, ensure_string_collection,
 };
 use crate::lexer::Span;
 use crate::value::Value;
 
-use std::collections::{BTreeMap, HashMap};
+use std::collections::HashMap;
 
+#[allow(unused)]
 use anyhow::{anyhow, bail, Context, Result};
 
 pub fn register(m: &mut HashMap<&'static str, builtins::BuiltinFcn>) {
@@ -41,11 +43,6 @@ pub fn register(m: &mut HashMap<&'static str, builtins::BuiltinFcn>) {
     m.insert("json.is_valid", (json_is_valid, 1));
     m.insert("json.marshal", (json_marshal, 1));
     m.insert("json.unmarshal", (json_unmarshal, 1));
-    #[cfg(feature = "jsonschema")]
-    {
-        m.insert("json.match_schema", (json_match_schema, 2));
-        m.insert("json.verify_schema", (json_verify_schema, 1));
-    }
 
     #[cfg(feature = "yaml")]
     {
@@ -240,7 +237,7 @@ fn urlquery_decode_object(
         Err(_) => bail!(params[0].span().error("not a valid url query")),
     };
 
-    let mut map = BTreeMap::new();
+    let mut map = std::collections::BTreeMap::new();
     for (k, v) in url.query_pairs() {
         let key = Value::String(k.clone().into());
         let value = Value::String(v.clone().into());
@@ -382,72 +379,3 @@ fn json_unmarshal(
     let json_str = ensure_string(name, &params[0], &args[0])?;
     Value::from_json_str(&json_str).with_context(|| span.error("could not deserialize json."))
 }
-
-#[cfg(feature = "jsonschema")]
-fn compile_json_schema(param: &Ref<Expr>, arg: &Value) -> Result<jsonschema::JSONSchema> {
-    let schema_str = match arg {
-        Value::String(schema_str) => schema_str.as_ref().to_string(),
-        _ => arg.to_json_str()?,
-    };
-
-    if let Ok(schema) = serde_json::from_str(&schema_str) {
-        match jsonschema::JSONSchema::compile(&schema) {
-            Ok(schema) => return Ok(schema),
-            Err(e) => bail!(e.to_string()),
-        }
-    }
-    bail!(param.span().error("not a valid json schema"))
-}
-
-#[cfg(feature = "jsonschema")]
-fn json_verify_schema(
-    span: &Span,
-    params: &[Ref<Expr>],
-    args: &[Value],
-    strict: bool,
-) -> Result<Value> {
-    let name = "json.verify_schema";
-    ensure_args_count(span, name, params, args, 1)?;
-
-    Ok(Value::from_array(
-        match compile_json_schema(&params[0], &args[0]) {
-            Ok(_) => [Value::Bool(true), Value::Null],
-            Err(e) if strict => bail!(params[0]
-                .span()
-                .error(format!("invalid schema: {e}").as_str())),
-            Err(e) => [Value::Bool(false), Value::String(e.to_string().into())],
-        }
-        .to_vec(),
-    ))
-}
-
-#[cfg(feature = "jsonschema")]
-fn json_match_schema(
-    span: &Span,
-    params: &[Ref<Expr>],
-    args: &[Value],
-    strict: bool,
-) -> Result<Value> {
-    let name = "json.match_schema";
-    ensure_args_count(span, name, params, args, 2)?;
-
-    // The following is expected to succeed.
-    let document: serde_json::Value = serde_json::from_str(&args[0].to_json_str()?)?;
-
-    Ok(Value::from_array(
-        match compile_json_schema(&params[1], &args[1]) {
-            Ok(schema) => match schema.validate(&document) {
-                Ok(_) => [Value::Bool(true), Value::Null],
-                Err(e) => [
-                    Value::Bool(false),
-                    Value::from_array(e.map(|e| Value::String(e.to_string().into())).collect()),
-                ],
-            },
-            Err(e) if strict => bail!(params[1]
-                .span()
-                .error(format!("invalid schema: {e}").as_str())),
-            Err(e) => [Value::Bool(false), Value::String(e.to_string().into())],
-        }
-        .to_vec(),
-    ))
-}
diff --git a/src/builtins/objects.rs b/src/builtins/objects.rs
@@ -23,6 +23,12 @@ pub fn register(m: &mut HashMap<&'static str, builtins::BuiltinFcn>) {
     m.insert("object.subset", (subset, 2));
     m.insert("object.union", (object_union, 2));
     m.insert("object.union_n", (object_union_n, 1));
+
+    #[cfg(feature = "jsonschema")]
+    {
+        m.insert("json.match_schema", (json_match_schema, 2));
+        m.insert("json.verify_schema", (json_verify_schema, 1));
+    }
 }
 
 fn json_filter_impl(v: &Value, filter: &Value) -> Value {
@@ -382,3 +388,72 @@ fn object_union_n(
 
     Ok(u)
 }
+
+#[cfg(feature = "jsonschema")]
+fn compile_json_schema(param: &Ref<Expr>, arg: &Value) -> Result<jsonschema::JSONSchema> {
+    let schema_str = match arg {
+        Value::String(schema_str) => schema_str.as_ref().to_string(),
+        _ => arg.to_json_str()?,
+    };
+
+    if let Ok(schema) = serde_json::from_str(&schema_str) {
+        match jsonschema::JSONSchema::compile(&schema) {
+            Ok(schema) => return Ok(schema),
+            Err(e) => bail!(e.to_string()),
+        }
+    }
+    bail!(param.span().error("not a valid json schema"))
+}
+
+#[cfg(feature = "jsonschema")]
+fn json_verify_schema(
+    span: &Span,
+    params: &[Ref<Expr>],
+    args: &[Value],
+    strict: bool,
+) -> Result<Value> {
+    let name = "json.verify_schema";
+    ensure_args_count(span, name, params, args, 1)?;
+
+    Ok(Value::from_array(
+        match compile_json_schema(&params[0], &args[0]) {
+            Ok(_) => [Value::Bool(true), Value::Null],
+            Err(e) if strict => bail!(params[0]
+                .span()
+                .error(format!("invalid schema: {e}").as_str())),
+            Err(e) => [Value::Bool(false), Value::String(e.to_string().into())],
+        }
+        .to_vec(),
+    ))
+}
+
+#[cfg(feature = "jsonschema")]
+fn json_match_schema(
+    span: &Span,
+    params: &[Ref<Expr>],
+    args: &[Value],
+    strict: bool,
+) -> Result<Value> {
+    let name = "json.match_schema";
+    ensure_args_count(span, name, params, args, 2)?;
+
+    // The following is expected to succeed.
+    let document: serde_json::Value = serde_json::from_str(&args[0].to_json_str()?)?;
+
+    Ok(Value::from_array(
+        match compile_json_schema(&params[1], &args[1]) {
+            Ok(schema) => match schema.validate(&document) {
+                Ok(_) => [Value::Bool(true), Value::Null],
+                Err(e) => [
+                    Value::Bool(false),
+                    Value::from_array(e.map(|e| Value::String(e.to_string().into())).collect()),
+                ],
+            },
+            Err(e) if strict => bail!(params[1]
+                .span()
+                .error(format!("invalid schema: {e}").as_str())),
+            Err(e) => [Value::Bool(false), Value::String(e.to_string().into())],
+        }
+        .to_vec(),
+    ))
+}