opensandbox-group--opensandbox/server/opensandbox_server/services/constants.py

# Copyright 2025 Alibaba Group Holding Ltd.
#
# 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.

"""Shared constants for sandbox services."""

RESERVED_LABEL_PREFIX = "opensandbox.io/"

SANDBOX_ID_LABEL = "opensandbox.io/id"
SANDBOX_EXPIRES_AT_LABEL = "opensandbox.io/expires-at"
SANDBOX_MANUAL_CLEANUP_LABEL = "opensandbox.io/manual-cleanup"
SANDBOX_PLATFORM_OS_LABEL = "opensandbox.io/platform-os"
SANDBOX_PLATFORM_ARCH_LABEL = "opensandbox.io/platform-arch"
SANDBOX_SNAPSHOT_ID_LABEL = "opensandbox.io/snapshot-id"
# Host-mapped ports recorded on containers (bridge mode).
SANDBOX_EMBEDDING_PROXY_PORT_LABEL = (
    "opensandbox.io/embedding-proxy-port"  # maps container 44772 -> host port
)
SANDBOX_HTTP_PORT_LABEL = "opensandbox.io/http-port"  # maps container 8080 -> host port
SANDBOX_OSSFS_MOUNTS_LABEL = "opensandbox.io/ossfs-mounts"
SANDBOX_MANAGED_VOLUMES_LABEL = "opensandbox.io/volume-managed-by"
OPEN_SANDBOX_INGRESS_HEADER = "OpenSandbox-Ingress-To"
OPEN_SANDBOX_EGRESS_AUTH_HEADER = "OPENSANDBOX-EGRESS-AUTH"
SANDBOX_EGRESS_AUTH_TOKEN_METADATA_KEY = "opensandbox.io/egress-auth-token"
OPEN_SANDBOX_SECURE_ACCESS_HEADER = "OpenSandbox-Secure-Access"
SANDBOX_SECURE_ACCESS_TOKEN_METADATA_KEY = "opensandbox.io/secure-access-token"

# Environment variable name for passing network policy to egress sidecar
EGRESS_RULES_ENV = "OPENSANDBOX_EGRESS_RULES"
# Must match components/egress/pkg/constants/configuration.go EnvEgressMode
EGRESS_MODE_ENV = "OPENSANDBOX_EGRESS_MODE"
# Must match components/egress/pkg/constants/configuration.go EnvEgressToken
OPENSANDBOX_EGRESS_TOKEN = "OPENSANDBOX_EGRESS_TOKEN"
OPENSANDBOX_EGRESS_MITMPROXY_TRANSPARENT = "OPENSANDBOX_EGRESS_MITMPROXY_TRANSPARENT"

EGRESS_ENV_PREFIX = "OPENSANDBOX_EGRESS_"
OPENSANDBOX_EGRESS_MITMPROXY_SSL_INSECURE = "OPENSANDBOX_EGRESS_MITMPROXY_SSL_INSECURE"
OPENSANDBOX_EGRESS_CREDENTIAL_VAULT_TRUSTED_PROXY_CIDRS = (
    "OPENSANDBOX_EGRESS_CREDENTIAL_VAULT_TRUSTED_PROXY_CIDRS"
)
ALLOWED_EGRESS_ENV_VARS = frozenset({
    "OPENSANDBOX_EGRESS_LOG_LEVEL",
    "OPENSANDBOX_EGRESS_DNS_UPSTREAM_TIMEOUT",
    OPENSANDBOX_EGRESS_MITMPROXY_SSL_INSECURE,
    OPENSANDBOX_EGRESS_MITMPROXY_TRANSPARENT,
    "OPENSANDBOX_EGRESS_DENY_WEBHOOK",
    "OPENSANDBOX_EGRESS_METRICS_EXTRA_ATTRS",
    "OPENSANDBOX_EGRESS_CREDENTIAL_VAULT_REQUIRE_TLS",
    OPENSANDBOX_EGRESS_CREDENTIAL_VAULT_TRUSTED_PROXY_CIDRS,
    "OPENSANDBOX_EGRESS_POLICY_FILE",
})
OPENSANDBOX_RUNTIME_VOLUME_NAME = "opensandbox-bin"
OPENSANDBOX_RUNTIME_MOUNT_PATH = "/opt/opensandbox"


