# 機能設計書 110-RemoteProtocol

## 概要

本ドキュメントは、Avalonia UIフレームワークにおけるリモートプロトコル機能の機能設計書である。デザイナー通信プロトコルを提供する。

### 本機能の処理概要

RemoteProtocolは、Avaloniaデザイナー/プレビューワーとIDE（Visual Studio、Rider等）間の通信プロトコルを定義する。BSON形式でシリアライズされたメッセージをTCP/IP経由で交換し、XAML更新、フレームデータ転送、入力イベント転送などを実現する。

**業務上の目的・背景**：IDEとデザイナープロセスは別プロセスとして動作するため、プロセス間通信のための標準化されたプロトコルが必要である。RemoteProtocolは、このプロセス間通信を抽象化し、IDE側とデザイナー側の両方で使用可能な共通のメッセージ定義を提供する。これにより、複数のIDEベンダーが統一された方法でAvaloniaデザイナーと連携できる。

**機能の利用シーン**：
- Visual StudioとAvaloniaプレビューワー間の通信
- JetBrains RiderとAvaloniaプレビューワー間の通信
- カスタムデザイナーツールの開発
- リモートプレビュー機能の実装
- デザイナー機能のテスト

**主要な処理内容**：
1. メッセージタイプの定義とGUID管理
2. BSONシリアライゼーション
3. TCPストリーム通信
4. ビューポートメッセージ（サイズ、DPI、フレーム）
5. デザインメッセージ（XAML更新、結果通知）
6. 入力メッセージ（マウス、キーボード、スクロール）

**関連システム・外部連携**：
- Avalonia.DesignerSupport（デザイナー実装）
- IDE拡張機能
- BSON（Binary JSON）ライブラリ

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

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | デザイナー通信 | 内部機能 | IDE-デザイナー間通信 |

## 機能種別

通信プロトコル / メッセージ定義 / シリアライゼーション

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| IPAddress | IPAddress | Yes | 接続先IPアドレス | 有効なIP |
| Port | int | Yes | 接続先ポート番号 | 有効なポート |

### 入力データソース

- TCPストリームからのBSONメッセージ
- IDE/デザイナーからの送信要求

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| 各種メッセージ | object | GUID識別されたメッセージオブジェクト |
| OnMessage | イベント | メッセージ受信イベント |

### 出力先

- TCPストリーム
- メッセージイベントハンドラー

## 処理フロー

### 処理シーケンス

```
1. トランスポート接続
   └─ BsonTcpTransport.Connect
   └─ ストリーム取得
2. メッセージ送信
   └─ Send(object data)
   └─ BSON シリアライズ
   └─ ストリーム書き込み
3. メッセージ受信
   └─ バックグラウンドループ
   └─ BSON デシリアライズ
   └─ OnMessage イベント発火
4. 型解決
   └─ AvaloniaRemoteMessageGuidAttribute
   └─ DefaultMessageTypeResolver
```

### フローチャート

