falco

トリガーと対象範囲

次の場合に使用します：VCL ファイル、.vcl 拡張子、XVCL ファイル、.xvcl 拡張子、falco CLI、VCL ユニットテスト、VCL のリント／シミュレーション／フォーマット、VCL REPL、beresp/bereq/req.http 変数、サブルーチンのスコープ、バックエンド／ACL／ディレクター／テーブルの宣言、エッジ辞書、Terraform プラン内の VCL の検証、または XVCL スクリプトのローカルでの実行／テスト。

次の場合には使用しないでください：Fastly 以外の一般的な VCL、Fastly Compute/WASM、Fastly API／ダッシュボードの操作、CDN の比較、キャッシュのパージ、Terraform リソースの作成。

Falco — VCL 開発ツールとリファレンス

Falco は、VCL コードのリント、テスト、シミュレーション、フォーマットを行うための Fastly VCL 開発ツールです。同じくらい重要なのは、falco のソースコードが Fastly の VCL 方言に関する最も完全な機械可読仕様であることです。パーサー、インタープリター、型システムによって、VCL のすべての変数、関数、型、スコープ規則が記述されています。

公式 VCL ドキュメント：https://www.fastly.com/documentation/guides/full-site-delivery/fastly-vcl/about-fastly-vcl/

Falco ドキュメント：https://github.com/ysugimoto/falco

Falco のソースを VCL リファレンスとして使う

VCL の仕組み（どのような変数があり、どのスコープで使用できるか、組み込み関数は何か、型がどのように変換されるか）を理解する必要がある場合は、falco のソースコードが最適なリファレンスです。Fastly の VCL 2.x を完全に実装した Go コードであり、文章によるドキュメントよりも正確です。

falco のソースがローカルにない場合は、クローンすることをおすすめします：

git clone https://github.com/ysugimoto/falco.git ~/src/falco

ローカルで利用できるようになったら、VCL に関する質問に答えるためにソースファイルを直接読んでください。VCL のトピックごとに読むべきファイルの詳細なガイドについては、understanding-vcl-from-source.md を参照してください。

インストール

# Homebrew
brew install falco

# From source (requires Go 1.25+)
go install github.com/ysugimoto/falco/cmd/falco@latest

# Or clone and build
git clone https://github.com/ysugimoto/falco.git
cd falco
make darwin_arm64    # or darwin_amd64, linux_amd64, linux_arm64

コマンド

コマンド	説明
falco [lint]	VCL ファイルをリントします（デフォルトのコマンド）
falco test	VCL ユニットテストを実行します
falco simulate	ローカルシミュレーターサーバーを起動します
falco fmt	VCL ファイルをフォーマットします
falco stats	VCL コードの統計情報を表示します
falco console	対話型 VCL REPL
falco terraform	Terraform プランの VCL をリントします
falco dap	Debug Adapter Protocol サーバー

共通フラグ（すべてのコマンド）

フラグ	説明
-I, --include_path	VCL のインポート用にインクルードパスを追加します
-h, --help	ヘルプを表示します
-V, --version	バージョンを表示します
-r, --remote	Fastly API からスニペットを取得します
--refresh	リモートスニペットのキャッシュを更新します

クイックリファレンス

デプロイ前にリントする：

falco -vv -I ./vcl ./vcl/main.vcl

テストを実行する：

falco test -I ./vcl ./vcl/main.vcl

ウォッチモードで開発する：

falco test -w -I ./vcl ./vcl/main.vcl

VCL をローカルで実行する（「ローカルで実行」または「ローカルでテスト」する方法です。lint だけでなく simulate を使用してください）：

falco simulate -I ./vcl ./vcl/main.vcl
# Default port is 3124. Test with: curl http://localhost:3124/path
# Use -p to override: falco simulate -p 8080 ./vcl/main.vcl

すべての VCL をフォーマットする：

falco fmt -w ./vcl/**/*.vcl

Terraform との統合：

terraform show -json planned.out | falco terraform -vv

よくある VCL の問題

Falco はこれらを検出しますが、理解しておくと lint と修正のサイクルで時間を無駄にせずに済みます。

