# 通知設計書 10-OS\ConnectionException

## 概要

本ドキュメントは、HH\Lib\OS\ConnectionException クラスによる接続関連エラーの抽象基底クラスとしての通知機能について記載する。

### 本通知の処理概要

OS\ConnectionException は、ネットワーク接続に関連するエラーを通知する例外クラスの抽象基底クラスである。この抽象クラスは直接インスタンス化されることはなく、4つの具象サブクラス（BrokenPipeException、ConnectionAbortedException、ConnectionRefusedException、ConnectionResetException）の共通の親クラスとして機能する。

**業務上の目的・背景**：ネットワークプログラミングにおいて、接続に関する様々なエラーが発生する。これらは原因によって細分化されるが、共通して「接続の問題」として扱うことができる。ConnectionException を基底クラスとして使用することで、すべての接続関連エラーを一括してキャッチすることも、具体的なサブクラスで個別に処理することも可能になる。これにより、柔軟で堅牢なエラーハンドリングが実現できる。

**通知の送信タイミング**：ネットワーク操作（ソケット操作、接続、データ送受信など）が接続関連のエラーで失敗した際に、対応するサブクラスがスローされる。

**通知の受信者**：ネットワーク操作を呼び出したコード（クライアント/サーバーアプリケーション）が受信者となる。

**通知内容の概要**：サブクラスに応じた Errno 値とエラーメッセージが含まれる。基底クラスでのキャッチにより、すべての接続エラーを一括処理可能。

**期待されるアクション**：受信者はエラーの種類に応じて、接続のリトライ、代替サーバーへの接続、ユーザーへのエラー通知などを行う。

## 通知種別

例外通知（接続エラー・抽象基底クラス）

## 送信仕様

### 基本情報

| 項目 | 内容 |
|-----|------|
| 送信方式 | 同期（例外スロー） |
| 優先度 | N/A（例外通知のため） |
| リトライ | サブクラスにより異なる |
| クラス種別 | 抽象クラス（直接インスタンス化不可） |

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

例外は呼び出しスタックを遡って伝播し、ConnectionException または具体的なサブクラスをキャッチする catch ブロックで捕捉される。

## 通知テンプレート

### 例外の場合

| 項目 | 内容 |
|-----|------|
| 例外クラス | HH\Lib\OS\ConnectionException（抽象） |
| 親クラス | HH\Lib\OS\ErrnoException |
| 名前空間 | HH\Lib\OS |

### 例外データ構造

```hack
abstract class ConnectionException extends ErrnoException {
  // ErrnoException から継承
}
```

### サブクラス一覧

| サブクラス | 対応 Errno | 説明 |
|----------|-----------|------|
| BrokenPipeException | EPIPE, ESHUTDOWN | パイプ破損・接続切断 |
| ConnectionAbortedException | ECONNABORTED | 接続が中断された |
| ConnectionRefusedException | ECONNREFUSED | 接続が拒否された |
| ConnectionResetException | ECONNRESET | 接続がリセットされた |

## テンプレート変数

| 変数名 | 説明 | データ取得元 | 必須 |
|--------|------|-------------|-----|
| $errno | Errno 値 | OS からのエラーコード | Yes |
| $message | エラーメッセージ | エラー説明文字列 | Yes |

## 送信トリガー・条件

### トリガー一覧

| トリガー種別 | トリガーイベント | サブクラス | 説明 |
|------------|----------------|-----------|------|
| 接続拒否 | connect() 失敗 | ConnectionRefusedException | サーバーが接続を拒否 |
| 接続リセット | read/write 時 | ConnectionResetException | 相手が接続をリセット |
| 接続中断 | accept() 時 | ConnectionAbortedException | 接続確立前に中断 |
| パイプ破損 | write() 時 | BrokenPipeException | 相手が接続を閉じた |

### 送信抑止条件

| 条件 | 説明 |
|-----|------|
| 正常接続 | 接続が正常に確立・維持されている場合は例外はスローされない |

## 処理フロー

### 送信フロー

```mermaid
flowchart TD
    A[ネットワーク操作] --> B{操作成功?}
    B -->|Yes| C[正常完了]
    B -->|No| D[errno 取得]
    D --> E{errno の種類}
    E -->|ECONNREFUSED| F[ConnectionRefusedException]
    E -->|ECONNRESET| G[ConnectionResetException]
    E -->|ECONNABORTED| H[ConnectionAbortedException]
    E -->|EPIPE/ESHUTDOWN| I[BrokenPipeException]
    F --> J[throw サブクラス例外]
    G --> J
    H --> J
    I --> J
    J --> K{catch の種類}
    K -->|ConnectionException| L[一括処理]
    K -->|具体的サブクラス| M[個別処理]
```

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

該当なし（OS レベルの例外通知のため）

### 参照テーブル一覧

該当なし

### 更新テーブル一覧

該当なし

## エラー処理

### エラーケース一覧

