# 機能設計書 42-TCP既存ソケットオープン

## 概要

本ドキュメントは、libuv の `uv_tcp_open()` APIにより、既存のOSソケットファイルディスクリプタをuv_tcp_tハンドルに関連付ける機能の設計を記述する。

### 本機能の処理概要

**業務上の目的・背景**：外部ライブラリやシステムコールで既に作成されたソケットをlibuvのイベントループに統合する必要がある場合がある。例えば、accept()で取得したソケットや、他のライブラリで作成されたソケットをlibuvで管理下に置くためにuv_tcp_open()を使用する。これにより既存のネットワークインフラストラクチャとlibuvの非同期I/Oを組み合わせることが可能になる。

**機能の利用シーン**：外部ライブラリとの統合、systemdソケットアクティベーション、inetdスタイルのサーバー、既存ソケットの再利用など、OSが提供するソケットをlibuvハンドルとして扱いたい場面で使用される。

**主要な処理内容**：
1. ループ内のFD重複チェック
2. ソケットのノンブロッキングモード設定
3. uv__stream_open()によるストリームへのFD関連付け（READABLE|WRITABLEフラグ設定）

**関連システム・外部連携**：OSのソケットAPI。外部で作成されたソケットFDを受け取る。

**権限による制御**：特別な権限制御はない。有効なソケットFDを保持していることが前提。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 18 | TCP | 主機能 | uv_tcp_open()による既存OSソケット関連付けのAPI定義 |

## 機能種別

リソース管理（ソケットFD関連付け）

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| handle | uv_tcp_t* | Yes | 初期化済みTCPハンドル | uv_tcp_init()で初期化済みであること |
| sock | uv_os_sock_t | Yes | 既存のOSソケットファイルディスクリプタ | 有効なソケットFD |

### 入力データソース

アプリケーションが外部で取得したソケットFD。

## 出力仕様

### 出力データ

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

### 出力先

戻り値として直接返却。

## 処理フロー

### 処理シーケンス

```
1. FD重複チェック
   └─ uv__fd_exists()でループ内に同一FDが既に登録されていないか確認
2. ノンブロッキング設定
   └─ uv__nonblock(sock, 1)でソケットをノンブロッキングモードに設定
3. ストリームオープン
   └─ uv__stream_open()でFDをストリームハンドルに関連付け（READABLE|WRITABLE）
```

### フローチャート

```mermaid
flowchart TD
    A[uv_tcp_open 呼び出し] --> B{uv__fd_exists?}
    B -->|Yes| C[UV_EEXIST を返す]
    B -->|No| D[uv__nonblock設定]
    D --> E{成功?}
    E -->|No| F[エラー返却]
    E -->|Yes| G[uv__stream_open]
    G --> H[0 を返す]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-42-1 | FD重複禁止 | 同一FDが既にループに登録されている場合はUV_EEXISTを返す | 常時 |
| BR-42-2 | ノンブロッキング必須 | ソケットは自動的にノンブロッキングモードに設定される | 常時 |
| BR-42-3 | 読み書き可能設定 | UV_HANDLE_READABLEとUV_HANDLE_WRITABLEの両方が設定される | 常時 |

### 計算ロジック

特になし。

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

該当なし。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| UV_EEXIST | 重複エラー | 同一FDが既にループに登録済み | 別のFDを使用する |
| UV_EINVAL | バリデーションエラー | ノンブロッキング設定失敗 | 有効なソケットFDを使用する |

### リトライ仕様

リトライは不要。エラー発生時はパラメータを修正して再呼び出し。

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

該当なし。

## パフォーマンス要件

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

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

外部から渡されるFDの妥当性はアプリケーション側で保証する必要がある。

## 備考

- uv_tcp_open()はソケットの所有権をlibuvに移譲する。以降のソケット管理はlibuvが行う。
- ハンドルをクローズする際にFDも自動的にクローズされる。

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | uv.h | `include/uv.h` | uv_tcp_s構造体（592-596行目）とuv_tcp_open()のAPI宣言（600行目） |

**読解のコツ**: uv_os_sock_t型はプラットフォームによってintまたはSOCKETとなる。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | tcp.c | `src/unix/tcp.c` | uv_tcp_open()の実装（352-365行目） |

**主要処理フロー**:
1. **355-356行目**: uv__fd_exists()でFD重複チェック → UV_EEXIST
2. **358-360行目**: uv__nonblock(sock, 1)でノンブロッキング設定
3. **362-364行目**: uv__stream_open()でREADABLE|WRITABLEフラグ付きでストリームオープン

#### Step 3: ストリームオープン処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | stream.c | `src/unix/stream.c` | uv__stream_open()の実装。FDをI/Oウォッチャーに設定し、フラグを更新する |

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

```
uv_tcp_open() [src/unix/tcp.c:352]
    │
    ├─ uv__fd_exists() [src/unix/core.c]
    │
    ├─ uv__nonblock() [src/unix/core.c]
    │
    └─ uv__stream_open() [src/unix/stream.c]
```

### データフロー図

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

uv_tcp_t* handle   ──▶  uv_tcp_open()          ──▶  戻り値(0/エラー)
uv_os_sock_t sock  ──▶  ├ FD重複チェック
                        ├ ノンブロッキング設定
                        └ ストリームオープン
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| uv.h | `include/uv.h` | ヘッダー | uv_tcp_open()のAPI宣言 |
| tcp.c (unix) | `src/unix/tcp.c` | ソース | Unix系のuv_tcp_open()実装 |
| tcp.c (win) | `src/win/tcp.c` | ソース | Windowsのuv_tcp_open()実装 |
| stream.c | `src/unix/stream.c` | ソース | uv__stream_open()によるFD管理 |
| core.c | `src/unix/core.c` | ソース | uv__fd_exists(), uv__nonblock()の実装 |
