Mark Phase 4 as completed
This commit is contained in:
136
IMPLEMENTATION-PHASES.md
Normal file
136
IMPLEMENTATION-PHASES.md
Normal file
@@ -0,0 +1,136 @@
|
|||||||
|
# MemoriC Agent Direct-LAN + UI Roadmap (Phased)
|
||||||
|
|
||||||
|
## Summary
|
||||||
|
|
||||||
|
Shift agent architecture from localhost-only control to **LAN-capable agent endpoint** so phones can upload directly when on the same network, while keeping broker/tunnel path for remote/off-LAN cases.
|
||||||
|
Deliver in phases: architecture first, then safe storage migration UI, then direct-LAN data plane.
|
||||||
|
|
||||||
|
## Phase 1: Networking & Security Foundation
|
||||||
|
|
||||||
|
Status: ✅ Completed (2026-05-18)
|
||||||
|
|
||||||
|
- Replace localhost-only UI assumption with configurable bind strategy.
|
||||||
|
- Add agent listener config:
|
||||||
|
- `bind_host` (default: `0.0.0.0`)
|
||||||
|
- `bind_port`
|
||||||
|
- `allowed_subnets` (default: RFC1918 private ranges)
|
||||||
|
- Define auth model for LAN access (required before direct upload):
|
||||||
|
- Pairing token or short-lived device token
|
||||||
|
- Per-request auth on all mutable endpoints
|
||||||
|
- Add transport policy:
|
||||||
|
- HTTP for local development only
|
||||||
|
- TLS option planned for production LAN usage
|
||||||
|
- Threat model doc for LAN attack surface (unauthorized upload, path abuse, replay).
|
||||||
|
|
||||||
|
### Acceptance
|
||||||
|
|
||||||
|
- Agent can bind on LAN interface.
|
||||||
|
- Unauthorized requests are rejected.
|
||||||
|
- Private-network restrictions are enforceable via config.
|
||||||
|
|
||||||
|
## Phase 2: Agent UI v1 (Settings + Status Only)
|
||||||
|
|
||||||
|
Status: ✅ Completed (2026-05-18)
|
||||||
|
|
||||||
|
- Build local web UI served by agent, reachable over LAN per bind config.
|
||||||
|
- UI includes:
|
||||||
|
- Connection status (broker + LAN endpoint)
|
||||||
|
- Current storage directory
|
||||||
|
- Health indicators and recent errors
|
||||||
|
- No photo library management yet.
|
||||||
|
- API surface:
|
||||||
|
- `GET /api/status`
|
||||||
|
- `POST /api/storage/validate`
|
||||||
|
- `POST /api/storage/change`
|
||||||
|
- `GET /api/storage/migration`
|
||||||
|
|
||||||
|
### Acceptance
|
||||||
|
|
||||||
|
- User can open UI from another device on same network (authorized).
|
||||||
|
- Storage settings are visible and editable through UI.
|
||||||
|
|
||||||
|
## Phase 3: Storage Relocation with Safe Migration
|
||||||
|
|
||||||
|
Status: ✅ Completed (2026-05-18)
|
||||||
|
|
||||||
|
- Implement storage change flow with your rule:
|
||||||
|
- Destination must be empty.
|
||||||
|
- Migration behavior:
|
||||||
|
- Validate destination exists/is writable/is empty.
|
||||||
|
- Move files preserving paths.
|
||||||
|
- Rename when possible; copy+remove fallback for cross-device moves.
|
||||||
|
- Atomic cutover behavior:
|
||||||
|
- Active storage path switches only after migration completes successfully.
|
||||||
|
- On any failure, remain on old storage path and return detailed error report.
|
||||||
|
- Persist selected storage location in config file.
|
||||||
|
|
||||||
|
### Acceptance
|
||||||
|
|
||||||
|
- Successful migration moves all files and switches path.
|
||||||
|
- Failed migration never leaves partial active-path switch.
|
||||||
|
|
||||||
|
## Phase 4: Direct Phone-to-Agent Upload (LAN Data Plane)
|
||||||
|
|
||||||
|
Status: ✅ Completed (2026-05-18)
|
||||||
|
|
||||||
|
- Add authenticated upload endpoint on agent for same-network phone backup.
|
||||||
|
- Keep broker relay as fallback path when phone is off-LAN.
|
||||||
|
- Define upload routing policy:
|
||||||
|
- Phone tries direct agent first if discoverable/reachable.
|
||||||
|
- Falls back to broker if direct path fails.
|
||||||
|
- Add simple discovery approach (phase target):
|
||||||
|
- Agent publishes LAN endpoint hints (IP:port candidates) to broker on connect.
|
||||||
|
- Phone fetches broker-provided hints and attempts direct upload automatically.
|
||||||
|
- Manual endpoint entry remains available as override/debug path.
|
||||||
|
|
||||||
|
### Acceptance
|
||||||
|
|
||||||
|
- On same LAN, phone uploads directly to agent without broker relay.
|
||||||
|
- Off-LAN upload still works through broker fallback.
|
||||||
|
|
||||||
|
## Phase 5: Platform Integration & Hardening
|
||||||
|
|
||||||
|
- Align Linux service + Windows task launchers with new network/config settings.
|
||||||
|
- Add rate limits and upload size checks on LAN endpoint.
|
||||||
|
- Add migration/upload concurrency controls.
|
||||||
|
- Add operational logs/metrics for:
|
||||||
|
- Auth failures
|
||||||
|
- Direct vs broker upload ratio
|
||||||
|
- Migration outcomes and duration.
|
||||||
|
|
||||||
|
### Acceptance
|
||||||
|
|
||||||
|
- Windows and Linux agents behave consistently with LAN mode enabled.
|
||||||
|
- Security and reliability checks pass in repeated real-network tests.
|
||||||
|
|
||||||
|
## Public Interfaces / Config Additions
|
||||||
|
|
||||||
|
- Config fields:
|
||||||
|
- `storage_dir`
|
||||||
|
- `bind_host`
|
||||||
|
- `bind_port`
|
||||||
|
- `allowed_subnets`
|
||||||
|
- `auth_mode`
|
||||||
|
- `pairing_token` (or token issuer reference)
|
||||||
|
- New/extended APIs:
|
||||||
|
- `GET /api/status`
|
||||||
|
- `POST /api/storage/validate`
|
||||||
|
- `POST /api/storage/change`
|
||||||
|
- `GET /api/storage/migration`
|
||||||
|
- `POST /api/upload` (direct LAN upload)
|
||||||
|
- Existing broker protocol remains supported for fallback path.
|
||||||
|
|
||||||
|
## Test Plan
|
||||||
|
|
||||||
|
- Unit:
|
||||||
|
- Path validation, empty-destination rule, migration rollback behavior.
|
||||||
|
- Auth checks for all LAN-accessible endpoints.
|
||||||
|
- Integration:
|
||||||
|
- Same-LAN direct upload success.
|
||||||
|
- Broker fallback when direct upload unavailable.
|
||||||
|
- Migration under active upload load (defined behavior, no corruption).
|
||||||
|
- Platform:
|
||||||
|
- Windows + Linux startup/restart persistence and config application.
|
||||||
|
- Security:
|
||||||
|
- Unauthorized LAN client denied.
|
||||||
|
- Path traversal and invalid filename rejection.
|
||||||
Reference in New Issue
Block a user