# 機能設計書 51-HTTP通信

## 概要

本ドキュメントは、NushellにおけるHTTP通信機能の設計仕様を記載する。この機能は、HTTP GET、POST、PUT、DELETE、PATCH、HEAD、OPTIONSの各メソッドによるRESTful API通信を提供する。

### 本機能の処理概要

HTTP通信機能は、Nushellからネットワーク上のリソースにアクセスし、Webサービスやリモートサーバーとのデータ交換を実現する。

**業務上の目的・背景**：現代のシステム運用・開発において、REST APIやWebサービスとの連携は必須である。シェル環境からcurlやwgetの代替として、Nushellの構造化データ処理と統合されたHTTPクライアント機能を提供することで、APIレスポンスの効率的な処理・加工を可能にする。

**機能の利用シーン**：
- REST APIからデータを取得してNushellで分析・加工する
- マイクロサービス間の通信テスト
- Webサービスへのデータ送信（フォーム送信、JSONデータ投稿）
- ファイルのダウンロード・アップロード
- API認証を伴うリクエストの実行

**主要な処理内容**：
1. HTTPリクエストの構築（URL解析、ヘッダー設定、認証情報付与）
2. ureqライブラリを使用したHTTPリクエストの送信
3. レスポンスの受信とコンテンツタイプに基づく自動変換
4. エラーハンドリングとタイムアウト管理
5. リダイレクト処理（follow/manual/error モード）

**関連システム・外部連携**：
- 外部HTTPサーバー・APIエンドポイント
- プロキシサーバー（HTTP_PROXY、HTTPS_PROXY環境変数対応）
- Unix Domain Socket（Dockerデーモンなどとの通信）

**権限による制御**：特になし（ネットワークアクセス権限はOS側で制御）

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | - | - | CLI専用コマンド |

## 機能種別

データ連携 / API通信

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| URL | String | Yes | リクエスト先のURL | 有効なURL形式（httpまたはhttps） |
| data | Any | No（POSTの場合条件付き必須） | リクエストボディ | 型に応じてJSON/Form/Multipart形式に変換 |
| --user, -u | String | No | Basic認証のユーザー名 | - |
| --password, -p | String | No | Basic認証のパスワード | - |
| --max-time, -m | Duration | No | タイムアウト時間 | 正の整数 |
| --headers, -H | Record/List | No | カスタムヘッダー | キー・値のペア形式 |
| --content-type, -t | String | No | Content-Typeヘッダー | MIMEタイプ形式 |
| --raw, -r | Switch | No | レスポンスをテキストとして取得 | - |
| --insecure, -k | Switch | No | SSL証明書検証をスキップ | - |
| --full, -f | Switch | No | 完全なレスポンス情報を取得 | - |
| --allow-errors, -e | Switch | No | エラーコードでも失敗しない | - |
| --redirect-mode, -R | String | No | リダイレクト処理モード | follow/manual/error |
| --unix-socket, -U | Filepath | No | Unix Domain Socket パス | 有効なファイルパス |

### 入力データソース

コマンドライン引数、パイプライン入力（リクエストボディとして）

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| body | Any | レスポンスボディ（Content-Typeに応じて自動変換） |
| status | Int | HTTPステータスコード（--full時） |
| headers | List | レスポンスヘッダー（--full時） |
| urls | List | リダイレクト履歴（--full時） |

### 出力先

パイプライン出力、標準出力

## 処理フロー

### 処理シーケンス

