1. はじめに
CEL とは
CEL は、高速で移植可能で安全に実行できるように設計された非チューリング完全な式言語です。CEL は単独で使用することも、より大きなプロダクトに埋め込むこともできます。
CEL は、ユーザーコードを安全に実行できる言語として設計されました。ユーザーの Python コードで eval() を盲目的に呼び出すのは危険ですが、ユーザーの CEL コードは安全に実行できます。また、CEL はパフォーマンスを低下させる動作を防ぐため、ナノ秒からマイクロ秒のオーダーで安全に評価されます。パフォーマンスが重要なアプリケーションに最適です。
CEL は、単一行関数やラムダ式に似た式を評価します。CEL は通常、ブール判定に使用されますが、JSON や protobuf メッセージなどのより複雑なオブジェクトを構築するために使用することもできます。
CEL はプロジェクトに適していますか？
CEL は AST から式をナノ秒からマイクロ秒で評価するため、CEL の理想的なユースケースは、パフォーマンスが重要なパスを持つアプリケーションです。CEL コードの AST へのコンパイルは、クリティカル パスで行うべきではありません。理想的なアプリケーションは、構成が頻繁に実行され、変更が比較的少ないアプリケーションです。
たとえば、サービスへの HTTP リクエストごとにセキュリティ ポリシーを実行することは、CEL の理想的なユースケースです。セキュリティ ポリシーはめったに変更されず、CEL がレスポンス時間に与える影響はごくわずかです。この場合、CEL はリクエストを許可するかどうかを示すブール値を返しますが、より複雑なメッセージを返すこともできます。
この Codelab の内容
この Codelab の最初のステップでは、CEL を使用する動機とそのコア コンセプトについて説明します。残りの部分は、一般的なユースケースをカバーするコーディング 演習に充てられています。言語、セマンティクス、機能の詳細については、GitHub の CEL 言語の定義と CEL Go ドキュメントをご覧ください。
この Codelab は、CEL をすでにサポートしているサービスを使用するために CEL を学習したいデベロッパーを対象としています。この Codelab では、CEL を独自のプロジェクトに統合する方法については説明しません。
学習内容
- CEL の基本コンセプト
- Hello, World: CEL を使用して文字列を評価する
- 変数の作成
- 論理 AND/OR 演算での CEL の短絡を理解する
- CEL を使用して JSON をビルドする方法
- CEL を使用して Protobuffer を構築する方法
- マクロを作成する
- CEL 式を調整する方法
必要なもの
前提条件
この Codelab は、Protocol Buffers と Go 言語の基本的な知識があることを前提としています。
プロトコル バッファに慣れていない場合は、最初の演習で CEL の仕組みを理解できますが、より高度な例ではプロトコル バッファが CEL への入力として使用されているため、理解が難しい場合があります。まず、これらのチュートリアルのいずれかを行うことを検討してください。CEL の使用に Protocol Buffers は必須ではありませんが、この Codelab では広範囲で使用されています。
次のコマンドを実行して、Go がインストールされていることをテストできます。
go --help
2. 主なコンセプト
アプリケーション
CEL は汎用であり、RPC のルーティングからセキュリティ ポリシーの定義まで、さまざまなアプリケーションで使用されています。CEL は拡張可能で、アプリケーションに依存せず、コンパイルを 1 回実行して評価を複数回行うワークフロー向けに最適化されています。
多くのサービスとアプリケーションが宣言型構成を評価します。たとえば、ロールベース アクセス制御（RBAC）は、ロールとユーザーのセットを指定するとアクセス決定を行う宣言型構成です。宣言型構成が 80% のユースケースである場合、CEL は、ユーザーがより表現力を必要とする残りの 20% を補完するのに役立つツールです。
コンパイル
式は環境に対してコンパイルされます。コンパイル ステップでは、protobuf 形式の抽象構文ツリー（AST）が生成されます。コンパイルされた式は通常、評価をできるだけ高速に保つために、将来の使用のために保存されます。コンパイルされた 1 つの式を、さまざまな入力で評価できます。
式
ユーザーは式を定義し、サービスとアプリケーションは式が実行される環境を定義します。関数シグネチャは入力を宣言し、CEL 式の外部に記述されます。CEL で使用できる関数のライブラリは自動的にインポートされます。
次の例では、式はリクエスト オブジェクトを取得し、リクエストにはクレーム トークンが含まれます。この式は、クレーム トークンがまだ有効かどうかを示すブール値を返します。
// Check whether a JSON Web Token has expired by inspecting the 'exp' claim.
//
// Args:
// claims - authentication claims.
// now - timestamp indicating the current system time.
// Returns: true if the token has expired.
//
timestamp(claims["exp"]) < now
環境
環境はサービスによって定義されます。CEL を埋め込むサービスとアプリケーションは、式環境を宣言します。環境とは、式で使用できる変数と関数のコレクションです。
proto ベースの宣言は、CEL 型チェッカーによって使用され、式内のすべての識別子と関数参照が正しく宣言され、使用されていることを確認します。
式の解析の 3 つのフェーズ
式の処理には、解析、チェック、評価の 3 つのフェーズがあります。CEL の最も一般的なパターンは、コントロール プレーンが構成時に式を解析してチェックし、AST を保存することです。
実行時に、データプレーンは AST を繰り返し取得して評価します。CEL はランタイム効率が最適化されていますが、レイテンシが重要なコードパスでは解析とチェックを行わないでください。
CEL は、ANTLR の字句解析 / 構文解析文法を使用して、人間が読める式から抽象構文ツリーに解析されます。解析フェーズでは、proto ベースの抽象構文ツリーが出力されます。AST の各 Expr ノードには、解析とチェック中に生成されたメタデータのインデックスに使用される整数 ID が含まれています。解析中に生成された syntax.proto は、式の文字列形式で入力された内容の抽象表現を忠実に表します。
式が解析されると、環境に対してチェックされ、式内のすべての変数と関数識別子が宣言され、正しく使用されていることが確認されます。型チェッカーは、評価効率を大幅に向上させる型、変数、関数解決メタデータを含む checked.proto を生成します。
CEL エバリュエータには次の 3 つが必要です。
- カスタム拡張機能の関数バインディング
- バリエーション バインディング
- 評価する AST
関数と変数のバインディングは、AST のコンパイルに使用されたものと一致している必要があります。これらの入力は、複数の評価で再利用できます。たとえば、多くの変数バインディングのセットで評価される AST、多くの AST で使用される同じ変数、プロセスのライフサイクル全体で使用される関数バインディングなどです（一般的なケース）。
3. セットアップ
この Codelab のコードは、cel-go リポジトリの codelab フォルダにあります。ソリューションは、同じリポジトリの codelab/solution フォルダにあります。
リポジトリのクローンを作成して、そのリポジトリに移動します。
git clone https://github.com/google/cel-go.git
cd cel-go/codelab
go run を使用してコードを実行します。
go run .
次の出力が表示されます。
=== Exercise 1: Hello World ===
=== Exercise 2: Variables ===
=== Exercise 3: Logical AND/OR ===
=== Exercise 4: Customization ===
=== Exercise 5: Building JSON ===
=== Exercise 6: Building Protos ===
=== Exercise 7: Macros ===
=== Exercise 8: Tuning ===
CEL パッケージはどこにありますか？
エディタで codelab/codelab.go を開きます。この Codelab の演習の実行を制御する main 関数と、3 つのヘルパー関数のブロックが表示されます。最初のヘルパー セットは、CEL 評価のフェーズを支援します。
Compile関数: 入力式を解析して環境と照合し、チェックするEval関数: コンパイルされたプログラムを入力に対して評価しますReport関数: 評価結果を整形して出力します。
また、さまざまな演習の入力構築を支援するために、request ヘルパーと auth ヘルパーが用意されています。
演習では、パッケージは短いパッケージ名で参照されます。詳細を確認する場合は、google/cel-go リポジトリ内のパッケージからソースの場所へのマッピングを以下に示します。
パッケージ | ソースの場所 | 説明 |
cel | トップレベル インターフェース | |
ref | 参照インターフェース | |
タイプ | ランタイム タイプの値 |
4. Hello, World!
すべてのプログラミング言語の伝統にのっとり、「Hello World!」を作成して評価することから始めます。
環境を構成する
エディタで exercise1 の宣言を見つけ、次の値を入力して環境を設定します。
// exercise1 evaluates a simple literal expression: "Hello, World!"
//
// Compile, eval, profit!
func exercise1() {
fmt.Println("=== Exercise 1: Hello World ===\n")
// Create the standard environment.
env, err := cel.NewEnv()
if err != nil {
glog.Exitf("env error: %v", err)
}
// Will add the parse and check steps here
}
CEL アプリケーションは、Environment に対して式を評価します。env, err := cel.NewEnv() は標準環境を構成します。
環境は、呼び出しにオプション cel.EnvOption を指定することでカスタマイズできます。これらのオプションでは、マクロの無効化、カスタム変数と関数の宣言などを行うことができます。
標準の CEL 環境は、言語仕様で定義されているすべての型、演算子、関数、マクロをサポートしています。
式を解析して確認する
環境が構成されると、式を解析してチェックできます。関数に次のコードを追加します。
// exercise1 evaluates a simple literal expression: "Hello, World!"
//
// Compile, eval, profit!
func exercise1() {
fmt.Println("=== Exercise 1: Hello World ===\n")
// Create the standard environment.
env, err := cel.NewEnv()
if err != nil {
glog.Exitf("env error: %v", err)
}
// Check that the expression compiles and returns a String.
ast, iss := env.Parse(`"Hello, World!"`)
// Report syntactic errors, if present.
if iss.Err() != nil {
glog.Exit(iss.Err())
}
// Type-check the expression for correctness.
checked, iss := env.Check(ast)
// Report semantic errors, if present.
if iss.Err() != nil {
glog.Exit(iss.Err())
}
// Check the output type is a string.
if !reflect.DeepEqual(checked.OutputType(), cel.StringType) {
glog.Exitf(
"Got %v, wanted %v output type",
checked.OutputType(), cel.StringType,
)
}
// Will add the planning step here
}
Parse 呼び出しと Check 呼び出しによって返される iss 値は、エラーの可能性がある問題のリストです。iss.Err() が nil 以外の場合、構文またはセマンティクスにエラーがあり、プログラムはそれ以上進むことができません。式が整形式の場合、これらの呼び出しの結果は実行可能な cel.Ast になります。
式を評価する
式が解析されて cel.Ast にチェックインされると、評価可能なプログラムに変換できます。このプログラムの関数バインディングと評価モードは、関数オプションを使用してカスタマイズできます。cel.CheckedExprToAst 関数または cel.ParsedExprToAst 関数を使用して、proto から cel.Ast を読み取ることもできます。
cel.Program を計画したら、Eval を呼び出して入力に対して評価できます。Eval の結果には、結果、評価の詳細、エラー ステータスが含まれます。
プランニングを追加して eval を呼び出します。
// exercise1 evaluates a simple literal expression: "Hello, World!"
//
// Compile, eval, profit!
func exercise1() {
fmt.Println("=== Exercise 1: Hello World ===\n")
// Create the standard environment.
env, err := cel.NewEnv()
if err != nil {
glog.Exitf("env error: %v", err)
}
// Check that the expression compiles and returns a String.
ast, iss := env.Parse(`"Hello, World!"`)
// Report syntactic errors, if present.
if iss.Err() != nil {
glog.Exit(iss.Err())
}
// Type-check the expression for correctness.
checked, iss := env.Check(ast)
// Report semantic errors, if present.
if iss.Err() != nil {
glog.Exit(iss.Err())
}
// Check the output type is a string.
if !reflect.DeepEqual(checked.OutputType(), cel.StringType) {
glog.Exitf(
"Got %v, wanted %v output type",
checked.OutputType(), cel.StringType)
}
// Plan the program.
program, err := env.Program(checked)
if err != nil {
glog.Exitf("program error: %v", err)
}
// Evaluate the program without any additional arguments.
eval(program, cel.NoVars())
fmt.Println()
}
以降の演習では、簡潔にするため、上記のエラーケースは省略します。
コードを実行する
コマンドラインで、コードを再実行します。
go run .
次の出力が表示されます。今後の演習用のプレースホルダも表示されます。
=== Exercise 1: Hello World ===
------ input ------
(interpreter.emptyActivation)
------ result ------
value: Hello, World! (types.String)
5. 関数で変数を使用する
ほとんどの CEL アプリケーションは、式内で参照できる変数を宣言します。変数の宣言では、名前と型を指定します。変数の型は、CEL 組み込み型、プロトコル バッファの既知の型、または記述子が CEL にも提供されている限り、任意の protobuf メッセージ型にできます。
関数を追加する
エディタで exercise2 の宣言を見つけ、次を追加します。
// exercise2 shows how to declare and use variables in expressions.
//
// Given a request of type google.rpc.context.AttributeContext.Request
// determine whether a specific auth claim is set.
func exercise2() {
fmt.Println("=== Exercise 2: Variables ===\n")
env, err := cel.NewEnv(
// Add cel.EnvOptions values here.
)
if err != nil {
glog.Exit(err)
}
ast := compile(env, `request.auth.claims.group == 'admin'`, cel.BoolType)
program, _ := env.Program(ast)
// Evaluate a request object that sets the proper group claim.
claims := map[string]string{"group": "admin"}
eval(program, request(auth("user:me@acme.co", claims), time.Now()))
fmt.Println()
}
再実行してエラーを理解する
プログラムを再実行します。
go run .
次の出力が表示されます。
ERROR: <input>:1:1: undeclared reference to 'request' (in container '')
| request.auth.claims.group == 'admin'
| ^
型チェッカーは、エラーが発生したソース スニペットを便利に含むリクエスト オブジェクトのエラーを生成します。
6. 変数を宣言する
EnvOptions を追加
エディタで、次のようにリクエスト オブジェクトの宣言を google.rpc.context.AttributeContext.Request 型のメッセージとして指定して、エラーを修正しましょう。
// exercise2 shows how to declare and use variables in expressions.
//
// Given a `request` of type `google.rpc.context.AttributeContext.Request`
// determine whether a specific auth claim is set.
func exercise2() {
fmt.Println("=== Exercise 2: Variables ===\n")
env, err := cel.NewEnv(
cel.Variable("request",
cel.ObjectType("google.rpc.context.AttributeContext.Request"),
),
)
if err != nil {
glog.Exit(err)
}
ast := compile(env, `request.auth.claims.group == 'admin'`, cel.BoolType)
program, _ := env.Program(ast)
// Evaluate a request object that sets the proper group claim.
claims := map[string]string{"group": "admin"}
eval(program, request(auth("user:me@acme.co", claims), time.Now()))
fmt.Println()
}
再実行してエラーを理解する
プログラムを再度実行します。
go run .
次のようなエラーが表示されます。
ERROR: <input>:1:8: [internal] unexpected failed resolution of 'google.rpc.context.AttributeContext.Request'
| request.auth.claims.group == 'admin'
| .......^
protobuf メッセージを参照する変数を使用するには、型チェッカーが型記述子も認識している必要があります。
cel.Types を使用して、関数内のリクエストの記述子を決定します。
// exercise2 shows how to declare and use variables in expressions.
//
// Given a `request` of type `google.rpc.context.AttributeContext.Request`
// determine whether a specific auth claim is set.
func exercise2() {
fmt.Println("=== Exercise 2: Variables ===\n")
env, err := cel.NewEnv(
cel.Types(&rpcpb.AttributeContext_Request{}),
cel.Variable("request",
cel.ObjectType("google.rpc.context.AttributeContext.Request"),
),
)
if err != nil {
glog.Exit(err)
}
ast := compile(env, `request.auth.claims.group == 'admin'`, cel.BoolType)
program, _ := env.Program(ast)
// Evaluate a request object that sets the proper group claim.
claims := map[string]string{"group": "admin"}
eval(program, request(auth("user:me@acme.co", claims), time.Now()))
fmt.Println()
}
再実行が完了しました。
プログラムを再度実行します。
go run .
次の結果が表示されます。
=== Exercise 2: Variables ===
request.auth.claims.group == 'admin'
------ input ------
request = time: <
seconds: 1569255569
>
auth: <
principal: "user:me@acme.co"
claims: <
fields: <
key: "group"
value: <
string_value: "admin"
>
>
>
>
------ result ------
value: true (types.Bool)
要約すると、エラーの変数を宣言し、型記述子を割り当てて、式評価で変数を参照しました。
7. 論理 AND/OR
CEL のユニークな機能の一つは、可換論理演算子を使用することです。条件分岐のどちら側でも、エラーや部分的な入力があっても評価を短絡できます。
つまり、CEL は、他の評価順序で発生する可能性のあるエラーや欠落したデータは無視して、可能な限り結果が得られる評価順序を見つけます。アプリケーションはこのプロパティを利用して、結果がなくても結果が得られる場合は高価な入力の収集を延期することで、評価のコストを最小限に抑えることができます。
AND/OR の例を追加し、さまざまな入力で試して、CEL が評価を短絡させる方法を確認します。
関数を作成する
エディタで、演習 3 に次のコンテンツを追加します。
// exercise3 demonstrates how CEL's commutative logical operators work.
//
// Construct an expression which checks if the `request.auth.claims.group`
// value is equal to admin or the `request.auth.principal` is
// `user:me@acme.co`. Issue two requests, one that specifies the proper
// user, and one that specifies an unexpected user.
func exercise3() {
fmt.Println("=== Exercise 3: Logical AND/OR ===\n")
env, _ := cel.NewEnv(
cel.Types(&rpcpb.AttributeContext_Request{}),
cel.Variable("request",
cel.ObjectType("google.rpc.context.AttributeContext.Request"),
),
)
}
次に、ユーザーが admin グループのメンバーであるか、特定のメール識別子を持っている場合に true を返す OR ステートメントを含めます。
// exercise3 demonstrates how CEL's commutative logical operators work.
//
// Construct an expression which checks if the `request.auth.claims.group`
// value is equal to admin or the `request.auth.principal` is
// `user:me@acme.co`. Issue two requests, one that specifies the proper
// user, and one that specifies an unexpected user.
func exercise3() {
fmt.Println("=== Exercise 3: Logical AND/OR ===\n")
env, _ := cel.NewEnv(
cel.Types(&rpcpb.AttributeContext_Request{}),
cel.Variable("request",
cel.ObjectType("google.rpc.context.AttributeContext.Request"),
),
)
ast := compile(env,
`request.auth.claims.group == 'admin'
|| request.auth.principal == 'user:me@acme.co'`,
cel.BoolType)
program, _ := env.Program(ast)
}
最後に、空のクレーム セットでユーザーを評価する eval ケースを追加します。
// exercise3 demonstrates how CEL's commutative logical operators work.
//
// Construct an expression which checks whether the request.auth.claims.group
// value is equal to admin or the request.auth.principal is
// user:me@acme.co. Issue two requests, one that specifies the proper user,
// and one that specifies an unexpected user.
func exercise3() {
fmt.Println("=== Exercise 3: Logical AND/OR ===\n")
env, _ := cel.NewEnv(
cel.Types(&rpcpb.AttributeContext_Request{}),
cel.Variable("request",
cel.ObjectType("google.rpc.context.AttributeContext.Request"),
),
)
ast := compile(env,
`request.auth.claims.group == 'admin'
|| request.auth.principal == 'user:me@acme.co'`,
cel.BoolType)
program, _ := env.Program(ast)
emptyClaims := map[string]string{}
eval(program, request(auth("user:me@acme.co", emptyClaims), time.Now()))
}
空のクレーム セットでコードを実行する
プログラムを再実行すると、次の新しい出力が表示されます。
=== Exercise 3: Logical AND/OR ===
request.auth.claims.group == 'admin'
|| request.auth.principal == 'user:me@acme.co'
------ input ------
request = time: <
seconds: 1569302377
>
auth: <
principal: "user:me@acme.co"
claims: <
>
>
------ result ------
value: true (types.Bool)
評価ケースを更新する
次に、評価ケースを更新して、空のクレーム セットで別のプリンシパルを渡します。
// exercise3 demonstrates how CEL's commutative logical operators work.
//
// Construct an expression which checks whether the request.auth.claims.group
// value is equal to admin or the request.auth.principal is
// user:me@acme.co. Issue two requests, one that specifies the proper user,
// and one that specifies an unexpected user.
func exercise3() {
fmt.Println("=== Exercise 3: Logical AND/OR ===\n")
env, _ := cel.NewEnv(
cel.Types(&rpcpb.AttributeContext_Request{}),
cel.Variable("request",
cel.ObjectType("google.rpc.context.AttributeContext.Request"),
),
)
ast := compile(env,
`request.auth.claims.group == 'admin'
|| request.auth.principal == 'user:me@acme.co'`,
cel.BoolType)
program, _ := env.Program(ast)
emptyClaims := map[string]string{}
eval(program, request(auth("other:me@acme.co", emptyClaims), time.Now()))
}
時間付きでコードを実行する
プログラムを再実行すると、
go run .
次のエラーが表示されます。
=== Exercise 3: Logical AND/OR ===
request.auth.claims.group == 'admin'
|| request.auth.principal == 'user:me@acme.co'
------ input ------
request = time: <
seconds: 1588989833
>
auth: <
principal: "user:me@acme.co"
claims: <
>
>
------ result ------
value: true (types.Bool)
------ input ------
request = time: <
seconds: 1588989833
>
auth: <
principal: "other:me@acme.co"
claims: <
>
>
------ result ------
error: no such key: group
protobuf では、想定されるフィールドと型がわかっています。マップ値と JSON 値では、キーが存在するかどうかはわかりません。キーがない場合の安全なデフォルト値がないため、CEL はデフォルトでエラーになります。
8. カスタム関数
CEL には多くの組み込み関数が含まれていますが、カスタム関数が役立つ場合もあります。たとえば、カスタム関数を使用して、一般的な条件のユーザー エクスペリエンスを改善したり、コンテキストに応じた状態を公開したりできます。
この演習では、よく使用されるチェックをまとめてパッケージ化する関数を公開する方法について説明します。
カスタム関数を呼び出す
まず、contains というオーバーライドを設定するコードを作成します。このオーバーライドは、マップにキーが存在し、特定の値を持っているかどうかを判断します。関数定義と関数バインディングのプレースホルダを残します。
// exercise4 demonstrates how to extend CEL with custom functions.
// Declare a `contains` member function on map types that returns a boolean
// indicating whether the map contains the key-value pair.
func exercise4() {
fmt.Println("=== Exercise 4: Customization ===\n")
// Determine whether an optional claim is set to the proper value. The
// custom map.contains(key, value) function is used as an alternative to:
// key in map && map[key] == value
env, _ := cel.NewEnv(
cel.Types(&rpcpb.AttributeContext_Request{}),
// Declare the request.
cel.Variable("request",
cel.ObjectType("google.rpc.context.AttributeContext.Request"),
),
// Add the custom function declaration and binding here with cel.Function()
)
ast := compile(env,
`request.auth.claims.contains('group', 'admin')`,
cel.BoolType)
// Construct the program plan and provide the 'contains' function impl.
// Output: false
program, _ := env.Program(ast)
emptyClaims := map[string]string{}
eval(
program,
request(auth("user:me@acme.co", emptyClaims), time.Now()),
)
fmt.Println()
}
コードを実行してエラーを理解する
コードを再実行すると、次のエラーが表示されます。
ERROR: <input>:1:29: found no matching overload for 'contains' applied to 'map(string, dyn).(string, string)'
| request.auth.claims.contains('group', 'admin')
| ............................^
このエラーを修正するには、現在リクエスト変数を宣言している宣言のリストに contains 関数を追加する必要があります。
次の 3 行を追加して、パラメータ化された型を宣言します。（これは、CEL の関数オーバーロードが複雑になるのと同じです）。
// exercise4 demonstrates how to extend CEL with custom functions.
// Declare a `contains` member function on map types that returns a boolean
// indicating whether the map contains the key-value pair.
func exercise4() {
fmt.Println("=== Exercise 4: Customization ===\n")
// Determine whether an optional claim is set to the proper value. The custom
// map.contains(key, value) function is used as an alternative to:
// key in map && map[key] == value
// Useful components of the type-signature for 'contains'.
typeParamA := cel.TypeParamType("A")
typeParamB := cel.TypeParamType("B")
mapAB := cel.MapType(typeParamA, typeParamB)
env, _ := cel.NewEnv(
cel.Types(&rpcpb.AttributeContext_Request{}),
// Declare the request.
cel.Variable("request",
cel.ObjectType("google.rpc.context.AttributeContext.Request"),
),
// Add the custom function declaration and binding here with cel.Function()
)
ast := compile(env,
`request.auth.claims.contains('group', 'admin')`,
cel.BoolType)
// Construct the program plan.
// Output: false
program, _ := env.Program(ast)
emptyClaims := map[string]string{}
eval(program, request(auth("user:me@acme.co", emptyClaims), time.Now()))
fmt.Println()
}
カスタム関数を追加する
次に、パラメータ化された型を使用する新しい contains 関数を追加します。
// exercise4 demonstrates how to extend CEL with custom functions.
// Declare a `contains` member function on map types that returns a boolean
// indicating whether the map contains the key-value pair.
func exercise4() {
fmt.Println("=== Exercise 4: Customization ===\n")
// Determine whether an optional claim is set to the proper value. The custom
// map.contains(key, value) function is used as an alternative to:
// key in map && map[key] == value
// Useful components of the type-signature for 'contains'.
typeParamA := cel.TypeParamType("A")
typeParamB := cel.TypeParamType("B")
mapAB := cel.MapType(typeParamA, typeParamB)
// Env declaration.
env, _ := cel.NewEnv(
cel.Types(&rpcpb.AttributeContext_Request{}),
// Declare the request.
cel.Variable("request",
cel.ObjectType("google.rpc.context.AttributeContext.Request"),
),
// Declare the custom contains function and its implementation.
cel.Function("contains",
cel.MemberOverload(
"map_contains_key_value",
[]*cel.Type{mapAB, typeParamA, typeParamB},
cel.BoolType,
// Provide the implementation using cel.FunctionBinding()
),
),
)
ast := compile(env,
`request.auth.claims.contains('group', 'admin')`,
cel.BoolType)
// Construct the program plan and provide the 'contains' function impl.
// Output: false
program, _ := env.Program(ast)
emptyClaims := map[string]string{}
eval(program, request(auth("user:me@acme.co", emptyClaims), time.Now()))
fmt.Println()
}
プログラムを実行してエラーを理解する
演習を実行します。ランタイム関数が見つからないという次のエラーが表示されます。
------ result ------
error: no such overload: contains
cel.FunctionBinding() 関数を使用して、NewEnv 宣言に関数の実装を指定します。
// exercise4 demonstrates how to extend CEL with custom functions.
//
// Declare a contains member function on map types that returns a boolean
// indicating whether the map contains the key-value pair.
func exercise4() {
fmt.Println("=== Exercise 4: Customization ===\n")
// Determine whether an optional claim is set to the proper value. The custom
// map.contains(key, value) function is used as an alternative to:
// key in map && map[key] == value
// Useful components of the type-signature for 'contains'.
typeParamA := cel.TypeParamType("A")
typeParamB := cel.TypeParamType("B")
mapAB := cel.MapType(typeParamA, typeParamB)
// Env declaration.
env, _ := cel.NewEnv(
cel.Types(&rpcpb.AttributeContext_Request{}),
// Declare the request.
cel.Variable("request",
cel.ObjectType("google.rpc.context.AttributeContext.Request"),
),
// Declare the custom contains function and its implementation.
cel.Function("contains",
cel.MemberOverload(
"map_contains_key_value",
[]*cel.Type{mapAB, typeParamA, typeParamB},
cel.BoolType,
cel.FunctionBinding(mapContainsKeyValue)),
),
)
ast := compile(env,
`request.auth.claims.contains('group', 'admin')`,
cel.BoolType)
// Construct the program plan.
// Output: false
program, err := env.Program(ast)
if err != nil {
glog.Exit(err)
}
eval(program, request(auth("user:me@acme.co", emptyClaims), time.Now()))
claims := map[string]string{"group": "admin"}
eval(program, request(auth("user:me@acme.co", claims), time.Now()))
fmt.Println()
}
プログラムが正常に実行されます。
=== Exercise 4: Custom Functions ===
request.auth.claims.contains('group', 'admin')
------ input ------
request = time: <
seconds: 1569302377
>
auth: <
principal: "user:me@acme.co"
claims: <
>
>
------ result ------
value: false (types.Bool)
申し立てが存在する場合
追加の課題として、入力に管理者クレームを設定して、クレームが存在する場合にも contains オーバーロードが true を返すことを確認してみてください。次の出力が表示されます。
=== Exercise 4: Customization ===
request.auth.claims.contains('group','admin')
------ input ------
request = time: <
seconds: 1588991010
>
auth: <
principal: "user:me@acme.co"
claims: <
>
>
------ result ------
value: false (types.Bool)
------ input ------
request = time: <
seconds: 1588991010
>
auth: <
principal: "user:me@acme.co"
claims: <
fields: <
key: "group"
value: <
string_value: "admin"
>
>
>
>
------ result ------
value: true (types.Bool)
次に進む前に、mapContainsKeyValue 関数自体を確認しておきましょう。
// mapContainsKeyValue implements the custom function:
// map.contains(key, value) -> bool.
func mapContainsKeyValue(args ...ref.Val) ref.Val {
// The declaration of the function ensures that only arguments which match
// the mapContainsKey signature will be provided to the function.
m := args[0].(traits.Mapper)
// CEL has many interfaces for dealing with different type abstractions.
// The traits.Mapper interface unifies field presence testing on proto
// messages and maps.
key := args[1]
v, found := m.Find(key)
// If not found and the value was non-nil, the value is an error per the
// `Find` contract. Propagate it accordingly. Such an error might occur with
// a map whose key-type is listed as 'dyn'.
if !found {
if v != nil {
return types.ValOrErr(v, "unsupported key type")
}
// Return CEL False if the key was not found.
return types.False
}
// Otherwise whether the value at the key equals the value provided.
return v.Equal(args[2])
}
拡張性を最大限に高めるため、カスタム関数のシグネチャでは ref.Val 型の引数が想定されています。このトレードオフは、拡張の容易さによって、すべての値の型が適切に処理されるように実装者が負担を負うことです。入力引数の型または数が関数宣言と一致しない場合は、no such overload エラーを返す必要があります。
cel.FunctionBinding() は、ランタイム コントラクトが環境内の型チェック済み宣言と一致するように、ランタイム型ガードを追加します。
9. JSON の作成
CEL は、JSON などのブール値以外の出力を生成することもできます。関数に次のコードを追加します。
// exercise5 covers how to build complex objects as CEL literals.
//
// Given the input now, construct a JWT with an expiry of 5 minutes.
func exercise5() {
fmt.Println("=== Exercise 5: Building JSON ===\n")
env, _ := cel.NewEnv(
// Declare the 'now' variable as a Timestamp.
// cel.Variable("now", cel.TimestampType),
)
// Note the quoted keys in the CEL map literal. For proto messages the
// field names are unquoted as they represent well-defined identifiers.
ast := compile(env, `
{'sub': 'serviceAccount:delegate@acme.co',
'aud': 'my-project',
'iss': 'auth.acme.com:12350',
'iat': now,
'nbf': now,
'exp': now + duration('300s'),
'extra_claims': {
'group': 'admin'
}}`,
cel.MapType(cel.StringType, cel.DynType))
program, _ := env.Program(ast)
out, _, _ := eval(
program,
map[string]interface{}{
"now": &tpb.Timestamp{Seconds: time.Now().Unix()},
},
)
fmt.Printf("------ type conversion ------\n%v\n", out)
fmt.Println()
}
コードの実行
コードを再実行すると、次のエラーが表示されます。
ERROR: <input>:5:11: undeclared reference to 'now' (in container '')
| 'iat': now,
| ..........^
... and more ...
cel.NewEnv() に cel.TimestampType 型の now 変数の宣言を追加して、再度実行します。
// exercise5 covers how to build complex objects as CEL literals.
//
// Given the input now, construct a JWT with an expiry of 5 minutes.
func exercise5() {
fmt.Println("=== Exercise 5: Building JSON ===\n")
env, _ := cel.NewEnv(
cel.Variable("now", cel.TimestampType),
)
// Note the quoted keys in the CEL map literal. For proto messages the
// field names are unquoted as they represent well-defined identifiers.
ast := compile(env, `
{'sub': 'serviceAccount:delegate@acme.co',
'aud': 'my-project',
'iss': 'auth.acme.com:12350',
'iat': now,
'nbf': now,
'exp': now + duration('300s'),
'extra_claims': {
'group': 'admin'
}}`,
cel.MapType(cel.StringType, cel.DynType))
// Hint:
// Convert `out` to JSON using the valueToJSON() helper method.
// The valueToJSON() function calls ConvertToNative(&structpb.Value{})
// to adapt the CEL value to a protobuf JSON representation and then
// uses the jsonpb.Marshaler utilities on the output to render the JSON
// string.
program, _ := env.Program(ast)
out, _, _ := eval(
program,
map[string]interface{}{
"now": time.Now(),
},
)
fmt.Printf("------ type conversion ------\n%v\n", out)
fmt.Println()
}
コードを再実行すると、成功します。
=== Exercise 5: Building JSON ===
{'aud': 'my-project',
'exp': now + duration('300s'),
'extra_claims': {
'group': 'admin'
},
'iat': now,
'iss': 'auth.acme.com:12350',
'nbf': now,
'sub': 'serviceAccount:delegate@acme.co'
}
------ input ------
now = seconds: 1569302377
------ result ------
value: &{0xc0002eaf00 map[aud:my-project exp:{0xc0000973c0} extra_claims:0xc000097400 iat:{0xc000097300} iss:auth.acme.com:12350 nbf:{0xc000097300} sub:serviceAccount:delegate@acme.co] {0x8c8f60 0xc00040a6c0 21}} (*types.baseMap)
------ type conversion ------
&{0xc000313510 map[aud:my-project exp:{0xc000442510} extra_claims:0xc0004acdc0 iat:{0xc000442450} iss:auth.acme.com:12350 nbf:{0xc000442450} sub:serviceAccount:delegate@acme.co] {0x9d0ce0 0xc0004424b0 21}}
プログラムは実行されますが、出力値 out を JSON に明示的に変換する必要があります。この場合の内部 CEL 表現は、JSON がサポートできる型、またはよく知られている Proto から JSON へのマッピングがある型のみを参照するため、JSON に変換可能です。
// exercise5 covers how to build complex objects as CEL literals.
//
// Given the input now, construct a JWT with an expiry of 5 minutes.
func exercise5() {
fmt.Println("=== Exercise 5: Building JSON ===\n")
...
fmt.Printf("------ type conversion ------\n%v\n", valueToJSON(out))
fmt.Println()
}
codelab.go ファイル内の valueToJSON ヘルパー関数を使用して型を変換すると、次の追加の出力が表示されます。
------ type conversion ------
{
"aud": "my-project",
"exp": "2019-10-13T05:54:29Z",
"extra_claims": {
"group": "admin"
},
"iat": "2019-10-13T05:49:29Z",
"iss": "auth.acme.com:12350",
"nbf": "2019-10-13T05:49:29Z",
"sub": "serviceAccount:delegate@acme.co"
}
10. ビルディング プロト
CEL は、アプリケーションにコンパイルされた任意のメッセージ タイプの protobuf メッセージをビルドできます。入力 jwt から google.rpc.context.AttributeContext.Request をビルドする関数を追加
// exercise6 describes how to build proto message types within CEL.
//
// Given an input jwt and time now construct a
// google.rpc.context.AttributeContext.Request with the time and auth
// fields populated according to the go/api-attributes specification.
func exercise6() {
fmt.Println("=== Exercise 6: Building Protos ===\n")
// Construct an environment and indicate that the container for all references
// within the expression is `google.rpc.context.AttributeContext`.
requestType := &rpcpb.AttributeContext_Request{}
env, _ := cel.NewEnv(
// Add cel.Container() option for 'google.rpc.context.AttributeContext'
cel.Types(requestType),
// Add cel.Variable() option for 'jwt' as a map(string, Dyn) type
// and for 'now' as a timestamp.
)
// Compile the Request message construction expression and validate that
// the resulting expression type matches the fully qualified message name.
//
// Note: the field names within the proto message types are not quoted as they
// are well-defined names composed of valid identifier characters. Also, note
// that when building nested proto objects, the message name needs to prefix
// the object construction.
ast := compile(env, `
Request{
auth: Auth{
principal: jwt.iss + '/' + jwt.sub,
audiences: [jwt.aud],
presenter: 'azp' in jwt ? jwt.azp : "",
claims: jwt
},
time: now
}`,
cel.ObjectType("google.rpc.context.AttributeContext.Request"),
)
program, _ := env.Program(ast)
// Construct the message. The result is a ref.Val that returns a dynamic
// proto message.
out, _, _ := eval(
program,
map[string]interface{}{
"jwt": map[string]interface{}{
"sub": "serviceAccount:delegate@acme.co",
"aud": "my-project",
"iss": "auth.acme.com:12350",
"extra_claims": map[string]string{
"group": "admin",
},
},
"now": time.Now(),
},
)
// Hint: Unwrap the CEL value to a proto. Make sure to use the
// `ConvertToNative(reflect.TypeOf(requestType))` to convert the dynamic proto
// message to the concrete proto message type expected.
fmt.Printf("------ type unwrap ------\n%v\n", out)
fmt.Println()
}
コードの実行
コードを再実行すると、次のエラーが表示されます。
ERROR: <input>:2:10: undeclared reference to 'Request' (in container '')
| Request{
| .........^
コンテナは基本的に名前空間やパッケージと同等ですが、protobuf メッセージ名と同じくらい細かくすることもできます。CEL コンテナは、特定の変数、関数、型名が宣言されている場所を特定するために、Protobuf と C++ と同じ名前空間解決ルールを使用します。
コンテナ google.rpc.context.AttributeContext が指定されている場合、型チェッカーと評価ツールは、すべての変数、型、関数に対して次の識別子名を試します。
google.rpc.context.AttributeContext.<id>google.rpc.context.<id>google.rpc.<id>google.<id><id>
絶対名の場合は、変数、型、関数参照の前にドットを付けます。この例では、式 .<id> は、コンテナ内を最初にチェックせずに、最上位の <id> 識別子のみを検索します。
CEL 環境に cel.Container("google.rpc.context.AttributeContext") オプションを指定して、もう一度実行してみてください。
// exercise6 describes how to build proto message types within CEL.
//
// Given an input jwt and time now construct a
// google.rpc.context.AttributeContext.Request with the time and auth
// fields populated according to the go/api-attributes specification.
func exercise6() {
fmt.Println("=== Exercise 6: Building Protos ===\n")
// Construct an environment and indicate that the container for all references
// within the expression is `google.rpc.context.AttributeContext`.
requestType := &rpcpb.AttributeContext_Request{}
env, _ := cel.NewEnv(
// Add cel.Container() option for 'google.rpc.context.AttributeContext'
cel.Container("google.rpc.context.AttributeContext.Request"),
cel.Types(requestType),
// Later, add cel.Variable() options for 'jwt' as a map(string, Dyn) type
// and for 'now' as a timestamp.
// cel.Variable("now", cel.TimestampType),
// cel.Variable("jwt", cel.MapType(cel.StringType, cel.DynType)),
)
...
}
出力は次のようになります。
ERROR: <input>:4:16: undeclared reference to 'jwt' (in container 'google.rpc.context.AttributeContext')
| principal: jwt.iss + '/' + jwt.sub,
| ...............^
... その他多数のエラー...
次に、jwt 変数と now 変数を宣言します。プログラムは想定どおりに実行されます。
=== Exercise 6: Building Protos ===
Request{
auth: Auth{
principal: jwt.iss + '/' + jwt.sub,
audiences: [jwt.aud],
presenter: 'azp' in jwt ? jwt.azp : "",
claims: jwt
},
time: now
}
------ input ------
jwt = {
"aud": "my-project",
"extra_claims": {
"group": "admin"
},
"iss": "auth.acme.com:12350",
"sub": "serviceAccount:delegate@acme.co"
}
now = seconds: 1588993027
------ result ------
value: &{0xc000485270 0xc000274180 {0xa6ee80 0xc000274180 22} 0xc0004be140 0xc0002bf700 false} (*types.protoObj)
----- type unwrap ----
&{0xc000485270 0xc000274180 {0xa6ee80 0xc000274180 22} 0xc0004be140 0xc0002bf700 false}
追加演習として、メッセージで out.Value() を呼び出して型をアンラップし、結果がどのように変化するかを確認してください。
11. マクロ
マクロは、解析時に CEL プログラムを操作するために使用できます。マクロは呼び出しシグネチャを照合し、入力呼び出しとその引数を操作して、新しいサブ式 AST を生成します。
マクロを使用すると、CEL で直接記述できない複雑なロジックを AST に実装できます。たとえば、has マクロを使用すると、フィールドの存在テストが可能になります。exists や all などの内包表記マクロは、関数呼び出しを入力リストまたはマップに対する境界付きの反復処理に置き換えます。どちらのコンセプトも構文レベルでは実現できませんが、マクロ展開によって実現できます。
次の演習を追加して実行します。
// exercise7 introduces macros for dealing with repeated fields and maps.
//
// Determine whether the jwt.extra_claims has at least one key that starts
// with the group prefix, and ensure that all group-like keys have list
// values containing only strings that end with '@acme.co`.
func exercise7() {
fmt.Println("=== Exercise 7: Macros ===\n")
env, _ := cel.NewEnv(
cel.ClearMacros(),
cel.Variable("jwt", cel.MapType(cel.StringType, cel.DynType)),
)
ast := compile(env,
`jwt.extra_claims.exists(c, c.startsWith('group'))
&& jwt.extra_claims
.filter(c, c.startsWith('group'))
.all(c, jwt.extra_claims[c]
.all(g, g.endsWith('@acme.co')))`,
cel.BoolType)
program, _ := env.Program(ast)
// Evaluate a complex-ish JWT with two groups that satisfy the criteria.
// Output: true.
eval(program,
map[string]interface{}{
"jwt": map[string]interface{}{
"sub": "serviceAccount:delegate@acme.co",
"aud": "my-project",
"iss": "auth.acme.com:12350",
"extra_claims": map[string][]string{
"group1": {"admin@acme.co", "analyst@acme.co"},
"labels": {"metadata", "prod", "pii"},
"groupN": {"forever@acme.co"},
},
},
})
fmt.Println()
}
次のエラーが表示されます。
ERROR: <input>:1:25: undeclared reference to 'c' (in container '')
| jwt.extra_claims.exists(c, c.startsWith('group'))
| ........................^
... その他多数 ...
これらのエラーは、マクロがまだ有効になっていないために発生します。マクロを有効にするには、cel.ClearMacros() を削除して、もう一度実行します。
=== Exercise 7: Macros ===
jwt.extra_claims.exists(c, c.startsWith('group'))
&& jwt.extra_claims
.filter(c, c.startsWith('group'))
.all(c, jwt.extra_claims[c]
.all(g, g.endsWith('@acme.co')))
------ input ------
jwt = {
"aud": "my-project",
"extra_claims": {
"group1": [
"admin@acme.co",
"analyst@acme.co"
],
"groupN": [
"forever@acme.co"
],
"labels": [
"metadata",
"prod",
"pii"
]
},
"iss": "auth.acme.com:12350",
"sub": "serviceAccount:delegate@acme.co"
}
------ result ------
value: true (types.Bool)
現在サポートされているマクロは次のとおりです。
マクロ | 署名 | 説明 |
すべて | r.all(var, cond) | 範囲 r 内のすべての var に対して cond が true と評価されるかどうかをテストします。 |
存在しています | r.exists(var, cond) | 範囲 r 内の任意の var に対して cond が true と評価されるかどうかをテストします。 |
exists_one | r.exists_one(var, cond) | 範囲 r 内の1 つの var に対して cond が true と評価されるかどうかをテストします。 |
filter | r.filter(var, cond) | リストの場合、範囲 r 内の各要素 var が条件 cond を満たす新しいリストを作成します。マップの場合、範囲 r 内の各キー変数で条件 cond が満たされる新しいリストを作成します。 |
地図 | r.map(var, expr) | 範囲 r の各 var が expr によって変換される新しいリストを作成します。 |
r.map(var, cond, expr) | 2 つの引数を持つ map と同じですが、値が変換される前に条件付きの cond フィルタがあります。 | |
has | has(a.b) | 値 a に b が存在するかどうかのテスト : マップの場合、JSON テスト定義。proto の場合、デフォルト以外のプリミティブ値または設定されたメッセージ フィールドをテストします。 |
範囲 r 引数が map 型の場合、var はマップキーになります。list 型の値の場合、var はリスト要素の値になります。all、exists、exists_one、filter、map の各マクロは、入力のサイズで制限された for-each イテレーションを実行する AST 書き換えを行います。
境界付き内包表記により、CEL プログラムはチューリング完全ではなくなりますが、入力に関して超線形時間で評価されます。これらのマクロは、なるべく使用しないか、まったく使用しないでください。内包表記を多用している場合は、カスタム関数を使用することでユーザー エクスペリエンスとパフォーマンスが向上する可能性が高いことを示しています。
12. チューニング
現時点では CEL-Go 固有の機能がいくつかありますが、これらは他の CEL 実装の将来の計画を示しています。次の演習では、同じ AST のさまざまなプログラム プランを紹介します。
// exercise8 covers features of CEL-Go which can be used to improve
// performance and debug evaluation behavior.
//
// Turn on the optimization, exhaustive eval, and state tracking
// ProgramOption flags to see the impact on evaluation behavior.
func exercise8() {
fmt.Println("=== Exercise 8: Tuning ===\n")
// Declare the x and 'y' variables as input into the expression.
env, _ := cel.NewEnv(
cel.Variable("x", cel.IntType),
cel.Variable("y", cel.UintType),
)
ast := compile(env,
`x in [1, 2, 3, 4, 5] && type(y) == uint`,
cel.BoolType)
// Try the different cel.EvalOptions flags when evaluating this AST for
// the following use cases:
// - cel.OptOptimize: optimize the expression performance.
// - cel.OptExhaustiveEval: turn off short-circuiting.
// - cel.OptTrackState: track state and compute a residual using the
// interpreter.PruneAst function.
program, _ := env.Program(ast)
eval(program, cel.NoVars())
fmt.Println()
}
オプティマイズ
最適化フラグがオンの場合、CEL はリストとマップのリテラルを事前に構築し、in 演算子などの特定の呼び出しを真のセット メンバーシップ テストに最適化するために、余分な時間を費やします。
// Turn on optimization.
trueVars := map[string]interface{}{"x": int64(4), "y": uint64(2)}
program, _ := env.Program(ast, cel.EvalOptions(cel.OptOptimize))
// Try benchmarking with the optimization flag on and off.
eval(program, trueVars)
同じプログラムが異なる入力に対して何度も評価される場合は、最適化が適しています。ただし、プログラムが 1 回だけ評価される場合は、最適化によってオーバーヘッドが増加するだけです。
徹底的な評価
Exhaustive Eval は、式評価の各ステップで観測された値に関する分析情報を提供するため、式評価の動作をデバッグするのに役立ちます。
// Turn on exhaustive eval to see what the evaluation state looks like.
// The input is structure to show a false on the first branch, and true
// on the second.
falseVars := map[string]interface{}{"x": int64(6), "y": uint64(2)}
program, _ = env.Program(ast, cel.EvalOptions(cel.OptExhaustiveEval))
eval(program, falseVars)
各式 ID の式評価状態のリストが表示されます。
------ eval states ------
1: 6 (types.Int)
2: false (types.Bool)
3: &{0xc0000336b0 [1 2 3 4 5] {0x89f020 0xc000434760 151}} (*types.baseList)
4: 1 (types.Int)
5: 2 (types.Int)
6: 3 (types.Int)
7: 4 (types.Int)
8: 5 (types.Int)
9: uint (*types.Type)
10: 2 (types.Uint)
11: true (types.Bool)
12: uint (*types.Type)
13: false (types.Bool)
式 ID 2 は最初のブランチの in 演算子の結果に対応し、式 ID 11 は 2 番目のブランチの == 演算子に対応します。通常の評価では、2 が計算された後、式は短絡されます。y が uint でなかった場合、状態には式が失敗する理由が 1 つではなく 2 つ表示されます。
13. 学習した内容
式エンジンが必要な場合は、CEL の使用を検討してください。CEL は、パフォーマンスが重要なユーザー構成を実行する必要があるプロジェクトに最適です。
前の演習では、データを CEL に渡し、出力または決定を取得することに慣れていただけたかと思います。
ブール値の決定から JSON メッセージや Protobuffer メッセージの生成まで、どのようなオペレーションを実行できるかをご理解いただけたかと思います。
式を操作する方法と、式が何を行っているかについてご理解いただけたでしょうか。また、拡張する一般的な方法も理解しています。