path-types

パス型

新しい型を定義する際は、この指針を適用してください。明示的な依頼がない限り既存のコードは変更せず、編集は最小限かつ適切な範囲にとどめてください。これらのルールは現在進行中の移行の目標状態として扱ってください。準拠が難しい場合は、進め方をユーザーに確認してください。

• app-server プロトコルの型では、URI への移行中の後方互換性を保つために LegacyAppPathString を使用してください。プロトコル境界で PathUri に変換し、内部では PathUri を使用してください。一部の設定値など、ホストローカルのロジックには、代わりに AbsolutePathBuf または PathBuf を使用してください。
• exec-server プロトコルの型では、PathUri を使用してください。内部では、適宜 PathUri または AbsolutePathBuf を使用してください。
• 両方のサーバーで共有される依存関係では、PathUri を使用するか、用途を分離する別個の API を使用してください。
• モデルが生成することを想定しているツール呼び出しの引数は、通常の String としてデシリアライズし、機能固有のパス処理コードで処理してください。

移行要件

上記のガイドラインに準拠するようコードを移行する際は、以下の要件に留意してください。

• 既存の app-server クライアントは、従来のネイティブパス文字列を引き続き送受信する
• app-server は、異なるプラットフォームのパス URI を保持し、操作できる
• exec-server API は file:// URI を使用する
• ローカルのみの操作では、モデルから見えるテキストを変更しない
• モデルのツール引数には、あらゆる OS の生の相対パスまたは絶対パスが含まれる場合がある
• 関連する環境が起動する前に、パスに関する推論が機能する
• URI では、実行環境のパス規則や OS を明示的にエンコードできない
• ユーザーが環境の OS／パス規則を明示的に設定する必要がない
• URI は、現時点ではロールアウト、データベース、その他の永続ストレージに保存しない
• パス変換エラーは、セキュリティ上重要なパスでは fail-closed、UI／診断では fail-open とする
• ローカルヘルパーよりも、PathUri または LegacyAppPathString に小さく特化したメソッドを優先する
• 診断では、PathUri の値を URI として表す

パスと URI の変換で多少の情報が失われても、実際のユーザーにとって正しく動作するのであれば問題ありません。

URI への移行によって、重大な新たな障害要因が増えるべきではありません。これまでは失敗しなかった一部の箇所でエラーを表面化させる必要がありますが、それは最小限にとどめてください。