feat: SOVD diagnostic scripts with plugin-extensible ScriptProvider

README.md

@@ -83,7 +83,7 @@ Feedback welcome on [#265](https://github.com/selfpatch/ros2_medkit/issues/265).
 | 📋 Logs | **Available** | Log sources, entries, and configuration |
 | 🔁 Entity Lifecycle | Planned | Start, restart, shutdown control |
 | 🔐 Modes & Locking | Planned | Target mode control and resource locking |
-| 📝 Scripts | Planned | Diagnostic script upload and execution |
+| 📝 Scripts | **Available** | Diagnostic script upload and execution (SOVD 7.15) |
 | 🧹 Clear Data | Planned | Clear cached and learned diagnostic data |
 | 📞 Communication Logs | Planned | Protocol-level communication logging |
 

docs/api/rest.rst

@@ -1189,6 +1189,125 @@ Subscribe to a specific configuration parameter:
      "duration": 120
    }
 
+Scripts
+-------
+
+Upload, manage, and execute diagnostic scripts on entities.
+*(ISO 17978-3, 7.15)*
+
+Scripts are available on **Components** and **Apps** entity types.
+The feature must be enabled by setting ``scripts.scripts_dir`` in the gateway configuration.
+
+Upload Script
+~~~~~~~~~~~~~
+
+``POST /api/v1/{entity_type}/{entity_id}/scripts``
+   Upload a diagnostic script via ``multipart/form-data``.
+
+   - **file** (required): The script file (Python, bash, or sh)
+   - **metadata** (optional): JSON with name, description, parameters_schema
+
+   Response: **201 Created** with ``Location`` header pointing to the new script.
+
+   .. note::
+
+      Uploads can be disabled by setting ``scripts.allow_uploads: false`` in the
+      gateway configuration. When disabled, POST returns 400. Pre-deployed
+      manifest scripts remain available for execution.
+
+List Scripts
+~~~~~~~~~~~~
+
+``GET /api/v1/{entity_type}/{entity_id}/scripts``
+   List all scripts for an entity. Returns ``{"items": [...]}``.
+
+Get Script
+~~~~~~~~~~
+
+``GET /api/v1/{entity_type}/{entity_id}/scripts/{script_id}``
+   Get metadata for a specific script.
+
+Delete Script
+~~~~~~~~~~~~~
+
+``DELETE /api/v1/{entity_type}/{entity_id}/scripts/{script_id}``
+   Delete an uploaded script. Returns **204 No Content**.
+   Returns **409** if the script is manifest-managed or currently executing.
+
+Start Execution
+~~~~~~~~~~~~~~~
+
+``POST /api/v1/{entity_type}/{entity_id}/scripts/{script_id}/executions``
+   Start a new execution of a script.
+
+   **Request Body:**
+
+   .. code-block:: json
+
+      {
+        "execution_type": "now",
+        "parameters": {"threshold": 0.1}
+      }
+
+   .. list-table::
+      :header-rows: 1
+      :widths: 25 15 10 50
+
+      * - Attribute
+        - Type
+        - Conv
+        - Description
+      * - ``execution_type``
+        - string
+        - M
+        - When to run: ``now``, ``on_restart``, ``now_and_on_restart``, ``once_on_restart``
+      * - ``parameters``
+        - object
+        - O
+        - Input parameters for the script
+      * - ``proximity_response``
+        - string
+        - O
+        - Co-location proof token
+
+   .. note::
+
+      The built-in script backend supports only ``now``. Other execution types
+      (``on_restart``, ``now_and_on_restart``, ``once_on_restart``) require a
+      plugin-provided ScriptProvider and will return 400 ``invalid-parameter``
+      if not supported.
+
+   Response: **202 Accepted** with ``Location`` header pointing to the execution status.
+
+Get Execution Status
+~~~~~~~~~~~~~~~~~~~~
+
+``GET /api/v1/{entity_type}/{entity_id}/scripts/{script_id}/executions/{execution_id}``
+   Poll the status of a script execution.
+
+   Status values: ``prepared``, ``running``, ``completed``, ``failed``, ``terminated``
+
+Terminate Execution
+~~~~~~~~~~~~~~~~~~~
+
+``PUT /api/v1/{entity_type}/{entity_id}/scripts/{script_id}/executions/{execution_id}``
+   Send a termination action to a running execution.
+
+   **Request Body:**
+
+   .. code-block:: json
+
+      {"action": "stop"}
+
+   Action values: ``stop`` (SIGTERM), ``forced_termination`` (SIGKILL).
+
+Delete Execution
+~~~~~~~~~~~~~~~~
+
+``DELETE /api/v1/{entity_type}/{entity_id}/scripts/{script_id}/executions/{execution_id}``
+   Remove a completed/terminated execution resource. Returns **204 No Content**.
+   Returns **409** if the execution is still running.
+
 Rate Limiting
 -------------
 
