# 機能設計書 44-キープアライブ設定

## 概要

本ドキュメントは、libuv の `uv_tcp_keepalive()` および `uv_tcp_keepalive_ex()` APIによりTCPキープアライブオプションを設定する機能の設計を記述する。

### 本機能の処理概要

**業務上の目的・背景**：TCP接続が長時間アイドル状態にある場合、通信相手が依然としてアクティブかどうかを確認する必要がある。TCPキープアライブは、一定時間アイドル後にプローブパケットを送信し、接続の死活監視を行う仕組みである。uv_tcp_keepalive()は基本的なキープアライブ設定（有効/無効とアイドル時間）を提供し、uv_tcp_keepalive_ex()はさらにプローブ間隔とプローブ回数の詳細設定を提供する。

**機能の利用シーン**：長時間接続を維持するサーバーアプリケーション（Webサーバー、データベース接続プール、チャットサーバー等）で、死んだ接続を検出してリソースを解放するために使用される。

**主要な処理内容**：
1. SO_KEEPALIVEソケットオプションの設定（有効/無効）
2. TCP_KEEPIDLE（アイドル時間）の設定
3. TCP_KEEPINTVL（プローブ間隔）の設定（_ex版）
4. TCP_KEEPCNT（プローブ回数）の設定（_ex版）
5. ハンドルフラグ（UV_HANDLE_TCP_KEEPALIVE）の更新
6. プラットフォーム固有の差異吸収（Solaris, macOS, DragonFlyBSD等）

**関連システム・外部連携**：OSのソケットオプション（SO_KEEPALIVE, TCP_KEEPIDLE, TCP_KEEPINTVL, TCP_KEEPCNT, TCP_KEEPALIVE(macOS)）を使用する。

**権限による制御**：特別な権限制御はない。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 18 | TCP | 主機能 | uv_tcp_keepalive()/uv_tcp_keepalive_ex()によるTCPキープアライブのAPI定義 |

## 機能種別

ソケットオプション設定

## 入力仕様

### 入力パラメータ

#### uv_tcp_keepalive()

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| handle | uv_tcp_t* | Yes | 初期化済みTCPハンドル | - |
| enable | int | Yes | 1: キープアライブ有効、0: 無効 | - |
| delay | unsigned int | Yes | アイドル時間（秒）。enable=1時に使用 | enable=1時: >= 1 |

#### uv_tcp_keepalive_ex()

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| handle | uv_tcp_t* | Yes | 初期化済みTCPハンドル | - |
| on | int | Yes | 1: キープアライブ有効、0: 無効 | - |
| idle | unsigned int | Yes | アイドル時間（秒） | on=1時: >= 1 |
| intvl | unsigned int | Yes | プローブ間隔（秒） | on=1時: >= 1 |
| cnt | unsigned int | Yes | プローブ回数 | on=1時: >= 1 |

### 入力データソース

アプリケーションから直接呼び出される。

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| 戻り値 | int | 成功時0、失敗時負のエラーコード |

### 出力先

戻り値として直接返却。

## 処理フロー

### 処理シーケンス

```
1. uv_tcp_keepalive()の場合
   └─ uv_tcp_keepalive_ex(handle, on, idle, 1, 10)を呼び出す（デフォルト値で委譲）
2. ソケット存在チェック
   └─ uv__stream_fd(handle) != -1 の場合、setsockoptを即時実行
3. SO_KEEPALIVE設定
   └─ setsockopt(SOL_SOCKET, SO_KEEPALIVE)
4. キープアライブ有効時のパラメータ設定
   ├─ TCP_KEEPIDLE (Linux) / TCP_KEEPALIVE (macOS)
   ├─ TCP_KEEPINTVL
   └─ TCP_KEEPCNT
5. フラグ更新
   └─ on=1: UV_HANDLE_TCP_KEEPALIVE設定、on=0: フラグクリア
```

### フローチャート

