@phystack/hub-client 4.5.19-dev → 4.5.20-dev

package/docs/webrtc-test.md

@@ -0,0 +1,330 @@
+# WebRTC Testing Guide
+
+This guide explains how to test the WebRTC functionality in hub-client using direct PhyHub connections.
+
+## Overview
+
+The hub-client WebRTC system enables peer-to-peer DataChannel and MediaStream connections between twins. Testing requires two connected endpoints, which we achieve by running two processes with different device credentials.
+
+## Architecture
+
+```
+Normal Operation:
+  App (hub-client) → phyos (on device) → PhyHub (cloud)
+       {instanceId}      {deviceId, accessKey}
+
+Testing Mode (PHYHUB_DIRECT=true):
+  Test Script → PhyHub (cloud)
+       {deviceId, accessKey}
+```
+
+## Prerequisites
+
+1. **Two device credentials** - You need credentials for two separate devices
+2. **PhyHub access** - Devices must be registered and accessible
+3. **Node.js & ts-node** - For running the test harness
+
+## Getting Device Credentials
+
+Use the Phygrid CLI to get device credentials:
+
+```bash
+# List available devices
+phy dev list
+
+# Select a device interactively
+phy dev select
+
+# Export credentials as environment variables
+phy dev develop --export
+```
+
+This will output something like:
+```bash
+export PHYGRID_DEVICE_ID=abc123...
+export PHYGRID_DEVICE_KEY=xyz789...
+```
+
+Repeat for a second device to get two sets of credentials.
+
+## Running the Test Harness
+
+The test requires two terminals - one for each endpoint.
+
+### Terminal 1: Responder (Start First)
+
+```bash
+cd packages/hub-client
+
+PHYHUB_DIRECT=true \
+DEVICE_ID=<device-b-id> \
+ACCESS_KEY=<device-b-key> \
+PEER_TWIN_ID=<device-a-id> \
+ROLE=responder \
+npx ts-node src/test/webrtc-test-harness.ts
+```
+
+### Terminal 2: Initiator
+
+```bash
+cd packages/hub-client
+
+PHYHUB_DIRECT=true \
+DEVICE_ID=<device-a-id> \
+ACCESS_KEY=<device-a-key> \
+PEER_TWIN_ID=<device-b-id> \
+ROLE=initiator \
+npx ts-node src/test/webrtc-test-harness.ts
+```
+
+## Environment Variables
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `PHYHUB_DIRECT` | Yes | Must be `true` to enable direct connection |
+| `DEVICE_ID` | Yes | Your device ID (also used as twin ID) |
+| `ACCESS_KEY` | Yes | Your device access key |
+| `PEER_TWIN_ID` | Yes | Twin ID of the peer to connect to |
+| `ROLE` | Yes | `initiator` or `responder` |
+| `PHYHUB_URL` | No | PhyHub URL (default: EU region) |
+| `PHYHUB_REGION` | No | `eu`, `us`, or `local` |
+
+Alternative variable names (for CLI compatibility):
+- `PHYGRID_DEVICE_ID` instead of `DEVICE_ID`
+- `PHYGRID_DEVICE_KEY` instead of `ACCESS_KEY`
+
+## Test Flow
+
+1. **Responder** connects to PhyHub and waits for incoming DataChannel
+2. **Initiator** connects to PhyHub and creates DataChannel to responder
+3. **WebRTC signaling** happens via twin messaging (offer/answer/ICE)
+4. **Initiator** sends 5 test messages with timestamps
+5. **Responder** echoes each message back
+6. **Both sides** log all events and messages
+
+## Expected Output
+
+### Responder Output
+```
+============================================================
+WebRTC Test Harness
+============================================================
+
+Configuration:
+  Device ID:    device-b-id
+  Peer Twin ID: device-a-id
+  Role:         responder
+  PhyHub URL:   (default EU)
+
+=== Running as RESPONDER ===
+
+Connecting to PhyHub...
+Connected!
+
+Waiting for DataChannel from peer: device-a-id
+Ready to accept connection...
+
+[EVENT] Connected to device-a-id (datachannel)
+DataChannel received!
+
+[RECEIVED] { type: 'test', count: 1, timestamp: 1234567890 }
+[SENDING] { type: 'echo', original: {...}, respondedAt: 1234567891 }
+...
+
+Channel closed. Received 5 messages.
+
+[SUCCESS] Test completed successfully!
+```
+
+### Initiator Output
+```
+============================================================
+WebRTC Test Harness
+============================================================
+
+Configuration:
+  Device ID:    device-a-id
+  Peer Twin ID: device-b-id
+  Role:         initiator
+  PhyHub URL:   (default EU)
+
+=== Running as INITIATOR ===
+
+Connecting to PhyHub...
+Connected!
+
+Creating DataChannel to peer: device-b-id
+Waiting for responder to be ready...
+
+[EVENT] Connected to device-b-id (datachannel)
+DataChannel created successfully!
+
+Sending test messages...
+
+[SENDING] { type: 'test', count: 1, timestamp: 1234567890 }
+[RECEIVED] { type: 'echo', original: {...}, respondedAt: 1234567891 }
+...
+
+Test complete. Closing channel...
+
+[SUCCESS] Test completed successfully!
+```
+
+## Testing Against Local PhyHub
+
+For local development, you can test against a local PhyHub instance:
+
+```bash
+PHYHUB_DIRECT=true \
+PHYHUB_URL=http://localhost:3000 \
+DEVICE_ID=<device-id> \
+ACCESS_KEY=<access-key> \
+PEER_TWIN_ID=<peer-id> \
+ROLE=initiator \
+npx ts-node src/test/webrtc-test-harness.ts
+```
+
+## Troubleshooting
+
+### Connection Timeout
+- Ensure both devices are registered in PhyHub
+- Check that device credentials are correct
+- Verify PhyHub is accessible (try EU vs US region)
+
+### No DataChannel Received
+- Start the **responder first**, then the initiator
+- Ensure `PEER_TWIN_ID` values are swapped correctly between terminals
+- Check that twin messaging is working (devices subscribed to each other)
+
+### ICE Connection Failed
+- Both peers need to be able to reach STUN servers
+- Try with/without STUN: the system auto-toggles on first failure
+- Check firewall settings
+
+### Authentication Failed
+- Verify `ACCESS_KEY` matches the `DEVICE_ID`
+- Ensure the device exists in PhyHub (was migrated from legacy)
+
+## Programmatic Testing
+
+You can also use the test functions programmatically:
+
+```typescript
+import { runInitiator, runResponder } from './test/webrtc-test-harness';
+
+// In your test file
+describe('WebRTC', () => {
+  it('should establish DataChannel connection', async () => {
+    // Run in separate processes or use test fixtures
+  });
+});
+```
+
+## WebRTC Manager API
+
+For more control during testing, use the WebRTCManager directly:
+
+```typescript
+const client = await PhyHubClient.connect();
+const manager = await client.getWebRTCManager({ verbose: true });
+
+// Listen for all events
+manager.on('connected', (data) => console.log('Connected:', data));
+manager.on('disconnected', (data) => console.log('Disconnected:', data));
+manager.on('error', (data) => console.log('Error:', data));
+manager.on('reconnecting', (data) => console.log('Reconnecting:', data));
+manager.on('reconnected', (data) => console.log('Reconnected:', data));
+
+// Create connections
+const channel = await manager.createDataChannel(targetTwinId);
+const stream = await manager.createMediaStream(targetTwinId);
+```
+
+## Automated Two-Host Testing
+
+For realistic testing across network boundaries, use the `webrtc-test.sh` script which:
+- Stores credentials for two devices in `.env.webrtc-test`
+- Syncs code to a remote Linux host via rsync
+- Runs responder on remote host via SSH
+- Runs initiator locally
+
+### Setup
+
+1. Create `.env.webrtc-test` with credentials for both devices:
+
+```bash
+# Run the setup wizard
+./scripts/webrtc-test.sh setup
+```
+
+Or manually create `.env.webrtc-test`:
+
+```bash
+# Device A (local initiator)
+DEVICE_A_ID=your-device-a-id
+DEVICE_A_KEY=your-device-a-access-key
+
+# Device B (remote responder)
+DEVICE_B_ID=your-device-b-id
+DEVICE_B_KEY=your-device-b-access-key
+
+# Remote host configuration
+REMOTE_HOST=user@remote-linux-host
+REMOTE_PATH=/tmp/hub-client-test
+
+# Optional
+PHYHUB_REGION=eu
+```
+
+2. Run the test:
+
+```bash
+./scripts/webrtc-test.sh run
+```
+
+### What the Script Does
+
+1. **Syncs** the hub-client package to the remote host via rsync
+2. **Installs** dependencies on remote if needed
+3. **Starts** responder on remote host via SSH (backgrounded)
+4. **Waits** for responder to be ready
+5. **Runs** initiator locally
+6. **Collects** logs from both sides
+7. **Cleans up** remote processes
+
+### Manual Two-Host Testing
+
+If you prefer manual control:
+
+```bash
+# On remote host (responder)
+ssh user@remote-host
+cd /path/to/hub-client
+PHYHUB_DIRECT=true \
+DEVICE_ID=$DEVICE_B_ID \
+ACCESS_KEY=$DEVICE_B_KEY \
+PEER_TWIN_ID=$DEVICE_A_ID \
+ROLE=responder \
+npx ts-node src/test/webrtc-test-harness.ts
+
+# On local host (initiator)
+PHYHUB_DIRECT=true \
+DEVICE_ID=$DEVICE_A_ID \
+ACCESS_KEY=$DEVICE_A_KEY \
+PEER_TWIN_ID=$DEVICE_B_ID \
+ROLE=initiator \
+npx ts-node src/test/webrtc-test-harness.ts
+```
+
+## Files Reference
+
+| File | Purpose |
+|------|---------|
+| `src/test/webrtc-test-harness.ts` | Main test script |
+| `scripts/webrtc-test.sh` | Automated two-host test runner |
+| `.env.webrtc-test` | Test credentials (gitignored) |
+| `src/services/phyhub-direct-connection.service.ts` | Direct PhyHub connection |
+| `src/services/webrtc/WebRTCManager.ts` | WebRTC manager class |
+| `src/services/webrtc/DataChannelHandler.ts` | DataChannel implementation |
+| `src/services/webrtc/MediaStreamHandler.ts` | MediaStream implementation |
+| `src/services/webrtc/PeerConnectionManager.ts` | ICE/connection management |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@phystack/hub-client",
-  "version": "4.5.19-dev",
+  "version": "4.5.20-dev",
   "main": "dist/index.js",
   "license": "MIT",
   "private": false,
@@ -14,7 +14,7 @@
     "format:check": "prettier --check \"src/**/*.{ts,js,json,md}\""
   },
   "dependencies": {
-    "@phystack/socket.io-proxy": "4.5.19-dev",
+    "@phystack/socket.io-proxy": "4.5.20-dev",
     "@roamhq/wrtc": "^0.8.0",
     "axios": "^1.7.9",
     "bufferutil": "^4.0.9",
@@ -46,5 +46,5 @@
   },
   "test": "react-scripts test",
   "test:coverage": "npm run test -- --coverage --watchAll=false",
-  "gitHead": "2a35e91d1c5691e5e3d33449dfab2737b5215b22"
+  "gitHead": "2c6f557c48d6bfa40754a5f59e22c40e7cc5d29c"
 }