openhands-agent-server 1.49.6__tar.gz → 1.50.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (98) hide show
  1. {openhands_agent_server-1.49.6 → openhands_agent_server-1.50.0}/PKG-INFO +2 -2
  2. {openhands_agent_server-1.49.6 → openhands_agent_server-1.50.0}/openhands/agent_server/api.py +7 -0
  3. openhands_agent_server-1.50.0/openhands/agent_server/canvas_extensions/backend.py +649 -0
  4. {openhands_agent_server-1.49.6 → openhands_agent_server-1.50.0}/openhands/agent_server/canvas_extensions/manifest.py +88 -2
  5. {openhands_agent_server-1.49.6 → openhands_agent_server-1.50.0}/openhands/agent_server/canvas_extensions_router.py +124 -7
  6. {openhands_agent_server-1.49.6 → openhands_agent_server-1.50.0}/openhands/agent_server/conversation_service.py +9 -3
  7. {openhands_agent_server-1.49.6 → openhands_agent_server-1.50.0}/openhands/agent_server/event_service.py +6 -0
  8. openhands_agent_server-1.50.0/openhands/agent_server/managed_llm_key.py +148 -0
  9. {openhands_agent_server-1.49.6 → openhands_agent_server-1.50.0}/openhands/agent_server/profiles_router.py +5 -1
  10. {openhands_agent_server-1.49.6 → openhands_agent_server-1.50.0}/openhands_agent_server.egg-info/PKG-INFO +2 -2
  11. {openhands_agent_server-1.49.6 → openhands_agent_server-1.50.0}/openhands_agent_server.egg-info/SOURCES.txt +4 -0
  12. {openhands_agent_server-1.49.6 → openhands_agent_server-1.50.0}/openhands_agent_server.egg-info/requires.txt +1 -1
  13. {openhands_agent_server-1.49.6 → openhands_agent_server-1.50.0}/pyproject.toml +2 -2
  14. {openhands_agent_server-1.49.6 → openhands_agent_server-1.50.0}/openhands/agent_server/__init__.py +0 -0
  15. {openhands_agent_server-1.49.6 → openhands_agent_server-1.50.0}/openhands/agent_server/__main__.py +0 -0
  16. {openhands_agent_server-1.49.6 → openhands_agent_server-1.50.0}/openhands/agent_server/_secret_redaction.py +0 -0
  17. {openhands_agent_server-1.49.6 → openhands_agent_server-1.50.0}/openhands/agent_server/_secrets_exposure.py +0 -0
  18. {openhands_agent_server-1.49.6 → openhands_agent_server-1.50.0}/openhands/agent_server/agent_profiles_router.py +0 -0
  19. {openhands_agent_server-1.49.6 → openhands_agent_server-1.50.0}/openhands/agent_server/auth_router.py +0 -0
  20. {openhands_agent_server-1.49.6 → openhands_agent_server-1.50.0}/openhands/agent_server/bash_router.py +0 -0
  21. {openhands_agent_server-1.49.6 → openhands_agent_server-1.50.0}/openhands/agent_server/bash_service.py +0 -0
  22. {openhands_agent_server-1.49.6 → openhands_agent_server-1.50.0}/openhands/agent_server/canvas_extensions/__init__.py +0 -0
  23. {openhands_agent_server-1.49.6 → openhands_agent_server-1.50.0}/openhands/agent_server/canvas_extensions/installed.py +0 -0
  24. {openhands_agent_server-1.49.6 → openhands_agent_server-1.50.0}/openhands/agent_server/config.py +0 -0
  25. {openhands_agent_server-1.49.6 → openhands_agent_server-1.50.0}/openhands/agent_server/conversation_lease.py +0 -0
  26. {openhands_agent_server-1.49.6 → openhands_agent_server-1.50.0}/openhands/agent_server/conversation_registry.py +0 -0
  27. {openhands_agent_server-1.49.6 → openhands_agent_server-1.50.0}/openhands/agent_server/conversation_router.py +0 -0
  28. {openhands_agent_server-1.49.6 → openhands_agent_server-1.50.0}/openhands/agent_server/credential_binding.py +0 -0
  29. {openhands_agent_server-1.49.6 → openhands_agent_server-1.50.0}/openhands/agent_server/dependencies.py +0 -0
  30. {openhands_agent_server-1.49.6 → openhands_agent_server-1.50.0}/openhands/agent_server/docker/Dockerfile +0 -0
  31. {openhands_agent_server-1.49.6 → openhands_agent_server-1.50.0}/openhands/agent_server/docker/build.py +0 -0
  32. {openhands_agent_server-1.49.6 → openhands_agent_server-1.50.0}/openhands/agent_server/docker_runtime/__init__.py +0 -0
  33. {openhands_agent_server-1.49.6 → openhands_agent_server-1.50.0}/openhands/agent_server/docker_runtime/mediation.py +0 -0
  34. {openhands_agent_server-1.49.6 → openhands_agent_server-1.50.0}/openhands/agent_server/docker_runtime/provisioning.py +0 -0
  35. {openhands_agent_server-1.49.6 → openhands_agent_server-1.50.0}/openhands/agent_server/docker_runtime/proxy.py +0 -0
  36. {openhands_agent_server-1.49.6 → openhands_agent_server-1.50.0}/openhands/agent_server/docker_runtime/registry.py +0 -0
  37. {openhands_agent_server-1.49.6 → openhands_agent_server-1.50.0}/openhands/agent_server/docker_runtime/routers.py +0 -0
  38. {openhands_agent_server-1.49.6 → openhands_agent_server-1.50.0}/openhands/agent_server/env_parser.py +0 -0
  39. {openhands_agent_server-1.49.6 → openhands_agent_server-1.50.0}/openhands/agent_server/event_router.py +0 -0
  40. {openhands_agent_server-1.49.6 → openhands_agent_server-1.50.0}/openhands/agent_server/file_router.py +0 -0
  41. {openhands_agent_server-1.49.6 → openhands_agent_server-1.50.0}/openhands/agent_server/git_router.py +0 -0
  42. {openhands_agent_server-1.49.6 → openhands_agent_server-1.50.0}/openhands/agent_server/hooks_router.py +0 -0
  43. {openhands_agent_server-1.49.6 → openhands_agent_server-1.50.0}/openhands/agent_server/hooks_service.py +0 -0
  44. {openhands_agent_server-1.49.6 → openhands_agent_server-1.50.0}/openhands/agent_server/init_router.py +0 -0
  45. {openhands_agent_server-1.49.6 → openhands_agent_server-1.50.0}/openhands/agent_server/llm_router.py +0 -0
  46. {openhands_agent_server-1.49.6 → openhands_agent_server-1.50.0}/openhands/agent_server/local_secret_resolver.py +0 -0
  47. {openhands_agent_server-1.49.6 → openhands_agent_server-1.50.0}/openhands/agent_server/logging_config.py +0 -0
  48. {openhands_agent_server-1.49.6 → openhands_agent_server-1.50.0}/openhands/agent_server/mcp_oauth_store.py +0 -0
  49. {openhands_agent_server-1.49.6 → openhands_agent_server-1.50.0}/openhands/agent_server/mcp_router.py +0 -0
  50. {openhands_agent_server-1.49.6 → openhands_agent_server-1.50.0}/openhands/agent_server/meta_profiles_router.py +0 -0
  51. {openhands_agent_server-1.49.6 → openhands_agent_server-1.50.0}/openhands/agent_server/middleware.py +0 -0
  52. {openhands_agent_server-1.49.6 → openhands_agent_server-1.50.0}/openhands/agent_server/models.py +0 -0
  53. {openhands_agent_server-1.49.6 → openhands_agent_server-1.50.0}/openhands/agent_server/openai/__init__.py +0 -0
  54. {openhands_agent_server-1.49.6 → openhands_agent_server-1.50.0}/openhands/agent_server/openai/models.py +0 -0
  55. {openhands_agent_server-1.49.6 → openhands_agent_server-1.50.0}/openhands/agent_server/openai/router.py +0 -0
  56. {openhands_agent_server-1.49.6 → openhands_agent_server-1.50.0}/openhands/agent_server/openai/service.py +0 -0
  57. {openhands_agent_server-1.49.6 → openhands_agent_server-1.50.0}/openhands/agent_server/openapi.py +0 -0
  58. {openhands_agent_server-1.49.6 → openhands_agent_server-1.50.0}/openhands/agent_server/persistence/__init__.py +0 -0
  59. {openhands_agent_server-1.49.6 → openhands_agent_server-1.50.0}/openhands/agent_server/persistence/models.py +0 -0
  60. {openhands_agent_server-1.49.6 → openhands_agent_server-1.50.0}/openhands/agent_server/persistence/store.py +0 -0
  61. {openhands_agent_server-1.49.6 → openhands_agent_server-1.50.0}/openhands/agent_server/plugins_router.py +0 -0
  62. {openhands_agent_server-1.49.6 → openhands_agent_server-1.50.0}/openhands/agent_server/plugins_service.py +0 -0
  63. {openhands_agent_server-1.49.6 → openhands_agent_server-1.50.0}/openhands/agent_server/provider_connections_router.py +0 -0
  64. {openhands_agent_server-1.49.6 → openhands_agent_server-1.50.0}/openhands/agent_server/pub_sub.py +0 -0
  65. {openhands_agent_server-1.49.6 → openhands_agent_server-1.50.0}/openhands/agent_server/py.typed +0 -0
  66. {openhands_agent_server-1.49.6 → openhands_agent_server-1.50.0}/openhands/agent_server/runtime_router.py +0 -0
  67. {openhands_agent_server-1.49.6 → openhands_agent_server-1.50.0}/openhands/agent_server/server_details_router.py +0 -0
  68. {openhands_agent_server-1.49.6 → openhands_agent_server-1.50.0}/openhands/agent_server/session_protocol.py +0 -0
  69. {openhands_agent_server-1.49.6 → openhands_agent_server-1.50.0}/openhands/agent_server/session_socket.py +0 -0
  70. {openhands_agent_server-1.49.6 → openhands_agent_server-1.50.0}/openhands/agent_server/settings_router.py +0 -0
  71. {openhands_agent_server-1.49.6 → openhands_agent_server-1.50.0}/openhands/agent_server/skills_router.py +0 -0
  72. {openhands_agent_server-1.49.6 → openhands_agent_server-1.50.0}/openhands/agent_server/skills_service.py +0 -0
  73. {openhands_agent_server-1.49.6 → openhands_agent_server-1.50.0}/openhands/agent_server/sockets.py +0 -0
  74. {openhands_agent_server-1.49.6 → openhands_agent_server-1.50.0}/openhands/agent_server/sub_agents_router.py +0 -0
  75. {openhands_agent_server-1.49.6 → openhands_agent_server-1.50.0}/openhands/agent_server/telemetry/__init__.py +0 -0
  76. {openhands_agent_server-1.49.6 → openhands_agent_server-1.50.0}/openhands/agent_server/telemetry/factory.py +0 -0
  77. {openhands_agent_server-1.49.6 → openhands_agent_server-1.50.0}/openhands/agent_server/telemetry/http_exporter.py +0 -0
  78. {openhands_agent_server-1.49.6 → openhands_agent_server-1.50.0}/openhands/agent_server/telemetry/models.py +0 -0
  79. {openhands_agent_server-1.49.6 → openhands_agent_server-1.50.0}/openhands/agent_server/telemetry/policy.py +0 -0
  80. {openhands_agent_server-1.49.6 → openhands_agent_server-1.50.0}/openhands/agent_server/telemetry/posthog_exporter.py +0 -0
  81. {openhands_agent_server-1.49.6 → openhands_agent_server-1.50.0}/openhands/agent_server/telemetry/sanitizer.py +0 -0
  82. {openhands_agent_server-1.49.6 → openhands_agent_server-1.50.0}/openhands/agent_server/telemetry/service.py +0 -0
  83. {openhands_agent_server-1.49.6 → openhands_agent_server-1.50.0}/openhands/agent_server/telemetry/sink.py +0 -0
  84. {openhands_agent_server-1.49.6 → openhands_agent_server-1.50.0}/openhands/agent_server/telemetry/subscriber.py +0 -0
  85. {openhands_agent_server-1.49.6 → openhands_agent_server-1.50.0}/openhands/agent_server/telemetry_types.py +0 -0
  86. {openhands_agent_server-1.49.6 → openhands_agent_server-1.50.0}/openhands/agent_server/tool_preload_service.py +0 -0
  87. {openhands_agent_server-1.49.6 → openhands_agent_server-1.50.0}/openhands/agent_server/tool_router.py +0 -0
  88. {openhands_agent_server-1.49.6 → openhands_agent_server-1.50.0}/openhands/agent_server/utils.py +0 -0
  89. {openhands_agent_server-1.49.6 → openhands_agent_server-1.50.0}/openhands/agent_server/vscode_extensions/openhands-settings/extension.js +0 -0
  90. {openhands_agent_server-1.49.6 → openhands_agent_server-1.50.0}/openhands/agent_server/vscode_extensions/openhands-settings/package.json +0 -0
  91. {openhands_agent_server-1.49.6 → openhands_agent_server-1.50.0}/openhands/agent_server/vscode_router.py +0 -0
  92. {openhands_agent_server-1.49.6 → openhands_agent_server-1.50.0}/openhands/agent_server/vscode_service.py +0 -0
  93. {openhands_agent_server-1.49.6 → openhands_agent_server-1.50.0}/openhands/agent_server/workspace_router.py +0 -0
  94. {openhands_agent_server-1.49.6 → openhands_agent_server-1.50.0}/openhands/agent_server/workspaces_router.py +0 -0
  95. {openhands_agent_server-1.49.6 → openhands_agent_server-1.50.0}/openhands_agent_server.egg-info/dependency_links.txt +0 -0
  96. {openhands_agent_server-1.49.6 → openhands_agent_server-1.50.0}/openhands_agent_server.egg-info/entry_points.txt +0 -0
  97. {openhands_agent_server-1.49.6 → openhands_agent_server-1.50.0}/openhands_agent_server.egg-info/top_level.txt +0 -0
  98. {openhands_agent_server-1.49.6 → openhands_agent_server-1.50.0}/setup.cfg +0 -0
