# 画面設計書 35-ネットワーク

## 概要

libuvユーザーガイドのネットワークページ（guide/networking.rst）に関する画面設計書。TCP/UDPネットワークプログラミング、DNS解決、ネットワークインターフェース取得の使い方をサンプルコード付きで解説するページの構造と仕様を定義する。

### 本画面の処理概要

本ページはlibuvのネットワーク機能（TCP: uv_tcp_t、UDP: uv_udp_t）、DNS解決（uv_getaddrinfo）、およびネットワークインターフェース情報取得の実践的な使い方を、複数のサンプルプログラムを通じて解説するガイドページである。

**業務上の目的・背景**：ネットワークプログラミングはlibuvの主要ユースケースの一つであり、TCPエコーサーバーの実装を通じてサーバー開発の基本パターン（bind→listen→accept→read/write）を学習できる。UDPについてはDHCPクライアントのサンプルを用い、コネクションレスなデータグラム通信の特性を理解させる。DNS解決とネットワークインターフェース情報取得のユーティリティ機能も実践例付きで解説される。

**画面へのアクセス方法**：ユーザーガイド一覧（No.31）のtoctreeリンク、またはファイルシステム（No.34）からのNextナビゲーションでアクセスする。URLパスは `/guide/networking.html` となる。

**主要な操作・処理内容**：
1. TCPサーバーの実装パターン（tcp-echo-server/main.c）の表示と解説
2. TCPクライアントの接続パターンの説明
3. UDPソケット操作（udp-dhcp/main.c）の表示と解説
4. UDPオプション（TTL、IPv6 only、マルチキャスト）の説明
5. 非同期DNS解決（dns/main.c）の表示と解説
6. ネットワークインターフェース情報取得（interfaces/main.c）の表示と解説

**画面遷移**：
- 遷移元：ユーザーガイド一覧（No.31）、ファイルシステム（No.34）
- 遷移先：スレッド（No.36）、ファイルシステム（No.34、buffers-and-streamsラベルへの参照）
- 外部リンク：DHCP RFC、マルチキャストHOWTO、getaddrinfo manページ、uv_getnameinfo APIリファレンス

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

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 39 | TCP初期化 | 主機能 | TCPエコーサーバーサンプルでのTCPハンドル初期化 |
| 40 | TCPバインド | 主機能 | TCPサーバーのアドレスバインド処理の使用例 |
| 33 | ストリーム接続待受 | 主機能 | uv_listen()によるサーバー接続待ち受けの使用例 |
| 34 | 接続受入 | 主機能 | uv_accept()による接続受け入れ処理の使用例 |
| 41 | TCP接続 | 補助機能 | TCPクライアント接続の使用例 |
| 30 | ストリーム読み取り開始・停止 | 補助機能 | クライアントからのデータ読み取りの使用例 |
| 31 | ストリーム書き込み | 補助機能 | クライアントへのデータ書き込みの使用例 |
| 48 | UDP初期化 | 主機能 | UDPソケット初期化のサンプル解説 |
| 52 | UDP送信 | 補助機能 | UDPデータグラム送信の使用例 |
| 54 | UDP受信開始・停止 | 補助機能 | UDPデータグラム受信の使用例 |

## 画面種別

チュートリアル（サンプルコード付き解説）

## URL/ルーティング

- ソースファイル：`docs/src/guide/networking.rst`
- 生成先URL：`/guide/networking.html`
- Sphinxルーティング：guide.rstのtoctreeから参照

## 入出力項目

| 項目名 | 入出力 | 型 | 説明 |
|--------|--------|-----|------|
| TCP概要 | 出力 | テキスト | TCP接続指向プロトコルの説明 |
| tcp-echo-server/main.cコード | 出力 | Cソースコード | TCPエコーサーバー（部分表示、ハイライト付き） |
| TCPクライアントコード | 出力 | Cコードブロック | uv_tcp_connect使用例（インラインコード） |
| udp-dhcp/main.cコード | 出力 | Cソースコード | DHCP Discoverサンプル（部分表示） |
| dns/main.cコード | 出力 | Cソースコード | DNS解決サンプル（部分表示、ハイライト付き） |
| interfaces/main.cコード | 出力 | Cソースコード | インターフェース一覧表示（ハイライト付き） |

