orchestrator-lso 2.1.1__py3-none-any.whl → 2.2.0__py3-none-any.whl

lso/__init__.py

@@ -13,7 +13,7 @@
 
 """LSO, an API for remotely running Ansible playbooks."""
 
-__version__ = "2.1.1"
+__version__ = "2.2.0"
 
 import logging
 

lso/execute.py

@@ -1,11 +1,13 @@
 """Module for handling the execution of arbitrary executables."""
 
+import subprocess  # noqa: S404
 import uuid
 from pathlib import Path
 
 from pydantic import HttpUrl
 
 from lso.config import ExecutorType, settings
+from lso.schema import ExecutionResult
 from lso.tasks import run_executable_proc_task
 from lso.utils import get_thread_pool
 
@@ -15,17 +17,43 @@ def get_executable_path(executable_name: Path) -> Path:
     return Path(settings.EXECUTABLES_ROOT_DIR) / executable_name
 
 
-def run_executable(executable_path: Path, args: list[str], callback: HttpUrl) -> uuid.UUID:
+def run_executable_async(executable_path: Path, args: list[str], callback: HttpUrl | None) -> uuid.UUID:
     """Dispatch the task for executing an arbitrary executable remotely.
 
     Uses a ThreadPoolExecutor (for local execution) or a Celery worker (for distributed tasks).
     """
     job_id = uuid.uuid4()
+    callback_url = str(callback) if callback else None
     if settings.EXECUTOR == ExecutorType.THREADPOOL:
         executor = get_thread_pool()
-        future = executor.submit(run_executable_proc_task, str(job_id), str(executable_path), args, str(callback))
+        future = executor.submit(run_executable_proc_task, str(job_id), str(executable_path), args, callback_url)
         if settings.TESTING:
             future.result()
     elif settings.EXECUTOR == ExecutorType.WORKER:
-        run_executable_proc_task.delay(str(job_id), str(executable_path), args, str(callback))
+        run_executable_proc_task.delay(str(job_id), str(executable_path), args, callback_url)
     return job_id
+
+
+def run_executable_sync(executable_path: str, args: list[str]) -> ExecutionResult:
+    """Run the given executable synchronously and return the result."""
+    try:
+        result = subprocess.run(  # noqa: S603
+            [executable_path, *args],
+            text=True,
+            capture_output=True,
+            timeout=settings.EXECUTABLE_TIMEOUT_SEC,
+            check=False,
+        )
+        output = result.stdout + result.stderr
+        return_code = result.returncode
+    except subprocess.TimeoutExpired:
+        output = "Execution timed out."
+        return_code = -1
+    except Exception as e:  # noqa: BLE001
+        output = str(e)
+        return_code = -1
+
+    return ExecutionResult(  # type: ignore[call-arg]
+        output=output,
+        return_code=return_code,
+    )

lso/routes/execute.py

@@ -1,5 +1,6 @@
 """FastAPI route for running arbitrary executables."""
 
+import asyncio
 import uuid
 from pathlib import Path
 from typing import Annotated
@@ -7,7 +8,8 @@ from typing import Annotated
 from fastapi import APIRouter, HTTPException, status
 from pydantic import AfterValidator, BaseModel, HttpUrl
 
-from lso.execute import get_executable_path, run_executable
+from lso.execute import get_executable_path, run_executable_async, run_executable_sync
+from lso.schema import ExecutableRunResponse
 
 router = APIRouter()
 
@@ -35,17 +37,17 @@ class ExecutableRunParams(BaseModel):
 
     executable_name: ExecutableName
     args: list[str] = []
-    callback: HttpUrl
-
-
-class ExecutableRunResponse(BaseModel):
-    """Response for running an arbitrary executable."""
-
-    job_id: uuid.UUID
+    callback: HttpUrl | None = None
+    is_async: bool = True
 
 
 @router.post("/", response_model=ExecutableRunResponse, status_code=status.HTTP_201_CREATED)
