# 機能設計書 80-接続の再起動

## 概要

本ドキュメントは、Windows Terminalにおける接続再起動機能の設計を記述する。切断されたターミナル接続を、同一のプロファイル設定で新規接続として再起動する機能である。

### 本機能の処理概要

RestartConnectionアクションは、現在のペインに関連付けられた接続を、元のプロファイル設定に基づいて新しい接続として再作成・起動する機能である。プロセスがクラッシュした場合や接続が切断された場合に、手動でタブを閉じて再作成することなく、同じ設定で接続を復元できる。

**業務上の目的・背景**：ターミナルセッションが予期せず終了した場合（プロセスクラッシュ、ネットワーク切断等）に、同じ設定で素早くセッションを復元したいという要求に応える。新しいタブを作成する手間を省き、作業の継続性を確保する。

**機能の利用シーン**：シェルプロセスがクラッシュした場合、SSH接続が切断された場合、Azure Cloud Shellの接続が失われた場合、TermControlのRestartTerminalRequestedイベントによる自動再起動時に利用される。

**主要な処理内容**：
1. RestartConnectionアクションの受信
2. アクティブペインからTerminalPaneContentの取得
3. _duplicateConnectionForRestartによる新規接続の作成
4. 元の接続を新しい接続に置き換え
5. 新しい接続のStart()呼び出し

**関連システム・外部連携**：ConptyConnection（ローカルシェル接続）、AzureConnection（Azure Cloud Shell接続）、プロファイル設定との連携。

**権限による制御**：特になし。元の接続と同じ権限レベルで再起動される。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 1 | TerminalPage（メイン画面） | 主画面 | _HandleRestartConnectionにより接続を再起動 |
| 6 | TermControl（ターミナル表示） | 関連画面 | ターミナル接続の再起動処理 |
| 19 | ControlNoticeDialog（通知） | 補助画面 | 接続切断等のコントロール通知メッセージを表示 |

## 機能種別

接続管理 / プロセス制御

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| なし | - | - | RestartConnectionアクションにはパラメータなし | - |

### 入力データソース

キーバインド、コマンドパレット、またはTermControlのRestartTerminalRequestedイベントからの呼び出し。

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| ITerminalConnection | ITerminalConnection | 新しく作成されたターミナル接続 |

### 出力先

TermControl のConnection プロパティ（既存接続の置き換え）

## 処理フロー

### 処理シーケンス

```
1. RestartConnectionアクション受信
   └─ _HandleRestartConnectionハンドラが呼び出される
2. アクティブタブ・ペインの取得
   └─ _senderOrFocusedTab → GetActivePane → GetContent
3. TerminalPaneContent の取得
   └─ try_as<TerminalPaneContent> でキャスト
4. _restartPaneConnection の呼び出し
   └─ paneContent と nullptr（引数なし）を渡す
5. _duplicateConnectionForRestart の実行
   ├─ TermControl からプロファイル取得
   ├─ GetClosestProfileForDuplicationOfProfile で近似プロファイル取得
   ├─ TerminalSettings::CreateWithProfile で設定作成
   ├─ 作業ディレクトリを現在のCWDで上書き
   └─ _CreateConnectionFromSettings で新規接続作成
6. 接続の置き換え
   └─ paneContent.GetTermControl().Connection(connection)
7. 新接続の起動
   └─ connection.Start()
```

### フローチャート

