webview.io 1.0.0 → 1.0.2

package/README.md

@@ -5,13 +5,15 @@ Easy and friendly API to connect and interact between React Native applications
 ## Features
 
 - **Bidirectional Communication**: Seamless messaging between React Native and WebView
-- **Enhanced Security**: Origin validation, message sanitization, and payload size limits
+- **Robust Connection Handshake**: Three-way handshake with token validation for reliable connections
+- **Enhanced Security**: Origin validation, message sanitization, token-based authentication, and payload size limits
 - **Auto-Reconnection**: Automatic reconnection with exponential backoff strategy
+- **Connection Timeout & Retries**: Configurable timeout with periodic connection attempts
 - **Heartbeat Monitoring**: Connection health monitoring with configurable intervals
 - **Message Queuing**: Queue messages when disconnected and replay on reconnection
 - **Rate Limiting**: Configurable message rate limiting to prevent spam
 - **Promise Support**: Modern async/await APIs with timeout handling
-- **Connection Statistics**: Real-time connection and performance metrics
+- **Connection Statistics**: Real-time connection and performance metrics including readiness state
 - **Comprehensive Error Handling**: Detailed error types and handling mechanisms
 
 ## Installation
@@ -67,6 +69,11 @@ function MapComponent() {
       wioRef.current.emit('hello', { message: 'Hello from React Native!' })
     })
 
