Add BDD-based rules engine trait

This commit updates the smithy-rules-engine package to support
binary decision diagrams (BDD) to more efficiently resolve endpoints.

We create the BDD by converting the decision tree into a control flow
graph (CFG), then compile the CFG to a BDD. The CFG canonicalizes
conditions for better sharing (e.g., sorts commutative functions,
expands simple string templates, etc), and strips all conditions from
results and hash-conses them as well. Later, we'll migrate to emitting
the BDD directly in order to shave off many conditions and results
that can be simplified.

Our decision-tree based rules engine requires deep branching logic to
find results. When evaluating the path to a result based on given
input, decision trees require descending into a branch, and if
at any point a condition in the branch fails, you bail out and go
back up to the next branch. This can cause pathological searches of a
tree (e.g., 60+ repeated checks on things like isset and
booleanEquals to resolve S3 endpoints). In fact, there are currently
~73,000 unique paths through the current decision tree for S3 rules.

Using a BDD (a fully reduced one at least) guarantees that we only
evaluate any given condition at most once, and only when that condition
actually discriminates the result. This is achieved by recursively
converting the CFG into BDD nodes using ITE (if-then-else) operations,
choosing a variable ordering that honors dependencies between conditions
and variable bindings. The BDD builder applies Shannon expansion during
ITE operations and uses hash-consing to share common subgraphs.

The "bdd" trait has most of the same information as the endpointRuleset
trait, but doesn't include "rules". Instead it contains a base64
encoded "nodes" value that contains the zig-zag variable-length
encoded node triples, one after the other (this is much more compact
and efficient to decode than 1000+ JSON array nodes).

The BDD implementation uses CUDD-style complement edges where negative
node references represent logical NOT, further reducing BDD size.

Author: mtdowling

config/spotbugs/filter.xml

@@ -209,4 +209,10 @@
         <Bug code="CT"/>
     </Match>
 
+    <!-- This is a false positive. Yeah, we have a terminal node that's a singleton, but the ctor is still valid. -->
+    <Match>
+        <Class name="software.amazon.smithy.rulesengine.logic.cfg.ResultNode" />
+        <Bug pattern="SING_SINGLETON_HAS_NONPRIVATE_CONSTRUCTOR" />
+    </Match>
+
 </FindBugsFilter>

smithy-aws-endpoints/src/main/java/software/amazon/smithy/rulesengine/aws/language/functions/AwsArn.java

@@ -4,7 +4,7 @@
  */
 package software.amazon.smithy.rulesengine.aws.language.functions;
 
-import java.util.Arrays;
+import java.util.ArrayList;
 import java.util.List;
 import java.util.Objects;
 import java.util.Optional;
