iii-channels

チャネル

比較対象：Unix パイプ、gRPC ストリーミング、WebSocket データストリーム

主な概念

タスクに適している場合は、以下の概念を使用してください。すべてのワーカーでチャネルが必要なわけではありません。

• チャネルは、2 つのエンドポイント（書き込み側と読み取り側）の間にある、WebSocket ベースのバイナリストリームです
• createChannel() は、書き込み側と読み取り側のペア、および他のワーカーに渡せるシリアライズ可能な参照を返します
• StreamChannelRef はシリアライズ可能な参照（channel_id、access_key、direction）で、関数のペイロードに含められます
• 書き込み側はバイナリデータ（64KB のフレームに分割）とテキストメッセージを送信します
• 読み取り側は readAll() でバイナリチャンクを読み取るか、コールバックを通じてテキストメッセージを受け取ります
• コンシューマーは、createChannel() が返すプロデューサー側の読み取りオブジェクトではなく、シリアライズ可能な StreamChannelRef（例：ChannelReader::new(...)）から読み取り側を構築する必要があります
• チャネルはワーカー間および言語間で動作します。Python の書き込み側から Rust の読み取り側へストリーミングできます

アーキテクチャ

関数は createChannel() でチャネルを作成し、書き込み側と読み取り側のペアを受け取ります。トリガーペイロードを介して、書き込み側の参照または読み取り側の参照を別の関数（異なるワーカー／言語の場合もあります）に渡します。エンジンが 2 つのエンドポイント間の WebSocket 接続を仲介します。バイナリデータは、エンジンのチャネルエンドポイントを通じてワーカー間を直接流れます。

使用する iii プリミティブ

プリミティブ	用途
createChannel(bufferSize?)	チャネルを作成し、書き込み側と読み取り側のペアを返します
ChannelWriter.write(data)	バイナリデータを送信します（64KB のフレームに分割）
ChannelWriter.sendMessage(msg)	チャネルを通じてテキストメッセージを送信します
ChannelWriter.close()	書き込み側を閉じます
ChannelReader.readAll()	ストリーム全体を単一のバッファに読み込みます
ChannelReader.onMessage(callback)	テキストメッセージ用のコールバックを登録します
StreamChannelRef	ワーカー間で渡すシリアライズ可能な参照

参照実装

• TypeScript：../references/channels.js
• Python：../references/channels.py
• Rust：../references/channels.rs

各リファレンスでは、チャネルの作成、バイナリストリーミング、テキストメッセージ、関数間の受け渡しという同じパターンを、それぞれの言語で示しています。

よく使われるパターン

このパターンを使用するコードには、関連する場合、通常以下が含まれます。

• const channel = await iii.createChannel() — チャネルのペアを作成します（プロデューサー側のアクセス）
• channel.writer.stream.write(buffer) / channel.writer.write(data) — バイナリデータを送信します
• channel.writer.sendMessage(JSON.stringify({ type: 'metadata', ... })) — テキストメタデータを送信します
• channel.writer.close() — ストリームの終了を通知します
• ワーカー間のストリーミングには、トリガーペイロードに channel.readerRef または channel.writerRef を渡します
• コンシューマーは参照から読み取り側を再構築する必要があります。例：new ChannelReader(iii.address, readerRef)
• const data = await reader.readAll() — ストリーム全体を読み込みます（コンシューマーの動作）
• reader.onMessage(msg => { ... }) — テキストメッセージを処理します（コンシューマーの動作）

このパターンの応用

タスクに当てはまる場合は、以下の応用方法を使用してください。

• JSON ペイロードにシリアライズすべきでない大容量データの転送には、チャネルを使用します
• パイプラインのパターンでは、処理関数に readerRef を、生成関数に writerRef を渡します
• バイナリデータのストリームに付随するメタデータやシグナリングには、テキストメッセージを使用します
• 読み取り側の速度が書き込み側より遅い場合は、バックプレッシャーを適用するために bufferSize を設定します
• チャネルは言語間で動作します。TypeScript のプロデューサーから Rust のコンシューマーへストリーミングできます

パターンの境界

• キーと値の状態の永続化には、iii-state-management を優先してください。
• ストリームの CRUD（名前付きストリームとグループ／キー）には、iii-realtime-streams を優先してください。
• パブリッシュ／サブスクライブ型のメッセージングには、subscribe タイプのトリガーを優先してください。
• 主な課題がワーカー間のバイナリデータのストリーミングである場合は、iii-channels を使用してください。

使用するタイミング

• タスクが主に iii エンジンの iii-channels に関する場合に、このスキルを使用してください。
• リクエストでこのパターンまたは同等の実装が直接求められている場合に使用してください。

境界

• 無関係なタスクに対する汎用的な代替手段として、このスキルを使用しないでください。
• より具体的な iii スキルが適している場合は、このスキルを適用してはいけません。
• このスキルの例を適用する前に、環境と安全性の制約を必ず確認してください。