```mermaid
flowchart TD
    A[uv_tcp_keepalive / _ex 呼び出し] --> B{ソケット存在?}
    B -->|Yes| C[uv__tcp_keepalive呼び出し]
    C --> D{成功?}
    D -->|No| E[エラー返却]
    D -->|Yes| F{on?}
    B -->|No| F
    F -->|1| G[UV_HANDLE_TCP_KEEPALIVE設定]
    F -->|0| H[UV_HANDLE_TCP_KEEPALIVEクリア]
    G --> I[0 を返す]
    H --> I
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-44-1 | 簡易API委譲 | uv_tcp_keepalive()はuv_tcp_keepalive_ex(handle, on, idle, 1, 10)に委譲する | uv_tcp_keepalive()呼び出し時 |
| BR-44-2 | パラメータ最小値 | idle, intvl, cntはすべて1以上でなければならない | on=1の場合 |
| BR-44-3 | Solaris最小値制限 | Solarisではidle, intvlの最小値は10秒 | __sun定義時 |
| BR-44-4 | Solaris最大値制限 | Solarisではidle, intvlの最大値は10日（864000秒） | __sun定義時 |
| BR-44-5 | macOS代替オプション | macOSではTCP_KEEPIDLEの代わりにTCP_KEEPALIVEを使用 | TCP_KEEPALIVE定義時 |
| BR-44-6 | ミリ秒変換 | DragonFlyBSD < 500702 および Solaris < 11.4 ではミリ秒単位で設定 | UV_KEEPALIVE_FACTORマクロ |

### 計算ロジック

- Solaris旧バージョン（TCP_KEEPIDLE未定義時）: `time_to_abort = intvl * cnt`（ミリ秒変換後）

## データベース操作仕様

該当なし。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| UV_EINVAL | バリデーションエラー | idle, intvl, cntのいずれかが0 | 1以上の値を指定する |
| UV__ERR(errno) | システムエラー | setsockopt()が失敗した場合 | ソケットの状態を確認する |

### リトライ仕様

リトライは不要。

## トランザクション仕様

該当なし。

## パフォーマンス要件

同期的に即座に完了する軽量な操作。

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

キープアライブパケットは暗号化されないため、ネットワーク上で観測可能。TLS層での対策が別途必要。

## 備考

- uv_tcp_keepalive()はuv_tcp_keepalive_ex()のラッパーであり、intvl=1, cnt=10のデフォルト値を使用する。
- プラットフォームごとのキープアライブ実装の差異は、関数内部で吸収される。
- Solarisの旧バージョンでは指数バックオフアルゴリズムでプローブが送信される。

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | uv.h | `include/uv.h` | uv_tcp_keepalive()（602-604行目）とuv_tcp_keepalive_ex()（605-609行目）のAPI宣言 |

**読解のコツ**: uv_tcp_keepalive()はシンプルなAPI、uv_tcp_keepalive_ex()は拡張版で詳細パラメータを受け付ける。

#### Step 2: エントリーポイントを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | tcp.c | `src/unix/tcp.c` | uv_tcp_keepalive()（591-593行目）。uv_tcp_keepalive_ex()への委譲（intvl=1, cnt=10） |
| 2-2 | tcp.c | `src/unix/tcp.c` | uv_tcp_keepalive_ex()（596-619行目）。フラグ管理とuv__tcp_keepaliveへの委譲 |

**主要処理フロー**:
1. **592行目**: uv_tcp_keepalive_ex(handle, on, idle, 1, 10)に委譲
2. **603-607行目**: ソケット存在時にuv__tcp_keepalive()を呼び出し
3. **609-612行目**: UV_HANDLE_TCP_KEEPALIVEフラグの設定/クリア

#### Step 3: 内部実装を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | tcp.c | `src/unix/tcp.c` | uv__tcp_keepalive()（468-570行目）。プラットフォーム固有のキープアライブ設定 |

**主要処理フロー**:
- **473-474行目**: SO_KEEPALIVE設定
- **476-477行目**: on=0の場合は即return（有効化パラメータ不要）
- **479-480行目**: idle, intvl, cntの最小値チェック（>= 1）
- **506-543行目**: Solaris固有の処理（最小10秒、TCP_KEEPIDLE/TCP_KEEPALIVE_THRESHOLD）
- **547-566行目**: 非Solaris環境（TCP_KEEPIDLE/TCP_KEEPALIVE(macOS)、TCP_KEEPINTVL、TCP_KEEPCNT）

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

```
uv_tcp_keepalive() [src/unix/tcp.c:591]
    │
    └─ uv_tcp_keepalive_ex() [src/unix/tcp.c:596]
           │
           └─ uv__tcp_keepalive() [src/unix/tcp.c:468]
                  │
                  ├─ setsockopt(SO_KEEPALIVE) [OS]
                  ├─ setsockopt(TCP_KEEPIDLE / TCP_KEEPALIVE) [OS]
                  ├─ setsockopt(TCP_KEEPINTVL) [OS]
                  └─ setsockopt(TCP_KEEPCNT) [OS]
```

### データフロー図

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

uv_tcp_t* handle       ──▶  uv_tcp_keepalive_ex()       ──▶  戻り値(0/エラー)
int on                 ──▶  ├ SO_KEEPALIVE設定
unsigned int idle      ──▶  ├ TCP_KEEPIDLE設定
unsigned int intvl     ──▶  ├ TCP_KEEPINTVL設定
unsigned int cnt       ──▶  ├ TCP_KEEPCNT設定
                            └ フラグ更新
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| uv.h | `include/uv.h` | ヘッダー | API宣言 |
| tcp.c (unix) | `src/unix/tcp.c` | ソース | Unix系のキープアライブ設定実装 |
| tcp.c (win) | `src/win/tcp.c` | ソース | Windowsのキープアライブ設定実装 |
