diff --git a/docs/api.md b/docs/api.md index 01bf40a..c155c0a 100644 --- a/docs/api.md +++ b/docs/api.md @@ -48,7 +48,7 @@ Request and response models live in `nanokvm.models`. |---|---| | `get_info`, `get_hardware`, `get_gpio`, `push_button` | all | | `get_oled_info`, `set_oled_sleep` | all | -| `get_virtual_device_status`, `update_virtual_device` | all | +| `get_virtual_device_status`, `update_virtual_device` | all; `enable=` non-Pro 2.5.3 | | `get_hostname`, `set_hostname`, `get_web_title`, `set_web_title` | non-Pro 2.2.6 / Pro | | `get_ssh_state`, `enable_ssh`, `disable_ssh` | non-Pro 2.1.6 / Pro | | `get_mdns_state`, `enable_mdns`, `disable_mdns` | non-Pro 2.2.2 / Pro | @@ -83,6 +83,11 @@ Check the power LED rather than the video signal: on the PCIe, `get_hdmi_state().signal` can stay `True` for about ten seconds after the target is off. +`update_virtual_device(device)` toggles the device. From non-Pro 2.5.3, +`enable=True` or `enable=False` sets the state instead, and leaves a device +already in that state alone. Older firmware ignores `enable` and toggles, so +the client refuses it there. + ### Keyboard and mouse | Methods | Requires | @@ -222,6 +227,42 @@ async for status in client.watch_image_download(): Autostart scripts run when the device boots. +### Virtual media + +| Methods | Requires | +|---|---| +| `get_media`, `get_media_state`, `get_media_status`, `mount_media`, `eject_media`, `delete_media` | non-Pro 2.5.3 | +| `list_media_files`, `upload_media_file`, `download_media_file`, `delete_media_file`, `download_media` | non-Pro 2.5.3 | +| `create_media_directory` | non-Pro 2.5.4 | + +From 2.5.3 the USB disk carries a medium: an image, or the device's shared data +partition. `rel` names an image by its path in the media directory, as +`get_media()` lists it; leaving `rel` out means the partition. The image +methods above keep working. + +```python +media = await client.get_media() # media.media[0].rel: "debian.iso" +await client.mount_media("debian.iso", cdrom=True) +await client.eject_media() +await client.mount_media() # serve the data partition again + +listing = await client.list_media_files("/") # files on the partition +await client.upload_media_file("notes.txt", "/docs") +await client.download_media_file("/docs/notes.txt", "notes-copy.txt") +await client.list_media_files("/", rel="debian.iso") # files inside an image +``` + +- An image is always served read-only. `cdrom=True` needs an ISO 9660 or UDF + image. +- While the target machine holds the partition, `/data` is read-only on the + device and writes fail. `get_media_state().local_writable` (2.5.4) reports it. +- `force=True` on `mount_media` and `eject_media` takes the disk back from a + target machine that holds it, losing its unflushed writes. +- The device refuses a busy, attached or full medium with `NanoKVMApiError`: + -10 virtual disk off, -11 medium attached, -12 medium in use, -13 not + browsable, -14 not enough space, -15 not an optical image, -16 name taken. +- A failed download raises and leaves no file at the destination. + ### Network | Methods | Requires | @@ -285,3 +326,22 @@ package from a local file. Pass `sha256=` to check the file first; non-Pro |---|---| | `authenticate`, `logout`, `get_account`, `change_password`, `is_password_updated` | all | | `get_users`, `create_user`, `update_user`, `delete_user`, `set_user_password` | non-Pro 2.5.1 | +| `get_permissions`; `permissions=` and `rotate_mcp_key=` on the methods above | non-Pro 2.5.3 | + +From non-Pro 2.5.3, a `user` account holds an explicit set of `Permission` +grants; administrators hold them all. `get_permissions()` lists the catalog +with each grant's group, risk and implied grants, and `get_account().permissions` +lists what the logged-in account can do. + +```python +await client.create_user("viewer", "password", permissions=[Permission.CONSOLE_VIEW]) +await client.update_user("viewer", permissions=[], rotate_mcp_key=True) +``` + +- `create_user` without `permissions` grants console view, console control and + power, as the `user` role did before 2.5.3. An empty list grants nothing. +- `update_user(permissions=...)` replaces the stored grants. From 2.5.3 only + disabling an account ends its sessions. +- `rotate_mcp_key=True` regenerates the device MCP API key when the change or + deletion takes the `mcp` grant away, which disconnects every MCP client. +- An account without the grant for a route gets `NanoKVMPermissionError`. diff --git a/nanokvm/client.py b/nanokvm/client.py index a11278b..34b64ef 100644 --- a/nanokvm/client.py +++ b/nanokvm/client.py @@ -10,6 +10,7 @@ from . import models from .compatibility import require_application_version, require_hardware from .components.hid import PASTE_CHAR_MAP, HidController +from .components.media import MediaController from .components.mouse import MouseController from .components.network import NetworkController from .components.services import ServiceController @@ -60,6 +61,7 @@ class NanoKVMClient( HidController, VideoController, StorageController, + MediaController, NetworkController, ServiceController, UserController, diff --git a/nanokvm/components/media.py b/nanokvm/components/media.py new file mode 100644 index 0000000..f905c11 --- /dev/null +++ b/nanokvm/components/media.py @@ -0,0 +1,207 @@ +"""Internal virtual media operations (non-Pro 2.5.3 storage API).""" + +from __future__ import annotations + +import asyncio +from os import PathLike +from pathlib import Path + +from aiohttp import ClientTimeout, hdrs + +from ..compatibility import require_hardware +from ..exceptions import NanoKVMInvalidResponseError +from ..models.common import HWFamily +from ..models.non_pro import ( + EjectMediaReq, + GetMediaFilesRsp, + GetMediaRsp, + GetMediaStateRsp, + GetMediaStatusRsp, + MediaFile, + MediaPathReq, + MediaRefReq, + MediaType, + MountMediaReq, +) +from .session import Controller + + +def _media_type(rel: str | None) -> MediaType: + # An image is named by its path in the media directory; no name is the + # shared data partition. + return MediaType.IMAGE if rel else MediaType.PARTITION + + +def _media_params(rel: str | None, **extra: str) -> dict[str, str]: + return {"type": _media_type(rel).value, "rel": rel or "", **extra} + + +class MediaController(Controller): + """Implement virtual media operations behind the public client facade. + + ``rel`` names an image by its path relative to the media directory, as + ``get_media()`` lists it. Leaving it out means the shared data partition. + """ + + def _transfer_timeout(self) -> ClientTimeout: + return ClientTimeout( + total=None, + sock_connect=self._session._request_timeout, + sock_read=self._session._request_timeout, + ) + + @require_hardware(HWFamily.NON_PRO, min_version="2.5.3") + async def get_media(self) -> GetMediaRsp: + """List the images and the data partition the USB disk can carry.""" + return await self._session.api_request_json( + hdrs.METH_GET, "/storage/media", response_model=GetMediaRsp + ) + + @require_hardware(HWFamily.NON_PRO, min_version="2.5.3") + async def get_media_state(self) -> GetMediaStateRsp: + """Get what the target machine currently sees on the USB disk.""" + return await self._session.api_request_json( + hdrs.METH_GET, "/storage/media/state", response_model=GetMediaStateRsp + ) + + @require_hardware(HWFamily.NON_PRO, min_version="2.5.3") + async def get_media_status(self) -> GetMediaStatusRsp: + """Get the progress of the running media file transfer.""" + return await self._session.api_request_json( + hdrs.METH_GET, "/storage/media/status", response_model=GetMediaStatusRsp + ) + + @require_hardware(HWFamily.NON_PRO, min_version="2.5.3") + async def mount_media( + self, rel: str | None = None, *, cdrom: bool = False, force: bool = False + ) -> None: + """Attach an image, or the data partition, to the target machine. + + An image is always served read-only. ``cdrom`` needs an ISO 9660 or + UDF image. ``force`` takes the disk back from a target machine that + holds it, losing its unflushed writes. + """ + await self._session.api_request_json( + hdrs.METH_POST, + "/storage/media/mount", + data=MountMediaReq( + type=_media_type(rel), rel=rel or "", cdrom=cdrom, force=force + ), + ) + + @require_hardware(HWFamily.NON_PRO, min_version="2.5.3") + async def eject_media(self, *, force: bool = False) -> None: + """Release the attached medium; ``force`` as in ``mount_media``.""" + await self._session.api_request_json( + hdrs.METH_POST, "/storage/media/eject", data=EjectMediaReq(force=force) + ) + + @require_hardware(HWFamily.NON_PRO, min_version="2.5.3") + async def delete_media(self, rel: str) -> None: + """Delete an image. The data partition cannot be deleted.""" + if not rel: + raise ValueError("rel must name an image") + await self._session.api_request_json( + hdrs.METH_POST, + "/storage/media/delete", + data=MediaRefReq(type=MediaType.IMAGE, rel=rel), + ) + + @require_hardware(HWFamily.NON_PRO, min_version="2.5.3") + async def list_media_files( + self, path: str = "/", *, rel: str | None = None + ) -> GetMediaFilesRsp: + """List a directory inside an image or the data partition.""" + return await self._session.api_request_json( + hdrs.METH_GET, + "/storage/media/files", + response_model=GetMediaFilesRsp, + params=_media_params(rel, path=path), + ) + + @require_hardware(HWFamily.NON_PRO, min_version="2.5.3") + async def upload_media_file( + self, + file_path: str | PathLike[str], + path: str = "/", + *, + rel: str | None = None, + ) -> MediaFile: + """Upload a local file into a directory of an image or the partition. + + An existing name raises ``NanoKVMApiError`` with code -16. + """ + return await self._session.upload_file( + "/storage/media/files/upload", + file_path, + response_model=MediaFile, + params=_media_params(rel, path=path), + timeout=self._transfer_timeout(), + ) + + @require_hardware(HWFamily.NON_PRO, min_version="2.5.4") + async def create_media_directory( + self, path: str, *, rel: str | None = None, exist_ok: bool = False + ) -> None: + """Create a directory inside an image or the data partition.""" + await self._session.api_request_json( + hdrs.METH_POST, + "/storage/media/files/mkdir", + data=MediaPathReq( + type=_media_type(rel), + rel=rel or "", + path=path, + exists_ok=exist_ok or None, + ), + ) + + @require_hardware(HWFamily.NON_PRO, min_version="2.5.3") + async def delete_media_file(self, path: str, *, rel: str | None = None) -> None: + """Delete a file or directory inside an image or the data partition.""" + await self._session.api_request_json( + hdrs.METH_POST, + "/storage/media/files/delete", + data=MediaPathReq(type=_media_type(rel), rel=rel or "", path=path), + ) + + @require_hardware(HWFamily.NON_PRO, min_version="2.5.3") + async def download_media_file( + self, + path: str, + destination: str | PathLike[str], + *, + rel: str | None = None, + ) -> None: + """Save a file from inside an image or the data partition locally.""" + await self._download( + "/storage/media/files/download", _media_params(rel, path=path), destination + ) + + @require_hardware(HWFamily.NON_PRO, min_version="2.5.3") + async def download_media(self, rel: str, destination: str | PathLike[str]) -> None: + """Save a whole image locally. An attached image is refused.""" + if not rel: + raise ValueError("rel must name an image") + await self._download("/storage/media/download", _media_params(rel), destination) + + async def _download( + self, path: str, params: dict[str, str], destination: str | PathLike[str] + ) -> None: + target = Path(destination) + async with self._session.request( + hdrs.METH_GET, path, params=params, timeout=self._transfer_timeout() + ) as response: + # The device answers a refusal with its JSON envelope instead of + # the file. + if response.content_type == "application/json": + self._session.validate_api_response( + await self._session.read_json_response(response) + ) + raise NanoKVMInvalidResponseError("Expected a file, got JSON") + try: + with target.open("wb") as file: + async for chunk in response.content.iter_chunked(1024 * 1024): + await asyncio.to_thread(file.write, chunk) + except BaseException: + target.unlink(missing_ok=True) + raise diff --git a/nanokvm/components/system.py b/nanokvm/components/system.py index ac4e114..e75ff80 100644 --- a/nanokvm/components/system.py +++ b/nanokvm/components/system.py @@ -8,7 +8,11 @@ from aiohttp import ClientTimeout, ServerDisconnectedError, hdrs from ..compatibility import require_application_version, require_hardware -from ..exceptions import NanoKVMApiError, NanoKVMInvalidResponseError +from ..exceptions import ( + NanoKVMApiError, + NanoKVMInvalidResponseError, + NanoKVMNotSupportedError, +) from ..models.common import ( GetGpioRsp, GetHardwareRsp, @@ -194,15 +198,29 @@ async def update_virtual_device( self, device: VirtualDevice, *, + enable: bool | None = None, # non-Pro 2.5.3 disk_type: DiskType | None = None, # Pro only ) -> None: - """Toggle the state of a virtual device.""" + """Toggle a virtual device, or with ``enable`` set it on or off. + + Older firmware ignores ``enable`` and toggles, so it is refused there. + """ + if enable is not None and not ( + await self._session.application_version_at_least(non_pro="2.5.3") + and self._session.is_hardware_family(HWFamily.NON_PRO) + ): + raise NanoKVMNotSupportedError( + "update_virtual_device enable requires non-Pro application " + f"version >= 2.5.3 (detected: {self._session._hw_version} " + f"{self._session._application_version})" + ) await self._session.api_request_json( hdrs.METH_POST, "/vm/device/virtual", data=UpdateVirtualDeviceReq( device=device, type=disk_type.value if disk_type else None, + enable=enable, ), ) diff --git a/nanokvm/components/users.py b/nanokvm/components/users.py index 4d531c9..7f84cb6 100644 --- a/nanokvm/components/users.py +++ b/nanokvm/components/users.py @@ -5,10 +5,13 @@ from aiohttp import hdrs from ..compatibility import require_hardware +from ..exceptions import NanoKVMNotSupportedError from ..models.common import HWFamily from ..models.non_pro import ( CreateUserReq, + GetPermissionsRsp, GetUsersRsp, + Permission, SetUserPasswordReq, UpdateUserReq, UserRole, @@ -27,6 +30,22 @@ def _user_path(username: str, suffix: str = "") -> str: class UserController(Controller): """Implement user account operations behind the public client facade.""" + async def _require_permissions_api(self) -> None: + if not await self._session.application_version_at_least(non_pro="2.5.3"): + raise NanoKVMNotSupportedError( + "account permissions require non-Pro application version >= 2.5.3 " + f"(detected: {self._session._application_version})" + ) + + @require_hardware(HWFamily.NON_PRO, min_version="2.5.3") + async def get_permissions(self) -> GetPermissionsRsp: + """List the permissions an account can be granted.""" + return await self._session.api_request_json( + hdrs.METH_GET, + "/auth/permissions", + response_model=GetPermissionsRsp, + ) + @require_hardware(HWFamily.NON_PRO, min_version="2.5.1") async def get_users(self) -> GetUsersRsp: """List the user accounts on the device.""" @@ -38,9 +57,20 @@ async def get_users(self) -> GetUsersRsp: @require_hardware(HWFamily.NON_PRO, min_version="2.5.1") async def create_user( - self, username: str, password: str, role: UserRole | str = UserRole.USER + self, + username: str, + password: str, + role: UserRole | str = UserRole.USER, + *, + permissions: list[Permission | str] | None = None, ) -> None: - """Create a user account.""" + """Create a user account. + + ``permissions`` needs 2.5.3. Without it, a user account gets console + view, console control and power; an empty list grants nothing. + """ + if permissions is not None: + await self._require_permissions_api() await self._session.api_request_json( hdrs.METH_POST, "/auth/users", @@ -48,6 +78,7 @@ async def create_user( username=username, password=obfuscate_password(password), role=role, + permissions=permissions, ), ) @@ -58,23 +89,45 @@ async def update_user( *, role: UserRole | str | None = None, enabled: bool | None = None, + permissions: list[Permission | str] | None = None, + rotate_mcp_key: bool = False, ) -> None: - """Change a user's role, enabled state or both. + """Change a user's role, enabled state, permissions or several. - The device ends that user's sessions. + Before 2.5.3 the device ends that user's sessions; from 2.5.3 only + disabling does. ``permissions`` (2.5.3) replaces the stored grants. + ``rotate_mcp_key`` (2.5.3) regenerates the device MCP API key if the + change takes the ``mcp`` grant away, which disconnects every MCP client. """ - if role is None and enabled is None: - raise ValueError("role or enabled is required") + if role is None and enabled is None and permissions is None: + raise ValueError("role, enabled or permissions is required") + if permissions is not None or rotate_mcp_key: + await self._require_permissions_api() await self._session.api_request_json( hdrs.METH_PUT, _user_path(username), - data=UpdateUserReq(role=role, enabled=enabled), + data=UpdateUserReq( + role=role, + enabled=enabled, + permissions=permissions, + rotate_mcp_key=rotate_mcp_key or None, + ), ) @require_hardware(HWFamily.NON_PRO, min_version="2.5.1") - async def delete_user(self, username: str) -> None: - """Delete a user account and end its sessions.""" - await self._session.api_request_json(hdrs.METH_DELETE, _user_path(username)) + async def delete_user(self, username: str, *, rotate_mcp_key: bool = False) -> None: + """Delete a user account and end its sessions. + + ``rotate_mcp_key`` (2.5.3) regenerates the device MCP API key if the + account held the ``mcp`` grant. + """ + params = {} + if rotate_mcp_key: + await self._require_permissions_api() + params["rotateMcpKey"] = "true" + await self._session.api_request_json( + hdrs.METH_DELETE, _user_path(username), params=params + ) @require_hardware(HWFamily.NON_PRO, min_version="2.5.1") async def set_user_password(self, username: str, new_password: str) -> None: diff --git a/nanokvm/models/common.py b/nanokvm/models/common.py index 92052d1..17d018c 100644 --- a/nanokvm/models/common.py +++ b/nanokvm/models/common.py @@ -370,6 +370,7 @@ class LoginRsp(BaseModel): class GetAccountRsp(BaseModel): username: str role: str | None = None + permissions: list[str] | None = None # effective grants, non-Pro 2.5.3 class ChangePasswordReq(BaseModel): @@ -469,6 +470,7 @@ class UpdateVirtualDeviceReq(BaseModel): device: VirtualDevice type: str | None = None # Pro only (sdcard/emmc for disk device) + enable: bool | None = None # non-Pro 2.5.3; older firmware toggles class GetVirtualDeviceRsp(BaseModel): @@ -755,6 +757,8 @@ class StatusImageRsp(BaseModel): status: DownloadStatus file: str percentage: str + loaded: int | None = None # bytes so far, non-Pro 2.5.3 + total: int | None = None # expected bytes, 0 when unknown, non-Pro 2.5.3 class DownloadImageReq(BaseModel): diff --git a/nanokvm/models/non_pro.py b/nanokvm/models/non_pro.py index 9c4c3d8..76b4c2d 100644 --- a/nanokvm/models/non_pro.py +++ b/nanokvm/models/non_pro.py @@ -14,6 +14,7 @@ "CreateUserReq", "DNSInfo", "DNSMode", + "EjectMediaReq", "GetAutostartRsp", "GetCdRomRsp", "GetDNSRsp", @@ -21,13 +22,27 @@ "GetInputRegionRsp", "GetInputResolutionRsp", "GetMCPConfigRsp", + "GetMediaFilesRsp", + "GetMediaRsp", + "GetMediaStateRsp", + "GetMediaStatusRsp", "GetMemoryLimitRsp", + "GetPermissionsRsp", "GetSwapSizeRsp", "GetUpdateServerRsp", "GetUsersRsp", "InputRegionMode", "ManualRegion", + "MediaCapabilities", + "MediaFile", + "MediaItem", + "MediaPathReq", + "MediaRefReq", + "MediaType", + "MountMediaReq", "OriginalResolution", + "Permission", + "PermissionInfo", "ScreenSettingType", "SetAIControlModeReq", "SetAIControlModeRsp", @@ -271,14 +286,54 @@ class UserRole(StrEnum): USER = "user" +class Permission(StrEnum): + """Account permissions, from non-Pro 2.5.3. Administrators hold them all.""" + + CONSOLE_VIEW = "console.view" + CONSOLE_CONTROL = "console.control" + POWER = "power" + MEDIUM_ATTACH = "medium.attach" + LIBRARY_READ = "library.read" + LIBRARY_WRITE = "library.write" + TERMINAL = "terminal" + DEVICE = "device" + NETWORK = "network" + UPDATE = "update" + MCP = "mcp" + TAILSCALE = "tailscale" + AI = "ai" + + +class PermissionInfo(BaseModel): + id: str + group: str + risk: str # "info", or "warn" for a grant that amounts to full device control + implies: list[str] = Field(default_factory=list) + + @field_validator("implies", mode="before") + @classmethod + def _normalize_implies(cls, value: Any) -> Any: + return _normalize_string_list(value) + + +class GetPermissionsRsp(BaseModel): + permissions: list[PermissionInfo] + + class UserInfo(BaseModel): model_config = ConfigDict(populate_by_name=True) username: str role: str enabled: bool + permissions: list[str] = Field(default_factory=list) # stored grants, 2.5.3 system_account: bool = Field(default=False, alias="systemAccount") + @field_validator("permissions", mode="before") + @classmethod + def _normalize_permissions(cls, value: Any) -> Any: + return _normalize_string_list(value) + class GetUsersRsp(BaseModel): users: list[UserInfo] @@ -288,11 +343,16 @@ class CreateUserReq(BaseModel): username: str password: str = Field(repr=False) role: str + permissions: list[str] | None = None class UpdateUserReq(BaseModel): + model_config = ConfigDict(populate_by_name=True) + role: str | None = None enabled: bool | None = None + permissions: list[str] | None = None + rotate_mcp_key: bool | None = Field(default=None, alias="rotateMcpKey") class SetUserPasswordReq(BaseModel): @@ -347,3 +407,107 @@ def _normalize_dns_lists(cls, value: Any) -> Any: class SetDNSReq(BaseModel): mode: DNSMode servers: list[str] = Field(default_factory=list) + + +class MediaType(StrEnum): + """What a virtual medium is: an image file or the shared data partition.""" + + IMAGE = "image" + PARTITION = "partition" + + +class MediaItem(BaseModel): + model_config = ConfigDict(populate_by_name=True) + + type: str + rel: str # image path relative to the media directory; empty for the partition + name: str + size: int + fs: str + browsable: bool # the device can list the files inside + attached: bool + modified_at: datetime = Field(alias="modifiedAt") + + +class MediaCapabilities(BaseModel): + loop: bool + + +class GetMediaRsp(BaseModel): + media: list[MediaItem] = Field(default_factory=list) + capabilities: MediaCapabilities + + @field_validator("media", mode="before") + @classmethod + def _normalize_media(cls, value: Any) -> Any: + return _normalize_string_list(value) + + +class GetMediaStateRsp(BaseModel): + model_config = ConfigDict(populate_by_name=True) + + state: str # none | image | partition | unsupported (virtual disk off) + type: str + rel: str + hid_only: bool = Field(alias="hidOnly") # the gadget has no mass storage + open: list[str] = Field(default_factory=list) # media the file manager holds + cdrom: bool + local_writable: bool | None = Field(default=None, alias="localWritable") # 2.5.4 + + @field_validator("open", mode="before") + @classmethod + def _normalize_open(cls, value: Any) -> Any: + return _normalize_string_list(value) + + +class GetMediaStatusRsp(BaseModel): + status: str + name: str + percentage: str + loaded: int + total: int # 0 when unknown + message: str + + +class MediaFile(BaseModel): + model_config = ConfigDict(populate_by_name=True) + + name: str + size: int + is_dir: bool = Field(default=False, alias="isDir") + modified_at: datetime | None = Field(default=None, alias="modifiedAt") + + +class GetMediaFilesRsp(BaseModel): + path: str + entries: list[MediaFile] = Field(default_factory=list) + free: int + total: int + # A zero-length entry is a transfer in progress while this is true. + writing: bool + + @field_validator("entries", mode="before") + @classmethod + def _normalize_entries(cls, value: Any) -> Any: + return _normalize_string_list(value) + + +class MediaRefReq(BaseModel): + type: MediaType + rel: str = "" + + +class MountMediaReq(MediaRefReq): + cdrom: bool = False + force: bool = False + + +class EjectMediaReq(BaseModel): + force: bool = False + + +class MediaPathReq(MediaRefReq): + model_config = ConfigDict(populate_by_name=True) + + path: str + exists_ok: bool | None = Field(default=None, alias="existsOk") diff --git a/tests/test_media.py b/tests/test_media.py new file mode 100644 index 0000000..ef71f7a --- /dev/null +++ b/tests/test_media.py @@ -0,0 +1,121 @@ +"""Tests for the non-Pro 2.5.3 virtual media API.""" + +from pathlib import Path + +from aioresponses import aioresponses +import pytest +import yarl + +from nanokvm.client import NanoKVMApiError, NanoKVMClient, NanoKVMNotSupportedError + +from .common import BASE_URL, mark_detected + +_OK = {"code": 0, "msg": "success", "data": None} + + +def _calls(mocked: aioresponses, method: str, path: str) -> list[object]: + return [ + call.kwargs.get("json") + for (m, url), calls in mocked.requests.items() + if m == method and url.path == f"/api/{path}" + for call in calls + ] + + +async def test_rel_picks_image_or_partition( + client: NanoKVMClient, mocked: aioresponses +) -> None: + """No ``rel`` addresses the data partition, a ``rel`` an image.""" + mark_detected(client, application_version="2.5.3") + mocked.post(f"{BASE_URL}storage/media/mount", payload=_OK, repeat=True) + mocked.post(f"{BASE_URL}storage/media/eject", payload=_OK) + mocked.post(f"{BASE_URL}storage/media/files/delete", payload=_OK) + files = {"path": "/a", "entries": None, "free": 1, "total": 2, "writing": False} + mocked.get( + f"{BASE_URL}storage/media/files?path=/a&rel=debian.iso&type=image", + payload={**_OK, "data": files}, + ) + + await client.mount_media() + await client.mount_media("debian.iso", cdrom=True) + await client.eject_media(force=True) + await client.delete_media_file("/a/b.txt") + listing = await client.list_media_files("/a", rel="debian.iso") + + assert listing.entries == [] + assert _calls(mocked, "POST", "storage/media/mount") == [ + {"type": "partition", "rel": "", "cdrom": False, "force": False}, + {"type": "image", "rel": "debian.iso", "cdrom": True, "force": False}, + ] + assert _calls(mocked, "POST", "storage/media/eject") == [{"force": True}] + assert _calls(mocked, "POST", "storage/media/files/delete") == [ + {"type": "partition", "rel": "", "path": "/a/b.txt"} + ] + + +async def test_versions(client: NanoKVMClient, mocked: aioresponses) -> None: + """The media API needs 2.5.3 and directory creation 2.5.4.""" + mark_detected(client, application_version="2.5.2") + with pytest.raises(NanoKVMNotSupportedError): + await client.get_media() + + mark_detected(client, application_version="2.5.3") + with pytest.raises(NanoKVMNotSupportedError): + await client.create_media_directory("/new") + assert not mocked.requests + + mark_detected(client, application_version="2.5.4") + mocked.post(f"{BASE_URL}storage/media/files/mkdir", payload=_OK) + await client.create_media_directory("/new", exist_ok=True) + assert _calls(mocked, "POST", "storage/media/files/mkdir") == [ + {"type": "partition", "rel": "", "path": "/new", "existsOk": True} + ] + + +async def test_download_writes_the_file( + client: NanoKVMClient, mocked: aioresponses, tmp_path: Path +) -> None: + """The body lands in the destination.""" + mark_detected(client) + mocked.get( + f"{BASE_URL}storage/media/files/download?path=/a.txt&rel=&type=partition", + body=b"hello", + content_type="application/octet-stream", + ) + + await client.download_media_file("/a.txt", tmp_path / "a.txt") + + assert (tmp_path / "a.txt").read_bytes() == b"hello" + + +async def test_download_refusal_raises_and_leaves_no_file( + client: NanoKVMClient, mocked: aioresponses, tmp_path: Path +) -> None: + """A JSON error envelope in place of the file raises the API error.""" + mark_detected(client) + mocked.get( + f"{BASE_URL}storage/media/download?rel=debian.iso&type=image", + payload={"code": -11, "msg": "the medium is attached", "data": None}, + ) + + with pytest.raises(NanoKVMApiError) as err: + await client.download_media("debian.iso", tmp_path / "debian.iso") + + assert err.value.code == -11 + assert not (tmp_path / "debian.iso").exists() + + +async def test_upload_sends_the_target_directory( + client: NanoKVMClient, mocked: aioresponses, tmp_path: Path +) -> None: + """The directory and medium travel as query parameters.""" + mark_detected(client) + source = tmp_path / "notes.txt" + source.write_text("hi") + url = f"{BASE_URL}storage/media/files/upload?path=/docs&rel=&type=partition" + mocked.post(url, payload={**_OK, "data": {"name": "notes.txt", "size": 2}}) + + uploaded = await client.upload_media_file(source, "/docs") + + assert (uploaded.name, uploaded.size) == ("notes.txt", 2) + assert ("POST", yarl.URL(url)) in mocked.requests diff --git a/tests/test_system.py b/tests/test_system.py index 29bac40..b6c8b71 100644 --- a/tests/test_system.py +++ b/tests/test_system.py @@ -11,7 +11,7 @@ import pytest import yarl -from nanokvm.client import NanoKVMApiError, NanoKVMClient +from nanokvm.client import NanoKVMApiError, NanoKVMClient, NanoKVMNotSupportedError from nanokvm.models import DiskType, GpioType, HWVersion, VirtualDevice from .common import BASE_URL, mark_detected @@ -270,3 +270,24 @@ async def never_answers(request: web.Request) -> web.Response: release.set() assert not guard.expired() + + +async def test_update_virtual_device_enable_needs_non_pro_2_5_3( + client: NanoKVMClient, mocked: aioresponses +) -> None: + """Older firmware toggles on ``enable``, so only 2.5.3 non-Pro gets it.""" + url = f"{BASE_URL}vm/device/virtual" + mocked.post(url, payload={"code": 0, "msg": "success", "data": {"on": True}}) + + for hardware, version in ((HWVersion.PCIE, "2.5.2"), (HWVersion.PRO, "9.9.9")): + mark_detected(client, hardware, version) + with pytest.raises(NanoKVMNotSupportedError): + await client.update_virtual_device(VirtualDevice.DISK, enable=True) + + mark_detected(client, HWVersion.PCIE, "2.5.3") + await client.update_virtual_device(VirtualDevice.DISK, enable=False) + + calls = mocked.requests[("POST", yarl.URL(url))] + assert [call.kwargs["json"] for call in calls] == [ + {"device": "disk", "enable": False} + ] diff --git a/tests/test_users.py b/tests/test_users.py index 03579db..e6ade66 100644 --- a/tests/test_users.py +++ b/tests/test_users.py @@ -5,7 +5,7 @@ import yarl from nanokvm.client import NanoKVMClient, NanoKVMNotSupportedError -from nanokvm.models import HWVersion, UserRole +from nanokvm.models import HWVersion, Permission, UserRole from .common import BASE_URL, mark_detected @@ -74,7 +74,7 @@ async def test_update_user_sends_only_given_fields( await client.update_user("guest", enabled=False) assert _sent_json(mocked, "PUT", "auth/users/guest") == {"enabled": False} - with pytest.raises(ValueError, match="role or enabled"): + with pytest.raises(ValueError, match="role, enabled or permissions"): await client.update_user("guest") @@ -117,3 +117,83 @@ async def test_users_require_non_pro_2_5_1( with pytest.raises(NanoKVMNotSupportedError): await client.get_users() + + +async def test_permissions_are_sent_from_2_5_3( + client: NanoKVMClient, mocked: aioresponses +) -> None: + """Grants and MCP key rotation reach the device, and older firmware refuses.""" + mark_detected(client, application_version="2.5.2") + with pytest.raises(NanoKVMNotSupportedError): + await client.update_user("guest", permissions=[Permission.POWER]) + with pytest.raises(NanoKVMNotSupportedError): + await client.delete_user("guest", rotate_mcp_key=True) + assert not mocked.requests + + mark_detected(client, application_version="2.5.3") + mocked.post(f"{BASE_URL}auth/users", payload=_OK) + mocked.put(f"{BASE_URL}auth/users/guest", payload=_OK) + mocked.delete(f"{BASE_URL}auth/users/guest?rotateMcpKey=true", payload=_OK) + + await client.create_user("guest", "pw", permissions=[]) + await client.update_user( + "guest", permissions=[Permission.CONSOLE_VIEW, "mcp"], rotate_mcp_key=True + ) + await client.delete_user("guest", rotate_mcp_key=True) + + assert _sent_json(mocked, "POST", "auth/users")["permissions"] == [] + assert _sent_json(mocked, "PUT", "auth/users/guest") == { + "permissions": ["console.view", "mcp"], + "rotateMcpKey": True, + } + assert ("DELETE", yarl.URL(f"{BASE_URL}auth/users/guest?rotateMcpKey=true")) in ( + mocked.requests + ) + + +async def test_users_and_catalog_parse_permissions( + client: NanoKVMClient, mocked: aioresponses +) -> None: + """A null permission list from the device reads as empty.""" + mark_detected(client) + mocked.get( + f"{BASE_URL}auth/users", + payload={ + **_OK, + "data": { + "users": [ + {"username": "a", "role": "admin", "enabled": True}, + { + "username": "b", + "role": "user", + "enabled": True, + "permissions": None, + }, + ] + }, + }, + ) + mocked.get( + f"{BASE_URL}auth/permissions", + payload={ + **_OK, + "data": { + "permissions": [ + {"id": "console.view", "group": "console", "risk": "info"}, + { + "id": "terminal", + "group": "host", + "risk": "warn", + "implies": ["console.view"], + }, + ] + }, + }, + ) + + users = await client.get_users() + catalog = await client.get_permissions() + + assert [user.permissions for user in users.users] == [[], []] + assert catalog.permissions[0].implies == [] + assert catalog.permissions[1].implies == ["console.view"]