morphcloud 0.1.114__tar.gz → 0.1.116__tar.gz

{morphcloud-0.1.114 → morphcloud-0.1.116}/PKG-INFO

@@ -1,10 +1,10 @@
 Metadata-Version: 2.5
 Name: morphcloud
-Version: 0.1.114
+Version: 0.1.116
 Summary: A Python SDK and CLI tool for creating, managing, and interacting with Morph Cloud VMs.
 License: Apache-2.0
 License-File: LICENSE
-Requires-Python: >=3.11
+Requires-Python: >=3.10
 Requires-Dist: click>=8.1.7
 Requires-Dist: httpx>=0.27.0
 Requires-Dist: packaging>=24.2

morphcloud-0.1.116/morphcloud/_disk_resize.py

@@ -0,0 +1,154 @@
+"""Disk-capacity operation values and local waiting policy.
+
+Waiting never changes a remote operation: timeouts and cancellation only stop
+local observation. Every error preserves the request key and operation evidence
+available to that invocation so a caller can safely resume observation or replay.
+"""
+from __future__ import annotations
+import math
+import time
+import uuid
+from datetime import datetime
+from typing import Literal
+from urllib.parse import quote
+from pydantic import BaseModel, ConfigDict, Field
+
+class DiskResizeOperationError(BaseModel):
+    """Service rejection or failure details, including a measured minimum."""
+    model_config = ConfigDict(frozen=True)
+    code: str
+    message: str
+    retryable: bool
+    minimum_target_mib: int | None = Field(default=None, ge=0)
+
+class DiskResizeOperation(BaseModel):
+    """An observed disk resize; byte observations are null until known.
+
+    ``requested_disk_size`` and ``previous_disk_size`` use MiB. A successful
+    operation changes effective capacity; backing storage observations may differ.
+    ``idempotency_key`` is local recovery context, never inferred by GET calls.
+    """
+    model_config = ConfigDict(frozen=True)
+    object: Literal['instance_disk_resize'] = 'instance_disk_resize'
+    id: str = Field(min_length=1)
+    instance_id: str = Field(min_length=1)
+    previous_disk_size: int = Field(ge=0)
+    requested_disk_size: int = Field(ge=256, le=1048576)
+    capacity_mode: str
+    status: Literal['pending', 'running', 'succeeded', 'failed', 'recovery_required']
+    phase: Literal['accepted', 'geometry_ready', 'budget_applied', 'complete']
+    capacity_generation: int = Field(ge=0)
+    effective_capacity_bytes: int | None = Field(default=None, ge=0)
+    statfs_total_bytes: int | None = Field(default=None, ge=0)
+    charged_bytes: int | None = Field(default=None, ge=0)
+    reserved_bytes: int | None = Field(default=None, ge=0)
+    backing_bytes: int | None = Field(default=None, ge=0)
+    guest_device_bytes: int | None = Field(default=None, ge=0)
+    ext4_geometry_bytes: int | None = Field(default=None, ge=0)
+    error: DiskResizeOperationError | None = None
+    retry_after_seconds: float = Field(default=1, ge=0, allow_inf_nan=False)
+    created_at: datetime
+    updated_at: datetime
+    completed_at: datetime | None = None
+    idempotency_key: str | None = None
+
+class DiskResizeError(Exception):
+    """Base failure with enough evidence to resume or replay safely."""
+
+    def __init__(self, message: str, *, operation: DiskResizeOperation | None=None, operation_id: str | None=None, idempotency_key: str | None=None) -> None:
+        self.operation = operation
+        self.operation_id = operation.id if operation else operation_id
+        self.idempotency_key = idempotency_key or (operation.idempotency_key if operation else None)
+        recovery = []
+        if self.operation_id:
+            recovery.append(f'operation_id={self.operation_id}')
+        if self.idempotency_key:
+            recovery.append(f'idempotency_key={self.idempotency_key}')
+        if recovery:
+            message += ' (' + ', '.join(recovery) + ')'
+        super().__init__(message)
+
+class DiskResizeFailed(DiskResizeError):
+    """The observed operation failed; inspect its structured error."""
+
+class DiskResizeRecoveryRequired(DiskResizeError):
+    """The operation requires recovery; do not submit a replacement."""
+
+class DiskResizeTimeout(DiskResizeError, TimeoutError):
+    """Local waiting expired. The remote operation was not cancelled."""
+
+class DiskResizeRequestError(DiskResizeError):
+    """A request failed or returned invalid evidence; its cause is preserved."""
+
+    def __init__(self, message: str, *, cause: Exception, operation: DiskResizeOperation | None=None, operation_id: str | None=None, idempotency_key: str | None=None) -> None:
+        self.status_code = getattr(cause, 'status_code', None)
+        self.error_code = getattr(cause, 'error_code', None)
+        self.response_body = getattr(cause, 'response_body', None)
+        if self.status_code is not None:
+            message += f'; HTTP {self.status_code}'
+        if self.error_code is not None:
+            message += f'; {self.error_code}'
+        super().__init__(message, operation=operation, operation_id=operation_id, idempotency_key=idempotency_key)
+
+class DiskResizeRefreshError(DiskResizeError):
+    """Resize succeeded, but refreshing the local Instance failed.
+
+    ``operation`` remains the successful receipt. Do not repeat the resize to
+    refresh an instance; retrieve the instance separately.
+    """
+
+def request_key(disk_size: int, idempotency_key: str | None) -> str:
+    if type(disk_size) is not int or not 256 <= disk_size <= 1048576:
+        raise ValueError('disk_size must be an integer MiB value from 256 to 1048576')
+    if idempotency_key is None:
+        return str(uuid.uuid4())
+    if not isinstance(idempotency_key, str) or not 1 <= len(idempotency_key) <= 128:
+        raise ValueError('idempotency_key must contain 1 to 128 ASCII characters')
+    if any((ord(character) < 33 or ord(character) > 126 for character in idempotency_key)):
+        raise ValueError('idempotency_key must contain visible ASCII characters')
+    return idempotency_key
+
+def deadline(timeout: float) -> float:
+    if isinstance(timeout, bool) or not isinstance(timeout, (int, float)):
+        raise ValueError('timeout must be a finite positive number of seconds')
+    if not math.isfinite(timeout) or timeout <= 0:
+        raise ValueError('timeout must be a finite positive number of seconds')
+    return time.monotonic() + timeout
+
+def remaining(end: float, *, operation: DiskResizeOperation | None=None, operation_id: str | None=None, idempotency_key: str | None=None) -> float:
+    seconds = end - time.monotonic()
+    if seconds <= 0:
+        raise DiskResizeTimeout('Disk resize waiting timed out; remote work may still be running', operation=operation, operation_id=operation_id, idempotency_key=idempotency_key)
+    return seconds
+
+def operation_path(instance_id: str, operation_id: str | None=None) -> str:
+    if not isinstance(instance_id, str) or not instance_id:
+        raise ValueError('instance_id must be a nonempty string')
+    path = f"/instance/{quote(instance_id, safe='')}/disk-resize"
+    if operation_id is not None:
+        if not isinstance(operation_id, str) or not operation_id:
+            raise ValueError('operation_id must be a nonempty string')
+        path += f"/{quote(operation_id, safe='')}"
+    return path
+
+def parse_operation(payload: object, instance_id: str, *, operation_id: str | None=None, idempotency_key: str | None=None, requested_disk_size: int | None=None, previous: DiskResizeOperation | None=None) -> DiskResizeOperation:
+    operation = DiskResizeOperation.model_validate(payload)
+    if operation.instance_id != instance_id:
+        raise ValueError('Disk resize response instance does not match the request')
+    if operation_id is not None and operation.id != operation_id:
+        raise ValueError('Disk resize response operation does not match the request')
+    if requested_disk_size is not None and operation.requested_disk_size != requested_disk_size:
+        raise ValueError('Disk resize response target does not match the request')
+    if previous is not None and operation.capacity_generation < previous.capacity_generation:
+        raise ValueError('Disk resize response capacity generation regressed')
+    return operation.model_copy(update={'idempotency_key': idempotency_key})
+
+def terminal(operation: DiskResizeOperation) -> bool:
+    if operation.status == 'failed':
+        raise DiskResizeFailed('Disk resize failed', operation=operation)
+    if operation.status == 'recovery_required':
+        raise DiskResizeRecoveryRequired('Disk resize requires recovery', operation=operation)
+    return operation.status == 'succeeded'
+
+def poll_delay(operation: DiskResizeOperation, end: float) -> float:
+    return min(max(operation.retry_after_seconds, 0.1), 5, remaining(end, operation=operation))

