prototype: Create JavaScript client example for Mesh v2 integration

[takaokouji]

Overview

Create a JavaScript-based prototype demonstrating Mesh v2 client integration. This prototype serves as a reference implementation for Phase 3 frontend work in smalruby3-gui.

Related Issues:

• Phase 3: Mesh v2拡張機能ブロックの実装 smalruby3-gui#453 (Phase 3: Mesh v2 Frontend Extension)
• EPIC: Mesh v2 拡張機能の実装 smalruby3-gui#444 (EPIC: Mesh v2 Extension Implementation)

Purpose

Provide a working example of Mesh v2 client implementation using vanilla JavaScript (not TypeScript) to match Smalruby's technology stack and validate the backend API design before full GUI integration.

Technical Requirements

Technology Stack

• Client: Vanilla JavaScript (ES6+)
• GraphQL Client: Apollo Client or AWS Amplify
• UI: Simple HTML/CSS web page
• Server: Node.js/Express for static file serving
• No build tools: Direct browser execution

Directory Structure

mesh-v2/
├── examples/
│   └── javascript-client/
│       ├── index.html          # Main web page
│       ├── mesh-client.js      # Mesh v2 client library
│       ├── app.js              # Application logic
│       ├── server.js           # Simple Express server
│       ├── package.json        # Dependencies
│       └── README.md           # Usage instructions

Features to Implement

1. Domain Management

• Parse `?mesh=domain` URL parameter (max 256 characters)
• Support no-domain mode (backend uses sourceIp auto-detection)
• Display current domain in UI
• Domain input field for manual override

2. Group Operations

• Create Group

  • Input: group name
  • Option: specify domain or use auto-detected sourceIp
  • Display created groupId and fullId (id@domain)
  • Show host status indicator

• List Groups

  • Query groups by current domain
  • Display: groupId, name, hostId
  • Refresh button for manual updates

• Join Group

  • Select from listed groups
  • Input: nodeId and node name
  • Show success/error messages
  • Display joined group info

• Dissolve Group

  • Exit current group
  • Handle host exit (group dissolution)
  • Clear UI state

• Role Display

  • Show if current node is host or member
  • Visual indicator for host privileges

3. Sensor Data Transmission

• Set Sensor Values

  • UI controls for multiple sensors (e.g., sliders, inputs)
  • Sensor types: temperature, brightness, distance, etc.
  • Display current values

• Change Detection

  • Only transmit when sensor values change
  • Local state tracking
  • Visual indicator when data is sent

• Rate Limiting

  • Maximum 4 sends per second (250ms intervals)
  • Queue system for rapid changes
  • Display rate limit status

• Display Other Nodes' Data

  • Subscribe to sensor updates in group
  • Real-time display of other nodes' sensors
  • Show nodeId for each data source
  • Update timestamps

4. Event System

• Send Events

  • Event name input
  • Payload input (JSON or text)
  • Send button
  • Rate limiting: max 2 events/sec (500ms intervals)
  • Send confirmation feedback

• Receive Events

  • Subscribe to group events via WebSocket
  • Display event history (last 20 events)
  • Show: event name, payload, sender nodeId, timestamp
  • Auto-scroll to latest

• Event Queue Management

  • Handle rapid event sends with queuing
  • Visual queue status

5. Connection & Session Management

• API Configuration

  • AppSync endpoint URL input (or from config)
  • API Key input (or from config)
  • Save to localStorage for convenience

• Connection Status

  • WebSocket connection indicator (connected/disconnected)
  • Auto-reconnect on connection loss
  • Display connection errors

• 90-Minute Session Limit

  • Track session duration
  • Display remaining time
  • Auto-logout warning at 85 minutes
  • Automatic group exit on timeout

6. User Interface

