Document Browser Inbox roadmap
This commit is contained in:
parent
58ac3e5336
commit
cff4577113
File diff suppressed because it is too large
Load Diff
|
|
@ -0,0 +1,228 @@
|
|||
# Sync Server & Plugin Design
|
||||
|
||||
## [S1] Problem
|
||||
|
||||
Verstak2 needs synchronization between devices. The old Verstak (`~/git/verstak`) has a working sync server and client, but Verstak2 is a platform architecture with plugins. Sync must be implemented as:
|
||||
1. A separate sync server repository
|
||||
2. A sync plugin that provides settings UI via the plugin manager
|
||||
|
||||
## [S2] Sync Server
|
||||
|
||||
### Location
|
||||
Separate repository: `verstak-sync-server`
|
||||
|
||||
### Source
|
||||
Based on `~/git/verstak/cmd/verstak-server/` with minimal changes.
|
||||
|
||||
### Structure
|
||||
```
|
||||
verstak-sync-server/
|
||||
cmd/server/main.go
|
||||
internal/
|
||||
server/
|
||||
server.go
|
||||
routes.go
|
||||
handlers_api.go
|
||||
handlers_auth.go
|
||||
handlers_admin.go
|
||||
middleware.go
|
||||
config.go
|
||||
schema.go
|
||||
tokens.go
|
||||
smtp.go
|
||||
go.mod
|
||||
go.sum
|
||||
README.md
|
||||
```
|
||||
|
||||
### API Endpoints
|
||||
- `POST /api/v1/sync/push` — push operations
|
||||
- `POST /api/v1/sync/pull` — pull operations
|
||||
- `POST /api/v1/blobs/` — upload blob (multipart)
|
||||
- `GET /api/v1/blobs/:sha256` — download blob
|
||||
- `POST /api/client/pair` — device pairing with login/password
|
||||
- `POST /api/auth/test` — test credentials
|
||||
- `GET /api/client/me` — device info
|
||||
- `POST /api/client/revoke-current` — revoke current device
|
||||
- `POST /api/client/revoke-device` — revoke specific device (web)
|
||||
- `GET /api/v1/health` — health check
|
||||
- Admin endpoints: `/admin/dashboard`, `/admin/users`, `/admin/api/stats`
|
||||
|
||||
### Config
|
||||
YAML file at `data/config.yml`:
|
||||
```yaml
|
||||
port: 47732
|
||||
admin:
|
||||
- username: admin
|
||||
password_hash: "$2a$10$..."
|
||||
```
|
||||
|
||||
### Database
|
||||
SQLite at `data/server.db` with tables:
|
||||
- `server_users` — user accounts
|
||||
- `server_devices` — paired devices
|
||||
- `server_ops` — sync operations
|
||||
- `server_tombstones` — deleted entities
|
||||
- `server_idempotency_keys` — idempotent push
|
||||
- `server_user_devices` — user-device mapping
|
||||
- `server_audit_log` — audit trail
|
||||
|
||||
## [S3] Sync Plugin
|
||||
|
||||
### Location
|
||||
`verstak-official-plugins/plugins/sync/`
|
||||
|
||||
### Manifest
|
||||
```json
|
||||
{
|
||||
"schemaVersion": 1,
|
||||
"id": "verstak.sync",
|
||||
"name": "Sync",
|
||||
"version": "0.1.0",
|
||||
"apiVersion": "0.1.0",
|
||||
"description": "Vault synchronization across devices via Verstak Sync Server.",
|
||||
"source": "official",
|
||||
"icon": "sync",
|
||||
"provides": ["verstak/sync/v1", "verstak/sync.status/v1"],
|
||||
"requires": ["verstak/core/files/v1"],
|
||||
"permissions": [
|
||||
"files.read",
|
||||
"files.write",
|
||||
"network.remote",
|
||||
"settings.read",
|
||||
"settings.write",
|
||||
"ui.register"
|
||||
],
|
||||
"frontend": {
|
||||
"entry": "frontend/dist/index.js"
|
||||
},
|
||||
"contributes": {
|
||||
"settingsPanels": [{
|
||||
"id": "verstak.sync.settings",
|
||||
"title": "Sync",
|
||||
"component": "SyncSettings"
|
||||
}],
|
||||
"statusBarItems": [{
|
||||
"id": "verstak.sync.status",
|
||||
"label": "Sync",
|
||||
"position": "right"
|
||||
}]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Capabilities Provided
|
||||
- `verstak/sync/v1` — sync provider capability
|
||||
- `verstak/sync.status/v1` — sync status provider
|
||||
|
||||
### Settings (Extended)
|
||||
The plugin stores settings via `settings.read/write` API:
|
||||
|
||||
| Key | Type | Default | Description |
|
||||
|-----|------|---------|-------------|
|
||||
| `serverUrl` | string | "" | Sync server URL |
|
||||
| `username` | string | "" | User login |
|
||||
| `password` | string | "" | User password (stored temporarily, not persisted) |
|
||||
| `syncInterval` | number | 0 | Auto-sync interval in minutes (0 = disabled) |
|
||||
| `autoSync` | boolean | false | Enable auto-sync |
|
||||
| `deviceName` | string | hostname | Device identifier |
|
||||
| `deviceId` | string | "" | Assigned device ID |
|
||||
| `deviceToken` | string | "" | Device auth token |
|
||||
| `lastStatus` | string | "disabled" | Connection status |
|
||||
| `lastSyncAt` | string | "" | Last successful sync timestamp |
|
||||
| `lastError` | string | "" | Last error message |
|
||||
|
||||
### Settings UI Component
|
||||
|
||||
`SyncSettings.svelte` — registered as settings panel via contributes.
|
||||
|
||||
**Two states:**
|
||||
|
||||
1. **Not configured** — setup form:
|
||||
- Server URL input
|
||||
- Username input
|
||||
- Password input
|
||||
- "Test Connection" button
|
||||
- "Connect" button
|
||||
|
||||
2. **Configured** — status view:
|
||||
- Status indicator (connected/disconnected/error/revoked)
|
||||
- Server URL display
|
||||
- Device Name display
|
||||
- Device ID display
|
||||
- Last Sync Time display
|
||||
- Last Error display (if any)
|
||||
- "Sync Now" button
|
||||
- "Disconnect" button
|
||||
- "Reset Key" button
|
||||
- Sync Interval input + Save button
|
||||
- Auto-sync toggle
|
||||
|
||||
### Backend Integration
|
||||
|
||||
The plugin uses VerstakPluginAPI to:
|
||||
- Read/write settings via `settings.read/write`
|
||||
- Call backend methods for sync operations
|
||||
|
||||
Backend methods needed in `verstak-desktop`:
|
||||
- `SyncStatus()` — get current sync status
|
||||
- `SyncConfigure(serverURL, username, password)` — pair device
|
||||
- `SyncDisconnect()` — disconnect and revoke
|
||||
- `SyncTestConnection(serverURL, username, password)` — test credentials
|
||||
- `SyncSetInterval(minutes)` — set auto-sync interval
|
||||
- `SyncNow()` — trigger immediate sync
|
||||
- `ResetSyncKey()` — clear device token
|
||||
|
||||
### Status Bar Item
|
||||
|
||||
Shows sync status in the bottom-right status bar:
|
||||
- Icon: sync icon
|
||||
- Label: status text (Connected/Disconnected/Error)
|
||||
- Click: opens plugin settings
|
||||
|
||||
## [S4] Data Flow
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────┐
|
||||
│ Verstak Desktop │
|
||||
│ ┌──────────────┐ ┌──────────────┐ ┌───────────┐ │
|
||||
│ │ Plugin Manager│───▶│ Sync Plugin │───▶│ Settings │ │
|
||||
│ │ (Settings) │ │ (UI Panel) │ │ API │ │
|
||||
│ └──────────────┘ └──────┬───────┘ └───────────┘ │
|
||||
│ │ │
|
||||
│ ┌──────────────────────────▼──────────────────────────┐│
|
||||
│ │ VerstakPluginAPI ││
|
||||
│ │ settings.read/write → files.read/write ││
|
||||
│ └──────────────────────────┬──────────────────────────┘│
|
||||
│ │ │
|
||||
│ ┌──────────────────────────▼──────────────────────────┐│
|
||||
│ │ Core Platform (Go Backend) ││
|
||||
│ │ SyncService: RecordOp, GetUnpushedOps, MarkPushed ││
|
||||
│ │ SyncClient: Push, Pull, UploadBlob, DownloadBlob ││
|
||||
│ └──────────────────────────┬──────────────────────────┘│
|
||||
└─────────────────────────────┼───────────────────────────┘
|
||||
│ HTTP
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────┐
|
||||
│ Verstak Sync Server │
|
||||
│ SQLite: users, devices, ops, tombstones │
|
||||
│ Blobs: SHA-256 content-addressed storage │
|
||||
│ API: push/pull, pair, auth, admin │
|
||||
└─────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
## [S5] Implementation Order
|
||||
|
||||
1. **Sync Server** — copy and adapt from `~/git/verstak/cmd/verstak-server/`
|
||||
2. **Backend API** — add sync methods to `verstak-desktop/internal/api/app.go`
|
||||
3. **Sync Plugin** — create plugin structure with manifest and frontend
|
||||
4. **Settings UI** — implement `SyncSettings.svelte` component
|
||||
5. **Status Bar** — add sync status indicator
|
||||
6. **Testing** — E2E tests for settings UI, integration tests for sync
|
||||
|
||||
## [S6] Testing Strategy
|
||||
|
||||
- **Unit tests**: Sync client (push/pull), settings read/write
|
||||
- **E2E tests**: Settings UI (configure, disconnect, sync now)
|
||||
- **Integration tests**: Full sync cycle (two devices, push/pull)
|
||||
- **Manual verification**: Real sync server with two vault instances
|
||||
Loading…
Reference in New Issue