Add 'restart' parameter to test_component and update REST API documentation

Author: grongierisc

docs/python-api.md

@@ -277,13 +277,14 @@ Manages InterSystems IRIS productions and business services, particularly for no
         - `target`: Name of the business service in production
     - Returns: Business service instance
 
-- `test_component(target: str, message=None, classname: str=None, body=None) -> object`
+- `test_component(target: str, message=None, classname: str=None, body=None, restart: bool=False) -> object`
     - Test a production component
     - Parameters:
         - `target`: Component name
-        - `message`: Optional message instance
+        - `message`: Optional message instance (local mode only)
         - `classname`: Optional message class name
-        - `body`: Optional message body
+        - `body`: Optional message body (JSON string or dict)
+        - `restart`: If `True`, the target component is stopped and restarted before the test message is dispatched (remote mode only)
     - Returns: Component response
 
 **Production Logging:**

docs/rest-api.md

@@ -307,7 +307,8 @@ Sends a test message to a target component and returns the response synchronousl
 {
   "target":    "Python.MyOperation",
   "classname": "Python.MyMsg",
-  "body":      {"key": "value"}
+  "body":      {"key": "value"},
+  "restart":   true
 }
 ```
 
@@ -316,6 +317,7 @@ Sends a test message to a target component and returns the response synchronousl
 | `target`    | Yes      | Config name of the component to invoke                                           |
 | `classname` | No       | Python message class name. If omitted an empty `Ens.Request` is used.           |
 | `body`      | No       | Message body — either a **JSON object** or a **JSON string**. Defaults to `{}`. |
+| `restart`   | No       | If `true`, the target component is stopped and restarted before the message is dispatched. Useful to pick up code changes without restarting the whole production. |
 
 **Response**
 

src/iop/_remote.py

@@ -191,13 +191,20 @@ def test_component(
         message=None,           # ignored remotely — not serialisable over HTTP
         classname: Optional[str] = None,
         body: Optional[Union[str, dict]] = None,
+        restart: bool = True,
     ) -> dict:
-        """Returns a dict: {"classname": "...", "body": "...", "truncated": false}"""
+        """Returns a dict: {"classname": "...", "body": "...", "truncated": false}.
+
+        If *restart* is True the target component is stopped and restarted on
+        the server before the test message is dispatched.
+        """
         payload: dict = {"target": target or ""}
         if classname:
             payload["classname"] = classname
         if body is not None:
             payload["body"] = body
+        if restart:
+            payload["restart"] = True
         try:
             return self._check_error(self._post("/test", payload))
         except requests.exceptions.HTTPError as exc:

src/iop/cls/IOP/Service/Remote/Rest/v1.cls

@@ -250,7 +250,8 @@ ClassMethod GetExport() As %Status
 }
 
 /// POST /test
-/// Body: {"target":"Python.MyOp", "classname":"Python.MyMsg", "body":"{}", "namespace":"USER"}
+/// Body: {"target":"Python.MyOp", "classname":"Python.MyMsg", "body":"{}", "namespace":"USER", "restart":true}
+/// If "restart" is true the target component is stopped and restarted before the test message is dispatched. (Default true)
 /// Returns: {"classname":"...", "body":"...", "session_id":"..."}
 ClassMethod PostTest() As %Status
 {
@@ -262,9 +263,17 @@ ClassMethod PostTest() As %Status
 		Set target    = dyna.%Get("target")
 		Set classname = dyna.%Get("classname")
 		Set body      = dyna.%Get("body")
+		Set restart   = dyna.%Get("restart")
+		If restart = "" { Set restart = 1 }
 		Set ns        = ..ResolveNs(dyna)
 		If ns '= "" { Do ..NamespaceCheck(ns)  New $NAMESPACE  Set $NAMESPACE = ns }
 
+		// Optionally restart the target component before testing
+		If restart {
+			$$$ThrowOnError(##class(Ens.Director).EnableConfigItem(target, 0, 1))
+			$$$ThrowOnError(##class(Ens.Director).EnableConfigItem(target, 1, 1))
+		}
+
 		// Normalize body: if it arrived as a JSON object, serialize it to a string
 		If $isobject(body) { Set body = body.%ToJSON() }