• Layout Sections

  +------------------+------------------+
  | Configuration    | Connection Status|
  +------------------+------------------+
  | Group Management | Current Group    |
  +------------------+------------------+
  | Sensor Data      | Other Nodes Data |
  +------------------+------------------+
  | Event Send       | Event History    |
  +------------------+------------------+
  

• Responsive Design

  • Works on desktop browsers
  • Clear visual hierarchy
  • Error message display areas

• Real-Time Updates

  • WebSocket subscription for sensor data
  • WebSocket subscription for events
  • WebSocket subscription for group dissolution

Implementation Plan

Phase 1: Basic Setup (Day 1)

• Create directory structure
• Set up Express server
• Create basic HTML page
• Configure GraphQL client (Apollo/Amplify)
• Test connection to staging AppSync API

Phase 2: Group Management (Day 2)

• Implement createGroup mutation
• Implement listGroupsByDomain query
• Implement joinGroup mutation (when available in backend)
• Implement dissolveGroup mutation (when available in backend)
• Add UI for group operations

Phase 3: Sensor Data (Day 3)

• Implement reportDataByNode mutation
• Add sensor value inputs (3-5 sample sensors)
• Implement change detection logic
• Add rate limiting (250ms throttle)
• Subscribe to onDataUpdateInGroup
• Display other nodes' sensor data

Phase 4: Events (Day 4)

• Implement fireEventByNode mutation
• Add event send UI
• Implement rate limiting (500ms throttle)
• Subscribe to onEventInGroup
• Display event history

Phase 5: Polish (Day 5)

• Add 90-minute session timer
• Improve error handling
• Add connection status indicators
• Write README documentation
• Test all features end-to-end

Testing Checklist

Domain Handling

• URL parameter `?mesh=testdomain` works
• No parameter uses sourceIp auto-detection
• 256-character domain limit enforced
• Domain persists across page refreshes

Group Operations

• Create group with custom domain
• Create group with auto-detected domain (sourceIp)
• List shows all groups in current domain
• Join group from list
• Dissolve Group as host

Sensor Data

• Sensor changes trigger transmission
• Unchanged sensors don't send data
• Rate limit (4/sec) prevents flooding
• Other nodes' data appears in real-time
• WebSocket subscription updates immediately

Events

• Events send successfully
• Rate limit (2/sec) enforced
• Events received via subscription
• Event history displays correctly
• Payload JSON parsing works

Session Management

• 90-minute timer counts down
• Warning at 85 minutes
• Auto-logout at 90 minutes
• Reconnection after disconnect

Success Criteria

1. ✅ Two browser windows can communicate via Mesh v2
2. ✅ All CRUD operations for groups work
3. ✅ Sensor data updates appear in real-time
4. ✅ Events transmit between nodes
5. ✅ Rate limits prevent API abuse
6. ✅ Code is simple and readable (reference quality)
7. ✅ README provides clear usage instructions

Documentation Requirements

README.md

• Installation instructions
• Configuration (AppSync endpoint, API key)
• How to run the server
• How to use the web interface
• Architecture overview
• Code structure explanation

Code Comments

• Explain GraphQL queries/mutations/subscriptions
• Document rate limiting logic
• Clarify change detection algorithm
• Note any Smalruby-specific considerations

Deliverables

• Working JavaScript client in `examples/javascript-client/`
• Simple Express server for file serving
• Comprehensive README.md
• All features tested and working
• Screenshots or demo video (optional)

Notes

• Keep code simple - this is a reference implementation
• Prioritize clarity over optimization
• Use modern JavaScript (ES6+) but avoid complex frameworks
• GraphQL subscriptions should use WebSocket protocol
• Consider localStorage for saving API configuration

---

🤖 Generated with Claude Code

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

[takaokouji]

Subscription自動テスト実装調査

📋 目的

データ変更時のsubscription通知を自動テストで検証する。

テストシナリオ

1. Subscriptionに参加（WebSocket接続）
2. データ変更を実行（Mutation）
3. Subscriptionで通知を受信
4. 通知内容を検証

