Phase 0: 既存Mesh拡張機能とSkyWay API利用状況の調査

[takaokouji]

目的

既存のMesh拡張機能がSkyWay APIをどのように使用して機能を実現しているかを調査し、Mesh v2システムの設計にフィードバックします。

調査対象ファイル

gui/scratch-vm/src/extensions/scratch3_mesh/ 配下のファイル:

• index.js - 拡張機能のエントリーポイント
• mesh-service.js - SkyWay API利用の中核
• mesh-host.js - ホスト機能
• mesh-peer.js - ピア機能
• block-icon.png - ブロックアイコン

調査項目

1. SkyWay API利用状況

• mesh-service.js#12 周辺のSkyWay API利用箇所の特定
• 使用しているSkyWay APIの種類とメソッド
• SkyWay APIの初期化処理
• 接続・切断フロー

2. 実現している機能

• グループ管理機能（作成、参加、退出）
• データ共有機能（送信、受信）
• イベント通知機能
• ホスト・ピアの役割分担

3. データフローとイベントフロー

• クライアント間のデータ送受信フロー
• イベント発火と受信の仕組み
• グループ内ブロードキャストの実装

4. ブロック定義

• 提供されているブロックの種類と機能
• ブロックのパラメータと戻り値
• イベントハンドラーの実装

成果物

• 既存Mesh拡張機能の機能一覧
• SkyWay API使用箇所と機能のマッピング
• データフロー図（テキストまたはMermaid）
• Mesh v2システムへの要件フィードバック（コメント）

関連

• EPIC Issue: EPIC: Mesh v2 拡張機能の実装 #444

🤖 Generated with Claude Code

Co-Authored-By: Claude noreply@anthropic.com

[takaokouji]

Phase 0 調査中間報告（作業中断）

すべてのPhaseのsub-issue作成後に調査を再開します。

SkyWay API利用状況（mesh-service.js#12）

使用ライブラリ: skyway-js

主要API:

• Peer API: new Peer(), peer.on('open|close|error'), peer.listAllPeers(), peer.fetchPeerExists(), peer.joinRoom(), peer.destroy()
• Room API: room.on('open|peerJoin|peerLeave|data|close|log'), room.send(), room.close()
• APIキー: a9023dec-9791-4949-add5-d5306a45ad95

実現している機能

1. グループ管理: ホスト作成、ピア参加、スキャン、退出、TTL管理
2. データ共有: グローバル変数の共有、変数変更通知
3. イベント通知: ブロードキャストメッセージ送受信
4. メッセージ形式: {owner, type: "variable|variables|broadcast", data}

詳細な調査結果は、Phase 1以降のsub-issue作成後に報告します。

[takaokouji]

Phase 0 調査完了報告

既存Mesh拡張機能のSkyWay API利用状況と実現機能を調査しました。

---

1. SkyWay API → Mesh v2 GraphQL API マッピング

接続・グループ管理

SkyWay API	用途	Mesh v2 GraphQL API	実装方法
new Peer(peerId, {key})	P2P接続確立	WebSocket接続	Apollo Client / Amplify
peer.listAllPeers(callback)	利用可能なホスト検索	未実装	スキャン機能は不要（グループID直接入力）
peer.fetchPeerExists(peerId)	ホスト存在確認	未実装	joinGroup時のエラーハンドリングで対応
peer.joinRoom(roomName) (ホスト)	ルーム作成	createGroup(name, hostId)	Mutation
peer.joinRoom(hostPeerId) (ピア)	ルーム参加	joinGroup(groupId, nodeId)	Mutation
peer.destroy() / room.close()	切断	leaveGroup(groupId, nodeId)	Mutation

データ送受信

SkyWay API	用途	Mesh v2 GraphQL API	実装方法
room.send({type: 'variable'})	単一変数送信	reportDataByNode(groupId, nodeId, data)	Mutation (高頻度最適化)
room.send({type: 'variables'})	複数変数送信	reportDataByNode(groupId, nodeId, data)	Mutation (配列で送信)
room.send({type: 'broadcast'})	イベント送信	fireEventByNode(groupId, nodeId, eventName, payload)	Mutation (None DS)
room.on('data', callback)	データ受信	onDataUpdateInGroup(groupId)	Subscription
room.on('data', callback)	イベント受信	onEventInGroup(groupId)	Subscription
room.on('peerLeave') (ホスト検知)	ホスト退出検知	onGroupDissolve(groupId)	Subscription

---

2. 実現機能の詳細分析

2.1 ブロック機能

