fix: アートワーク取得の信頼性改善とクラスタサイズ0対応 (#57) (#66)

## Summary

- Fileパケット(clusterSize=0)でアートワークデータが抽出できないバグを修正 (#57, #58, #59)
- 5スキル並列レビュー(CodeRabbit, requesting-code-review, simplify, Codex
adversarial-review, TDD)を3ラウンド実施し、発見された全問題(T1-T23)を修正

### 主な変更

**バグ修正**
- `clusterSize=0` のFileパケットからバッファ末尾までをデータとして読み取るよう修正
- `requestData` がFileパケット応答で resolve しないバグを修正
- CUEデータパーサーの `cueStart` offset を仕様書通り byte 47 に修正
- `ipToNumber` の空セグメント検証漏れ(`"192.168..1"` 等)を修正
- `CueData` から `loopOutTime` を削除(byte 46-49 が CUE 1 開始 byte 47 と重複するため)
- converge 後のサブネット外 Master OptIn で `this.server` が上書きされる信頼境界退行を修正
- `connectToAdapter` (switchAdapter経由) の pre-connected パスにもサブネットチェックを追加
- `disconnectSockets` で共有ソケットの重複 close を排除
- 通常 assembler パスと fileChunks パスの両方で `readAssembled` 後の data null
チェックを追加

**信頼性向上**
- `handleFileChunkPacket` メソッド抽出で `receiveUnicast` のネスト深化を解消
- `fileCollectionTimeout` (200ms) に加え `requestTimeout`
を全体上限タイマーとして設定し無限蓄積を防止
- `maxFileChunkBytes` (10MB) によるメモリ上限を追加
- `TCNetDataPacketArtwork.readAssembled` に JPEG SOI マーカー (0xFF 0xD8)
検証を追加
- `resolveAdapterByRemoteAddress` に try-catch (IPv6防御) と重複サブネット曖昧性検出を追加
- `getClusterEnd` ユーティリティ関数でバッファ末尾計算ロジックを統一

**テスト (+10件, 269テスト全パス)**
- `ipToNumber` エラーケース6件、`listNetworkAdapters` エッジケース3件
- サブネットフィルタ(connected / pre-connected)、重複サブネット曖昧性検出
- `totalPackets=0` の単一/マルチFileパケットアセンブリ、requestTimeout上限
- JPEG SOI 検証(不正データ reject)
- テストの private アクセスを `configureMockBroadcast` ヘルパーに集約

### 破壊的変更

- `CueData.loopOutTime` を削除(byte 46-49 が CUE 1 と重複し信頼できない値のため)

## Test plan

- [x] `npx vitest run --project unit` — 269テスト全パス
- [x] lefthook pre-commit フック全パス (typecheck, build, test, lint, format)
- [x] 実機テスト: Bridge + CDJ 環境でアートワーク取得を確認

Author: 9c5s

.changeset/artwork-cluster-size.md

@@ -0,0 +1,13 @@
+---
+"@9c5s/node-tcnet": patch
+---
+
+fix: アートワーク取得の信頼性改善とクラスタサイズ0対応
+
+- FileパケットのclusterSize=0対応とアートワークデータ抽出の修正
+- CUEデータパーサーのbyte offset修正とloopOutTime削除(byte重複)
+- ソケット共有設計のサブネットフィルタリングとlongest prefix match
+- JPEG SOIマーカー検証、fileChunksメモリ上限、requestTimeout上限の追加
+- ipToNumber入力検証強化とgetClusterEndユーティリティ統一
+
+BREAKING CHANGE: CueData.loopOutTimeを削除(byte 46-49がCUE 1と重複し信頼できない値のため)

src/multi-packet.ts

@@ -1,3 +1,5 @@
+import { getClusterEnd } from "./utils";
+
 /**
  * BigWaveFormとBeatGridのマルチパケットを組み立てるアセンブラ
  * @category Utilities
@@ -22,9 +24,10 @@ export class MultiPacketAssembler {
         const packetNo = buffer.readUInt32LE(34);
         const clusterSize = buffer.readUInt32LE(38);
         const dataStart = 42;
-        if (dataStart + clusterSize > buffer.length) return false;
+        const end = getClusterEnd(buffer.length, dataStart, clusterSize);
+        if (clusterSize > 0 && end !== dataStart + clusterSize) return false;
         // T3: Buffer.from() でコピーを保持し、元バッファへの参照共有を防ぐ
-        this.packets.set(packetNo, Buffer.from(buffer.slice(dataStart, dataStart + clusterSize)));
+        this.packets.set(packetNo, Buffer.from(buffer.slice(dataStart, end)));
         return this.packets.size >= this.totalPackets;
     }
 

src/network.ts

@@ -1,4 +1,4 @@
-import { assert } from "./utils";
+import { assert, getClusterEnd } from "./utils";
 import type {
     ArtworkData,
     CueData,
@@ -630,30 +630,33 @@ export class TCNetDataPacketCUE extends TCNetDataPacket {
     /** バッファからパケットデータを読み取る */
     read(): void {
         const loopInTime = this.buffer.readUInt32LE(42);
-        const loopOutTime = this.buffer.readUInt32LE(46);
+        // byte 46-49 (Loop OUT Time) はCUE 1開始(byte 47)と重複するため読み取らない
+        // CUE 1にデータがあるとloopOutTimeは汚染された値になる
         const cues: CuePoint[] = [];
-        // 仕様書にはCUE 1開始を byte 47 と記載しているが、
-        // Loop OUT Time (byte 46-49) と重複するため仕様書の誤記。
-        // 実機検証に基づき byte 50 を採用。
-        const cueStart = 50;
+        const cueStart = 47;
         for (let i = 0; i < 18; i++) {
             const offset = cueStart + i * 22;
             if (offset + 22 > this.buffer.length) break;
             const type = this.buffer.readUInt8(offset);
-            if (type === 0) continue;
+            const inTime = this.buffer.readUInt32LE(offset + 2);
+            const outTime = this.buffer.readUInt32LE(offset + 6);
+            // BridgeはTYPEフィールドを0で送信する場合がある
+            // type=0かつinTime/outTime両方0のエントリのみスキップする
+            // type有効値(>=1)でinTime/outTime=0のケース(トラック先頭CUE)は保持する
+            if (type === 0 && inTime === 0 && outTime === 0) continue;
             cues.push({
                 index: i + 1,
                 type,
-                inTime: this.buffer.readUInt32LE(offset + 2),
-                outTime: this.buffer.readUInt32LE(offset + 6),
+                inTime,
+                outTime,
                 color: {
                     r: this.buffer.readUInt8(offset + 11),
                     g: this.buffer.readUInt8(offset + 12),
                     b: this.buffer.readUInt8(offset + 13),
                 },
             });
         }
-        this.data = { loopInTime, loopOutTime, cues };
+        this.data = { loopInTime, cues };
     }
 
     /** パケットデータをバッファに書き込む */
@@ -909,7 +912,7 @@ export class TCNetDataPacketArtwork extends TCNetDataPacket {
             return;
         }
         const clusterSize = this.buffer.readUInt32LE(38);
-        const end = Math.min(dataStart + clusterSize, this.buffer.length);
+        const end = getClusterEnd(this.buffer.length, dataStart, clusterSize);
         this.data = { jpeg: Buffer.from(this.buffer.slice(dataStart, end)) };
     }
 
@@ -918,6 +921,11 @@ export class TCNetDataPacketArtwork extends TCNetDataPacket {
      * @param assembled - 結合済みバッファ
      */
     readAssembled(assembled: Buffer): void {
+        // JPEG SOIマーカー(0xFF 0xD8)が存在しないデータは不正とみなす
+        if (assembled.length < 2 || assembled[0] !== 0xff || assembled[1] !== 0xd8) {
+            this.data = null;
+            return;
+        }
         this.data = { jpeg: Buffer.from(assembled) };
     }