john-okeefe
f859b2714d
- Move all files from bruno-yaml/* to bruno/* - Maintains existing directory structure within categories - Updates bruno/user/auth files with OAuth2 refresh token flow - Updates bruno/user/profile files for user profile management - Adds bruno/dashboard/ directory with dashboard API tests - Preserves all existing test scenarios and OpenCollection YAML format - No functional changes - file reorganization only
124 lines
3.4 KiB
YAML
124 lines
3.4 KiB
YAML
info:
|
|
name: Checkpoint Sync
|
|
type: http
|
|
seq: 11
|
|
|
|
http:
|
|
method: POST
|
|
url: '{{base_url}}/api/sync/koreader/progress'
|
|
auth: inherit
|
|
headers:
|
|
- key: Content-Type
|
|
value: application/json
|
|
body:
|
|
type: json
|
|
json:
|
|
sync_mode: checkpoint
|
|
checkpoint_id: checkpoint-uuid
|
|
since_timestamp: '2026-01-30T19:00:00Z'
|
|
books:
|
|
- uuid: book-uuid-1
|
|
percentage: 0.45
|
|
chapter: 3
|
|
- uuid: book-uuid-2
|
|
percentage: 0.75
|
|
chapter: 8
|
|
|
|
docs: |-
|
|
## Checkpoint Sync
|
|
|
|
Incremental sync using checkpoint-based change tracking.
|
|
|
|
**Method:** POST
|
|
|
|
**Endpoint:** /api/sync/koreader/progress
|
|
|
|
**Authentication:** Bearer token
|
|
|
|
**Request Body:**
|
|
- `sync_mode` (string): Must be `checkpoint`
|
|
- `checkpoint_id` (string): Unique checkpoint identifier
|
|
- `since_timestamp` (string): ISO 8601 timestamp for incremental sync
|
|
- `books` (array): Book progress items
|
|
- `uuid` (string): Book UUID
|
|
- `percentage` (number): Progress 0.0-1.0
|
|
- `chapter` (integer): Current chapter
|
|
- `epubcfi` (string, optional): Current position
|
|
- `modified_since` (boolean, optional): Whether modified since checkpoint
|
|
|
|
**Response:**
|
|
- `checkpoint_id` (string): Server checkpoint ID
|
|
- `checkpoint_timestamp` (string): Checkpoint creation time
|
|
- `processed` (integer): Books processed
|
|
- `changes_only` (boolean): Whether only changed items synced
|
|
- `next_checkpoint_id` (string): ID for next checkpoint sync
|
|
- `results` (array): Per-book results
|
|
|
|
**Status Codes:**
|
|
- 200: Checkpoint sync completed
|
|
- 401: Unauthorized
|
|
- 400: Invalid checkpoint or timestamp
|
|
|
|
**Checkpoint Sync Benefits:**
|
|
- **Incremental**: Only sync changed items
|
|
- **Efficient**: Smaller payloads
|
|
- **Fast**: Reduced processing time
|
|
- **Reliable**: Checkpoint-based tracking
|
|
- **Resumable**: Can continue from last checkpoint
|
|
|
|
**Checkpoint Mechanism:**
|
|
- Server tracks changes since checkpoint
|
|
- Client provides checkpoint ID or timestamp
|
|
- Only modified books returned/processed
|
|
- Checkpoint ID advances on each sync
|
|
- Supports large libraries efficiently
|
|
|
|
**Use Cases:**
|
|
- Large libraries (100+ books)
|
|
- Intermittent connectivity
|
|
- Bandwidth optimization
|
|
- Battery conservation
|
|
- Background sync
|
|
- Periodic sync (every 5-15 minutes)
|
|
|
|
**Checkpoint Lifecycle:**
|
|
1. Initial sync: No checkpoint (full sync)
|
|
2. Server returns checkpoint_id
|
|
3. Next sync: Client sends checkpoint_id
|
|
4. Server processes only changes
|
|
5. New checkpoint_id returned
|
|
6. Repeat from step 3
|
|
|
|
**Sync Optimization:**
|
|
- Only books with progress changes
|
|
- Skips unmodified books
|
|
- Delta transfer
|
|
- Compression for large payloads
|
|
- Batch processing
|
|
|
|
**Failure Handling:**
|
|
- Checkpoint ID preserved on failure
|
|
- Retry with same checkpoint
|
|
- Full sync if checkpoint expired
|
|
- Checkpoint validity: 24 hours
|
|
- Auto-fallback to full sync
|
|
|
|
**Performance:**
|
|
- Small changes (1-10 books): 100-300ms
|
|
- Medium changes (10-50 books): 300ms-1s
|
|
- Large changes (50-100 books): 1-3s
|
|
- Typical: 5-10x faster than full sync
|
|
|
|
**When to Use:**
|
|
- Default sync mode for most users
|
|
- Periodic background sync
|
|
- Large library management
|
|
- Mobile/network-constrained environments
|
|
- Battery-powered devices
|
|
|
|
**Configuration:**
|
|
- Checkpoint expiration: 24 hours
|
|
- Max history: 100 checkpoints
|
|
- Auto-cleanup of old checkpoints
|
|
- Configurable sync interval
|