talk2me/CONNECTION_RETRY.md

# Connection Retry Logic Documentation

This document explains the connection retry and network interruption handling features in Talk2Me.

## Overview

Talk2Me implements robust connection retry logic to handle network interruptions gracefully. When a connection is lost or a request fails due to network issues, the application automatically queues requests and retries them when the connection is restored.

## Features

### 1. Automatic Connection Monitoring
- Monitors browser online/offline events
- Periodic health checks to the server (every 5 seconds when offline)
- Visual connection status indicator
- Automatic detection when returning from sleep/hibernation

### 2. Request Queuing
- Failed requests are automatically queued during network interruptions
- Requests maintain their priority and are processed in order
- Queue persists across connection failures
- Visual indication of queued requests

### 3. Exponential Backoff Retry
- Failed requests are retried with exponential backoff
- Initial retry delay: 1 second
- Maximum retry delay: 30 seconds
- Backoff multiplier: 2x
- Maximum retries: 3 attempts

### 4. Connection Status UI
- Real-time connection status indicator (bottom-right corner)
- Offline banner with retry button
- Queue status showing pending requests by type
- Temporary status messages for important events

## User Experience

### When Connection is Lost

1. **Visual Indicators**:
   - Connection status shows "Offline" or "Connection error"
   - Red banner appears at top of screen
   - Queued request count is displayed

2. **Request Handling**:
   - New requests are automatically queued
   - User sees "Connection error - queued" message
   - Requests will be sent when connection returns

3. **Manual Retry**:
   - Users can click "Retry" button in offline banner
   - Forces immediate connection check

### When Connection is Restored

1. **Automatic Recovery**:
   - Connection status changes to "Connecting..."
   - Queued requests are processed automatically
   - Success message shown briefly

2. **Request Processing**:
   - Queued requests maintain their order
   - Higher priority requests (transcription) processed first
   - Progress indicators show processing status

## Configuration

The connection retry logic can be configured programmatically:

```javascript
// In app.ts or initialization code
connectionManager.configure({
    maxRetries: 3,           // Maximum retry attempts
    initialDelay: 1000,      // Initial retry delay (ms)
    maxDelay: 30000,         // Maximum retry delay (ms)
    backoffMultiplier: 2,    // Exponential backoff multiplier
    timeout: 10000,          // Request timeout (ms)
    onlineCheckInterval: 5000 // Health check interval (ms)
});
```

## Request Priority

Requests are prioritized as follows:
1. **Transcription** (Priority: 8) - Highest priority
2. **Translation** (Priority: 5) - Normal priority
3. **TTS/Audio** (Priority: 3) - Lower priority

## Error Types

### Retryable Errors
- Network errors
- Connection timeouts
- Server errors (5xx)
- CORS errors (in some cases)

### Non-Retryable Errors
- Client errors (4xx)
- Authentication errors
- Rate limit errors
- Invalid request errors

## Best Practices

1. **For Users**:
   - Wait for queued requests to complete before closing the app
   - Use the manual retry button if automatic recovery fails
   - Check the connection status indicator for current state

2. **For Developers**:
   - All fetch requests should go through RequestQueueManager
   - Use appropriate request priorities
   - Handle both online and offline scenarios in UI
   - Provide clear feedback about connection status

## Technical Implementation

### Key Components

1. **ConnectionManager** (`connectionManager.ts`):
   - Monitors connection state
   - Implements retry logic with exponential backoff
   - Provides connection state subscriptions

2. **RequestQueueManager** (`requestQueue.ts`):
   - Queues failed requests
   - Integrates with ConnectionManager
   - Handles request prioritization

3. **ConnectionUI** (`connectionUI.ts`):
   - Displays connection status
   - Shows offline banner
   - Updates queue information

### Integration Example

```typescript
// Automatic integration through RequestQueueManager
const queue = RequestQueueManager.getInstance();
const data = await queue.enqueue<ResponseType>(
    'translate',  // Request type
    async () => {
        // Your fetch request
        const response = await fetch('/api/translate', options);
        return response.json();
    },
    5  // Priority (1-10, higher = more important)
);
```

## Troubleshooting

### Connection Not Detected
- Check browser permissions for network status
- Ensure health endpoint (/health) is accessible
- Verify no firewall/proxy blocking

### Requests Not Retrying
- Check browser console for errors
- Verify request type is retryable
- Check if max retries exceeded

### Queue Not Processing
- Manually trigger retry with button
- Check if requests are timing out
- Verify server is responding

## Future Enhancements

- Persistent queue storage (survive page refresh)
- Configurable retry strategies per request type
- Network speed detection and adaptation
- Progressive web app offline mode