## 表示項目

| 項目名 | 表示内容 | 備考 |
|--------|----------|------|
| セクションタイトル | "Networking" | ページ見出し（h1） |
| NOTEボックス | コードサンプルの品質に関する注記 | メモリリーク・接続クローズ漏れの注意 |
| TCP (h2) | TCP通信の解説 | Server / Client サブセクション |
| Server (h3) | TCPサーバーの5ステップ実装手順 | tcp-echo-server/main.c |
| Client (h3) | TCPクライアントの接続手順 | uv_tcp_connect使用例 |
| UDP (h2) | UDP通信の解説 | DHCP Discoverサンプル |
| UDP Options (h3) | TTL / IPv6 only / Multicast | 各オプションの説明 |
| Querying DNS (h2) | 非同期DNS解決 | dns/main.c |
| Network interfaces (h2) | インターフェース情報取得 | interfaces/main.c |
| NOTEボックス | IPv6のip6_*関数に関する注記 | TCPセクション |
| NOTEボックス | udp-dhcpのroot実行要件 | UDPセクション |
| NOTEボックス | IPアドレス "0.0.0.0" / "255.255.255.255" の説明 | UDPセクション |

## イベント仕様

### 1-TCPサーバーの処理フロー

tcp-echo-server/main.cで示される5ステップ：
1. uv_tcp_init -- TCPハンドル初期化
2. uv_tcp_bind -- アドレスバインド
3. uv_listen -- 接続待ち受け開始（on_new_connectionコールバック設定）
4. uv_accept -- 新規接続受入
5. uv_read_start / uv_write -- データ読み書き

### 2-外部リンク遷移

DHCP RFC、マルチキャストHOWTO、getaddrinfo manページなどへのリンク遷移。

## データベース更新仕様

### 操作別データベース影響一覧

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| - | - | - | 静的HTMLページのため該当なし |

## メッセージ仕様

| メッセージID | 種別 | メッセージ内容 | 表示条件 |
|-------------|------|--------------|---------|
| N-35-01 | 注記 | "The code samples in this chapter exist to show certain libuv APIs..." | ページ冒頭 |
| N-35-02 | 注記 | "There are uv_ip6_* analogues for the ip4 functions." | TCPセクション |
| N-35-03 | 注記 | "You will have to run udp-dhcp as root..." | UDPセクション |
| N-35-04 | 注記 | "The IP address 0.0.0.0 is used to bind to all interfaces..." | UDPセクション |

## 例外処理

静的HTMLページのため、アプリケーションレベルの例外処理は発生しない。

## 備考

- TCPサーバーのサンプルではDEFAULT_PORT=7000、DEFAULT_BACKLOG=128が設定されている。
- UDPサンプルではDHCP Discoverメッセージの構築が含まれるが、ドキュメントでは詳細な解説は省略されている。
- `c-ares` ライブラリへの言及があり、libuv v0.9.0以前にはDNS解決の代替として使用されていたが削除された経緯が脚注に記載されている。
- 脚注として3つの補足情報（ブロードキャストパケット、マルチキャストループバック、getaddrinfoの実装）が含まれる。

---

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

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

### 推奨読解順序

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

TCP/UDPで使用されるハンドル型とリクエスト型を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | networking.rst | `docs/src/guide/networking.rst` | 行1-10: uv_tcp_tとuv_udp_tの位置づけ |
| 1-2 | tcp-echo-server/main.c | `docs/code/tcp-echo-server/main.c` | 行9-15: グローバル変数（uv_loop_t, sockaddr_in, write_req_t構造体） |

**読解のコツ**: TCPはコネクション指向のストリームプロトコルでuv_stream_t基盤を利用する。UDPはコネクションレスでuv_udp_send_tリクエストを使用する。write_req_t構造体はuv_write_tとuv_buf_tを組み合わせたアプリケーション定義の構造体である。

