immish/docs/websocket.md

# WebSocket - Real-Time Updates

The app maintains a WebSocket connection to receive real-time updates from the server, enabling instant synchronization when changes occur.

## Connection Management

### Connection Setup

**WebSocket URL:** `{server-origin}/socket.io`

**Transport:** WebSocket (not polling)

**Options:**
- Auto-reconnection enabled
- Force new connection on each connect
- Custom WebSocket connector for SSL support

### Connection Lifecycle

```
┌─────────────────┐
│ User Logged In  │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│ Build Socket    │
│ with Auth       │
└────────┬────────┘
         │
         ▼
┌─────────────────┐     Reconnect
│ Connect         │◄───────────┐
└────────┬────────┘            │
         │                     │
         ▼                     │
┌─────────────────┐            │
│ onConnect       │            │
│ - Set connected │            │
│ - Start listen  │            │
└────────┬────────┘            │
         │                     │
         ▼                     │
┌─────────────────┐            │
│ Listen Events   │            │
└────────┬────────┘            │
         │                     │
    ┌────┴────┐                │
    │         │                │
    ▼         ▼                │
 Event     Error/              │
 Received  Disconnect          │
    │         │                │
    ▼         └────────────────┘
┌─────────────────┐
│ Process Event   │
└─────────────────┘
```

### Connection States

| State | Description |
|-------|-------------|
| Disconnected | Not connected to server |
| Connected | Active WebSocket connection |
| Reconnecting | Attempting to restore connection |

## Event Types

### Asset Events

| Event Name | Payload | Action |
|------------|---------|--------|
| `on_upload_success` | Asset JSON | Add new asset to timeline |
| `on_asset_delete` | Asset ID | Remove asset from local DB |
| `on_asset_trash` | Asset IDs array | Move assets to trash |
| `on_asset_restore` | - | Refresh all assets |
| `on_asset_update` | - | Refresh asset metadata |
| `on_asset_stack_update` | - | Refresh stacked assets |
| `on_asset_hidden` | Asset ID | Remove from visible timeline |

### Server Events

| Event Name | Payload | Action |
|------------|---------|--------|
| `on_config_update` | - | Refresh server features and config |
| `on_new_release` | Version info | Show update notification |

### Beta Timeline Events

| Event Name | Payload | Action |
|------------|---------|--------|
| `AssetUploadReadyV1` | Asset data | Sync new upload to timeline |
| `AssetEditReadyV1` | Edit data | Sync asset edit |

## Pending Changes System

Events are batched to prevent UI thrashing:

### Change Types

```
PendingAction:
- assetDelete: Asset was deleted
- assetUploaded: New asset uploaded
- assetHidden: Asset hidden from timeline
- assetTrash: Asset moved to trash
```

### Processing Flow

```
┌─────────────────┐
│ Event Received  │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│ Add to Pending  │
│ Changes List    │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│ Start Debounce  │
│ Timer (500ms)   │
└────────┬────────┘
         │
         ▼
  More Events?
    │       │
   Yes      No
    │       │
    ▼       ▼
 Reset   ┌─────────────────┐
 Timer   │ Process Batch   │
    │    │ - Uploads       │
    └───►│ - Deletes       │
         │ - Hidden        │
         │ - Trash         │
         └─────────────────┘
```

### Debouncing

**Standard Debounce:** 500ms
- Waits 500ms after last event before processing
- Prevents rapid UI updates during bulk operations

**Batch Debounce:** 5 seconds (max 10 seconds)
- For upload events
- Batches multiple uploads together
- Maximum wait time of 10 seconds

## Event Handlers

### Upload Success Handler

When a new asset is uploaded (from web or another device):

1. Receive asset JSON data
2. Add to pending changes
3. After debounce:
   - Parse asset response
   - Create local Asset object
   - Add to local database
   - Update timeline display

### Asset Delete Handler

When an asset is permanently deleted:

1. Receive asset ID
2. Add to pending changes
3. After debounce:
   - Remove from local database
   - Update timeline display

### Asset Trash Handler

When assets are moved to trash:

1. Receive array of asset IDs
2. Add to pending changes
3. After debounce:
   - Mark assets as trashed in local DB
   - Remove from main timeline
   - Refresh asset list

### Asset Hidden Handler

When an asset is hidden (moved to locked folder):

1. Receive asset ID
2. Add to pending changes
3. After debounce:
   - Remove from local database
   - Asset only visible in locked folder

### Config Update Handler

When server configuration changes:

1. Receive event (no payload)
2. Immediately refresh:
   - Server features
   - Server configuration

### Release Update Handler

When a new server version is available:

1. Receive version payload:
   ```json
   {
     "serverVersion": {"major": 1, "minor": 2, "patch": 3},
     "releaseVersion": {"major": 1, "minor": 3, "patch": 0}
   }
   ```
2. Parse version info
3. Update server info provider
4. Show update notification if applicable

## WebSocket State

```
WebsocketState:
- socket: The socket instance (or null if disconnected)
- isConnected: Boolean connection status
- pendingChanges: List of changes waiting to be processed
```

## Lifecycle Integration

### On App Start
1. Check if user is authenticated
2. If yes, connect WebSocket
3. Register event listeners

### On App Foreground
1. Reconnect if disconnected
2. Clear stale pending changes

### On App Background
1. Keep connection for brief period
2. Disconnect after timeout
3. Background service takes over

### On Logout
1. Disconnect WebSocket
2. Clear socket instance
3. Clear pending changes

## Error Handling

### Connection Errors
- Log error message
- Set state to disconnected
- Auto-reconnection handles recovery

### Event Processing Errors
- Log error with stack trace
- Continue processing other events
- Don't crash the app

## Switching Event Listeners

The app can switch between different event listener sets:

**Stop Old Events:**
```
- on_upload_success
- on_asset_delete
- on_asset_trash
- on_asset_restore
- on_asset_update
- on_asset_stack_update
- on_asset_hidden
```

**Start Beta Events:**
```
- AssetUploadReadyV1
- AssetEditReadyV1
```

This allows smooth transition between different sync implementations.

---

[Previous: Background Services](background-services.md) | [Next: Data Models](data-models.md)