+    // Handle connection timeout
+    wioRef.current.on('connect_timeout', ({ attempts }) => {
+      console.log(`Connection failed after ${attempts} attempts`)
+    })
+
     // Listen for messages
     wioRef.current.on('response', (data) => {
       console.log('Received:', data)
@@ -128,6 +135,8 @@ const wio = new WIO({
   debug: false,                      // Enable debug logging
   heartbeatInterval: 30000,          // Heartbeat interval in ms (30s)
   connectionTimeout: 10000,          // Connection timeout in ms (10s)
+  connectionPingInterval: 2000,      // Ping interval during connection (2s)
+  maxConnectionAttempts: 5,          // Max connection attempts before timeout
   maxMessageSize: 1024 * 1024,       // Max message size in bytes (1MB)
   maxMessagesPerSecond: 100,         // Rate limit (100 messages/second)
   autoReconnect: true,               // Enable automatic reconnection
@@ -135,6 +144,48 @@ const wio = new WIO({
 })
 ```
 
+## Connection Architecture
+
+### Three-Way Handshake
+
+webview.io uses a robust three-way handshake protocol with token validation to ensure reliable connections:
+
+```
+1. WEBVIEW → ping (with token) → EMBEDDED
+   - WEBVIEW initiates connection with unique token
+   - Sends periodic pings until acknowledged
+
+2. WEBVIEW ← pong (with token) ← EMBEDDED
+   - EMBEDDED responds with same token
+   - EMBEDDED announces readiness periodically
+
+3. WEBVIEW → __connection_ack (with token) → EMBEDDED
+   - WEBVIEW confirms receipt of pong
+   - Both sides now confirmed connected
+```
+
+This prevents:
+- Race conditions during initialization
+- Accepting connections from wrong peers
+- Silent connection failures
+- Message loss during handshake
+
+### Connection Flow Details
+
+**WEBVIEW Side:**
+- Sends initial `ping` with unique connection token
+- Retries every 2 seconds (configurable via `connectionPingInterval`)
+- Times out after 10 seconds (configurable via `connectionTimeout`)
+- Maximum 5 attempts (configurable via `maxConnectionAttempts`)
+- Fires `connect_timeout` event if all attempts fail
+
+**EMBEDDED Side:**
+- Automatically announces `__embedded_ready` when loaded
+- Retries announcement every 2 seconds until connected
+- Handles race condition if loaded before React Native
+- Responds to `ping` with `pong` containing same token
+- Confirms connection upon receiving `__connection_ack`
+
 ## Async/Await Support
 
 ### Send Messages with Acknowledgments
@@ -177,6 +228,21 @@ console.log('User data received:', userData)
 
 ## Enhanced Connection Management
 
+### Connection Timeout Handling
+
+```javascript
+// Handle connection timeout (new event)
+wio.on('connect_timeout', ({ attempts }) => {
+  console.log(`Failed to connect after ${attempts} attempts`)
+  // Optionally retry manually or show error to user
+})
+
+// With auto-reconnect enabled, timeout triggers reconnection
+wio.on('reconnecting', ({ attempt, delay }) => {
+  console.log(`Reconnection attempt ${attempt}, waiting ${delay}ms`)
+})
+```
+
 ### Auto-Reconnection
 
 ```javascript
@@ -201,11 +267,13 @@ const stats = wio.getStats()
 console.log(stats)
 // {
 //   connected: true,
+//   embeddedReady: true,              // NEW: EMBEDDED peer readiness state
 //   peerType: 'WEBVIEW',
 //   origin: 'https://example.com',
 //   lastHeartbeat: 1609459200000,
 //   queuedMessages: 0,
 //   reconnectAttempts: 0,
+//   connectionAttempts: 0,            // NEW: Current connection attempts
 //   activeListeners: 5,
 //   messageRate: 2
 // }
@@ -213,18 +281,24 @@ console.log(stats)
 
 ## Security Features
 
+### Token-Based Authentication
+
+Each connection uses a unique token for validation:
+
+```javascript
+// Automatically generated and validated during handshake
+// Prevents accepting messages from previous connections
+// Tokens are only used for connection-related events
+```
+
 ### Origin Validation
 
 ```javascript
-// Strict origin checking (WebView side)
-window._wio.listen('react-native') // Only accept from React Native
+// Strict origin checking (React Native side)
+wio.initiate(webViewRef, 'https://trusted-domain.com')
 
-// Error handling for invalid origins (React Native side)
-wio.on('error', (error) => {
-  if (error.type === 'INVALID_ORIGIN') {
-    console.log(`Rejected message from ${error.received}`)
-  }
-})
+// Messages from other origins are automatically rejected
+// No additional configuration needed
 ```
 
 ### Message Sanitization
@@ -257,17 +331,8 @@ wio.on('error', (error) => {
 ```javascript
 wio.on('error', (error) => {
   switch (error.type) {
-    case 'INVALID_ORIGIN':
-      console.error(`Invalid origin: expected ${error.expected}, got ${error.received}`)
-      break
-    case 'ORIGIN_MISMATCH':
-      console.error(`Origin mismatch: expected ${error.expected}, got ${error.received}`)
-      break
-    case 'RATE_LIMIT_EXCEEDED':
-      console.warn(`Rate limit exceeded: ${error.current}/${error.limit} messages/second`)
-      break
     case 'MESSAGE_HANDLING_ERROR':
-      console.error(`Error handling event ${error.event}: ${error.error}`)
+      console.error(`Error handling message: ${error.error}`)
       break
     case 'EMIT_ERROR':
       console.error(`Error sending event ${error.event}: ${error.error}`)
@@ -275,6 +340,9 @@ wio.on('error', (error) => {
     case 'LISTENER_ERROR':
       console.error(`Error in listener for ${error.event}: ${error.error}`)
       break
+    case 'RATE_LIMIT_EXCEEDED':
+      console.warn(`Rate limit exceeded: ${error.current}/${error.limit} messages/second`)
+      break
     case 'NO_CONNECTION':
       console.error(`Attempted to send ${error.event} without connection`)
       break
@@ -308,15 +376,15 @@ console.log(`${stats.queuedMessages} messages queued`)
 - **`onceAsync(event)`** - Wait for single event (Promise)
 
 #### Utility Methods
-- **`getStats()`** - Get connection statistics
+- **`getStats()`** - Get connection statistics including readiness states
 - **`clearQueue()`** - Clear queued messages
 - **`getInjectedJavaScript()`** - Get JavaScript to inject into WebView
 
 #### Connection Methods
-- **`initiate(webViewRef, origin)`** - Establish connection (WEBVIEW peer only)
-- **`listen(hostOrigin?)`** - Listen for connection (EMBEDDED peer only)
+- **`initiate(webViewRef, origin)`** - Establish connection with retry logic (WEBVIEW peer only)
+- **`listen(hostOrigin?)`** - Listen for connection with readiness announcement (EMBEDDED peer only)
 - **`handleMessage(event)`** - Handle incoming message from WebView
-- **`disconnect(callback?)`** - Disconnect and cleanup
+- **`disconnect(callback?)`** - Disconnect and cleanup all resources
 - **`isConnected()`** - Check connection status
 
 #### Messaging Methods
@@ -329,11 +397,18 @@ console.log(`${stats.queuedMessages} messages queued`)
 ### Events
 
 #### Connection Events
-- **`connect`** - Connection established
+- **`connect`** - Connection established (after 3-way handshake)
 - **`disconnect`** - Connection lost with reason
+- **`connect_timeout`** - Initial connection failed after all attempts (NEW)
 - **`reconnecting`** - Reconnection attempt started
 - **`reconnection_failed`** - All reconnection attempts failed
 
+#### Internal Events (handled automatically)
+- **`__embedded_ready`** - EMBEDDED peer announces readiness
+- **`__connection_ack`** - Final acknowledgment in 3-way handshake
+- **`__heartbeat`** - Connection health check
+- **`__heartbeat_response`** - Heartbeat response
+
 #### Error Events
 - **`error`** - Various error conditions with detailed error objects
 
@@ -341,7 +416,7 @@ console.log(`${stats.queuedMessages} messages queued`)
 
 ```javascript
 import React, { useRef, useEffect, useState } from 'react'
-import { View, TouchableOpacity, Text, StyleSheet } from 'react-native'
+import { View, TouchableOpacity, Text, StyleSheet, ActivityIndicator } from 'react-native'
 import { WebView } from 'react-native-webview'
 import WIO from 'webview.io'
 
@@ -349,24 +424,41 @@ function App() {
   const webViewRef = useRef(null)
   const wioRef = useRef(null)
   const [isConnected, setIsConnected] = useState(false)
+  const [isConnecting, setIsConnecting] = useState(false)
+  const [connectionAttempts, setConnectionAttempts] = useState(0)
 
   useEffect(() => {
     wioRef.current = new WIO({ 
       type: 'WEBVIEW',
-      debug: true 
+      debug: true,
+      connectionTimeout: 10000,
+      connectionPingInterval: 2000,
+      maxConnectionAttempts: 5
     })
 
     wioRef.current.initiate(webViewRef, 'https://your-app.com')
+    setIsConnecting(true)
 
     wioRef.current
       .on('connect', () => {
         console.log('Connected!')
         setIsConnected(true)
+        setIsConnecting(false)
+        setConnectionAttempts(0)
       })
-      .on('disconnect', () => {
-        console.log('Disconnected!')
+      .on('disconnect', ({ reason }) => {
+        console.log('Disconnected:', reason)
         setIsConnected(false)
       })
+      .on('connect_timeout', ({ attempts }) => {
+        console.log(`Connection timeout after ${attempts} attempts`)
+        setIsConnecting(false)
+        setConnectionAttempts(attempts)
+      })
+      .on('reconnecting', ({ attempt, delay }) => {
+        console.log(`Reconnecting (${attempt})...`)
+        setIsConnecting(true)
+      })
       .on('location:picked', (location) => {
         console.log('User picked location:', location)
       })
@@ -378,13 +470,19 @@ function App() {
 
   const getLocation = async () => {
     try {
-      const location = await wioRef.current.emitAsync('get:location')
+      const location = await wioRef.current.emitAsync('get:location', null, 5000)
       console.log('Got location:', location)
     } catch (error) {
       console.error('Failed to get location:', error)
     }
   }
 
+  const retry = () => {
+    setConnectionAttempts(0)
+    setIsConnecting(true)
+    wioRef.current.initiate(webViewRef, 'https://your-app.com')
+  }
+
   return (
     <View style={styles.container}>
       <WebView
@@ -396,10 +494,29 @@ function App() {
       />
       
       <View style={styles.controls}>
-        <Text>Status: {isConnected ? 'Connected' : 'Disconnected'}</Text>
-        <TouchableOpacity onPress={getLocation}>
-          <Text>Get Location</Text>
-        </TouchableOpacity>
+        <View style={styles.status}>
+          {isConnecting && <ActivityIndicator />}
+          <Text>
+            Status: {isConnected ? 'Connected' : isConnecting ? 'Connecting...' : 'Disconnected'}
+          </Text>
+          {connectionAttempts > 0 && (
+            <Text style={styles.error}>
+              Failed after {connectionAttempts} attempts
+            </Text>
+          )}
+        </View>
+        
+        {isConnected && (
+          <TouchableOpacity style={styles.button} onPress={getLocation}>
+            <Text>Get Location</Text>
+          </TouchableOpacity>
+        )}
+        
+        {!isConnected && !isConnecting && (
+          <TouchableOpacity style={styles.button} onPress={retry}>
+            <Text>Retry Connection</Text>
+          </TouchableOpacity>
+        )}
       </View>
     </View>
   )
@@ -407,7 +524,10 @@ function App() {
 
 const styles = StyleSheet.create({
   container: { flex: 1 },
-  controls: { padding: 16 }
+  controls: { padding: 16 },
+  status: { flexDirection: 'row', alignItems: 'center', gap: 8, marginBottom: 12 },
+  error: { color: 'red', marginTop: 4 },
+  button: { padding: 12, backgroundColor: '#007AFF', borderRadius: 8, alignItems: 'center' }
 })
 ```
 
@@ -422,6 +542,9 @@ const options: Options = {
   type: 'WEBVIEW',
   debug: true,
   heartbeatInterval: 30000,
+  connectionTimeout: 10000,
+  connectionPingInterval: 2000,
+  maxConnectionAttempts: 5,
   maxMessageSize: 512 * 1024
 }
 
@@ -449,8 +572,6 @@ const response = await wio.emitAsync<{ query: string }, ApiResponse>(
 
 | Error Type | Description |
 |------------|-------------|
-| `INVALID_ORIGIN` | Message from unexpected origin |
-| `ORIGIN_MISMATCH` | Origin changed during session |
 | `MESSAGE_HANDLING_ERROR` | Error processing incoming message |
 | `EMIT_ERROR` | Error sending message |
 | `LISTENER_ERROR` | Error in event listener |
@@ -469,8 +590,55 @@ const response = await wio.emitAsync<{ query: string }, ApiResponse>(
 - **Rate Limiting**: Respect the `maxMessagesPerSecond` limit (default 100/sec)
 - **Queue Size**: Monitor queued messages to avoid memory issues
 - **Heartbeat**: Adjust `heartbeatInterval` based on your reliability needs
+- **Connection Timeout**: Configure `connectionTimeout` and `maxConnectionAttempts` based on network conditions
 - **Battery Impact**: Consider disabling heartbeat or increasing interval for battery-sensitive applications
 
+## Troubleshooting
+
+### Connection Never Establishes
+
+**Symptoms:** `connect_timeout` event fires, connection never succeeds
+
+**Solutions:**
+1. Check that `injectedJavaScript` is properly set on WebView
+2. Verify `javaScriptEnabled={true}` is set
+3. Check browser console for JavaScript errors in WebView
+4. Ensure origin matches exactly (including protocol)
+5. Increase `connectionTimeout` for slow networks
+6. Check that WebView content loads successfully
+
+### Messages Not Received
+
+**Symptoms:** `emit()` called but listener never fires
+
+**Solutions:**
+1. Verify connection is established (`isConnected()` returns true)
+2. Check that listener is registered before message is sent
+3. Look for errors in `error` event listener
+4. Check if rate limiting is being exceeded
+5. Verify message size is under `maxMessageSize`
+
+### Frequent Disconnections
+
+**Symptoms:** Constant `disconnect`/`reconnect` cycle
+
+**Solutions:**
+1. Increase `heartbeatInterval` to reduce network overhead
+2. Check network stability
+3. Look for memory issues or crashes in WebView
+4. Verify no conflicting JavaScript in WebView
+5. Check React Native debugger for errors
+
+### Race Conditions on Load
+
+**Symptoms:** Sometimes connects, sometimes doesn't
+
+**Solutions:**
+- Already handled! The three-way handshake with readiness announcements prevents this
+- EMBEDDED announces readiness periodically until connected
+- WEBVIEW retries connection attempts automatically
+- No action needed from your side
+
 ## Differences from iframe.io
 
 `webview.io` is adapted specifically for React Native and differs from `iframe.io` in the following ways:
@@ -480,6 +648,9 @@ const response = await wio.emitAsync<{ query: string }, ApiResponse>(
 - **Message Handling**: Requires explicit `handleMessage()` call in `onMessage` prop
 - **Injected Script**: Uses `getInjectedJavaScript()` to setup bridge in WebView
 - **No DOM Dependencies**: Works in React Native environment without DOM APIs
+- **Enhanced Handshake**: Three-way handshake with token validation for mobile reliability
+- **Connection Retry**: Built-in retry logic for spotty mobile connections
+- **Readiness Protocol**: Handles race conditions common in mobile WebView loading
 
 ## License
 

package/dist/index.d.ts

@@ -12,6 +12,8 @@ export type Options = {
     maxMessagesPerSecond?: number;
     autoReconnect?: boolean;
     messageQueueSize?: number;
+    connectionPingInterval?: number;
+    maxConnectionAttempts?: number;
 };
 export interface RegisteredEvents {
     [index: string]: Listener[];
@@ -22,6 +24,7 @@ export type Peer = {
     origin?: string;
     connected?: boolean;
     lastHeartbeat?: number;
+    embeddedReady?: boolean;
 };
 export type MessageData = {
     _event: string;
@@ -29,6 +32,7 @@ export type MessageData = {
     cid: string | undefined;
     timestamp?: number;
     size?: number;
+    token?: string;
 };
 export type Message = {
     data: MessageData;
@@ -45,10 +49,15 @@ export default class WIO {
     options: Options;
     private heartbeatTimer?;
     private reconnectTimer?;
+    private connectionAttemptTimer?;
+    private connectionPingInterval?;
+    private embeddedReadyCheckInterval?;
     private messageQueue;
     private messageRateTracker;
     private reconnectAttempts;
     private maxReconnectAttempts;
+    private connectionToken?;
+    private connectionAttempts;
     constructor(options?: Options);
     debug(...args: any[]): void;
     isConnected(): boolean;
@@ -56,6 +65,10 @@ export default class WIO {
     private stopHeartbeat;
     private handleConnectionLoss;
     private attemptReconnection;
+    private startConnectionAttempt;
+    private stopConnectionAttempt;
+    private announceEmbeddedReady;
+    private stopEmbeddedReadyAnnouncement;
     private checkRateLimit;
     private queueMessage;
     private processMessageQueue;
@@ -65,12 +78,10 @@ export default class WIO {
     initiate(webViewRef: RefObject<WebView>, origin: string): this;
     /**
      * Listening to connection from the WebView host
-     * Note: In React Native context, this is handled by injected JavaScript
      */
     listen(hostOrigin?: string): this;
     /**
      * Handle incoming message from WebView
-     * Called by React Native component via onMessage prop
      */
     handleMessage(event: {
         nativeEvent: {
@@ -90,11 +101,13 @@ export default class WIO {
     disconnect(fn?: () => void): this;
     getStats(): {
         connected: boolean;
+        embeddedReady: boolean | undefined;
         peerType: PeerType;
         origin: string | undefined;
         lastHeartbeat: number | undefined;
         queuedMessages: number;
         reconnectAttempts: number;
+        connectionAttempts: number;
         activeListeners: number;
         messageRate: number;
     };