iii-realtime-streams

リアルタイムストリーム

類似サービス：Socket.io、Pusher、Firebase Realtime

主な概念

タスクに該当する場合は、以下の概念を使用してください。すべてのストリーム設定で、これらすべてが必要になるわけではありません。

• StreamModule はポート 3112 で WebSocket 接続を提供します
• クライアントは ws://host:3112/stream/{stream_name}/{group_id} に接続します
• stream::set／stream::get／stream::list／stream::delete は、ストリーム項目の CRUD 操作を提供します
• stream::send は、ストリームグループ内のすべての接続済みクライアントにイベントをプッシュします
• createStream は、デフォルト以外のストリームバックエンド用にカスタムアダプターを登録します
• 各ストリーム項目は、stream_name、group_id、item_id、data で指定します

アーキテクチャ

Function
  → trigger('stream::set', { stream_name, group_id, item_id, data })
  → trigger('stream::send', { stream_name, group_id, data })
    → StreamModule
      → WebSocket プッシュ
        → /stream/{stream_name}/{group_id} に接続済みのクライアント

使用する iii プリミティブ

プリミティブ	目的
trigger({ function_id: 'stream::set', payload })	ストリーム項目を作成または更新する
trigger({ function_id: 'stream::get', payload })	ストリーム項目を読み取る
trigger({ function_id: 'stream::list', payload })	ストリームグループ内の項目を一覧表示する
trigger({ function_id: 'stream::delete', payload })	ストリーム項目を削除する
trigger({ function_id: 'stream::send', payload })	接続済みクライアントにイベントをプッシュする
createStream	カスタムストリームアダプターを登録する

リファレンス実装

完全に動作する例については、../references/realtime-streams.js を参照してください。WebSocket クライアントにライブ更新をプッシュし、CRUD 操作でストリーム項目を管理するストリームの例です。

Python 版もあります：../references/realtime-streams.py

Rust 版もあります：../references/realtime-streams.rs

よくあるパターン

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

• registerWorker(url, { workerName }) — ワーカーの初期化
• trigger({ function_id: 'stream::set', payload: { stream_name, group_id, item_id, data } }) — ストリーム項目を書き込む
• trigger({ function_id: 'stream::send', payload: { stream_name, group_id, data } }) — クライアントにイベントをプッシュする
• trigger({ function_id: 'stream::get', payload: { stream_name, group_id, item_id } }) — ストリーム項目を読み取る
• trigger({ function_id: 'stream::list', payload: { stream_name, group_id } }) — グループ内の項目を一覧表示する
• createStream(name, adapter) — 特殊なバックエンド用のカスタムアダプター
• const logger = new Logger() — 構造化ログ

このパターンの応用

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

• ドメインに合わせてストリームに名前を付けます（例：chat-messages、dashboard-metrics、notifications）
• group_id を使用して、ユーザー、ルーム、テナントごとにストリームを分割します
• iii-state-reactions と組み合わせ、状態が変化するたびにストリームイベントをプッシュします
• デフォルトのアダプターが適さない場合（例：カスタムの永続化やファンアウトのロジック）は、createStream を使用します

エンジン設定

StreamModule を使用するには、ポートとアダプター（KvStore または Redis）を指定して iii-config.yaml で有効にする必要があります。注釈付きの設定リファレンス全体については、../references/iii-config.yaml を参照してください。

パターンの適用範囲

• タスクがリアルタイムプッシュを伴わない永続的なキー値データに関するものであれば、iii-state-management を優先してください。
• タスクで状態変化に応じたリアクティブなトリガー（サーバーサイド）が必要であれば、iii-state-reactions を優先してください。
• 主な要件が接続済みクライアントへのライブ更新のプッシュであれば、iii-realtime-streams を使用してください。

使用する場面

• タスクの主な対象が iii エンジンの iii-realtime-streams である場合に、このスキルを使用します。
• リクエストで、このパターンまたは同等の実装が明確に求められている場合に適用されます。

適用範囲

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