| エラー種別 | 発生条件 | 対処方法 |
|----------|---------|---------|
| ECONNREFUSED | サーバーが起動していない/拒否 | サーバー状態確認、リトライ |
| ECONNRESET | 相手が強制切断 | 再接続を試行 |
| ECONNABORTED | 接続確立中に中断 | 再接続を試行 |
| EPIPE/ESHUTDOWN | 相手が接続を閉じた後の書き込み | 接続終了として処理 |

### リトライ仕様

| 項目 | 内容 |
|-----|------|
| リトライ回数 | 呼び出し側で制御（サブクラスにより推奨値が異なる） |
| リトライ間隔 | 指数バックオフ推奨 |
| リトライ対象エラー | ECONNREFUSED, ECONNRESET, ECONNABORTED（一般的にリトライ可能） |

## 配信設定

### レート制限

該当なし（例外通知のため）

### 配信時間帯

制限なし

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

- 接続エラーメッセージにサーバー情報が含まれる可能性があるため、ユーザーへの表示時は注意
- 大量の接続エラーは DoS 攻撃の兆候の可能性があるため、監視を推奨
- 接続リトライの実装では、無限ループや過剰なリトライを避けるためのタイムアウトを設定

## 備考

- 抽象クラスのため直接インスタンス化は不可能
- ConnectionException をキャッチすることで、すべての接続関連エラーを一括処理可能
- 具体的なエラー内容は getErrno() で取得した Errno 値で判断可能

---

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

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

### 推奨読解順序

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

ConnectionException クラスの抽象構造を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | ErrnoException.php | `src/os/ErrnoException.php` | ConnectionException クラス（108-109行目） |

**読解のコツ**: abstract class として定義されており、直接インスタンス化は不可能。中身は空で、ErrnoException をそのまま継承している。

#### Step 2: サブクラス群を理解する

4つの具象サブクラスの実装を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | ErrnoException.php | `src/os/ErrnoException.php` | BrokenPipeException（111-125行目） |
| 2-2 | ErrnoException.php | `src/os/ErrnoException.php` | ConnectionAbortedException（127-135行目） |
| 2-3 | ErrnoException.php | `src/os/ErrnoException.php` | ConnectionRefusedException（137-145行目） |
| 2-4 | ErrnoException.php | `src/os/ErrnoException.php` | ConnectionResetException（147-155行目） |

**主要処理フロー**:
- **BrokenPipeException**: EPIPE, ESHUTDOWN に対応（複数 Errno）
- **ConnectionAbortedException**: ECONNABORTED に対応（単一 Errno）
- **ConnectionRefusedException**: ECONNREFUSED に対応（単一 Errno）
- **ConnectionResetException**: ECONNRESET に対応（単一 Errno）

#### Step 3: 親クラスとの関係を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | ErrnoException.php | `src/os/ErrnoException.php` | ErrnoException 基底クラス（52-76行目） |

**主要処理フロー**:
- ConnectionException は ErrnoException を継承
- サブクラスは ConnectionException を継承
- getErrno() メソッドはすべてのサブクラスで利用可能

#### Step 4: Errno 値の詳細を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | Errno.php | `src/os/Errno.php` | EPIPE（70行目） |
| 4-2 | Errno.php | `src/os/Errno.php` | ECONNABORTED（146行目） |
| 4-3 | Errno.php | `src/os/Errno.php` | ECONNRESET（147行目） |
| 4-4 | Errno.php | `src/os/Errno.php` | ECONNREFUSED（154行目） |
| 4-5 | Errno.php | `src/os/Errno.php` | ESHUTDOWN（151行目） |

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

```
ネットワーク操作（connect/read/write など）
    |
    +-- [接続エラー発生]
            |
            +-- errno 値を取得
            |
            +-- 適切なサブクラスを選択
            |       |
            |       +-- ECONNREFUSED -> ConnectionRefusedException
            |       +-- ECONNRESET -> ConnectionResetException
            |       +-- ECONNABORTED -> ConnectionAbortedException
            |       +-- EPIPE/ESHUTDOWN -> BrokenPipeException
            |
            +-- throw サブクラス例外
                    |
                    +-- [catch (ConnectionException)] 一括処理
                    |
                    +-- [catch (具体的サブクラス)] 個別処理
```

### データフロー図

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

ネットワーク操作
    |
    v
[接続エラー]
    |
    v
errno ──────────────▶ サブクラス選択 ────────▶ ConnectionException
(ECONNREFUSED等)            │                  のサブクラス
                            v                       │
                   ┌────────────────┐               v
                   │ BrokenPipe    │         throw Exception
                   │ Aborted       │               │
                   │ Refused       │               v
                   │ Reset         │         try-catch で
                   └────────────────┘         ハンドリング
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| ErrnoException.php | `src/os/ErrnoException.php` | ソース | ConnectionException とサブクラスの実装（108-155行目） |
| Errno.php | `src/os/Errno.php` | ソース | EPIPE, ECONNABORTED, ECONNRESET, ECONNREFUSED, ESHUTDOWN の定義 |
