コンパイルのたびに出力が変わる！？protocプラグインをめぐるトラブルシュートとHyrum'Lawの教訓

Go Conference mini 2026 in Sendai
https://sendaigo.jp/

Transcript

1. コンパイルのたびに出力が変わる!? ～protocプラグインをめぐるトラブルシュートと Hyrum’s Lawの教訓～ Go Conference mini Sendai 2026/02/21
2. 自己紹介 Name • Fujikane Yoshiki (ふじを) Company • CyberAgent, Inc. • AmebaLIFE事業部 Platform Engineer Love • Go ʕ◔ϖ◔ʔ / ビール🍺 @ffjlabo
3. protocプラグインの不具合奮闘記🔥 本日のお話
4. ʕ◔ϖ◔ʔ> Let’s≡Go
5. 開発対象
6. 開発対象 • PipeCD: One CD for Allを掲げるGitOpsライクなCDツール • Web UI上から操作することができる ◦ いわゆるWeb UIとAPI Serverが存在するWeb Applicationな側面がある
7. • 「ユーザのRoleに基づいて対象リソースへのAPIの実行を制限」 RBAC機能 rpc GetDeployment Role: Viewer ❌ ✅ ✅ resource: Deployment resources=application,deployment,piped; actions=get,list rpc ListDeployment rpc CreateDeployment
8. RBAC機能の内部実装 • gRPCサーバのinterceptorで、 「あるRoleで特定リソースを操作するAPIを実行できるか」 をチェック • チェックロジックは protoc-gen-authという自作protocプラグイ ンを用いて自動生成
9. protoc-gen-auth protoc -I . --auth_out=. --auth_opt=paths=source_relative resources=API_KEY に対し、actions=CREATEができるロールのみ API実行可能
10. 発生した問題
11. protoc-gen-authの出力が 不定期で変化する 問題
12. 前提: protoc-gen-authはコンテナ経由で実行 • 自動生成系実行のために、 codegen というコンテナイメージを自作 • 過去の経緯でamd64向けのコンテナをビルドし利用している • protoc-gen-authは内部でビルドし利用している
13. 始まりは突然に
14. バグ、襲来 codegenのアップグレード作業をしていた時のこと… • CI上で自動生成コードの生成漏れチェックが失敗するように ◦ codegenを実行し、差分をチェック • protoc-gen-authの生成結果に差分が発生 HEAD detached at pull/4970/merge Changes not staged for commit: (use "git add <file>..." to update what will be committed) (use "git restore <file>..." to discard changes in working directory) modified: pkg/app/server/service/webservice/service.pb.auth.go
15. バグ、襲来 • 自動生成されるAuthorizeメソッドの一部が欠損
16. バグ、襲来 直近実施したこと • Go versionのアップグレード（1.20.4 -> 1.22.4） • 依存モジュールのprotobufアップグレード (1.28.1 -> 1.33.0) • コンテナのbase imageをAlpineからDebianへ変更 けれども… • コードは特に変更していない • 上記実施した際に、ローカル環境(M1 Mac上)で動作確認済み
17. バグ、襲来 ローカル環境（M1 Mac上）で事象が再現するか確認 • ❌ `go build` (darwin/arm64) • ❌ `docker build` (linux/arm64)
18. バグ、襲来 ローカル環境（M1 Mac上）で事象が再現するか確認 • ❌ `go build` (darwin/arm64) • ❌ `docker build` (linux/arm64) • ✅ `docker build --platform linux/amd64` (linux/amd64)
19. バグ、襲来 ローカル環境で事象が再現するか確認 • ❌ `go build` (darwin/arm64) • ❌ `docker build` (linux/arm64) • ✅ `docker build --platform linux/amd64` (linux/amd64) amd64向けのバイナリでのみ再現
20. バグ、襲来 特定の部分に改行を入れると、問題が解消 😇 https://github.com/pipe-cd/pipecd/pull/4972
21. 時は流れ…
22. バグ、再び • 数ヶ月後、問題が再発
23. バグ、再び 直近実施したこと • Go versionのアップグレード（1.22.4 -> 1.23） • golang/mock -> uber-go/mockへの移行 • またしてもコードは特に変更していない
24. バグ、再び 複数のアーキテクチャ向けのバイナリで再現 • ✅ `go build` (darwin/arm64) • ✅ `docker build` (linux/arm64) • ✅ `docker build --platform linux/amd64` (linux/amd64)
25. 問題まとめ • コードベースの修正はしていないが、protoc-gen-authの出力結果が 突然変化した • 再現条件に法則性が見えない ◦ CPUアーキテクチャによって再現したりしなかったり ◦ コードに改行を入れると解消さる
26. 調査
27. デバッガによる調査 • 不具合はローカル環境で再現している • 実際に動かしつつ、どの部分が問題か手掛かりを探す 方針 • デバッガとしてdelveを利用 • protoc-gen-debugの出力結果を使って、protocコマンドを使わず protoc-gen-authを単体実行
28. delve • GDBライクなデバッガ • Go 独自の仕様（ランタイム、 同時実行モデル、変数など）に 合わせて調整されている • 様々なエディタでGoのデバッガ を使っている場合は裏で利用し ている…はず！ https://github.com/go-delve/delve
29. protoc-gen-debug • 「protocプラグインがprotocから受け取る情報」をファイルに出力し てくれるprotocプラグイン https://github.com/lyft/protoc-gen-star/tree/master/protoc-g en-debug • protocプラグイン = 「protoファイルの解析結果」を標準入力から 受け取り、何らかの処理を行う protoc protocプラグイン CodeGeneratorRequest via stdin CodeGeneratorRespose via stdout .proto
30. protoc-gen-debug • 出力ファイルを使うことで、protocプラグイン単体で動かすことが できる # before protoc \ -I . \ --auth_out=. \ --auth_opt=paths=source_relative \ # after ./protoc-gen-auth < ./code_generator_request.pb.bin
31. 事前準備 • devleのインストール • go build -gcflags="all=-N -l" でデバッグ情報を含めるようビルド • protoc -I . –debug_out=”${dir}:${dir}” でprotocプラグインへの インプットを作成
32. デバッガ起動、ヨシ！ dlv exec -r stdin:./code_generator_request.pb.bin ./protoc-gen-auth debugserver-@(#)PROGRAM:LLDB PROJECT:lldb-1700.0.9.502 for arm64. Got a connection, launched process Type 'help' for list of commands. (dlv)
33. 準備完了！Let’s Debug
34. protoc-gen-authのコードベース ① Methodデータを作成 ② ファイルレンダリング
35. ① Methodデータを作成 rpcの定義を解析してMethod構造体を作成
36. ② ファイルレンダリング Methodデータを元に、各種rpcに対応する認可処理をレンダリング
37. デバッグ箇所を絞り込み • バグの状況を見るに、メソッドデータが欠落したように見える • そのため、「① Methodデータを作成」の処理付近を確認する
38. methodデータ作成直前のrpc数 🤔 少なくとも50個以上 (dlv) b 69 Breakpoint 5 set at 0x100d71d34 for main.main.func1() /tmp/pipecd/tool/codegen/protoc-gen-auth/main.go:69 (dlv) c … } (dlv) p svc.Methods Sending output to pager... []*google.golang.org/protobuf/compiler/protogen.Method len: 50, cap: 64, [ *{ … GoName: "RegisterPiped", … *{ … GoName: "UpdatePiped", …
39. レンダリング時のmethodデータ 🤔 複数あるrpcのうち1つのみ 格納されている (dlv) b 86 Breakpoint 3 set at 0x10292e280 for main.main.func1() /tmp/pipecd/tool/codegen/protoc-gen-auth/main.go:86 (dlv) c … (dlv) p methods []*main.Method len: 1, cap: 50, [ *{ Name: "GetCommand", Resource: "", Action: "", Ignored: true,}, ]
40. 挙動まとめ • Input: 50個以上のrpc、output: methodデータ1つのみ • methodデータの作成処理（generateMethods）で何かが起きている 可能性大
41. generateMethodsの挙動分析 rpcのカスタムオプションを分解して、 Method構造体を作成
42. generateMethodsの挙動分析 “resource:PIPED action:CREATE” ↓ [“resource:PIPED”, “action:CREATE”] ↓ &Method{ Name: m.GoName, Resource: ”PIPED”, Action:”CREATE” }
43. デバッグによる詳細な挙動分析 (dlv) b 128 Breakpoint 7 set at 0x100d71260 for main.generateMethods.func1() /tmp/pipecd/tool/codegen/protoc-gen-auth/main.go:128 (dlv) c > [Breakpoint 7] main.generateMethods.func1() /tmp/pipecd/tool/codegen/protoc-gen-auth/main.go:128 (hits total:1) (PC: 0x100d71260) … (dlv) p vs []string len: 1, cap: 1, [ "resource:PIPED action:CREATE", ] 🤔 文字列がSplitされていない！？
44. よく見てみると… スペースが1つ足りない！？！？
45. ここまでのまとめ • 「rpcの定義情報から生成されるmethodデータ欠損」が不具合を誘発 • v.String()の出力結果からスペースが1つ分消えたことが原因 • 仮説: protobufモジュールのアップデートで挙動に変更が入った？
46. Deep Dive into protobuf
47. v.String()の実体 v.String() => protoreflect.Value.String()
48. protoreflect.Value • リフレクションを通じて、値を動的に読み取る標準フォーマット • protobufメッセージの「型」と「データ」を保持
49. protoreflect.Value interface{}のデータ構造に類似 • リフレクションを通じて、値を動的に読み取る 標準フォーマット • protobufメッセージの「型」と「データ」を保持
50. protoreflect.Value.String() • unsafeポインタの指す型情報に応じて出力処理を実行 • 型がstring以外の時、fmt.Sprint経由で型に紐づくString()を実行
51. protoreflect.Value.String() dynamicpb.Message.String()を実行 (dlv) s … 275: // Sprint formats using the default formats for its operands and returns the resulting string. 276: // Spaces are added between operands when neither is a string. => 277: func Sprint(a ...any) string { 278: p := newPrinter() 279: p.doPrint(a) 280: s := string(p.buf) 281: p.free() 282: return s (dlv) p a []interface {} len: 1, cap: 1, [ *google.golang.org/protobuf/types/dynamicpb.Message { … }, ]
52. dynamicpb.Message.String() • 最終的に prototext.MarshalOptions.Format() を実行し、 メッセージを文字列として出力
53. ここまでのまとめ v.String()の実体を確認すると… ↓ protoreflect.Value.String() ↓ dynamicpb.Message.String() ↓ prototext.MarshalOptions.Format()
54. prototext.MarshalOptions.Format() • Formatはメッセージをstringとして整形して出力
55. prototext.MarshalOptions.marshal() • encoderのmarshalMessageにてメッセージをstring化
56. エンコーダによる文字列書き込み e.g. フィールド名を文字列として書き込む処理 すでにe.outに ”resource:PIPED” がある状態で、文字列 “actions” が渡っ てきたとして… • prepareNextによって何らかの事前準備がされる • e.outに “actions:” を追記する
57. prepareNext • 事前準備として、すでに存在する出力の末尾に空白を追加 • e.out が “resources:PIPED” だったとすると、 末尾に空白が追加され ”resources:PIPED ” となる
58. prepareNext 追加でもう1つ空白を用意する可能性がある！！！！！！！！
59. （再掲） スペースが1つ足りない！？！？
60. prepareNext 何らかの理由でdetrand.Bool()の結果が変わった？？
61. detrand.Bool() randomなシードを2で割った余りが1か
62. binaryHash() 実行バイナリを自身で読み込む
63. binaryHash() 実行バイナリを8つの位置からそれぞれ64バイト分ずつ データを取得し、ハッシュを計算
64. detrand.Bool()の結果は 実行バイナリデータ次第で変わる！
65. v.String()の結果は 実行バイナリデータ次第で変わる！
66. protobufのMessage出力は 実行バイナリデータ次第で変わる！
67. 実行バイナリデータ次第で変わる コードのロジック変更がなくても、ビルド後のバイナリが変化すれば 実行結果も変化する！！！ • 依存モジュールの更新 • CPUアーキテクチャ変更 • ロジックに直接関係ない部分で処理を修正 などなど
68. 一見するとバグに見えるが… なぜこんなことを…
69. upstreamでのディスカッション encoding: provide canonical output format https://github.com/golang/protobuf/issues/1121 投稿主 テストなどに影響でるので せめて機能をオフにできるように してくれないか？ メンテナ 今回は対応しません。 むしろ不安定な出力に依存する実 装をしない方がいいです。
70. Hyrumの法則 簡潔に言えば、観察結果は次のとおりです。 API のユーザーが十分な数いれば、契約で何を約束するかは関係ありません。 システムのすべての観測可能な動作は、誰かが依存することになります。 https://www.hyrumslaw.com/
71. 仕様に関わらず実際の動作に依存してしまう
72. 仕様ではなく実際の動作に依存する 具体例 • mapのキー順序がソートされるものだと見越して 実装する • Errorの文言が固定されていると考えて直接参照して 分岐させるよう実装する
73. 開発の安定性を損ねてしまう 利用者 • 実装が簡単に壊れる ◦ 動作が修正されると、その動作に依存していた実装が軒並み壊れる ◦ e.g. 特定のエラーメッセージの存在有無によるハンドリング など 開発者 • 将来的な保守運用コストが増加する ◦ 意図しない利用が増え、修正による影響範囲が増大 → 機能拡張などの障壁化
74. 非決定性 || プロダクトの開発を持続させるための 意図的な防御策
75. 最終的な対応 非決定的なString()に依存せず、別な手段で実装することで解決
76. 恒久対応完了！！
77. まとめ • protocプラグインの不具合の根本原因は、 実装がprotobufの「出力の揺らぎ（非決定性）」に依存していたこと • 「出力の揺らぎ」は不具合ではなく、 Hyrumの法則の影響を回避するための意図的な防御策 • 仕様として保証しない動作に依存することに起因する負荷から 利用者、開発者それぞれを守る手段
78. ありがとうございましたʕ◔ϖ◔ʔ
79. 参考文献 • https://github.com/golang/protobuf/issues/1121 • https://protobuf.dev/reference/go/faq/#hyrums-law • https://www.hyrumslaw.com/ • http://pipecd.dev/ • https://github.com/pipe-cd/pipecd/pull/4919 • https://github.com/pipe-cd/pipecd/pull/4972 • https://github.com/pipe-cd/pipecd/pull/5436 • https://github.com/lyft/protoc-gen-star/tree/master/protoc-g en-debug • https://github.com/go-delve/delve