```
1. URL解析
   └─ http_parse_url()でURLを検証・正規化
2. HTTPクライアント初期化
   └─ http_client()またはhttp_client_pool()でクライアント生成
3. リクエスト構築
   └─ タイムアウト、認証、カスタムヘッダーの設定
4. リクエスト送信
   └─ send_request_no_body()またはsend_request()で送信
5. レスポンス処理
   └─ request_handle_response()でレスポンスを処理
6. コンテンツ変換
   └─ Content-Typeに基づき適切な形式に変換
7. 結果返却
   └─ PipelineDataとして返却
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B[URL解析]
    B --> C{URL有効?}
    C -->|No| D[エラー返却]
    C -->|Yes| E[HTTPクライアント初期化]
    E --> F[リクエスト構築]
    F --> G{メソッド}
    G -->|GET/HEAD/DELETE/OPTIONS| H[ボディなし送信]
    G -->|POST/PUT/PATCH| I[ボディ付き送信]
    H --> J[レスポンス受信]
    I --> J
    J --> K{成功?}
    K -->|No| L{allow-errors?}
    L -->|Yes| M[エラーレスポンス返却]
    L -->|No| D
    K -->|Yes| N{--full?}
    M --> O[終了]
    N -->|Yes| P[完全レスポンス構築]
    N -->|No| Q[ボディのみ返却]
    P --> O
    Q --> O
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-01 | URL自動補完 | スキームなしURLにはhttp://を付与 | URLがスキームで始まらない場合 |
| BR-02 | ポート省略 | :で始まるURLはlocalhost扱い | :8080形式の場合 |
| BR-03 | Content-Type自動判定 | ボディ型に応じてJSON/Form/Multipartを判定 | POSTリクエスト時 |
| BR-04 | リダイレクト追従 | デフォルトでリダイレクトを自動追従 | redirect-mode未指定時 |

### 計算ロジック

特になし

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

該当なし（外部HTTP通信のみ）

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| NetworkFailure | 接続エラー | サーバーに接続できない | URLとネットワーク接続を確認 |
| Timeout | タイムアウト | 指定時間内に応答なし | タイムアウト値の調整 |
| UnsupportedInput | 入力エラー | 無効なURL形式 | URL形式の修正 |
| TypeMismatch | 型エラー | ボディ型とContent-Type不一致 | 適切な型に変換 |
| DNSError | DNS解決エラー | ホスト名解決失敗 | ホスト名・DNS設定確認 |

### リトライ仕様

リトライ機能は実装されていない。必要な場合はユーザーが明示的にループ処理を行う。

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

該当なし

## パフォーマンス要件

- デフォルトタイムアウト: ureqライブラリのデフォルト（約30秒）
- 接続プール: `--pool`フラグで共有クライアントを使用可能
- ストリーミング: 大容量レスポンスはByteStreamとして処理

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

- SSL/TLS: デフォルトで証明書検証を実施
- `--insecure`オプション: 証明書検証スキップ（本番環境では非推奨）
- Basic認証: Base64エンコードで送信（HTTPSの使用を推奨）
- プロキシ設定: 環境変数から自動取得（http_proxy, https_proxy）

## 備考

- User-Agentは「nushell」固定
- Content-Typeに応じて自動的にfrom json/from xml等の変換コマンドを適用

---

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

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

### 推奨読解順序

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

まず、HTTPリクエスト・レスポンスの処理に使用されるデータ構造を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | client.rs | `crates/nu-command/src/network/http/client.rs` | RedirectMode、BodyType、RequestFlags等の列挙型・構造体を理解 |

**読解のコツ**:
- **63-81行目**: BodyTypeの定義とContent-Typeからの変換ロジック
- **97-106行目**: RedirectModeの3つのモード（Follow/Error/Manual）
- **957-961行目**: RequestFlagsの構造

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

処理の起点となるhttpコマンドの実装を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | http_.rs | `crates/nu-command/src/network/http/http_.rs` | httpコマンドのシグネチャと振り分けロジック |
| 2-2 | get.rs | `crates/nu-command/src/network/http/get.rs` | http getコマンドの実装 |

**主要処理フロー（http_.rs）**:
- **115-152行目**: run()メソッドでURLとデータの有無に応じてGET/POSTを振り分け
- **141-143行目**: URL有り・data有りでPOST、URL有り・data無しでGET

**主要処理フロー（get.rs）**:
- **169-190行目**: run_get()で引数を解析
- **194-250行目**: helper()でリクエスト構築・送信・レスポンス処理

#### Step 3: リクエスト送信処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | client.rs | `crates/nu-command/src/network/http/client.rs` | HTTPクライアント生成とリクエスト処理 |

**主要処理フロー**:
- **188-237行目**: http_client()でureq::Agentを生成
- **239-265行目**: http_parse_url()でURL検証・正規化
- **353-384行目**: request_add_authorization_header()でBasic認証ヘッダー追加
- **405-427行目**: send_request_no_body()でボディなしリクエスト送信
- **679-714行目**: send_cancellable_request()でキャンセル可能なリクエスト送信

#### Step 4: レスポンス処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | client.rs | `crates/nu-command/src/network/http/client.rs` | レスポンス処理とデータ変換 |

**主要処理フロー**:
- **279-318行目**: response_to_buffer()でレスポンスをByteStreamに変換
- **963-1016行目**: transform_response_using_content_type()でContent-Typeに基づく変換
- **1063-1141行目**: request_handle_response()でレスポンス全体の処理

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

```
http / http get / http post 等
    │
    ├─ http_parse_url()
    │      └─ URL検証・正規化
    │
    ├─ http_client() / http_client_pool()
    │      ├─ tls_config() - TLS設定
    │      ├─ InterruptibleTcpConnector - 接続管理
    │      └─ DnsLookupResolver - DNS解決
    │
    ├─ request_set_timeout()
    ├─ request_add_authorization_header()
    ├─ request_add_custom_headers()
    │
    ├─ send_request_no_body() / send_request()
    │      └─ send_cancellable_request()
    │             └─ スレッドでリクエスト実行
    │
    └─ request_handle_response()
           ├─ handle_response_status()
           ├─ response_to_buffer()
           └─ transform_response_using_content_type()
