From 95a9834487d476dc5cbf81de1136cf8c74d890bc Mon Sep 17 00:00:00 2001 From: Google APIs Date: Mon, 30 Sep 2019 10:05:30 -0700 Subject: [PATCH] Synchronize new proto/yaml changes. PiperOrigin-RevId: 272006912 --- google/api/expr/v1alpha1/cel.yaml | 69 +++++++++++++++++++ google/api/expr/v1alpha1/checked.proto | 25 +++---- .../expr/v1alpha1/conformance_service.proto | 45 ++++++------ google/api/expr/v1alpha1/eval.proto | 2 +- google/api/expr/v1alpha1/explain.proto | 2 +- google/api/expr/v1alpha1/syntax.proto | 32 +++++---- google/api/expr/v1alpha1/value.proto | 2 +- google/api/expr/v1beta1/decl.proto | 2 +- google/api/expr/v1beta1/eval.proto | 2 +- google/api/expr/v1beta1/expr.proto | 22 +++--- google/api/expr/v1beta1/source.proto | 2 +- google/api/expr/v1beta1/value.proto | 2 +- 12 files changed, 139 insertions(+), 68 deletions(-) create mode 100644 google/api/expr/v1alpha1/cel.yaml diff --git a/google/api/expr/v1alpha1/cel.yaml b/google/api/expr/v1alpha1/cel.yaml new file mode 100644 index 00000000..2f79c16d --- /dev/null +++ b/google/api/expr/v1alpha1/cel.yaml @@ -0,0 +1,69 @@ +type: google.api.Service +config_version: 3 +name: cel.googleapis.com +title: Common Expression Language + +apis: +- name: google.api.expr.v1alpha1.ConformanceService + +documentation: + summary: Defines common types for the Common Expression Language. + overview: |- + # Common Expression Language + + The Common Expression Language (CEL) implements common semantics for + expression evaluation, enabling different applications to more easily + interoperate. + + Key Applications + + * Security policy: organization have complex infrastructure and need + common tooling to reason about the system as a whole * Protocols: + expressions are a useful data type and require interoperability across + programming languages and platforms. + + + Guiding philosophy: + + 1. Keep it small & fast. + * CEL evaluates in linear time, is mutation free, and not + Turing-complete. This limitation is a feature of the language + design, which allows the implementation to evaluate orders of + magnitude faster than equivalently sandboxed JavaScript. 2. Make + it extensible. + * CEL is designed to be embedded in applications, and allows for + extensibility via its context which allows for functions and data + to be provided by the software that embeds it. 3. + Developer-friendly + * The language is approachable to developers. The initial spec was + based on the experience of developing Firebase Rules and usability + testing many prior iterations. * The library itself and + accompanying toolings should be easy to adopt by teams that seek + to integrate CEL into their platforms. + + The required components of a system that supports CEL are: + + * The textual representation of an expression as written by a developer. + It is of similar syntax of expressions in C/C++/Java/JavaScript * A + binary representation of an expression. It is an abstract syntax tree + (AST). + * A compiler library that converts the textual representation to the + binary representation. This can be done ahead of time (in the control + plane) or just before evaluation (in the data plane). * A context + containing one or more typed variables, often protobuf messages. Most + use-case will use attribute_context.proto + * An evaluator library that takes the binary format in the context and + produces a result, usually a Boolean. + + Example of boolean conditions and object construction: + + ``` c + // Condition + account.balance >= transaction.withdrawal + || (account.overdraftProtection + && account.overdraftLimit >= transaction.withdrawal - + account.balance) + + // Object construction + common.GeoPoint{ latitude: 10.0, longitude: -5.5 } + ``` diff --git a/google/api/expr/v1alpha1/checked.proto b/google/api/expr/v1alpha1/checked.proto index 60dd09e2..0a7e3c54 100644 --- a/google/api/expr/v1alpha1/checked.proto +++ b/google/api/expr/v1alpha1/checked.proto @@ -1,4 +1,4 @@ -// Copyright 2018 Google LLC. +// Copyright 2019 Google LLC. // // Licensed under the Apache License, Version 2.0 (the "License"); // you may not use this file except in compliance with the License. @@ -236,8 +236,8 @@ message Decl { // logging which are not observable from CEL). message FunctionDecl { // An overload indicates a function's parameter types and return type, and - // may optionally include a function body described in terms of - // [Expr][google.api.expr.v1alpha1.Expr] values. + // may optionally include a function body described in terms of [Expr][google.api.expr.v1alpha1.Expr] + // values. // // Functions overloads are declared in either a function or method // call-style. For methods, the `params[0]` is the expected type of the @@ -249,13 +249,11 @@ message Decl { // Required. Globally unique overload name of the function which reflects // the function name and argument types. // - // This will be used by a [Reference][google.api.expr.v1alpha1.Reference] - // to indicate the `overload_id` that was resolved for the function - // `name`. + // This will be used by a [Reference][google.api.expr.v1alpha1.Reference] to indicate the `overload_id` that + // was resolved for the function `name`. string overload_id = 1; - // List of function parameter [Type][google.api.expr.v1alpha1.Type] - // values. + // List of function parameter [Type][google.api.expr.v1alpha1.Type] values. // // Param types are disjoint after generic type parameters have been // replaced with the type `DYN`. Since the `DYN` type is compatible with @@ -297,11 +295,9 @@ message Decl { // Declarations are organized in containers and this represents the full path // to the declaration in its container, as in `google.api.expr.Decl`. // - // Declarations used as - // [FunctionDecl.Overload][google.api.expr.v1alpha1.Decl.FunctionDecl.Overload] - // parameters may or may not have a name depending on whether the overload is - // function declaration or a function definition containing a result - // [Expr][google.api.expr.v1alpha1.Expr]. + // Declarations used as [FunctionDecl.Overload][google.api.expr.v1alpha1.Decl.FunctionDecl.Overload] parameters may or may not + // have a name depending on whether the overload is function declaration or a + // function definition containing a result [Expr][google.api.expr.v1alpha1.Expr]. string name = 1; // Required. The declaration kind. @@ -326,8 +322,7 @@ message Reference { // presented candidates must happen at runtime because of dynamic types. The // type checker attempts to narrow down this list as much as possible. // - // Empty if this is not a reference to a - // [Decl.FunctionDecl][google.api.expr.v1alpha1.Decl.FunctionDecl]. + // Empty if this is not a reference to a [Decl.FunctionDecl][google.api.expr.v1alpha1.Decl.FunctionDecl]. repeated string overload_id = 3; // For references to constants, this may contain the value of the diff --git a/google/api/expr/v1alpha1/conformance_service.proto b/google/api/expr/v1alpha1/conformance_service.proto index 7a9321a0..47642aa7 100644 --- a/google/api/expr/v1alpha1/conformance_service.proto +++ b/google/api/expr/v1alpha1/conformance_service.proto @@ -1,4 +1,4 @@ -// Copyright 2018 Google LLC. +// Copyright 2019 Google LLC. // // Licensed under the Apache License, Version 2.0 (the "License"); // you may not use this file except in compliance with the License. @@ -17,13 +17,15 @@ syntax = "proto3"; package google.api.expr.v1alpha1; +import "google/api/client.proto"; import "google/api/expr/v1alpha1/checked.proto"; import "google/api/expr/v1alpha1/eval.proto"; import "google/api/expr/v1alpha1/syntax.proto"; +import "google/api/field_behavior.proto"; import "google/rpc/status.proto"; option cc_enable_arenas = true; -option go_package = "google.golang.org/genproto/googleapis/api/expr/v1alpha1;expr"; +option go_package = "google.golang.org/genproto/googleapis/api/expr/conformance/v1alpha1;confpb"; option java_multiple_files = true; option java_outer_classname = "ConformanceServiceProto"; option java_package = "com.google.api.expr.v1alpha1"; @@ -34,28 +36,34 @@ option java_package = "com.google.api.expr.v1alpha1"; // a server for this API. The API will be used for conformance testing // and other utilities. service ConformanceService { + option (google.api.default_host) = "cel.googleapis.com"; + // Transforms CEL source text into a parsed representation. - rpc Parse(ParseRequest) returns (ParseResponse) {} + rpc Parse(ParseRequest) returns (ParseResponse) { + option (google.api.method_signature) = "cel_source"; + } // Runs static checks on a parsed CEL representation and return // an annotated representation, or a set of issues. - rpc Check(CheckRequest) returns (CheckResponse) {} + rpc Check(CheckRequest) returns (CheckResponse) { + option (google.api.method_signature) = "parsed_expr"; + } // Evaluates a parsed or annotation CEL representation given // values of external bindings. - rpc Eval(EvalRequest) returns (EvalResponse) {} + rpc Eval(EvalRequest) returns (EvalResponse) { + } } // Request message for the Parse method. message ParseRequest { // Required. Source text in CEL syntax. - string cel_source = 1; + string cel_source = 1 [(google.api.field_behavior) = REQUIRED]; // Tag for version of CEL syntax, for future use. string syntax_version = 2; - // File or resource for source text, used in - // [SourceInfo][google.api.expr.v1alpha1.SourceInfo]. + // File or resource for source text, used in [SourceInfo][google.api.expr.v1alpha1.SourceInfo]. string source_location = 3; // Prevent macro expansion. See "Macros" in Language Defiinition. @@ -74,7 +82,7 @@ message ParseResponse { // Request message for the Check method. message CheckRequest { // Required. The parsed representation of the CEL program. - ParsedExpr parsed_expr = 1; + ParsedExpr parsed_expr = 1 [(google.api.field_behavior) = REQUIRED]; // Declarations of types for external variables and functions. // Required if program uses external variables or functions @@ -85,10 +93,9 @@ message CheckRequest { // Language Definition. string container = 3; - // If true, use only the declarations in - // [type_env][google.api.expr.v1alpha1.CheckRequest.type_env]. If false - // (default), add declarations for the standard definitions to the type - // environment. See "Standard Definitions" in the Language Definition. + // If true, use only the declarations in [type_env][google.api.expr.v1alpha1.CheckRequest.type_env]. If false (default), + // add declarations for the standard definitions to the type environment. See + // "Standard Definitions" in the Language Definition. bool no_std_env = 4; } @@ -113,12 +120,10 @@ message EvalRequest { } // Bindings for the external variables. The types SHOULD be compatible - // with the type environment in - // [CheckRequest][google.api.expr.v1alpha1.CheckRequest], if checked. + // with the type environment in [CheckRequest][google.api.expr.v1alpha1.CheckRequest], if checked. map bindings = 3; - // SHOULD be the same container as used in - // [CheckRequest][google.api.expr.v1alpha1.CheckRequest], if checked. + // SHOULD be the same container as used in [CheckRequest][google.api.expr.v1alpha1.CheckRequest], if checked. string container = 4; } @@ -128,9 +133,9 @@ message EvalResponse { ExprValue result = 1; // Any number of issues with [StatusDetails][] as the details. - // Note that CEL execution errors are reified into - // [ExprValue][google.api.expr.v1alpha1.ExprValue]. Nevertheless, we'll allow - // out-of-band issues to be raised, which also makes the replies more regular. + // Note that CEL execution errors are reified into [ExprValue][google.api.expr.v1alpha1.ExprValue]. + // Nevertheless, we'll allow out-of-band issues to be raised, + // which also makes the replies more regular. repeated google.rpc.Status issues = 2; } diff --git a/google/api/expr/v1alpha1/eval.proto b/google/api/expr/v1alpha1/eval.proto index f516ba6b..2187427d 100644 --- a/google/api/expr/v1alpha1/eval.proto +++ b/google/api/expr/v1alpha1/eval.proto @@ -1,4 +1,4 @@ -// Copyright 2018 Google LLC. +// Copyright 2019 Google LLC. // // Licensed under the Apache License, Version 2.0 (the "License"); // you may not use this file except in compliance with the License. diff --git a/google/api/expr/v1alpha1/explain.proto b/google/api/expr/v1alpha1/explain.proto index 089e144a..56f84405 100644 --- a/google/api/expr/v1alpha1/explain.proto +++ b/google/api/expr/v1alpha1/explain.proto @@ -1,4 +1,4 @@ -// Copyright 2018 Google LLC. +// Copyright 2019 Google LLC. // // Licensed under the Apache License, Version 2.0 (the "License"); // you may not use this file except in compliance with the License. diff --git a/google/api/expr/v1alpha1/syntax.proto b/google/api/expr/v1alpha1/syntax.proto index 4a3cb907..59bc2691 100644 --- a/google/api/expr/v1alpha1/syntax.proto +++ b/google/api/expr/v1alpha1/syntax.proto @@ -1,4 +1,4 @@ -// Copyright 2018 Google LLC. +// Copyright 2019 Google LLC. // // Licensed under the Apache License, Version 2.0 (the "License"); // you may not use this file except in compliance with the License. @@ -45,24 +45,21 @@ message ParsedExpr { // operators with the exception of the '.' operator are modelled as function // calls. This makes it easy to represent new operators into the existing AST. // -// All references within expressions must resolve to a -// [Decl][google.api.expr.v1alpha1.Decl] provided at type-check for an -// expression to be valid. A reference may either be a bare identifier `name` or -// a qualified identifier `google.api.name`. References may either refer to a -// value or a function declaration. +// All references within expressions must resolve to a [Decl][google.api.expr.v1alpha1.Decl] provided at +// type-check for an expression to be valid. A reference may either be a bare +// identifier `name` or a qualified identifier `google.api.name`. References +// may either refer to a value or a function declaration. // // For example, the expression `google.api.name.startsWith('expr')` references -// the declaration `google.api.name` within a -// [Expr.Select][google.api.expr.v1alpha1.Expr.Select] expression, and the -// function declaration `startsWith`. +// the declaration `google.api.name` within a [Expr.Select][google.api.expr.v1alpha1.Expr.Select] expression, and +// the function declaration `startsWith`. message Expr { // An identifier expression. e.g. `request`. message Ident { // Required. Holds a single, unqualified identifier, possibly preceded by a // '.'. // - // Qualified names are represented by the - // [Expr.Select][google.api.expr.v1alpha1.Expr.Select] expression. + // Qualified names are represented by the [Expr.Select][google.api.expr.v1alpha1.Expr.Select] expression. string name = 1; } @@ -239,8 +236,7 @@ message Expr { // primitives. // // Lists and structs are not included as constants as these aggregate types may -// contain [Expr][google.api.expr.v1alpha1.Expr] elements which require -// evaluation and are thus not constant. +// contain [Expr][google.api.expr.v1alpha1.Expr] elements which require evaluation and are thus not constant. // // Examples of literals include: `"hello"`, `b'bytes'`, `1u`, `4.2`, `-2`, // `true`, `null`. @@ -302,6 +298,16 @@ message SourceInfo { // A map from the parse node id (e.g. `Expr.id`) to the character offset // within source. map positions = 4; + + // A map from the parse node id where a macro replacement was made to the + // call `Expr` that resulted in a macro expansion. + // + // For example, `has(value.field)` is a function call that is replaced by a + // `test_only` field selection in the AST. Likewise, the call + // `list.exists(e, e > 10)` translates to a comprehension expression. The key + // in the map corresponds to the expression id of the expanded macro, and the + // value is the call `Expr` that was replaced. + map macro_calls = 5; } // A specific position in source. diff --git a/google/api/expr/v1alpha1/value.proto b/google/api/expr/v1alpha1/value.proto index a0508ed9..a6ba3876 100644 --- a/google/api/expr/v1alpha1/value.proto +++ b/google/api/expr/v1alpha1/value.proto @@ -1,4 +1,4 @@ -// Copyright 2018 Google LLC. +// Copyright 2019 Google LLC. // // Licensed under the Apache License, Version 2.0 (the "License"); // you may not use this file except in compliance with the License. diff --git a/google/api/expr/v1beta1/decl.proto b/google/api/expr/v1beta1/decl.proto index 6d079b82..d3d748b4 100644 --- a/google/api/expr/v1beta1/decl.proto +++ b/google/api/expr/v1beta1/decl.proto @@ -1,4 +1,4 @@ -// Copyright 2018 Google LLC. +// Copyright 2019 Google LLC. // // Licensed under the Apache License, Version 2.0 (the "License"); // you may not use this file except in compliance with the License. diff --git a/google/api/expr/v1beta1/eval.proto b/google/api/expr/v1beta1/eval.proto index cdbe6ac3..0c6c4d98 100644 --- a/google/api/expr/v1beta1/eval.proto +++ b/google/api/expr/v1beta1/eval.proto @@ -1,4 +1,4 @@ -// Copyright 2018 Google LLC. +// Copyright 2019 Google LLC. // // Licensed under the Apache License, Version 2.0 (the "License"); // you may not use this file except in compliance with the License. diff --git a/google/api/expr/v1beta1/expr.proto b/google/api/expr/v1beta1/expr.proto index 93b917f1..77249baf 100644 --- a/google/api/expr/v1beta1/expr.proto +++ b/google/api/expr/v1beta1/expr.proto @@ -1,4 +1,4 @@ -// Copyright 2018 Google LLC. +// Copyright 2019 Google LLC. // // Licensed under the Apache License, Version 2.0 (the "License"); // you may not use this file except in compliance with the License. @@ -45,24 +45,21 @@ message ParsedExpr { // operators with the exception of the '.' operator are modelled as function // calls. This makes it easy to represent new operators into the existing AST. // -// All references within expressions must resolve to a -// [Decl][google.api.expr.v1beta1.Decl] provided at type-check for an expression -// to be valid. A reference may either be a bare identifier `name` or a -// qualified identifier `google.api.name`. References may either refer to a -// value or a function declaration. +// All references within expressions must resolve to a [Decl][google.api.expr.v1beta1.Decl] provided at +// type-check for an expression to be valid. A reference may either be a bare +// identifier `name` or a qualified identifier `google.api.name`. References +// may either refer to a value or a function declaration. // // For example, the expression `google.api.name.startsWith('expr')` references -// the declaration `google.api.name` within a -// [Expr.Select][google.api.expr.v1beta1.Expr.Select] expression, and the -// function declaration `startsWith`. +// the declaration `google.api.name` within a [Expr.Select][google.api.expr.v1beta1.Expr.Select] expression, and +// the function declaration `startsWith`. message Expr { // An identifier expression. e.g. `request`. message Ident { // Required. Holds a single, unqualified identifier, possibly preceded by a // '.'. // - // Qualified names are represented by the - // [Expr.Select][google.api.expr.v1beta1.Expr.Select] expression. + // Qualified names are represented by the [Expr.Select][google.api.expr.v1beta1.Expr.Select] expression. string name = 1; } @@ -237,8 +234,7 @@ message Expr { // primitives. // // Lists and structs are not included as constants as these aggregate types may -// contain [Expr][google.api.expr.v1beta1.Expr] elements which require -// evaluation and are thus not constant. +// contain [Expr][google.api.expr.v1beta1.Expr] elements which require evaluation and are thus not constant. // // Examples of literals include: `"hello"`, `b'bytes'`, `1u`, `4.2`, `-2`, // `true`, `null`. diff --git a/google/api/expr/v1beta1/source.proto b/google/api/expr/v1beta1/source.proto index adaf84d5..78bb0a06 100644 --- a/google/api/expr/v1beta1/source.proto +++ b/google/api/expr/v1beta1/source.proto @@ -1,4 +1,4 @@ -// Copyright 2018 Google LLC. +// Copyright 2019 Google LLC. // // Licensed under the Apache License, Version 2.0 (the "License"); // you may not use this file except in compliance with the License. diff --git a/google/api/expr/v1beta1/value.proto b/google/api/expr/v1beta1/value.proto index a5ae0676..0978228d 100644 --- a/google/api/expr/v1beta1/value.proto +++ b/google/api/expr/v1beta1/value.proto @@ -1,4 +1,4 @@ -// Copyright 2018 Google LLC. +// Copyright 2019 Google LLC. // // Licensed under the Apache License, Version 2.0 (the "License"); // you may not use this file except in compliance with the License.