• 型の不一致：set req.http.X-API = true — HTTP ヘッダーは BOOL ではなく STRING です。"true" を使用してください。
• 時間の単位の不足：set beresp.ttl = 86400 — RTIME 値には s サフィックスが必要です：86400s。
• スコープの誤り：beresp.* は vcl_fetch でのみ使用できます。vcl_deliver では resp.* を使用してください。
• 非推奨：req.request → req.method を使用してください。Falco はどちらも受け付けますが、VCL を修正する際は必ず req.method に変更してください。
• 合成文字列：synthetic "text" には長文字列構文が必要です：synthetic {"text"}。
• バックエンドの命名：backend origin ではなく、backend F_origin { ... } のように F_ プレフィックスを使用してください。
• 剰余演算子はありません：VCL に % はありません。分割にはハッシュに対する substr() または randomint() を使用してください。
• テストでは req.url.path は読み取り専用です：テスト用サブルーチンでは set req.url.path ではなく、set req.url = "/path" を使用してください。
• Vary の設定位置：Vary は vcl_deliver だけでなく、vcl_fetch で設定する必要があります。オブジェクトがキャッシュに格納された後では遅すぎます。キャッシュキーに Vary のディメンションが含まれなくなります。

設定

永続的な設定を行うには、プロジェクトのルートに .falco.yaml を作成します。

include_paths:
  - ./vcl
  - ./includes

linter:
  verbose: "warning"
  rules:
    rule-name: ERROR  # or WARNING, INFO, IGNORE

testing:
  timeout: 10  # minutes (default: 10)
  filter: "*.test.vcl"

simulator:
  port: 3124

format:
  indent_width: 2
  line_width: 120

環境変数

変数	説明
FASTLY_SERVICE_ID	Fastly API のサービス ID
FASTLY_API_KEY	Fastly API の API キー

-r, --remote フラグを使用する場合に必要です。

API 認証情報はチャットの外でローカルに設定してください。 会話の中で API キーを尋ねたり、その値を表示したりしないでください。

参考資料

トピック	ファイル	使用する場面
ソースから VCL を理解する	understanding-vcl-from-source.md	falco の実装を読んで VCL のセマンティクスを理解する場合
VCL のテスト	testing-vcl.md	TDD のためにテストスイート、カバレッジ、ウォッチモードを実行する場合
VCL のフォーマット	formatting-vcl.md	一貫したスタイルで VCL をフォーマットする場合
VCL の lint	linting-vcl.md	デプロイ前に VCL のエラーを確認する場合
VCL のシミュレーション	simulating-vcl.md	ローカルで HTTP リクエストに対して VCL をテストする場合
Terraform VCL	terraform-vcl.md	Terraform のプランから VCL を検証する場合
VCL コンソール	vcl-console.md	VCL 式を対話形式で試す場合
VCL の統計	vcl-statistics.md	VCL プロジェクトの規模と複雑さを分析する場合

VCL のリファレンスとしてのソースコード（クイック検索）

ローカルで falco のソースコード（デフォルト：~/src/falco）を参照できる場合は、具体的な VCL に関する質問に答える際に、以下のパスを確認してください。

質問	確認するファイル	理由
「vcl_recv で使える変数は何ですか？」	interpreter/variable/	スコープを含む、すべての req.*、beresp.*、client.* 変数
「組み込み関数には何がありますか？」	interpreter/function/	型シグネチャとスコープ規則を含む、390 以上の関数すべて
「VCL の型には何がありますか？」	interpreter/value/	STRING、INTEGER、FLOAT、BOOL、TIME、RTIME、IP、BACKEND
「リクエストのライフサイクルはどうなっていますか？」	interpreter/context/	9 つのスコープ：recv、hash、hit、miss、pass、fetch、error、deliver、log
「この VCL の構文は有効ですか？」	token/token.go、lexer/lexer.go	すべてのキーワード、演算子、リテラル型
「この VCL のステートメントはどのように動作しますか？」	interpreter/statement.go	set、unset、return、restart などの実行方法
「よくある VCL のミスには何がありますか？」	linter/、docs/rules.md	説明付きの 50 以上のリンティングルール
「ディレクターはどのように動作しますか？」	interpreter/director.go	Random、fallback、hash、client、chash の各ディレクタータイプ

包括的なガイドについては、understanding-vcl-from-source.md を参照してください。