matelab-python-sdk 0.1.0a1__py3-none-any.whl

matelab/uploads.py

@@ -0,0 +1,247 @@
+import hashlib
+import re
+import secrets
+from dataclasses import dataclass, field, replace
+from typing import IO, Literal, Self, cast
+
+from pydantic import ValidationError
+
+from matelab._generated.models import ErrorResponse as WireErrorResponse
+from matelab._generated.models import StagedTemporaryFileFragmentResponse as WireStagedFragmentResponse
+from matelab._generated.models import StagedTemporaryFileResponse as WireStagedFileResponse
+from matelab._generated.models import StageTemporaryFileRequest as WireStageTemporaryFileRequest
+from matelab._generated.models import StageTemporaryFileResponse as WireStageTemporaryFileOperationResponse
+from matelab._transport import Encoding, Operation, SessionTransport, multipart_fields
+from matelab.errors import MatelabProtocolError, MatelabUsageError
+
+_STAGE_FILE = Operation(
+    method="POST",
+    path="/actions/bigupload",
+    encoding=Encoding.MULTIPART,
+    response_model=WireStageTemporaryFileOperationResponse,
+    success_codes=frozenset({0}),
+)
+_ABORT_STAGE = Operation(
+    method="POST",
+    path="/actions/bigupload",
+    encoding=Encoding.MULTIPART,
+    response_model=WireErrorResponse,
+    success_codes=frozenset({2}),
+)
+_SHA256_PATTERN = re.compile(r"^[0-9a-f]{64}$")
+
+
+@dataclass(frozen=True, slots=True)
+class UploadBindingRef:
+    """Caller-generated correlation value for one temporary-upload binding."""
+
+    uid: str = field(repr=False)
+
+    @classmethod
+    def new(cls) -> Self:
+        return cls(uid=f"upl-{secrets.token_urlsafe(24)}")
+
+
+@dataclass(frozen=True, slots=True)
+class StagedUploadSession:
+    """A resumable upload session whose offset is tracked by this caller."""
+
+    binding: UploadBindingRef
+    upload_session_id: str = field(repr=False)
+    next_offset: int = 0
+    offset_basis: Literal["client_declared_fragment_sizes_not_provider_confirmed"] = (
+        "client_declared_fragment_sizes_not_provider_confirmed"
+    )
+
+    @classmethod
+    def new(cls, *, binding: UploadBindingRef | None = None) -> Self:
+        return cls(binding=binding or UploadBindingRef.new(), upload_session_id=f"tmp-{secrets.token_urlsafe(24)}")
+
+
+@dataclass(frozen=True, slots=True)
+class StagedFileFragment:
+    """Provider-acknowledged non-final fragment and the next client-side session state."""
+
+    session: StagedUploadSession
+    fragment_sha256: str = field(repr=False)
+    fragment_size: int
+    completion: Literal["incomplete"] = "incomplete"
+    provider_offset_confirmation: Literal[False] = False
+    automatic_retry: Literal[False] = False
+
+
+@dataclass(frozen=True, slots=True)
+class StagedFile:
+    """A completed temporary file, not proof of downstream binding or uploader checks."""
+
+    session: StagedUploadSession
+    temporary_file_id: int
+    filename: str
+    size: int
+    sha256: str = field(repr=False)
+    temporary_url: str = field(repr=False)
+    completion: Literal["provider_acknowledged_complete"] = "provider_acknowledged_complete"
+    binding_state: Literal["staged_not_bound"] = "staged_not_bound"
+    downstream_binding_authorization: Literal["provider_does_not_verify_uploader"] = "provider_does_not_verify_uploader"
+    automatic_retry: Literal[False] = False
+
+    @property
+    def binding(self) -> UploadBindingRef:
+        return self.session.binding
+
+
+@dataclass(frozen=True, slots=True)
+class StagedUploadAbortResult:
+    session: StagedUploadSession
+    provider_message: str
+    cleanup_confirmation: Literal["provider_reported_cancellation_not_independently_verified"] = (
+        "provider_reported_cancellation_not_independently_verified"
+    )
+    automatic_retry: Literal[False] = False
+
+
+class Uploads:
+    """Cross-domain resumable staging without claiming downstream ownership checks."""
+
+    def __init__(self, transport: SessionTransport) -> None:
+        self._transport: SessionTransport = transport
+
+    async def stage(
+        self,
+        content: IO[bytes] | bytes,
+        *,
+        filename: str,
+        fragment_size: int,
+        session: StagedUploadSession | None = None,
+        final: bool = True,
+        complete_sha256: str | None = None,
+        content_type: str = "application/octet-stream",
+    ) -> StagedFileFragment | StagedFile:
+        selected = session or StagedUploadSession.new()
+        self._validate_session(selected)
+        self._validate_fragment(
+            content=content,
+            filename=filename,
+            fragment_size=fragment_size,
+            content_type=content_type,
+            complete_sha256=complete_sha256,
+            final=final,
+            offset=selected.next_offset,
+        )
+        expected_sha256 = complete_sha256
+        if final and expected_sha256 is None and isinstance(content, bytes) and selected.next_offset == 0:
+            expected_sha256 = hashlib.sha256(content).hexdigest()
+        try:
+            request = WireStageTemporaryFileRequest.model_validate(
+                {
+                    "uid": selected.binding.uid,
+                    "tempid": selected.upload_session_id,
+                    "hash": expected_sha256 or "",
+                    "last": int(final),
+                    "abort": 0,
+                    "file": b"contract-validation-placeholder",
+                }
+            )
+        except ValidationError:
+            raise MatelabUsageError("Temporary-file fragment does not satisfy the Integration Contract.") from None
+        response = await self._transport.request(
+            _STAGE_FILE,
+            payload=request.model_dump(mode="json", exclude={"file"}),
+            files={"file": (filename, content, content_type)},
+        )
+        wire = response.root
+        next_session = replace(selected, next_offset=selected.next_offset + fragment_size)
+        if not final:
+            if not isinstance(wire, WireStagedFragmentResponse):
+                raise MatelabProtocolError(
+                    "Matelab returned final-file metadata for a non-final fragment; the staging state is ambiguous."
+                )
+            if wire.tempid != selected.upload_session_id:
+                raise MatelabProtocolError("Matelab returned a different resumable upload-session identity.")
+            if isinstance(content, bytes) and wire.hash.root != hashlib.sha256(content).hexdigest():
+                raise MatelabProtocolError(
+                    "Matelab returned a fragment hash that does not match the submitted temporary-file bytes."
+                )
+            return StagedFileFragment(session=next_session, fragment_sha256=wire.hash.root, fragment_size=fragment_size)
+        if not isinstance(wire, WireStagedFileResponse):
+            raise MatelabProtocolError(
+                "Matelab returned fragment metadata for a final fragment; the temporary upload may remain incomplete."
+            )
+        if (
+            wire.name != selected.upload_session_id
+            or wire.filename != filename
+            or wire.size != next_session.next_offset
+            or (expected_sha256 is not None and wire.hash.root != expected_sha256)
+        ):
+            message = (
+                "Matelab completed staging with different identity, filename, size, or hash metadata; "
+                + "the temporary upload may require abort cleanup."
+            )
+            raise MatelabProtocolError(message)
+        return StagedFile(
+            session=next_session,
+            temporary_file_id=wire.id,
+            filename=wire.filename,
+            size=wire.size,
+            sha256=wire.hash.root,
+            temporary_url=self._transport.absolute_url(wire.path, wire.query),
+        )
+
+    async def abort(self, session: StagedUploadSession) -> StagedUploadAbortResult:
+        """Request compensating cleanup; the legacy Provider reports this as business code 2."""
+        self._validate_session(session)
+        try:
+            request = WireStageTemporaryFileRequest.model_validate(
+                {"uid": session.binding.uid, "tempid": session.upload_session_id, "hash": "", "last": 0, "abort": 1}
+            )
+        except ValidationError:
+            raise MatelabUsageError(
+                "Temporary-file abort identity does not satisfy the Integration Contract."
+            ) from None
+        response = await self._transport.request(
+            _ABORT_STAGE, files=multipart_fields(request.model_dump(mode="json", exclude_none=True))
+        )
+        return StagedUploadAbortResult(session=session, provider_message=response.msg)
+
+    @staticmethod
+    def _validate_session(session: StagedUploadSession) -> None:
+        if (
+            not session.binding.uid
+            or len(session.binding.uid) > 45
+            or not session.upload_session_id
+            or len(session.upload_session_id) > 45
+            or type(session.next_offset) is not int
+            or session.next_offset < 0
+        ):
+            raise MatelabUsageError("Temporary-upload session identity or offset is invalid.")
+
+    @staticmethod
+    def _validate_fragment(
+        *,
+        content: IO[bytes] | bytes,
+        filename: str,
+        fragment_size: int,
+        content_type: str,
+        complete_sha256: str | None,
+        final: bool,
+        offset: int,
+    ) -> None:
+        if (
+            not filename
+            or "\r" in filename
+            or "\n" in filename
+            or type(fragment_size) is not int
+            or fragment_size < 0
+            or type(final) is not bool
+            or not content_type
+            or "\r" in content_type
+            or "\n" in content_type
+            or (complete_sha256 is not None and _SHA256_PATTERN.fullmatch(complete_sha256) is None)
+            or (complete_sha256 is not None and not final)
+            or (offset > 0 and final and complete_sha256 is None)
+        ):
+            raise MatelabUsageError("Temporary-file fragment metadata is invalid.")
+        if isinstance(content, bytes) and len(content) != fragment_size:
+            raise MatelabUsageError("Temporary-file bytes do not match the declared fragment size.")
+        if not isinstance(content, bytes) and not hasattr(cast(object, content), "read"):
+            raise MatelabUsageError("Temporary-file content must be bytes or a readable binary stream.")