class SandboxErrorCodes:
    """Canonical error codes for sandbox service operations."""

    # Docker runtime error codes
    DOCKER_INITIALIZATION_ERROR = "DOCKER::INITIALIZATION_ERROR"
    CONTAINER_QUERY_FAILED = "DOCKER::SANDBOX_QUERY_FAILED"
    SANDBOX_NOT_FOUND = "DOCKER::SANDBOX_NOT_FOUND"
    IMAGE_PULL_FAILED = "DOCKER::SANDBOX_IMAGE_PULL_FAILED"
    IMAGE_REMOVE_ERROR = "DOCKER::SNAPSHOT_IMAGE_REMOVE_FAILED"
    CONTAINER_START_FAILED = "DOCKER::SANDBOX_START_FAILED"
    SANDBOX_DELETE_FAILED = "DOCKER::SANDBOX_DELETE_FAILED"
    SANDBOX_NOT_RUNNING = "DOCKER::SANDBOX_NOT_RUNNING"
    SANDBOX_PAUSE_FAILED = "DOCKER::SANDBOX_PAUSE_FAILED"
    SANDBOX_NOT_PAUSED = "DOCKER::SANDBOX_NOT_PAUSED"
    SANDBOX_RESUME_FAILED = "DOCKER::SANDBOX_RESUME_FAILED"
    INVALID_EXPIRATION = "DOCKER::INVALID_EXPIRATION"
    EXPIRATION_NOT_EXTENDED = "DOCKER::EXPIRATION_NOT_EXTENDED"
    EXECD_START_FAILED = "DOCKER::SANDBOX_EXECD_START_FAILED"
    EXECD_DISTRIBUTION_FAILED = "DOCKER::SANDBOX_EXECD_DISTRIBUTION_FAILED"
    BOOTSTRAP_INSTALL_FAILED = "DOCKER::SANDBOX_BOOTSTRAP_INSTALL_FAILED"
    INVALID_ENTRYPOINT = "DOCKER::INVALID_ENTRYPOINT"
    INVALID_PORT = "DOCKER::INVALID_PORT"
    NETWORK_MODE_ENDPOINT_UNAVAILABLE = "DOCKER::NETWORK_MODE_ENDPOINT_UNAVAILABLE"

    # Kubernetes runtime error codes
    K8S_INITIALIZATION_ERROR = "KUBERNETES::INITIALIZATION_ERROR"
    K8S_SANDBOX_NOT_FOUND = "KUBERNETES::SANDBOX_NOT_FOUND"
    K8S_POD_FAILED = "KUBERNETES::POD_FAILED"
    K8S_POD_READY_TIMEOUT = "KUBERNETES::POD_READY_TIMEOUT"
    K8S_API_ERROR = "KUBERNETES::API_ERROR"
    K8S_POD_IP_NOT_AVAILABLE = "KUBERNETES::POD_IP_NOT_AVAILABLE"

    # Common error codes
    UNKNOWN_ERROR = "SANDBOX::UNKNOWN_ERROR"
    API_NOT_SUPPORTED = "SANDBOX::API_NOT_SUPPORTED"
    INVALID_METADATA_LABEL = "SANDBOX::INVALID_METADATA_LABEL"
    INVALID_PARAMETER = "SANDBOX::INVALID_PARAMETER"

    # Pool error codes
    K8S_POOL_NOT_FOUND = "KUBERNETES::POOL_NOT_FOUND"
    K8S_POOL_ALREADY_EXISTS = "KUBERNETES::POOL_ALREADY_EXISTS"
    K8S_POOL_API_ERROR = "KUBERNETES::POOL_API_ERROR"
    K8S_POOL_NOT_SUPPORTED = "KUBERNETES::POOL_NOT_SUPPORTED"

    # Volume error codes
    INVALID_VOLUME_NAME = "VOLUME::INVALID_NAME"
    DUPLICATE_VOLUME_NAME = "VOLUME::DUPLICATE_NAME"
    INVALID_VOLUME_BACKEND = "VOLUME::INVALID_BACKEND"
    INVALID_MOUNT_PATH = "VOLUME::INVALID_MOUNT_PATH"
    INVALID_SUB_PATH = "VOLUME::INVALID_SUB_PATH"
    INVALID_HOST_PATH = "VOLUME::INVALID_HOST_PATH"
    HOST_PATH_NOT_ALLOWED = "VOLUME::HOST_PATH_NOT_ALLOWED"
    INVALID_PVC_NAME = "VOLUME::INVALID_PVC_NAME"
    UNSUPPORTED_VOLUME_BACKEND = "VOLUME::UNSUPPORTED_BACKEND"
    HOST_PATH_NOT_FOUND = "VOLUME::HOST_PATH_NOT_FOUND"
    HOST_PATH_CREATE_FAILED = "VOLUME::HOST_PATH_CREATE_FAILED"
    PVC_VOLUME_NOT_FOUND = "VOLUME::PVC_NOT_FOUND"
    PVC_VOLUME_INSPECT_FAILED = "VOLUME::PVC_INSPECT_FAILED"
    PVC_SUBPATH_UNSUPPORTED_DRIVER = "VOLUME::PVC_SUBPATH_UNSUPPORTED_DRIVER"
    INVALID_OSSFS_VERSION = "VOLUME::INVALID_OSSFS_VERSION"
    INVALID_OSSFS_ENDPOINT = "VOLUME::INVALID_OSSFS_ENDPOINT"
    INVALID_OSSFS_BUCKET = "VOLUME::INVALID_OSSFS_BUCKET"
    INVALID_OSSFS_OPTION = "VOLUME::INVALID_OSSFS_OPTION"
    INVALID_OSSFS_CREDENTIALS = "VOLUME::INVALID_OSSFS_CREDENTIALS"
    INVALID_OSSFS_MOUNT_ROOT = "VOLUME::INVALID_OSSFS_MOUNT_ROOT"
    OSSFS_PATH_NOT_FOUND = "VOLUME::OSSFS_PATH_NOT_FOUND"
    OSSFS_MOUNT_FAILED = "VOLUME::OSSFS_MOUNT_FAILED"
    OSSFS_UNMOUNT_FAILED = "VOLUME::OSSFS_UNMOUNT_FAILED"

    # Pause/Resume error codes
    INVALID_STATE = "KUBERNETES::INVALID_STATE"


