cel.expr.eval.proto Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of api Show documentation
There is a newer version: 1.0.47
// 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
//
//     http://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.

syntax = "proto3";

package cel.expr;

import "cel/expr/value.proto";
import "google/rpc/status.proto";

option cc_enable_arenas = true;
option go_package = "cel.dev/expr";
option java_multiple_files = true;
option java_outer_classname = "EvalProto";
option java_package = "dev.cel.expr";

// The state of an evaluation.
//
// Can represent an initial, partial, or completed state of evaluation.
message EvalState {
  // A single evaluation result.
  message Result {
    // The id of the expression this result if for.
    int64 expr = 1;

    // The index in `values` of the resulting value.
    int64 value = 2;
  }

  // The unique values referenced in this message.
  repeated ExprValue values = 1;

  // An ordered list of results.
  //
  // Tracks the flow of evaluation through the expression.
  // May be sparse.
  repeated Result results = 3;
}

// The value of an evaluated expression.
message ExprValue {
  // An expression can resolve to a value, error or unknown.
  oneof kind {
    Value value = 1;

    // The set of errors in the critical path of evaluation.
    //
    // Only errors in the critical path are included. For example,
    // `( || true) && ` will only result in ``,
    // while ` || ` will result in both `` and
    // ``.
    //
    // Errors cause by the presence of other errors are not included in the
    // set. For example `.foo`, `foo()`, and ` + 1` will
    // only result in ``.
    //
    // Multiple errors *might* be included when evaluation could result
    // in different errors. For example ` + ` and
    // `foo(, )` may result in ``, `` or both.
    // The exact subset of errors included for this case is unspecified and
    // depends on the implementation details of the evaluator.
    ErrorSet error = 2;

    // The set of unknowns in the critical path of evaluation.
    //
    // Unknown behaves identically to Error with regards to propagation.
    // Specifically, only unknowns in the critical path are included, unknowns
    // caused by the presence of other unknowns are not included, and multiple
    // unknowns *might* be included when evaluation could result in
    // different unknowns. For example:
    //
    //     ( || true) &&  -> 
    //      ||  -> 
    //     .foo -> 
    //     foo() -> 
    //      +  ->  or 
    //
    // Unknown takes precedence over Error in cases where a `Value` can short
    // circuit the result:
    //
    //      ||  -> 
    //      &&  -> 
    //
    // Errors take precedence in all other cases:
    //
    //      +  -> 
    //     foo(, ) -> 
    UnknownSet unknown = 3;
  }
}

// A set of errors.
//
// The errors included depend on the context. See `ExprValue.error`.
message ErrorSet {
  repeated google.rpc.Status errors = 1;
}

// A set of expressions for which the value is unknown.
//
// The unknowns included depend on the context. See `ExprValue.unknown`.
message UnknownSet {
  // The ids of the expressions with unknown values.
  repeated int64 exprs = 1;
}