Source code for pyvergeos.resources.snapshots

"""VM Snapshot resource manager."""

from __future__ import annotations

import builtins
import logging
from datetime import datetime, timezone
from typing import TYPE_CHECKING, Any, cast

from pyvergeos.filters import combine_filters, quote_value
from pyvergeos.resources.base import ResourceManager, ResourceObject

if TYPE_CHECKING:
    from pyvergeos.client import VergeClient
    from pyvergeos.resources.vms import VM

logger = logging.getLogger(__name__)


def _clone_restore_vm_key(result: Any) -> int:
    """Return the new VM key from a clone-restore response.

    VergeOS returns ``{"response": {"vmkey": "52", ...}}``. ``$key`` and
    ``key`` stay as fallbacks for payloads that put the key at the top level.
    """
    raw: Any = None
    if isinstance(result, dict):
        response = result.get("response")
        if isinstance(response, dict):
            raw = response.get("vmkey")
        if not raw:
            raw = result.get("$key") or result.get("key")
    if isinstance(raw, bool) or not raw:
        raise ValueError("Clone restore did not return a VM key to power on")
    try:
        return int(raw)
    except (TypeError, ValueError) as exc:
        raise ValueError("Clone restore did not return a VM key to power on") from exc


# Default fields for snapshots
SNAPSHOT_DEFAULT_FIELDS = [
    "$key",
    "name",
    "description",
    "created",
    "expires",
    "expires_type",
    "quiesced",
    "created_manually",
    "machine",
    "snap_machine",
    "snapshot_period",
]


