67 lines
2.9 KiB
Markdown
67 lines
2.9 KiB
Markdown
# v0.3 Research: Pitfalls
|
|
|
|
**Milestone:** v0.3 Reimagining Cloud Storage integration
|
|
**Date:** 2026-06-17
|
|
|
|
## Major Risks
|
|
|
|
### Full Mirror by Accident
|
|
|
|
If analysis downloads every cloud file into MinIO, user quota and infrastructure cost explode. Treat bytes as temporary cache unless the user explicitly imports a file.
|
|
|
|
Prevention: separate cloud item metadata/index records from local `documents`; add cache limits and eviction tests early.
|
|
|
|
### Provider Capability Mismatch
|
|
|
|
OneDrive, Google Drive, Nextcloud, and generic WebDAV do not expose identical semantics. Google Workspace files, WebDAV path IDs, OneDrive item IDs, etag behavior, move/rename semantics, and preview support differ.
|
|
|
|
Prevention: model provider capabilities explicitly and disable unsupported actions with a clear reason.
|
|
|
|
### Search That Downloads on Query
|
|
|
|
Smart search must query persisted extracted text/embeddings. Downloading cloud bytes during search would be slow, expensive, and fragile.
|
|
|
|
Prevention: search only analyzed/indexed cloud item records; show unanalyzed items as out of search scope until analyzed.
|
|
|
|
### Stale or Wrong Results
|
|
|
|
Cloud files can change outside DocuVault. Search results become misleading if etags/versions are ignored.
|
|
|
|
Prevention: store last analyzed etag/version, mark stale when provider metadata changes, and re-analyze changed items.
|
|
|
|
### Destructive Action Surprise
|
|
|
|
Delete/move/rename in cloud mode changes the user's real provider storage, not a DocuVault copy.
|
|
|
|
Prevention: clear confirmations for destructive actions, audit logs, ownership checks, and provider-specific error handling.
|
|
|
|
### Credential and Token Drift
|
|
|
|
OAuth tokens expire or are revoked. WebDAV passwords/app tokens change. Background jobs may fail long after the user connected the provider.
|
|
|
|
Prevention: connection health state, reconnect flows, token refresh persistence, and failure states that stop retry storms.
|
|
|
|
### Blocking Event Loop or Worker Exhaustion
|
|
|
|
Provider SDKs may be synchronous and cloud downloads can be large.
|
|
|
|
Prevention: keep sync SDK calls in thread wrappers, stream/chunk large files, use Celery queues/rate limits, and retry external API failures with backoff.
|
|
|
|
### SSRF and URL Handling Regression
|
|
|
|
WebDAV/Nextcloud URLs are user-supplied. v0.1 already added SSRF guards; new action endpoints must preserve them.
|
|
|
|
Prevention: all WebDAV outbound paths go through existing validation utilities; never join raw user path strings into URLs without provider helper methods.
|
|
|
|
### Cache Privacy Leak
|
|
|
|
Cached bytes are sensitive document content. A shared cache path without user/item scoping could leak across users.
|
|
|
|
Prevention: cache keys include user id, connection id, item id, and etag; cache content is never served without current-user ownership checks.
|
|
|
|
### Runaway AI Cost
|
|
|
|
"Analyze all cloud documents" could enqueue thousands of files.
|
|
|
|
Prevention: preflight count/size estimate, explicit confirmation, quotas/rate limits, progress UI, cancellation, and retry controls.
|