アートワーク取得の信頼性向上: タイムアウト値の調整検討

[9c5s]

背景

beat-link (Pro DJ Link) の調査を踏まえ、TCNetのアートワーク取得における信頼性向上の検討事項をまとめる。

TCNetはUDP上のFileパケットでアートワークを転送するため、TCPベースのPro DJ Linkと比べてパケットロスや応答遅延の影響を受けやすい。

現状の実装

• requestTimeout: 2000ms (リクエスト全体のタイムアウト)
• fileCollectionTimeout: 200ms (totalPackets=0のFileパケット蓄積タイムアウト)
• tcnet-viewer側で最大3回リトライ

観測された問題パターン

Pattern 1: 部分データ (解決済み)

BridgeがtotalPackets=0のFileパケットで送信 → 最初のパケットだけで即resolve → 不完全な画像
→ fileCollectionTimeoutベースの蓄積方式で対応済み

Pattern 2: 全リトライtimeout

Bridgeが応答しない or 応答が遅い → 3回×2秒=6秒で全滅
→ 未解決。requestTimeoutの延長が有効かもしれないが、UXとのバランスが必要

検討事項

• requestTimeoutを2秒→5秒程度に延長する検討 (beat-linkは10秒)
• fileCollectionTimeoutの200msが最適か実機データで検証
• Bridgeの応答パターンの調査 (どのタイミングでアートワークが準備完了するか)
• メタデータ取得成功後に一定時間待機してからアートワークをリクエストする戦略の検討

参考

• beat-link ArtFinder.java - 10秒タイムアウト、失敗時はnull返却 (リトライなし)、2段キャッシュ
• beat-linkはTCP (dbserver) 経由のためパケットロスの問題がない

[coderabbitai]

Coding Plan

Summary

• requestTimeoutのデフォルトを2秒→5秒に延長し、beat-linkの10秒タイムアウトに近づけて信頼性を向上
• 新設定項目interPacketTimeout（デフォルト200ms）を追加し、マルチパケット受信時のパケット間タイムアウトを独立制御可能に
• 初回応答待ち（長め）とパケット間待機（短め）を分離することで、UXと信頼性のバランスを最適化
• 既存のTCNetConfigurationクラスパターンを踏襲し、後方互換性を維持

Design Choices

Design Choice 1: チケットに記載されている`fileCollectionTimeout: 200ms`について

Options Considered:

1. チケットの記載は将来実装予定の仕様であり、今回新規追加する
2. チケットの記載は誤りであり、requestTimeoutの延長のみ行う

Chosen Option: 1

Rationale: チケットの意図に沿い、パケット間タイムアウトを分離した設定項目interPacketTimeoutを新規追加する。これにより、初回リクエストの待機時間（5秒）とパケット間の待機時間（200ms）を独立して制御でき、UXと信頼性のバランスを取りやすくなる。

💡 User Tips

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

Implementation Steps

Phase 1: TCNetConfiguration の拡張とタイムアウト分離

マルチパケット転送の信頼性向上のため、設定クラスに新しいタイムアウト項目を追加し、receiveUnicast()でのタイムアウト処理を分離する。

Task 1: TCNetConfiguration への interPacketTimeout 追加

requestTimeoutとは別に、マルチパケット受信時のパケット間タイムアウトを制御する設定項目を追加する。

• src/tcnet.tsのTCNetConfigurationクラスにinterPacketTimeoutフィールドを追加（デフォルト200ms）
• 同ファイルでrequestTimeoutのデフォルト値を2000msから5000msに変更
• JSDocコメントで各タイムアウトの役割を明確に記載（requestTimeout: 初回応答待ち、interPacketTimeout: マルチパケット間の待機）

Task 2: receiveUnicast() のタイムアウト処理分離

マルチパケット受信時のローリングタイムアウトに新しい設定値を使用するよう修正する。

• src/tcnet.tsのreceiveUnicast()メソッド内、パケット到着時のタイムアウトリセット処理（現在543-553行付近）を修正
• 初回タイムアウト設定（requestData()内）は引き続きrequestTimeoutを使用
• パケット間のローリングタイムアウトリセット時はinterPacketTimeoutを使用するよう変更

🤖 Prompt for AI agents

`src/tcnet.ts`の`TCNetConfiguration`クラスを拡張し、タイムアウト処理を分離する。

**Task 1.1: `TCNetConfiguration`への`interPacketTimeout`追加**
-
`src/tcnet.ts`内の`TCNetConfiguration`クラスに`interPacketTimeout`フィールドを追加し、デフォルト値を200msに設定する
- 同クラス内の`requestTimeout`のデフォルト値を2000msから5000msに変更する
-
各フィールドにJSDocコメントを追加し、`requestTimeout`は「初回応答待ち」、`interPacketTimeout`は「マルチパケット間の待機」として役割を明記する

**Task 1.2: `receiveUnicast()`のタイムアウト処理分離**
- `src/tcnet.ts`の`receiveUnicast()`メソッド内（543-553行付近）のパケット到着時タイムアウトリセット処理を修正する
- `requestData()`内の初回タイムアウト設定は引き続き`requestTimeout`を使用する
- パケット間のローリングタイムアウトリセット時には`interPacketTimeout`を参照するよう変更する

Phase 2: テストの更新

