fix: report a locked folder as FolderLockedException

Fetching a locked folder before its password is sent returns 200 with
only its listing fields, without metadata, sub_folders and path, so
FoldersApi.retrieve failed with a pydantic ValidationError. The DOI
route fetches the folder before it can see the lock, so a
password-protected DOI folder could not be opened even with its
password.

- Add FolderLockedException, a subclass of UnauthorizedException, and
  raise it from retrieve on that short record and from the lock checks.
- On a DOI folder, send the password and fetch it again when the first
  fetch finds it locked.

mdrsclient/api/folders.py

@@ -6,7 +6,7 @@ from pydantic.dataclasses import dataclass
 
 from mdrsclient.api.base import BaseApi
 from mdrsclient.api.utils import retry_on_expired_token, token_check
-from mdrsclient.exceptions import UnauthorizedException
+from mdrsclient.exceptions import FolderLockedException, UnauthorizedException
 from mdrsclient.models import Folder, FolderSimple
 
 
@@ -38,7 +38,12 @@ class FoldersApi(BaseApi):
         token_check(self.connection)
         response = self.connection.get(url)
         self._raise_response_error(response)
-        ret = TypeAdapter(Folder).validate_python(response.json())
+        data = response.json()
+        # A locked folder not yet opened with its password comes back with 200 but only
+        # its listing fields, without `metadata`, `sub_folders` and `path`.
+        if data.get("lock") and "sub_folders" not in data:
+            raise FolderLockedException(f"Folder `{data.get('name', id)}` is locked.")
+        ret = TypeAdapter(Folder).validate_python(data)
         return ret
 
     @retry_on_expired_token

mdrsclient/exceptions.py

@@ -28,6 +28,12 @@ class UnauthorizedException(MDRSException):
     pass
 
 
+class FolderLockedException(UnauthorizedException):
+    """Thrown when a folder cannot be opened without its password"""
+
+    pass
+
+
 class TokenExpiredException(UnauthorizedException):
     """Thrown when the access token was still valid when sent but had expired on arrival"""
 

mdrsclient/services.py

@@ -8,9 +8,9 @@ from mdrsclient.cache import CacheInterface
 from mdrsclient.config import ConfigFile, ConfigInterface
 from mdrsclient.connection import MDRSConnection
 from mdrsclient.exceptions import (
+    FolderLockedException,
     IllegalArgumentException,
     MissingConfigurationException,
-    UnauthorizedException,
     UnexpectedException,
 )
 from mdrsclient.models import File, Folder, Laboratory, Token, User
@@ -103,7 +103,7 @@ class MdrsService:
             raise UnexpectedException(f"Folder `{path}` not found.")
         if folders[0].lock:
             if password is None:
-                raise UnauthorizedException(f"Folder `{path}` is locked.")
+                raise FolderLockedException(f"Folder `{path}` is locked.")
             folder_api.auth(folders[0].id, password)
         return folder_api.retrieve(folders[0].id)
 
@@ -207,12 +207,20 @@ class MdrsService:
             )
 
         folder_api = FoldersApi(self.connection)
-        folder = folder_api.retrieve(doi_resp.folder_id)
+        # The folder is found by its id, so whether it is locked is known only from what
+        # retrieve returns: a full record, or the short one of a locked folder.
+        folder: Folder | None
+        try:
+            folder = folder_api.retrieve(doi_resp.folder_id)
+        except FolderLockedException:
+            folder = None
 
-        if folder.lock:
+        if folder is None or folder.lock:
             if password is None:
-                raise UnauthorizedException(f"Folder for DOI `{doi_clean}` is locked.")
+                raise FolderLockedException(f"Folder for DOI `{doi_clean}` is locked.")
             folder_api.auth(doi_resp.folder_id, password)
+            if folder is None:
+                folder = folder_api.retrieve(doi_resp.folder_id)
 
         lab_api = LaboratoriesApi(self.connection)
         labs = lab_api.list()