curo1305
299d4b523d
- api/cloud/cache.py: GET /analysis/cache, PATCH /analysis/cache/settings - api/cloud/analysis.py: analysis router aggregator (Phase 14 parent) - schemas.py: CacheStatusOut, CacheSettingsUpdateRequest (explicit allowlists) - __init__.py: register analysis_router under /api/cloud - 7 new security tests: admin block, unauthenticated block, object_key exclusion, response structure, enum validation, tier cap enforcement (T-14-01..02, T-14-08) - All 47 plan target tests pass (test_cloud_cache.py + test_cloud_security.py)
258 lines
9.4 KiB
Python
258 lines
9.4 KiB
Python
"""
|
|
Whitelisted Pydantic response schemas for the cloud API package.
|
|
|
|
All schemas are explicit allowlists — credentials_enc, tokens, and passwords
|
|
are deliberately absent. T-12-03: credential exclusion by design.
|
|
|
|
Phase 13 additions:
|
|
- ConnectionHealthOut: typed health status response (D-12, CONN-03)
|
|
- ReconnectOut: typed reconnect response (CONN-01..03)
|
|
- ContentResultOut: typed open/preview/download response (D-02, D-18, T-13-14)
|
|
- MutationResultOut: typed kind/reason mutation response (D-05..11)
|
|
|
|
Phase 14 additions:
|
|
- CacheStatusOut: aggregate cache usage + settings response (T-14-02, T-14-08)
|
|
- CacheSettingsUpdateRequest: PATCH body for updating analysis settings/cache limit
|
|
"""
|
|
from __future__ import annotations
|
|
|
|
from datetime import datetime
|
|
from typing import List, Optional
|
|
|
|
from pydantic import BaseModel, Field, field_validator
|
|
|
|
|
|
# ── Capability / item schemas ─────────────────────────────────────────────────
|
|
|
|
class CloudCapabilityOut(BaseModel):
|
|
"""Whitelisted capability descriptor. reason/message only when not supported."""
|
|
|
|
action: str
|
|
state: str # "supported" | "unsupported" | "temporarily_unavailable"
|
|
reason: Optional[str] = None
|
|
message: Optional[str] = None
|
|
|
|
|
|
class CloudItemOut(BaseModel):
|
|
"""Normalized cloud item metadata. No credentials or byte content."""
|
|
|
|
id: str # DocuVault stable UUID
|
|
provider_item_id: str
|
|
name: str
|
|
kind: str # "file" | "folder"
|
|
parent_ref: Optional[str] = None
|
|
content_type: Optional[str] = None
|
|
size: Optional[int] = None
|
|
modified_at: Optional[datetime] = None
|
|
etag: Optional[str] = None
|
|
capabilities: dict[str, CloudCapabilityOut] = {}
|
|
|
|
|
|
# ── Freshness / folder state schemas ─────────────────────────────────────────
|
|
|
|
class FolderFreshnessOut(BaseModel):
|
|
"""Freshness and error state for a browsed folder."""
|
|
|
|
refresh_state: str # "fresh" | "refreshing" | "warning"
|
|
last_refreshed_at: Optional[datetime] = None
|
|
error_code: Optional[str] = None
|
|
error_message: Optional[str] = None
|
|
|
|
|
|
# ── Browse response ───────────────────────────────────────────────────────────
|
|
|
|
class CloudBrowseResponse(BaseModel):
|
|
"""Owner-scoped connection-ID browse response.
|
|
|
|
T-12-01: items are always scoped to the resolved connection which is owned
|
|
by the requesting user. credentials_enc is never included.
|
|
"""
|
|
|
|
connection_id: str
|
|
provider: str
|
|
display_name: str
|
|
parent_ref: Optional[str]
|
|
items: List[CloudItemOut]
|
|
capabilities: dict[str, CloudCapabilityOut]
|
|
freshness: FolderFreshnessOut
|
|
|
|
|
|
# ── Connection schemas ────────────────────────────────────────────────────────
|
|
|
|
class ConnectionRenameRequest(BaseModel):
|
|
"""Validated PATCH body for renaming a connection display name.
|
|
|
|
Only display_name is accepted — mass assignment prevention.
|
|
"""
|
|
|
|
display_name: str = Field(..., max_length=255)
|
|
|
|
@field_validator("display_name")
|
|
@classmethod
|
|
def must_be_nonblank(cls, v: str) -> str:
|
|
stripped = v.strip()
|
|
if not stripped:
|
|
raise ValueError("display_name must not be blank")
|
|
return stripped
|
|
|
|
|
|
# ── Phase 13 health / reconnect schemas ────────────────────────────────────────
|
|
|
|
class ConnectionHealthOut(BaseModel):
|
|
"""Typed connection health response.
|
|
|
|
D-12: Explicit health status available without probing on every browse.
|
|
CONN-03: Never exposes credentials_enc, tokens, or raw provider URLs.
|
|
|
|
status: 'healthy' | 'degraded' | 'auth_failed' | 'offline'
|
|
"""
|
|
|
|
status: str
|
|
connection_id: str
|
|
provider: str
|
|
display_name: Optional[str] = None
|
|
|
|
|
|
class ReconnectOut(BaseModel):
|
|
"""Typed reconnect result.
|
|
|
|
CONN-01: No new connection row created (reconnected patches in place).
|
|
CONN-02: credentials_enc updated with re-encrypted token.
|
|
CONN-03: No credentials, tokens, or provider URLs in response.
|
|
D-14: Cached metadata preserved as stale.
|
|
"""
|
|
|
|
status: str
|
|
connection_id: str
|
|
provider: str
|
|
display_name: Optional[str] = None
|
|
reconnected: bool = True
|
|
|
|
|
|
# ── Phase 13 content result schemas ───────────────────────────────────────────
|
|
|
|
class ContentResultOut(BaseModel):
|
|
"""Typed open/preview result body.
|
|
|
|
D-02: Provider credentials and raw provider URLs must never appear in responses.
|
|
D-18: Preview is binary-only; unsupported formats fall back to download fallback.
|
|
T-13-14: Stable kind/reason codes let the frontend route without parsing provider payloads.
|
|
|
|
kind: 'open' | 'preview' | 'download' | 'unsupported_preview'
|
|
reason: discriminator code (e.g. 'binary_supported', 'unsupported_format', 'authorized')
|
|
url: DocuVault-scoped authorized URL (never a raw provider URL)
|
|
"""
|
|
|
|
kind: str
|
|
reason: Optional[str] = None
|
|
url: Optional[str] = None
|
|
content_type: Optional[str] = None
|
|
|
|
|
|
# ── Phase 13 mutation result schemas ──────────────────────────────────────────
|
|
|
|
class MutationResultOut(BaseModel):
|
|
"""Typed mutation result body used by rename, move, delete, and create-folder.
|
|
|
|
T-13-14: Stable kind/reason codes let the frontend route without parsing
|
|
raw provider error payloads.
|
|
|
|
kind: 'renamed' | 'moved' | 'deleted' | 'folder' | 'conflict' | 'stale' |
|
|
'offline' | 'reauth_required' | 'invalid_destination' | 'unsupported_operation'
|
|
reason: discriminator detail (e.g. 'trashed', 'permanent', 'name_collision',
|
|
'item_changed', 'provider_unreachable', 'token_expired',
|
|
'self_destination', 'cross_connection', 'provider_unsupported')
|
|
"""
|
|
|
|
kind: str
|
|
reason: Optional[str] = None
|
|
name: Optional[str] = None
|
|
provider_item_id: Optional[str] = None
|
|
parent_ref: Optional[str] = None
|
|
|
|
|
|
# ── Phase 13 mutation request schemas ─────────────────────────────────────────
|
|
|
|
class CreateFolderRequest(BaseModel):
|
|
"""Request body for POST /connections/{id}/folders."""
|
|
parent_ref: Optional[str] = None
|
|
name: str = Field(..., max_length=255)
|
|
|
|
@field_validator("name")
|
|
@classmethod
|
|
def must_be_nonblank(cls, v: str) -> str:
|
|
stripped = v.strip()
|
|
if not stripped:
|
|
raise ValueError("name must not be blank")
|
|
return stripped
|
|
|
|
|
|
class RenameItemRequest(BaseModel):
|
|
"""Request body for PATCH /connections/{id}/items/{item_id}/rename."""
|
|
new_name: str = Field(..., max_length=255)
|
|
etag: Optional[str] = None
|
|
|
|
@field_validator("new_name")
|
|
@classmethod
|
|
def must_be_nonblank(cls, v: str) -> str:
|
|
stripped = v.strip()
|
|
if not stripped:
|
|
raise ValueError("new_name must not be blank")
|
|
return stripped
|
|
|
|
|
|
class MoveItemRequest(BaseModel):
|
|
"""Request body for POST /connections/{id}/items/{item_id}/move."""
|
|
destination_parent_ref: str
|
|
destination_connection_id: Optional[str] = None
|
|
etag: Optional[str] = None
|
|
|
|
|
|
# ── Phase 14 cache schemas ─────────────────────────────────────────────────────
|
|
|
|
class CacheStatusOut(BaseModel):
|
|
"""Aggregate cache usage and user analysis settings.
|
|
|
|
T-14-02: object_key, credentials_enc, and raw provider URLs are absent by
|
|
design. This schema is a strict allowlist — no internal MinIO keys or
|
|
credentials can leak through it.
|
|
|
|
entry_count: Number of active (non-evicted) cache entries.
|
|
total_bytes: Sum of size_bytes across active entries.
|
|
cache_limit_bytes: User's preferred cache byte ceiling.
|
|
tier_cap_bytes: Maximum allowed cache limit for this tier.
|
|
analysis_progress_detail: "simple" | "detailed" — default "simple".
|
|
analysis_failure_behavior:"pause_batch" | "continue_item" — default "pause_batch".
|
|
"""
|
|
|
|
entry_count: int = 0
|
|
total_bytes: int = 0
|
|
cache_limit_bytes: int
|
|
tier_cap_bytes: int
|
|
analysis_progress_detail: str
|
|
analysis_failure_behavior: str
|
|
|
|
|
|
class CacheSettingsUpdateRequest(BaseModel):
|
|
"""PATCH body for updating analysis preferences and cache limit.
|
|
|
|
Only provided (non-None) fields are applied. Enum validation and bounds
|
|
checking are performed in the service layer.
|
|
|
|
Mass-assignment prevention: only the three fields below are accepted.
|
|
"""
|
|
|
|
analysis_progress_detail: Optional[str] = Field(
|
|
default=None,
|
|
description="Progress label verbosity: 'simple' or 'detailed'",
|
|
)
|
|
analysis_failure_behavior: Optional[str] = Field(
|
|
default=None,
|
|
description="Batch failure mode: 'pause_batch' or 'continue_item'",
|
|
)
|
|
cloud_cache_limit_bytes: Optional[int] = Field(
|
|
default=None,
|
|
ge=1,
|
|
description="Preferred byte ceiling for the local byte cache",
|
|
)
|