# アーキテクチャ設計書

## 概要

本ドキュメントは、Hack Standard Library (HSL) のアーキテクチャ設計を記述する。HSLは、Hackプログラマー向けに一貫性のある、集中管理された、型安全なAPIセットを提供するライブラリである。特にHack配列（`vec`、`keyset`、`dict`）の操作に有用であり、非同期処理、ファイルI/O、ネットワーク通信、文字列操作、数学演算など、幅広い機能を提供する。

## システム全体構成

### アーキテクチャ概要図

[アーキテクチャ構成図](./アーキテクチャ構成図.md) を参照。

### システム境界と外部連携

| 外部システム | 連携方式 | 用途 |
| --- | --- | --- |
| HHVM | ランタイム統合 | Hack言語のランタイム環境として動作 |
| PCRE | ネイティブライブラリ呼び出し | 正規表現処理の実行基盤 |
| OS (POSIX) | システムコール | ファイル操作、ソケット通信、プロセス管理 |

## レイヤー構成

### アーキテクチャスタイル

**モジュラーライブラリアーキテクチャ**

HSLは単一のモノリシックなアプリケーションではなく、機能ごとに分割されたモジュール群として設計されている。各モジュールは独立した名前空間を持ち、特定のドメインの機能を提供する。クリーンアーキテクチャやDDDとは異なり、ライブラリとして汎用的に使用されることを前提とした設計である。

### レイヤー定義

| レイヤー | 責務 | 主なコンポーネント |
| --- | --- | --- |
| Public API | ユーザーに公開される関数・クラスインターフェース | `HH\Lib\Vec`, `HH\Lib\Dict`, `HH\Lib\Str` 等の名前空間 |
| Internal Implementation | 内部実装の詳細、ユーザーから隠蔽 | `HH\Lib\_Private` 名前空間配下のモジュール |
| OS Abstraction | OSシステムコールの抽象化 | `HH\Lib\OS` 名前空間、POSIX互換API |

### レイヤー間の依存関係ルール

- **Public API -> Internal Implementation**: 公開APIは内部実装を参照可能
- **Internal Implementation -> OS Abstraction**: 内部実装はOS抽象化レイヤーを使用
- **禁止される参照**: ユーザーコードから `_Private` 名前空間への直接参照は非推奨

## モジュール構成

### ドメイン分割

| ドメイン | 責務 | 関連モジュール |
| --- | --- | --- |
| Container Operations | Hack配列（vec, dict, keyset）の操作 | `Vec`, `Dict`, `Keyset`, `C` |
| String Processing | 文字列の変換、検索、操作 | `Str`, `Regex`, `Locale` |
| Asynchronous Programming | 非同期処理の制御とユーティリティ | `Async` |
| I/O Operations | ファイル・ストリーム入出力 | `IO`, `File` |
| Network Communication | TCP/Unix ソケット通信 | `TCP`, `Unix`, `Network` |
| System Operations | OS レベルの操作 | `OS` |
| Mathematics | 数学演算 | `Math` |
| Randomness | 乱数生成 | `Random` |
| Legacy Support | レガシーコード互換性 | `LegacyFixme` |

### パッケージ構造

```
src/
├── Ref.php                     # 参照ラッパークラス
├── private.php                 # 内部ユーティリティ関数
├── _Private/                   # 内部共通実装
│   └── OptionalIncrementalTimeout.php
├── async/                      # 非同期処理
│   ├── Semaphore.php
│   ├── Condition.php
│   ├── Poll.php
│   └── ...
├── c/                          # Container共通操作
│   ├── introspect.php
│   ├── select.php
│   ├── order.php
│   └── reduce.php
├── dict/                       # dict操作
│   ├── select.php
│   ├── transform.php
│   ├── combine.php
│   └── ...
├── vec/                        # vec操作
│   ├── select.php
│   ├── transform.php
│   ├── order.php
│   └── ...
├── keyset/                     # keyset操作
│   ├── select.php
│   ├── combine.php
│   └── ...
├── str/                        # 文字列操作
│   ├── transform.php
│   ├── select.php
│   └── ...
├── regex/                      # 正規表現
│   ├── regex.php
│   ├── exception.php
│   └── private.php
├── math/                       # 数学演算
│   ├── compute.php
│   ├── constants.php
│   └── ...
├── random/                     # 乱数生成
├── io/                         # I/O操作
│   ├── Handle.php
│   ├── ReadHandle.php
│   ├── WriteHandle.php
│   ├── BufferedReader.php
│   └── _Private/
├── file/                       # ファイル操作
│   ├── open.php
│   ├── Handle.php
│   ├── TemporaryFile.php
│   └── _Private/
├── network/                    # ネットワーク共通
│   ├── Socket.php
│   ├── Server.php
│   └── _Private/
├── tcp/                        # TCP通信
│   ├── connect.php
│   ├── Server.php
│   └── _Private/
├── unix/                       # Unixソケット通信
│   ├── connect.php
│   ├── Server.php
│   └── _Private/
├── os/                         # OS操作
│   ├── Errno.php
│   ├── socket.php
│   ├── open.php
│   ├── spawn.php
│   └── _Private/
├── locale/                     # ロケール
│   ├── Locale.php
│   └── Category.php
└── legacy_fixme/               # レガシー互換
    ├── coercions.php
    └── str.php
```

### コンポーネント依存関係

主要コンポーネント間の依存関係：

1. **Container操作モジュール間の依存**
   - `Vec` -> `C`, `Dict`, `Keyset`, `_Private`
   - `Dict` -> `C`, `_Private`
   - `Keyset` -> `C`, `_Private`

