initial commit

docs/resource-warning-contract.md

@@ -0,0 +1,33 @@
+# 資源の警告集計
+
+HTML・HTML ZIP・EPUBで読み込めない資源があっても、表示可能な本文を維持する。最初の検出時に一度だけ通知し、`:info`で理由別の検出件数を確認できる。件数は同じ資源の再試行も含み、固有URLの数ではない。
+
+検出は三つの経路を使う。
+
+- ResourceHandler: `ResourceFailure` の有限分類を使い、不在、危険な参照、OSアクセス拒否、許可外の資源形式、サイズ上限、アーカイブの展開上限・CRC/長さ破損、容量不足、保存失敗、読取I/O失敗、Worker停止・期限超過を区別する。OSやWorkerの生のmessage・パスは受け渡さない。
+- DocumentInterceptor: 通信・文書外参照の拒否。Chromiumの割込み処理では上限付きatomicカウンターだけを更新し、250msごとにMainで集約する。
+- ApplicationWorldの固定スクリプト: ブラウザー自身が発生させた`securitypolicyviolation`のうち、強制適用されたもの。画像、CSS、フォント等のdirective分類だけを取り出す。
+
+集計は文書セッションのメモリー内だけに置く。URL、ファイル名、blockedURI、sourceFile、policy本文、sampleは収集しない。理由は固定24種類（broker 12、network 1、CSP 11）、各件数は999,999で飽和し、上限では「以上」と表示する。ブラウザーからの報告は固定11キー、有限の正整数、上限を全件検証してから反映する。不正な一項目があれば報告全体を捨てる。
+
+| 検出 | 表示コード |
+|---|---|
+| 索引にない資源、OSが返す存在しないファイル・ディレクトリー | `E_RESOURCE_MISSING` |
+| root/型/リンク等の安全検査拒否、OSの権限・共有拒否、許可外MIME（理由は別集計） | `E_RESOURCE_BLOCKED` |
+| 1資源256 MiBまたは1書込64 KiBの上限 | `E_RESOURCE_LIMIT` |
+| アーカイブの累積・資源展開上限 | `E_ARCHIVE_LIMIT` |
+| CRC・圧縮データ・長さの不整合 | `E_ARCHIVE_CORRUPT` |
+| OSが明示するディスク容量・割当量不足 | `E_STORAGE_FULL` |
+| その他の一時資源の作成・書込・同期・確定失敗 | `E_STORAGE_FAILED` |
+| その他の資源open・read失敗 | `E_RESOURCE_IO` |
+| 不正/未知のworker失敗、期限超過 | `E_WORKER_CRASH` / `E_WORKER_TIMEOUT` |
+
+`E_RESOURCE_LIMIT`、`E_STORAGE_FAILED`、`E_RESOURCE_IO` はこの追加契約のコードである。未知のOS失敗を欠落や容量不足と推測しない。WindowsではNTSTATUSをOSの変換APIで分類し、reparse/type/link/sizeは開いたhandleの情報から判定する。QFileは両OSとも所有済みfdを採用する。open後のread失敗は一度だけqueued signalでMainへ伝え、破棄・失効済みセッションには反映しない。
+
+展開のcompletionは成功・取消・原因分類を保持する。WorkerProcessが実際に停止してRPC callbackを破棄した場合も、failed通知で保留中の資源jobへ停止理由を渡してからセッションを失効する。明示的な取消・文書切替の失効はCancelledのままとし、件数を追加しない。CRC・展開上限・不正worker応答では後続展開を停止し、既に表示した本文を保持する。失敗した途中ファイルは公開しない。保存容量不足とCRC不整合を同じコードへまとめない。汎用の章load失敗は`E_OPEN_FAILED`とし、資源不在と決め付けない。
+
+取り消した文書、終了した文書、失効したセッションの報告は反映しない。固定EPUBの見開きでは現在表示する両ページから同じ文書へ集約する。履歴・保存位置には件数を保存しない。すべてのブラウザー内拒否が必ずCSPイベントを発生させるとは限らないため、一覧は実際に検出した事象を表す。
+
+[Qtのinterceptor契約](https://doc.qt.io/qt-6/qwebengineurlrequestinterceptor.html)に従い、interceptRequest内でprofileのAPIやUIを呼ばない。[CSP仕様](https://www.w3.org/TR/CSP3/#securitypolicyviolationevent)のイベントを利用し、合成イベントは`isTrusted`で除外する。Qt 6.11.2での実際のイベント配送と通信拒否は[試験記録](../tests/results/resource-warnings/README.md)に残す。
+
+分類の追加回帰は[resource-classification](../tests/results/resource-classification/README.md)に記録する。Windows nativeのアクセス拒否・容量不足・I/O配送は未検証であり、補助コンパイルはその代わりにならない。