例外・エラー処理

Laravel Copilot SDK がスローする例外の種類と発生条件、throw() による捕捉方法、JSON-RPC エラーや SessionFs の SQLite プロバイダーでの扱いを説明します。

例外・エラー処理

SDK がスローする例外は、すべて Revolution\Copilot\Exceptions 名前空間にあります。発生のしかたは2通りあり、セッションの実行結果に保持されて throw() でスローされるものと、RPC 呼び出しなどでその場でスローされるものがあります。

セッションのエラーとタイムアウト

sendAndWait() や Copilot::run() では、セッションエラーやタイムアウトが発生してもその場ではスローされず、返ってきた SessionEvent に例外が保持されます。Laravel の Http や Process と同様に throw() を呼ぶと保持された例外がスローされ、エラーでないときは何もしないので、そのままメソッドチェーンを続けられます。

use Revolution\Copilot\Exceptions\SessionErrorException;
use Revolution\Copilot\Exceptions\SessionTimeoutException;
use Revolution\Copilot\Facades\Copilot;

try {
    $content = Copilot::run('1 + 1 を計算して')->throw()->content();
} catch (SessionTimeoutException $e) {
    // タイムアウト時の処理
} catch (SessionErrorException $e) {
    // セッションエラー時の処理
}

例外をスローせずに成否だけを確認したい場合は、failed() と successful() が使えます。詳しくは SessionEvent を参照してください。

SessionTimeoutException

session.idle（応答の完了）を待つ間にタイムアウトすると保持されます。タイムアウトは sendAndWait() の timeout 引数で指定でき、省略した場合は copilot.timeout 設定（デフォルトは60秒）が使われます。

SessionErrorException

セッションが SESSION_ERROR イベントでエラーを返すと保持されます。メッセージにはランタイムから返されたエラーの内容が含まれます。

JsonRpcException

RPC 呼び出しに対して CLI が JSON-RPC エラーを返すと、その場でスローされます。JSON-RPC のエラーコードは code プロパティ、エラーに付随するデータは data プロパティで取得できます。

use Revolution\Copilot\Exceptions\JsonRpcException;
use Revolution\Copilot\Facades\Copilot;

try {
    Copilot::client()->rpc()->ping();
} catch (JsonRpcException $e) {
    $e->code; // JSON-RPC のエラーコード
    $e->data; // エラーに付随するデータ
}

SessionFsSqliteTransactionFailure

SessionFs の SQLite プロバイダーを実装する場合に使う例外です。捕捉するものではなく、プロバイダーの transaction() からスローして失敗の分類をランタイムへ伝えます。分類は errorClass で指定します。

• Fatal（デフォルト）: 回復不能な失敗
• BusyOrLocked: コミット前に SQLite が BUSY/LOCKED を返し、トランザクションがロールバックされた場合のみ使います
• PostCommitAmbiguous: コミット後の結果が確定できない場合

これ以外の例外を transaction() からスローすると、fatal として報告されます。

use Revolution\Copilot\Enums\SessionFSSqliteTransactionErrorClass;
use Revolution\Copilot\Exceptions\SessionFsSqliteTransactionFailure;

throw new SessionFsSqliteTransactionFailure(
    'database is locked',
    SessionFSSqliteTransactionErrorClass::BusyOrLocked,
);

StrayRequestException

テスト用の Fake で、対応する Fake が登録されていないリクエストを送るとスローされます。意図せず発生した場合は、リクエストに対応する Fake の登録漏れです。Fake の使い方は テスト を参照してください。