@@ -1,13 +1,13 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: openhands-agent-server
3
- Version: 1.49.6
3
+ Version: 1.50.0
4
4
  Summary: OpenHands Agent Server - REST/WebSocket interface for OpenHands AI Agent
5
5
  Project-URL: Source, https://github.com/OpenHands/software-agent-sdk
6
6
  Project-URL: Homepage, https://github.com/OpenHands/software-agent-sdk
7
7
  Project-URL: Documentation, https://docs.openhands.dev/sdk
8
8
  Project-URL: Bug Tracker, https://github.com/OpenHands/software-agent-sdk/issues
9
9
  Requires-Python: >=3.12
10
- Requires-Dist: aiosqlite>=0.19
10
+ Requires-Dist: aiosqlite>=0.22.1
11
11
  Requires-Dist: alembic>=1.13
12
12
  Requires-Dist: docker<8,>=7.1
13
13
  Requires-Dist: fastapi>=0.104
@@ -21,6 +21,9 @@ from openhands.agent_server.agent_profiles_router import agent_profiles_router
21
21
  from openhands.agent_server.auth_router import auth_router
22
22
  from openhands.agent_server.bash_router import bash_router
23
23
  from openhands.agent_server.bash_service import get_default_bash_event_service
24
+ from openhands.agent_server.canvas_extensions.backend import (
25
+ CanvasExtensionBackendManager,
26
+ )
24
27
  from openhands.agent_server.canvas_extensions_router import canvas_extensions_router