@@ -1621,6 +1740,7 @@ use cases benefit.
 - Bulk Data (``/bulk-data``) with custom categories and rosbag downloads
 - Software Updates (``/updates``) with async prepare/execute lifecycle
 - Cyclic Subscriptions (``/cyclic-subscriptions``) with SSE-based delivery
+- Scripts (``/scripts``) with upload, execution, and lifecycle management
 
 **Pragmatic Extensions:**
 
@@ -1679,6 +1799,12 @@ extends this to areas and functions where aggregation makes practical sense:
      - yes
      - yes
      - apps, components
+   * - scripts
+     - \-
+     - yes
+     - yes
+     - \-
+     - apps, components
 
 Other extensions beyond SOVD:
 

docs/requirements/specs/scripts.rst

@@ -36,13 +36,6 @@ Scripts
 
    The endpoint shall start an execution of the addressed script on the entity.
 
-.. req:: GET /{entity}/scripts/{id}/executions
-   :id: REQ_INTEROP_045
-   :status: open
-   :tags: Scripts
-
-   The endpoint shall list executions of the addressed script on the entity.
-
 .. req:: GET /{entity}/scripts/{id}/executions/{exec-id}
    :id: REQ_INTEROP_046
    :status: open
@@ -56,4 +49,3 @@ Scripts
    :tags: Scripts
 
    The endpoint shall control or modify the addressed script execution, if supported.
-

src/ros2_medkit_gateway/CMakeLists.txt

@@ -154,6 +154,11 @@ add_library(gateway_lib STATIC
   src/auth/auth_requirement_policy.cpp
   # Updates module
   src/updates/update_manager.cpp
+  # Scripts module
+  src/script_manager.cpp
+  src/default_script_provider.cpp
+  # HTTP handlers - scripts
+  src/http/handlers/script_handlers.cpp
   # HTTP handlers - updates
   src/http/handlers/update_handlers.cpp
   # Plugin framework
@@ -453,6 +458,19 @@ if(BUILD_TESTING)
   ament_add_gtest(test_update_manager test/test_update_manager.cpp)
   target_link_libraries(test_update_manager gateway_lib)
 
+  # Add script manager tests
+  ament_add_gtest(test_script_manager test/test_script_manager.cpp)
+  target_link_libraries(test_script_manager gateway_lib)
+
+  # Add default script provider tests
+  ament_add_gtest(test_default_script_provider test/test_default_script_provider.cpp)
+  target_link_libraries(test_default_script_provider gateway_lib)
+
+  # Add script handler tests
+  ament_add_gtest(test_script_handlers test/test_script_handlers.cpp)
+  target_link_libraries(test_script_handlers gateway_lib)
+  set_tests_properties(test_script_handlers PROPERTIES ENVIRONMENT "ROS_DOMAIN_ID=69")
+
   # Add data handler tests
   ament_add_gtest(test_data_handlers test/test_data_handlers.cpp)
   target_link_libraries(test_data_handlers gateway_lib)
@@ -554,7 +572,7 @@ if(BUILD_TESTING)
   # Capability generator tests (OpenAPI spec generation engine)
   ament_add_gtest(test_capability_generator test/test_capability_generator.cpp)
   target_link_libraries(test_capability_generator gateway_lib)
-  set_tests_properties(test_capability_generator PROPERTIES ENVIRONMENT "ROS_DOMAIN_ID=67")
+  set_tests_properties(test_capability_generator PROPERTIES ENVIRONMENT "ROS_DOMAIN_ID=74")
 
   # Route registry tests (OpenAPI route registration and path conversion)
   ament_add_gtest(test_route_registry test/test_route_registry.cpp)
@@ -572,7 +590,7 @@ if(BUILD_TESTING)
   # Lock handlers tests
   ament_add_gtest(test_lock_handlers test/test_lock_handlers.cpp)
   target_link_libraries(test_lock_handlers gateway_lib)
-  set_tests_properties(test_lock_handlers PROPERTIES ENVIRONMENT "ROS_DOMAIN_ID=70")
+  set_tests_properties(test_lock_handlers PROPERTIES ENVIRONMENT "ROS_DOMAIN_ID=73")
 
   # Apply coverage flags to test targets
   if(ENABLE_COVERAGE)
@@ -605,6 +623,9 @@ if(BUILD_TESTING)
       test_cyclic_subscription_handlers
       test_sse_transport_provider
       test_update_manager
+      test_script_manager
+      test_default_script_provider
+      test_script_handlers
       test_data_handlers
       test_auth_handlers
       test_health_handlers

src/ros2_medkit_gateway/config/gateway_params.yaml

@@ -342,6 +342,27 @@ ros2_medkit_gateway:
       # Default: false
       enabled: false
 
+    # ---------------------------------------------------------------------------
+    # Scripts Configuration
+    # ---------------------------------------------------------------------------
+    # Diagnostic scripts: upload, manage, and execute scripts on entities.
+    # Set scripts_dir to enable. Leave empty to disable (all script endpoints return 501).
+    scripts:
+      # Directory for storing uploaded scripts. Empty = feature disabled.
+      scripts_dir: ""
+      # Allow uploading scripts via HTTP. Set to false for hardened deployments
+      # that only use manifest-defined scripts.
+      allow_uploads: true
+      # Maximum uploaded script file size in megabytes
+      max_file_size_mb: 10
+      # Maximum number of scripts executing concurrently
+      max_concurrent_executions: 5
+      # Default timeout per execution in seconds
+      default_timeout_sec: 300
+      # Maximum number of completed executions to keep in memory.
+      # Oldest completed entries are evicted when this limit is exceeded.
+      max_execution_history: 100
+
     # OpenAPI Documentation Endpoints
     # Controls the /docs endpoints that serve OpenAPI capability descriptions
     docs:

src/ros2_medkit_gateway/design/index.rst

@@ -35,6 +35,7 @@ The following diagram shows the relationships between the main components of the
            + get_discovery_manager(): DiscoveryManager*
            + get_configuration_manager(): ConfigurationManager*
            + get_lock_manager(): LockManager*
+           + get_script_manager(): ScriptManager*
        }
 
        class DiscoveryManager {
@@ -146,6 +147,19 @@ The following diagram shows the relationships between the main components of the
            + get_lock(): optional<LockInfo>
        }
 
