bca-web の運用

bca-web は big-code-analysis ライブラリをラップする HTTP デーモンで、コメント除去、関数スパン、AST ダンプ、保守性メトリクス、変更履歴（VCS）メトリクスを REST API として公開します。このページはデーモンを運用するオペレーター向けに、ビルドと起動の方法、チューニングに使うフラグと環境変数、そして公開前に守るべき信頼境界を説明します。

本ページは 2 つのリファレンスページを補う運用ガイドです。REST API リファレンスは、全エンドポイントとそのリクエスト / レスポンス形式、エラー契約を文書化しています。REST API を操作するレシピは、エンドツーエンドの curl 呼び出しを示します。このページはプロセスそのものを扱い、内容を繰り返す代わりにこの 2 つへリンクします。

ビルドと実行

bca-web は big-code-analysis-web クレートのバイナリです。チェックアウトからは Cargo 経由で実行します:

cargo run -p big-code-analysis-web -- --host 127.0.0.1 --port 8080

バイナリを PATH 上に置くには、リリースアーティファクトをビルドしてコピーするか、クレートからインストールします:

cargo install big-code-analysis-web   # `bca-web` コマンドをインストールします
bca-web --host 127.0.0.1 --port 8080

bca-web は指定されたアドレスにバインドし、中断されるまでサービスを提供します。ポートをバインドできない場合や I/O エラーに遭遇した場合は非ゼロで終了するため、スーパーバイザー（systemd、コンテナオーケストレーター、CI のスモークチェック）が失敗を検知して再起動や警告を行えます。

出荷される bca-web バイナリは、対応するすべての tree-sitter 文法をコンパイルして組み込みます。big-code-analysis-web クレートはライブラリの all-languages フィーチャセットを明示的に固定しているため、cargo build -p big-code-analysis-web に --no-default-features や独自の --features リストを渡しても、生成されるバイナリから文法は除外されません。ユーザー向けデーモンから文法が黙って抜け落ちると、ビルドエラーではなくリクエスト時に「言語 X が動かなくなった」という形で表面化するため、このクレートはそれを禁止しています（issue #252）。

文法セットを削減する必要がある場合は、自分の Rust コードに big-code-analysis ライブラリを組み込み、自分の Cargo.toml でフィーチャを選択してください。言語別 Cargo フィーチャの章に、すべてのフィーチャと実際の例が載っています。

コマンドラインフラグ

デフォルト値付きの全フラグ一覧:

フラグ	デフォルト	目的
`-j`, `--num-jobs <N\\|auto>`	`auto`	ワーカースレッド数。`auto` は OS が報告する実効 CPU 数に解決されます。
`--host <HOST>`	`127.0.0.1`	バインドするアドレス。
`-p`, `--port <PORT>`	`8080`	TCP ポート。
`--parse-timeout-secs <SECS>`	`30`	パース 1 回あたりの期限。`0` で無効になります。
`--cors <ORIGINS>`	オフ	カンマ区切りのオリジン許可リストに対して CORS を有効にします。
`-h`, `--help`		ヘルプを表示して終了します。
`-V`, `--version`		バージョンを表示して終了します。

--num-jobs auto は Linux で cgroup のクォータと cpuset を認識します。CPU クォータ付きのコンテナ内では、ホストの物理コア数ではなくクォータに解決され、bca CLI の --num-jobs と同じ挙動になります。この数はワーカープールとパース許可セマフォのサイズを決めるため、同時に実行できるパース数の上限になります。最小値は 1 で、0 はパース時に拒否されます。

--parse-timeout-secs は、リクエストが 504 Gateway Timeout を返すまでに 1 回のパースが実行できる時間を制限します。デフォルトの 30 は、病的な入力がワーカーを無期限に塞ぐことを防ぎます。0 に設定すると期限がなくなり、それとともに後述の負荷制御も無効になります。無制限のパースが許容できる場合にのみ 0 を使ってください。タイムアウト時に返されるレスポンスボディは REST API リファレンスを参照してください。

CORS はデフォルトで無効です。リファレンスの CORS セクションが、プリフライト処理、ワイルドカード形式、クレデンシャル非対応を含めて完全に文書化しています。要約すると、ブラウザーのツールにレスポンスを読ませたい場合は明示的なオリジン許可リストを付けて --cors を渡し、省略すれば Access-Control-* ヘッダーは一切出力されません。

