Extend

2025-11-22 19:41:24 +00:00 · 2025-11-22 19:41:24 +00:00 · d590a2c9c8
commit d590a2c9c8
parent 511ac78e6d
8 changed files with 261 additions and 30 deletions
--- a/docs/guide/limitations.md
+++ b/docs/guide/limitations.md
@ -0,0 +1,192 @@
+# Limitations
+
+VaultLink works well for most Obsidian vaults, but has some constraints you should know about.
+
+## File Type Limitations
+
+### Mergeable Files
+
+Only **`.md`** and **`.txt`** files get automatic conflict-free merging.
+
+Other file types (images, PDFs, etc.) use last-write-wins:
+
+```
+User A updates diagram.png → Server stores version 1
+User B updates diagram.png → Server stores version 2 (overwrites A's changes)
+```
+
+**Workaround**: Avoid editing the same non-text file simultaneously.
+
+### Binary Detection
+
+Files are treated as binary if they:
+
+- Contain NUL bytes (`0x00`)
+- Fail UTF-8 validation
+
+Binary files within `.md` or `.txt` extensions still get last-write-wins (no merge).
+
+## Performance Constraints
+
+### Server Limits (Configurable)
+
+| Resource                 | Default | Maximum Tested |
+| ------------------------ | ------- | -------------- |
+| Clients per vault        | 256     | ~256           |
+| Database connections     | 12      | 20             |
+| Max file size            | 512 MB  | 4096 MB        |
+| Request timeout          | 60s     | 180s           |
+| WebSocket cursor timeout | 60s     | 300s           |
+| Database busy timeout    | 3600s   | -              |
+
+### Vault Size
+
+- **Small vaults** (< 1000 files): Excellent performance
+- **Medium vaults** (1000-10000 files): Good performance
+- **Large vaults** (> 10000 files): Works, but initial sync slower
+
+No hard file count limit—constrained by disk space and sync time.
+
+### Resource Usage
+
+Rough estimates (varies by vault size and activity):
+
+- **RAM**: ~50-200 MB base + ~1-5 MB per active client
+- **CPU**: Low (< 5%) for typical usage, spikes during merges
+- **Disk**: Vault size + version history (grows over time)
+
+## Version History
+
+### Storage
+
+- All versions stored indefinitely (no automatic cleanup)
+- Each vault is a separate SQLite database
+- Deleted files marked as deleted (not purged)
+
+**Growth**: Version history grows with every change. A 10 MB vault with frequent edits might grow to 100+ MB over months.
+
+**Cleanup**: Manual only (see [Advanced Configuration](/config/advanced#version-history-cleanup)).
+
+### Implications
+
+- Disk usage grows over time
+- Database size affects backup time
+- No built-in retention policy
+
+## Merge Quality
+
+### Text Merging
+
+VaultLink uses word-level tokenisation for merging:
+
+```markdown
+Parent: "The quick brown fox"
+User A: "The quick red fox"
+User B: "The very quick brown fox"
+Result: "The very quick red fox" ← Both changes preserved
+```
+
+**Imperfect scenarios**:
+
+- Complex nested Markdown (tables, code blocks)
+- Simultaneous edits to the same sentence
+- Large structural changes (moving sections around)
+
+**Result**: Merged file might need manual cleanup in ~1-5% of concurrent edits.
+
+## Scalability
+
+### SQLite Limitations
+
+- One SQLite database per vault
+- Single-server architecture (no built-in clustering)
+- Write serialisation through database
+
+**For high concurrency**: Consider multiple vaults instead of one massive shared vault.
+
+### Horizontal Scaling
+
+Not currently supported. Running multiple servers requires manual vault partitioning.
+
+## Network Requirements
+
+### Latency
+
+- Real-time sync typically < 500ms on good connections
+- Mobile/slow networks: 1-5s latency possible
+- Timeout failures on very slow connections (> 60s)
+
+### Offline Behaviour
+
+- Clients queue changes locally
+- On reconnect, sync all changes since last connection
+- Conflicts resolved automatically (for mergeable files)
+
+**Limitation**: No offline conflict preview—merged result appears after reconnect.
+
+## Security
+
+### No End-to-End Encryption
+
+- Server sees all file contents
+- Transport encryption only (WSS/TLS)
+- Trust your server
+
+**Workaround**: Self-host on infrastructure you control.
+
+### Authentication
+
+- Token-based only (no OAuth, SAML, etc.)
+- Tokens configured in server config file
+- No runtime user management
+
+## Known Edge Cases
+
+### Simultaneous Deletes and Edits
+
+```
+User A deletes note.md
+User B edits note.md
+Result: Edit wins (file recreated with B's content)
+```
+
+Operational transformation prioritises content preservation.
+
+### Large File Uploads
+
+Files > 100 MB may time out on slow connections. Increase `response_timeout_seconds` or split large files.
+
+### Mobile Sync
+
+- Mobile networks may drop WebSocket connections frequently
+- Client auto-reconnects, but causes sync delays
+- Battery impact from constant reconnections
+
+## What VaultLink is NOT
+
+- **Not a backup solution**: Version history helps but isn't a backup (make backups!)
+- **Not Git**: No branching, no commit messages, no diffs to review before merge
+- **Not encrypted storage**: Server sees everything
+- **Not multi-master**: One server, multiple clients (not peer-to-peer)
+
+## Recommendations
+
+### Good Use Cases
+
+- Personal multi-device sync (< 10 devices)
+- Small team collaboration (< 20 people)
+- Primarily text/Markdown content
+- Trusted server environment
+
+### Poor Use Cases
+
+- Large teams (> 50 concurrent users per vault)
+- Primarily binary files (images, videos, large PDFs)
+- Untrusted server (need E2E encryption)
+- Highly regulated environments (HIPAA, etc.)
+
+## Next Steps
+
+- [Server configuration limits →](/config/server)
+- [Advanced tuning →](/config/advanced)
+- [Architecture details →](/architecture/)