{morphcloud-0.1.114 → morphcloud-0.1.116}/morphcloud/api.py

@@ -11,6 +11,8 @@ from functools import lru_cache
 import httpx
 from pydantic import BaseModel, Field, PrivateAttr, model_validator
 from rich.console import Console
+from morphcloud import _disk_resize
+from morphcloud._disk_resize import DiskResizeError, DiskResizeFailed, DiskResizeOperation, DiskResizeOperationError, DiskResizeRecoveryRequired, DiskResizeRefreshError, DiskResizeRequestError, DiskResizeTimeout
 from morphcloud._http_transport import build_async_http_transport, build_http_transport
 from morphcloud._utils import StrEnum
 from morphcloud.config import resolve_settings
@@ -1354,6 +1356,111 @@ class InstanceAPI(BaseAPI):
         response = await self._client._async_http_client.delete(f'/instance/{instance_id}')
         response.raise_for_status()
 
+    def resize_disk(self, instance_id: str, *, disk_size: int, idempotency_key: str | None=None, wait: bool=True, timeout: float=300) -> DiskResizeOperation:
+        """Set absolute disk capacity in MiB without rebooting an eligible instance.
+
+        Waiting is local: timeout never cancels accepted work. Preserve the
+        returned/exception idempotency key to replay after an uncertain response.
+        Decreases must fit existing usage and required headroom.
+        """
+        end = _disk_resize.deadline(timeout)
+        key = _disk_resize.request_key(disk_size, idempotency_key)
+        path = _disk_resize.operation_path(instance_id)
+        if not isinstance(wait, bool):
+            raise ValueError('wait must be a bool')
+        try:
+            response = self._client._http_client.post(path, json={'disk_size': disk_size}, headers={'Idempotency-Key': key}, timeout=min(30, _disk_resize.remaining(end, idempotency_key=key)))
+            response.raise_for_status()
+            operation = _disk_resize.parse_operation(response.json(), instance_id, idempotency_key=key, requested_disk_size=disk_size)
+        except httpx.TimeoutException as exc:
+            raise DiskResizeTimeout('Disk resize submission timed out; replay with the same key', idempotency_key=key) from exc
+        except (ApiError, httpx.HTTPError, ValueError) as exc:
+            raise DiskResizeRequestError('Disk resize submission failed; preserve the key for safe replay', cause=exc, idempotency_key=key) from exc
+        if _disk_resize.terminal(operation) or not wait:
+            return operation
+        return self._wait_disk_resize(instance_id, operation.id, end, operation)
+
+    async def aresize_disk(self, instance_id: str, *, disk_size: int, idempotency_key: str | None=None, wait: bool=True, timeout: float=300) -> DiskResizeOperation:
+        """Async resize_disk; cancelling the caller does not cancel remote work.
+
+        Supply a persistent key before starting if cancellation must be recoverable
+        across processes, including cancellation before an operation ID is known.
+        """
+        end = _disk_resize.deadline(timeout)
+        key = _disk_resize.request_key(disk_size, idempotency_key)
+        path = _disk_resize.operation_path(instance_id)
+        if not isinstance(wait, bool):
+            raise ValueError('wait must be a bool')
+        try:
+            seconds = _disk_resize.remaining(end, idempotency_key=key)
+            response = await asyncio.wait_for(self._client._async_http_client.post(path, json={'disk_size': disk_size}, headers={'Idempotency-Key': key}, timeout=min(30, seconds)), timeout=seconds)
+            response.raise_for_status()
+            operation = _disk_resize.parse_operation(response.json(), instance_id, idempotency_key=key, requested_disk_size=disk_size)
+        except (httpx.TimeoutException, asyncio.TimeoutError) as exc:
+            raise DiskResizeTimeout('Disk resize submission timed out; replay with the same key', idempotency_key=key) from exc
+        except (ApiError, httpx.HTTPError, ValueError) as exc:
+            raise DiskResizeRequestError('Disk resize submission failed; preserve the key for safe replay', cause=exc, idempotency_key=key) from exc
+        if _disk_resize.terminal(operation) or not wait:
+            return operation
+        return await self._await_disk_resize(instance_id, operation.id, end, operation)
+
+    def get_disk_resize(self, instance_id: str, operation_id: str) -> DiskResizeOperation:
+        """Inspect the exact operation, including failed or recovery-required state."""
+        return self._get_disk_resize(instance_id, operation_id, _disk_resize.deadline(30))
+
+    async def aget_disk_resize(self, instance_id: str, operation_id: str) -> DiskResizeOperation:
+        """Async inspection of the exact operation without changing its state."""
+        return await self._aget_disk_resize(instance_id, operation_id, _disk_resize.deadline(30))
+
+    def _get_disk_resize(self, instance_id: str, operation_id: str, end: float, previous: DiskResizeOperation | None=None) -> DiskResizeOperation:
+        path = _disk_resize.operation_path(instance_id, operation_id)
+        key = previous.idempotency_key if previous else None
+        try:
+            response = self._client._http_client.get(path, timeout=min(30, _disk_resize.remaining(end, operation=previous, operation_id=operation_id)))
+            response.raise_for_status()
+            return _disk_resize.parse_operation(response.json(), instance_id, operation_id=operation_id, idempotency_key=key, requested_disk_size=previous.requested_disk_size if previous else None, previous=previous)
+        except httpx.TimeoutException as exc:
+            raise DiskResizeTimeout('Disk resize observation timed out; remote work was not cancelled', operation=previous, operation_id=operation_id) from exc
+        except (ApiError, httpx.HTTPError, ValueError) as exc:
+            raise DiskResizeRequestError('Disk resize observation failed; inspect this operation again', cause=exc, operation=previous, operation_id=operation_id) from exc
+
+    async def _aget_disk_resize(self, instance_id: str, operation_id: str, end: float, previous: DiskResizeOperation | None=None) -> DiskResizeOperation:
+        path = _disk_resize.operation_path(instance_id, operation_id)
+        key = previous.idempotency_key if previous else None
+        try:
+            seconds = _disk_resize.remaining(end, operation=previous, operation_id=operation_id)
+            response = await asyncio.wait_for(self._client._async_http_client.get(path, timeout=min(30, seconds)), timeout=seconds)
+            response.raise_for_status()
+            return _disk_resize.parse_operation(response.json(), instance_id, operation_id=operation_id, idempotency_key=key, requested_disk_size=previous.requested_disk_size if previous else None, previous=previous)
+        except (httpx.TimeoutException, asyncio.TimeoutError) as exc:
+            raise DiskResizeTimeout('Disk resize observation timed out; remote work was not cancelled', operation=previous, operation_id=operation_id) from exc
+        except (ApiError, httpx.HTTPError, ValueError) as exc:
+            raise DiskResizeRequestError('Disk resize observation failed; inspect this operation again', cause=exc, operation=previous, operation_id=operation_id) from exc
+
+    def wait_disk_resize(self, instance_id: str, operation_id: str, *, timeout: float=300) -> DiskResizeOperation:
+        """Wait for this operation; raise typed terminal errors or a local timeout."""
+        return self._wait_disk_resize(instance_id, operation_id, _disk_resize.deadline(timeout))
+
+    async def await_disk_resize(self, instance_id: str, operation_id: str, *, timeout: float=300) -> DiskResizeOperation:
+        """Async wait; cancellation stops observation without cancelling remote work."""
+        return await self._await_disk_resize(instance_id, operation_id, _disk_resize.deadline(timeout))
+
+    def _wait_disk_resize(self, instance_id: str, operation_id: str, end: float, operation: DiskResizeOperation | None=None) -> DiskResizeOperation:
+        while True:
+            if operation is not None:
+                if _disk_resize.terminal(operation):
+                    return operation
+                time.sleep(_disk_resize.poll_delay(operation, end))
+            operation = self._get_disk_resize(instance_id, operation_id, end, operation)
+
+    async def _await_disk_resize(self, instance_id: str, operation_id: str, end: float, operation: DiskResizeOperation | None=None) -> DiskResizeOperation:
+        while True:
+            if operation is not None:
+                if _disk_resize.terminal(operation):
+                    return operation
+                await asyncio.sleep(_disk_resize.poll_delay(operation, end))
+            operation = await self._aget_disk_resize(instance_id, operation_id, end, operation)
+
     def reboot(self, instance_id: str, *, vcpus: typing.Optional[int]=None, memory: typing.Optional[int]=None, disk_size: typing.Optional[int]=None, metadata: typing.Optional[typing.Dict[str, str]]=None, ttl_seconds: typing.Optional[int]=None, ttl_action: typing.Union[None, typing.Literal['stop', 'pause']]=None) -> Instance:
         """
         Reboot an instance by its ID, optionally applying a new machine configuration.
@@ -1918,6 +2025,30 @@ class Instance(BaseModel):
         response = await self._api._client._async_http_client.post(f'/instance/{self.id}/snapshot', params=params, json=body)
         return Snapshot.model_validate(response.json())._set_api(self._api._client.snapshots)
 
+    def resize_disk(self, *, disk_size: int, idempotency_key: str | None=None, wait: bool=True, timeout: float=300) -> DiskResizeOperation:
+        """Resize disk capacity; refresh local state only after confirmed success.
+
+        A DiskResizeRefreshError retains the successful operation if the later
+        refresh fails. Waiting timeout does not cancel the remote operation.
+        """
+        operation = self._api.resize_disk(self.id, disk_size=disk_size, idempotency_key=idempotency_key, wait=wait, timeout=timeout)
+        if operation.status == 'succeeded':
+            try:
+                self._refresh()
+            except (ApiError, httpx.HTTPError, ValueError) as exc:
+                raise DiskResizeRefreshError('Disk resize succeeded, but instance refresh failed', operation=operation) from exc
+        return operation
+
+    async def aresize_disk(self, *, disk_size: int, idempotency_key: str | None=None, wait: bool=True, timeout: float=300) -> DiskResizeOperation:
+        """Async resize with success evidence preserved across refresh failures."""
+        operation = await self._api.aresize_disk(self.id, disk_size=disk_size, idempotency_key=idempotency_key, wait=wait, timeout=timeout)
+        if operation.status == 'succeeded':
+            try:
+                await self._refresh_async()
+            except (ApiError, httpx.HTTPError, ValueError) as exc:
+                raise DiskResizeRefreshError('Disk resize succeeded, but instance refresh failed', operation=operation) from exc
+        return operation
+
     def reboot(self, *, vcpus: typing.Optional[int]=None, memory: typing.Optional[int]=None, disk_size: typing.Optional[int]=None, metadata: typing.Optional[typing.Dict[str, str]]=None, ttl_seconds: typing.Optional[int]=None, ttl_action: typing.Union[None, typing.Literal['stop', 'pause']]=None) -> None:
         """
         Reboot the instance, optionally applying a new machine configuration.