Parsing HCL/CUE / Fukuoka.go #21

https://fukuokago.connpass.com/event/344467/

Transcript

1. Parsing HCL/CUE ⼩⼭健⼀郎 ( @k1LoW ) / Tailor Inc. 2025.3.11 Fukuoka.go #21
2. 2 What is HCL/CUE
3. • HCL is a toolkit for creating structured configuration languages that are both human- and machine-friendly, for use with command-line tools. • Terraformの記述⾔語として有名 • HCL attempts to strike a compromise between generic serialization formats such as JSON and configuration formats built around full programming languages such as Ruby. ◦ HCLは、JSONのような汎⽤的なシリアライゼーション‧フォーマットと、Rubyのような完全なプロ グラミング⾔語で構築されたコンフィギュレーション‧フォーマットとの妥協点を⾒出そうとしてい る。 • HashiCorp Configuration Language ref: https://github.com/hashicorp/hcl HCL What is HCL/CUE 3
4. • CUE is an open-source data validation language and inference engine with its roots in logic programming. • Types are values ◦ データ、スキーマ、検証、ポリシー制約を指定するための単⼀⾔語 ▪ （設定などの）構造データと、そのデータの構造を同時に定義することができる • Configure（設定）、Unify（統⼀）、Execute（実⾏） ref: https://cuelang.org/ CUE What is HCL/CUE 4
5. 5 解決したかった課題
6. 6 前提
7. • Tailor Platform is a backend platform that enables enterprises to create tailor-made business tools that perfectly match their unique requirements, amazingly fast. ◦ ローコードでヘッドレスな業務アプリケーションバックエンドを構築できるプラットフォーム • Tailor DB / Auth / Pipeline / StateFlow / Executor / Function などのサービスとそれぞれでトリガーされる Events を使⽤してスケーラブルなインフ ラも含めたアプリケーションを構築できる • 構成の全てをTerraform、もしくはCUEで の管理が可能 ref: https://docs.tailor.tech Tailor Platform 7
8. 1. HCL/CUEファイルシンタックス内の⽂字列それぞれにフォーマッタを適⽤したい 2. Tailor DBのデータベーススキーマドキュメントを⽣成したい 解決したかった課題 8
9. • Tailor PlatformではロジックとしてJavaScriptやCELが記述でき、GraphQLで⼀連の操作を繋げた Query/Mutation（やそれに必要なDSL）を新たに定義することができる。 • terraform fmt や cue fmt はHCL/CUEシンタックスの範囲においては整形してくれるが、ヒアドキュメ ントの中の⽂字列は対象外。 • JavaScriptやGraphQLを外部ファイルにすることは可能だが、ヒアドキュメントで書く選択肢も持ちた い。 • HCL/CUEファイルシンタックス内のヒアドキュメントに対して、任意のフォーマッタ（例えばprettier）を 適⽤したい。 1. HCL/CUEファイルシンタックス内の⽂字列それぞれに フォーマッタを適⽤したい 解決したかった課題 9
10. 1. HCL/CUEファイルシンタックス内の⽂字列それぞれに フォーマッタを適⽤したい 解決したかった課題 10
11. • Tailor PlatformのWebコンソールではTailor DBのスキーマだけでなくPermissionやHookも確認できる。 • しかし、テーブル（Typeと呼ぶ）間のリレーションを把握したり、テーブルをグルーピングしたドキュメ ント（Viewpoint）を書くことは現時点では難しい。 • つまりtblsの導⼊をしたい。 2. Tailor DBのデータベーススキーマドキュメントを⽣成し たい 解決したかった課題 11
12. 12 実装 / Implementation
13. • hclstr is a utility tool for string literals in HCL files. ◦ https://github.com/k1LoW/hclstr • cuestr is a utility tool for string literals in CUE files. ◦ https://github.com/k1LoW/cuestr • HCL/CUE内の⽂字列に対して任意のフォーマッタを適⽤しつつHCL/CUEのフォーマットも実施するCLI ツール 1. hclstr / cuestr Implementation 13
14. • tbls driver for TailorDB schema definition ◦ https://github.com/k1LoW/tbls-driver-tailordb • Terraform/CUEで定義されたTailor Platformアプリケーション内のTailor DBの定義を元にスキーマ情報を 作成しtblsに渡すExternal database driver。 ◦ External database driver is ... ▪ tbls-driver-foodb という実⾏バイナリをPATHに置いてくとtblsが foodb:// スキームを 受け取った時に tbls-driver-foodb にDSNを渡す。 ▪ External database driver は受け取ったDSNから標準出⼒経由で schema.json を返す。 ▪ schema.jsonを元にtblsは例えば doc コマンドでドキュメント⽣成をする。 2. tbls-driver-tailordb Implementation 14
15. 15 課題ごとのパースパッケージへの要求
16. 16 1. HCL/CUEファイルシンタックス内の⽂字列それぞれにフォーマッタを適⽤したい 課題ごとのパースパッケージへの要求(1/2) • 「⽂字列それぞれ」 ◦ 構造は意識する必要がない。しかしどのフィールドの⽂字列なのかは知りたい。 • 「フォーマッタを適⽤したい」 ◦ パースした結果を修正し、再度HCL/CUEファイルとして書き出したい。 • 「⽂字列それぞれにフォーマッタを適⽤したい」 ◦ 変数展開や式評価の必要はないがフォーマッタが理解できるように整形する必要がある。
17. 17 2. Tailor DBのデータベーススキーマドキュメントを⽣成したい 課題ごとのパースパッケージへの要求(2/2) • 「Tailor DBの定義を元に」 ◦ 構造化された意味のある情報として取得したい。 • 「スキーマ情報を作成」 ◦ HCL/CUEファイルを操作するわけではない。Read Only。 • 「スキーマ情報を作成」 ◦ ワークスペース内の情報で変数展開や式評価はできる限りする必要がある。
18. 18 実装時のパースパッケージ利⽤
19. 19 1. HCL/CUEファイルシンタックス内の⽂字列それぞれにフォーマッタを適⽤したい 実装時のパースパッケージ利⽤(1/2) 1. ASTを filepath.WalkDir のように⾛査する関数や、Visitorパターンを実装しているパッケージや関数を 探す。⾛査途中で書き換えが可能なものが望ましい。 2. 上記が難しければ他の⽅法を探す • HCL: HCLを書き換えるパッケージとして github.com/hashicorp/hcl/v2/hclwrite があるのでこれを中⼼に 実装 ◦ 再帰的に⾛査しながら書き換える関数を⾃作 ◦ github.com/hashicorp/hcl/v2/hclsyntax.Walk や github.com/hashicorp/hcl/v2/hclsyntax.VisitAll は今回は使⽤せず（hclwriteの検証をしていたらそのまま実装できた） • CUE: cuelang.org/go/cue/ast func Walk(node Node, before func(Node) bool, after func(Node)) で⾛査しながら書き換える ◦ https://github.com/k1LoW/cuestr/blob/6d81945edf2dee6d73b4307b4adc77eb8fdd0619/fmt/fm t.go#L48-L128
20. 20 2. Tailor DBのデータベーススキーマドキュメントを⽣成したい 実装時のパースパッケージ利⽤(2/2) 1. json.Unmarshal のような、構造体に変換してくれる関数を探す • HCL: hcl.Body.PartialContent(schema *hcl.BodySchema) (*hcl.BodyContent, hcl.Body, hcl.Diagnostics) で想定しているデータ構造( schema )と値を取得する ◦ https://github.com/k1LoW/tbls-driver-tailordb/blob/5d53f12cd944813ae3036a19650c68daacb6 150a/tailordb/tf/tf.go#L136-L271 • CUE: func (v cue.Value) Decode(x interface{}) error や func (v cue.Value) LookupPath(p cue.Path) cue.Value を駆使して想定しているデータ構造( x )と値を取得する ◦ https://github.com/k1LoW/tbls-driver-tailordb/blob/main/tailordb/cue/cue.go#L122-L236
21. 21 まとめ
22. • 実現したい機能において同じパースパッケージでも使い⽅が異なる • 今回は2つのユースケースに沿ってパースパッケージの使⽤⽅法を紹介した ◦ コードはOSSになっています • 別の視点からみると、今回のようなユースケースは想定の範囲内だからこそあらかじめ関数やパッケージ が⽤意されている ◦ 公式のパースパッケージは素晴らしい まとめ 22
23. 23 Appendix
24. • 正直置換しか思いつかなかった ◦ https://github.com/k1LoW/cuestr/blob/6d81945edf2dee6d73b4307b4adc77eb8fdd0619/fmt/fm t.go#L87-L90 • それでも変数（Interpolation ）はなんとか対応できたが、ifやforが含まれる場合（Directives）は対応で きていない ◦ ref: https://developer.hashicorp.com/terraform/language/expressions/strings • 何かアイデアがあれば是⾮ HCL/CUEの変数や式が埋め込まれているヒアドキュメント のフォーマット Appendix 24