# 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.