feat: Control (Type=101) パケットの実装

[9c5s]

概要

Control (Type=101) パケットの送受信を実装する。レイヤー制御コマンドの送受信が可能になる。

仕様 (TCNET V3.5.1B)

• サイズ: 42 + DataSize バイト / ユニキャスト / レスポンス必須
• ASCII形式のControl Pathでレイヤー操作を指示
• Step 0 (Initialize) → Step 1 (Response) のハンドシェイク

Control Path例

layer/1/state=6;              # Layer 1を停止
layer/5/source=1;             # Layer AのソースをLayer 1に設定
layer/2/state=3; layer/2/resync;  # Layer 2を再生+再同期

パケット構造

Byte	Size	Type	説明
24	1	UInt8	Step (0=Initialize, 1=Response)
25	1	-	RESERVED
26	4	UInt32LE	Data Size
30	12	-	RESERVED
42	DataSize	ASCII	Control Path

実装タスク

• TCNetControlPacket クラスの実装 (read/write)
• Control Pathのパーサー/ビルダー
• TCNetPackets[101] へのマッピング登録
• テスト

[coderabbitai]

Coding Plan

Summary

• 既存の TCNetPacket パターンに完全準拠した TCNetControlPacket クラスを実装し、length() は可変長を動的に計算する方式を採用
• Control Path は生文字列としてパケットに保持し、パーサー/ビルダーは独立ユーティリティとして提供することでレイヤー分離を維持
• sendControl() メソッドを新設し、既存の requestData() パターンを踏襲した Promise ベースのハンドシェイク API を提供
• TCNetPackets へのマッピング登録により受信パスは自動的に機能させ、receiveUnicast() には Control 専用の分岐を追加してレスポンス処理を明示化

Design Choices

Design Choice 1: 可変長パケットの送信方法

Options Considered:

1. length() で実際のサイズ (42 + controlPath.length) を動的に計算して返す
2. sendPacket() を修正し、length() === -1 の場合は packet.buffer が事前割当済みであることを期待する
3. Control パケット専用の sendControl() メソッドを新設し、バッファ確保を内部で行う

Chosen Option: 1

Rationale: Option 1 + Option 3 の組み合わせ: length() は動的に計算可能とし、専用の sendControl() メソッドで送信・レスポンス待機を一括処理する。これにより既存の sendPacket() の変更を最小化しつつ、Control 特有のハンドシェイクロジックを明確に分離できる。

Design Choice 2: Control Path のデータ構造

Options Considered:

1. 単純な文字列として保持し、パーサー/ビルダーはユーティリティ関数として提供
2. 構造化された型 (ControlCommand[]) を定義し、パケットクラス内で変換

Chosen Option: 1

Rationale: Option 1: パケットクラスは controlPath: string として生の ASCII を保持し、パーサー/ビルダーは独立したユーティリティ関数として提供する。これはプロトコル層とアプリケーション層の責務を分離し、既存パケットクラスのパターン（生データ保持）に合致する。

💡 User Tips

Regenerate the plan with different choices with @coderabbitai <feedback>.

Implementation Steps

Phase 1: TCNetControlPacket コアクラスの実装

このフェーズでは Control パケットの基本クラスを実装し、既存のパケットディスパッチシステムに登録する。これにより受信パスが自動的に機能するようになる。

Task 1: TCNetControlPacket クラスの定義

パケット仕様に基づき、固定ヘッダー部分 (bytes 24-41) と可変長ペイロード (byte 42+) を処理するクラスを実装する。

• src/network.ts に TCNetControlPacket クラスを追加（TCNetRequestPacket の直後が適切）
• フィールド: step: number (UInt8), dataSize: number (UInt32LE), controlPath: string (ASCII)
• read(): バッファから各フィールドを読み取り。offset 24 に step、26 に dataSize、42 から dataSize バイト分を controlPath として slice → toString("ascii")
• write(): 各フィールドをバッファに書き込み。dataSize は controlPath.length から自動計算。Reserved バイト (25, 30-41) は Buffer.alloc のゼロフィルに依存
• length(): 42 + this.controlPath.length を返す（動的計算）
• type(): TCNetMessageType.Control (101) を返す

Task 2: TCNetPackets ディスパッチテーブルへの登録

パケットタイプ 101 を新クラスにマッピングし、受信時の自動パースを有効化する。

• src/network.ts の TCNetPackets オブジェクトで [TCNetMessageType.Control]: null を [TCNetMessageType.Control]: TCNetControlPacket に変更
• src/index.ts で TCNetControlPacket をエクスポートに追加