#### Step 2: TCPエコーサーバーの処理フローを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | tcp-echo-server/main.c | `docs/code/tcp-echo-server/main.c` | 行72-87: main関数 -- サーバー初期化とリスン開始 |
| 2-2 | tcp-echo-server/main.c | `docs/code/tcp-echo-server/main.c` | 行55-70: on_new_connection -- クライアント受入とread開始 |
| 2-3 | tcp-echo-server/main.c | `docs/code/tcp-echo-server/main.c` | 行39-53: echo_read -- データ読み取りとエコー書き込み |
| 2-4 | tcp-echo-server/main.c | `docs/code/tcp-echo-server/main.c` | 行32-37: echo_write -- 書き込み完了時のクリーンアップ |

**主要処理フロー**:
1. **行75-76**: `uv_tcp_init(loop, &server)` -- TCPハンドル初期化
2. **行78**: `uv_ip4_addr("0.0.0.0", DEFAULT_PORT, &addr)` -- アドレス構造体設定
3. **行80**: `uv_tcp_bind(&server, (const struct sockaddr*)&addr, 0)` -- バインド
4. **行81**: `uv_listen((uv_stream_t*)&server, DEFAULT_BACKLOG, on_new_connection)` -- リスン開始
5. **行62-63**: `uv_tcp_init / uv_accept` -- 新規クライアント受入
6. **行65**: `uv_read_start` -- データ読み取り開始
7. **行43**: `uv_write` -- エコー書き込み

#### Step 3: DNS解決の処理フローを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | dns/main.c | `docs/code/dns/main.c` | 行61以降: main関数 -- uv_getaddrinfo呼び出し |
| 3-2 | dns/main.c | `docs/code/dns/main.c` | 行42-60: on_resolved -- アドレス情報からTCP接続 |

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

```
tcp-echo-server/main.c
    |
    +-- uv_tcp_init(loop, &server)
    +-- uv_ip4_addr("0.0.0.0", 7000, &addr)
    +-- uv_tcp_bind(&server, &addr, 0)
    +-- uv_listen(&server, 128, on_new_connection)
    |       +-- on_new_connection() [コールバック]
    |               +-- uv_tcp_init(loop, client)
    |               +-- uv_accept(server, client)
    |               +-- uv_read_start(client, alloc_buffer, echo_read)
    |                       +-- echo_read() [コールバック]
    |                               +-- [nread > 0] uv_write(req, client, &buf, echo_write)
    |                               +-- [nread < 0] uv_close(client, on_close)
    +-- uv_run(loop, UV_RUN_DEFAULT)

dns/main.c
    |
    +-- uv_getaddrinfo(loop, &resolver, on_resolved, hostname, ...)
    |       +-- on_resolved() [コールバック]
    |               +-- uv_tcp_init()
    |               +-- uv_tcp_connect()
    |               +-- uv_freeaddrinfo()
    +-- uv_run(loop, UV_RUN_DEFAULT)
```

### データフロー図

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

クライアント接続要求      --> uv_listen() / uv_accept()   --> クライアントハンドル
クライアントデータ        --> uv_read_start()              --> バッファ読み取り
バッファデータ            --> uv_write()                   --> エコーバック
ホスト名                  --> uv_getaddrinfo()             --> sockaddr構造体
sockaddr                  --> uv_tcp_connect()             --> TCP接続
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| networking.rst | `docs/src/guide/networking.rst` | テンプレート | ネットワークガイドページ本体 |
| guide.rst | `docs/src/guide.rst` | テンプレート | 親ページ（toctreeで参照） |
| tcp-echo-server/main.c | `docs/code/tcp-echo-server/main.c` | ソース | TCPエコーサーバーサンプル |
| udp-dhcp/main.c | `docs/code/udp-dhcp/main.c` | ソース | UDP DHCPサンプル |
| dns/main.c | `docs/code/dns/main.c` | ソース | DNS解決サンプル |
| interfaces/main.c | `docs/code/interfaces/main.c` | ソース | インターフェース情報取得サンプル |
| conf.py | `docs/src/conf.py` | 設定 | Sphinxビルド設定 |
