autobots-devtools-shared-lib 0.8.0__tar.gz → 0.10.0__tar.gz

{autobots_devtools_shared_lib-0.8.0 → autobots_devtools_shared_lib-0.10.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: autobots-devtools-shared-lib
-Version: 0.8.0
+Version: 0.10.0
 Summary: Shared library functions to be used for all autobots projects
 License: MIT
 Author: Pralhad

{autobots_devtools_shared_lib-0.8.0 → autobots_devtools_shared_lib-0.10.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "autobots-devtools-shared-lib"
-version = "0.8.0"
+version = "0.10.0"
 description = "Shared library functions to be used for all autobots projects"
 readme = "README.md"
 authors = [

autobots_devtools_shared_lib-0.10.0/src/autobots_devtools_shared_lib/common/servers/noderedmanagerserver/__init__.py

@@ -0,0 +1,23 @@
+"""Node-RED instance manager server package."""
+
+from .app import app  # re-export for convenience
+from .exceptions import (
+    FlowsFileNotFoundError,
+    InstanceNotFoundError,
+    InvalidWorkspacePathError,
+    NoAvailablePortError,
+    NodeRedLaunchError,
+    NodeRedManagerError,
+    UnknownEnvironmentError,
+)
+
+__all__ = [
+    "FlowsFileNotFoundError",
+    "InstanceNotFoundError",
+    "InvalidWorkspacePathError",
+    "NoAvailablePortError",
+    "NodeRedLaunchError",
+    "NodeRedManagerError",
+    "UnknownEnvironmentError",
+    "app",
+]

{autobots_devtools_shared_lib-0.8.0 → autobots_devtools_shared_lib-0.10.0}/src/autobots_devtools_shared_lib/common/servers/noderedmanagerserver/__main__.py

@@ -1,16 +1,25 @@
 """Entry point: reads host/port from node-red-config.yaml and starts the server."""
 
+import asyncio
+import sys
+
 import uvicorn
 
 from autobots_devtools_shared_lib.common.servers.noderedmanagerserver.config import (
     NodeRedManagerServerConfig,
 )
 
+# asyncio.create_subprocess_exec requires ProactorEventLoop on Windows.
+# Python 3.12+ defaults to it, but set explicitly to guard against uvicorn
+# or dependency changes that could reset the event loop policy.
+if sys.platform == "win32":
+    asyncio.set_event_loop_policy(asyncio.WindowsProactorEventLoopPolicy())
+
 if __name__ == "__main__":
     cfg = NodeRedManagerServerConfig()
     uvicorn.run(
         "autobots_devtools_shared_lib.common.servers.noderedmanagerserver.app:app",
         host=cfg.node_red_manager_server_host,
         port=cfg.node_red_manager_server_port,
-        reload=True,
+        reload=False,
     )

{autobots_devtools_shared_lib-0.8.0 → autobots_devtools_shared_lib-0.10.0}/src/autobots_devtools_shared_lib/common/servers/noderedmanagerserver/app.py

@@ -16,18 +16,31 @@ Or: make node-red-server (from autobots-devtools-shared-lib)
 import asyncio
 import contextlib
 import os
+import subprocess
+import sys
 from contextlib import asynccontextmanager
-from datetime import UTC, datetime
+from datetime import UTC, datetime, timedelta
 from pathlib import Path
 from typing import Any
 
-from fastapi import FastAPI, HTTPException, status
+from fastapi import FastAPI
+from fastapi.requests import Request
+from fastapi.responses import JSONResponse
 
 from autobots_devtools_shared_lib.common.observability.logging_utils import get_logger
 from autobots_devtools_shared_lib.common.servers.noderedmanagerserver.config import (
     NodeRedManagerServerConfig,
     TemplateConfig,
 )
+from autobots_devtools_shared_lib.common.servers.noderedmanagerserver.exceptions import (
+    FlowsFileNotFoundError,
+    InstanceNotFoundError,
+    InvalidWorkspacePathError,
+    NoAvailablePortError,
+    NodeRedLaunchError,
+    NodeRedManagerError,
+    UnknownEnvironmentError,
+)
 from autobots_devtools_shared_lib.common.servers.noderedmanagerserver.models import (
     CreateInstanceRequest,
     CreateInstanceResponse,
@@ -39,8 +52,8 @@ from autobots_devtools_shared_lib.common.servers.noderedmanagerserver.models imp
 logger = get_logger(__name__)
 config = NodeRedManagerServerConfig()
 
-# In-memory registry: instance_id -> (InstanceInfo, subprocess handle)
-_registry: dict[str, tuple[InstanceInfo, asyncio.subprocess.Process]] = {}
+# In-memory registry: instance_id -> (InstanceInfo, subprocess handle, TTL task)
+_registry: dict[str, tuple[InstanceInfo, asyncio.subprocess.Process, asyncio.Task[None]]] = {}
 
 
 # ---------------------------------------------------------------------------
@@ -62,13 +75,13 @@ async def _is_port_available(port: int) -> bool:
 
 async def _find_available_port(template: TemplateConfig) -> int:
     """Scan sequentially within the template's port range; skip ports used by tracked instances."""
-    used_ports = {info.port for info, _ in _registry.values()}
+    used_ports = {info.port for info, _, _ in _registry.values()}
     for port in range(template.min_port, template.max_port + 1):
         if port in used_ports:
             continue
         if await _is_port_available(port):
             return port
-    raise RuntimeError(
+    raise NoAvailablePortError(
         f"No available ports in range [{template.min_port}, {template.max_port}] "
         f"for environment '{template.name}'. All ports are occupied."
     )
@@ -86,26 +99,54 @@ async def _launch_node_red(
 
     INSTANCE_ID is passed as an env var so the environment's settings.js can set
     httpAdminRoot and httpNodeRoot to '/<instance_id>' for URL isolation.
+
+    On Windows, node-red is installed as a .cmd batch file and cannot be executed
+    directly by create_subprocess_exec — it must be routed through cmd.exe.
+    CREATE_NEW_PROCESS_GROUP assigns a new process group so taskkill /T can target
+    the entire tree (cmd.exe + node-red child) during cleanup.
     """
     env = {**os.environ, "FLOW": flows_json_path, "INSTANCE_ID": instance_id}
+    node_red_args = ["-u", str(template.path), "--port", str(port)]
+    if sys.platform == "win32":
+        cmd = ["cmd", "/c", config.node_red_executable, *node_red_args]
+        extra_kwargs: dict = {"creationflags": subprocess.CREATE_NEW_PROCESS_GROUP}
+    else:
+        cmd = [config.node_red_executable, *node_red_args]
+        extra_kwargs = {}
     return await asyncio.create_subprocess_exec(
-        config.node_red_executable,
-        "-u",
-        str(template.path),
-        "--port",
-        str(port),
+        *cmd,
         env=env,
         stdout=asyncio.subprocess.PIPE,
         stderr=asyncio.subprocess.PIPE,
+        **extra_kwargs,
     )
 
 
 async def _kill_instance(instance_id: str, process: asyncio.subprocess.Process) -> None:
-    """SIGTERM the process; escalate to SIGKILL after 5 seconds."""
+    """Terminate the process and its children.
+
+    On Unix: SIGTERM with a 5s grace period, then SIGKILL.
+    On Windows: taskkill /F /T kills the entire process tree (cmd.exe + node-red child)
+    because process.terminate() only kills cmd.exe, leaving node-red orphaned.
+    """
     try:
-        process.terminate()  # SIGTERM on Unix
-        await asyncio.wait_for(process.wait(), timeout=5.0)
-        logger.info("Instance %s terminated gracefully", instance_id)
+        if sys.platform == "win32":
+            killer = await asyncio.create_subprocess_exec(
+                "taskkill",
+                "/F",
+                "/T",
+                "/PID",
+                str(process.pid),
+                stdout=asyncio.subprocess.DEVNULL,
+                stderr=asyncio.subprocess.DEVNULL,
+            )
+            await killer.wait()
+            await process.wait()
+            logger.info("Instance %s terminated (Windows taskkill)", instance_id)
+        else:
+            process.terminate()  # SIGTERM on Unix
+            await asyncio.wait_for(process.wait(), timeout=5.0)
+            logger.info("Instance %s terminated gracefully", instance_id)
     except ProcessLookupError:
         logger.info("Instance %s process already gone (pid=%s)", instance_id, process.pid)
     except TimeoutError:
@@ -115,6 +156,20 @@ async def _kill_instance(instance_id: str, process: asyncio.subprocess.Process)
         await process.wait()
 
 
+async def _ttl_kill(instance_id: str, ttl_seconds: int) -> None:
+    """Background task: auto-kill an instance after its TTL expires."""
+    try:
+        await asyncio.sleep(ttl_seconds)
+    except asyncio.CancelledError:
+        return  # killed manually before TTL; nothing to do
+    entry = _registry.pop(instance_id, None)
+    if entry is None:
+        return  # already removed (e.g. manual kill lost the race)
+    _, process, _ = entry
+    logger.info("TTL expired for instance %s, killing", instance_id)
+    await _kill_instance(instance_id, process)
+
+
 # ---------------------------------------------------------------------------
 # Lifespan
 # ---------------------------------------------------------------------------
@@ -139,7 +194,9 @@ async def lifespan(_app: FastAPI):
     yield
 
     logger.info("Node-RED server shutting down, terminating %d instance(s)", len(_registry))
-    tasks = [_kill_instance(iid, proc) for iid, (_, proc) in _registry.items()]
+    for _, _, ttl_task in _registry.values():
+        ttl_task.cancel()
+    tasks = [_kill_instance(iid, proc) for iid, (_, proc, _) in _registry.items()]
     if tasks:
         await asyncio.gather(*tasks, return_exceptions=True)
     _registry.clear()
@@ -163,6 +220,37 @@ app = FastAPI(
 )
 
 
+@app.exception_handler(NodeRedManagerError)
+async def _node_red_manager_error_handler(
+    _request: Request, exc: NodeRedManagerError
+) -> JSONResponse:
+    """Convert domain exceptions to HTTP JSON responses."""
+    return JSONResponse(
+        status_code=exc.status_code,
+        content={"detail": exc.detail, "error_code": exc.ERROR_CODE},
+    )
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+
+def _resolve_instance_id(workspace_context: dict, environment_name: str) -> str:
+    """Validate workspace_base_path and return the scoped instance ID.
+
+    Raises InvalidWorkspacePathError if the path is missing or contains '..'.
+    """
+    workspace_base_path = (workspace_context.get("workspace_base_path") or "").strip()
+    if not workspace_base_path:
+        raise InvalidWorkspacePathError(
+            "workspace_context.workspace_base_path is required and cannot be empty."
+        )
+    if ".." in workspace_base_path:
+        raise InvalidWorkspacePathError("workspace_base_path cannot contain '..'")
+    return f"{environment_name}/{workspace_base_path}"
+
+
 # ---------------------------------------------------------------------------
 # Endpoints
 # ---------------------------------------------------------------------------
@@ -206,8 +294,10 @@ def list_instances() -> dict[str, Any]:
             "environment_name": info.environment_name,
             "url": info.url,
             "pid": info.pid,
+            "created_at": info.created_at.isoformat(),
+            "expires_at": info.expires_at.isoformat(),
         }
-        for info, _ in _registry.values()
+        for info, _, _ in _registry.values()
     ]
     return {"instances": instances, "count": len(instances)}
 
@@ -227,65 +317,48 @@ async def create_instance(body: CreateInstanceRequest) -> CreateInstanceResponse
         body.workspace_context,
     )
 
-    # 1. Extract and validate workspace_base_path — used as the instance ID
-    workspace_base_path: str = (body.workspace_context.get("workspace_base_path") or "").strip()
-    if not workspace_base_path:
-        raise HTTPException(
-            status_code=status.HTTP_400_BAD_REQUEST,
-            detail="workspace_context.workspace_base_path is required and cannot be empty.",
-        )
-    if ".." in workspace_base_path:
-        raise HTTPException(
-            status_code=status.HTTP_400_BAD_REQUEST,
-            detail="workspace_base_path cannot contain '..'",
-        )
-    instance_id = workspace_base_path
+    # 1. Validate workspace path and derive scoped instance ID
+    instance_id = _resolve_instance_id(body.workspace_context, body.environment_name)
 
     # 2. Return existing instance if one is already running for this workspace
     if instance_id in _registry:
-        existing_info, _ = _registry[instance_id]
+        existing_info, _, _ = _registry[instance_id]
         logger.info(
             "create-instance reusing existing id=%s url=%s", existing_info.id, existing_info.url
         )
-        return CreateInstanceResponse(id=existing_info.id, url=existing_info.url)
+        return CreateInstanceResponse(
+            id=existing_info.id, url=existing_info.url, expires_at=existing_info.expires_at
+        )
 
     # 3. Validate environment name
     environment = config.environments.get(body.environment_name)
     if environment is None:
         logger.warning("create-instance unknown environment=%s", body.environment_name)
-        raise HTTPException(
-            status_code=status.HTTP_400_BAD_REQUEST,
-            detail=(
-                f"Unknown environment '{body.environment_name}'. "
-                f"Available: {list(config.environments.keys())}"
-            ),
+        raise UnknownEnvironmentError(
+            f"Unknown environment '{body.environment_name}'. "
+            f"Available: {list(config.environments.keys())}"
         )
 
     # 4. Resolve full flows path: base_path / workspace_base_path / flows_json_path
+    workspace_base_path = instance_id.split("/", 1)[1]
     flows_path = Path(config.base_path) / workspace_base_path / body.flows_json_path
     if not flows_path.exists():
-        raise HTTPException(
-            status_code=status.HTTP_400_BAD_REQUEST,
-            detail=f"flows.json not found at resolved path: {flows_path}",
-        )
+        raise FlowsFileNotFoundError(f"flows.json not found at resolved path: {flows_path}")
 
-    # 5. Find next available port within this environment's port range
-    try:
-        port = await _find_available_port(environment)
-    except RuntimeError as e:
-        raise HTTPException(status_code=status.HTTP_503_SERVICE_UNAVAILABLE, detail=str(e)) from e
+    # 5. Find next available port within this environment's port range (raises NoAvailablePortError)
+    port = await _find_available_port(environment)
 
     # 6. Launch subprocess — INSTANCE_ID env var picked up by the environment's settings.js
     try:
         process = await _launch_node_red(environment, str(flows_path), port, instance_id)
     except Exception as e:
         logger.exception("create-instance failed to launch node-red")
-        raise HTTPException(
-            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
-            detail=f"Failed to launch Node-RED: {e!s}",
-        ) from e
+        raise NodeRedLaunchError(f"Failed to launch Node-RED: {e!s}") from e
 
     # 7. Register and return
+    ttl = body.ttl_seconds if body.ttl_seconds is not None else config.instance_ttl_seconds
+    created_at = datetime.now(UTC)
+    expires_at = created_at + timedelta(seconds=ttl)
     url = f"http://{config.node_red_manager_server_host}:{port}/{instance_id}"
     info = InstanceInfo(
         id=instance_id,
@@ -293,31 +366,29 @@ async def create_instance(body: CreateInstanceRequest) -> CreateInstanceResponse
         environment_name=body.environment_name,
         url=url,
         pid=process.pid or 0,
+        created_at=created_at,
+        expires_at=expires_at,
     )
-    _registry[instance_id] = (info, process)
-    logger.info("create-instance success id=%s url=%s pid=%s", instance_id, url, process.pid)
-    return CreateInstanceResponse(id=instance_id, url=url)
+    ttl_task = asyncio.create_task(_ttl_kill(instance_id, ttl))
+    _registry[instance_id] = (info, process, ttl_task)
+    logger.info(
+        "create-instance success id=%s url=%s pid=%s ttl=%ss", instance_id, url, process.pid, ttl
+    )
+    return CreateInstanceResponse(id=instance_id, url=url, expires_at=expires_at)
 
 
 @app.post("/kill-instance")
 async def kill_instance(body: KillInstanceRequest) -> KillInstanceResponse:
     """Kill a running Node-RED instance by workspace_base_path."""
-    instance_id: str = (body.workspace_context.get("workspace_base_path") or "").strip()
-    if not instance_id:
-        raise HTTPException(
-            status_code=status.HTTP_400_BAD_REQUEST,
-            detail="workspace_context.workspace_base_path is required and cannot be empty.",
-        )
+    instance_id = _resolve_instance_id(body.workspace_context, body.environment_name)
     logger.info("kill-instance called id=%s", instance_id)
 
     entry = _registry.get(instance_id)
     if entry is None:
-        raise HTTPException(
-            status_code=status.HTTP_404_NOT_FOUND,
-            detail=f"Instance '{instance_id}' not found",
-        )
+        raise InstanceNotFoundError(f"Instance '{instance_id}' not found")
 
-    _, process = entry
+    _, process, ttl_task = entry
+    ttl_task.cancel()
     await _kill_instance(instance_id, process)
     del _registry[instance_id]
 

{autobots_devtools_shared_lib-0.8.0 → autobots_devtools_shared_lib-0.10.0}/src/autobots_devtools_shared_lib/common/servers/noderedmanagerserver/config.py

@@ -22,10 +22,10 @@ class TemplateConfig:
 
 def _load_yaml_config(
     config_file: Path,
-) -> tuple[str, str, str, int, dict[str, TemplateConfig]]:
+) -> tuple[str, str, str, int, int, dict[str, TemplateConfig]]:
     """
     Load node-red-config.yaml and return
-    (node_red_executable, base_path, manager_host, manager_port, environments_by_name).
+    (node_red_executable, base_path, manager_host, manager_port, instance_ttl_seconds, environments_by_name).
 
     Expected YAML structure::
 
@@ -38,6 +38,9 @@ def _load_yaml_config(
         node_red_manager_server_host: 0.0.0.0   # optional, defaults to "0.0.0.0"
         node_red_manager_server_port: 9003       # optional, defaults to 9003
 
+        # Seconds before an idle instance is auto-killed. Optional, defaults to 2700 (45 min).
+        instance_ttl_seconds: 2700
+
         environments:
           - name: compose-engine-template
             path: /path/to/compose-engine-template
@@ -64,6 +67,7 @@ def _load_yaml_config(
         data.get("node_red_manager_server_host", "0.0.0.0") or "0.0.0.0"  # noqa: S104
     )
     manager_port: int = int(data.get("node_red_manager_server_port", 9003))
+    instance_ttl_seconds: int = int(data.get("instance_ttl_seconds", 2700))
 
     raw_environments: list[dict] = data.get("environments") or []
     environments: dict[str, TemplateConfig] = {}
@@ -83,7 +87,14 @@ def _load_yaml_config(
             max_port=max_port,
         )
 
-    return node_red_executable, base_path, manager_host, manager_port, environments
+    return (
+        node_red_executable,
+        base_path,
+        manager_host,
+        manager_port,
+        instance_ttl_seconds,
+        environments,
+    )
 
 
 # Resolve config file path from env var; default to node-red-config.yaml in cwd.
@@ -92,14 +103,20 @@ _config_file = Path(os.getenv("NODE_RED_CONFIG_FILE", "node-red-config.yaml"))
 # Load at module import time so config is available immediately.
 # If the file is absent the server will fail fast during lifespan startup (validate() call).
 try:
-    _node_red_executable, _base_path, _manager_host, _manager_port, _environments = (
-        _load_yaml_config(_config_file)
-    )
+    (
+        _node_red_executable,
+        _base_path,
+        _manager_host,
+        _manager_port,
+        _instance_ttl_seconds,
+        _environments,
+    ) = _load_yaml_config(_config_file)
 except FileNotFoundError:
     _node_red_executable = "node-red"
     _base_path = ""
     _manager_host = "0.0.0.0"  # noqa: S104
     _manager_port = 9003
+    _instance_ttl_seconds = 2700
     _environments = {}
 
 
@@ -111,6 +128,7 @@ class NodeRedManagerServerConfig:
     base_path: str = _base_path
     node_red_manager_server_host: str = _manager_host
     node_red_manager_server_port: int = _manager_port
+    instance_ttl_seconds: int = _instance_ttl_seconds
     environments: dict[str, TemplateConfig] = _environments
 
     @classmethod

autobots_devtools_shared_lib-0.10.0/src/autobots_devtools_shared_lib/common/servers/noderedmanagerserver/exceptions.py

@@ -0,0 +1,66 @@
+"""Domain exceptions for the Node-RED instance manager server."""
+
+
+class NodeRedManagerError(Exception):
+    """Base exception for Node-RED instance manager errors.
+
+    Subclasses declare a status_code so the central FastAPI exception handler
+    can convert them to HTTP responses without any per-endpoint boilerplate.
+
+    ERROR_CODE is a stable string constant included in HTTP responses and utils
+    error strings so consumers can distinguish error types without re-raising:
+
+        from ...exceptions import FlowsFileNotFoundError
+        result = create_instance(...)
+        if FlowsFileNotFoundError.ERROR_CODE in result:
+            ...
+    """
+
+    status_code: int = 500
+    ERROR_CODE: str = "NODE_RED_MANAGER_ERROR"
+
+    def __init__(self, detail: str) -> None:
+        super().__init__(detail)
+        self.detail = detail
+
+
+class InvalidWorkspacePathError(NodeRedManagerError):
+    """Raised when workspace_base_path is empty or contains invalid path segments."""
+
+    status_code = 400
+    ERROR_CODE = "INVALID_WORKSPACE_PATH"
+
+
+class UnknownEnvironmentError(NodeRedManagerError):
+    """Raised when the requested environment name is not in the server config."""
+
+    status_code = 400
+    ERROR_CODE = "UNKNOWN_ENVIRONMENT"
+
+
+class FlowsFileNotFoundError(NodeRedManagerError):
+    """Raised when flows.json does not exist at the resolved workspace path."""
+
+    status_code = 404
+    ERROR_CODE = "FLOWS_FILE_NOT_FOUND"
+
+
+class NoAvailablePortError(NodeRedManagerError):
+    """Raised when no free port exists within the environment's configured range."""
+
+    status_code = 503
+    ERROR_CODE = "NO_AVAILABLE_PORT"
+
+
+class NodeRedLaunchError(NodeRedManagerError):
+    """Raised when the node-red subprocess fails to start."""
+
+    status_code = 500
+    ERROR_CODE = "NODE_RED_LAUNCH_ERROR"
+
+
+class InstanceNotFoundError(NodeRedManagerError):
+    """Raised when the requested instance ID is not in the registry."""
+
+    status_code = 404
+    ERROR_CODE = "INSTANCE_NOT_FOUND"

{autobots_devtools_shared_lib-0.8.0 → autobots_devtools_shared_lib-0.10.0}/src/autobots_devtools_shared_lib/common/servers/noderedmanagerserver/models.py

@@ -1,5 +1,6 @@
 """Pydantic request/response models for the Node-RED instance manager API."""
 
+from datetime import datetime
 from typing import Any
 
 from pydantic import BaseModel, Field, field_validator
@@ -20,6 +21,11 @@ class CreateInstanceRequest(BaseModel):
         description="Relative path to flows.json within the workspace directory.",
     )
     environment_name: str = Field(..., description="Name of the Node-RED environment to use.")
+    ttl_seconds: int | None = Field(
+        default=None,
+        description="TTL in seconds before the instance is auto-killed. Uses server default if not provided.",
+        ge=1,
+    )
 
     @field_validator("flows_json_path")
     @classmethod
@@ -41,6 +47,9 @@ class CreateInstanceRequest(BaseModel):
 class CreateInstanceResponse(BaseModel):
     id: str = Field(..., description="Instance ID (workspace_base_path).")
     url: str = Field(..., description="URL to access the Node-RED instance (includes port).")
+    expires_at: datetime = Field(
+        ..., description="UTC datetime when this instance will be auto-killed."
+    )
 
 
 class KillInstanceRequest(BaseModel):
@@ -49,6 +58,7 @@ class KillInstanceRequest(BaseModel):
         description="Workspace scoping context. Must include `workspace_base_path`.",
         json_schema_extra={"examples": [{"workspace_base_path": "alice/my-project-JIRA-42"}]},
     )
+    environment_name: str = Field(..., description="Name of the Node-RED environment to kill.")
 
 
 class KillInstanceResponse(BaseModel):
@@ -61,3 +71,5 @@ class InstanceInfo(BaseModel):
     environment_name: str
     url: str
     pid: int
+    created_at: datetime
+    expires_at: datetime