Deprecate forms key in Storm command definitions and related syn:cmd …

…props (SYN-6596) (#4076)

changes/fce9eb48213f47cd09de69147fc605bd.yaml

@@ -0,0 +1,7 @@
+---
+desc: The ``forms`` key in Storm package command definitions has been deprecated. The
+  ``cmdinputs`` key may still be used to specify node forms that commands are intended
+  to accept as input.
+prs: []
+type: deprecation
+...

docs/docdata/foopkg/foopkg.yml

@@ -38,10 +38,5 @@ commands:
           help: Specify a timeout in seconds.
     cmdconf:
       srcguid: f751f9ad20e75547be230ae1a425fb9f
-    forms:
-      input:
-        - inet:ipv4
-      output:
-        - inet:ipv4
-      nodedata:
-        - [ foodata, file:bytes ]
+    cmdinputs:
+      - form: inet:ipv4

synapse/cortex.py

@@ -2860,6 +2860,12 @@ async def _normStormPkg(self, pkgdef, validstorm=True):
                 cmdtext = cdef.get('storm')
                 await self.getStormQuery(cmdtext)
 
+            if cdef.get('forms') is not None:
+                name = cdef.get('name')
+                mesg = f"Storm command definition 'forms' key is deprecated and will be removed " \
+                       f"in 3.0.0 (command {name} in package {pkgname})"
+                logger.warning(mesg, extra=await self.getLogExtra(name=name, pkgname=pkgname))
+
         for gdef in pkgdef.get('graphs', ()):
             gdef['iden'] = s_common.guid((pkgname, gdef.get('name')))
             gdef['scope'] = 'power-up'

synapse/models/syn.py

@@ -341,10 +341,13 @@ def getModelDefs(self):
                     ('svciden', ('guid', {'strip': True}), {
                         'doc': 'Storm service iden which provided the package.'}),
                     ('input', ('array', {'type': 'syn:form'}), {
+                        'deprecated': True,
                         'doc': 'The list of forms accepted by the command as input.', 'uniq': True, 'sorted': True, 'ro': True}),
                     ('output', ('array', {'type': 'syn:form'}), {
+                        'deprecated': True,
                         'doc': 'The list of forms produced by the command as output.', 'uniq': True, 'sorted': True, 'ro': True}),
                     ('nodedata', ('array', {'type': 'syn:nodedata'}), {
+                        'deprecated': True,
                         'doc': 'The list of nodedata that may be added by the command.', 'uniq': True, 'sorted': True, 'ro': True}),
                 )),
             ),

synapse/tests/test_model_syn.py

@@ -612,10 +612,16 @@ async def test_syn_cmd_runts(self):
                 nodes = await core.nodes('syn:cmd +:package')
                 self.len(0, nodes)
 
-                await core.nodes(f'service.add test {url}')
-                iden = core.getStormSvcs()[0].iden
+                with self.getLoggerStream('synapse.cortex') as stream:
+                    await core.nodes(f'service.add test {url}')
+                    iden = core.getStormSvcs()[0].iden
 
-                await core.nodes('$lib.service.wait(test)')
+                    await core.nodes('$lib.service.wait(test)')
+
+                stream.seek(0)
+                warn = "Storm command definition 'forms' key is deprecated and will be removed " \
+                       "in 3.0.0 (command foobar in package foo)"
+                self.isin(warn, stream.read())
 
                 # check that runt nodes for new commands are created
                 nodes = await core.nodes('syn:cmd +:package')