環境変数

変数	デフォルト	目的
`BCA_MAX_ORPHANED_TASKS`	`max(num_jobs * 2, 4)`	孤児化した（タイムアウト後もまだ実行中の）パースタスクの上限。これに達すると新しいリクエストは `503` で遮断されます。
`RUST_LOG`	`info`	`tracing` サブスクライバーのログフィルター。

RUST_LOG は EnvFilter の構文を使います（例: RUST_LOG=big_code_analysis_web=debug）。デーモンは完了したリクエストごとに、メソッド、ルート、ステータス、レイテンシを含むアクセスログを 1 行出力します。

リソース制限とバックプレッシャー

単一のクライアントによるリソース枯渇からデーモンを守る制限が 2 つあります。

リクエストボディサイズ。 すべてのエンドポイントは、4 MiB を超えるリクエストボディを 413 Payload Too Large で拒否します。この制限は JSON と raw オクテットストリームのコンテンツタイプに一律に適用されるため、どちらも同じしきい値で過大なボディを拒否します。

孤児タスクの流入制御。 パースが --parse-timeout-secs を超えるとリクエストは 504 を返しますが、tree-sitter はパース途中で中断できないため、ブロッキングスレッドはパースが自然に終わるまでプール上で動き続けます。持続的な病的入力によってバックグラウンド作業が際限なく積み上がるのを止めるため、孤児タスク数がソフト上限に達すると、新しいリクエストは 503 Service Unavailable で拒否されます。上限のデフォルトは max(num_jobs * 2, 4) で、BCA_MAX_ORPHANED_TASKS で上書きできます（符号なし整数としてパースされ、不正な値やゼロはデフォルトにフォールバックします）。--parse-timeout-secs 0 を設定すると、この仕組み全体が無効になります。期限がなければタスクが孤児化することはないためです。

セキュリティと信頼境界

bca-web 自体には認証、認可、レート制限がありません。デフォルト値はローカルの単一オペレーター運用向けに選ばれています。広げる場合は意図的に行ってください。

デフォルトのバインド先はループバックです。 サーバーは --host で指定しない限り 127.0.0.1 にバインドします。ネットワークに公開する前は、そのままにしておくか、前段に認証プロキシを置いてください。0.0.0.0 にバインドすると、ポートに到達できる誰もが以下のすべての機能に到達できるようになります。

CORS はデフォルトで無効です。 --cors フラグがなければ、別オリジンのブラウザースクリプトは API レスポンスを読めないため、オペレーターがたまたま訪れたページがループバックの bca-web をこっそり操作することはできません。ワイルドカード形式（--cors '*'）はすべてのオリジンに応答し、サーバーのメトリクスやリポジトリパスを任意のサイトに公開するため、信頼できるネットワークでのみ使ってください。完全なセマンティクスは CORS にあります。

VCS エンドポイントはサーバー側のリポジトリを読み取ります。 ソースコードをボディで受け取るエンドポイントと異なり、/v1/vcs、/v1/vcs/trend、/v1/vcs/jit は、リクエストの repo_path で指定される、サーバーのファイルシステム上に既にある git リポジトリを解析します。これらのエンドポイントに到達できる呼び出し元は、サーバーが読み取れる任意の git リポジトリをサーバーに走査させ、そのリポジトリのファイルパス、チャーン、作者シグナルを知ることができます。リファレンスの VCS 信頼境界の警告がこれを完全に扱っています。認可レイヤーなしで、信頼できないクライアントにこれらのエンドポイントを公開しないでください。

VCS キャッシュディレクトリはクライアントが制御する書き込みパスです。 VCS エンドポイントはオプションの cache_dir フィールドを受け付け、永続的な変更履歴キャッシュの書き込み先を上書きできます。デフォルトはプラットフォームのキャッシュ位置（$XDG_CACHE_HOME/big-code-analysis/vcs）です。cache_dir を設定できる呼び出し元は、サーバープロセスが書き込むディレクトリを選べるため、信頼できないクライアントは攻撃者が選んだパスにキャッシュ書き込みを向けられます。これも、VCS エンドポイントを認可レイヤーの背後に置き、信頼できない入力に決して開放してはならない理由の 1 つです。

big-code-analysis Documentation