146 lines
4.4 KiB
Markdown
146 lines
4.4 KiB
Markdown
# Milestone 2: Sync Protocol
|
|
|
|
**Duration:** 2 weeks
|
|
**Goal:** Bidirectional file sync between server and filesystem/web client
|
|
|
|
## Tasks
|
|
|
|
### Week 3: Server-Side Sync
|
|
|
|
- [x] Content-addressed filesystem implementation
|
|
- [x] SHA-256 hash computation
|
|
- [x] Directory layout: `store/ab/cd/abcdef...`
|
|
- [x] Write-once semantics
|
|
- [x] Deduplication verification
|
|
|
|
- [x] File watcher (fsnotify)
|
|
- [x] Watch configured directory recursively
|
|
- [x] Debounce rapid changes
|
|
- [x] Ignore hidden paths and common editor temp files
|
|
- [x] Compute hash on change, update database
|
|
|
|
- [x] WebSocket server
|
|
- [x] Connection management (connection pool)
|
|
- [x] Message framing and parsing
|
|
- WebSocket authentication intentionally out of scope for Milestone 2
|
|
- [x] Heartbeat/ping-pong for connection health
|
|
|
|
- [x] SimpleSync protocol server implementation
|
|
- [x] Sync request/response handler
|
|
- [x] Root hash computation
|
|
- [x] Missing content detection
|
|
- [x] Conflict detection logic
|
|
|
|
### Week 4: Client-Side Sync & Offline Support
|
|
|
|
- [x] WebSocket client (Go-served UI)
|
|
- [x] Connection management with auto-reconnect
|
|
- [x] Message queue for offline periods
|
|
- [x] Reconnection after offline periods
|
|
|
|
- [x] IndexedDB cache layer
|
|
- [x] Store document/page content for offline reads
|
|
- [x] Store sync state and pending changes
|
|
- [x] Simple fixed cap for cached pages/content
|
|
- [x] Preserve pending edits during cache cleanup
|
|
|
|
- [x] File sync UI
|
|
- [x] Sync status indicator
|
|
- [x] Offline mode banner
|
|
- [x] Pending changes list
|
|
- [x] Manual sync trigger button
|
|
|
|
- [x] Conflict detection display
|
|
- [x] Visual indicator for conflicting files
|
|
- [x] Side-by-side diff for server copy vs queued edit
|
|
- [x] Conflict resolution UI with Monaco resolved document editor
|
|
|
|
## Acceptance Criteria
|
|
|
|
### Functional
|
|
- [x] File changes on disk automatically sync to server within 5 seconds
|
|
- [x] Web client receives real-time updates when files change on server
|
|
- [x] Client can make changes offline and sync when reconnected
|
|
- [x] Concurrent edits to different files succeed without conflict
|
|
- [x] Concurrent edits to same file detected as conflict
|
|
- [x] Content hash verified on every transfer (client and server)
|
|
- [x] Sync works across browser refresh (IndexedDB persistence)
|
|
|
|
### Non-Functional
|
|
- WebSocket authentication deferred to Milestone 3 application auth
|
|
- [ ] File watcher doesn't consume >1% CPU on idle
|
|
- IndexedDB logout clearing deferred to Milestone 3 application auth
|
|
- [x] Sync protocol documented with state/flow diagrams
|
|
|
|
### Performance
|
|
- [x] 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
|
|
|
|
```typescript
|
|
// 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. [x] SimpleSync protocol specification document
|
|
2. [x] State/flow diagrams for browser sync scenarios
|
|
3. [x] WebSocket message documentation
|
|
4. [x] Go-level offline/conflict sync test coverage
|
|
|
|
## 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
|
|
|
|
- [x] All Milestone 2 functional acceptance criteria pass
|
|
- [x] Sync protocol tested with 2+ concurrent clients
|
|
- [x] Offline/online transition tested
|
|
- [x] 100-file sync performance target validated
|
|
- [x] Documentation complete
|