# 非機能要件定義書

## 概要

本ドキュメントは、webpack v5.105.3 のソースコードから抽出した非機能要件を定義するものである。webpackはECMAScript/CommonJS/AMDモジュールをバンドルするビルドツールであり、Node.js上で動作する。本書では、キャッシュ設定、タイムアウト設定、リトライ設定、ロギング・監視設定、パフォーマンス制御、セキュリティ機構などの非機能要件を記述する。

## 性能要件

### レスポンスタイム

| 処理種別 | 目標値 | 備考 |
| --- | --- | --- |
| チャンクロードタイムアウト | 120,000ms（120秒）以内 | `output.chunkLoadTimeout` のデフォルト値。スクリプトタグによる動的チャンク読み込み時のタイムアウト。タイムアウト超過時は `onScriptComplete` が呼ばれエラーとなる（`lib/runtime/LoadScriptRuntimeModule.js`） |
| ファイルキャッシュ アイドルタイムアウト | 60,000ms（60秒） | `cache.idleTimeout` のデフォルト値。コンパイル完了後、ディスクキャッシュへの書き込みを開始するまでの待機時間（`lib/config/defaults.js:620`） |
| ファイルキャッシュ 初回ストアタイムアウト | 5,000ms（5秒） | `cache.idleTimeoutForInitialStore` のデフォルト値。初回ビルド時はより早くキャッシュを永続化する（`lib/config/defaults.js:621`） |
| ファイルキャッシュ 大規模変更後タイムアウト | 1,000ms（1秒） | `cache.idleTimeoutAfterLargeChanges` のデフォルト値。大規模な変更検知時にキャッシュ永続化を迅速に開始する（`lib/config/defaults.js:622`） |
| ウォッチモード 集約タイムアウト | 20ms | `watchOptions.aggregateTimeout` のデフォルト値。ファイル変更検知後、再ビルドを開始するまでの集約待機時間（`lib/Watching.js:63`） |

### スループット

| 項目 | 目標値 | 備考 |
| --- | --- | --- |
| 並列処理数（parallelism） | 100 | `options.parallelism` のデフォルト値。モジュールのファクトリ処理やビルド処理の同時実行数上限（`lib/config/defaults.js:352`） |
| アイドル時バッチ処理数 | 最大100件 / 100ms | `IdleFileCachePlugin` のアイドル時処理で、1バッチあたり最大100件または100ms以内のタスクを処理する（`lib/cache/IdleFileCachePlugin.js:143-147`） |
| 最大非同期リクエスト数（production） | 30 | `splitChunks.maxAsyncRequests` のデフォルト値（production）。非同期チャンクの並列リクエスト上限（`lib/config/defaults.js:1898`） |
| 最大初期リクエスト数（production） | 30 | `splitChunks.maxInitialRequests` のデフォルト値（production）。初期チャンクの並列リクエスト上限（`lib/config/defaults.js:1899`） |

## 可用性要件

| 項目 | 目標値 | 備考 |
| --- | --- | --- |
| 稼働率 | 該当なし | webpackはビルドツールであり、常時稼働サービスではないため、稼働率の定義は該当しない |
| 計画停止時間 | 該当なし | 同上 |
| 障害復旧時間（RTO） | 該当なし | 同上 |
| 目標復旧時点（RPO） | 該当なし | 同上 |
| ウォッチモード継続性 | ファイル変更検知による自動再ビルド | `Watching` クラスがファイルシステムの変更を監視し、変更検知時に自動で再コンパイルを実行。エラー発生時もウォッチモードは継続する（`lib/Watching.js`） |
| キャッシュ復旧 | ビルド依存関係スナップショットによる検証 | `PackFileCacheStrategy` がビルド依存関係のスナップショットとバージョンを検証し、不整合時はキャッシュを無効化して再ビルドする（`lib/cache/PackFileCacheStrategy.js`） |

## セキュリティ要件

### Trusted Types対応

webpackは W3C Trusted Types API に対応しており、XSS攻撃を防止するためのポリシー機構を提供する。