-def run_executable_endpoint(params: ExecutableRunParams) -> ExecutableRunResponse:
-    """Dispatch an asynchronous task to run an arbitrary executable."""
-    job_id = run_executable(params.executable_name, params.args, params.callback)
-    return ExecutableRunResponse(job_id=job_id)
+async def run_executable_endpoint(params: ExecutableRunParams) -> ExecutableRunResponse:
+    """Dispatch a task to run an arbitrary executable."""
+    if params.is_async:
+        job_id = run_executable_async(params.executable_name, params.args, params.callback)
+        return ExecutableRunResponse(job_id=job_id)
+
+    job_id = uuid.uuid4()
+    result = await asyncio.to_thread(run_executable_sync, str(params.executable_name), params.args)
+    return ExecutableRunResponse(job_id=job_id, result=result)

lso/schema.py

@@ -0,0 +1,50 @@
+# Copyright 2024-2025 GÉANT Vereniging.
+# 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.
+
+"""Module for defining the schema for running arbitrary executables."""
+
+import uuid
+from enum import StrEnum
+
+from pydantic import BaseModel, model_validator
+
+
+class JobStatus(StrEnum):
+    """Enumeration of possible job statuses."""
+
+    SUCCESSFUL = "successful"
+    FAILED = "failed"
+
+
+class ExecutionResult(BaseModel):
+    """Model for capturing the result of an executable run."""
+
+    output: str
+    return_code: int
+    status: JobStatus
+
+    @model_validator(mode="before")
+    def populate_status(cls, values: dict) -> dict:
+        """Set the status based on the return code."""
+        rc = values.get("return_code")
+        if rc is not None:
+            values["status"] = JobStatus.SUCCESSFUL if rc == 0 else JobStatus.FAILED
+
+        return values
+
+
+class ExecutableRunResponse(BaseModel):
+    """Response for running an arbitrary executable."""
+
+    job_id: uuid.UUID
+    result: ExecutionResult | None = None

lso/tasks.py

@@ -1,4 +1,4 @@
-# Copyright 2023-2024 GÉANT Vereniging.
+# Copyright 2024-2025 GÉANT Vereniging.
 # 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
@@ -18,15 +18,15 @@ the results to a specified callback URL.
 """
 
 import logging
-import subprocess  # noqa: S404
-from enum import StrEnum
 from typing import Any
+from uuid import UUID
 
 import ansible_runner
 import requests
 from starlette import status
 
 from lso.config import settings
+from lso.schema import ExecutableRunResponse
 from lso.worker import RUN_EXECUTABLE, RUN_PLAYBOOK, celery
 
 logger = logging.getLogger(__name__)
@@ -36,13 +36,6 @@ class CallbackFailedError(Exception):
     """Exception raised when a callback url can't be reached."""
 
 
