askrobots / dbbasic-object-server
Public
Runs live, versioned Python application objects on one VM, with a suite of apps: projects, notes, tasks, files and more.
danq9
signup: the person chooses the password and name on the confirm page
83c7aa6
2 weeks, 5 days ago
History
object_execution.py · 12.1 KB · 413 lines
| 1 | """Object execution contract. |
| 2 | |
| 3 | This module defines the small result shape shared by the daemon, future ASGI |
| 4 | server, DBBASIC Scroll, and AI-assisted repair loop. It does not implement the |
| 5 | object runtime itself; it wraps an existing runtime object and turns execution |
| 6 | success or failure into structured data. |
| 7 | """ |
| 8 | from __future__ import annotations |
| 9 | |
| 10 | import time |
| 11 | import traceback |
| 12 | from dataclasses import dataclass |
| 13 | from datetime import datetime, timezone |
| 14 | from multiprocessing import get_context |
| 15 | from multiprocessing.connection import Connection |
| 16 | from pathlib import Path |
| 17 | from typing import Any, Iterable, Mapping, Protocol |
| 18 | |
| 19 | import object_correlation |
| 20 | from object_namespace import resolve_object_id |
| 21 | |
| 22 | |
| 23 | @dataclass(frozen=True) |
| 24 | class ObjectExecutionRequest: |
| 25 | """A request to execute one object method with a payload.""" |
| 26 | |
| 27 | object_id: str |
| 28 | method: str = "GET" |
| 29 | payload: Mapping[str, Any] | None = None |
| 30 | path: Path | None = None |
| 31 | correlation_id: str | None = None |
| 32 | |
| 33 | def normalized_method(self) -> str: |
| 34 | """Return the method name used by object runtimes.""" |
| 35 | method = self.method.strip() if isinstance(self.method, str) else "" |
| 36 | return method.upper() or "GET" |
| 37 | |
| 38 | def normalized_payload(self) -> dict[str, Any]: |
| 39 | """Return a mutable dict payload for object execution.""" |
| 40 | if self.payload is None: |
| 41 | return {} |
| 42 | return dict(self.payload) |
| 43 | |
| 44 | |
| 45 | @dataclass(frozen=True) |
| 46 | class ObjectExecutionError: |
| 47 | """Structured execution failure details.""" |
| 48 | |
| 49 | type: str |
| 50 | message: str |
| 51 | traceback: str = "" |
| 52 | |
| 53 | def to_dict(self) -> dict[str, str]: |
| 54 | return { |
| 55 | "type": self.type, |
| 56 | "message": self.message, |
| 57 | "traceback": self.traceback, |
| 58 | } |
| 59 | |
| 60 | |
| 61 | @dataclass(frozen=True) |
| 62 | class ObjectExecutionResult: |
| 63 | """Structured result for one object execution attempt.""" |
| 64 | |
| 65 | object_id: str |
| 66 | method: str |
| 67 | path: Path | None |
| 68 | ok: bool |
| 69 | result: Any |
| 70 | error: ObjectExecutionError | None |
| 71 | started_at: str |
| 72 | finished_at: str |
| 73 | duration_ms: float |
| 74 | correlation_id: str | None = None |
| 75 | |
| 76 | def to_dict(self) -> dict[str, Any]: |
| 77 | return { |
| 78 | "object_id": self.object_id, |
| 79 | "method": self.method, |
| 80 | "path": str(self.path) if self.path is not None else None, |
| 81 | "ok": self.ok, |
| 82 | "result": self.result, |
| 83 | "error": self.error.to_dict() if self.error else None, |
| 84 | "started_at": self.started_at, |
| 85 | "finished_at": self.finished_at, |
| 86 | "duration_ms": self.duration_ms, |
| 87 | "correlation_id": self.correlation_id, |
| 88 | } |
| 89 | |
| 90 | |
| 91 | class ObjectRuntimeProtocol(Protocol): |
| 92 | """Runtime boundary required by this execution contract.""" |
| 93 | |
| 94 | def load_object(self, path: Path, object_id: str | None = None) -> "ExecutableObjectProtocol": |
| 95 | ... |
| 96 | |
| 97 | |
| 98 | class ExecutableObjectProtocol(Protocol): |
| 99 | """Object boundary required by this execution contract.""" |
| 100 | |
| 101 | def execute(self, method: str, payload: dict[str, Any]) -> Any: |
| 102 | ... |
| 103 | |
| 104 | |
| 105 | class ObjectExecutionFailure(RuntimeError): |
| 106 | """Exception wrapper for callers that still need raise-on-failure behavior.""" |
| 107 | |
| 108 | def __init__(self, execution_result: ObjectExecutionResult): |
| 109 | self.execution_result = execution_result |
| 110 | message = "Object execution failed" |
| 111 | if execution_result.error is not None: |
| 112 | message = execution_result.error.message |
| 113 | super().__init__(message) |
| 114 | |
| 115 | |
| 116 | TIMEOUT_ERROR_TYPE = "ObjectExecutionTimeoutError" |
| 117 | WORKER_ERROR_TYPE = "ObjectWorkerError" |
| 118 | |
| 119 | |
| 120 | def execute_object( |
| 121 | runtime: ObjectRuntimeProtocol, |
| 122 | request: ObjectExecutionRequest, |
| 123 | roots: Iterable[Path] | None = None, |
| 124 | *, |
| 125 | raise_on_error: bool = False, |
| 126 | ) -> ObjectExecutionResult: |
| 127 | """Execute an object and capture success or failure as structured data.""" |
| 128 | correlation_id = object_correlation.ensure_correlation_id( |
| 129 | request.correlation_id or object_correlation.current_correlation_id() |
| 130 | ) |
| 131 | request = _request_with_correlation_id(request, correlation_id) |
| 132 | token = object_correlation.set_current_correlation_id(correlation_id) |
| 133 | |
| 134 | try: |
| 135 | return _execute_object_with_context(runtime, request, roots, raise_on_error=raise_on_error) |
| 136 | finally: |
| 137 | object_correlation.reset_current_correlation_id(token) |
| 138 | |
| 139 | |
| 140 | def _execute_object_with_context( |
| 141 | runtime: ObjectRuntimeProtocol, |
| 142 | request: ObjectExecutionRequest, |
| 143 | roots: Iterable[Path] | None = None, |
| 144 | *, |
| 145 | raise_on_error: bool = False, |
| 146 | ) -> ObjectExecutionResult: |
| 147 | """Execute an object with a correlation context already installed.""" |
| 148 | started_perf = time.perf_counter() |
| 149 | started_at = _utc_timestamp() |
| 150 | method = request.normalized_method() |
| 151 | payload = request.normalized_payload() |
| 152 | |
| 153 | path = request.path |
| 154 | if path is None: |
| 155 | path = resolve_object_id(request.object_id, roots) |
| 156 | |
| 157 | if path is None or not path.exists(): |
| 158 | result = _finish_error( |
| 159 | request=request, |
| 160 | method=method, |
| 161 | path=path, |
| 162 | error=ObjectExecutionError( |
| 163 | type="ObjectNotFoundError", |
| 164 | message=f"Object not found: {request.object_id}", |
| 165 | ), |
| 166 | started_at=started_at, |
| 167 | started_perf=started_perf, |
| 168 | ) |
| 169 | if raise_on_error: |
| 170 | raise ObjectExecutionFailure(result) |
| 171 | return result |
| 172 | |
| 173 | try: |
| 174 | obj = runtime.load_object(path, request.object_id) |
| 175 | output = obj.execute(method, payload) |
| 176 | except Exception as exc: |
| 177 | result = _finish_error( |
| 178 | request=request, |
| 179 | method=method, |
| 180 | path=path, |
| 181 | error=_error_from_exception(exc), |
| 182 | started_at=started_at, |
| 183 | started_perf=started_perf, |
| 184 | ) |
| 185 | if raise_on_error: |
| 186 | raise ObjectExecutionFailure(result) from exc |
| 187 | return result |
| 188 | |
| 189 | return _finish_success( |
| 190 | request=request, |
| 191 | method=method, |
| 192 | path=path, |
| 193 | output=output, |
| 194 | started_at=started_at, |
| 195 | started_perf=started_perf, |
| 196 | ) |
| 197 | |
| 198 | |
| 199 | def execute_python_object_subprocess( |
| 200 | request: ObjectExecutionRequest, |
| 201 | roots: Iterable[Path] | None = None, |
| 202 | *, |
| 203 | timeout_seconds: float, |
| 204 | raise_on_error: bool = False, |
| 205 | ) -> ObjectExecutionResult: |
| 206 | """Execute a Python object in a subprocess with a wall-clock timeout.""" |
| 207 | correlation_id = object_correlation.ensure_correlation_id( |
| 208 | request.correlation_id or object_correlation.current_correlation_id() |
| 209 | ) |
| 210 | request = _request_with_correlation_id(request, correlation_id) |
| 211 | |
| 212 | if timeout_seconds <= 0: |
| 213 | from python_object_runtime import PythonObjectRuntime |
| 214 | |
| 215 | return execute_object( |
| 216 | PythonObjectRuntime(), |
| 217 | request, |
| 218 | roots, |
| 219 | raise_on_error=raise_on_error, |
| 220 | ) |
| 221 | |
| 222 | started_perf = time.perf_counter() |
| 223 | started_at = _utc_timestamp() |
| 224 | method = request.normalized_method() |
| 225 | roots_list = list(roots) if roots is not None else None |
| 226 | resolved_request = _request_with_resolved_path(request, roots_list) |
| 227 | |
| 228 | context = get_context("spawn") |
| 229 | parent_conn, child_conn = context.Pipe(duplex=False) |
| 230 | process = context.Process( |
| 231 | target=_execute_python_object_child, |
| 232 | args=(child_conn, resolved_request, roots_list), |
| 233 | daemon=True, |
| 234 | ) |
| 235 | process.start() |
| 236 | child_conn.close() |
| 237 | process.join(timeout_seconds) |
| 238 | |
| 239 | if process.is_alive(): |
| 240 | process.terminate() |
| 241 | process.join(1) |
| 242 | if process.is_alive(): |
| 243 | process.kill() |
| 244 | process.join(1) |
| 245 | parent_conn.close() |
| 246 | result = _finish_error( |
| 247 | request=resolved_request, |
| 248 | method=method, |
| 249 | path=resolved_request.path, |
| 250 | error=ObjectExecutionError( |
| 251 | type=TIMEOUT_ERROR_TYPE, |
| 252 | message=( |
| 253 | f"{method} timed out for object {resolved_request.object_id} " |
| 254 | f"after {_format_seconds(timeout_seconds)} seconds" |
| 255 | ), |
| 256 | ), |
| 257 | started_at=started_at, |
| 258 | started_perf=started_perf, |
| 259 | ) |
| 260 | if raise_on_error: |
| 261 | raise ObjectExecutionFailure(result) |
| 262 | return result |
| 263 | |
| 264 | try: |
| 265 | if parent_conn.poll(): |
| 266 | result = parent_conn.recv() |
| 267 | else: |
| 268 | result = _finish_error( |
| 269 | request=resolved_request, |
| 270 | method=method, |
| 271 | path=resolved_request.path, |
| 272 | error=ObjectExecutionError( |
| 273 | type=WORKER_ERROR_TYPE, |
| 274 | message=( |
| 275 | f"Object worker exited without a result " |
| 276 | f"(exit code {process.exitcode})" |
| 277 | ), |
| 278 | ), |
| 279 | started_at=started_at, |
| 280 | started_perf=started_perf, |
| 281 | ) |
| 282 | finally: |
| 283 | parent_conn.close() |
| 284 | |
| 285 | if raise_on_error and not result.ok: |
| 286 | raise ObjectExecutionFailure(result) |
| 287 | return result |
| 288 | |
| 289 | |
| 290 | def _finish_success( |
| 291 | *, |
| 292 | request: ObjectExecutionRequest, |
| 293 | method: str, |
| 294 | path: Path, |
| 295 | output: Any, |
| 296 | started_at: str, |
| 297 | started_perf: float, |
| 298 | ) -> ObjectExecutionResult: |
| 299 | return ObjectExecutionResult( |
| 300 | object_id=request.object_id, |
| 301 | method=method, |
| 302 | path=path, |
| 303 | ok=True, |
| 304 | result=output, |
| 305 | error=None, |
| 306 | started_at=started_at, |
| 307 | finished_at=_utc_timestamp(), |
| 308 | duration_ms=_duration_ms(started_perf), |
| 309 | correlation_id=request.correlation_id, |
| 310 | ) |
| 311 | |
| 312 | |
| 313 | def _finish_error( |
| 314 | *, |
| 315 | request: ObjectExecutionRequest, |
| 316 | method: str, |
| 317 | path: Path | None, |
| 318 | error: ObjectExecutionError, |
| 319 | started_at: str, |
| 320 | started_perf: float, |
| 321 | ) -> ObjectExecutionResult: |
| 322 | return ObjectExecutionResult( |
| 323 | object_id=request.object_id, |
| 324 | method=method, |
| 325 | path=path, |
| 326 | ok=False, |
| 327 | result=None, |
| 328 | error=error, |
| 329 | started_at=started_at, |
| 330 | finished_at=_utc_timestamp(), |
| 331 | duration_ms=_duration_ms(started_perf), |
| 332 | correlation_id=request.correlation_id, |
| 333 | ) |
| 334 | |
| 335 | |
| 336 | def _request_with_correlation_id( |
| 337 | request: ObjectExecutionRequest, |
| 338 | correlation_id: str, |
| 339 | ) -> ObjectExecutionRequest: |
| 340 | return ObjectExecutionRequest( |
| 341 | object_id=request.object_id, |
| 342 | method=request.method, |
| 343 | payload=request.payload, |
| 344 | path=request.path, |
| 345 | correlation_id=correlation_id, |
| 346 | ) |
| 347 | |
| 348 | |
| 349 | def _request_with_resolved_path( |
| 350 | request: ObjectExecutionRequest, |
| 351 | roots: Iterable[Path] | None, |
| 352 | ) -> ObjectExecutionRequest: |
| 353 | if request.path is not None: |
| 354 | return request |
| 355 | |
| 356 | return ObjectExecutionRequest( |
| 357 | object_id=request.object_id, |
| 358 | method=request.method, |
| 359 | payload=request.payload, |
| 360 | path=resolve_object_id(request.object_id, roots), |
| 361 | correlation_id=request.correlation_id, |
| 362 | ) |
| 363 | |
| 364 | |
| 365 | def _execute_python_object_child( |
| 366 | connection: Connection, |
| 367 | request: ObjectExecutionRequest, |
| 368 | roots: list[Path] | None, |
| 369 | ) -> None: |
| 370 | try: |
| 371 | from python_object_runtime import PythonObjectRuntime |
| 372 | |
| 373 | result = execute_object(PythonObjectRuntime(), request, roots) |
| 374 | connection.send(result) |
| 375 | except BaseException as exc: |
| 376 | error_result = _finish_error( |
| 377 | request=request, |
| 378 | method=request.normalized_method(), |
| 379 | path=request.path, |
| 380 | error=ObjectExecutionError( |
| 381 | type=WORKER_ERROR_TYPE, |
| 382 | message=f"Object worker failed: {type(exc).__name__}: {exc}", |
| 383 | traceback="".join(traceback.format_exception(type(exc), exc, exc.__traceback__)), |
| 384 | ), |
| 385 | started_at=_utc_timestamp(), |
| 386 | started_perf=time.perf_counter(), |
| 387 | ) |
| 388 | try: |
| 389 | connection.send(error_result) |
| 390 | except BaseException: |
| 391 | pass |
| 392 | finally: |
| 393 | connection.close() |
| 394 | |
| 395 | |
| 396 | def _error_from_exception(exc: Exception) -> ObjectExecutionError: |
| 397 | return ObjectExecutionError( |
| 398 | type=exc.__class__.__name__, |
| 399 | message=str(exc), |
| 400 | traceback="".join(traceback.format_exception(type(exc), exc, exc.__traceback__)), |
| 401 | ) |
| 402 | |
| 403 | |
| 404 | def _duration_ms(started_perf: float) -> float: |
| 405 | return round((time.perf_counter() - started_perf) * 1000, 3) |
| 406 | |
| 407 | |
| 408 | def _utc_timestamp() -> str: |
| 409 | return datetime.now(timezone.utc).isoformat(timespec="milliseconds").replace("+00:00", "Z") |
| 410 | |
| 411 | |
| 412 | def _format_seconds(seconds: float) -> str: |
| 413 | return f"{seconds:g}" |