Add evaluation listener

PiperOrigin-RevId: 569010652

bundle/src/main/java/dev/cel/bundle/BUILD.bazel

@@ -36,6 +36,7 @@ java_library(
         "//parser:macro",
         "//parser:parser_builder",
         "//runtime",
+        "//runtime:evaluation_listener",
         "@cel_spec//proto/cel/expr:expr_java_proto",
         "@maven//:com_google_code_findbugs_annotations",
         "@maven//:com_google_errorprone_error_prone_annotations",

bundle/src/main/java/dev/cel/bundle/CelBuilder.java

@@ -31,6 +31,7 @@
 import dev.cel.compiler.CelCompilerLibrary;
 import dev.cel.parser.CelMacro;
 import dev.cel.parser.CelStandardMacro;
+import dev.cel.runtime.CelEvaluationListener;
 import dev.cel.runtime.CelRuntime;
 import dev.cel.runtime.CelRuntimeLibrary;
 import java.util.function.Function;
@@ -282,6 +283,10 @@ public interface CelBuilder {
   @CanIgnoreReturnValue
   CelBuilder addRuntimeLibraries(Iterable<CelRuntimeLibrary> libraries);
 
+  /** Adds a listener that gets invoked as evaluation progresses through the AST. */
+  @CanIgnoreReturnValue
+  CelBuilder addEvaluationListener(CelEvaluationListener listener);
+
   /** Construct a new {@code Cel} instance from the provided configuration. */
   Cel build();
 }

bundle/src/main/java/dev/cel/bundle/CelImpl.java

@@ -49,6 +49,7 @@
 import dev.cel.parser.CelParserBuilder;
 import dev.cel.parser.CelStandardMacro;
 import dev.cel.runtime.CelEvaluationException;
+import dev.cel.runtime.CelEvaluationListener;
 import dev.cel.runtime.CelRuntime;
 import dev.cel.runtime.CelRuntimeBuilder;
 import dev.cel.runtime.CelRuntimeLegacyImpl;
@@ -339,6 +340,13 @@ public Builder addRuntimeLibraries(Iterable<CelRuntimeLibrary> libraries) {
       return this;
     }
 
+    @Override
+    public CelBuilder addEvaluationListener(CelEvaluationListener listener) {
+      checkNotNull(listener);
+      runtimeBuilder.addEvaluationListener(listener);
+      return this;
+    }
+
     @Override
     public Cel build() {
       return new CelImpl(

common/src/main/java/dev/cel/common/CelDescriptorUtil.java

@@ -14,7 +14,6 @@
 
 package dev.cel.common;
 
-import com.google.common.annotations.VisibleForTesting;
 import com.google.common.collect.ImmutableMap;
 import com.google.common.collect.ImmutableSet;
 import com.google.protobuf.DescriptorProtos.FileDescriptorSet;
@@ -63,7 +62,6 @@ public static ImmutableSet<FileDescriptor> getFileDescriptorsForDescriptors(
    * <p>Warning: This will produce unique FileDescriptor instances. Use with care especially in
    * hermetic environments.
    */
-  @VisibleForTesting
   public static ImmutableSet<FileDescriptor> getFileDescriptorsFromFileDescriptorSet(
       FileDescriptorSet fileDescriptorSet) {
     return FileDescriptorSetConverter.convert(fileDescriptorSet);

runtime/BUILD.bazel

@@ -40,3 +40,8 @@ java_library(
     name = "interpreter_util",
     exports = ["//runtime/src/main/java/dev/cel/runtime:interpreter_util"],
 )
+
+java_library(
+    name = "evaluation_listener",
+    exports = ["//runtime/src/main/java/dev/cel/runtime:evaluation_listener"],
+)

runtime/src/main/java/dev/cel/runtime/BUILD.bazel

@@ -73,6 +73,7 @@ java_library(
     exports = [":base"],
     deps = [
         ":base",
+        ":evaluation_listener",
         ":runtime_helper",
         ":unknown_attributes",
         "//:auto_value",
@@ -85,7 +86,6 @@ java_library(
         "//common/ast",
         "//common/internal:dynamic_proto",
         "//common/types:type_providers",
-        "//runtime:unknown_attributes",
         "@cel_spec//proto/cel/expr:expr_java_proto",
         "@maven//:com_google_code_findbugs_annotations",
         "@maven//:com_google_errorprone_error_prone_annotations",
@@ -142,14 +142,14 @@ java_library(
     ],
     deps = [
         ":base",
-        ":interpreter",
-        ":unknown_attributes",
+        ":evaluation_listener",
         "//:auto_value",
         "//common",
         "//common:error_codes",
         "//common:options",
         "//common/annotations",
         "//common/internal:dynamic_proto",
+        "//runtime:interpreter",
         "//runtime:unknown_attributes",
         "@maven//:com_google_code_findbugs_annotations",
         "@maven//:com_google_errorprone_error_prone_annotations",
@@ -216,3 +216,14 @@ java_library(
         "@maven//:org_jspecify_jspecify",
     ],
 )
+
+java_library(
+    name = "evaluation_listener",
+    srcs = ["CelEvaluationListener.java"],
+    tags = [
+    ],
+    deps = [
+        "//common/ast",
+        "@maven//:com_google_errorprone_error_prone_annotations",
+    ],
+)

runtime/src/main/java/dev/cel/runtime/CelEvaluationListener.java

@@ -0,0 +1,37 @@
+// Copyright 2023 Google LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//      https://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package dev.cel.runtime;
+
+import com.google.errorprone.annotations.Immutable;
+import dev.cel.common.ast.CelExpr;
+
+/** Functional interface for a callback method invoked by the runtime. */
+@FunctionalInterface
+@Immutable
+public interface CelEvaluationListener {
+
+  /**
+   * Callback method invoked by the CEL runtime as evaluation progresses through the AST.
+   *
+   * @param expr CelExpr that was evaluated to produce the evaluated result.
+   * @param evaluatedResult Evaluated result.
+   */
+  void callback(CelExpr expr, Object evaluatedResult);
+
+  /** Construct a listener that does nothing. */
+  static CelEvaluationListener noOpListener() {
+    return (arg1, arg2) -> {};
+  }
+}

runtime/src/main/java/dev/cel/runtime/CelRuntimeBuilder.java

@@ -149,6 +149,10 @@ public interface CelRuntimeBuilder {
   @CanIgnoreReturnValue
   CelRuntimeBuilder addLibraries(Iterable<? extends CelRuntimeLibrary> libraries);
 
+  /** Adds a listener that gets invoked as evaluation progresses through the AST. */
+  @CanIgnoreReturnValue
+  CelRuntimeBuilder addEvaluationListener(CelEvaluationListener listener);
+
   /** Build a new instance of the {@code CelRuntime}. */
   @CheckReturnValue
   CelRuntime build();

runtime/src/main/java/dev/cel/runtime/CelRuntimeLegacyImpl.java

@@ -74,92 +74,81 @@ public static final class Builder implements CelRuntimeBuilder {
 
     private boolean standardEnvironmentEnabled;
     private Function<String, Message.Builder> customTypeFactory;
+    private CelEvaluationListener evaluationListener;
 
-    /** {@inheritDoc} */
     @Override
     @CanIgnoreReturnValue
     public Builder setOptions(CelOptions options) {
       this.options = options;
       return this;
     }
 
-    /** {@inheritDoc} */
     @Override
     @CanIgnoreReturnValue
     public Builder addFunctionBindings(CelFunctionBinding... bindings) {
       return addFunctionBindings(Arrays.asList(bindings));
     }
 
-    /** {@inheritDoc} */
     @Override
     @CanIgnoreReturnValue
     public Builder addFunctionBindings(Iterable<CelFunctionBinding> bindings) {
       bindings.forEach(o -> functionBindings.put(o.getOverloadId(), o));
       return this;
     }
 
-    /** {@inheritDoc} */
     @Override
     @CanIgnoreReturnValue
     public Builder addMessageTypes(Descriptor... descriptors) {
       return addMessageTypes(Arrays.asList(descriptors));
     }
 
-    /** {@inheritDoc} */
     @Override
     @CanIgnoreReturnValue
     public Builder addMessageTypes(Iterable<Descriptor> descriptors) {
       return addFileTypes(CelDescriptorUtil.getFileDescriptorsForDescriptors(descriptors));
     }
 
-    /** {@inheritDoc} */
     @Override
     @CanIgnoreReturnValue
     public Builder addFileTypes(FileDescriptor... fileDescriptors) {
       return addFileTypes(Arrays.asList(fileDescriptors));
     }
 
-    /** {@inheritDoc} */
     @Override
     @CanIgnoreReturnValue
     public Builder addFileTypes(Iterable<FileDescriptor> fileDescriptors) {
       this.fileTypes.addAll(checkNotNull(fileDescriptors));
       return this;
     }
 
-    /** {@inheritDoc} */
     @Override
     @CanIgnoreReturnValue
     public Builder addFileTypes(FileDescriptorSet fileDescriptorSet) {
       return addFileTypes(
           CelDescriptorUtil.getFileDescriptorsFromFileDescriptorSet(fileDescriptorSet));
     }
 
-    /** {@inheritDoc} */
     @Override
     @CanIgnoreReturnValue
     public Builder setTypeFactory(Function<String, Message.Builder> typeFactory) {
       this.customTypeFactory = typeFactory;
       return this;
     }
 
-    /** {@inheritDoc} */
     @Override
     @CanIgnoreReturnValue
     public Builder setStandardEnvironmentEnabled(boolean value) {
       standardEnvironmentEnabled = value;
       return this;
     }
 
-    /** {@inheritDoc} */
     @Override
     @CanIgnoreReturnValue
     public Builder addLibraries(CelRuntimeLibrary... libraries) {
       checkNotNull(libraries);
       return this.addLibraries(Arrays.asList(libraries));
     }
 
-    /** {@inheritDoc} */
     @Override
     @CanIgnoreReturnValue
     public Builder addLibraries(Iterable<? extends CelRuntimeLibrary> libraries) {
@@ -168,6 +157,14 @@ public Builder addLibraries(Iterable<? extends CelRuntimeLibrary> libraries) {
       return this;
     }
 
+    @Override
+    @CanIgnoreReturnValue
+    public CelRuntimeBuilder addEvaluationListener(CelEvaluationListener listener) {
+      checkNotNull(listener);
+      this.evaluationListener = listener;
+      return this;
+    }
+
     /** Build a new {@code CelRuntimeLegacyImpl} instance from the builder config. */
     @Override
     @CanIgnoreReturnValue
@@ -232,7 +229,8 @@ public CelRuntimeLegacyImpl build() {
           new DefaultInterpreter(
               new DescriptorMessageProvider(runtimeTypeFactory, dynamicProto, options),
               dispatcher,
-              options),
+              options,
+              evaluationListener),
           options);
     }
 
@@ -252,6 +250,7 @@ private Builder() {
       this.messageTypes = ImmutableSet.builder();
       this.functionBindings = ImmutableMap.builder();
       this.celRuntimeLibraries = ImmutableSet.builder();
+      this.evaluationListener = CelEvaluationListener.noOpListener();
       this.customTypeFactory = null;
     }
   }