Skip to content

Secure, Fast, and Extensible Sandbox runtime for AI agents.

5.6 KB
Raw Blame
#
# Copyright 2026 The OpenSandbox Authors
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
#     http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
#

from __future__ import annotations

from collections.abc import Mapping
from typing import TYPE_CHECKING, Any, TypeVar

from attrs import define as _attrs_define

from ..types import UNSET, Unset

if TYPE_CHECKING:
    from ..models.host import Host
    from ..models.ossfs import OSSFS
    from ..models.pvc import PVC


T = TypeVar("T", bound="Volume")


@_attrs_define
class Volume:
    """Storage mount definition for a sandbox. Each volume entry contains:
    - A unique name identifier
    - Exactly one backend struct (host, pvc, ossfs, etc.) with backend-specific fields
    - Common mount settings (mountPath, readOnly, subPath)

        Attributes:
            name (str): Unique identifier for the volume within the sandbox.
                Must be a valid DNS label (lowercase alphanumeric, hyphens allowed, max 63 chars).
            mount_path (str): Absolute path inside the container where the volume is mounted.
                Must start with '/'.
            host (Host | Unset): Host path bind mount backend. Maps a directory on the host filesystem
                into the container. Only available when the runtime supports host mounts.

                Security note: Host paths are restricted by server-side allowlist.
                Users must specify paths under permitted prefixes.
            pvc (PVC | Unset): Platform-managed named volume backend. A runtime-neutral abstraction
                for referencing a platform-managed named volume. If `createIfNotExists`
                is true (the default) and the volume does not yet exist, it will be
                created automatically using the provisioning hints below.

                - Kubernetes: maps to a PersistentVolumeClaim in the same namespace.
                - Docker: maps to a Docker named volume (created via `docker volume create`).
            ossfs (OSSFS | Unset): Alibaba Cloud OSS mount backend via ossfs.

                The runtime mounts a host-side OSS path under `storage.ossfs_mount_root`
                and bind-mounts the resolved path into the sandbox container.
                Prefix selection is expressed via `Volume.subPath`.
                In Docker runtime, OSSFS backend requires OpenSandbox Server to run on a Linux host with FUSE support.
            read_only (bool | Unset): If true, the volume is mounted as read-only. Defaults to false (read-write).
                 Default: False.
            sub_path (str | Unset): Optional subdirectory under the backend path to mount.
                For `ossfs` backend, this field is used as the bucket prefix.
                Must be a relative path without '..' components.
    """

    name: str
    mount_path: str
    host: Host | Unset = UNSET
    pvc: PVC | Unset = UNSET
    ossfs: OSSFS | Unset = UNSET
    read_only: bool | Unset = False
    sub_path: str | Unset = UNSET

    def to_dict(self) -> dict[str, Any]:
        name = self.name

        mount_path = self.mount_path

        host: dict[str, Any] | Unset = UNSET
        if not isinstance(self.host, Unset):
            host = self.host.to_dict()

        pvc: dict[str, Any] | Unset = UNSET
        if not isinstance(self.pvc, Unset):
            pvc = self.pvc.to_dict()

        ossfs: dict[str, Any] | Unset = UNSET
        if not isinstance(self.ossfs, Unset):
            ossfs = self.ossfs.to_dict()

        read_only = self.read_only

        sub_path = self.sub_path

        field_dict: dict[str, Any] = {}

        field_dict.update(
            {
                "name": name,
                "mountPath": mount_path,
            }
        )
        if host is not UNSET:
            field_dict["host"] = host
        if pvc is not UNSET:
            field_dict["pvc"] = pvc
        if ossfs is not UNSET:
            field_dict["ossfs"] = ossfs
        if read_only is not UNSET:
            field_dict["readOnly"] = read_only
        if sub_path is not UNSET:
            field_dict["subPath"] = sub_path

        return field_dict

    @classmethod
    def from_dict(cls: type[T], src_dict: Mapping[str, Any]) -> T:
        from ..models.host import Host
        from ..models.ossfs import OSSFS
        from ..models.pvc import PVC

        d = dict(src_dict)
        name = d.pop("name")

        mount_path = d.pop("mountPath")

        _host = d.pop("host", UNSET)
        host: Host | Unset
        if isinstance(_host, Unset):
            host = UNSET
        else:
            host = Host.from_dict(_host)

        _pvc = d.pop("pvc", UNSET)
        pvc: PVC | Unset
        if isinstance(_pvc, Unset):
            pvc = UNSET
        else:
            pvc = PVC.from_dict(_pvc)

        _ossfs = d.pop("ossfs", UNSET)
        ossfs: OSSFS | Unset
        if isinstance(_ossfs, Unset):
            ossfs = UNSET
        else:
            ossfs = OSSFS.from_dict(_ossfs)

        read_only = d.pop("readOnly", UNSET)

        sub_path = d.pop("subPath", UNSET)

        volume = cls(
            name=name,
            mount_path=mount_path,
            host=host,
            pvc=pvc,
            ossfs=ossfs,
            read_only=read_only,
            sub_path=sub_path,
        )

        return volume