```

### データフロー図

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

URL + Options ──────────▶ http_parse_url() ────────────▶ Validated URL
                         http_client() ─────────────────▶ ureq::Agent
Headers/Auth ───────────▶ request_add_*() ─────────────▶ RequestBuilder
Body (POST等) ──────────▶ send_request() ──────────────▶ HTTP Response
HTTP Response ──────────▶ response_to_buffer() ────────▶ ByteStream
ByteStream ─────────────▶ transform_response_*() ──────▶ Value (JSON/Table等)
                         request_handle_response() ────▶ PipelineData
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| mod.rs | `crates/nu-command/src/network/http/mod.rs` | ソース | モジュール定義 |
| http_.rs | `crates/nu-command/src/network/http/http_.rs` | ソース | httpコマンドの実装 |
| get.rs | `crates/nu-command/src/network/http/get.rs` | ソース | http getコマンド |
| post.rs | `crates/nu-command/src/network/http/post.rs` | ソース | http postコマンド |
| put.rs | `crates/nu-command/src/network/http/put.rs` | ソース | http putコマンド |
| patch.rs | `crates/nu-command/src/network/http/patch.rs` | ソース | http patchコマンド |
| delete.rs | `crates/nu-command/src/network/http/delete.rs` | ソース | http deleteコマンド |
| head.rs | `crates/nu-command/src/network/http/head.rs` | ソース | http headコマンド |
| options.rs | `crates/nu-command/src/network/http/options.rs` | ソース | http optionsコマンド |
| client.rs | `crates/nu-command/src/network/http/client.rs` | ソース | HTTPクライアント共通処理 |
| pool.rs | `crates/nu-command/src/network/http/pool.rs` | ソース | 接続プール管理 |
| resolver.rs | `crates/nu-command/src/network/http/resolver.rs` | ソース | DNS解決 |
| interruptible_tcp.rs | `crates/nu-command/src/network/http/interruptible_tcp.rs` | ソース | 中断可能なTCP接続 |
| interruptible_unix.rs | `crates/nu-command/src/network/http/interruptible_unix.rs` | ソース | Unix Socket接続 |