matelab/users.py

@@ -0,0 +1,77 @@
+from dataclasses import dataclass
+from enum import StrEnum
+from typing import Literal
+
+from pydantic import ValidationError
+
+from matelab._generated.models import SearchUsersParametersQuery as WireSearchUsersQuery
+from matelab._generated.models import UserDirectorySearchResponse as WireUserDirectorySearchResponse
+from matelab._transport import Encoding, Operation, SessionTransport
+from matelab.errors import MatelabUsageError
+
+_SEARCH_USERS = Operation(
+    method="GET",
+    path="/actions/search_user",
+    encoding=Encoding.QUERY,
+    response_model=WireUserDirectorySearchResponse,
+    success_codes=frozenset({0}),
+    retry_on_access_expired=True,
+)
+
+
+class UserSearchScope(StrEnum):
+    SAME_INSTITUTE = "same_institute"
+    GLOBAL = "global"
+
+
+@dataclass(frozen=True, slots=True)
+class UserRef:
+    userid: int
+
+
+@dataclass(frozen=True, slots=True)
+class UserSummary:
+    ref: UserRef
+    display_name: str | None
+    email: str | None
+    institute: str | None
+
+
+@dataclass(frozen=True, slots=True)
+class UserSearchResult:
+    """Unpaged directory matches in Provider-unspecified order."""
+
+    users: tuple[UserSummary, ...]
+    scope: UserSearchScope
+    ordering: Literal["provider_unspecified"] = "provider_unspecified"
+
+
+class Users:
+    """User discovery operations for selecting sharing targets."""
+
+    def __init__(self, transport: SessionTransport) -> None:
+        self._transport: SessionTransport = transport
+
+    async def search(
+        self, keyword: str, *, scope: UserSearchScope = UserSearchScope.SAME_INSTITUTE
+    ) -> UserSearchResult:
+        try:
+            normalized_scope = UserSearchScope(scope)
+        except ValueError:
+            raise MatelabUsageError("User search scope must be same_institute or global.") from None
+        try:
+            request = WireSearchUsersQuery.model_validate(
+                {"keyword": keyword, "all": 1 if normalized_scope is UserSearchScope.GLOBAL else 0}
+            )
+        except ValidationError:
+            raise MatelabUsageError("User search input does not satisfy the Integration Contract.") from None
+        response = await self._transport.request(_SEARCH_USERS, payload=request.model_dump(mode="json"))
+        return UserSearchResult(
+            users=tuple(
+                UserSummary(
+                    ref=UserRef(userid=user.id), display_name=user.username, email=user.email, institute=user.institute
+                )
+                for user in response.users
+            ),
+            scope=normalized_scope,
+        )