2. **I/O系モジュールの依存**
   - `File` -> `IO`, `OS`, `_Private\_File`
   - `TCP` -> `Network`, `OS`, `_Private\_TCP`
   - `Unix` -> `OS`, `_Private`

3. **横断的依存**
   - ほぼ全モジュール -> `_Private`（内部ユーティリティ）
   - 文字列関連 -> `Str`, `_Private\_Str`

## ミドルウェア構成

### データベース

HSLはデータベース接続機能を直接提供しない。アプリケーションレベルでの実装が必要。

| 種類 | ミドルウェア | バージョン | 用途 |
| --- | --- | --- | --- |
| - | - | - | HSLは純粋なユーティリティライブラリであり、DB接続は対象外 |

### キャッシュ

| ミドルウェア | バージョン | 用途 | TTL |
| --- | --- | --- | --- |
| - | - | - | HSLはキャッシュ機能を直接提供しない |

### メッセージキュー

| ミドルウェア | バージョン | 用途 |
| --- | --- | --- |
| - | - | HSLはMQ機能を直接提供しない |

### 検索エンジン

| ミドルウェア | バージョン | 用途 |
| --- | --- | --- |
| - | - | HSLは検索エンジン連携を直接提供しない |

### その他ミドルウェア

| ミドルウェア | バージョン | 用途 |
| --- | --- | --- |
| HHVM | - | Hackランタイム環境 |
| PCRE | - | 正規表現エンジン |

## データフロー

### リクエスト処理の流れ

HSLはライブラリであり、リクエスト/レスポンスのフローは持たない。代わりに、典型的な関数呼び出しフローを示す。

**コンテナ操作の例（Vec\filter）**:

1. ユーザーコードが `Vec\filter($traversable, $predicate)` を呼び出し
2. 入力値の検証（traversableの確認）
3. 内部ループで各要素に対してpredicate関数を適用
4. 条件を満たす要素を新しいvecに追加
5. 結果のvecを返却

**ファイル操作の例（File\open_read_only）**:

1. ユーザーコードが `File\open_read_only($path)` を呼び出し
2. `OS\open()` を使用してファイルディスクリプタを取得
3. `CloseableReadHandle` オブジェクトを生成して返却

### 非同期処理の流れ

**Async\Semaphore の使用例**:

1. `new Async\Semaphore($limit, $func)` でセマフォを生成
2. `$semaphore->waitForAsync($input)` を呼び出し
3. 同時実行数が制限内であれば即座に実行
4. 制限を超えている場合は `Condition` で待機
5. 実行完了後、待機中のタスクを起動
6. 結果を返却

### データ永続化の流れ

**File\open_write_only を使用した書き込み**:

1. `File\open_write_only($path, WriteMode::TRUNCATE)` でハンドル取得
2. `$handle->writeAllAsync($data)` でデータ書き込み
3. バッファがフラッシュされ、OSにデータが渡される
4. `$handle->close()` でファイルディスクリプタを解放

## 横断的関心事

### 認証・認可

| 方式 | 実装箇所 | 対象 |
| --- | --- | --- |
| - | - | HSLは認証・認可機能を提供しない |

### ロギング・監査

| 種類 | 実装方式 | 保存先 |
| --- | --- | --- |
| - | - | HSLはロギング機能を直接提供しない |

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

HSLは型安全性とinvariant（不変条件）による堅牢なエラーハンドリングを採用している。

| エラー種別 | ハンドリング方式 | レスポンス |
| --- | --- | --- |
| 引数の不正 | `invariant()` による事前条件チェック | `InvariantException` をスロー |
| OS エラー | `ErrnoException` | 詳細なエラー情報を含む例外 |
| 正規表現エラー | `Regex\Exception` | パターンとエラー詳細を含む例外 |
| ホスト名解決エラー | `HErrnoException` | DNS関連のエラー情報を含む例外 |

### トランザクション管理

| 範囲 | 管理方式 | 分離レベル |
| --- | --- | --- |
| - | - | HSLはトランザクション管理を提供しない |

## 設計原則・コーディング規約

### 適用している設計原則

| 原則 | 適用箇所 | 実装例 |
| --- | --- | --- |
| 純粋関数 | Container操作全般 | `Vec\map`, `Dict\filter` - 副作用なし、入力から出力を決定 |
| イミュータビリティ | Container操作 | 常に新しいコンテナを返却、元データを変更しない |
| 型安全性 | 全モジュール | ジェネリクス、strict型チェック |
| コンテキスト係数 | 多くの関数 | `[ctx $predicate]` による純粋性の伝播 |
| 単一責任 | モジュール設計 | 各モジュールは特定のドメインに特化 |
| Open-Closed | インターフェース設計 | `IO\Handle` 系インターフェースによる拡張性 |

### コーディング規約

- **名前空間**: `HH\Lib\{ModuleName}` 形式を使用
- **内部実装**: `_Private` サブ名前空間に配置
- **関数命名**: スネークケース（`filter_nulls`, `open_read_only`）
- **クラス命名**: パスカルケース（`Semaphore`, `BufferedReader`）
- **ドキュメント**: 各関数に計算量（Time/Space complexity）を記載
- **deprecation**: `<<__Deprecated("...")>>` アトリビュートを使用
- **テスト**: `tests/` ディレクトリに対応するテストを配置

## 備考

- HSLは2021年5月以降、HHVMに組み込まれる形で移行が進んでいる
- 本リポジトリは主にテストコードを含み、実装コードはHHVMリポジトリの `hphp/hsl` サブディレクトリに移行
- 新規の貢献はHHVMリポジトリに対して行う必要がある
- ライセンス: MIT License