```mermaid
flowchart TD
    A[RestartConnectionアクション受信] --> B[_HandleRestartConnection]
    B --> C[アクティブタブ・ペイン取得]
    C --> D{TerminalPaneContent?}
    D -->|Yes| E[_restartPaneConnection]
    D -->|No| F[処理終了]
    E --> G[_duplicateConnectionForRestart]
    G --> H{paneContentがnull?}
    H -->|Yes| I[nullを返す]
    H -->|No| J[TermControlからプロファイル取得]
    J --> K[GetClosestProfileForDuplicationOfProfile]
    K --> L[TerminalSettings::CreateWithProfile]
    L --> M[作業ディレクトリをCWDで上書き]
    M --> N[_CreateConnectionFromSettings]
    N --> O{接続作成成功?}
    O -->|Yes| P[TermControl.Connection に設定]
    O -->|No| Q[処理終了]
    P --> R[connection.Start]
    R --> S[新セッション開始]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-80-01 | 作業ディレクトリ継承 | 新しい接続は現在の作業ディレクトリ（CWD）を引き継ぐ | CWDが空でない場合 |
| BR-80-02 | カーソル継承 | 再起動時はinheritCursor=trueを設定 | 接続がConPTYの場合 |
| BR-80-03 | プロファイル近似取得 | 元のプロファイルに最も近いプロファイルを使用 | GetClosestProfileForDuplicationOfProfile |
| BR-80-04 | 自動再起動対応 | TermControlのRestartTerminalRequestedイベントからも呼び出される | Tab.RestartTerminalRequested |
| BR-80-05 | null安全性 | paneContentまたはcontrolがnullの場合は接続を作成しない | _duplicateConnectionForRestart |

### 計算ロジック

特になし。

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

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

本機能にデータベース操作はない。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | ペイン取得失敗 | アクティブペインが存在しない場合 | 処理をスキップ |
| - | PaneContent取得失敗 | TerminalPaneContentへのキャスト失敗 | nullが返され処理終了 |
| - | プロファイルなし | ペインにプロファイルが関連付けられていない場合 | 接続を作成しない |
| - | 接続作成失敗 | _CreateConnectionFromSettingsが失敗した場合 | nullが返され処理終了 |

### リトライ仕様

ユーザーが再度RestartConnectionアクションを実行することで再試行可能。

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

本機能にトランザクション処理はない。古い接続から新しい接続への切り替えはアトミックに行われる（TermControl.Connection setter経由）。

## パフォーマンス要件

接続の再作成は即座に開始されること。新しいプロセスの起動時間はConPTY/Azure接続の特性に依存する。

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

再起動された接続は元の接続と同じプロファイル設定を使用するため、セキュリティレベルは変わらない。

## 備考

- _duplicateConnectionForRestartは_restartPaneConnectionから呼び出される
- Tab.RestartTerminalRequestedイベントは、_RegisterTabEventsでTerminalPage._restartPaneConnectionに接続される（TerminalPage.cpp:2057行目）
- プロファイルの「近似取得」は、元のプロファイルが削除された場合のフォールバック

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | TerminalPage.h | `src/cascadia/TerminalApp/TerminalPage.h` | _restartPaneConnection宣言（324行目）、_duplicateConnectionForRestart宣言（323行目） |

**読解のコツ**: _restartPaneConnectionはTerminalPaneContentとIInspectable（nullptr）を受け取る。_duplicateConnectionForRestartはITerminalConnectionを返すヘルパーメソッド。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | AppActionHandlers.cpp | `src/cascadia/TerminalApp/AppActionHandlers.cpp` | _HandleRestartConnection（1579-1590行目） |

**主要処理フロー**:
1. **1579行目**: _HandleRestartConnectionハンドラ定義
2. **1582行目**: _senderOrFocusedTabでアクティブタブ取得
3. **1584行目**: GetActivePane()でアクティブペイン取得
4. **1586行目**: _restartPaneConnection呼び出し
5. **1589行目**: args.Handled(true)

#### Step 3: 接続再作成処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | TerminalPage.cpp | `src/cascadia/TerminalApp/TerminalPage.cpp` | _restartPaneConnection（3723-3736行目）、_duplicateConnectionForRestart（1572-1602行目以降） |

**主要処理フロー**:
- **3723-3736行目**: _restartPaneConnection - _duplicateConnectionForRestart呼び出し、Connection setter、Start()呼び出し
- **1572行目**: _duplicateConnectionForRestart - paneContent/control のnullチェック
- **1585行目**: プロファイル取得
- **1592行目**: GetClosestProfileForDuplicationOfProfile
- **1593行目**: TerminalSettings::CreateWithProfile
- **1596-1601行目**: CWD上書き

#### Step 4: イベント登録を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | TerminalPage.cpp | `src/cascadia/TerminalApp/TerminalPage.cpp` | _RegisterTabEvents内（2057行目）: RestartTerminalRequested イベント登録 |

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

```
TerminalPage::_HandleRestartConnection (AppActionHandlers.cpp:1579)
    │
    └─ TerminalPage::_restartPaneConnection (TerminalPage.cpp:3723)
           │
           ├─ TerminalPage::_duplicateConnectionForRestart (TerminalPage.cpp:1572)
           │      │
           │      ├─ TermControl::Connection() [現在の接続取得]
           │      ├─ TerminalPaneContent::GetProfile() [プロファイル取得]
           │      ├─ GetClosestProfileForDuplicationOfProfile()
           │      ├─ TerminalSettings::CreateWithProfile()
           │      ├─ 作業ディレクトリ上書き
           │      └─ _CreateConnectionFromSettings() [新規接続作成]
           │
           ├─ TermControl::Connection(newConnection) [接続置き換え]
           │
           └─ ITerminalConnection::Start() [新接続開始]

--- (自動再起動パス) ---

Tab::RestartTerminalRequested (TerminalPage.cpp:2057)
    │
    └─ TerminalPage::_restartPaneConnection [同上]
```

### データフロー図

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

RestartConnection     ───▶ _HandleRestartConnection
アクション                       │
                                 ▼
アクティブペイン ──────────▶ _restartPaneConnection
(TerminalPaneContent)            │
                                 ▼
元の接続情報 ──────────▶ _duplicateConnectionForRestart ──▶ 新規接続
(Profile, CWD, Settings)         │                          (ITerminalConnection)
                                 ▼
                          TermControl.Connection = 新接続
                                 │
                                 ▼
                          connection.Start() ──▶ 新セッション開始
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| AppActionHandlers.cpp | `src/cascadia/TerminalApp/AppActionHandlers.cpp` | ソース | RestartConnectionアクションハンドラ |
| TerminalPage.cpp | `src/cascadia/TerminalApp/TerminalPage.cpp` | ソース | _restartPaneConnection、_duplicateConnectionForRestart実装 |
| TerminalPage.h | `src/cascadia/TerminalApp/TerminalPage.h` | ヘッダー | メソッド宣言 |
| Tab.cpp | `src/cascadia/TerminalApp/Tab.cpp` | ソース | RestartTerminalRequestedイベント定義 |
| ConptyConnection.cpp | `src/cascadia/TerminalConnection/ConptyConnection.cpp` | ソース | ConPTY接続の再作成 |
| AzureConnection.cpp | `src/cascadia/TerminalConnection/AzureConnection.cpp` | ソース | Azure接続の再作成 |
| AllShortcutActions.h | `src/cascadia/TerminalSettingsModel/AllShortcutActions.h` | ヘッダー | RestartConnectionアクション定義 |
