# 通知設計書 22-HErrnoException

## 概要

本ドキュメントは、HH\Lib\OS\HErrnoException クラスの設計仕様を定義する。HErrnoExceptionは、C言語のh_errno変数で報告されるホストネームリゾルバエラーを通知するための例外クラスである。

### 本通知の処理概要

HErrnoExceptionは、DNS名前解決やホスト検索などのネットワーク関連操作で発生するエラーを呼び出し元に通知するための例外クラスである。h_errnoはerrnoとは別のエラー報告機構であり、主にgetaddrinfo、gethostbynameなどの関数で使用される。

**業務上の目的・背景**：ネットワークプログラミングにおいて、ホスト名の解決は頻繁に行われる操作である。DNSサーバーの障害、ホスト名の不存在、一時的なネットワーク問題などの状況を適切に通知し、アプリケーションが適切なエラーハンドリングを行えるようにすることが目的である。h_errnoはerrnoとは異なる名前空間のエラーコードを持つため、専用の例外クラスが必要となる。

**通知の送信タイミング**：HErrnoExceptionは以下のような状況でスローされる：
- ホスト名がDNSで見つからない場合（HOST_NOT_FOUND）
- DNSサーバーが一時的に応答しない場合（TRY_AGAIN）
- DNSサーバーから回復不能なエラーが返された場合（NO_RECOVERY）
- ホスト名に対応するデータ（Aレコード等）が存在しない場合（NO_DATA）

**通知の受信者**：例外をキャッチする呼び出し元コード（アプリケーション層）が受信者となる。開発者はcatch文でHErrnoExceptionを捕捉し、適切な処理を行う。

**通知内容の概要**：例外メッセージとしてエラーの詳細説明が含まれる。getHErrno()メソッドでHErrno列挙型の値（HOST_NOT_FOUND、TRY_AGAIN、NO_RECOVERY、NO_DATA）を取得可能。

**期待されるアクション**：
- TRY_AGAINの場合：一定時間後にリトライ
- HOST_NOT_FOUNDの場合：ホスト名の確認、ユーザーへのエラー通知
- NO_RECOVERYの場合：DNSサーバー設定の確認、管理者への通知
- NO_DATAの場合：別のレコードタイプでの再試行、エラー通知

## 通知種別

例外（Exception） - プログラム実行時のエラー通知

## 送信仕様

### 基本情報

| 項目 | 内容 |
|-----|------|
| 送信方式 | 同期（throw文による例外スロー） |
| 優先度 | 高（処理を中断） |
| リトライ | TRY_AGAINの場合は推奨、その他はケースバイケース |

### 送信先決定ロジック

例外はコールスタックを遡って伝播し、最初にマッチするcatchブロックで捕捉される。捕捉されない場合はプログラムが異常終了する。

## 通知テンプレート

### 例外メッセージ形式

| 項目 | 内容 |
|-----|------|
| フォーマット | エラー詳細メッセージ（呼び出し元から渡される） |
| 例 | `Host not found: example.invalid` |

### 本文テンプレート

```
{error_message}
```

### 添付ファイル

なし（例外オブジェクトとしてスタックトレースを含む）

## テンプレート変数

| 変数名 | 説明 | データ取得元 | 必須 |
|--------|------|-------------|-----|
| h_errno | ホストエラー番号 | OS\HErrno列挙型 | Yes |
| message | エラーメッセージ | 呼び出し元から渡される | Yes |

## 送信トリガー・条件

### トリガー一覧

| トリガー種別 | トリガーイベント | 送信条件 | 説明 |
|------------|----------------|---------|------|
| システム呼び出し | ホスト名解決 | HOST_NOT_FOUND | ホストが見つからない |
| システム呼び出し | DNS問い合わせ | TRY_AGAIN | 一時的なDNSエラー |
| システム呼び出し | DNS問い合わせ | NO_RECOVERY | 回復不能なDNSエラー |
| システム呼び出し | DNS問い合わせ | NO_DATA | 対応するデータなし |

### 送信抑止条件

| 条件 | 説明 |
|-----|------|
| 正常解決 | ホスト名が正常に解決された場合 |

## 処理フロー

### 送信フロー

