# 機能設計書 59-UDP TTL設定

## 概要

本ドキュメントは、libuvにおけるUDP TTL（Time To Live）設定機能（`uv_udp_set_ttl()`）の設計仕様を記述する。UDPユニキャストパケットのTTL値（IPv4）/ホップリミット（IPv6）を設定する。

### 本機能の処理概要

**業務上の目的・背景**：TTL（Time To Live）はIPパケットがネットワークを通過できるルーター数の上限を指定する。パケットの到達範囲を制御するために使用され、ネットワーク設計やセキュリティポリシーに基づいて適切に設定する必要がある。IPv6ではHop Limitとして同等の機能が提供される。

**機能の利用シーン**：
- ネットワークの到達範囲制限（ローカルネットワーク内に限定等）
- トレースルート機能の実装
- ネットワーク診断ツール
- マルチホップ通信の制御

**主要な処理内容**：
1. TTL値の範囲チェック（1-255）
2. z/OSではIPv4非サポートのチェック
3. プラットフォーム依存の型サイズ処理
4. IP_TTL（IPv4）/ IPV6_UNICAST_HOPS（IPv6）の設定

**関連システム・外部連携**：OSのソケットAPI（setsockopt）。

**権限による制御**：特になし。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 21 | UDP | 主機能 | uv_udp_set_ttl()によるUDPパケットTTL設定のAPI定義 |

## 機能種別

ソケットオプション設定

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| handle | uv_udp_t* | Yes | UDPハンドル | ソケットFDが有効であること |
| ttl | int | Yes | TTL値（ホップ数） | 1-255の範囲 |

### 入力データソース

アプリケーションから直接指定されるTTL値。

## 出力仕様

### 出力データ

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

### 出力先

OSカーネルのソケットオプションが変更される。

## 処理フロー

### 処理シーケンス

```
1. TTL範囲チェック
   └─ ttl < 1 || ttl > 255 → UV_EINVAL
2. z/OSプラットフォーム固有チェック
   └─ IPv4ソケットの場合 → UV_ENOTSUP
3. プラットフォーム依存処理
   ├─ Solaris/AIX/OpenBSD/z/OS/QNX: uv__setsockopt()でsizeof(int)を使用
   └─ その他: uv__setsockopt_maybe_char()で型を自動選択
4. setsockopt(IP_TTL / IPV6_UNICAST_HOPS)
```

### フローチャート

```mermaid
flowchart TD
    A[uv_udp_set_ttl呼び出し] --> B{ttl 1-255範囲内?}
    B -->|No| C[UV_EINVAL]
    B -->|Yes| D{z/OS かつ IPv4?}
    D -->|Yes| E[UV_ENOTSUP]
    D -->|No| F{Solaris/AIX/OpenBSD/z/OS/QNX?}
    F -->|Yes| G[uv__setsockopt sizeof int]
    F -->|No| H[uv__setsockopt_maybe_char]
    G --> I[setsockopt IP_TTL / IPV6_UNICAST_HOPS]
    H --> I
    I -->|成功| J[0返却]
    I -->|失敗| K[エラーコード返却]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-59-01 | TTL範囲 | TTL値は1-255の範囲（マルチキャストTTLと異なり0は不可） | 常時 |
| BR-59-02 | z/OS IPv4非サポート | z/OSではIPv4のTTL設定はサポートされない | z/OS + IPv4 |
| BR-59-03 | IPv4/IPv6自動判定 | UV_HANDLE_IPV6フラグでIP_TTL/IPV6_UNICAST_HOPSを自動選択 | 常時 |
| BR-59-04 | プラットフォーム型差異 | Solaris/AIX等ではsizeof(int)を直接使用 | 該当プラットフォーム |

### 計算ロジック

特になし。

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

該当なし。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| UV_EINVAL | パラメータ不正 | ttlが1-255範囲外 | 1-255の範囲で指定 |
| UV_ENOTSUP | 非サポート | z/OSでIPv4のTTL設定 | IPv6ソケットを使用 |
| UV__ERR(errno) | OS APIエラー | setsockopt失敗 | エラー内容を確認 |

### リトライ仕様

リトライは不要。

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

該当なし。

## パフォーマンス要件

同期処理。setsockopt()の実行時間のみ。

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

- TTLを大きく設定すると、パケットが意図しないネットワークセグメントまで到達する可能性がある
- セキュリティポリシーに基づいて適切なTTL値を設定すること

## 備考

- uv_udp_set_ttl()はユニキャストTTLの設定であり、マルチキャストTTL（uv_udp_set_multicast_ttl）とは異なるソケットオプションを使用する
- IP_TTL vs IP_MULTICAST_TTL、IPV6_UNICAST_HOPS vs IPV6_MULTICAST_HOPS
- TTLの最小値が1（マルチキャストTTLの最小値0と異なる）

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | uv.h | `include/uv.h` | **L775行目**: uv_udp_set_ttl()のAPI宣言 |
| 1-2 | udp.c (unix) | `src/unix/udp.c` | **L1145-1179行目**: uv_udp_set_ttl()の実装 |

**主要処理フロー**:
1. **L1146-1147行目**: TTL範囲チェック（1-255）
2. **L1149-1152行目**: z/OSでIPv4非サポートチェック
3. **L1160-1167行目**: Solaris/AIX/OpenBSD/z/OS/QNX向け - sizeof(int)でsetsockopt
4. **L1172-1175行目**: その他プラットフォーム - uv__setsockopt_maybe_charで設定

**読解のコツ**: マルチキャストTTL（L1182-1204）と比較して読むと、IPv4のオプション名（IP_TTL vs IP_MULTICAST_TTL）とIPv6のオプション名（IPV6_UNICAST_HOPS vs IPV6_MULTICAST_HOPS）の違いが明確になる。TTLの最小値が1であるのに対し、マルチキャストTTLは0も許可される点も異なる。

#### Step 2: ヘルパー関数を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | udp.c (unix) | `src/unix/udp.c` | **L1088-1111行目**: uv__setsockopt() - IPv4/IPv6の自動切り替え |
| 2-2 | udp.c (unix) | `src/unix/udp.c` | **L1113-1129行目**: uv__setsockopt_maybe_char() - 型サイズ自動選択 |

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

```
uv_udp_set_ttl(handle, ttl)
    ├─ [Solaris/AIX/OpenBSD/z/OS/QNX]
    │      └─ uv__setsockopt(handle, IP_TTL, IPV6_UNICAST_HOPS, &ttl, sizeof(ttl))
    │             └─ setsockopt(fd, IPPROTO_IP/IPV6, option, val, size)
    │
    └─ [その他]
           └─ uv__setsockopt_maybe_char(handle, IP_TTL, IPV6_UNICAST_HOPS, ttl)
                  └─ uv__setsockopt(handle, option4, option6, &arg, sizeof(arg))
```

### データフロー図

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

ttl (1-255) ──────▶ uv_udp_set_ttl() ──────▶ setsockopt()
handle                    │                        │
                    範囲チェック             IP_TTL / IPV6_UNICAST_HOPS
                    型変換                   カーネルオプション更新
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| uv.h | `include/uv.h` | ヘッダ | API宣言（L775） |
| udp.c (unix) | `src/unix/udp.c` | ソース | Unix系実装（L1145-1179） |
| udp.c (win) | `src/win/udp.c` | ソース | Windows版実装 |