| 項目 | 設定 | 備考 |
| --- | --- | --- |
| Trusted Types ポリシー名 | `output.uniqueName` から自動生成 | 英数字以外の文字はアンダースコアに置換される。フォールバック値は `"webpack"`（`lib/config/defaults.js:1593-1598`） |
| ポリシー作成失敗時の動作 | `"stop"`（デフォルト） | `trustedTypes.onPolicyCreationFailure` の値。`"stop"` でエラー停止、`"continue"` で警告出力後に続行（`lib/config/defaults.js:1600`、`lib/runtime/GetTrustedTypesPolicyRuntimeModule.js`） |
| スクリプトURL生成 | Trusted Types経由 | `CreateScriptUrlRuntimeModule` が `trustedTypes.createScriptURL()` を使用してスクリプトURLを生成する（`lib/runtime/CreateScriptUrlRuntimeModule.js`） |

### Nonce対応

| 項目 | 設定 | 備考 |
| --- | --- | --- |
| CSP nonce属性 | `__webpack_nonce__` で設定可能 | 動的に読み込まれるスクリプトタグに `nonce` 属性を付与し、Content Security Policy に準拠する（`lib/runtime/NonceRuntimeModule.js`、`lib/runtime/LoadScriptRuntimeModule.js:78-81`） |

### Cross-Origin設定

| 項目 | 設定 | 備考 |
| --- | --- | --- |
| crossOriginLoading | `false`（デフォルト） | `output.crossOriginLoading` の値。`"anonymous"` または `"use-credentials"` を設定可能。異なるオリジンからのスクリプト読み込み時に `crossOrigin` 属性を付与する（`lib/config/defaults.js:1567`、`lib/runtime/LoadScriptRuntimeModule.js:100-110`） |

### HTTP URI整合性検証

| 項目 | 設定 | 備考 |
| --- | --- | --- |
| Subresource Integrity | SHA-512によるハッシュ検証 | `HttpUriPlugin` がHTTP/HTTPSで取得したリソースの整合性を `sha512` ハッシュで検証する（`lib/schemes/HttpUriPlugin.js:121-136`） |
| 最大リダイレクト回数 | 5回 | `MAX_REDIRECTS = 5`。リダイレクトループを防止する（`lib/schemes/HttpUriPlugin.js:37`） |
| リダイレクト先の検証 | プロトコル制限 + allowedUris検証 | リダイレクト先がHTTP/HTTPSであること、かつ `allowedUris` ポリシーに合致することを検証する（`lib/schemes/HttpUriPlugin.js:670-693`） |
| URL無害化 | エラーメッセージ内のURL情報を制限 | `sanitizeUrlForError` 関数により、エラーメッセージに含まれるURL情報をホスト名までに制限する（`lib/schemes/HttpUriPlugin.js:216-224`） |

### ハッシュ関数

| 項目 | 設定 | 備考 |
| --- | --- | --- |
| ハッシュ関数 | `md4`（デフォルト）/ `xxhash64`（futureDefaults） | `output.hashFunction` の値。コンテンツハッシュ生成に使用（`lib/config/defaults.js:1578-1584`） |
| ハッシュダイジェスト | `hex` | `output.hashDigest` の値（`lib/config/defaults.js:1586`） |
| ハッシュダイジェスト長 | 20（デフォルト）/ 16（futureDefaults） | `output.hashDigestLength` の値（`lib/config/defaults.js:1587`） |
| キャッシュ用ハッシュ | `md4`（デフォルト）/ `xxhash64`（futureDefaults） | `cache.hashAlgorithm` の値。ファイルシステムキャッシュの整合性検証に使用（`lib/config/defaults.js:616`） |

## 拡張性要件

### プラグインアーキテクチャ

webpackはTapableベースのプラグインアーキテクチャを採用しており、ビルドプロセスの各段階に対してフック（Hook）を通じた拡張が可能である。

| 項目 | 設定 | 備考 |
| --- | --- | --- |
| フック機構 | Tapable（`SyncHook`, `AsyncSeriesHook`, `AsyncParallelHook` 等） | Compilerは40以上のフックを提供し、ビルドライフサイクルの各段階で介入可能（`lib/Compiler.js:164-199`） |
| キャッシュステージ | MEMORY(-10), DEFAULT(0), DISK(10), NETWORK(20) | キャッシュプラグインの実行順序を制御するステージ定数（`lib/Cache.js:163-166`） |
| モジュール分割戦略 | `SplitChunksPlugin` によるカスタマイズ可能な分割 | `cacheGroups`, `minSize`, `maxSize`, `minChunks` 等のパラメータで細かく制御可能（`lib/optimize/SplitChunksPlugin.js`） |
| ターゲットプラットフォーム | `web`, `node`, `electron`, `nwjs`, `webworker` 等 | `target` オプションにより出力コードの実行環境を指定可能（`lib/config/target.js`） |

