# 機能設計書 88-プロセス間通信

## 概要

本ドキュメントは、Ghosttyターミナルエミュレータにおけるプロセス間通信（IPC: Inter-Process Communication）機能の設計仕様を記載する。

### 本機能の処理概要

プロセス間通信機能は、別のプロセスから実行中のGhosttyインスタンスに対してコマンドを送信し、新規ウィンドウを開くなどの操作を行う機能である。CLIツール（`ghostty +new-window`等）から既存のGhosttyプロセスを制御できる。

**業務上の目的・背景**：
スクリプトや他のアプリケーションからGhosttyを制御できるようにすることで、自動化やワークフロー統合を可能にする。また、シングルインスタンスモードでの新規ウィンドウ作成を実現する。

**機能の利用シーン**：
- CLIから`ghostty +new-window`で既存インスタンスに新規ウィンドウを開く
- スクリプトからGhosttyを自動制御
- ランチャーやデスクトップ統合からの呼び出し

**主要な処理内容**：
1. IPCターゲット（class指定または自動検出）を決定
2. D-Bus（Linux）または独自プロトコル（macOS）で通信を確立
3. アクション（new_window等）を送信
4. 受信側でアクションを実行

**関連システム・外部連携**：
- D-Bus（Linux）
- GTK Application API（Linux）
- macOS XPC（計画中）

**権限による制御**：
D-Bus セッションバスへのアクセス権限が必要。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | - | - | 画面を持たないバックエンド機能 |

## 機能種別

システム連携 / バックエンド処理

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| target | Target | Yes | IPCのターゲット（class指定またはdetect） | 有効なD-Busバス名 |
| action | Action | Yes | 実行するアクション | new_window等 |
| arguments | []string | No | コマンド引数（new_window用） | - |

### 入力データソース

- CLIコマンド（`ghostty +new-window`）
- libghostty API

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| 実行結果 | void/error | アクションの成功/失敗 |

### 出力先

実行中のGhosttyインスタンス

## 処理フロー

### 処理シーケンス

```
1. ターゲット決定
   ├─ class指定: 指定されたアプリケーションIDを使用
   └─ detect: デフォルトのアプリケーションIDを使用
2. 通信確立
   ├─ D-Busセッションバスに接続
   └─ バス名とオブジェクトパスを検証
3. ペイロード構築
   └─ アクション名とパラメータをGVariantに変換
4. メソッド呼び出し
   └─ org.gtk.Actions.Activateを呼び出し
5. 結果処理
   └─ エラーがあれば報告
```

### フローチャート

