add docs part 2
This commit is contained in:
@@ -0,0 +1,291 @@
|
||||
# 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)
|
||||
Reference in New Issue
Block a user