bca-web の運用

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

Use the REST API reference for request and response fields, and Driving the REST API for complete curl examples. This page covers the process itself and links to those two rather than repeating them.

ビルドと実行

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 のスモークチェック）が失敗を検知して再起動や警告を行えます。

言語のサブセットでのビルドは機能しません

The shipped bca-web binary compiles every supported tree-sitter grammar in. The big-code-analysis-web crate pins the library’s all-languages feature set explicitly, so passing --no-default-features or a custom --features list to cargo build -p big-code-analysis-web does not drop grammars from the resulting binary. Dropping a grammar silently from a user-facing daemon would surface as “language X stopped working” at request time rather than as a build error, so the crate forbids it (issue #252).

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

コマンドラインフラグ

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

--num-jobs auto is cgroup-quota- and cpuset-aware on Linux: in a container with a CPU quota it resolves to the quota rather than the host’s physical core count, matching the bca CLI’s --num-jobs. This count sizes the worker pool and the parse-admission semaphore, so it caps how many parses run concurrently. The minimum is 1; 0 is rejected when the flag is parsed.

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

CORS is off by default. The CORS section of the reference documents it in full, covering preflight handling, the wildcard form, and the absence of credentials. The short version: pass --cors with an explicit origin allow-list to let browser tooling read responses; omit it to emit no Access-Control-* headers at all.

環境変数

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

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

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

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

Orphaned-task admission control. When a parse exceeds --parse-timeout-secs, the request returns 504, but the blocking thread keeps running on the pool until the parse finishes on its own, because tree-sitter cannot be interrupted mid-parse. To stop sustained pathological input from piling up unbounded background work, new requests are rejected with 503 Service Unavailable once the count of orphaned tasks reaches a soft cap. The cap defaults to max(num_jobs * 2, 4); BCA_MAX_ORPHANED_TASKS overrides it (parsed as an unsigned integer; an invalid or zero value falls back to the default). Setting --parse-timeout-secs 0 disables this mechanism entirely, since with no deadline no task is ever orphaned.

セキュリティと信頼境界

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 つです。