feat(13-03): extend cloud contract with mutable adapter and provider implementations
- Add MutableCloudResourceAdapter abstract class to cloud_base.py with Phase 13 mutable-operation vocabulary (MUT_KIND_* / MUT_REASON_* constants, PreviewSupport) - Add abstract methods: create_folder, rename, move, delete, upload_file + _normalize_error - Update GoogleDriveBackend to implement MutableCloudResourceAdapter with Drive-scope methods; prefer trash() for delete (D-11); update SCOPES to drive (D-17) - Update OneDriveBackend to implement MutableCloudResourceAdapter; use PublicClientApplication for refresh_token flow; Graph DELETE is always permanent (D-11) - Update WebDAVBackend to implement MutableCloudResourceAdapter; SSRF guard via __init__ (not per-call) for mutable methods; _validate_destination for MOVE SSRF (T-13-04) - NextcloudBackend inherits all mutable methods from WebDAVBackend (no changes needed) - Add build_mutable_cloud_adapter() to cloud_backend_factory.py - All 184 tests pass (test_cloud_backends.py + test_cloud_provider_contract.py)
This commit is contained in:
curo1305
@@ -1,18 +1,24 @@
|
||||
"""
|
||||
Provider-neutral cloud resource capability contract for DocuVault Phase 12.
|
||||
Provider-neutral cloud resource capability and mutation contract for DocuVault.
|
||||
|
||||
Defines the stable vocabulary (action keys, capability states, reason codes),
|
||||
immutable normalized value types (CloudCapability, CloudResource, CloudListing),
|
||||
and the abstract CloudResourceAdapter read-only interface.
|
||||
immutable normalized value types (CloudCapability, CloudResource, CloudListing,
|
||||
mutation result types), and the abstract adapter interfaces:
|
||||
- CloudResourceAdapter — read-only browse/capability interface (Phase 12).
|
||||
- MutableCloudResourceAdapter — mutable-operation interface (Phase 13).
|
||||
|
||||
Design decisions (12-CONTEXT.md D-06 through D-10):
|
||||
Design decisions (12-CONTEXT.md D-06 through D-10, 13-CONTEXT.md D-01 through D-18):
|
||||
- Structurally unsupported actions remain visible but greyed out (D-06).
|
||||
- Capability discovery must never mutate provider content (D-08).
|
||||
- Permanent vs. temporary limitations have distinct visual states (D-09).
|
||||
- No mutation methods in Phase 12 contract; mutations added in Phase 13.
|
||||
- Mutable operations return typed result dicts — routers never parse raw
|
||||
provider error shapes (T-13-10).
|
||||
- Preview support is explicit and binary-only; Google Workspace and Office
|
||||
document preview/editing are excluded from Phase 13 (D-18).
|
||||
- Providers are never given permission to write audit rows or cloud_items
|
||||
directly — that is the service layer's responsibility (T-13-12).
|
||||
|
||||
Credentials are never fields on any value type. The interface contains no
|
||||
put, delete, rename, move, or create_folder methods.
|
||||
Credentials are never fields on any value type.
|
||||
"""
|
||||
from __future__ import annotations
|
||||
|
||||
@@ -243,3 +249,317 @@ class CloudResourceAdapter(ABC):
|
||||
message="This action is not supported by the provider.",
|
||||
)
|
||||
return merged
|
||||
|
||||
|
||||
# ── Mutable operation result kinds ────────────────────────────────────────────
|
||||
|
||||
# Stable kind vocabulary for mutation result dicts (T-13-10).
|
||||
# Routers and service layers must match these constants — never raw provider strings.
|
||||
|
||||
MUT_KIND_FOLDER = "folder" # create_folder succeeded
|
||||
MUT_KIND_UPLOADED = "uploaded" # upload_file succeeded
|
||||
MUT_KIND_UPDATED = "updated" # rename / move succeeded
|
||||
MUT_KIND_DELETED = "deleted" # delete succeeded
|
||||
MUT_KIND_CONFLICT = "conflict" # name collision detected
|
||||
MUT_KIND_STALE = "stale" # etag mismatch / item changed externally
|
||||
MUT_KIND_OFFLINE = "offline" # provider temporarily unreachable
|
||||
MUT_KIND_REAUTH = "reauth_required" # credential failure (not transient)
|
||||
MUT_KIND_UNSUPPORTED = "unsupported" # provider does not support this operation
|
||||
MUT_KIND_INVALID_DEST = "invalid_destination" # bad move destination (SSRF / self)
|
||||
MUT_KIND_ERROR = "error" # unclassified provider error
|
||||
|
||||
MUT_KINDS = frozenset({
|
||||
MUT_KIND_FOLDER, MUT_KIND_UPLOADED, MUT_KIND_UPDATED, MUT_KIND_DELETED,
|
||||
MUT_KIND_CONFLICT, MUT_KIND_STALE, MUT_KIND_OFFLINE, MUT_KIND_REAUTH,
|
||||
MUT_KIND_UNSUPPORTED, MUT_KIND_INVALID_DEST, MUT_KIND_ERROR,
|
||||
})
|
||||
|
||||
# Stable reason codes for mutation results
|
||||
MUT_REASON_CREATED = "created"
|
||||
MUT_REASON_RENAMED = "renamed"
|
||||
MUT_REASON_MOVED = "moved"
|
||||
MUT_REASON_TRASHED = "trashed"
|
||||
MUT_REASON_PERMANENT = "permanent"
|
||||
MUT_REASON_NAME_COLLISION = "name_collision"
|
||||
MUT_REASON_ITEM_CHANGED = "item_changed"
|
||||
MUT_REASON_PROVIDER_OFFLINE = "provider_offline"
|
||||
MUT_REASON_TOKEN_EXPIRED = "token_expired"
|
||||
MUT_REASON_INVALID_GRANT = "invalid_grant"
|
||||
MUT_REASON_NOT_SUPPORTED = "not_supported"
|
||||
MUT_REASON_SSRF_BLOCKED = "ssrf_blocked"
|
||||
MUT_REASON_SELF_MOVE = "self_or_descendant_move"
|
||||
MUT_REASON_PROVIDER_ERROR = "provider_error"
|
||||
|
||||
|
||||
# ── Preview support declaration ───────────────────────────────────────────────
|
||||
|
||||
class PreviewSupport:
|
||||
"""Explicit binary-only preview support declaration (D-18).
|
||||
|
||||
Providers declare support here rather than inferring it from MIME quirks.
|
||||
Google Workspace and Microsoft Office document rendering/editing are
|
||||
explicitly excluded from Phase 13 preview scope.
|
||||
"""
|
||||
|
||||
# MIME types with explicit binary preview support (D-18, Phase 13)
|
||||
SUPPORTED_BINARY_PREVIEW_TYPES: frozenset[str] = frozenset({
|
||||
"application/pdf",
|
||||
"image/jpeg",
|
||||
"image/png",
|
||||
"image/gif",
|
||||
"image/webp",
|
||||
"image/svg+xml",
|
||||
"text/plain",
|
||||
"text/html",
|
||||
"text/css",
|
||||
"text/javascript",
|
||||
"application/json",
|
||||
"application/xml",
|
||||
"text/xml",
|
||||
"text/markdown",
|
||||
"text/csv",
|
||||
})
|
||||
|
||||
# MIME types explicitly excluded from Phase 13 preview (D-18)
|
||||
EXCLUDED_FROM_PREVIEW: frozenset[str] = frozenset({
|
||||
# Google Workspace formats — require export, out of Phase 13 scope
|
||||
"application/vnd.google-apps.document",
|
||||
"application/vnd.google-apps.spreadsheet",
|
||||
"application/vnd.google-apps.presentation",
|
||||
"application/vnd.google-apps.form",
|
||||
"application/vnd.google-apps.drawing",
|
||||
# Microsoft Office formats — require Office rendering, out of Phase 13 scope
|
||||
"application/vnd.openxmlformats-officedocument.wordprocessingml.document",
|
||||
"application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
|
||||
"application/vnd.openxmlformats-officedocument.presentationml.presentation",
|
||||
"application/msword",
|
||||
"application/vnd.ms-excel",
|
||||
"application/vnd.ms-powerpoint",
|
||||
})
|
||||
|
||||
@classmethod
|
||||
def is_supported(cls, content_type: Optional[str]) -> bool:
|
||||
"""Return True if the MIME type has explicit binary preview support.
|
||||
|
||||
Returns False for excluded formats and unknown types.
|
||||
Phase 13 unsupported formats fall back to the authorized download
|
||||
path (D-02); they are never opened via raw provider URLs.
|
||||
"""
|
||||
if content_type is None:
|
||||
return False
|
||||
# Strip parameters (e.g. "text/plain; charset=utf-8" -> "text/plain")
|
||||
base_type = content_type.split(";")[0].strip().lower()
|
||||
if base_type in cls.EXCLUDED_FROM_PREVIEW:
|
||||
return False
|
||||
return base_type in cls.SUPPORTED_BINARY_PREVIEW_TYPES
|
||||
|
||||
|
||||
# ── Abstract mutable adapter ──────────────────────────────────────────────────
|
||||
|
||||
class MutableCloudResourceAdapter(CloudResourceAdapter):
|
||||
"""Phase 13 mutable-operation contract extending the read-only adapter.
|
||||
|
||||
Defines the provider-neutral mutation interface for Phase 13:
|
||||
create_folder, rename, move, delete, and upload_file.
|
||||
|
||||
Contract guarantees (T-13-10, T-13-11, T-13-12):
|
||||
- Every mutation method returns a normalized result dict with at minimum
|
||||
{'kind': <MUT_KIND_*>, 'reason': <MUT_REASON_*>}. Routers and service
|
||||
layers must never parse raw provider error classes — normalization
|
||||
happens inside the adapter.
|
||||
- Providers never write cloud_items or audit rows. Those responsibilities
|
||||
belong exclusively to the service layer (cloud_operations.py /
|
||||
cloud_items.py).
|
||||
- Refreshed credentials are returned upward via the result dict rather
|
||||
than stored by the provider (T-13-11). The service layer is the only
|
||||
place that persists encrypted credentials.
|
||||
"""
|
||||
|
||||
@abstractmethod
|
||||
async def create_folder(
|
||||
self,
|
||||
parent_ref: Optional[str],
|
||||
name: str,
|
||||
connection_id: uuid.UUID,
|
||||
user_id: uuid.UUID,
|
||||
) -> dict:
|
||||
"""Create a folder in the provider and return a normalized result.
|
||||
|
||||
Returns a dict with at minimum::
|
||||
|
||||
{
|
||||
'kind': 'folder',
|
||||
'reason': 'created',
|
||||
'provider_item_id': str, # opaque new folder ID
|
||||
'name': str, # actual name used (may differ on collision)
|
||||
'parent_ref': str | None,
|
||||
}
|
||||
|
||||
On name collision::
|
||||
|
||||
{'kind': 'conflict', 'reason': 'name_collision'}
|
||||
|
||||
On transient provider failure::
|
||||
|
||||
{'kind': 'offline', 'reason': 'provider_offline'}
|
||||
|
||||
On auth failure::
|
||||
|
||||
{'kind': 'reauth_required', 'reason': 'token_expired' | 'invalid_grant'}
|
||||
|
||||
On unsupported operation::
|
||||
|
||||
{'kind': 'unsupported', 'reason': 'not_supported'}
|
||||
"""
|
||||
...
|
||||
|
||||
@abstractmethod
|
||||
async def rename(
|
||||
self,
|
||||
provider_item_id: str,
|
||||
new_name: str,
|
||||
etag: Optional[str],
|
||||
) -> dict:
|
||||
"""Rename a provider item and return a normalized result.
|
||||
|
||||
etag is used for conditional write (D-07 stale detection).
|
||||
A None etag skips the precondition check.
|
||||
|
||||
Returns a dict with at minimum::
|
||||
|
||||
{
|
||||
'kind': 'updated',
|
||||
'reason': 'renamed',
|
||||
'provider_item_id': str,
|
||||
'name': str,
|
||||
}
|
||||
|
||||
On stale metadata (etag mismatch)::
|
||||
|
||||
{'kind': 'stale', 'reason': 'item_changed'}
|
||||
|
||||
On name collision::
|
||||
|
||||
{'kind': 'conflict', 'reason': 'name_collision'}
|
||||
"""
|
||||
...
|
||||
|
||||
@abstractmethod
|
||||
async def move(
|
||||
self,
|
||||
provider_item_id: str,
|
||||
destination_parent_ref: str,
|
||||
etag: Optional[str],
|
||||
) -> dict:
|
||||
"""Move a provider item to a new parent folder.
|
||||
|
||||
destination_parent_ref must be on the same connection — cross-connection
|
||||
moves are rejected by the service layer, but providers should also reject
|
||||
obviously invalid destinations (SSRF guard for WebDAV, D-09).
|
||||
|
||||
Returns a dict with at minimum::
|
||||
|
||||
{
|
||||
'kind': 'updated',
|
||||
'reason': 'moved',
|
||||
'provider_item_id': str,
|
||||
'destination_parent_ref': str,
|
||||
}
|
||||
|
||||
On stale metadata (etag mismatch)::
|
||||
|
||||
{'kind': 'stale', 'reason': 'item_changed'}
|
||||
|
||||
On invalid destination (SSRF blocked or self-move)::
|
||||
|
||||
{'kind': 'invalid_destination', 'reason': 'ssrf_blocked' | 'self_or_descendant_move'}
|
||||
"""
|
||||
...
|
||||
|
||||
@abstractmethod
|
||||
async def delete(
|
||||
self,
|
||||
provider_item_id: str,
|
||||
trash: bool = True,
|
||||
) -> dict:
|
||||
"""Delete a provider item (prefer trash/recycle-bin when supported, D-11).
|
||||
|
||||
trash=True: use the provider's trash/recycle-bin when available.
|
||||
trash=False: permanently delete.
|
||||
|
||||
Returns a dict with at minimum::
|
||||
|
||||
{
|
||||
'kind': 'deleted',
|
||||
'reason': 'trashed' | 'permanent',
|
||||
'provider_item_id': str,
|
||||
}
|
||||
|
||||
On auth failure::
|
||||
|
||||
{'kind': 'reauth_required', 'reason': 'token_expired' | 'invalid_grant'}
|
||||
"""
|
||||
...
|
||||
|
||||
@abstractmethod
|
||||
async def upload_file(
|
||||
self,
|
||||
parent_ref: Optional[str],
|
||||
filename: str,
|
||||
content: bytes,
|
||||
content_type: str,
|
||||
connection_id: uuid.UUID,
|
||||
user_id: uuid.UUID,
|
||||
) -> dict:
|
||||
"""Upload a file into the provider folder identified by parent_ref.
|
||||
|
||||
content is raw bytes — never streamed out to provider URLs or logged.
|
||||
connection_id and user_id are passed for audit trail and reconciliation.
|
||||
|
||||
Returns a dict with at minimum::
|
||||
|
||||
{
|
||||
'kind': 'uploaded',
|
||||
'reason': 'created',
|
||||
'provider_item_id': str,
|
||||
'name': str,
|
||||
'parent_ref': str | None,
|
||||
'size': int,
|
||||
}
|
||||
|
||||
On name collision::
|
||||
|
||||
{'kind': 'conflict', 'reason': 'name_collision', 'existing_name': str}
|
||||
|
||||
On auth failure::
|
||||
|
||||
{'kind': 'reauth_required', 'reason': 'token_expired' | 'invalid_grant'}
|
||||
"""
|
||||
...
|
||||
|
||||
def _normalize_error(
|
||||
self,
|
||||
exc: Exception,
|
||||
*,
|
||||
default_kind: str = MUT_KIND_ERROR,
|
||||
default_reason: str = MUT_REASON_PROVIDER_ERROR,
|
||||
) -> dict:
|
||||
"""Normalize a provider exception into a controlled result dict.
|
||||
|
||||
Provider-specific error classes must never escape this boundary.
|
||||
Subclasses should override to handle their own error types before
|
||||
calling super() for the fallback.
|
||||
|
||||
Args:
|
||||
exc: The provider exception to normalize.
|
||||
default_kind: Fallback kind when the exception is unclassified.
|
||||
default_reason: Fallback reason when the exception is unclassified.
|
||||
|
||||
Returns:
|
||||
A normalized result dict with at minimum {'kind': ..., 'reason': ...}.
|
||||
"""
|
||||
return {
|
||||
"kind": default_kind,
|
||||
"reason": default_reason,
|
||||
"message": "An unexpected provider error occurred.",
|
||||
}
|
||||
|
||||
Reference in New Issue
Block a user