### チャンク分割デフォルト値

| 項目 | production | development | 備考 |
| --- | --- | --- | --- |
| splitChunks.chunks | `"async"` | `"async"` | 非同期チャンクのみを分割対象とする（`lib/config/defaults.js:1892`） |
| splitChunks.minSize | 20,000 bytes | 10,000 bytes | 分割対象となる最小チャンクサイズ（`lib/config/defaults.js:1895`） |
| splitChunks.enforceSizeThreshold | 50,000 bytes | 30,000 bytes | このサイズを超えるとminChunks等の制約を無視して分割する（`lib/config/defaults.js:1897`） |
| splitChunks.minChunks | 1 | 1 | 分割対象となる最小共有チャンク数（`lib/config/defaults.js:1894`） |

## 保守性要件

### キャッシュ機構

webpackは多層キャッシュ機構を提供し、ビルドパフォーマンスの最適化と保守性の向上を図っている。

| キャッシュ種別 | 説明 | 設定 |
| --- | --- | --- |
| メモリキャッシュ | インメモリMap型キャッシュ。`MemoryCachePlugin` が担当 | `cache.type: "memory"` で有効化。developmentモードではデフォルトで有効（`lib/cache/MemoryCachePlugin.js`） |
| メモリキャッシュ（GC付き） | 世代管理によるガベージコレクション付きメモリキャッシュ | `cache.maxGenerations` で保持世代数を設定。`maxMemoryGenerations` でメモリ内保持世代数を制御（`lib/cache/MemoryWithGcCachePlugin.js`） |
| ファイルシステムキャッシュ | ディスクベースの永続キャッシュ。`IdleFileCachePlugin` + `PackFileCacheStrategy` が担当 | `cache.type: "filesystem"` で有効化。キャッシュディレクトリは `node_modules/.cache/webpack` がデフォルト（`lib/config/defaults.js:584-607`） |
| キャッシュ最大保持期間 | 60日 | `cache.maxAge` のデフォルト値。`1000 * 60 * 60 * 24 * 60`（`lib/config/defaults.js:624`） |
| キャッシュ圧縮 | 無効（デフォルト） | `cache.compression` で有効化可能（`lib/config/defaults.js:618`） |
| リゾルバキャッシュ | モジュール解決結果のキャッシュ | `ResolverCachePlugin` がモジュールパス解決結果をキャッシュ（`lib/cache/ResolverCachePlugin.js`） |

### シリアライゼーション

| 項目 | 説明 | 備考 |
| --- | --- | --- |
| シリアライゼーション方式 | `pack` 形式（デフォルト） | `cache.store` の値。複数のキャッシュエントリを1つのファイルにパックして書き込む（`lib/config/defaults.js:617`） |
| バイナリミドルウェア | 効率的なバイナリシリアライゼーション | `BinaryMiddleware` がオブジェクトをバイナリ形式に変換（`lib/serialization/BinaryMiddleware.js`） |
| ファイルミドルウェア | ディスクI/O最適化 | `FileMiddleware` がファイルの読み書きを管理（`lib/serialization/FileMiddleware.js`） |

### ファイルシステムリトライ

| 項目 | 設定 | 備考 |
| --- | --- | --- |
| symlink読み込みリトライ | 最大3回（初回 + 2回リトライ） | `lstatReadlinkAbsolute` 関数がシンボリックリンクの読み取りに失敗した場合、最大2回リトライする。ファイルシステムの一時的な変更に対する耐性を確保（`lib/util/fs.js:629-634`） |

## 運用・監視要件

### ロギング機構

webpackは階層化されたロギングシステムを提供する。

