iframe.io 1.0.6 → 1.2.0

package/README.md

@@ -1,18 +1,19 @@
 # iframe.io
 
-Easy and friendly API to connect and interact between content window and its containing iframe with enhanced features like heartbeat monitoring, automatic reconnection, message queuing, and rate limiting.
+Easy and friendly API to connect and interact between content window and its containing iframe with enhanced security, reliability, and modern async/await support.
 
-## Features
+## New Features & Improvements
 
-- 🔄 **Bi-directional Communication** - Seamless messaging between parent window and iframe
-- 💓 **Heartbeat Monitoring** - Automatic connection health checking
-- 🔌 **Auto Reconnection** - Automatic reconnection with exponential backoff
-- 📦 **Message Queuing** - Queue messages when connection is lost
-- 🛡️ **Security** - Origin validation and message sanitization
-- ⚡ **Rate Limiting** - Prevent message flooding
-- 🎯 **Event System** - Robust event-driven architecture
-- ✨ **Promise Support** - Async/await compatible methods
-- 📊 **Connection Stats** - Real-time connection statistics
+### 🆕 Version 1.1.0 Updates
+
+- **🔒 Enhanced Security**: Origin validation, message sanitization, and payload size limits
+- **🔄 Auto-Reconnection**: Automatic reconnection with exponential backoff strategy
+- **💓 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
+- **🛡️ Comprehensive Error Handling**: Detailed error types and handling mechanisms
 
 ## Installation
 
@@ -20,429 +21,391 @@ Easy and friendly API to connect and interact between content window and its con
 npm install iframe.io
 ```
 
-## Quick Start
+## Basic Usage
 
-### Parent Window (WINDOW type)
+### Parent Window (WINDOW peer)
 
 ```javascript
 import IOF from 'iframe.io'
 
-// Create iframe and get reference
-const iframe = document.createElement('iframe')
-iframe.src = 'https://example.com/iframe-content'
-document.body.appendChild(iframe)
-
-// Initialize connection
-const iof = new IOF({ type: 'WINDOW', debug: true })
-
-iframe.onload = () => {
-  // Initiate connection with iframe
-  iof.initiate(iframe.contentWindow, 'https://example.com')
-  
-  // Listen for connection
-  iof.on('connect', () => {
-    console.log('Connected to iframe!')
-    
-    // Send message
-    iof.emit('hello', { message: 'Hello from parent!' })
-  })
-  
-  // Listen for messages
-  iof.on('response', (data) => {
-    console.log('Received:', data)
-  })
-}
+const iframe = document.getElementById('myIframe')
+const iframeIO = new IOF({
+  type: 'WINDOW',
+  debug: true
+})
+
+// Establish connection
+iframeIO.initiate(iframe.contentWindow, 'https://child-domain.com')
+
+// Listen for connection
+iframeIO.on('connect', () => {
+  console.log('Connected to iframe!')
+
+  // Send a message
+  iframeIO.emit('hello', { message: 'Hello from parent!' })
+})
+
+// Listen for messages
+iframeIO.on('response', (data) => {
+  console.log('Received:', data)
+})
 ```
 
-### Iframe Content (IFRAME type)
+### Child Window (IFRAME peer)
 
 ```javascript
 import IOF from 'iframe.io'
 
-// Create connection listener
-const iof = new IOF({ type: 'IFRAME', debug: true })
+const iframeIO = new IOF({
+  type: 'IFRAME',
+  debug: true
+})
 
 // Listen for parent connection
-iof.listen('https://parent-domain.com')
+iframeIO.listen('https://parent-domain.com')
 
 // Handle connection