提供ブロック (index.js#89-105):

• getSensorValue - センサー値（グローバル変数）取得

フックされている既存ブロック (index.js#196-212):

• event_broadcast - ブロードキャストイベント
• event_broadcastandwait - ブロードキャスト待機イベント
• data_setvariableto - 変数設定
• data_changevariableby - 変数変更

2.2 メッセージフォーマット

SkyWay版メッセージ構造:

{
  "owner": "mesh_id",
  "type": "variable|variables|broadcast",
  "data": {
    "name": "変数名",
    "value": "値"
  }
}

Mesh v2版データ構造 (GraphQL):

# 変数送信
{
  groupId: "group_id"
  nodeId: "node_id"
  data: [
    { key: "変数名1", value: "値1" },
    { key: "変数名2", value: "値2" }
  ]
}

# イベント送信
{
  groupId: "group_id"
  nodeId: "node_id"
  eventName: "イベント名"
  payload: "ペイロード(JSON文字列)"
}

2.3 データフロー図

sequenceDiagram
    participant Host as ホスト
    participant SkyWay as SkyWay Room
    participant Peer as ピア

    Note over Host,Peer: グループ作成と参加
    Host->>SkyWay: peer.joinRoom(hostPeerId)
    SkyWay-->>Host: room open
    Peer->>SkyWay: peer.joinRoom(hostPeerId)
    SkyWay-->>Peer: room open
    SkyWay-->>Host: peerJoin event
    Host->>SkyWay: send(variables) - 初期変数同期
    SkyWay-->>Peer: data event

    Note over Host,Peer: 変数変更と共有
    Peer->>Peer: 変数変更 (data_setvariableto)
    Peer->>SkyWay: send({type: 'variable', data})
    SkyWay-->>Host: data event
    Host->>Host: setVariable(name, value, owner)

    Note over Host,Peer: イベント通知
    Host->>SkyWay: send({type: 'broadcast', data})
    SkyWay-->>Peer: data event
    Peer->>Peer: event_broadcast実行

    Note over Host,Peer: ピア退出
    Peer->>SkyWay: disconnect()
    SkyWay-->>Host: peerLeave event

    Note over Host,Peer: ホスト退出（グループ解散）
    Host->>SkyWay: disconnect()
    SkyWay-->>Peer: peerLeave event (hostPeerId)
    Peer->>Peer: 自動切断

Loading

Mesh v2版データフロー:

sequenceDiagram
    participant Host as ホスト
    participant AppSync as AppSync GraphQL
    participant DynamoDB as DynamoDB
    participant Peer as ピア

    Note over Host,Peer: グループ作成と参加
    Host->>AppSync: createGroup(name, hostId)
    AppSync->>DynamoDB: PutItem (GROUP#id/METADATA)
    AppSync-->>Host: Group
    Peer->>AppSync: joinGroup(groupId, nodeId)
    AppSync->>DynamoDB: PutItem (GROUP#id/NODE#id)
    AppSync-->>Peer: Node
    Peer->>AppSync: reportDataByNode(初期変数)
    AppSync->>DynamoDB: PutItem (NodeStatus)
    AppSync-->>Host: Subscription (onDataUpdateInGroup)

    Note over Host,Peer: 変数変更と共有
    Peer->>AppSync: reportDataByNode(data)
    AppSync->>DynamoDB: PutItem (NodeStatus)
    AppSync-->>Host: Subscription (onDataUpdateInGroup)

    Note over Host,Peer: イベント通知
    Host->>AppSync: fireEventByNode(eventName)
    AppSync-->>Peer: Subscription (onEventInGroup)

    Note over Host,Peer: ピア退出
    Peer->>AppSync: leaveGroup(groupId, nodeId)
    AppSync->>DynamoDB: DeleteItem

    Note over Host,Peer: ホスト退出（グループ解散）
    Host->>AppSync: leaveGroup(groupId, hostId)
    AppSync->>Lambda: leaveGroupHandler
    Lambda->>DynamoDB: Query + BatchWriteItem (全削除)
    AppSync-->>Peer: Subscription (onGroupDissolve)
    Peer->>Peer: 自動切断

Loading

---

3. Mesh v2設計へのフィードバック

3.1 既存機能との差異

❌ 未実装機能（意図的）

1. スキャン機能 (peer.listAllPeers)

   • 理由: SkyWayではホスト一覧を自動検出できたが、Mesh v2ではグループIDを直接入力する方式に変更
   • 代替: グループID共有機能（QRコード、URL等）を別途検討

2. TTL管理 (mesh-service.js#60-62, fixed could not convert extension ruby code to block if never enabled… #227-244)

   • 理由: SkyWayではpeerIdにTTLを埋め込んで有効期限を管理していたが、Mesh v2では不要
   • 代替: DynamoDBのTTL機能を使用した自動削除を検討

✅ 追加推奨機能

1. Query: listGroups

   • スキャン機能の代替として、アクティブなグループ一覧取得
   • フィルター条件: 最終更新時刻、グループ名など

2. Mutation: updateGroupMetadata

   • グループ名変更、追加メタデータ設定

3. Query: getNodesByGroup

   • グループ内の全Node情報取得（現在のメンバー一覧）

3.2 性能最適化の推奨事項

1. reportDataByNode の差分送信

   • 現状: 全変数を毎回送信
   • 推奨: 変更された変数のみ送信（差分更新）
   • 実装: クライアント側で変更検知、サーバー側でマージ処理

2. WebSocket接続の永続化

   • Subscription用WebSocket接続を維持
   • 再接続ロジックの実装

3. DynamoDBアクセスパターンの最適化

   • GSI追加検討: nodeId によるグループ検索
   • Composite Key設計の見直し

3.3 ブロック実装の注意点

既存フック機能の再実装 (index.js#196-212)

Mesh v2でも以下のブロックをフックする必要があります:

// 既存実装を置き換え
this.runtime._primitives.event_broadcast = this.broadcast.bind(this);
this.runtime._primitives.data_setvariableto = this.setVariableTo.bind(this);

これにより、ユーザーが通常のScratchブロックを使用しても、自動的にMesh v2で変数やイベントが共有されます。

変数管理の互換性 (index.js#274-368)

Scratchのグローバル変数システムとの統合:

• runtime.createNewGlobalVariable - 変数作成時に自動送信
• stage.setVariableValue - 変数変更時に自動送信
• stage.renameVariable - 変数名変更時に自動送信

Mesh v2でも同様のフック実装が必須です。

---

4. 実装優先度の提案

Phase 1-3 (GraphQLスキーマ) への追加提案

既存Meshとの機能互換性を保つため、以下を追加検討:

type Query {
  # 既存
  getGroup(groupId: ID!): Group
  getNodeStatus(nodeId: ID!): NodeStatus
  listGroupStatuses(groupId: ID!): [NodeStatus!]!
  listNodesInGroup(groupId: ID!): [Node!]!
  
  # 追加推奨
  listActiveGroups(limit: Int): [Group!]!  # スキャン機能代替
  getGroupByNode(nodeId: ID!): Group  # Node所属グループ取得
}

type Mutation {
  # 追加推奨
  updateGroupName(groupId: ID!, name: String!): Group!  # グループ名変更
}

---

5. 成果物サマリー

• ✅ 既存Mesh拡張機能の機能一覧
• ✅ SkyWay API使用箇所と機能のマッピング
• ✅ データフロー図（Mermaid）
• ✅ Mesh v2システムへの要件フィードバック

Phase 0の調査を完了しました。次のPhase 1以降の実装に進むことができます。

🤖 Generated with Claude Code

Co-Authored-By: Claude noreply@anthropic.com

[takaokouji]

Phase 0 調査結果の更新（レビューフィードバック反映）

調査結果のレビューを受けて、以下の設計変更を反映します。

---

設計変更サマリー

1. 利用可能なホスト検索機能の実装 ✅

当初の判断: 未実装（グループID直接入力方式）
変更後: 実装必須

SkyWayの peer.listAllPeers() に相当する機能として、GraphQL Queryを追加します。

type Query {
  listGroupsByDomain(domain: String): [Group!]!
}

2. Domain概念の導入 ✅

グループIDの正式名: {group_id}@{domain}

Domain決定ルール:

• 指定あり: ユーザーが指定した任意の文字列（URLパラメーター ?mesh=domain）
• 指定なし: リクエスト元のグローバルIP（自動取得）

ユースケース:

シナリオ	Domain	検索スコープ
教室内WiFi	203.0.113.1（自動）	同じルーター配下の端末のみ
携帯ネットワーク	school-2024（手動指定）	同じdomain文字列を指定した端末のみ
公開グループ	public-event（手動指定）	誰でもアクセス可能

3. Domain指定方法

URL形式: https://smalruby.app?mesh=domain

既存Mesh拡張機能と同じURLクエリーパラメーター方式を採用します。

4. Domain文字列の制約緩和

項目	既存Mesh	Mesh v2
最大文字数	10文字	256文字
許可文字	[a-zA-Z0-9_-]	英数字 + 記号 + マルチバイト文字

---

更新されたGraphQLスキーマ

type Group {
  id: ID!           # group_id部分のみ
  domain: String!   # domain部分（グローバルIP or 任意文字列）
  fullId: String!   # {group_id}@{domain}の完全なID
  name: String!
  hostId: ID!
  createdAt: AWSDateTime!
}

type Query {
  # domain内のグループ一覧取得（domain未指定時はリクエスト元IPを使用）
  listGroupsByDomain(domain: String): [Group!]!
  
  # 完全なグループID指定で取得
  getGroup(groupId: ID!, domain: String): Group
  getNodeStatus(nodeId: ID!): NodeStatus
  listGroupStatuses(groupId: ID!, domain: String!): [NodeStatus!]!
  listNodesInGroup(groupId: ID!, domain: String!): [Node!]!
}

type Mutation {
  # グループ作成（domain未指定時はリクエスト元IPを使用）
  createGroup(
    name: String!, 
    hostId: ID!, 
    domain: String @constraint(maxLength: 256)
  ): Group!
  
  # グループ参加
  joinGroup(groupId: ID!, domain: String!, nodeId: ID!): Node!
  
  # グループ退出
  leaveGroup(groupId: ID!, domain: String!, nodeId: ID!): Node

  # データ通信
  reportDataByNode(
    groupId: ID!
    domain: String!
    nodeId: ID!
    data: [SensorDataInput!]!
  ): NodeStatus!

  fireEventByNode(
    groupId: ID!
    domain: String!
    nodeId: ID!
    eventName: String!
    payload: String
  ): Event!
}

type Subscription {
  onDataUpdateInGroup(groupId: ID!, domain: String!): NodeStatus!
    @aws_subscribe(mutations: ["reportDataByNode"])

  onEventInGroup(groupId: ID!, domain: String!): Event!
    @aws_subscribe(mutations: ["fireEventByNode"])

  onGroupDissolve(groupId: ID!, domain: String!): GroupDissolvePayload!
    @aws_subscribe(mutations: ["leaveGroup"])
}

---

更新されたDynamoDBテーブル設計

パーティションキー/ソートキー設計

PK: DOMAIN#{domain}
SK: GROUP#{group_id}#METADATA

属性:
- id: group_id部分
- domain: domain部分
- fullId: {group_id}@{domain}
- name: グループ名
- hostId: ホストのnodeId
- createdAt: 作成日時

例:
PK: DOMAIN#203.0.113.1
SK: GROUP#abc123#METADATA

PK: DOMAIN#school-2024
SK: GROUP#def456#METADATA

GSI (Global Secondary Index)

GSI-PK: GROUP#{group_id}
GSI-SK: DOMAIN#{domain}

→ グループIDからdomain逆引き可能

---

更新されたSkyWay API → Mesh v2マッピング

SkyWay API	用途	Mesh v2 GraphQL API	実装方法
peer.listAllPeers()	利用可能なホスト検索	listGroupsByDomain(domain)	Query
peer.joinRoom(roomName) (ホスト)	ルーム作成	createGroup(name, hostId, domain)	Mutation
peer.joinRoom(hostPeerId) (ピア)	ルーム参加	joinGroup(groupId, domain, nodeId)	Mutation
room.send({type: 'variable'})	変数送信	reportDataByNode(groupId, domain, nodeId, data)	Mutation
room.send({type: 'broadcast'})	イベント送信	fireEventByNode(groupId, domain, nodeId, eventName, payload)	Mutation

---

実装への影響

以下のIssueを更新します:

• Phase 1-2: DynamoDBテーブルの設計と実装 #447 (Phase 1-2): DynamoDBテーブル設計にDomain対応を追加
• Phase 1-3: AppSync GraphQL APIとスキーマの実装 #448 (Phase 1-3): GraphQLスキーマにDomain対応を追加
• Phase 2-1: グループ管理Mutationの実装 #449 (Phase 2-1): グループ管理MutationにDomain処理を追加
• Phase 2-2: 高頻度Mutationリゾルバーの実装 #450 (Phase 2-2): 高頻度MutationにDomain対応を追加
• Phase 3: Mesh v2拡張機能ブロックの実装 #453 (Phase 3): フロントエンドでURLパラメーター ?mesh=domain の処理を実装

🤖 Generated with Claude Code

Co-Authored-By: Claude noreply@anthropic.com