[docs] class VMSnapshot(ResourceObject): """VM Snapshot resource object.""" @property def created_at(self) -> datetime | None: """Get creation timestamp as datetime.""" timestamp = self.get("created") if timestamp: return datetime.fromtimestamp(int(timestamp), tz=timezone.utc) return None @property def expires_at(self) -> datetime | None: """Get expiration timestamp as datetime.""" timestamp = self.get("expires") if timestamp and int(timestamp) > 0: return datetime.fromtimestamp(int(timestamp), tz=timezone.utc) return None @property def never_expires(self) -> bool: """Check if snapshot never expires.""" expires_type = self.get("expires_type") expires = self.get("expires") return expires_type == "never" or (expires is not None and int(expires) == 0) @property def is_quiesced(self) -> bool: """Check if snapshot was quiesced.""" return bool(self.get("quiesced", False)) @property def is_manual(self) -> bool: """Check if snapshot was created manually.""" return bool(self.get("created_manually", False)) @property def snap_machine_key(self) -> int | None: """Get the snap_machine key (used for restore).""" key = self.get("snap_machine") return int(key) if key is not None else None @property def is_cloud_snapshot(self) -> bool: """Check if this is a cloud snapshot.""" return bool(self.get("snapshot_period"))
[docs] def restore(self, name: str | None = None, power_on: bool = False) -> dict[str, Any] | None: """Restore this snapshot to a new VM. Args: name: Name for the restored VM (default: "{snapshot_name} restored"). power_on: Power on the VM after restoration. Returns: Clone task information. Raises: ValueError: If the snapshot has no snap_machine, no snapshot VM exists for that machine, or ``power_on`` is set and the clone response has no VM key. NotFoundError: If this snapshot key no longer exists or belongs to another VM. APIError: If the clone or power-on request fails. The power-on error is not swallowed. Notes: Delegates to ``VMSnapshotManager.restore`` so the snap_machine (machine key) is resolved to the snapshot VM key before posting to ``vm_actions``. Posting the machine key as a VM key fails with NotFound (or, if keys collide, can clone the wrong VM). """ manager = cast("VMSnapshotManager", self._manager) return manager.restore(self.key, name=name, power_on=power_on)
[docs] class VMSnapshotManager(ResourceManager[VMSnapshot]): """Manager for VM Snapshot operations. This manager is accessed through a VM object's snapshots property. """ _endpoint = "machine_snapshots" _default_fields = SNAPSHOT_DEFAULT_FIELDS
[docs] def __init__(self, client: VergeClient, vm: VM) -> None: super().__init__(client) self._vm = vm
@property def machine_key(self) -> int: """Get the machine key for this VM.""" machine = self._vm.get("machine") if machine is None: raise ValueError("VM has no machine key") return int(machine) def _to_model(self, data: dict[str, Any]) -> VMSnapshot: return VMSnapshot(data, self) def _scope_resource(self) -> str: return "Snapshot" def _scope_bindings(self) -> list[tuple[str, Any]]: """Snapshots are owned by the VM's machine (#168).""" return [("machine", self.machine_key)]
[docs] def list( # noqa: A003 self, filter: str | None = None, # noqa: A002 fields: str | list[str] | None = None, limit: int | None = None, offset: int | None = None, **kwargs: Any, ) -> list[VMSnapshot]: """List snapshots for this VM. Args: filter: Additional OData filter string. fields: List of fields to return. **kwargs: Additional filter arguments. Returns: List of VMSnapshot objects. """ if fields is None: fields = self._default_fields # Build filter for this VM's machine machine_filter = f"machine eq {self.machine_key}" if filter: machine_filter = f"{machine_filter} and ({filter})" # Merge shorthand kwargs instead of silently dropping them (issue #96) combined_filter = combine_filters(machine_filter, kwargs) params: dict[str, Any] = { "filter": combined_filter, "fields": self._projection(fields), "sort": "-created", # Most recent first } if limit is not None: params["limit"] = limit if offset is not None: params["offset"] = offset response = self._client._request("GET", self._endpoint, params=params) if response is None: return [] if not isinstance(response, list): return [self._to_model(response)] return [self._to_model(item) for item in response]
[docs] def get( self, key: int | None = None, *, name: str | None = None, fields: str | builtins.list[str] | None = None, ) -> VMSnapshot: """Get a snapshot by key or name. Args: key: Snapshot $key (ID). name: Snapshot name. fields: List of fields to return. Returns: VMSnapshot object. Raises: NotFoundError: If the snapshot does not exist or belongs to another VM. ValueError: If neither key nor name provided. """ if fields is None: fields = self._default_fields if key is not None: from pyvergeos.exceptions import NotFoundError # list() is filtered by machine; a key is not. Ask for machine even # when the caller narrowed fields, then refuse another VM's row (#168). selected = self._with_scope_fields(fields) params: dict[str, Any] = {"fields": self._projection(selected)} response = self._client._request("GET", f"{self._endpoint}/{key}", params=params) if response is None: raise NotFoundError(f"Snapshot {key} not found") if not isinstance(response, dict): raise NotFoundError(f"Snapshot {key} returned invalid response") self._assert_row_in_scope(key, response) return self._to_model(response) if name is not None: snapshots = self.list(filter=f"name eq {quote_value(name)}", fields=fields) if not snapshots: from pyvergeos.exceptions import NotFoundError raise NotFoundError(f"Snapshot with name '{name}' not found") return snapshots[0] raise ValueError("Either key or name must be provided")
[docs] def create( # type: ignore[override] self, name: str | None = None, retention: int = 86400, quiesce: bool = False, description: str = "", ) -> dict[str, Any] | None: """Create a new snapshot for this VM. Args: name: Snapshot name (optional, auto-generated with timestamp if not provided). retention: Snapshot retention in seconds (default 24h). Use 0 for never expires. Omitted uses the 24h default. Negative values and None are rejected. quiesce: Quiesce disk activity (requires guest agent). description: Snapshot description. Returns: Created snapshot information. """ import time as _time # None/bool must not fall through: bool is an int, and False would # otherwise be stored as expires:0 ("never"). if retention is None or isinstance(retention, bool): raise TypeError("retention must be an int number of seconds; use 0 for never expires") if retention < 0: raise ValueError("retention must be non-negative; use 0 for never expires") # Generate snapshot name if not provided snapshot_name = name or f"Snapshot-{_time.strftime('%Y%m%d-%H%M%S')}" # Calculate expiration timestamp (0 means never expires) expires_timestamp = int(_time.time()) + retention if retention > 0 else 0 body: dict[str, Any] = { "machine": self.machine_key, "name": snapshot_name, "created_manually": True, "quiesce": quiesce, } # Always send expires: retention=0 must be expires:0 ("never"), not # omitted — omitting lets the platform default to +72h (#146). body["expires"] = expires_timestamp if description: body["description"] = description result = self._client._request("POST", self._endpoint, json_data=body) return result if isinstance(result, dict) else None
[docs] def delete(self, key: int) -> None: """Delete a snapshot belonging to this VM. Args: key: Snapshot $key (ID). Raises: NotFoundError: If the snapshot does not exist or belongs to another VM. """ self._ensure_in_scope(key) self._client._request("DELETE", f"{self._endpoint}/{key}")
[docs] def restore( self, key: int, name: str | None = None, replace_original: bool = False, power_on: bool = False, ) -> dict[str, Any] | None: """Restore a snapshot. Args: key: Snapshot $key (ID). name: Name for the restored VM (only for clone mode). replace_original: If True, revert original VM to snapshot state. WARNING: All changes since snapshot will be lost. power_on: Power on VM after restoration. Returns: Restore task information. An in-place restore often returns None because the action body is empty. Raises: ValueError: If the snapshot has no snap_machine, no snapshot VM exists, the VM is running for an in-place restore, or ``power_on`` is set and a clone response has no VM key. NotFoundError: If the snapshot does not exist or belongs to another VM. APIError: If the restore or power-on request fails. The power-on error is not swallowed. """ # get() already fetched the row, and it rejects another VM's snapshot # before the snap_machine lookup or any vm_actions post (#168). snapshot = self.get(key) snap_machine_key = snapshot.snap_machine_key if snap_machine_key is None: raise ValueError("Snapshot does not have a valid snap_machine reference") # Find the snapshot VM that has this machine # The snap_machine is a machine key, not a VM key # We need to find the VM where machine = snap_machine response = self._client._request( "GET", "vms", params={ "filter": f"machine eq {snap_machine_key}", "fields": "$key,name,machine,is_snapshot", }, ) snap_vm_key = None if response: vms = response if isinstance(response, list) else [response] for vm_data in vms: if not isinstance(vm_data, dict) or not vm_data.get("is_snapshot"): continue # Trust an integer machine when the server returned one. A # row for a different machine must not be cloned just because # it is also a snapshot (key-collision case, #147). machine = vm_data.get("machine") if ( isinstance(machine, int) and not isinstance(machine, bool) and machine != snap_machine_key ): continue vm_key = vm_data.get("$key") if vm_key is None: continue snap_vm_key = vm_key break if snap_vm_key is None: raise ValueError(f"Could not find snapshot VM with machine key {snap_machine_key}") if replace_original: # In-place restore - revert original VM if self._vm.is_running: raise ValueError("VM must be powered off for in-place restore") body: dict[str, Any] = { "vm": snap_vm_key, "action": "restore", } result = self._client._request("POST", "vm_actions", json_data=body) # The restore action returns an empty body, so result is None. # Power on the original VM whenever requested (#172). if power_on: self._power_on_vm(self._vm.key) return result if isinstance(result, dict) else None else: # Clone mode - create new VM from snapshot restored_name = name or f"{snapshot.get('name', 'snapshot')} restored" body = { "vm": snap_vm_key, "action": "clone", "params": {"name": restored_name}, } result = self._client._request("POST", "vm_actions", json_data=body) if power_on: # Platform shape is {"response": {"vmkey": "..."}}; $key / key # remain fallbacks. A failed power-on POST propagates (#172). self._power_on_vm(_clone_restore_vm_key(result)) return result if isinstance(result, dict) else None
def _power_on_vm(self, vm_key: int) -> None: """Power on a VM after restore. The POST is not caught: an API error reaches the caller. """ import time time.sleep(2) self._client._request( "POST", "vm_actions", json_data={"vm": vm_key, "action": "poweron"}, )