```mermaid
flowchart TD
    A[ホスト名解決要求] --> B[DNS問い合わせ]
    B --> C{解決成功?}
    C -->|Yes| D[IPアドレス返却]
    C -->|No| E[h_errno取得]
    E --> F[HErrnoException生成]
    F --> G[例外スロー]
    G --> H[呼び出し元でキャッチ]
```

## データベース参照・更新仕様

### 参照テーブル一覧

なし（例外クラスはデータベースを参照しない）

### 更新テーブル一覧

なし（例外クラスはデータベースを更新しない）

## エラー処理

### エラーケース一覧

| エラー種別 | 発生条件 | 対処方法 |
|----------|---------|---------|
| HOST_NOT_FOUND | ホストが存在しない | ホスト名確認、ユーザー通知 |
| TRY_AGAIN | 一時的DNS障害 | リトライ |
| NO_RECOVERY | 回復不能エラー | 管理者通知 |
| NO_DATA | データ不在 | 別アプローチ検討 |

### リトライ仕様

| 項目 | 内容 |
|-----|------|
| リトライ回数 | TRY_AGAINの場合：3回程度推奨 |
| リトライ間隔 | 指数バックオフ（1秒、2秒、4秒等） |
| リトライ対象エラー | TRY_AGAIN |

## 配信設定

### レート制限

なし（例外の発生頻度に制限なし）

### 配信時間帯

なし（例外は発生時即座にスロー）

## セキュリティ考慮事項

- 例外メッセージに機密情報（内部ホスト名等）を含めない
- DNSエラー情報の過度な露出を避ける
- 本番環境では詳細なエラー情報をユーザーに表示しない

## 備考

- HErrnoExceptionはOS\ErrnoExceptionとは独立したクラス（継承関係なし）
- h_errnoはerrnoとは別のエラー報告機構であり、netdb.hで定義される
- NO_ADDRESSはLinuxではNO_DATAのエイリアス、macOSでは未定義

---

## コードリーディングガイド

本通知を理解するために参照すべきファイルと、推奨する読み解き順序を以下に示す。

### 推奨読解順序

#### Step 1: データ構造を理解する

まず、HErrno列挙型の構造を理解することが重要。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | HErrno.php | `src/os/HErrno.php` | HErrno列挙型の定義、4つの値（行22-27） |

**読解のコツ**: HErrnoはerrnoとは別の列挙型である。netdb.hで定義される標準的なホストエラーコードに対応。

#### Step 2: 例外クラスを理解する

HErrnoExceptionクラスの構造を確認。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | HErrnoException.php | `src/os/HErrnoException.php` | HErrnoExceptionクラスの定義（行20-28） |

**主要処理フロー**:
1. **行20**: finalクラスとして定義、\Exceptionを直接継承
2. **行21-23**: コンストラクタでHErrnoとメッセージを受け取る
3. **行25-27**: getHErrno()メソッドでエラーコード取得

#### Step 3: 設計思想を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | README.md | `src/os/README.md` | h_errnoの設計方針（行50-52） |

**主要処理フロー**:
- **行50-52**: h_errnoで報告されるエラーはerrnoとは別に扱い、専用の例外クラスを用意する設計方針

### プログラム呼び出し階層図

```
アプリケーションコード
    │
    ├─ ネットワーク操作（ホスト名解決等）
    │      │
    │      └─ OSレベルAPI呼び出し
    │             │
    │             ├─ 成功：IPアドレス返却
    │             │
    │             └─ 失敗：h_errno設定
    │                    │
    │                    └─ HErrnoException生成・スロー
    │                           │
    │                           └─ 呼び出し元でcatch
```

### データフロー図

```
[入力]                 [処理]                      [出力]

ホスト名 ───▶ DNS問い合わせ ───▶ 成功：IPアドレス
                    │
                    └─▶ 失敗：h_errno取得
                           │
                           ▼
                    HErrnoException生成
                           │
                           ▼
                    例外スロー ───▶ 呼び出し元でcatch
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| HErrnoException.php | `src/os/HErrnoException.php` | ソース | HErrnoExceptionクラス定義 |
| HErrno.php | `src/os/HErrno.php` | ソース | HErrno列挙型定義（HOST_NOT_FOUND等） |
| README.md | `src/os/README.md` | ドキュメント | 設計方針・ガイドライン |
| socket_connect_async.php | `src/network/_Private/socket_connect_async.php` | ソース | h_errnoの使用箇所（行21コメント参照） |