🔍 現状分析

既存のテスト基盤

利用可能なツール:

• ✅ RSpec 3.12
• ✅ execute_graphql ヘルパー（HTTP POST）
• ✅ faye-websocket gem（WebSocket対応）
• ✅ eventmachine gem（非同期処理）

現在の制限:

• ❌ WebSocketサポートなし（HTTP onlyヘルパー）
• ❌ Subscription専用ヘルパーなし
• ❌ AppSync WebSocketプロトコル実装なし

AppSync WebSocketプロトコル

AppSyncのリアルタイムエンドポイント:

HTTPS: https://xxx.appsync-api.ap-northeast-1.amazonaws.com/graphql
WebSocket: wss://xxx.appsync-realtime-api.ap-northeast-1.amazonaws.com/graphql

接続フロー:

1. WebSocket接続
   └─> wss://xxx.appsync-realtime-api.../graphql
       Headers:
         - host: xxx.appsync-api.ap-northeast-1.amazonaws.com
         - x-api-key: da2-...

2. connection_init メッセージ送信
   {
     "type": "connection_init"
   }

3. connection_ack 受信
   {
     "type": "connection_ack",
     "payload": { "connectionTimeoutMs": 300000 }
   }

4. start メッセージ送信（subscription開始）
   {
     "id": "subscription-1",
     "type": "start",
     "payload": {
       "query": "subscription { ... }",
       "variables": { ... }
     }
   }

5. data メッセージ受信
   {
     "id": "subscription-1",
     "type": "data",
     "payload": {
       "data": { "onDataUpdateInGroup": { ... } }
     }
   }

6. ka メッセージ（keep-alive）
   {
     "type": "ka"
   }

💡 実装方針の提案

案1: faye-websocketを使用したフルスタック実装

メリット:

• ✅ 実際のWebSocket通信をテスト
• ✅ AppSyncの動作を完全に検証
• ✅ 本番環境と同じプロトコルを使用

デメリット:

• ⚠️ 実装が複雑（AppSyncプロトコル対応）
• ⚠️ 非同期処理の制御が必要（EventMachine）
• ⚠️ テストの実行時間が長くなる可能性

実装イメージ:

# spec/support/appsync_subscription_helper.rb
require 'faye/websocket'
require 'eventmachine'

class AppSyncSubscriptionClient
  def initialize(endpoint, api_key)
    @endpoint = convert_to_websocket_endpoint(endpoint)
    @api_key = api_key
    @subscriptions = {}
  end

  def subscribe(query, variables = {}, &callback)
    EM.run do
      ws = Faye::WebSocket::Client.new(@endpoint, nil, {
        headers: {
          'host' => extract_host(@endpoint),
          'x-api-key' => @api_key
        }
      })

      ws.on :open do |event|
        # Send connection_init
        ws.send(JSON.generate({ type: 'connection_init' }))
      end

      ws.on :message do |event|
        message = JSON.parse(event.data)

        case message['type']
        when 'connection_ack'
          # Send subscription start
          subscription_id = SecureRandom.uuid
          ws.send(JSON.generate({
            id: subscription_id,
            type: 'start',
            payload: {
              query: query,
              variables: variables
            }
          }))

        when 'data'
          # Call callback with data
          callback.call(message['payload']['data'])

        when 'ka'
          # Keep-alive, do nothing
        end
      end

      ws.on :error do |event|
        puts "WebSocket error: #{event.message}"
      end
    end
  end
end