🤖 Prompt for AI agents

`src/network.ts` に `TCNetControlPacket` クラスを実装し、既存の `TCNetPackets` ディスパッチテーブルおよび
`src/index.ts` のエクスポートに登録するフェーズ。

- `src/network.ts` の `TCNetRequestPacket` の直後に `TCNetControlPacket` クラスを追加する
  - フィールド:
    - `step: number`（UInt8）
    - `dataSize: number`（UInt32LE）
    - `controlPath: string`（ASCII文字列）
  - `read()` メソッド:
    - offset 24 から `step` を UInt8 で読み取る
    - offset 26 から `dataSize` を UInt32LE で読み取る
- offset 42 から `dataSize` バイト分をスライスし、`toString("ascii")` で `controlPath` に変換する
  - `write()` メソッド:
    - `dataSize` は `controlPath.length` から自動計算してバッファに書き込む
    - Reserved バイト（offset 25, 30-41）は `Buffer.alloc` のゼロフィルに依存する
  - `length()` メソッド: `42 + this.controlPath.length` を動的に返す
  - `type()` メソッド: `TCNetMessageType.Control`（101）を返す
- `src/network.ts` の `TCNetPackets` オブジェクトで `[TCNetMessageType.Control]: null` を
`[TCNetMessageType.Control]: TCNetControlPacket` に変更する
- `src/index.ts` に `TCNetControlPacket` をエクスポートとして追加する

Phase 2: Control Path ユーティリティと送受信フロー

このフェーズでは Control Path の構造化ヘルパーを提供し、Control パケットの送信・レスポンス待機を行う公開 API を実装する。

Task 1: Control Path パーサー/ビルダーの実装

Control Path 文字列と構造化データ間の変換ユーティリティを提供する。

• src/network.ts または新規 src/control-path.ts に型定義とユーティリティ関数を追加
• ControlCommand 型の定義: { layer: number; property: string; value?: string | number }
• parseControlPath(path: string): ControlCommand[] - セミコロン区切りでコマンドを分割し、各コマンドをパース
• buildControlPath(commands: ControlCommand[]): string - コマンド配列から Control Path 文字列を生成
• シンプルな実装を優先（正規表現または split ベース）

Task 2: receiveUnicast での Control パケット処理

受信した Control パケット (Step=1 レスポンス) を適切にディスパッチする。

• src/tcnet.ts の receiveUnicast() メソッドに TCNetControlPacket 用の分岐を追加
• packet instanceof nw.TCNetControlPacket の場合、pending リクエストとのマッチングまたは "control" イベントの emit を行う
• Step フィールドを利用したハンドシェイク検証を追加

Task 3: sendControl 公開メソッドの実装

Control コマンドを送信し、レスポンスを待機する高レベル API を提供する。

• src/tcnet.ts の TCNetClient クラスに sendControl(controlPath: string): Promise<TCNetControlPacket> メソッドを追加
• 既存の requestData() パターンを参考に、pending リクエスト管理とタイムアウト処理を実装
• TCNetControlPacket を生成し、step = 0 (Initialize) を設定
• 動的 length() に対応するため、バッファ確保ロジックを調整（controlPath 設定後に length() を呼ぶ）
• sendServer() を使用してユニキャスト送信し、Step=1 レスポンスを待機

🤖 Prompt for AI agents

Control Path のパーサー/ビルダーユーティリティを実装し、`src/tcnet.ts` の受信・送信フローに Control
パケット処理を追加するフェーズ。

**Control Path ユーティリティ（`src/network.ts` または新規 `src/control-path.ts`）:**
- `ControlCommand` 型を定義する: `{ layer: number; property: string; value?: string |
number }`
- `parseControlPath(path: string): ControlCommand[]` を実装する
  - セミコロン区切りでコマンドを分割し、各コマンドをパースする
  - シンプルな実装を優先（正規表現または split ベース）
- `buildControlPath(commands: ControlCommand[]): string` を実装する
  - コマンド配列から Control Path 文字列を生成する

**`src/tcnet.ts` の受信フロー（`receiveUnicast()` メソッド）:**
- `packet instanceof nw.TCNetControlPacket` の分岐を追加する
- 該当する場合、pending リクエストとのマッチングまたは `"control"` イベントの emit を行う
- Step フィールドを利用したハンドシェイク検証を追加する