25
28
  from openhands.agent_server.config import (
26
29
  Config,
@@ -302,6 +305,9 @@ async def api_lifespan(api: FastAPI) -> AsyncIterator[None]:
302
305
  # after `async with service` so terminal events are still accepted.
303
306
  if secret_resolution is not None:
304
307
  secret_resolution.__exit__(None, None, None)
308
+ backend_manager = getattr(api.state, "canvas_extension_backend_manager", None)
309
+ if backend_manager is not None:
310
+ await backend_manager.shutdown()
305
311
  emit_server_stopped()
306
312
  await shutdown_telemetry_sink()
307
313
 
@@ -704,6 +710,7 @@ def create_app(config: Config | None = None) -> FastAPI:
704
710
  app = _create_fastapi_instance(config)
705
711
  app.state.config = config
706
712
  app.state.conversation_registry = create_conversation_registry(config)
713
+ app.state.canvas_extension_backend_manager = CanvasExtensionBackendManager()
707
714
 
708
715
  _add_api_routes(app)
709
716
  _setup_static_files(app, config)
@@ -0,0 +1,649 @@
1
+ """Owned lifecycle for optional Canvas App backend subprocesses."""
2
+
3
+ import asyncio
4
+ import hashlib
5
+ import os
6
+ import platform
7
+ import shutil
8
+ import signal
9
+ import socket
10
+ import tarfile
11
+ import tempfile
12
+ import time
13
+ import urllib.error
14
+ import urllib.request
15
+ from collections import deque
16
+ from pathlib import Path
17
+ from typing import Final, Literal
18
+
19
+ from pydantic import BaseModel, Field
20
+
21
+ from openhands.agent_server.canvas_extensions.installed import (
22
+ get_installed_canvas_extension,
23
+ get_installed_canvas_extension_manifest,
24
+ get_installed_canvas_extensions_dir,
25
+ )
26
+ from openhands.agent_server.canvas_extensions.manifest import (
27
+ BackendPlatform,
28
+ CanvasExtensionBackend,
29
+ CanvasExtensionBackendArtifact,
30
+ CanvasExtensionManifest,
31
+ )
32
+ from openhands.sdk.utils.path import get_user_persistence_dir
33
+
34
+
35
+ BackendState = Literal[
36
+ "missing", "stopped", "starting", "ready", "unhealthy", "unsupported"
37
+ ]
38
+ _SAFE_INHERITED_ENV: Final[frozenset[str]] = frozenset(
39
+ {"LANG", "LC_ALL", "LC_CTYPE", "PATH", "TMPDIR", "TZ"}
40
+ )
41
+ _MAX_LOG_BYTES: Final[int] = 256 * 1024
42
+ _STOP_TIMEOUT_SECONDS: Final[float] = 5
43
+
44
+
45
+ class BackendRevisionRequest(BaseModel):
46
+ """Explicit approval for one exact installed revision."""
47
+
48
+ revision: str = Field(min_length=1)
49
+
50
+
51
+ class BackendStatus(BaseModel):
52
+ """Current state of an installed Canvas App backend."""
53
+
54
+ name: str
55
+ state: BackendState
56
+ revision: str | None = None
57
+ prepared_revision: str | None = None
58
+ pid: int | None = None
59
+ port: int | None = None
60
+ detail: str | None = None
61
+
62
+
63
+ class BackendLogs(BaseModel):
64
+ """Bounded combined stdout and stderr output."""
65
+
66
+ name: str
67
+ logs: str
68
+ truncated: bool
69
+
70
+
71
+ class _PreparedState(BaseModel):
72
+ revision: str
73
+ platform: BackendPlatform
74
+ artifact_sha256: str
75
+ artifact_dir: str
76
+
77
+
78
+ class _Runtime:
79
+ def __init__(self) -> None:
80
+ self.process: asyncio.subprocess.Process | None = None
81
+ self.port: int | None = None
82
+ self.revision: str | None = None
83
+ self.state: BackendState = "stopped"
84
+ self.detail: str | None = None
85
+ self.logs: deque[bytes] = deque()
86
+ self.log_bytes = 0
87
+ self.logs_truncated = False
88
+ self.drain_tasks: list[asyncio.Task[None]] = []
89
+ # The health wait runs in its own task so the name lock stays free for
90
+ # status()/stop()/logs() while a backend is coming up.
91
+ self.start_task: asyncio.Task[None] | None = None
92
+ self.stop_requested = asyncio.Event()
93
+
94
+
95
+ class CanvasExtensionBackendManager:
96
+ """Owns one optional backend process per installed Canvas App."""
97
+
98
+ def __init__(
99
+ self,
100
+ installed_dir: Path | None = None,
101
+ state_dir: Path | None = None,
102
+ ) -> None:
103
+ self.installed_dir = installed_dir or get_installed_canvas_extensions_dir()
104
+ root = (
105
+ state_dir or get_user_persistence_dir() / "canvas-extensions" / "backends"
106
+ )
107
+ self.state_dir = root
108
+ self.artifacts_dir = root / "artifacts"
109
+ self.data_dir = root / "data"
110
+ self.approvals_dir = root / "approvals"
111
+ self._runtimes: dict[str, _Runtime] = {}
112
+ self._locks: dict[str, asyncio.Lock] = {}
113
+
114
+ def _lock(self, name: str) -> asyncio.Lock:
115
+ return self._locks.setdefault(name, asyncio.Lock())
116
+
117
+ def _runtime(self, name: str) -> _Runtime:
118
+ return self._runtimes.setdefault(name, _Runtime())
119
+
120
+ def _manifest(self, name: str) -> CanvasExtensionManifest | None:
121
+ return get_installed_canvas_extension_manifest(name, self.installed_dir)
122
+
123
+ def revision(self, name: str) -> str | None:
124
+ info = get_installed_canvas_extension(name, self.installed_dir)
125
+ manifest = self._manifest(name)
126
+ if info is None or manifest is None:
127
+ return None
128
+ if info.resolved_ref:
129
+ return info.resolved_ref
130
+ payload = manifest.model_dump_json(exclude_none=True).encode()
131
+ return f"sha256:{hashlib.sha256(payload).hexdigest()}"
132
+
133
+ @staticmethod
134
+ def current_platform() -> BackendPlatform | None:
135
+ if platform.system() != "Linux":
136
+ return None
137
+ machine = platform.machine().lower()
138
+ if machine in {"x86_64", "amd64"}:
139
+ return "linux-amd64"
140
+ if machine in {"aarch64", "arm64"}:
141
+ return "linux-arm64"
142
+ return None
143
+
144
+ def _backend_parts(
145
+ self, name: str
146
+ ) -> (
147
+ tuple[
148
+ CanvasExtensionBackend,
149
+ CanvasExtensionBackendArtifact,
150
+ BackendPlatform,
151
+ ]
152
+ | None
153
+ ):
154
+ manifest = self._manifest(name)
155
+ current_platform = self.current_platform()
156
+ if manifest is None or manifest.backend is None or current_platform is None:
157
+ return None
158
+ artifact = manifest.backend.artifacts.get(current_platform)
159
+ if artifact is None:
160
+ return None
161
+ return manifest.backend, artifact, current_platform
162
+
163
+ def _approval_path(self, name: str) -> Path:
164
+ return self.approvals_dir / f"{name}.json"
165
+
166
+ def _read_prepared(self, name: str) -> _PreparedState | None:
167
+ try:
168
+ return _PreparedState.model_validate_json(
169
+ self._approval_path(name).read_text()
170
+ )
171
+ except (OSError, ValueError):
172
+ return None
173
+
174
+ def _write_prepared(self, name: str, state: _PreparedState) -> None:
175
+ self.approvals_dir.mkdir(parents=True, exist_ok=True)
176
+ destination = self._approval_path(name)
177
+ temporary = destination.with_suffix(".tmp")
178
+ temporary.write_text(state.model_dump_json())
179
+ os.replace(temporary, destination)
180
+
181
+ def invalidate_approval(self, name: str) -> None:
182
+ self._approval_path(name).unlink(missing_ok=True)
183
+
184
+ @staticmethod
185
+ def _resolve_contained(root: Path, relative: str) -> Path:
186
+ resolved_root = root.resolve()
187
+ candidate = (resolved_root / relative).resolve()
188
+ if not candidate.is_relative_to(resolved_root) or not candidate.is_file():
189
+ raise ValueError("backend artifact is not a contained regular file")
190
+ return candidate
191
+
192
+ @staticmethod
193
+ def _sha256(path: Path) -> str:
194
+ digest = hashlib.sha256()
195
+ with path.open("rb") as stream:
196
+ for chunk in iter(lambda: stream.read(1024 * 1024), b""):
197
+ digest.update(chunk)
198
+ return digest.hexdigest()
199
+
200
+ @staticmethod
201
+ def _extract_archive(archive: Path, destination: Path) -> None:
202
+ root = destination.resolve()
203
+ with tarfile.open(archive, mode="r:gz") as tar:
204
+ members = tar.getmembers()
205
+ for member in members:
206
+ target = (root / member.name).resolve()
207
+ if (
208
+ member.name.startswith("/")
209
+ or not target.is_relative_to(root)
210
+ or not (member.isfile() or member.isdir())
211
+ ):
212
+ raise ValueError(
213
+ "backend artifact contains an unsafe archive entry"
214
+ )
215
+ tar.extractall(destination, members=members, filter="data")
216
+ for path in destination.rglob("*"):
217
+ mode = path.stat().st_mode
218
+ path.chmod(mode & (0o555 if path.is_file() else 0o755))
219
+ destination.chmod(0o555)
220
+
221
+ async def prepare(self, name: str, revision: str) -> BackendStatus:
222
+ async with self._lock(name):
223
+ status = self._status_unlocked(name)
224
+ if status.state in {"missing", "unsupported"}:
225
+ return status
226
+ current_revision = self.revision(name)
227
+ if revision != current_revision:
228
+ raise ValueError("approval revision does not match installed revision")
229
+ prepared = self._read_prepared(name)
230
+ if (
231
+ prepared is not None
232
+ and prepared.revision == revision
233
+ and Path(prepared.artifact_dir).is_dir()
234
+ ):
235
+ return self._status_unlocked(name)
236
+
237
+ parts = self._backend_parts(name)
238
+ assert parts is not None
239
+ _, artifact, current_platform = parts
240
+ package_root = self.installed_dir / name
241
+ archive = self._resolve_contained(package_root, artifact.path)
242
+ actual_sha256 = await asyncio.to_thread(self._sha256, archive)
243
+ if actual_sha256 != artifact.sha256:
244
+ raise ValueError("backend artifact checksum does not match manifest")
245
+
246
+ artifact_dir = self.artifacts_dir / name / actual_sha256
247
+ if not artifact_dir.exists():
248
+ artifact_dir.parent.mkdir(parents=True, exist_ok=True)
249
+ temporary = Path(
250
+ tempfile.mkdtemp(
251
+ prefix=f".{actual_sha256}.", dir=artifact_dir.parent
252
+ )
253
+ )
254
+ try:
255
+ await asyncio.to_thread(self._extract_archive, archive, temporary)
256
+ try:
257
+ os.replace(temporary, artifact_dir)
258
+ except OSError:
259
+ if not artifact_dir.is_dir():
260
+ raise
261
+ finally:
262
+ shutil.rmtree(temporary, ignore_errors=True)
263
+ self._write_prepared(
264
+ name,
265
+ _PreparedState(
266
+ revision=revision,
267
+ platform=current_platform,
268
+ artifact_sha256=actual_sha256,
269
+ artifact_dir=str(artifact_dir),
270
+ ),
271
+ )
272
+ return self._status_unlocked(name)
273
+
274
+ def _status_unlocked(self, name: str) -> BackendStatus:
275
+ revision = self.revision(name)
276
+ manifest = self._manifest(name)
277
+ runtime = self._runtimes.get(name)
278
+ prepared = self._read_prepared(name)
279
+ prepared_revision = prepared.revision if prepared else None
280
+ if manifest is None:
281
+ state: BackendState = "missing"
282
+ detail = "Canvas App is not installed or its manifest is invalid"
283
+ elif manifest.backend is None:
284
+ state = "unsupported"
285
+ detail = "Canvas App does not declare a backend"
286
+ elif self._backend_parts(name) is None:
287
+ state = "unsupported"
288
+ detail = "Canvas App backend does not support this platform"
289
+ elif runtime is not None and runtime.state in {
290
+ "starting",
291
+ "ready",
292
+ "unhealthy",
293
+ }:
294
+ state = runtime.state
295
+ detail = runtime.detail
296
+ else:
297
+ state = "stopped"
298
+ detail = None
299
+ return BackendStatus(
300
+ name=name,
301
+ state=state,
302
+ revision=revision,
303
+ prepared_revision=prepared_revision,
304
+ pid=runtime.process.pid if runtime and runtime.process else None,
305
+ port=runtime.port if runtime else None,
306
+ detail=detail,
307
+ )
308
+
309
+ async def status(self, name: str) -> BackendStatus:
310
+ async with self._lock(name):
311
+ runtime = self._runtimes.get(name)
312
+ if runtime and runtime.process and runtime.process.returncode is not None:
313
+ returncode = runtime.process.returncode
314
+ await self._finish_runtime(runtime)
315
+ runtime.process = None
316
+ runtime.port = None
317
+ runtime.state = "unhealthy"
318
+ runtime.detail = f"Backend exited with code {returncode}"
319
+ elif runtime and runtime.state == "ready" and runtime.port is not None:
320
+ manifest = self._manifest(name)
321
+ if manifest is None or manifest.backend is None:
322
+ # The on-disk manifest no longer validates (or stopped
323
+ # declaring a backend); report that instead of tracing back
324
+ # an AssertionError once `_probe` dereferences it.
325
+ return self._status_unlocked(name)
326
+ probe_url = (
327
+ f"http://127.0.0.1:{runtime.port}{manifest.backend.health.path}"
328
+ )
329
+ if not await asyncio.to_thread(self._probe, probe_url):
330
+ runtime.state = "unhealthy"
331
+ runtime.detail = "Backend health probe failed"
332
+ return self._status_unlocked(name)
333
+
334
+ @staticmethod
335
+ def _allocate_port() -> int:
336
+ with socket.socket() as sock:
337
+ sock.bind(("127.0.0.1", 0))
338
+ return int(sock.getsockname()[1])
339
+
340
+ def _environment(self, backend: CanvasExtensionBackend) -> dict[str, str]:
341
+ disallowed = set(backend.inherit_environment) - _SAFE_INHERITED_ENV
342
+ if disallowed:
343
+ names = ", ".join(sorted(disallowed))
344
+ raise ValueError(
345
+ f"backend requests disallowed environment variables: {names}"
346
+ )
347
+ return {
348
+ name: os.environ[name]
349
+ for name in backend.inherit_environment
350
+ if name in os.environ
351
+ }
352
+
353
+ @staticmethod
354
+ def _expand_argv(
355
+ backend: CanvasExtensionBackend,
356
+ port: int,
357
+ data_dir: Path,
358
+ artifact_dir: Path,
359
+ ) -> list[str]:
360
+ replacements = {
361
+ "{port}": str(port),
362
+ "{data_dir}": str(data_dir),
363
+ "{artifact_dir}": str(artifact_dir),
364
+ }
365
+ argv: list[str] = []
366
+ for argument in backend.argv:
367
+ for placeholder, value in replacements.items():
368
+ argument = argument.replace(placeholder, value)
369
+ argv.append(argument)
370
+
371
+ artifact_root = artifact_dir.resolve()
372
+ executable = Path(argv[0]).resolve()
373
+ if (
374
+ not executable.is_relative_to(artifact_root)
375
+ or not executable.is_file()
376
+ or not os.access(executable, os.X_OK)
377
+ ):
378
+ raise ValueError(
379
+ "backend executable must be an executable regular file inside "
380
+ "the prepared artifact"
381
+ )
382
+ argv[0] = str(executable)
383
+ return argv
384
+
385
+ async def _drain(
386
+ self, runtime: _Runtime, stream: asyncio.StreamReader | None, label: bytes
387
+ ) -> None:
388
+ if stream is None:
389
+ return
390
+ while chunk := await stream.read(8192):
391
+ entry = label + chunk
392
+ runtime.logs.append(entry)
393
+ runtime.log_bytes += len(entry)
394
+ while runtime.log_bytes > _MAX_LOG_BYTES and runtime.logs:
395
+ runtime.log_bytes -= len(runtime.logs.popleft())
396
+ runtime.logs_truncated = True
397
+
398
+ @staticmethod
399
+ def _probe(url: str) -> bool:
400
+ try:
401
+ with urllib.request.urlopen(url, timeout=1) as response:
402
+ return 200 <= response.status < 400
403
+ except (OSError, urllib.error.URLError):
404
+ return False
405
+
406
+ async def _await_healthy(
407
+ self,
408
+ runtime: _Runtime,
409
+ backend: CanvasExtensionBackend,
410
+ port: int,
411
+ ) -> None:
412
+ """Poll the backend's health endpoint until it is ready.
413
+
414
+ Runs as ``runtime.start_task`` rather than inline so the name lock is
415
+ free: ``status()`` can report ``starting`` and ``stop()`` can abandon a
416
+ backend that never comes up.
417
+ """
418
+ try:
419
+ deadline = time.monotonic() + backend.health.timeout_seconds
420
+ probe_url = f"http://127.0.0.1:{port}{backend.health.path}"
421
+ while time.monotonic() < deadline:
422
+ if runtime.stop_requested.is_set():
423
+ return
424
+ process = runtime.process
425
+ if process is None or process.returncode is not None:
426
+ code = process.returncode if process is not None else None
427
+ raise RuntimeError(f"backend exited with code {code}")
428
+ if await asyncio.to_thread(self._probe, probe_url):
429
+ runtime.state = "ready"
430
+ runtime.detail = None
431
+ return
432
+ await asyncio.sleep(backend.health.interval_seconds)
433
+ raise TimeoutError("backend health check timed out")
434
+ except asyncio.CancelledError:
435
+ runtime.state = "stopped"
436
+ runtime.detail = None
437
+ raise
438
+ except Exception as exc:
439
+ if runtime.stop_requested.is_set():
440
+ # `stop()` owns the final state; don't clobber it with an
441
+ # error raised purely because we tore the process down.
442
+ runtime.state = "stopped"
443
+ runtime.detail = None
444
+ else:
445
+ runtime.state = "unhealthy"
446
+ runtime.detail = str(exc)
447
+
448
+ async def start(self, name: str, revision: str) -> BackendStatus:
449
+ async with self._lock(name):
450
+ current = self._status_unlocked(name)
451
+ if current.state in {"missing", "unsupported"}:
452
+ return current
453
+ runtime = self._runtime(name)
454
+ task = runtime.start_task
455
+ if runtime.process and runtime.process.returncode is None:
456
+ if runtime.revision != revision:
457
+ raise RuntimeError(
458
+ "a different backend revision is already running"
459
+ )
460
+ if task is None:
461
+ return current
462
+ else:
463
+ if revision != self.revision(name):
464
+ raise ValueError(
465
+ "approval revision does not match installed revision"
466
+ )
467
+ prepared = self._read_prepared(name)
468
+ if prepared is None or prepared.revision != revision:
469
+ raise RuntimeError("backend revision must be prepared before start")
470
+ artifact_dir = Path(prepared.artifact_dir)
471
+ if not artifact_dir.is_dir():
472
+ raise RuntimeError("prepared backend artifact is missing")
473
+
474
+ parts = self._backend_parts(name)
475
+ assert parts is not None
476
+ backend, artifact, current_platform = parts
477
+ expected_artifact_dir = (
478
+ self.artifacts_dir / name / prepared.artifact_sha256
479
+ ).resolve()
480
+ if (
481
+ prepared.platform != current_platform
482
+ or prepared.artifact_sha256 != artifact.sha256
483
+ or artifact_dir.resolve() != expected_artifact_dir
484
+ ):
485
+ raise RuntimeError(
486
+ "prepared backend metadata does not match manifest"
487
+ )
488
+ package_root = (self.installed_dir / name).resolve()
489
+ data_dir = self.data_dir / name
490
+ data_dir.mkdir(parents=True, exist_ok=True)
491
+ port = self._allocate_port()
492
+ runtime.state = "starting"
493
+ runtime.detail = None
494
+ runtime.port = port
495
+ runtime.revision = revision
496
+ runtime.logs.clear()
497
+ runtime.log_bytes = 0
498
+ runtime.logs_truncated = False
499
+ runtime.stop_requested = asyncio.Event()
500
+ try:
501
+ runtime.process = await asyncio.create_subprocess_exec(
502
+ *self._expand_argv(backend, port, data_dir, artifact_dir),
503
+ cwd=package_root,
504
+ env=self._environment(backend),
505
+ stdout=asyncio.subprocess.PIPE,
506
+ stderr=asyncio.subprocess.PIPE,
507
+ start_new_session=True,
508
+ )
509
+ except Exception as exc:
510
+ runtime.state = "unhealthy"
511
+ runtime.detail = str(exc)
512
+ await self._terminate_runtime(runtime)
513
+ return self._status_unlocked(name)
514
+ runtime.drain_tasks = [
515
+ asyncio.create_task(
516
+ self._drain(runtime, runtime.process.stdout, b"[stdout] ")
517
+ ),
518
+ asyncio.create_task(
519
+ self._drain(runtime, runtime.process.stderr, b"[stderr] ")
520
+ ),
521
+ ]
522
+ task = asyncio.create_task(self._await_healthy(runtime, backend, port))
523
+ runtime.start_task = task
524
+ if task is not None:
525
+ await asyncio.gather(task, return_exceptions=True)
526
+ async with self._lock(name):
527
+ # Clear the handle and reclaim a failed start's process group here,
528
+ # where the runtime is known to still be ours.
529
+ if runtime.start_task is task:
530
+ runtime.start_task = None
531
+ if runtime.state == "unhealthy":
532
+ await self._terminate_runtime(runtime)
533
+ return self._status_unlocked(name)
534
+
535
+ async def _finish_runtime(self, runtime: _Runtime) -> None:
536
+ if runtime.process is not None:
537
+ await runtime.process.wait()
538
+ if runtime.drain_tasks:
539
+ await asyncio.gather(*runtime.drain_tasks, return_exceptions=True)
540
+ runtime.drain_tasks = []
541
+
542
+ @staticmethod
543
+ def _signal_group(pgid: int, sig: int) -> None:
544
+ try:
545
+ os.killpg(pgid, sig)
546
+ except ProcessLookupError:
547
+ pass
548
+
549
+ @staticmethod
550
+ def _group_alive(pgid: int) -> bool:
551
+ try:
552
+ os.killpg(pgid, 0)
553
+ return True
554
+ except ProcessLookupError:
555
+ return False
556
+
557
+ async def _wait_for_group_exit(self, pgid: int, timeout: float) -> bool:
558
+ deadline = time.monotonic() + timeout
559
+ while True:
560
+ if not self._group_alive(pgid):
561
+ return True
562
+ if time.monotonic() >= deadline:
563
+ return False
564
+ await asyncio.sleep(0.05)
565
+
566
+ async def _terminate_runtime(self, runtime: _Runtime) -> None:
567
+ process = runtime.process
568
+ if process is None:
569
+ return
570
+ pgid = process.pid
571
+ # Signal the whole group and wait for the *group* to drain, not just the
572
+ # leader: a backend may fork descendants, and one that outlives (or is
573
+ # forked just after) the leader keeps the group alive. Escalating only
574
+ # on the leader's exit code would leak those descendants.
575
+ if process.returncode is None or self._group_alive(pgid):
576
+ self._signal_group(pgid, signal.SIGTERM)
577
+ if not await self._wait_for_group_exit(pgid, _STOP_TIMEOUT_SECONDS):
578
+ self._signal_group(pgid, signal.SIGKILL)
579
+ await self._wait_for_group_exit(pgid, _STOP_TIMEOUT_SECONDS)
580
+ if process.returncode is None:
581
+ await process.wait()
582
+ await self._finish_runtime(runtime)
583
+ runtime.process = None
584
+ runtime.port = None
585
+
586
+ def has_running_backends(self) -> bool:
587
+ return any(
588
+ runtime.start_task is not None
589
+ or (runtime.process is not None and runtime.process.returncode is None)
590
+ for runtime in self._runtimes.values()
591
+ )
592
+
593
+ async def stop(self, name: str) -> BackendStatus:
594
+ task: asyncio.Task[None] | None = None
595
+ async with self._lock(name):
596
+ runtime = self._runtimes.get(name)
597
+ if runtime is not None:
598
+ # Ask an in-flight health wait to give up before cancelling it,
599
+ # so a backend stuck in `starting` is stoppable instead of
600
+ # holding the lock (and the REST handler) for the full timeout.
601
+ runtime.stop_requested.set()
602
+ task = runtime.start_task
603
+ runtime.start_task = None
604
+ if task is not None:
605
+ task.cancel()
606
+ await self._terminate_runtime(runtime)
607
+ runtime.state = "stopped"
608
+ runtime.detail = None
609
+ status = self._status_unlocked(name)
610
+ if task is not None:
611
+ await asyncio.gather(task, return_exceptions=True)
612
+ return status
613
+
614
+ async def logs(self, name: str, limit_bytes: int) -> BackendLogs:
615
+ async with self._lock(name):
616
+ runtime = self._runtimes.get(name)
617
+ if runtime is None:
618
+ return BackendLogs(name=name, logs="", truncated=False)
619
+ content = b"".join(runtime.logs)
620
+ truncated = runtime.logs_truncated or len(content) > limit_bytes
621
+ return BackendLogs(
622
+ name=name,
623
+ logs=content[-limit_bytes:].decode(errors="replace"),
624
+ truncated=truncated,
625
+ )
626
+
627
+ async def delete_data(self, name: str) -> BackendStatus:
628
+ async with self._lock(name):
629
+ runtime = self._runtimes.get(name)
630
+ if runtime and (
631
+ runtime.start_task is not None
632
+ or (runtime.process and runtime.process.returncode is None)
633
+ ):
634
+ raise RuntimeError("stop the backend before deleting its data")
635
+ shutil.rmtree(self.data_dir / name, ignore_errors=True)
636
+ return self._status_unlocked(name)
637
+
638
+ def ready_endpoint(self, name: str) -> tuple[str, int] | None:
639
+ """Internal registry boundary for the future authenticated router."""
640
+ runtime = self._runtimes.get(name)
641
+ if runtime is None or runtime.state != "ready" or runtime.port is None:
642
+ return None
643
+ return "127.0.0.1", runtime.port
644
+
645
+ async def shutdown(self) -> None:
646
+ await asyncio.gather(
647
+ *(self.stop(name) for name in list(self._runtimes)),
648
+ return_exceptions=True,
649
+ )