# spec/requests/subscription_integration_spec.rb
RSpec.describe "Subscription Integration", type: :request do
  it "データ更新時にsubscriptionが通知される" do
    client = AppSyncSubscriptionClient.new(
      ENV['APPSYNC_ENDPOINT'],
      ENV['APPSYNC_API_KEY']
    )

    received_data = nil

    # Subscription開始
    client.subscribe(
      "subscription OnDataUpdateInGroup($groupId: ID!, $domain: String!) {
        onDataUpdateInGroup(groupId: $groupId, domain: $domain) {
          nodeId
          groupId
          domain
          data { key value }
        }
      }",
      { groupId: group_id, domain: domain }
    ) do |data|
      received_data = data
      EM.stop
    end

    # Subscription確立後、mutationを実行
    sleep 1
    execute_graphql(mutation_query, mutation_variables)

    # データ受信を待つ（タイムアウト: 5秒）
    expect(received_data).not_to be_nil
    expect(received_data['onDataUpdateInGroup']['groupId']).to eq(group_id)
  end
end

実装の課題:

• EventMachineとRSpecの統合が複雑
• タイムアウト処理の実装が必要
• エラーハンドリングが複雑

案2: CloudWatch Logsベースの間接検証

メリット:

• ✅ 実装がシンプル
• ✅ 既存のHTTPヘルパーを活用
• ✅ テスト実行が高速

デメリット:

• ⚠️ 間接的な検証（実際のWebSocketは未検証）
• ⚠️ CloudWatch Logsのクエリ遅延
• ⚠️ AppSyncの内部動作に依存

実装イメージ:

RSpec.describe "Subscription Trigger via Logs", type: :request do
  it "mutation実行後、CloudWatch LogsにSubscription publishログが出力される" do
    # Mutation実行
    response = execute_graphql(mutation_query, variables)
    expect(response["errors"]).to be_nil

    # CloudWatch Logsでsubscription publishを確認
    # Note: 実際の実装では aws-sdk-cloudwatchlogs が必要
    sleep 2 # ログ出力を待つ

    logs = query_cloudwatch_logs(
      log_group: "/aws/appsync/apis/#{api_id}",
      filter_pattern: "subscription publish",
      start_time: Time.now - 10
    )

    expect(logs).not_to be_empty
    expect(logs.any? { |log| log.include?("onDataUpdateInGroup") }).to be true
  end
end

案3: ハイブリッド方式（推奨）

既存のテストは案2、追加で案1の基本実装を提供。

段階的実装:

Phase 1: 必須フィールド検証（既存）

• ✅ 実装済み: subscription_trigger_spec.rb
• Mutation responseに必要なフィールドが含まれるか検証

Phase 2: スキーマ検証（既存）

• ✅ 実装済み: subscription_trigger_spec.rb
• @aws_subscribe directive設定を検証

Phase 3: WebSocket基本実装（新規）

• AppSyncSubscriptionHelperの実装
• 基本的なsubscription接続テスト

Phase 4: E2Eテスト（新規）

• Subscription + Mutation + 通知受信の完全なフロー

📝 推奨実装計画

Step 1: AppSyncSubscriptionHelperの実装

# spec/support/appsync_subscription_helper.rb
require 'faye/websocket'
require 'eventmachine'
require 'json'
require 'securerandom'

class AppSyncSubscriptionHelper
  attr_reader :endpoint, :api_key, :ws_endpoint

  def initialize(endpoint, api_key)
    @endpoint = endpoint
    @api_key = api_key
    @ws_endpoint = convert_to_websocket_endpoint(endpoint)
  end

  # Subscriptionを確立し、データ受信を待つ
  def wait_for_subscription(query, variables, timeout: 10, &block)
    received_data = []
    error = nil

    EM.run do
      # Timeout設定
      EM.add_timer(timeout) do
        EM.stop
      end

      ws = create_websocket_connection

      setup_websocket_handlers(ws, query, variables) do |data|
        received_data << data
        block.call(data) if block_given?
        EM.stop if should_stop?(data)
      end
    end

    raise error if error
    received_data
  end

  private

  def convert_to_websocket_endpoint(https_endpoint)
    https_endpoint
      .sub('https://', 'wss://')
      .sub('.appsync-api.', '.appsync-realtime-api.')
  end

  def create_websocket_connection
    Faye::WebSocket::Client.new(@ws_endpoint, nil, {
      headers: {
        'host' => extract_host(@endpoint)
      }
    })
  end

  def setup_websocket_handlers(ws, query, variables, &callback)
    # 実装詳細...
  end
