feat(admin): add POST /sandboxes/{sandbox_id}/archive endpoint

RESTful-style archive endpoint following the same pattern as
POST /sandboxes/{sandbox_id}/restart (0632c8b).

Author: zhangjaycee

rock/admin/entrypoints/sandbox_api.py

@@ -452,10 +452,10 @@ async def delete(sandbox_id: str = Body(..., embed=True)) -> RockResponse:
     return RockResponse(result=f"{sandbox_id} deleted")
 
 
-@sandbox_router.post("/archive")
+@sandbox_router.post("/sandboxes/{sandbox_id}/archive")
 @handle_exceptions(error_message="archive sandbox failed")
 async def archive(
-    sandbox_id: str = Body(..., embed=True),
+    sandbox_id: NonBlankStr,
     rock_authorization: str | None = Header(default=None, alias="X-Key"),
 ) -> RockResponse:
     archive_cfg = sandbox_manager.rock_config.lifecycle.archive

rock/deployments/config.py

@@ -118,7 +118,9 @@ class DockerDeploymentConfig(DeploymentConfig):
     """Custom name for the container. If None, a random name will be generated."""
 
     auto_delete_seconds: int | None = None
-    """If set, the container will be automatically deleted after container stopped."""
+    """Per-sandbox auto-delete policy. 0 = --rm (immediate delete on stop);
+    >0 = delete after this many seconds idle; None = fall back to global
+    lifecycle.auto_delete_after_sec."""
 
     type: Literal["docker"] = "docker"
     """Deployment type discriminator for serialization/deserialization and CLI parsing. Should not be modified."""

tests/unit/admin/entrypoints/test_sandbox_restful_api.py

@@ -0,0 +1,51 @@
+"""Tests for RESTful sandbox endpoints on sandbox_router."""
+
+from unittest.mock import AsyncMock, MagicMock
+
+import pytest
+from fastapi import FastAPI
+from fastapi.exceptions import RequestValidationError
+from httpx import ASGITransport, AsyncClient
+
+from rock.admin.entrypoints.sandbox_api import sandbox_router, set_sandbox_manager
+from rock.common.exception import request_validation_exception_handler
+
+
+@pytest.fixture
+def sandbox_app():
+    mock_manager = MagicMock()
+    mock_manager.rock_config = MagicMock()
+    mock_manager.rock_config.nacos_provider = None
+    set_sandbox_manager(mock_manager)
+    app = FastAPI()
+    app.add_exception_handler(RequestValidationError, request_validation_exception_handler)
+    app.include_router(sandbox_router, prefix="/apis/envs/sandbox/v1")
+    return app, mock_manager
+
+
+BASE = "/apis/envs/sandbox/v1"
+
+
+@pytest.mark.asyncio
+async def test_archive_allowed(sandbox_app):
+    app, mock_manager = sandbox_app
+    mock_manager.rock_config.lifecycle.archive.is_allowed.return_value = True
+    mock_manager.archive_sandbox = AsyncMock()
+    async with AsyncClient(transport=ASGITransport(app=app), base_url="http://test") as client:
+        resp = await client.post(f"{BASE}/sandboxes/sb-1/archive")
+        assert resp.status_code == 200
+        assert resp.json()["status"] == "Success"
+    mock_manager.archive_sandbox.assert_called_once_with("sb-1")
+
+
+@pytest.mark.asyncio
+async def test_archive_forbidden(sandbox_app):
+    """Unauthorised key: handle_exceptions returns HTTP 200 with status=Failed."""
+    app, mock_manager = sandbox_app
+    mock_manager.rock_config.lifecycle.archive.is_allowed.return_value = False
+    mock_manager.archive_sandbox = AsyncMock()
+    async with AsyncClient(transport=ASGITransport(app=app), base_url="http://test") as client:
+        resp = await client.post(f"{BASE}/sandboxes/sb-1/archive", headers={"X-Key": "bad-key"})
+        assert resp.status_code == 200
+        assert resp.json()["status"] == "Failed"
+    mock_manager.archive_sandbox.assert_not_called()