@@ -39,28 +39,67 @@ private AwsArn(Builder builder) {
      * @return the optional ARN.
      */
     public static Optional<AwsArn> parse(String arn) {
-        String[] base = arn.split(":", 6);
-        if (base.length != 6) {
+        if (arn == null || arn.length() < 8 || !arn.startsWith("arn:")) {
             return Optional.empty();
         }
-        // First section must be "arn".
-        if (!base[0].equals("arn")) {
+
+        // find each of the first five ':' positions
+        int p0 = 3; // after "arn"
+        int p1 = arn.indexOf(':', p0 + 1);
+        if (p1 < 0) {
+            return Optional.empty();
+        }
+
+        int p2 = arn.indexOf(':', p1 + 1);
+        if (p2 < 0) {
+            return Optional.empty();
+        }
+
+        int p3 = arn.indexOf(':', p2 + 1);
+        if (p3 < 0) {
             return Optional.empty();
         }
-        // Sections for partition, service, and resource type must not be empty.
-        if (base[1].isEmpty() || base[2].isEmpty() || base[5].isEmpty()) {
+
+        int p4 = arn.indexOf(':', p3 + 1);
+        if (p4 < 0) {
+            return Optional.empty();
+        }
+
+        // extract and validate mandatory parts
+        String partition = arn.substring(p0 + 1, p1);
+        String service = arn.substring(p1 + 1, p2);
+        String region = arn.substring(p2 + 1, p3);
+        String accountId = arn.substring(p3 + 1, p4);
+        String resource = arn.substring(p4 + 1);
+
+        if (partition.isEmpty() || service.isEmpty() || resource.isEmpty()) {
             return Optional.empty();
         }
 
         return Optional.of(builder()
-                .partition(base[1])
-                .service(base[2])
-                .region(base[3])
-                .accountId(base[4])
-                .resource(Arrays.asList(base[5].split("[:/]", -1)))
+                .partition(partition)
+                .service(service)
+                .region(region)
+                .accountId(accountId)
+                .resource(splitResource(resource))
                 .build());
     }
 
+    private static List<String> splitResource(String resource) {
+        List<String> result = new ArrayList<>();
+        int start = 0;
+        int length = resource.length();
+        for (int i = 0; i < length; i++) {
+            char c = resource.charAt(i);
+            if (c == ':' || c == '/') {
+                result.add(resource.substring(start, i));
+                start = i + 1;
+            }
+        }
+        result.add(resource.substring(start));
+        return result;
+    }
+
     /**
      * Builder to create an {@link AwsArn} instance.
      *

smithy-aws-endpoints/src/main/java/software/amazon/smithy/rulesengine/aws/language/functions/AwsPartition.java

@@ -184,6 +184,11 @@ public Value evaluate(List<Value> arguments) {
         public AwsPartition createFunction(FunctionNode functionNode) {
             return new AwsPartition(functionNode);
         }
+
+        @Override
+        public int getCostHeuristic() {
+            return 6;
+        }
     }
 
     /**

smithy-aws-endpoints/src/main/java/software/amazon/smithy/rulesengine/aws/language/functions/IsVirtualHostableS3Bucket.java

@@ -97,6 +97,11 @@ public Value evaluate(List<Value> arguments) {
         public IsVirtualHostableS3Bucket createFunction(FunctionNode functionNode) {
             return new IsVirtualHostableS3Bucket(functionNode);
         }
+
+        @Override
+        public int getCostHeuristic() {
+            return 8;
+        }
     }
 
     /**

smithy-aws-endpoints/src/main/java/software/amazon/smithy/rulesengine/aws/language/functions/ParseArn.java

@@ -125,5 +125,10 @@ public Value evaluate(List<Value> arguments) {
         public ParseArn createFunction(FunctionNode functionNode) {
             return new ParseArn(functionNode);
         }
+
+        @Override
+        public int getCostHeuristic() {
+            return 9;
+        }
     }
 }

smithy-rules-engine/src/main/java/software/amazon/smithy/rulesengine/language/Endpoint.java

@@ -206,21 +206,21 @@ public int hashCode() {
     @Override
     public String toString() {
         StringBuilder sb = new StringBuilder();
-        sb.append("url: ").append(url).append("\n");
+        sb.append("url: ").append(url);
 
         if (!headers.isEmpty()) {
-            sb.append("headers:\n");
+            sb.append("\nheaders:");
             for (Map.Entry<String, List<Expression>> entry : headers.entrySet()) {
-                sb.append(StringUtils.indent(String.format("%s: %s", entry.getKey(), entry.getValue()), 2))
-                        .append("\n");
+                sb.append("\n");
+                sb.append(StringUtils.indent(String.format("%s: %s", entry.getKey(), entry.getValue()), 2));
             }
         }
 
         if (!properties.isEmpty()) {
-            sb.append("properties:\n");
+            sb.append("\nproperties:");
             for (Map.Entry<Identifier, Literal> entry : properties.entrySet()) {
-                sb.append(StringUtils.indent(String.format("%s: %s", entry.getKey(), entry.getValue()), 2))
-                        .append("\n");
+                sb.append("\n");
+                sb.append(StringUtils.indent(String.format("%s: %s", entry.getKey(), entry.getValue()), 2));
             }
         }
 

smithy-rules-engine/src/main/java/software/amazon/smithy/rulesengine/language/evaluation/RuleEvaluator.java

@@ -19,6 +19,7 @@
 import software.amazon.smithy.rulesengine.language.syntax.expressions.functions.GetAttr;
 import software.amazon.smithy.rulesengine.language.syntax.expressions.literal.Literal;
 import software.amazon.smithy.rulesengine.language.syntax.parameters.Parameter;
+import software.amazon.smithy.rulesengine.language.syntax.parameters.Parameters;
 import software.amazon.smithy.rulesengine.language.syntax.rule.Condition;
 import software.amazon.smithy.rulesengine.language.syntax.rule.Rule;
 import software.amazon.smithy.rulesengine.language.syntax.rule.RuleValueVisitor;
@@ -70,6 +71,21 @@ public Value evaluateRuleSet(EndpointRuleSet ruleset, Map<Identifier, Value> par
         });
     }
 
+    /**
+     * Configure the rule evaluator with the given parameters and parameter values for manual evaluation.
+     *
+     * @param parameters Parameters of the ruleset to evaluate.
+     * @param parameterArguments Parameter values to evaluate the ruleset against.
+     * @return the updated evaluator.
+     */
+    public RuleEvaluator withParameters(Parameters parameters, Map<Identifier, Value> parameterArguments) {
+        for (Parameter parameter : parameters) {
+            parameter.getDefault().ifPresent(value -> scope.insert(parameter.getName(), value));
+        }
+        parameterArguments.forEach(scope::insert);
+        return this;
+    }
+
     /**
      * Evaluates the given condition in the current scope.
      *

smithy-rules-engine/src/main/java/software/amazon/smithy/rulesengine/language/evaluation/value/ArrayValue.java

@@ -101,4 +101,13 @@ public String toString() {
         }
         return "[" + String.join(", ", valueStrings) + "]";
     }
+
+    @Override
+    public Object toObject() {
+        List<Object> result = new ArrayList<>(values.size());
+        for (Value value : values) {
+            result.add(value.toObject());
+        }
+        return result;
+    }
 }

smithy-rules-engine/src/main/java/software/amazon/smithy/rulesengine/language/evaluation/value/BooleanValue.java

@@ -68,4 +68,9 @@ public int hashCode() {
     public String toString() {
         return String.valueOf(value);
     }
+
+    @Override
+    public Object toObject() {
+        return value;
+    }
 }

smithy-rules-engine/src/main/java/software/amazon/smithy/rulesengine/language/evaluation/value/EmptyValue.java

@@ -35,4 +35,9 @@ public Node toNode() {
     public String toString() {
         return "<empty>";
     }
+
+    @Override
+    public Object toObject() {
+        return null;
+    }
 }