100 lines
4.4 KiB
Markdown
100 lines
4.4 KiB
Markdown
---
|
|
phase: "14"
|
|
plan: "03"
|
|
type: execute
|
|
wave: 2
|
|
depends_on:
|
|
- "14-02"
|
|
files_modified:
|
|
- backend/services/cloud_byte_cache.py
|
|
- backend/api/cloud/cache.py
|
|
- backend/api/cloud/schemas.py
|
|
- backend/api/cloud/__init__.py
|
|
- backend/tests/test_cloud_cache.py
|
|
- backend/tests/test_cloud_security.py
|
|
autonomous: true
|
|
requirements:
|
|
- CACHE-03
|
|
- CACHE-04
|
|
- CACHE-05
|
|
---
|
|
|
|
<objective>
|
|
Implement the owner-scoped byte cache service and read/control API: cache lookup, retain, pin/release, per-user LRU eviction, quota accounting, settings update, and metadata-safe cache status responses.
|
|
|
|
Scope fence: do not wire analysis workers or open/preview hydration yet. This plan builds the cache primitive those paths will call.
|
|
</objective>
|
|
|
|
<context>
|
|
@.planning/phases/14-selective-analysis-and-byte-cache/14-RESEARCH.md
|
|
@.planning/phases/14-selective-analysis-and-byte-cache/14-PATTERNS.md
|
|
@backend/storage/minio_backend.py
|
|
@backend/services/cloud_items.py
|
|
@backend/db/models.py
|
|
@backend/api/cloud/schemas.py
|
|
</context>
|
|
|
|
<tasks>
|
|
|
|
<task type="auto">
|
|
<name>Task 1: Build cache service with quota and pinning semantics</name>
|
|
<files>backend/services/cloud_byte_cache.py, backend/tests/test_cloud_cache.py</files>
|
|
<read_first>
|
|
- backend/storage/minio_backend.py
|
|
- backend/services/quota.py
|
|
- backend/db/models.py
|
|
- backend/tests/test_quota.py
|
|
</read_first>
|
|
<action>
|
|
Add cache service functions to resolve owned cache entries, reserve quota atomically before retaining bytes, store bytes using UUID/private object keys, record metadata, reuse matching non-evicted version entries, pin/release active job or preview use, update last access, evict inactive LRU entries per user limit, decrement quota when retained bytes are evicted, and delete MinIO objects best-effort after DB state is consistent. Protect entries with `pin_count > 0` or `active_job_count > 0`.
|
|
</action>
|
|
<acceptance_criteria>
|
|
- Cache retention increments quota and eviction decrements quota with atomic quota helpers.
|
|
- Eviction never selects another user's entry and never evicts pinned/active entries.
|
|
- Object keys are generated UUID/private keys and never include provider filenames.
|
|
- Service functions raise domain errors or `ValueError`, never `HTTPException`.
|
|
</acceptance_criteria>
|
|
<verify><automated>cd backend && pytest -q tests/test_cloud_cache.py</automated></verify>
|
|
</task>
|
|
|
|
<task type="auto">
|
|
<name>Task 2: Add cache settings/status API</name>
|
|
<files>backend/api/cloud/cache.py, backend/api/cloud/schemas.py, backend/api/cloud/__init__.py, backend/tests/test_cloud_cache.py, backend/tests/test_cloud_security.py</files>
|
|
<read_first>
|
|
- backend/api/cloud/connections.py
|
|
- backend/api/cloud/operations.py
|
|
- backend/api/cloud/schemas.py
|
|
- backend/tests/test_cloud_security.py
|
|
</read_first>
|
|
<action>
|
|
Add credential-free endpoints for current cache usage/settings and updating the user's preferred cache limit/progress/failure settings. Use explicit Pydantic fields only. Return aggregate bytes/counts and tier cap, not object keys. Enforce `get_regular_user`, owner scope, and rate limiting consistent with existing cloud routes.
|
|
</action>
|
|
<acceptance_criteria>
|
|
- Admin users are blocked.
|
|
- Responses contain no `object_key`, credentials, raw provider URLs, or extracted text.
|
|
- Invalid cache limits above the tier/admin cap return a controlled validation response.
|
|
- Security tests cover foreign user and admin-negative cases.
|
|
</acceptance_criteria>
|
|
<verify><automated>cd backend && pytest -q tests/test_cloud_cache.py tests/test_cloud_security.py -k "cache"</automated></verify>
|
|
</task>
|
|
|
|
</tasks>
|
|
|
|
<threat_model>
|
|
| Threat ID | Threat | Mitigation |
|
|
|-----------|--------|------------|
|
|
| T-14-06 | Cross-user cache access | All cache entry queries include user_id and connection_id; negative tests |
|
|
| T-14-07 | Quota race | Existing atomic quota update helpers required for retain/evict deltas |
|
|
| T-14-08 | Object key leakage | API schemas omit object_key and tests assert absence |
|
|
| T-14-09 | Active work eviction | Pin/active counters in selection predicate and regression tests |
|
|
</threat_model>
|
|
|
|
<verification>
|
|
1. `cd backend && pytest -q tests/test_cloud_cache.py`
|
|
2. `cd backend && pytest -q tests/test_cloud_security.py -k "cache"`
|
|
3. `rg "object_key|credentials_enc" backend/api/cloud/cache.py backend/api/cloud/schemas.py`
|
|
</verification>
|
|
|
|
<output>Create `.planning/phases/14-selective-analysis-and-byte-cache/14-03-SUMMARY.md` when complete.</output>
|
|
|