cairnquire/docs/milestones/milestone-02-sync-protocol.md

Milestone 2: Sync Protocol

Duration: 2 weeks
Goal: Bidirectional file sync between server and filesystem/web client

Tasks

Week 3: Server-Side Sync

• Content-addressed filesystem implementation

  • SHA-256 hash computation
  • Directory layout: store/ab/cd/abcdef...
  • Write-once semantics
  • Deduplication verification

• File watcher (fsnotify)

  • Watch configured directory recursively
  • Debounce rapid changes (1s window)
  • Ignore patterns (.git, temp files)
  • Compute hash on change, update database

• WebSocket server

  • Connection management (connection pool)
  • Message framing and parsing
  • Authentication over WebSocket (token validation)
  • Heartbeat/ping-pong for connection health

• SimpleSync protocol server implementation

  • Sync request/response handler
  • Root hash computation (Merkle tree)
  • Missing content detection
  • Conflict detection logic

Week 4: Client-Side Sync & Offline Support

• WebSocket client (Preact)

  • Connection management with auto-reconnect
  • Message queue for offline periods
  • Exponential backoff for reconnection

• IndexedDB cache layer

  • Store file content by hash
  • Store sync state and pending changes
  • LRU eviction for cache management

• File sync UI

  • Sync status indicator
  • Offline mode banner
  • Pending changes list
  • Manual sync trigger button

• Conflict detection display

  • Visual indicator for conflicting files
  • Basic conflict resolution UI (choose local/server)

Acceptance Criteria

Functional

• File changes on disk automatically sync to server within 5 seconds
• Web client receives real-time updates when files change on server
• Client can make changes offline and sync when reconnected
• Concurrent edits to different files succeed without conflict
• Concurrent edits to same file detected as conflict
• Content hash verified on every transfer (client and server)
• Sync works across browser refresh (IndexedDB persistence)

Non-Functional

• WebSocket connections authenticated (reject unauthenticated)
• File watcher doesn't consume >1% CPU on idle
• IndexedDB storage cleared on logout
• Sync protocol documented with sequence diagrams

Performance

• Sync of 100 files completes in <10 seconds
• WebSocket message overhead <1KB per sync cycle
• File watcher detects changes within 500ms

Protocol Specification

Message Types

// Client → Server
interface SyncRequest {
  type: 'sync_request';
  clientId: string;
  rootHash: string;
  files: Record<string, string>; // path → hash
}

// Server → Client
interface SyncResponse {
  type: 'sync_response';
  serverRootHash: string;
  missingFromClient: string[]; // hashes to download
  missingFromServer: string[]; // hashes to upload
  conflicts: string[]; // file paths with conflicts
}

// Content request
interface ContentRequest {
  type: 'content_request';
  hash: string;
}

// Content response
interface ContentResponse {
  type: 'content_response';
  hash: string;
  content: string; // base64 encoded
}

State Machine

[Idle] --sync_request--> [Comparing] --has_differences--> [Transferring] --complete--> [Idle]
                                      --no_differences--> [Idle]
[Idle] --file_change--> [LocalChange] --sync--> [Comparing]

Deliverables

1. SimpleSync protocol specification document
2. Sequence diagrams for all sync scenarios
3. WebSocket API documentation
4. Offline sync test suite

Risk Mitigation

Risk	Mitigation
WebSocket connection drops frequently	Auto-reconnect with exponential backoff, queue offline
Large files cause sync delays	Chunked transfer, progress indicators, size limits
Conflicts in frequently edited files	Optimistic UI, clear conflict resolution, email notification

Definition of Done

• All acceptance criteria pass
• Sync protocol tested with 2+ concurrent clients
• Offline/online transition tested
• Performance benchmarks meet targets
• Documentation complete