-iof.on('connect', () => {
+iframeIO.on('connect', () => {
   console.log('Connected to parent!')
 })
 
 // Listen for messages
-iof.on('hello', (data, ack) => {
-  console.log('Received from parent:', data)
-  
+iframeIO.on('hello', (data) => {
+  console.log('Received:', data)
+
   // Send response
-  iof.emit('response', { message: 'Hello from iframe!' })
-  
-  // Acknowledge receipt (optional)
-  if (ack) ack(false, 'Message received')
+  iframeIO.emit('response', { received: true })
 })
 ```
 
-## API Reference
-
-### Constructor
+## Enhanced Configuration Options
 
 ```javascript
-new IOF(options?)
+const iframeIO = new IOF({
+  type: 'WINDOW',                    // 'WINDOW' or 'IFRAME'
+  debug: false,                      // Enable debug logging
+  heartbeatInterval: 30000,          // Heartbeat interval in ms (30s)
+  connectionTimeout: 10000,          // Connection timeout in ms (10s)
+  maxMessageSize: 1024 * 1024,       // Max message size in bytes (1MB)
+  maxMessagesPerSecond: 100,         // Rate limit (100 messages/second)
+  autoReconnect: true,               // Enable automatic reconnection
+  messageQueueSize: 50,              // Max queued messages when disconnected
+  allowedIncomingEvents: ['hello', 'response'], // Optional incoming event allowlist (non-reserved events)
+  validateIncoming: (event, payload, origin) => true // Optional custom incoming validator
+})
 ```
 
-#### Options
+## New Async/Await Support
 
-| Option | Type | Default | Description |
-|--------|------|---------|-------------|
-| `type` | `'WINDOW' \| 'IFRAME'` | `'IFRAME'` | Connection type |
-| `debug` | `boolean` | `false` | Enable debug logging |
-| `heartbeatInterval` | `number` | `30000` | Heartbeat interval in ms |
-| `connectionTimeout` | `number` | `10000` | Connection timeout in ms |
-| `maxMessageSize` | `number` | `1048576` | Max message size (1MB) |
-| `maxMessagesPerSecond` | `number` | `100` | Rate limit for messages |
-| `autoReconnect` | `boolean` | `true` | Enable auto reconnection |
-| `messageQueueSize` | `number` | `50` | Max queued messages |
+### Send Messages with Acknowledgments
 
-### Connection Methods
+```javascript
+// Send message and wait for acknowledgment with timeout
+try {
+  const response = await iframeIO.emitAsync('getData', { id: 123 }, 10000) // 10s timeout
+  console.log('Response:', response)
+} catch (error) {
+  console.error('Request failed:', error.message)
+}
 
-#### `initiate(contentWindow, iframeOrigin)`
+// Listen and acknowledge
+iframeIO.on('getData', async (data, ack) => {
+  try {
+    const result = await fetchData(data.id)
+    ack(false, result) // Success: ack(error, ...response)
+  } catch (error) {
+    ack(error.message) // Error: ack(errorMessage)
+  }
+})
+```
 
-Establish connection with an iframe (WINDOW type only).
+### Wait for Connection
 
 ```javascript
-iof.initiate(iframe.contentWindow, 'https://iframe-origin.com')
-```
+// Wait for connection with timeout
+try {
+  await iframeIO.connectAsync(5000) // 5 second timeout
+  console.log('Connection established!')
+} catch (error) {
+  console.error('Connection failed:', error.message)
+}
 
-**Parameters:**
-- `contentWindow` - The iframe's contentWindow
-- `iframeOrigin` - The iframe's origin URL
+// Wait for single event
+const userData = await iframeIO.onceAsync('userProfile')
+console.log('User data received:', userData)
+```
 
-#### `listen(hostOrigin?)`
+## Enhanced Connection Management
 
-Listen for connection from parent window (IFRAME type).
+### Auto-Reconnection
 
 ```javascript
-iof.listen('https://parent-origin.com') // Optional origin restriction
-```
+// Handle connection events
+iframeIO.on('disconnect', (data) => {
+  console.log('Disconnected:', data.reason)
+})
 
-**Parameters:**
-- `hostOrigin` (optional) - Restrict connections to specific origin
+iframeIO.on('reconnecting', (data) => {
+  console.log(`Reconnection attempt ${data.attempt}, delay: ${data.delay}ms`)
+})
 
-#### `disconnect(callback?)`
+iframeIO.on('reconnection_failed', (data) => {
+  console.error(`Failed to reconnect after ${data.attempts} attempts`)
+})
+```
 
-Disconnect and clean up all resources.
+### Connection Statistics
 
 ```javascript
-iof.disconnect(() => {
-  console.log('Disconnected!')
-})
+const stats = iframeIO.getStats()
+console.log(stats)
+// {
+//   connected: true,
+//   peerType: 'WINDOW',
+//   origin: 'https://example.com',
+//   lastHeartbeat: 1609459200000,
+//   queuedMessages: 0,
+//   reconnectAttempts: 0,
+//   activeListeners: 5,
+//   messageRate: 2
+// }
 ```
 
-### Messaging Methods
+## Security Features
 
-#### `emit(event, payload?, callback?)`
-
-Send a message to the peer.
+### Origin Validation
 
 ```javascript
-// Simple message
-iof.emit('myEvent', { data: 'hello' })
+// Strict origin checking
+iframeIO.listen('https://trusted-domain.com') // Only accept from this origin
 
-// With acknowledgment
-iof.emit('myEvent', { data: 'hello' }, (error, response) => {
-  if (error) {
-    console.error('Error:', error)
-  } else {
-    console.log('Response:', response)
+// Error handling for invalid origins
+iframeIO.on('error', (error) => {
+  if (error.type === 'INVALID_ORIGIN') {
+    console.log(`Rejected message from ${error.received}`)
   }
 })
-
-// Callback as second parameter
-iof.emit('myEvent', (error, response) => {
-  console.log('Response:', response)
-})
 ```
 
-#### `on(event, listener)`
-
-Add event listener.
+### Message Sanitization
 
 ```javascript
-iof.on('myEvent', (data, ack) => {
-  console.log('Received:', data)
-  
-  // Send acknowledgment (optional)
-  if (ack) ack(false, 'Success response')
+// Automatic payload sanitization removes functions and undefined values
+iframeIO.emit('data', {
+  text: 'Hello',
+  func: () => {}, // Functions are automatically removed
+  undef: undefined // Undefined values are automatically removed
 })
 ```
 
-#### `once(event, listener)`
-
-Add one-time event listener.
+### Rate Limiting
 
 ```javascript
-iof.once('myEvent', (data) => {
-  console.log('This will only fire once:', data)
+const iframeIO = new IOF({
+  maxMessagesPerSecond: 10 // Limit to 10 messages per second
 })
-```
-
-#### `off(event, listener?)`
-
-Remove event listener(s).
-
-```javascript
-// Remove specific listener
-iof.off('myEvent', myListener)
 
-// Remove all listeners for event
-iof.off('myEvent')
+iframeIO.on('error', (error) => {
+  if (error.type === 'RATE_LIMIT_EXCEEDED') {
+    console.log(`Rate limited: ${error.current}/${error.limit}`)
+  }
+})
 ```
 
-#### `removeListeners(callback?)`
+### Incoming Event Allowlist & Validation
 
-Remove all event listeners.
+For defense-in-depth, you can restrict which **application-level** events are accepted and/or validate incoming payloads. Reserved internal events (`ping`, `pong`, `__heartbeat`, `__heartbeat_response`) are always allowed.
 
 ```javascript
-iof.removeListeners(() => {
-  console.log('All listeners removed')
+const iframeIO = new IOF({
+  type: 'IFRAME',
+  debug: true,
+  allowedIncomingEvents: ['getData', 'hello'],
+  validateIncoming: (event, payload, origin) => {
+    // Example: basic shape checks
+    if (event === 'getData') return payload && typeof payload.id === 'number'
+    return true
+  }
 })
-```
 
-### Async Methods
-
-#### `emitAsync(event, payload?)`
-
-Send message and return Promise.
-
-```javascript
-try {
-  const response = await iof.emitAsync('getData', { id: 123 })
-  console.log('Response:', response)
-} catch (error) {
-  console.error('Error:', error)
-}
+iframeIO.on('error', (error) => {
+  if (error.type === 'DISALLOWED_EVENT' || error.type === 'INVALID_MESSAGE') {
+    console.warn('Dropped incoming message:', error)
+  }
+})
 ```
 
-#### `onceAsync(event)`
-
-Wait for single event occurrence.
+## Comprehensive Error Handling
 
 ```javascript
-const data = await iof.onceAsync('dataReady')
-console.log('Data received:', data)
+iframeIO.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}`)
+      break
+    case 'EMIT_ERROR':
+      console.error(`Error sending event ${error.event}: ${error.error}`)
+      break
+    case 'LISTENER_ERROR':
+      console.error(`Error in listener for ${error.event}: ${error.error}`)
+      break
+    case 'NO_CONNECTION':
+      console.error(`Attempted to send ${error.event} without connection`)
+      break
+    default:
+      console.error('Unknown error:', error)
+  }
+})
 ```
 
-#### `connectAsync(timeout?)`
-
-Wait for connection to be established.
+## Message Queuing
 
 ```javascript
-try {
-  await iof.connectAsync(5000) // 5 second timeout
-  console.log('Connected!')
-} catch (error) {
-  console.error('Connection timeout')
-}
-```
-
-### Utility Methods
+// Messages are automatically queued when disconnected
+iframeIO.emit('important-data', { data: 'This will be queued if disconnected' })
 
-#### `isConnected()`
+// Clear queue manually if needed
+iframeIO.clearQueue()
 
-Check if connection is active.
-
-```javascript
-if (iof.isConnected()) {
-  console.log('Connection is active')
-}
+// Check queue status
+const stats = iframeIO.getStats()
+console.log(`${stats.queuedMessages} messages queued`)
 ```
 
-#### `getStats()`
-
-Get connection statistics.
+## API Reference
 
-```javascript
-const stats = iof.getStats()
-console.log('Stats:', stats)
-/*
-{
-  connected: true,
-  peerType: 'WINDOW',
-  origin: 'https://example.com',
-  lastHeartbeat: 1640995200000,
-  queuedMessages: 0,
-  reconnectAttempts: 0,
-  activeListeners: 5,
-  messageRate: 10
-}
-*/
-```
+### New Methods
 
-#### `clearQueue()`
+#### Async Methods
+- **`emitAsync(event, payload?, timeout?)`** - Send message and wait for response (Promise)
+- **`connectAsync(timeout?)`** - Wait for connection with timeout (Promise)
+- **`onceAsync(event)`** - Wait for single event (Promise)
 
-Clear queued messages.
+#### Utility Methods
+- **`getStats()`** - Get connection statistics
+- **`clearQueue()`** - Clear queued messages
 
-```javascript
-iof.clearQueue()
-```
+### Connection Methods
 
-## Events
+- **`initiate(contentWindow, iframeOrigin)`** - Establish connection (WINDOW peer only)
+- **`listen(hostOrigin?)`** - Listen for connection (IFRAME peer only)
+- **`disconnect(callback?)`** - Disconnect and cleanup
+- **`isConnected()`** - Check connection status
 
-### Built-in Events
+### Messaging Methods
 
-| Event | Description | Data |
-|-------|-------------|------|
-| `connect` | Connection established | - |
-| `disconnect` | Connection lost | `{ reason: string }` |
-| `reconnecting` | Reconnection attempt | `{ attempt: number, delay: number }` |
-| `reconnection_failed` | All reconnection attempts failed | `{ attempts: number }` |
-| `error` | Error occurred | `{ type: string, ...details }` |
+- **`emit(event, payload?, callback?)`** - Send message
+- **`on(event, listener)`** - Add event listener
+- **`once(event, listener)`** - Add one-time event listener
+- **`off(event, listener?)`** - Remove event listener(s)
+- **`removeListeners(callback?)`** - Remove all listeners
 
-### Error Types
+### Events
 
-- `RATE_LIMIT_EXCEEDED` - Message rate limit exceeded
-- `MESSAGE_HANDLING_ERROR` - Error processing received message
-- `EMIT_ERROR` - Error sending message
-- `LISTENER_ERROR` - Error in event listener
-- `INVALID_ORIGIN` - Message from unauthorized origin
-- `ORIGIN_MISMATCH` - Origin doesn't match established connection
-- `NO_CONNECTION` - Attempted to send without connection
+#### Connection Events
+- **`connect`** - Connection established
+- **`disconnect`** - Connection lost with reason
+- **`reconnecting`** - Reconnection attempt started
+- **`reconnection_failed`** - All reconnection attempts failed
 
-## Advanced Usage
+#### Error Events
+- **`error`** - Various error conditions with detailed error objects
 
-### Message Acknowledgments
+## TypeScript Support
 
-```javascript
-// Sender
-iof.emit('processData', { data: [...] }, (error, result) => {
-  if (error) {
-    console.error('Processing failed:', error)
-  } else {
-    console.log('Processing result:', result)
-  }
-})
+Full TypeScript support with comprehensive type definitions:
 
-// Receiver
-iof.on('processData', async (data, ack) => {
-  try {
-    const result = await processData(data.data)
-    ack(false, result) // Success: ack(error, ...args)
-  } catch (error) {
-    ack(error.message) // Error: ack(errorMessage)
-  }
-})
-```
+```typescript
+import IOF, { Options, Listener, AckFunction } from 'iframe.io'
 
-### Connection Monitoring
+const options: Options = {
+  type: 'WINDOW',
+  debug: true,
+  heartbeatInterval: 30000,
+  maxMessageSize: 512 * 1024
+}
 
-```javascript
-const iof = new IOF({
-  heartbeatInterval: 10000, // 10 seconds
-  connectionTimeout: 5000,  // 5 seconds
-  autoReconnect: true
-})
+const iframeIO = new IOF(options)
 
-iof.on('disconnect', ({ reason }) => {
-  console.log('Connection lost:', reason)
+// Typed event listeners
+iframeIO.on('userAction', (data: { action: string; userId: number }) => {
+  console.log(`User ${data.userId} performed ${data.action}`)
 })
 
-iof.on('reconnecting', ({ attempt, delay }) => {
-  console.log(`Reconnecting (${attempt}/5) in ${delay}ms`)
-})
+// Typed async responses
+interface ApiResponse {
+  success: boolean
+  data: any[]
+}
 
-iof.on('reconnection_failed', ({ attempts }) => {
-  console.log(`Failed to reconnect after ${attempts} attempts`)
-})
+const response = await iframeIO.emitAsync<{ query: string }, ApiResponse>(
+  'search',
+  { query: 'hello' },
+  5000 // 5 second timeout
+)
 ```
 
-### Message Queuing
+## Error Types Reference
 
-```javascript
-const iof = new IOF({
-  messageQueueSize: 100,
-  autoReconnect: true
-})
+| 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 |
+| `DISALLOWED_EVENT` | Incoming event rejected by `allowedIncomingEvents` |
+| `INVALID_MESSAGE` | Incoming message rejected by `validateIncoming` |
+| `RATE_LIMIT_EXCEEDED` | Too many messages sent |
+| `NO_CONNECTION` | Attempted to send without connection |
 
-// Messages sent while disconnected are automatically queued
-iof.emit('queuedMessage', { data: 'This will be queued if disconnected' })
+## Browser Compatibility
 
-// Check queue status
-const stats = iof.getStats()
-console.log(`Queued messages: ${stats.queuedMessages}`)
-```
+- Chrome 60+
+- Firefox 55+
+- Safari 12+
+- Edge 79+
 
-### Rate Limiting
+## Migration Guide
 
-```javascript
-const iof = new IOF({
-  maxMessagesPerSecond: 50,
-  maxMessageSize: 512 * 1024 // 512KB
-})
+### From v1.0.x to v1.1.0
 
-iof.on('error', ({ type, limit, current }) => {
-  if (type === 'RATE_LIMIT_EXCEEDED') {
-    console.log(`Rate limit exceeded: ${current}/${limit} messages per second`)
-  }
-})
-```
-
-### Security Best Practices
+All existing code continues to work without changes. New features are additive:
 
 ```javascript
-// Always specify allowed origins
-iof.listen('https://trusted-parent.com')
-
-// Handle security errors
-iof.on('error', ({ type, expected, received }) => {
-  if (type === 'INVALID_ORIGIN') {
-    console.warn(`Rejected message from ${received}, expected ${expected}`)
-  }
-})
-
-// Validate message content
-iof.on('userData', (data, ack) => {
-  if (!isValidUserData(data)) {
-    return ack('Invalid data format')
+// Old way (still works)
+iframeIO.emit('getData', { id: 123 }, (error, result) => {
+  if (error) {
+    console.error('Error:', error)
+  } else {
+    console.log('Result:', result)
   }
-  // Process valid data...
 })
-```
-
-## Browser Support
-
-- Modern browsers with postMessage API support
-- Chrome 2+
-- Firefox 3+
-- Safari 4+
-- IE 8+
-- Edge (all versions)
-
-## TypeScript Support
-
-The library is written in TypeScript and includes full type definitions:
 
-```typescript
-import IOF, { Options, PeerType, AckFunction, Listener } from 'iframe.io'
-
-const options: Options = {
-  type: 'WINDOW',
-  debug: true,
-  heartbeatInterval: 15000
+// New async way
+try {
+  const result = await iframeIO.emitAsync('getData', { id: 123 })
+  console.log('Result:', result)
+} catch (error) {
+  console.error('Error:', error.message)
 }
+```
 
-const iof = new IOF(options)
-
-// Type-safe event handling
-iof.on('myEvent', (data: { message: string }, ack?: AckFunction) => {
-  console.log(data.message)
-  ack?.(false, 'success')
-})
+## Performance Considerations
 
-// Type-safe async emissions
-const response = await iof.emitAsync<{ query: string }, { result: any }>('search', { 
-  query: 'typescript' 
-})
-```
+- **Message Size**: Keep messages under the configured `maxMessageSize` (default 1MB)
+- **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
 
 ## License
 
@@ -456,4 +419,4 @@ Contributions are welcome! Please read our contributing guidelines and submit pu
 
 - Create an issue on GitHub for bug reports
 - Check existing issues for common problems
-- Review the documentation for usage examples
+- Review the documentation for usage examples