```mermaid
flowchart TD
    A[BsonTcpTransport作成] --> B[Connect]
    B --> C[TcpClient接続]
    C --> D[ストリーム取得]
    D --> E[Start]
    E --> F[受信ループ開始]
    F --> G{メッセージ受信}
    G -->|データあり| H[BSON デシリアライズ]
    H --> I[GUID から型解決]
    I --> J[OnMessage発火]
    J --> G
    G -->|接続終了| K[クリーンアップ]

    L[Send呼び出し] --> M[BSON シリアライズ]
    M --> N[ストリーム書き込み]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-110-1 | メッセージGUID | 各メッセージ型はAvaloniaRemoteMessageGuidAttributeでGUID識別 | 常時 |
| BR-110-2 | BSON形式 | メッセージはBSON形式でシリアライズ | 常時 |
| BR-110-3 | 非同期送信 | Send()はTask を返す非同期メソッド | 常時 |
| BR-110-4 | イベントスタッシュ | 接続前のイベントはスタッシュして接続後に再送 | 再接続時 |

### 計算ロジック

特になし。

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

データベース操作なし。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| CONNECTION_FAILED | Exception | TCP接続失敗 | 再接続またはエラー通知 |
| DESERIALIZE_ERROR | Exception | BSONデシリアライズ失敗 | OnException発火 |
| UNKNOWN_MESSAGE | - | 未知のGUID | 無視またはログ |

### リトライ仕様

接続エラー時はOnExceptionイベントで通知、リトライは呼び出し元の責任。

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

トランザクションなし。

## パフォーマンス要件

- 低レイテンシのメッセージ転送
- フレームデータ（FrameMessage）の効率的なバイナリ転送
- BSON形式による効率的なシリアライゼーション

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

- デフォルトはローカルホスト接続
- 認証機構は未実装（IDE統合での使用を想定）

## 備考

- プロトコル定義のみで実装はDesignerSupport側
- IDE拡張機能でも同じプロトコルを使用

---

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

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

### 推奨読解順序

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

メッセージ型の定義を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | ViewportMessages.cs | `src/Avalonia.Remote.Protocol/ViewportMessages.cs` | ビューポート関連メッセージ（サイズ、DPI、フレーム） |
| 1-2 | DesignMessages.cs | `src/Avalonia.Remote.Protocol/DesignMessages.cs` | デザイン関連メッセージ（XAML更新） |
| 1-3 | InputMessages.cs | `src/Avalonia.Remote.Protocol/InputMessages.cs` | 入力関連メッセージ（マウス、キーボード） |

**読解のコツ**: 各メッセージクラスはAvaloniaRemoteMessageGuidAttributeで一意のGUIDを持つ。

#### Step 2: トランスポートインターフェースを理解する

通信インターフェースを理解。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | ITransport.cs | `src/Avalonia.Remote.Protocol/ITransport.cs` | IAvaloniaRemoteTransportConnection インターフェース |

**主要処理フロー**:
- **8行目**: Send(object data)で任意のオブジェクトを送信
- **9行目**: OnMessageイベントでメッセージ受信
- **10行目**: OnExceptionイベントでエラー通知
- **11行目**: Start()で受信ループ開始

#### Step 3: TCPトランスポートを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | BsonTcpTransport.cs | `src/Avalonia.Remote.Protocol/BsonTcpTransport.cs` | TCP/BSON トランスポート実装 |

#### Step 4: メッセージ型解決を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | AvaloniaRemoteMessageGuidAttribute.cs | `src/Avalonia.Remote.Protocol/AvaloniaRemoteMessageGuidAttribute.cs` | メッセージGUID属性 |
| 4-2 | DefaultMessageTypeResolver.cs | `src/Avalonia.Remote.Protocol/DefaultMessageTypeResolver.cs` | GUID→型解決 |

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

```
IAvaloniaRemoteTransportConnection (インターフェース)
    │
    └─ BsonTcpTransport (実装)
           │
           ├─ Connect(IPAddress, port)
           │      └─ TcpClient.ConnectAsync
           │
           ├─ Start()
           │      └─ 受信ループ開始
           │             │
           │             ├─ BsonStreamTransport.Read
           │             │      └─ MetsysBson デシリアライズ
           │             │
           │             └─ OnMessage イベント発火
           │
           └─ Send(object)
                  └─ BsonStreamTransport.Write
                         └─ MetsysBson シリアライズ

DefaultMessageTypeResolver
    │
    └─ ResolveType(Guid)
           └─ AvaloniaRemoteMessageGuidAttribute から型を検索
```

### データフロー図

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

送信オブジェクト ────────▶ BSON シリアライズ ─────────────▶ バイト列
                               │
                               ▼
                          TCPストリーム
                               │
                               ▼
バイト列 ────────────────▶ BSON デシリアライズ ───────────▶ 受信オブジェクト
                               │
                               ▼
GUID ─────────────────────▶ MessageTypeResolver ──────────▶ .NET型
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| ITransport.cs | `src/Avalonia.Remote.Protocol/ITransport.cs` | ソース | トランスポートインターフェース |
| ViewportMessages.cs | `src/Avalonia.Remote.Protocol/ViewportMessages.cs` | ソース | ビューポートメッセージ定義 |
| DesignMessages.cs | `src/Avalonia.Remote.Protocol/DesignMessages.cs` | ソース | デザインメッセージ定義 |
| InputMessages.cs | `src/Avalonia.Remote.Protocol/InputMessages.cs` | ソース | 入力メッセージ定義 |
| TransportMessages.cs | `src/Avalonia.Remote.Protocol/TransportMessages.cs` | ソース | トランスポートメッセージ定義 |
| BsonTcpTransport.cs | `src/Avalonia.Remote.Protocol/BsonTcpTransport.cs` | ソース | TCP/BSONトランスポート |
| BsonStreamTransport.cs | `src/Avalonia.Remote.Protocol/BsonStreamTransport.cs` | ソース | ストリームトランスポート |
| AvaloniaRemoteMessageGuidAttribute.cs | `src/Avalonia.Remote.Protocol/AvaloniaRemoteMessageGuidAttribute.cs` | ソース | メッセージGUID属性 |
| DefaultMessageTypeResolver.cs | `src/Avalonia.Remote.Protocol/DefaultMessageTypeResolver.cs` | ソース | 型解決 |
| IMessageTypeResolver.cs | `src/Avalonia.Remote.Protocol/IMessageTypeResolver.cs` | ソース | 型解決インターフェース |
| MetsysBson.cs | `src/Avalonia.Remote.Protocol/MetsysBson.cs` | ソース | BSON実装 |
| EventStash.cs | `src/Avalonia.Remote.Protocol/EventStash.cs` | ソース | イベントスタッシュ |
| TransportConnectionWrapper.cs | `src/Avalonia.Remote.Protocol/TransportConnectionWrapper.cs` | ソース | 接続ラッパー |