**`src/tcnet.ts` の送信フロー（`TCNetClient` クラス）:**
- `sendControl(controlPath: string): Promise<TCNetControlPacket>` メソッドを追加する
- 既存の `requestData()` パターンを参考に、pending リクエスト管理とタイムアウト処理を実装する
- `TCNetControlPacket` を生成し、`step = 0`（Initialize）を設定する
- `controlPath` 設定後に `length()` を呼ぶことで動的なバッファ確保ロジックに対応する
- `sendServer()` を使用してユニキャスト送信し、Step=1 レスポンスを待機する

Phase 3: テスト

このフェーズでは実装した機能の動作を検証するユニットテストを追加する。

Task 1: TCNetControlPacket の読み書きテスト

パケットクラスの read/write ラウンドトリップを検証する。

• tests/ ディレクトリに control-packet.test.ts を作成
• 固定バッファからの read() テスト: step, dataSize, controlPath が正しく読み取れること
• write() → read() ラウンドトリップテスト: 書き込んだ値が読み戻せること
• 様々な controlPath 長でのテスト（空文字列、短い文字列、複数コマンド）

Task 2: Control Path ユーティリティのテスト

パーサー/ビルダーの動作を検証する。

• 同ファイルまたは別ファイルにパーサー/ビルダーのテストを追加
• parseControlPath: 単一コマンド、複数コマンド、値あり/なしのパターン
• buildControlPath: 構造化データからの文字列生成、往復一致の検証
• エッジケース: 空文字列、末尾セミコロンの有無、不正形式の扱い

🤖 Prompt for AI agents

`tests/` ディレクトリにユニットテストを追加し、`TCNetControlPacket` クラスおよび Control Path
ユーティリティの動作を検証するフェーズ。

**`tests/control-packet.test.ts` の作成（`TCNetControlPacket` の読み書きテスト）:**
- 固定バッファからの `read()` テストを実装する
  - `step`、`dataSize`、`controlPath` が正しく読み取れることを検証する
- `write()` → `read()` のラウンドトリップテストを実装する
  - 書き込んだ値が読み戻せることを検証する
- 様々な `controlPath` 長でのテストを追加する（空文字列、短い文字列、複数コマンド）

**Control Path ユーティリティのテスト（同ファイルまたは別ファイル）:**
- `parseControlPath` のテストを追加する
  - 単一コマンド、複数コマンド、値あり/なしのパターンを検証する
- `buildControlPath` のテストを追加する
  - 構造化データからの文字列生成、往復一致を検証する
- エッジケースのテストを追加する（空文字列、末尾セミコロンの有無、不正形式の扱い）

Research

このコードベースは TCNet プロトコルの TypeScript 実装であり、src/network.ts に全パケットクラス (TCNetPacket 抽象基底クラスを継承) と TCNetPackets ディスパッチテーブルが定義されている。各パケットは read() / write() / length() / type() メソッドを実装し、24バイトの TCNetManagementHeader の後にパケット固有のペイロードを配置する。src/tcnet.ts の TCNetClient クラスが送受信ロジックを担当し、sendPacket() でバッファ確保・ヘッダー書き込み・ペイロード書き込み・UDP送信を行う。可変長パケット (length() === -1) は受信側のみ対応しており、送信側は固定長を前提としている。

---

🚀 Next Steps

🤖 All AI agent prompts combined

Task: 1

`src/network.ts` に `TCNetControlPacket` クラスを実装し、既存の `TCNetPackets` ディスパッチテーブルおよび
`src/index.ts` のエクスポートに登録するフェーズ。

- `src/network.ts` の `TCNetRequestPacket` の直後に `TCNetControlPacket` クラスを追加する
  - フィールド:
    - `step: number`（UInt8）
    - `dataSize: number`（UInt32LE）
    - `controlPath: string`（ASCII文字列）
  - `read()` メソッド:
    - offset 24 から `step` を UInt8 で読み取る
    - offset 26 から `dataSize` を UInt32LE で読み取る
- offset 42 から `dataSize` バイト分をスライスし、`toString("ascii")` で `controlPath` に変換する
  - `write()` メソッド:
    - `dataSize` は `controlPath.length` から自動計算してバッファに書き込む
    - Reserved バイト（offset 25, 30-41）は `Buffer.alloc` のゼロフィルに依存する
  - `length()` メソッド: `42 + this.controlPath.length` を動的に返す
  - `type()` メソッド: `TCNetMessageType.Control`（101）を返す
- `src/network.ts` の `TCNetPackets` オブジェクトで `[TCNetMessageType.Control]: null` を
`[TCNetMessageType.Control]: TCNetControlPacket` に変更する
- `src/index.ts` に `TCNetControlPacket` をエクスポートとして追加する
===============================================================================

