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:

   {
     "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 | Next: Data Models