Module Proxyのマニアックな話 / Niche Topics in Module Proxy

2025/10/24 Asakusa.go #6 で使用したスライドです。

参考リンク
what is the go proxy even doing?
https://flak.tedunangst.com/post/what-is-the-go-proxy-even-doing

what the go proxy has been doing?
https://flak.tedunangst.com/post/what-the-go-proxy-has-been-doing

cmd/go: implement Mercurial support for go mod download -reuse, go list -reuse · Issue #75119 · golang/go · GitHub
https://github.com/golang/go/issues/75119

proxy.golang.org: investigate and fix humungus.tedunangst.com traffic · Issue #75120
https://github.com/golang/go/issues/75120

proxy.golang.org: revise background refresh pacing · Issue #75191
https://github.com/golang/go/issues/75191

Go Module Proxy
https://proxy.golang.org/

License Policy - Go Packages
https://pkg.go.dev/license-policy

Transcript

1. Module Proxyのマニアックな話 2025/10/24 Asakusa.go #6 kuroda naoki
2. 自己紹介 kuro @knkurokuro7 - 名前：kuroda naoki - 所属：株式会社サイバーエージェント DeveloperProductivity室 Bucketeerチーム所属 - 浅草は仲がいい先輩が住んでいる という縁があります。
3. Go Module Proxyの基礎知識 • モジュールのダウンロード元として機能するHTTPサーバー • Goチームは、proxy.golang.orgで提供されるモジュールミラーを 管理 • Goコマンドでは、通常、https://proxy.golang.orgに接続し、そこ でモジュールが見つからない場合にのみ、フォールバックとして バージョン管理システム（VCS）から直接ダウンロードを試みる。 • あるモジュールバージョンをまだ保持していない場合、オリジンの VCSから情報を取得し、それをキャッシュ（ミラー）する。
4. Go Module Proxyの基礎知識 goコマンド モジュール プロキシ 　 　VCS キャッシュがあると それを返す キャッシュがないと VCSから取得して キャッシュする The Go gopher was designed by Renée French.
5. 事の発端 2025年8月、Ted Unangstさんがブログで問題を報告した 「Goプロキシは一体何をしているのか？」
6. ブログの内容 1. "what is the go proxy even doing?" ◦ proxy.golang.orgから数分おきにhg clone(Mercurial)リクエスト ◦ 24時間に1回のみ許可する429レート制限を実装 2. "what the go proxy has been doing" ◦ Russ Coxさんとメール交渉し根本原因を調査⇨Go側もissueを作成し調 査、対応 ◦ 原因: Pythonスクリプトがindex.golang.orgを監視し全タグをダウン ロード(※別でMercurialに対応できていない問題も) ◦ LICENSEファイルがないと30日でキャッシュ期限切れと判明 ◦ 対応: 全リポジトリにLICENSE追加、429制限解除⇨連続クローン消失
7. マニアックな学び①：LICENSEファイルの重要性 My advice to anyone hosting any go code, make sure you’ve got a LICENSE file. Also, make sure the text of the file is very simple, just the license, and not some commentary on why you’ve chosen the license, or it won’t count.　 ー"what the go proxy has been doing" ⇨LICENSEファイル📄 を置くことで長時間の連続クローンが消失
8. マニアックな学び①：LICENSEファイルの重要性 proxy.golang.org: investigate and fix humungus.tedunangst.com traffic #75120 によると、 LICENSEファイルありの場合 • モジュールプロキシに無期限にキャッシュされる • バックグラウンド更新は一切行われない • pkg.go.devにドキュメントが表示される LICENSEファイルなしの場合 • 30日でキャッシュ期限切れ • キャッシュにない場合:　オンデマンドで上流サーバーから取得 • 25日経過後にバックグラウンド更新を開始（最近アクセスがあった場合のみ） • pkg.go.devにドキュメントが表示されない
9. マニアックな学び②：cached-onlyエンドポイント Something I learned is that the go proxy includes an auxiliary index service; see proxy.golang.org for details. Whenever a new tag hits the proxy, it gets announced here too, which explains why I get a burst of traffic after retrieving a new tag. The instructions say one should use the /cached-only endpoint for bulk downloads, but not everyone reads the manual. ー"what the go proxy has been doing" • proxy.golang.org　のインデックスを見てPythonがクローリングしていた。 • /cached-only　エンドポイントが存在する。。。
10. マニアックな学び②：cached-onlyエンドポイント https://proxy.golang.org/
11. マニアックな学び②：cached-onlyエンドポイント issue: proxy.golang.org: investigate and fix humungus.tedunangst.com traffic #75120
12. マニアックな学び②：cached-onlyエンドポイント 通常のエンドポイント GOPROXY=https://proxy.golang.org • キャッシュをチェック • なければ上流から取得 • キャッシュして返す cached-onlyエンドポイント GOPROXY=https://proxy.golang.org/cached-only • キャッシュをチェック • キャッシュにあるものだけを返す • 上流へのアクセスなし
13. マニアックな学び③：モジュールプロキシの定期更新 モジュールプロキシは上流VCSサーバーから情報を定期的に再取得し てキャッシュを更新する。 対象 • モジュールzipファイル（LICENSEなしの場合） ◦ 特定バージョンのモジュールの実際のコード • バージョンクエリ（@v/main.infoなど） ◦ 特定のブランチやタグの最新情報を取得するクエリ • バージョンリスト（@v/list） ◦ そのモジュールの利用可能な全バージョンのリスト
14. マニアックな学び③：モジュールプロキシの定期更新 goコマンド モジュール プロキシ 　 　VCS 定期的にキャッシュを 更新する The Go gopher was designed by Renée French.
15. マニアックな学び③：モジュールプロキシの定期更新 例）3日に1回アクセスされるモジュールのバージョンリストの最悪のパターン = 1リクエスト → 3日間の更新を正当化 = 3日 × 24時間 × (60分 / 25分) = 最悪172.8回の上流アクセス ⇨更新間隔と「最近」の定義が不一致が問題 項目 更新間隔 「最近」の定義 LICENSEなしモジュール 25日 1日以内 バージョンクエリ 25分 1日以内 バージョンリスト 25分 3日以内
16. マニアックな学び③：モジュールプロキシの定期更新 issue: proxy.golang.org: revise background refresh pacing #75191 でこの問題が指摘されている。 改訂案として、（Go1.26で入るかも） 更新間隔 = 「最近」の定義 に統一 → 高頻度にアクセスされるモジュール：影響なし（バージョンリストの場合、25分に1回以上 のアクセス） 低頻度にアクセスされるモジュール：上流サーバーへの負荷が大幅削減
17. まとめ 1. LICENSEファイルの重要性 　　　⇨キャッシュ期間に影響する 2. cached-onlyエンドポイント ⇨キャッシュのみを見たい時に 3. モジュールプロキシの定期更新 ⇨このロジックが変わりそう
18. 参考 • what is the go proxy even doing? • what the go proxy has been doing • cmd/go: implement Mercurial support for go mod download -reuse, go list -reuse · Issue #75119 · golang/go · GitHub • proxy.golang.org: investigate and fix humungus.tedunangst.com traffic · Issue #75120 • proxy.golang.org: revise background refresh pacing · Issue #75191 • Go Module Proxy • License Policy - Go Packages