services: validate-reinstall

* Closes #526
* Add basic support for the `cylc vr` command.

Author: oliver-sanders

cylc/uiserver/resolvers.py

@@ -216,6 +216,9 @@ class Services:
     # log file stream lag
     CAT_LOG_SLEEP = 1
 
+    #  command timeout for commands which start schedulers
+    START_TIMEOUT = 120
+
     @staticmethod
     def _error(message: Union[Exception, str]):
         """Format error case response."""
@@ -235,9 +238,9 @@ def _return(message: str):
     @classmethod
     async def clean(
         cls,
+        workflows_mgr: 'WorkflowsManager',
         workflows: Iterable['Tokens'],
         args: dict,
-        workflows_mgr: 'WorkflowsManager',
         executor: 'Executor',
         log: 'Logger'
     ):
@@ -278,20 +281,21 @@ async def scan(
         return cls._return("Scan requested")
 
     @classmethod
-    async def play(
+    async def run_command(
         cls,
+        command: tuple[str],
         workflows: Iterable[Tokens],
         args: Dict[str, Any],
-        workflows_mgr: 'WorkflowsManager',
         log: 'Logger',
-    ) -> List[Union[bool, str]]:
-        """Calls `cylc play`."""
+        timeout: int,
+    ) -> List[bool | str]:
+        """Calls the specified Cylc command."""
         cylc_version = args.pop('cylc_version', None)
         results: Dict[str, str] = {}
         failed = False
         for tokens in workflows:
             try:
-                cmd = _build_cmd(['cylc', 'play', '--color=never'], args)
+                cmd = _build_cmd(['cylc', *command, '--color=never'], args)
 
                 if tokens['user'] and tokens['user'] != getuser():
                     return cls._error(
@@ -322,7 +326,7 @@ async def play(
                     stderr=PIPE,
                     text=True
                 )
-                ret_code = proc.wait(timeout=120)
+                ret_code = proc.wait(timeout=timeout)
 
                 if ret_code:
                     msg = f"Command failed ({ret_code}): {cmd_repr}"
@@ -335,7 +339,7 @@ async def play(
                     )
                     failed = True
                 else:
-                    results[wflow] = 'started'
+                    results[wflow] = 'Command succeeded'
 
             except Exception as exc:  # unexpected error
                 log.exception(exc)
@@ -351,10 +355,53 @@ async def play(
                 )
             )
 
+        return []
+
+    @classmethod
+    async def play(
+        cls, workflows_mgr: 'WorkflowsManager', *args, **kwargs
+    ) -> List[Union[bool, str]]:
+        """Calls `cylc play`."""
+        # run `cylc play`
+        ret = await cls.run_command(
+            ('play',),
+            *args,
+            **kwargs,
+            timeout=cls.START_TIMEOUT,
+        )
+
         # trigger a re-scan
         await workflows_mgr.scan()
-        # send a success message
-        return cls._return('Workflow(s) started')
+
+        # return results
+        if ret:
+            return ret
+        else:
+            # send a success message
+            return cls._return('Workflow(s) started')
+
+    @classmethod
+    async def validate_reinstall(
+        cls, workflows_mgr: 'WorkflowsManager', *args, **kwargs
+    ) -> List[Union[bool, str]]:
+        """Calls `cylc validate-reinstall`."""
+        # run `cylc play`
+        ret = await cls.run_command(
+            ('validate-reinstall', '--yes'),
+            *args,
+            **kwargs,
+            timeout=cls.START_TIMEOUT,
+        )
+
+        # trigger a re-scan
+        await workflows_mgr.scan()
+
+        # return results
+        if ret:
+            return ret
+        else:
+            # send a success message
+            return cls._return('Workflow(s) reinstalled')
 
     @staticmethod
     async def enqueue(stream, queue):
@@ -592,19 +639,26 @@ async def service(
 
         if command == 'clean':  # noqa: SIM116
             return await Services.clean(
+                self.workflows_mgr,
                 workflows,
                 kwargs,
-                self.workflows_mgr,
                 log=self.log,
                 executor=self.executor
             )
         elif command == 'play':
             return await Services.play(
+                self.workflows_mgr,
                 workflows,
                 kwargs,
-                self.workflows_mgr,
                 log=self.log
             )
+        elif command == 'validate_reinstall':
+            return await Services.validate_reinstall(
+                self.workflows_mgr,
+                workflows,
+                kwargs,
+                log=self.log,
+            )
         elif command == 'scan':
             return await Services.scan(
                 kwargs,

cylc/uiserver/schema.py

@@ -241,6 +241,44 @@ class Arguments:
     result = GenericScalar()
 
 
+class ValidateReinstall(graphene.Mutation):
+    class Meta:
+        description = sstrip('''
+            Validate, reinstall, then reload or restart as appropriate.
+
+            This command updates a workflow to reflect any new changes made in
+            the workflow source directory since it was installed.
+
+            The workflow will be reinstalled, then either:
+            * Reloaded (if the workflow is running),
+            * or restarted (if it is stopped).
+        ''')
+        # Note we have the "resume" mutation for paused workflows.
+        resolver = partial(mutator, command='validate_reinstall')
+
+    class Arguments:
+        workflows = graphene.List(WorkflowID, required=True)
+        cylc_version = CylcVersion(
+            description=sstrip('''
+                Set the Cylc version that the workflow starts with.
+            ''')
+        )
+        set = graphene.List(  # noqa: A003 (graphql field name)
+            graphene.String,
+            description=sstrip('''
+                Set the value of a Jinja2 template variable in the workflow
+                definition. Values should be valid Python literals so strings
+                must be quoted e.g. `STR="string"`, `INT=43`, `BOOL=True`.
+                This option can be used multiple  times on the command line.
+                NOTE: these settings persist across workflow restarts, but can
+                be set again on the `cylc play` command line if they need to be
+                overridden.
+            ''')
+        )
+
+    result = GenericScalar()
+
+
 class Clean(graphene.Mutation):
     class Meta:
         description = sstrip('''
@@ -894,6 +932,7 @@ class Logs(graphene.ObjectType):
 
 class UISMutations(Mutations):
     play = _mut_field(Play)
+    validate_reinstall = _mut_field(ValidateReinstall)
     clean = _mut_field(Clean)
     scan = _mut_field(Scan)