class SnapshotErrorCodes:
    """Canonical error codes for snapshot service operations."""

    INVALID_SOURCE_STATE = "SNAPSHOT::INVALID_SOURCE_STATE"


__all__ = [
    "RESERVED_LABEL_PREFIX",
    "SANDBOX_ID_LABEL",
    "SANDBOX_EXPIRES_AT_LABEL",
    "SANDBOX_MANUAL_CLEANUP_LABEL",
    "SANDBOX_PLATFORM_OS_LABEL",
    "SANDBOX_PLATFORM_ARCH_LABEL",
    "SANDBOX_SNAPSHOT_ID_LABEL",
    "SANDBOX_EMBEDDING_PROXY_PORT_LABEL",
    "SANDBOX_HTTP_PORT_LABEL",
    "SANDBOX_OSSFS_MOUNTS_LABEL",
    "SANDBOX_MANAGED_VOLUMES_LABEL",
    "OPEN_SANDBOX_INGRESS_HEADER",
    "OPEN_SANDBOX_EGRESS_AUTH_HEADER",
    "SANDBOX_EGRESS_AUTH_TOKEN_METADATA_KEY",
    "OPEN_SANDBOX_SECURE_ACCESS_HEADER",
    "SANDBOX_SECURE_ACCESS_TOKEN_METADATA_KEY",
    "EGRESS_RULES_ENV",
    "EGRESS_MODE_ENV",
    "OPENSANDBOX_EGRESS_TOKEN",
    "OPENSANDBOX_EGRESS_MITMPROXY_TRANSPARENT",
    "EGRESS_ENV_PREFIX",
    "OPENSANDBOX_EGRESS_MITMPROXY_SSL_INSECURE",
    "ALLOWED_EGRESS_ENV_VARS",
    "OPENSANDBOX_RUNTIME_VOLUME_NAME",
    "OPENSANDBOX_RUNTIME_MOUNT_PATH",
    "SandboxErrorCodes",
    "SnapshotErrorCodes",
]