Task: 2

Control Path のパーサー/ビルダーユーティリティを実装し、`src/tcnet.ts` の受信・送信フローに Control
パケット処理を追加するフェーズ。

**Control Path ユーティリティ（`src/network.ts` または新規 `src/control-path.ts`）:**
- `ControlCommand` 型を定義する: `{ layer: number; property: string; value?: string |
number }`
- `parseControlPath(path: string): ControlCommand[]` を実装する
  - セミコロン区切りでコマンドを分割し、各コマンドをパースする
  - シンプルな実装を優先（正規表現または split ベース）
- `buildControlPath(commands: ControlCommand[]): string` を実装する
  - コマンド配列から Control Path 文字列を生成する

**`src/tcnet.ts` の受信フロー（`receiveUnicast()` メソッド）:**
- `packet instanceof nw.TCNetControlPacket` の分岐を追加する
- 該当する場合、pending リクエストとのマッチングまたは `"control"` イベントの emit を行う
- Step フィールドを利用したハンドシェイク検証を追加する

**`src/tcnet.ts` の送信フロー（`TCNetClient` クラス）:**
- `sendControl(controlPath: string): Promise<TCNetControlPacket>` メソッドを追加する
- 既存の `requestData()` パターンを参考に、pending リクエスト管理とタイムアウト処理を実装する
- `TCNetControlPacket` を生成し、`step = 0`（Initialize）を設定する
- `controlPath` 設定後に `length()` を呼ぶことで動的なバッファ確保ロジックに対応する
- `sendServer()` を使用してユニキャスト送信し、Step=1 レスポンスを待機する
===============================================================================

Task: 3

`tests/` ディレクトリにユニットテストを追加し、`TCNetControlPacket` クラスおよび Control Path
ユーティリティの動作を検証するフェーズ。

**`tests/control-packet.test.ts` の作成（`TCNetControlPacket` の読み書きテスト）:**
- 固定バッファからの `read()` テストを実装する
  - `step`、`dataSize`、`controlPath` が正しく読み取れることを検証する
- `write()` → `read()` のラウンドトリップテストを実装する
  - 書き込んだ値が読み戻せることを検証する
- 様々な `controlPath` 長でのテストを追加する（空文字列、短い文字列、複数コマンド）

**Control Path ユーティリティのテスト（同ファイルまたは別ファイル）:**
- `parseControlPath` のテストを追加する
  - 単一コマンド、複数コマンド、値あり/なしのパターンを検証する
- `buildControlPath` のテストを追加する
  - 構造化データからの文字列生成、往復一致を検証する
- エッジケースのテストを追加する（空文字列、末尾セミコロンの有無、不正形式の扱い）

💡 Iterate on the plan with: @coderabbitai <feedback>

Example Feedback
- `@coderabbitai` You can skip phase 3. Add a simple unit test case for phase 2.
- `@coderabbitai` For design choice 1 go ahead with option 3 and replan.

---

💬 Have feedback or questions? Drop into our discord!

[9c5s]

調査結果: Control (Type=101) は実装しない

実機調査

Bridge (PRO DJ LINK Bridge) と ShowKontrol (TCS-SK8) 間の通信を60秒間・41万パケットキャプチャした結果、Control パケット (Type=101) は一切使用されていないことを確認した。

Type	パケット名	件数
200	Data	10,784
2	OptIn	2,476
5	Status	1,542
13	Error/Notification	92
30	ApplicationData	40
20	Request	12
101	Control	0

バイナリ解析

PRO DJ LINK Bridge の実行ファイルを解析した結果:

• TCNet関連ルーチン (cmdOfferTCNet*) は全msgType分存在するが、cmdOfferTCNetControl は存在しない
• msgType=101 (0x65) との比較命令をバイナリ全体で検索したが、TCNetディスパッチコード内にはゼロ件
• Text (128)、Keyboard (132) も同様に未実装

ShowKontrol マニュアル確認

ShowKontrolのレイヤー制御は OSC / ArtNet / Executor Commands 経由で行われており、TCNet Control パケットについてはマニュアルに一切記載がない。

結論

Control / Text / Keyboard は TCNet 仕様書にのみ存在し、現存する実装 (Bridge, ShowKontrol) では使用されていない死仕様である。nodeOptions の SUPPORTS TCNCM フラグは静的に設定されているだけで、実際の処理コードは存在しない。

[9c5s]

死仕様のため実装しない。詳細は上記調査結果を参照。