# 非機能要件定義書

## 概要

本ドキュメントは、Hack Standard Library (HSL) プロジェクトの非機能要件を定義するものである。HSLはHack言語向けの標準ライブラリであり、型安全で一貫性のあるAPIを提供することを目的としている。本ライブラリはHHVMに組み込まれて実行される。

## 性能要件

### レスポンスタイム

| 処理種別 | 目標値 | 備考 |
| --- | --- | --- |
| 非同期I/O読み取り | タイムアウト設定可能（ナノ秒単位） | `timeout_ns`パラメータで制御 |
| TCP接続 | タイムアウト設定可能（ナノ秒単位） | `ConnectOptions`の`timeout_ns`で制御 |
| ファイルロック取得 | ブロッキング（即時取得オプションあり） | `lock()`はブロック、`tryLockx()`は即時取得 |

### スループット

| 項目 | 目標値 | 備考 |
| --- | --- | --- |
| 同時実行数 | Semaphoreで制御可能 | `concurrentLimit`パラメータで1以上の任意の値を設定可能 |
| 読み取りバッファサイズ | 8 KiB (8,192バイト) | `DEFAULT_READ_BUFFER_SIZE`で定義 |
| Semaphore最大同時実行数 | 10,000以上対応可能 | テストケースで9,999並列実行を検証済み |

### 並行処理制御

| 項目 | 仕様 | 備考 |
| --- | --- | --- |
| Semaphore並行制限 | インスタンス単位 | 複数リクエストでは各リクエストで個別にカウント |
| Asyncポーリング | `Poll`/`KeyedPoll`クラス | 複数Awaitableの非同期待機をサポート |
| 条件変数 | `Condition`クラス | 事前通知対応のConditionWaitHandleラッパー |

## 可用性要件

| 項目 | 目標値 | 備考 |
| --- | --- | --- |
| 稼働率 | HHVMランタイム依存 | ライブラリ自体に稼働率保証機能なし |
| 計画停止時間 | 該当なし | ライブラリとして提供のため適用外 |
| 障害復旧時間（RTO） | 該当なし | ライブラリとして提供のため適用外 |
| 目標復旧時点（RPO） | 該当なし | ライブラリとして提供のため適用外 |

### エラーハンドリング

| 項目 | 仕様 | 備考 |
| --- | --- | --- |
| タイムアウト | `OS\Errno::ETIMEDOUT`例外 | タイムアウト時に明示的な例外をスロー |
| パイプ破壊 | `OS\BrokenPipeException` | EOF到達時など |
| ファイルロック失敗 | `AlreadyLockedException` | 非ブロッキングロック取得失敗時 |
| ソケットエラー | `OS\ErrnoException` | システムエラー番号を含む例外 |

## セキュリティ要件

### 乱数生成

| 項目 | 仕様 | 備考 |
| --- | --- | --- |
| セキュア乱数生成 | `SecureRandom`名前空間 | 暗号学的に安全な乱数生成器を提供 |
| 疑似乱数生成 | `PseudoRandom`名前空間 | 再現性が必要な場合に使用 |
| 乱数品質保証 | 統計的テスト実施 | 1,000回反復で分布範囲を検証 |

### ファイルシステム

| 項目 | 仕様 | 備考 |
| --- | --- | --- |
| ファイルロック | 共有ロック/排他ロック | `LockType::SHARED`/`LockType::EXCLUSIVE` |
| 一時ファイル | 自動クリーンアップ | `TemporaryFile`クラスがDisposableを実装 |
| ファイルディスクリプタ | 明示的クローズ | `CloseableHandle`インターフェースで管理 |

### 入力検証

| 項目 | 仕様 | 備考 |
| --- | --- | --- |
| 引数検証 | invariant/arg_assert使用 | 不正な引数で即時例外スロー |
| 型安全 | Hack型システム活用 | 静的型チェックで実行前エラー検出 |

## 拡張性要件

### コード構成

| 項目 | 仕様 | 備考 |
| --- | --- | --- |
| モジュール構成 | 名前空間ベース | `HH\Lib\*`以下に機能別に分類 |
| インターフェース設計 | トレイトとインターフェース活用 | 機能の再利用と拡張が容易 |
| ジェネリクス | 型パラメータ対応 | `Semaphore<Tin, Tout>`など |

### 依存関係

| 項目 | 仕様 | 備考 |
| --- | --- | --- |
| 外部依存 | HHVMランタイムのみ | サードパーティライブラリ不要 |
| 内部モジュール依存 | 最小限に設計 | 各モジュールは独立して使用可能 |

## 保守性要件

### コード品質

| 項目 | 仕様 | 備考 |
| --- | --- | --- |
| 型チェッカー | hh_client使用 | CI/CDで自動チェック |
| テストフレームワーク | minitest | 軽量なHack用テストフレームワーク |
| コードスタイル | Hackコーディング規約準拠 | .hhconfigで設定 |

### 設定管理

| 項目 | 設定ファイル | 備考 |
| --- | --- | --- |
| Hack設定 | `.hhconfig` | 言語機能フラグ、許可コード設定 |
| HHVMランタイム設定 | `.hhvmconfig.hdf` | オートロード設定 |
| 開発環境 | `.devcontainer/devcontainer.json` | VS Code Dev Container設定 |

### 許可されたFIXMEコード

| 設定項目 | 許可コード | 備考 |
| --- | --- | --- |
| allowed_decl_fixme_codes | 2053, 4045 | 宣言レベルFIXME |
| allowed_fixme_codes_strict | 2011, 2049, 2050, 2053, 3011, 4005, 4027, 4045, 4053, 4106, 4107, 4108, 4110, 4128, 4135, 4188, 4200, 4240, 4248, 4259, 4297, 4323, 4324, 4387, 4390, 4401 | 厳格モードFIXME |

## 運用・監視要件

### CI/CD

| 項目 | 仕様 | 備考 |
| --- | --- | --- |
| CIプラットフォーム | GitHub Actions | `.github/workflows/build-and-test.yml` |
| テスト実行環境 | Ubuntu + HHVM nightly | 最新HHVMでの動作保証 |
| 定期実行 | 毎日15:42 UTC | cronスケジュール設定 |
| 型チェック | hh_client | ビルド時に実行 |
| テスト実行 | minitest.sh | 全テストスイート実行 |

### テスト戦略

| テスト種別 | 対象 | 備考 |
| --- | --- | --- |
| 単体テスト | 全モジュール | tests/ディレクトリに配置 |
| 境界値テスト | 乱数生成、数値演算 | 極端な値でのテスト実施 |
| 並行処理テスト | Semaphore、Poll | 大量並列実行テスト（最大10,000並列） |
| ロケールテスト | 文字列処理 | 複数ロケール（en_US, fr_FR, tr_TR, da_DK）で検証 |

### ロギング・監視

| 項目 | 仕様 | 備考 |
| --- | --- | --- |
| ロギング機能 | 提供なし | HHVMの標準ログ機能に依存 |
| メトリクス収集 | 提供なし | アプリケーション層で実装が必要 |

## 備考

- 本ライブラリは2021年5月以降、HHVMおよびタイプチェッカーへの組み込みに移行中であり、本リポジトリは主にテストコードを含む
- 本番コードへの貢献は[HHVMリポジトリ](https://github.com/facebook/hhvm/)の`hphp/hsl`サブディレクトリに対して行う必要がある
- ライセンスはMITライセンスに基づく