```mermaid
flowchart TD
    A[IPC呼び出し] --> B{ターゲット種別}
    B -->|class| C[指定されたクラス名を使用]
    B -->|detect| D[デフォルトアプリIDを使用]
    C --> E[バス名/オブジェクトパス生成]
    D --> E
    E --> F{D-Busバス名検証}
    F -->|無効| G[エラー: IPCFailed]
    F -->|有効| H{オブジェクトパス検証}
    H -->|無効| G
    H -->|有効| I[D-Busセッションバス接続]
    I --> J{接続成功?}
    J -->|No| G
    J -->|Yes| K[ペイロード構築]
    K --> L[Activate呼び出し]
    L --> M{呼び出し成功?}
    M -->|No| G
    M -->|Yes| N[成功]
    G --> O[終了]
    N --> O
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-88-01 | D-Bus使用 | Linux環境ではD-Busセッションバスを使用 | Linux環境 |
| BR-88-02 | バス名形式 | バス名は`com.mitchellh.ghostty`形式 | 常時 |
| BR-88-03 | オブジェクトパス形式 | オブジェクトパスは`/com/mitchellh/ghostty`形式 | 常時 |
| BR-88-04 | アクション拡張可能 | 新規アクションは`Action`unionに追加 | 開発時 |

### 計算ロジック

オブジェクトパス生成: バス名の`.`を`/`に、`-`を`_`に変換

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

本機能はデータベース操作を行わない。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| IPCFailed | 通信エラー | D-Busバス名無効 | エラーメッセージをstderrに出力 |
| IPCFailed | 通信エラー | オブジェクトパス無効 | エラーメッセージをstderrに出力 |
| IPCFailed | 通信エラー | セッションバス接続失敗 | エラーメッセージをstderrに出力 |
| IPCFailed | 通信エラー | メソッド呼び出し失敗 | エラーメッセージをstderrに出力 |

### リトライ仕様

リトライは行わない。

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

該当なし。

## パフォーマンス要件

- D-Bus呼び出しは同期的に実行
- タイムアウトはデフォルト値を使用

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

- D-Busセッションバスはユーザーセッション内でのみアクセス可能
- 他ユーザーのGhosttyインスタンスには接続不可

## 備考

- 現在サポートされているアクションは`new_window`のみ
- macOSでのIPC実装は今後の課題

---

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

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

### 推奨読解順序

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

まず、IPCの型定義を理解することが重要。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | ipc.zig | `src/apprt/ipc.zig` | Target, Action unionの定義 |

**読解のコツ**: `Target`は`class`（指定）と`detect`（自動検出）の2種類。`Action`は現在`new_window`のみ。

**主要処理フロー**:
- **8-13行目**: Errors型の定義（IPCFailed）
- **15-54行目**: Target union（class, detect）
- **56-192行目**: Action union（new_window）とNewWindow構造体

#### Step 2: D-Bus実装を理解する

GTK環境でのD-Bus通信実装。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | DBus.zig | `src/apprt/gtk/ipc/DBus.zig` | D-Bus通信ヘルパー |

**主要処理フロー**:
- **32-125行目**: init関数 - D-Bus接続の初期化
- **127-130行目**: addParameter - パラメータ追加
- **132-185行目**: send - D-Busメソッド呼び出し
- **187-196行目**: deinit - リソース解放

#### Step 3: new_windowコマンドを理解する

CLIからのnew_window呼び出し。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | new_window.zig | `src/apprt/gtk/ipc/new_window.zig` | new_windowアクションの実装 |

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

```
CLI (ghostty +new-window)
    │
    └─ src/cli/new_window.zig
           │
           ▼
    src/apprt/ipc.zig
           │
           ├─ Target (class/detect)
           │
           └─ Action (new_window)
                  │
                  ▼
           [Linux/GTK環境]
                  │
                  ▼
           src/apprt/gtk/ipc/DBus.zig
                  │
                  ├─ init() - D-Bus接続
                  ├─ addParameter() - パラメータ追加
                  └─ send() - Activate呼び出し
                         │
                         ▼
                  実行中Ghosttyインスタンス
                         │
                         ▼
                  新規ウィンドウ作成
```

### データフロー図

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

CLI引数 ─────────▶ ipc.zig ───────▶ Target/Action構築
                      │
                      ▼
              プラットフォーム判定
                      │
                      ▼
              [Linux/GTK]
                      │
                      ▼
              DBus.zig#init()
                      │
                      ▼
              バス名/オブジェクトパス検証
                      │
                      ▼
              D-Busセッションバス接続
                      │
                      ▼
              Activate呼び出し
                      │
                      ▼
              実行中インスタンスでアクション実行
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| ipc.zig | `src/apprt/ipc.zig` | ソース | IPC型定義（Target, Action） |
| DBus.zig | `src/apprt/gtk/ipc/DBus.zig` | ソース | D-Bus通信ヘルパー |
| new_window.zig | `src/apprt/gtk/ipc/new_window.zig` | ソース | new_windowアクション実装 |
| new_window.zig | `src/cli/new_window.zig` | ソース | CLIコマンド実装 |
| App.zig | `src/apprt/gtk/App.zig` | ソース | GTKアプリケーションのIPC受信処理 |
| embedded.zig | `src/apprt/embedded.zig` | ソース | libghostty向けIPC API |