end

Step 2: 統合テストの実装

# spec/requests/subscription_e2e_spec.rb
require 'spec_helper'

RSpec.describe "Subscription E2E Test", type: :request do
  let(:subscription_helper) do
    AppSyncSubscriptionHelper.new(
      ENV['APPSYNC_ENDPOINT'],
      ENV['APPSYNC_API_KEY']
    )
  end

  it "reportDataByNode実行時、onDataUpdateInGroupが通知される" do
    # Setup
    group = create_test_group("E2E Test", host_id, domain)
    join_test_node(group['id'], domain, node_id)

    subscription_query = <<~GRAPHQL
      subscription OnDataUpdateInGroup($groupId: ID!, $domain: String!) {
        onDataUpdateInGroup(groupId: $groupId, domain: $domain) {
          nodeId
          groupId
          domain
          data { key value }
        }
      }
    GRAPHQL

    # Subscriptionをバックグラウンドで開始
    received_data = []
    subscription_thread = Thread.new do
      subscription_helper.wait_for_subscription(
        subscription_query,
        { groupId: group['id'], domain: domain },
        timeout: 10
      ) { |data| received_data << data }
    end

    # Subscription確立を待つ
    sleep 2

    # Mutation実行
    mutation_query = File.read('spec/fixtures/mutations/report_data_by_node.graphql')
    response = execute_graphql(mutation_query, {
      groupId: group['id'],
      domain: domain,
      nodeId: node_id,
      data: [{ key: 'temperature', value: '25.5' }]
    })

    expect(response['errors']).to be_nil

    # Subscription通知を待つ
    subscription_thread.join(5)

    # 検証
    expect(received_data).not_to be_empty
    expect(received_data.first['onDataUpdateInGroup']).not_to be_nil
    expect(received_data.first['onDataUpdateInGroup']['groupId']).to eq(group['id'])
  end
end

🎯 実装の優先順位

高優先度（即時実装）

1. ✅ Mutation response field検証（実装済み）
2. ✅ AppSyncSubscriptionHelper基本実装（実装済み）
3. ✅ 単純なsubscription接続テスト（実装済み）

中優先度（Phase 2）

4. ✅ E2Eテスト実装（Subscribe + Mutate + Verify）（実装済み）
5. ⏳ 複数subscription同時接続テスト
6. ✅ Subscription filteringテスト（groupId, domain検証）（実装済み）

低優先度（将来）

7. ⏳ CloudWatch Logsベースの検証
8. ⏳ パフォーマンステスト
9. ⏳ エラーケーステスト

🚧 実装上の注意点

EventMachineとRSpecの統合

問題: EventMachineは専用のイベントループを必要とする

解決策:

# spec/support/event_machine_helper.rb
module EventMachineHelper
  def em_run(timeout = 10, &block)
    result = nil
    EM.run do
      EM.add_timer(timeout) { EM.stop }
      result = block.call
    end
    result
  end
end

RSpec.configure do |config|
  config.include EventMachineHelper, type: :request
end

タイムアウト処理

問題: Subscriptionが届かない場合の無限待機

解決策:

EM.add_timer(timeout) do
  error = "Subscription timeout after #{timeout} seconds"
  EM.stop
end

エラーハンドリング

問題: WebSocketエラーの適切な処理

解決策:

ws.on :error do |event|
  @error = event.message
  EM.stop
end

# テスト終了時にエラーチェック
raise @error if @error

📊 実装コスト見積もり

タスク	工数	難易度
AppSyncSubscriptionHelper実装	4-6h	高
基本接続テスト	2h	中
E2Eテスト実装	3-4h	高
ドキュメント作成	1h	低
合計	10-13h	-