-class JobStatus(StrEnum):
-    """Enumeration of possible job statuses."""
-
-    SUCCESSFUL = "successful"
-    FAILED = "failed"
-
-
 @celery.task(name=RUN_PLAYBOOK)  # type: ignore[misc]
 def run_playbook_proc_task(
     job_id: str, playbook_path: str, extra_vars: dict[str, Any], inventory: dict[str, Any] | str, callback: str
@@ -74,48 +67,34 @@ def run_playbook_proc_task(
 
 
 @celery.task(name=RUN_EXECUTABLE)  # type: ignore[misc]
-def run_executable_proc_task(job_id: str, executable_path: str, args: list[str], callback: str) -> None:
+def run_executable_proc_task(job_id: str, executable_path: str, args: list[str], callback: str | None) -> None:
     """Celery task to run an arbitrary executable and notify via callback.
 
-    Executes the executable with the provided arguments and posts back the output and status.
+    Executes the executable with the provided arguments and posts back the result if a callback URL is provided.
     """
+    from lso.execute import run_executable_sync  # noqa: PLC0415
+
     msg = f"Executing executable: {executable_path} with args: {args}, callback: {callback}"
     logger.info(msg)
-    try:
-        result = subprocess.run(  # noqa: S603
-            [executable_path, *args],
-            text=True,
-            capture_output=True,
-            timeout=settings.EXECUTABLE_TIMEOUT_SEC,
-            check=False,
-        )
-        output = result.stdout + result.stderr
-        return_code = result.returncode
-    except subprocess.TimeoutExpired:
-        output = "Execution timed out."
-        return_code = -1
-    except Exception as e:  # noqa: BLE001
-        output = str(e)
-        return_code = -1
-
-    payload = {
-        "job_id": job_id,
-        "output": output,
-        "return_code": return_code,
-        "status": JobStatus.SUCCESSFUL if return_code == 0 else JobStatus.FAILED,
-    }
-
-    def _raise_callback_error(message: str, error: Exception | None = None) -> None:
-        if error:
-            raise CallbackFailedError(message) from error
-        raise CallbackFailedError(message)
-
-    try:
-        response = requests.post(str(callback), json=payload, timeout=settings.REQUEST_TIMEOUT_SEC)
-        if not (status.HTTP_200_OK <= response.status_code < status.HTTP_300_MULTIPLE_CHOICES):
-            msg = f"Callback failed: {response.text}, url: {callback}"
-            _raise_callback_error(msg)
-    except Exception as e:
-        error_msg = f"Callback error: {e}"
-        logger.exception(error_msg)
-        _raise_callback_error(error_msg, e)
+    result = run_executable_sync(executable_path, args)
+
+    if callback:
+        payload = ExecutableRunResponse(
+            job_id=UUID(job_id),
+            result=result,
+        ).model_dump(mode="json")
+
+        def _raise_callback_error(message: str, error: Exception | None = None) -> None:
+            if error:
+                raise CallbackFailedError(message) from error
+            raise CallbackFailedError(message)
+
+        try:
+            response = requests.post(str(callback), json=payload, timeout=settings.REQUEST_TIMEOUT_SEC)
+            if not (status.HTTP_200_OK <= response.status_code < status.HTTP_300_MULTIPLE_CHOICES):
+                msg = f"Callback failed: {response.text}, url: {callback}"
+                _raise_callback_error(msg)
+        except Exception as e:
+            error_msg = f"Callback error: {e}"
+            logger.exception(error_msg)
+            _raise_callback_error(error_msg, e)

lso/utils.py

@@ -1,3 +1,16 @@
+# Copyright 2024-2025 GÉANT Vereniging.
+# 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.
+
 """Utility functions for the LSO package."""
 
 from concurrent.futures import ThreadPoolExecutor

{orchestrator_lso-2.1.1.dist-info → orchestrator_lso-2.2.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: orchestrator-lso
-Version: 2.1.1
+Version: 2.2.0
 Summary: LSO, an API for remotely running Ansible playbooks.
 Author-email: GÉANT Orchestration and Automation Team <goat@geant.org>
 Requires-Python: >=3.11,<3.13
@@ -30,10 +30,10 @@ Requires-Dist: ansible-runner==2.4.1
 Requires-Dist: ansible==10.7.0
 Requires-Dist: fastapi==0.115.12
 Requires-Dist: httpx==0.28.1
-Requires-Dist: uvicorn[standard]==0.34.2
-Requires-Dist: requests==2.32.3
+Requires-Dist: uvicorn[standard]==0.34.3
+Requires-Dist: requests==2.32.4
 Requires-Dist: pydantic-settings==2.9.1
-Requires-Dist: celery==5.5.2
+Requires-Dist: celery==5.5.3
 Requires-Dist: redis==5.2.1
 Requires-Dist: types-setuptools ; extra == "dev"
 Requires-Dist: types-requests ; extra == "dev"

orchestrator_lso-2.2.0.dist-info/RECORD

@@ -0,0 +1,18 @@
+lso/__init__.py,sha256=jBH_2-SwYCAcTSYY-AZXATzRzEMrZh2tQVHLM12XrQ0,1589
+lso/app.py,sha256=WDtlmjELIeFA437j-WPfqBQf6QT_l35LEABbEosHlqY,775
+lso/config.py,sha256=fceYs85UGN76GRyGs4x6TiKhktv-ykjc6-WocPRmFGY,1639
+lso/environment.py,sha256=iZ3DmsSKAC5a7VNL-HfJOJZ0sQwUMf7ZzNGC34B2CG0,1771
+lso/execute.py,sha256=G1AacmmN46mAzPWpnoI31RhXoWN6WEZUFr_P8Z_9Ngw,2139
+lso/playbook.py,sha256=NHCeVttY5u1xGAdty954SZEYLcZEGBbBfjPuvBCgUwI,2409
+lso/schema.py,sha256=-QCBaUcfMH1MaEEDaGzZoGJn-NcQLbH4dfrLxFYoXXs,1513
+lso/tasks.py,sha256=tM26bAiEviaKAVwiHkKr6od3N00covBAAXTFVxIvdY8,4030
+lso/utils.py,sha256=eVKyYRtdu_yPkbUQqDJlCKlCPAgc0dFxG1E1kY2Qsao,1043
+lso/worker.py,sha256=61TXUefv8mGMq9LsD419r0O9Qxpa-WAtgSfu7SPEg44,1727
+lso/routes/__init__.py,sha256=1kRrth9zkFgmj6LChujieYJq5cjIETeTGXa1G70pduk,639
+lso/routes/default.py,sha256=a7STN1BJyFVizXUzmqKuADO0fpE1SHun-PzaZ-jx1wU,1438
+lso/routes/execute.py,sha256=zwObIRB2aSlCikpmHQ6TJFcZFCjEPFC4R7oIu1UA7R8,2122
+lso/routes/playbook.py,sha256=YNPZGuJXh5JkDWJ-sVRVE-cTg9eEm6BPjNThFLDqxeM,4904
+orchestrator_lso-2.2.0.dist-info/licenses/LICENSE,sha256=CgFXf7XbZXJADozQIw2uUmmvU-zwAwXo4u7cgDfx3rE,10744
+orchestrator_lso-2.2.0.dist-info/WHEEL,sha256=G2gURzTEtmeR8nrdXUJfNiB3VYVxigPQ-bEQujpNiNs,82
+orchestrator_lso-2.2.0.dist-info/METADATA,sha256=WU3uePo1qeayracQz2hlaj90m9ZXhPcjoinRCy5F15o,6352
+orchestrator_lso-2.2.0.dist-info/RECORD,,

orchestrator_lso-2.1.1.dist-info/RECORD

@@ -1,17 +0,0 @@
-lso/__init__.py,sha256=3ECt41yxiWdlZJA_Ym-67uW4kABwCp8AE6gtcsH53_U,1589
-lso/app.py,sha256=WDtlmjELIeFA437j-WPfqBQf6QT_l35LEABbEosHlqY,775
-lso/config.py,sha256=fceYs85UGN76GRyGs4x6TiKhktv-ykjc6-WocPRmFGY,1639
-lso/environment.py,sha256=iZ3DmsSKAC5a7VNL-HfJOJZ0sQwUMf7ZzNGC34B2CG0,1771
-lso/execute.py,sha256=BZeR0NYLZaLE28K7IcQ6JA7opdJOZrVK7rsSZyArsBo,1208
-lso/playbook.py,sha256=NHCeVttY5u1xGAdty954SZEYLcZEGBbBfjPuvBCgUwI,2409
-lso/tasks.py,sha256=ToHEDEqGipMUYk7sY8qZzrYV5dWwM8nekl2OGiEVVko,4509
-lso/utils.py,sha256=8B3_p5nliD0KQcU2dLRdbEa7LvDqtNH0ZViMJ4yB4gE,458
-lso/worker.py,sha256=61TXUefv8mGMq9LsD419r0O9Qxpa-WAtgSfu7SPEg44,1727
-lso/routes/__init__.py,sha256=1kRrth9zkFgmj6LChujieYJq5cjIETeTGXa1G70pduk,639
-lso/routes/default.py,sha256=a7STN1BJyFVizXUzmqKuADO0fpE1SHun-PzaZ-jx1wU,1438
-lso/routes/execute.py,sha256=8WACuI8QN8piI4pkHNtxARB8l5QcBKWSZ3qE_LWqBfU,1896
-lso/routes/playbook.py,sha256=YNPZGuJXh5JkDWJ-sVRVE-cTg9eEm6BPjNThFLDqxeM,4904
-orchestrator_lso-2.1.1.dist-info/licenses/LICENSE,sha256=CgFXf7XbZXJADozQIw2uUmmvU-zwAwXo4u7cgDfx3rE,10744
-orchestrator_lso-2.1.1.dist-info/WHEEL,sha256=G2gURzTEtmeR8nrdXUJfNiB3VYVxigPQ-bEQujpNiNs,82
-orchestrator_lso-2.1.1.dist-info/METADATA,sha256=W0RWPPi0wLpUE2mi6ZF696Axst7usH2njtV-txUh0bw,6352
-orchestrator_lso-2.1.1.dist-info/RECORD,,