新しい設定項目と変更されたデフォルト値に対応するテストを追加・更新する。

Task 1: 既存テストのデフォルト値更新

変更されたデフォルト値を反映するようテストを修正する。

• tests/配下の関連テストファイルで、requestTimeoutのデフォルト値を参照している箇所があれば5000msに更新
• テスト内でタイムアウト値をモックしている箇所の確認と必要に応じた修正

Task 2: interPacketTimeout のテスト追加

新設定項目の動作を検証するテストを追加する。

• tests/multi-packet.test.tsまたはtests/artwork.test.tsに、interPacketTimeoutがマルチパケット受信時のタイムアウトに使用されることを検証するテストを追加
• カスタムinterPacketTimeout値を設定した場合に、その値がパケット間タイムアウトに反映されることを確認

🤖 Prompt for AI agents

`tests/`配下の既存テストを更新し、新しい設定項目`interPacketTimeout`のテストを追加する。

**Task 2.1: 既存テストのデフォルト値更新**
- `tests/`配下の関連テストファイルを調査し、`requestTimeout`のデフォルト値（2000ms）を参照している箇所を5000msに更新する
- タイムアウト値をモックしている箇所を確認し、必要に応じて修正する

**Task 2.2: `interPacketTimeout`のテスト追加**
- `tests/multi-packet.test.ts`または`tests/artwork.test.ts`に新しいテストケースを追加する
- `interPacketTimeout`がマルチパケット受信時のパケット間タイムアウトとして使用されることを検証する
- カスタム`interPacketTimeout`値を設定した際に、その値がパケット間タイムアウトに正しく反映されることを確認するテストを実装する

Phase 3: エクスポートとドキュメント

公開APIへの影響を確認し、必要に応じてドキュメントを更新する。

公開APIの確認

新しい設定項目が適切にエクスポートされることを確認する。

• src/index.tsでTCNetConfigurationがエクスポートされていることを確認（既存のエクスポートで問題なし）
• 型定義ファイル（もしあれば）への影響を確認

🤖 Prompt for AI agents

公開APIへの影響を確認し、新しい設定項目が正しくエクスポートされていることを検証する。

- `src/index.ts`を確認し、`TCNetConfiguration`が既存のエクスポートに含まれていることを確認する
- 型定義ファイルが存在する場合、`interPacketTimeout`フィールドが型定義に反映されているかを確認し、必要に応じて更新する

Research

TCNetはUDPベースのプロトコルで、アートワーク取得はTCNetFilePacket（MessageType=204）を使用したマルチパケット転送で行われる。現在の実装ではTCNetConfigurationクラスにrequestTimeout（デフォルト2000ms）が定義されており、この単一の値が初回リクエストタイムアウトとマルチパケット組み立て時のパケット間ローリングタイムアウトの両方に使用されている。MultiPacketAssemblerがパケットの蓄積と組み立てを担当し、receiveUnicast()でタイムアウトのリセットが行われる。

---

🚀 Next Steps

🤖 All AI agent prompts combined

Task: 1

`src/tcnet.ts`の`TCNetConfiguration`クラスを拡張し、タイムアウト処理を分離する。

**Task 1.1: `TCNetConfiguration`への`interPacketTimeout`追加**
-
`src/tcnet.ts`内の`TCNetConfiguration`クラスに`interPacketTimeout`フィールドを追加し、デフォルト値を200msに設定する
- 同クラス内の`requestTimeout`のデフォルト値を2000msから5000msに変更する
-
各フィールドにJSDocコメントを追加し、`requestTimeout`は「初回応答待ち」、`interPacketTimeout`は「マルチパケット間の待機」として役割を明記する

**Task 1.2: `receiveUnicast()`のタイムアウト処理分離**
- `src/tcnet.ts`の`receiveUnicast()`メソッド内（543-553行付近）のパケット到着時タイムアウトリセット処理を修正する
- `requestData()`内の初回タイムアウト設定は引き続き`requestTimeout`を使用する
- パケット間のローリングタイムアウトリセット時には`interPacketTimeout`を参照するよう変更する
===============================================================================

Task: 2

`tests/`配下の既存テストを更新し、新しい設定項目`interPacketTimeout`のテストを追加する。

**Task 2.1: 既存テストのデフォルト値更新**
- `tests/`配下の関連テストファイルを調査し、`requestTimeout`のデフォルト値（2000ms）を参照している箇所を5000msに更新する
- タイムアウト値をモックしている箇所を確認し、必要に応じて修正する

**Task 2.2: `interPacketTimeout`のテスト追加**
- `tests/multi-packet.test.ts`または`tests/artwork.test.ts`に新しいテストケースを追加する
- `interPacketTimeout`がマルチパケット受信時のパケット間タイムアウトとして使用されることを検証する
- カスタム`interPacketTimeout`値を設定した際に、その値がパケット間タイムアウトに正しく反映されることを確認するテストを実装する
===============================================================================

Task: 3

公開APIへの影響を確認し、新しい設定項目が正しくエクスポートされていることを検証する。

- `src/index.ts`を確認し、`TCNetConfiguration`が既存のエクスポートに含まれていることを確認する
- 型定義ファイルが存在する場合、`interPacketTimeout`フィールドが型定義に反映されているかを確認し、必要に応じて更新する

💡 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!