| 項目 | 設定 | 備考 |
| --- | --- | --- |
| ログレベル | `none`, `error`, `warn`, `info`（デフォルト）, `log`, `verbose` | `infrastructureLogging.level` で設定。6段階のログレベルをサポート（`lib/logging/createConsoleLogger.js:68-77`） |
| デバッグフィルタ | 文字列、正規表現、関数、真偽値 | `infrastructureLogging.debug` で特定モジュールのデバッグログを有効化可能（`lib/logging/createConsoleLogger.js:83-92`） |
| ログ種別 | `error`, `warn`, `info`, `log`, `debug`, `trace`, `group`, `groupCollapsed`, `groupEnd`, `profile`, `profileEnd`, `time`, `clear`, `status` | `LogType` 定数で定義される全14種のログ種別（`lib/logging/Logger.js:8-28`） |
| パフォーマンス計測 | `time` / `timeEnd` / `timeAggregate` メソッド | `WebpackLogger` クラスが `process.hrtime()` を使用した高精度な時間計測を提供（`lib/logging/Logger.js:150-219`） |
| プロファイリング | `profile` / `profileEnd` メソッド | ブラウザDevToolsスタイルのプロファイリング対応（`lib/logging/Logger.js:136-145`） |

### 進捗報告

| 項目 | 設定 | 備考 |
| --- | --- | --- |
| ProgressPlugin | ビルド進捗の報告 | コンパイルの各段階でパーセンテージベースの進捗報告を行う。カスタムハンドラ関数の指定が可能（`lib/ProgressPlugin.js`） |
| キャッシュ進捗報告 | アイドル時のキャッシュ書き込み進捗 | `IdleFileCachePlugin` が `ProgressPlugin.getReporter()` を使用してキャッシュ書き込み進捗を報告（`lib/cache/IdleFileCachePlugin.js:113-123`） |

### パフォーマンス監視（バンドルサイズ）

| 項目 | デフォルト値 | 備考 |
| --- | --- | --- |
| 最大アセットサイズ | 250,000 bytes（約244KB） | `performance.maxAssetSize` の値。超過時に警告またはエラーを出力（`lib/config/defaults.js:1817`） |
| 最大エントリポイントサイズ | 250,000 bytes（約244KB） | `performance.maxEntrypointSize` の値。超過時に警告またはエラーを出力（`lib/config/defaults.js:1818`） |
| ヒント出力モード | `"warning"`（production）/ `false`（development） | `performance.hints` の値。`"error"` でビルドエラー扱いにすることも可能（`lib/config/defaults.js:1819`） |
| ソースマップ除外 | 開発用アセットは除外 | `assetFilter` のデフォルト実装が `info.development` フラグのあるアセットを除外（`lib/performance/SizeLimitsPlugin.js:40`） |

### HTTP URIキャッシュ制御

| 項目 | 設定 | 備考 |
| --- | --- | --- |
| Cache-Control解析 | `no-cache`, `max-age`, `must-revalidate` | `parseCacheControl` 関数がHTTPレスポンスのCache-Controlヘッダーを解析し、キャッシュ戦略を決定（`lib/schemes/HttpUriPlugin.js:165-185`） |
| ロックファイル管理 | バージョン1形式 | `Lockfile` クラスが取得済みリソースの `resolved`, `integrity`, `contentType` を管理（`lib/schemes/HttpUriPlugin.js:227-283`） |

## 備考

### 動作環境要件

| 項目 | 要件 | 備考 |
| --- | --- | --- |
| Node.jsバージョン | >= 10.13.0 | `package.json` の `engines.node` で定義（`package.json:209`） |
| テスト実行時メモリ | 最大4GB（`--max-old-space-size=4096`） | テストスクリプトで指定されるV8ヒープ上限（`package.json:55`） |

### developmentモードとproductionモードの差異

webpackの非機能特性はモードによって大きく異なる。

| 項目 | development | production |
| --- | --- | --- |
| キャッシュ | メモリキャッシュ有効 | キャッシュ無効 |
| メモリキャッシュ世代数 | 5 | Infinity |
| パフォーマンスヒント | 無効 | `"warning"` |
| splitChunks.minSize | 10,000 bytes | 20,000 bytes |
| splitChunks.maxAsyncRequests | Infinity | 30 |
| splitChunks.maxInitialRequests | Infinity | 30 |
