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:

// 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

// 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