+       class ScriptManager {
+           + set_backend(): void
+           + has_backend(): bool
+           + list_scripts(): expected<vector<ScriptInfo>, Error>
+           + get_script(): expected<ScriptInfo, Error>
+           + upload_script(): expected<ScriptUploadResult, Error>
+           + delete_script(): expected<void, Error>
+           + start_execution(): expected<ExecutionInfo, Error>
+           + get_execution(): expected<ExecutionInfo, Error>
+           + control_execution(): expected<ExecutionInfo, Error>
+           + delete_execution(): expected<void, Error>
+       }
+
        class NativeTopicSampler {
            + discover_all_topics(): vector<TopicInfo>
            + discover_topics(): vector<TopicInfo>
@@ -226,6 +240,7 @@ The following diagram shows the relationships between the main components of the
    GatewayNode *-down-> OperationManager : owns
    GatewayNode *-down-> ConfigurationManager : owns
    GatewayNode *-down-> LockManager : owns
+   GatewayNode *-down-> ScriptManager : owns
    GatewayNode *-down-> EntityCache : owns
 
    ' Discovery Manager uses Node interface
@@ -236,6 +251,7 @@ The following diagram shows the relationships between the main components of the
    RESTServer --> DataAccessManager : uses
    RESTServer --> OperationManager : uses
    RESTServer --> ConfigurationManager : uses
+   RESTServer --> ScriptManager : uses
 
    ' OperationManager uses DiscoveryManager and native serialization
    OperationManager --> DiscoveryManager : uses
@@ -361,10 +377,12 @@ Main Components
    - Data endpoints: ``/components/{id}/data``, ``/components/{id}/data/{topic}``
    - Operations endpoints: ``/apps/{id}/operations``, ``/apps/{id}/operations/{op}/executions``
    - Configurations endpoints: ``/apps/{id}/configurations``, ``/apps/{id}/configurations/{param}``
+   - Scripts endpoints: ``/{entity_type}/{id}/scripts``, ``/{entity_type}/{id}/scripts/{script_id}/executions``
    - Retrieves cached entities from the GatewayNode
    - Uses DataAccessManager for runtime topic data access
    - Uses OperationManager for service/action execution
    - Uses ConfigurationManager for parameter CRUD operations
+   - Uses ScriptManager for script upload and execution
    - Runs on configurable host and port with CORS support
 
 5. **ConfigurationManager** - Manages ROS 2 node parameters
@@ -413,3 +431,12 @@ Main Components
     - ``ServiceInfo`` - Service metadata (path, name, type)
     - ``ActionInfo`` - Action metadata (path, name, type)
     - ``EntityCache`` - Thread-safe cache of discovered entities (areas, components, apps)
+
+10. **ScriptManager** - Manages diagnostic script upload, storage, and execution (SOVD 7.15)
+    - Delegates to a pluggable ``ScriptProvider`` backend (set via ``set_backend()``)
+    - Lists, uploads, and deletes scripts per entity
+    - Starts script executions as POSIX subprocesses with timeout support
+    - Tracks execution status (``prepared``, ``running``, ``completed``, ``failed``, ``terminated``)
+    - Supports termination via ``stop`` (SIGTERM) and ``forced_termination`` (SIGKILL)
+    - Built-in ``DefaultScriptProvider`` handles filesystem storage and manifest-defined scripts
+    - Supports concurrent execution limits and per-script timeout configuration