1// Copyright 2023 Google LLC 2// 3// Licensed under the Apache License, Version 2.0 (the "License"); 4// you may not use this file except in compliance with the License. 5// You may obtain a copy of the License at 6// 7// http://www.apache.org/licenses/LICENSE-2.0 8// 9// Unless required by applicable law or agreed to in writing, software 10// distributed under the License is distributed on an "AS IS" BASIS, 11// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12// See the License for the specific language governing permissions and 13// limitations under the License. 14 15syntax = "proto3"; 16 17package google.api.expr.v1alpha1; 18 19import "google/api/expr/v1alpha1/value.proto"; 20import "google/rpc/status.proto"; 21 22option cc_enable_arenas = true; 23option go_package = "google.golang.org/genproto/googleapis/api/expr/v1alpha1;expr"; 24option java_multiple_files = true; 25option java_outer_classname = "EvalProto"; 26option java_package = "com.google.api.expr.v1alpha1"; 27 28// The state of an evaluation. 29// 30// Can represent an inital, partial, or completed state of evaluation. 31message EvalState { 32 // A single evalution result. 33 message Result { 34 // The id of the expression this result if for. 35 int64 expr = 1; 36 37 // The index in `values` of the resulting value. 38 int64 value = 2; 39 } 40 41 // The unique values referenced in this message. 42 repeated ExprValue values = 1; 43 44 // An ordered list of results. 45 // 46 // Tracks the flow of evaluation through the expression. 47 // May be sparse. 48 repeated Result results = 3; 49} 50 51// The value of an evaluated expression. 52message ExprValue { 53 // An expression can resolve to a value, error or unknown. 54 oneof kind { 55 // A concrete value. 56 Value value = 1; 57 58 // The set of errors in the critical path of evalution. 59 // 60 // Only errors in the critical path are included. For example, 61 // `(<error1> || true) && <error2>` will only result in `<error2>`, 62 // while `<error1> || <error2>` will result in both `<error1>` and 63 // `<error2>`. 64 // 65 // Errors cause by the presence of other errors are not included in the 66 // set. For example `<error1>.foo`, `foo(<error1>)`, and `<error1> + 1` will 67 // only result in `<error1>`. 68 // 69 // Multiple errors *might* be included when evaluation could result 70 // in different errors. For example `<error1> + <error2>` and 71 // `foo(<error1>, <error2>)` may result in `<error1>`, `<error2>` or both. 72 // The exact subset of errors included for this case is unspecified and 73 // depends on the implementation details of the evaluator. 74 ErrorSet error = 2; 75 76 // The set of unknowns in the critical path of evaluation. 77 // 78 // Unknown behaves identically to Error with regards to propagation. 79 // Specifically, only unknowns in the critical path are included, unknowns 80 // caused by the presence of other unknowns are not included, and multiple 81 // unknowns *might* be included included when evaluation could result in 82 // different unknowns. For example: 83 // 84 // (<unknown[1]> || true) && <unknown[2]> -> <unknown[2]> 85 // <unknown[1]> || <unknown[2]> -> <unknown[1,2]> 86 // <unknown[1]>.foo -> <unknown[1]> 87 // foo(<unknown[1]>) -> <unknown[1]> 88 // <unknown[1]> + <unknown[2]> -> <unknown[1]> or <unknown[2[> 89 // 90 // Unknown takes precidence over Error in cases where a `Value` can short 91 // circuit the result: 92 // 93 // <error> || <unknown> -> <unknown> 94 // <error> && <unknown> -> <unknown> 95 // 96 // Errors take precidence in all other cases: 97 // 98 // <unknown> + <error> -> <error> 99 // foo(<unknown>, <error>) -> <error> 100 UnknownSet unknown = 3; 101 } 102} 103 104// A set of errors. 105// 106// The errors included depend on the context. See `ExprValue.error`. 107message ErrorSet { 108 // The errors in the set. 109 repeated google.rpc.Status errors = 1; 110} 111 112// A set of expressions for which the value is unknown. 113// 114// The unknowns included depend on the context. See `ExprValue.unknown`. 115message UnknownSet { 116 // The ids of the expressions with unknown values. 117 repeated int64 exprs = 1; 118} 119