2.9 KiB
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.