✅ 結論と推奨事項

推奨実装方針: 案3（ハイブリッド方式）

理由:

1. 既存のfield検証テストで基本的な問題は検出可能
2. WebSocket実装で完全なE2E検証が可能
3. 段階的実装でリスク低減

次のステップ:

1. AppSyncSubscriptionHelper基本実装（4-6h）
2. 単純な接続テストで動作確認（2h）
3. E2Eテスト実装（3-4h）

実装可否判断:

• ✅ 技術的実装可能: faye-websocket, eventmachine利用可能
• ✅ 既存基盤活用: RSpec, execute_graphqlヘルパー
• ⚠️ 実装複雑度: 中〜高（AppSyncプロトコル対応必要）

代替案（簡易版）

時間制約がある場合は、CloudWatch Logsベースの検証のみ実装:

• 実装時間: 2-3h
• 検証範囲: 限定的（publishログのみ）
• メリット: 実装が簡単、既存テストとの統合が容易

---

✅ 実装完了サマリー（2025-12-22）

実装内容

Phase 1: Mutation Response Field検証 ✅

• ファイル: spec/requests/subscription_trigger_spec.rb
• 内容:
  • Mutation が subscription filtering に必要なフィールド（groupId, domain）を返すことを検証
  • GraphQL スキーマの @aws_subscribe directive が正しく設定されているか検証
  • Mutation と Subscription の戻り値型が一致しているか検証

Phase 2: AppSync WebSocket Subscription Helper ✅

• ファイル: spec/support/appsync_subscription_helper.rb
• 内容:
  • AppSync WebSocket プロトコル実装
  • Base64エンコードによる認証ヘッダー対応
  • graphql-ws プロトコル対応
  • subscribe_and_execute メソッドで subscription確立後にmutationを実行し、通知受信を待つ

Phase 3: E2E Subscription Tests ✅

• ファイル: spec/requests/subscription_e2e_spec.rb
• 内容:
  • reportDataByNode → onDataUpdateInGroup subscription の E2E テスト
  • fireEventByNode → onEventInGroup subscription の E2E テスト
  • WebSocket経由でリアルタイム通知を受信し、データ内容を検証

テスト実行結果

bundle exec rspec spec/requests/subscription_trigger_spec.rb spec/requests/subscription_e2e_spec.rb

11 examples, 0 failures

内訳:

• Subscription Trigger Validation: 9 tests ✅
• Subscription E2E Test: 2 tests ✅

技術的課題と解決方法

課題1: WebSocket NoProtocolError

• 問題: AppSync が "NoProtocolError" を返す
• 解決: WebSocket 接続時に graphql-ws プロトコルを指定

課題2: Required headers are missing

• 問題: 認証ヘッダーが不足
• 解決: WebSocket URL に Base64 エンコードした認証ヘッダーをクエリパラメータとして追加

実装例:

header = Base64.strict_encode64(JSON.generate({
  'host' => @host,
  'x-api-key' => @api_key
}))
payload = Base64.strict_encode64('{}')
ws_url_with_auth = "#{@ws_endpoint}?header=#{header}&payload=#{payload}"

Faye::WebSocket::Client.new(ws_url_with_auth, ['graphql-ws'])

実装所要時間

• AppSyncSubscriptionHelper実装: 約4時間
• E2Eテスト実装: 約3時間
• デバッグ（WebSocketプロトコル対応）: 約2時間
• 合計: 約9時間（見積もり: 10-13時間）

今後の拡張可能性

• ✅ 基本的な subscription E2E テストが自動化された
• ⏳ 複数 subscription 同時接続のテスト（将来実装）
• ⏳ Subscription エラーケースのテスト（将来実装）
• ⏳ CloudWatch Logs によるパブリッシュログの検証（将来実装）

---

作成日: 2025-12-22
実装完了日: 2025-12-22
調査担当: Claude Code