Chat Files

Peer-to-peer file transfer with WebRTC-first delivery and socket relay fallback.

Overview

chat_files provides file sharing within chat rooms. Files transfer directly between peers via WebRTC data channels when possible, falling back to a server-mediated socket relay when P2P connections can't be established. Files are cached locally in IndexedDB, and users who have downloaded a file become seeders for other peers. The module handles thumbnails for images, inline previews for media/PDF/text, and synchronized media playback across room participants.

Architecture

chat_files_server (nodejs)     chat_files_client (browser)
├── File metadata DB           ├── TransferManager (orchestration)
├── Seeder registry            ├── FileCache (IndexedDB)
├── Socket signal relay        ├── ChunkAccumulator
├── Relay chunk routing        ├── ChatFileCard (UI)
└── Preview size persistence   └── WebRTC DataChannel

Loaded by: chat.doh.yaml (no standalone package — part of core chat) Depends on: chat_server (rooms, messages, membership)

File Structure

Configuration

# pod.yaml override example
chat_files:
  max_file_size: 1073741824   # 1GB
  cache_max_bytes: 1000       # 1GB IndexedDB cache
  ice_servers:
    - urls: 'stun:stun.example.com:3478'
    - urls: 'turn:turn.example.com:3478'
      username: 'user'
      credential: 'pass'

Database Schema

File metadata shape (in chat.files):

{
  id: string,            // UUID
  room_id: string,
  name: string,          // Original filename
  size: number,          // Bytes
  mime_type: string,
  chunk_size: number,
  total_chunks: number,
  thumbnail: string,     // Base64 data URL (images only, capped at 50KB) or null
  sender: string,        // Username
  created_at: number     // Timestamp
}

Seeder record shape (in chat.file_seeds):

{
  id: string,            // "{file_id}:{username}"
  file_id: string,
  username: string,
  seeded_at: number
}

File message format (in chat.messages.content):

[FILE]{"file_id":"...","name":"...","size":123,"mime_type":"...","thumbnail":"..."}

REST API Reference

GET /api/chat/files/user

// Query params
{ room_id?: string, search?: string }
// Response
{
  files: [{
    id, name, size, mime_type, thumbnail, created_at,
    room_id, room_name, room_type, sender_chat_name
  }]
}

Socket Events Reference

File Sharing

Side effects: creates chat.files entry, registers sender as seeder, creates [FILE] message, broadcasts chat:message_received.

Peer Discovery

WebRTC Signaling

signal_type: 'offer' | 'answer' | 'ice-candidate'

Socket Relay Transfer

Relay chunks are base64-encoded. Acks sent every relay_batch_size (8) chunks.

Seeding & Sync

action: 'play' | 'pause' | 'seek'

Transfer Flow

1. Check local memory (localFiles Map)
   └─ Found → complete (instant)

2. Check IndexedDB cache (FileCache)
   └─ Found → complete, register as seeder

3. Probe room peers (chat:file:probe, 3s timeout)
   └─ Peer responds → attempt transfer

4. Query seed registry (chat:file:request_peers)
   └─ Seeders found → attempt transfer

5. Wait passively (60s) for new seeders
   └─ chat:file:seeder_available / chat:room_peer_joined
   └─ Timeout → 'unavailable'

Transfer attempt:
  a. Try WebRTC DataChannel (10s timeout)
     └─ Success → complete, cache, register seeder
     └─ Fail → try next method

  b. Try socket relay (base64 chunks, batched with ack)
     └─ Success → complete, cache, register seeder
     └─ Fail → try next seeder, then give up

Client Architecture

TransferManager (Singleton)

Orchestrates all file transfers. Key methods:

FileCache (IndexedDB)

DB: doh_chat_files, store: files, indices: room_id, cached_at

ChunkAccumulator

Efficiently accumulates binary chunks, merging to Blob at the blob_merge_threshold to prevent memory pressure on large files.

ChatFileCard Pattern

Sub-objects: thumbEl, info (nameEl, metaEl), progressBar (fill), actionArea (downloadBtn, toggleBtn, cancelBtn, statusEl), previewArea, resizeHandle

Supports inline preview for images, video, audio, PDF, and text files. Previews are resizable with cross-peer size synchronization.

Testing

1. Share a file in a chat room — verify [FILE] message appears
2. Open a second browser/tab in the same room — download the file
3. Verify WebRTC transfer (check console for "WebRTC" transport label)
4. Test with WebRTC blocked (e.g., restrictive NAT) — verify socket relay fallback
5. Close all tabs, reopen — verify cached file loads from IndexedDB
6. Test media sync: play a video in one tab, verify playback syncs to other tabs