Merge branch 'master' into blackout/SYN-8002/cpe-migration-help

.bumpversion.cfg

@@ -1,5 +1,5 @@
 [bumpversion]
-current_version = 2.182.0
+current_version = 2.183.0
 commit = True
 tag = True
 tag_message = 

CHANGELOG.rst

@@ -6,6 +6,41 @@
 Synapse Changelog
 *****************
 
+v2.183.0 - 2024-10-09
+=====================
+
+Model Changes
+-------------
+- Fix an issue where the ``:path:base``, ``:path:dir``, and ``:path:ext``
+  secondary properties were marked readonly on the ``it:fs:file``,
+  ``it:exec:file:add``, ``it:exec:file:del``, ``it:exec:file:read``, and
+  ``it:exec:file:write`` forms.
+  (`#3942 <https://github.com/vertexproject/synapse/pull/3942>`_)
+- See :ref:`userguide_model_v2_183_0` for more detailed model changes.
+
+Features and Enhancements
+-------------------------
+- Expose Stormlib deprecation status from the Python API.
+  (`#3929 <https://github.com/vertexproject/synapse/pull/3929>`_)
+- Add ``$lib.random.generator()`` to get a random number generator in Storm.
+  (`#3945 <https://github.com/vertexproject/synapse/pull/3945>`_)
+
+Bugfixes
+--------
+- Tag add operations with the try syntax ( ``+?#`` ) now catch BadTag
+  exceptions raised by tags which are not valid for a defined tag model.
+  (`#3941 <https://github.com/vertexproject/synapse/pull/3941>`_)
+- Added ``task.get`` and ``task.del`` permissions declarations so they get
+  included in the output of the ``auth.perms.list`` command.
+  (`#3944 <https://github.com/vertexproject/synapse/pull/3944>`_)
+
+Improved documentation
+----------------------
+- Clarify parts of the Storm automation guide.
+  (`#3938 <https://github.com/vertexproject/synapse/pull/3938>`_)
+- Clarify Storm type specific documentation for ``guid`` types.
+  (`#3939 <https://github.com/vertexproject/synapse/pull/3939>`_)
+
 v2.182.0 - 2024-09-27
 =====================
 

changes/b033cdc61731e49b48db67094121b4d6.yaml

@@ -0,0 +1,7 @@
+---
+desc: Fix a Storm bug where a runtsafe list unpacking operation which was executed
+  per-node would be executed one additional time after all nodes had finished
+  moving through the pipeline.
+prs: []
+type: bug
+...

docs/synapse/userguides/model_updates/update_v2_183_0.rst

@@ -0,0 +1,78 @@
+
+
+.. _userguide_model_v2_183_0:
+
+######################
+v2.183.0 Model Updates
+######################
+
+The following model updates were made during the ``v2.183.0`` Synapse release.
+
+******************
+Updated Properties
+******************
+
+``it:exec:file:add``
+  The form had the following properties updated:
+
+
+    The property ``path:base`` is no longer marked as read only.
+
+
+    The property ``path:dir`` is no longer marked as read only.
+
+
+    The property ``path:ext`` is no longer marked as read only.
+
+
+``it:exec:file:del``
+  The form had the following properties updated:
+
+
+    The property ``path:base`` is no longer marked as read only.
+
+
+    The property ``path:dir`` is no longer marked as read only.
+
+
+    The property ``path:ext`` is no longer marked as read only.
+
+
+``it:exec:file:read``
+  The form had the following properties updated:
+
+
+    The property ``path:base`` is no longer marked as read only.
+
+
+    The property ``path:dir`` is no longer marked as read only.
+
+
+    The property ``path:ext`` is no longer marked as read only.
+
+
+``it:exec:file:write``
+  The form had the following properties updated:
+
+
+    The property ``path:base`` is no longer marked as read only.
+
+
+    The property ``path:dir`` is no longer marked as read only.
+
+
+    The property ``path:ext`` is no longer marked as read only.
+
+
+``it:fs:file``
+  The form had the following properties updated:
+
+
+    The property ``path:base`` is no longer marked as read only.
+
+
+    The property ``path:dir`` is no longer marked as read only.
+
+
+    The property ``path:ext`` is no longer marked as read only.
+

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = 'setuptools.build_meta'
 
 [project]
 name = 'synapse'
-version = '2.182.0'
+version = '2.183.0'
 authors = [
     { name = 'The Vertex Project LLC', email = '[email protected]'},
 ]

synapse/cortex.py

@@ -1453,6 +1453,11 @@ def _initCorePerms(self):
             {'perm': ('storm', 'macro', 'edit'), 'gate': 'cortex',
              'desc': 'Controls access to edit a storm macro.'},
 
+            {'perm': ('task', 'get'), 'gate': 'cortex',
+             'desc': 'Controls access to view other users tasks.'},
+            {'perm': ('task', 'del'), 'gate': 'cortex',
+             'desc': 'Controls access to terminate other users tasks.'},
+
             {'perm': ('view',), 'gate': 'cortex',
              'desc': 'Controls all view permissions.'},
             {'perm': ('view', 'add'), 'gate': 'cortex',

synapse/lib/ast.py

@@ -1302,8 +1302,9 @@ async def run(self, runt, genr):
         names = self.kids[0].value()
         vkid = self.kids[1]
 
+        anynodes = False
         async for node, path in genr:
-
+            anynodes = True
             item = await vkid.compute(runt, path)
             item = [i async for i in s_stormtypes.toiter(item)]
 
@@ -1318,7 +1319,7 @@ async def run(self, runt, genr):
 
             yield node, path
 
-        if vkid.isRuntSafe(runt):
+        if not anynodes and vkid.isRuntSafe(runt):
 
             item = await vkid.compute(runt, None)
             item = [i async for i in s_stormtypes.toiter(item)]

synapse/lib/stormlib/random.py

@@ -1,33 +1,114 @@
 import random
 
 import synapse.exc as s_exc
+import synapse.common as s_common
+
 import synapse.lib.stormtypes as s_stormtypes
 
+from typing import Optional
+
 randinst = random.SystemRandom()
 
+
+@s_stormtypes.registry.registerType
+class Random(s_stormtypes.StormType):
+    '''
+    A random number generator.
+    '''
+    _storm_typename = 'random'
+    _storm_locals = (
+        {'name': 'int', 'desc': 'Generate a random integer.',
+         'type': {'type': 'function', '_funcname': '_methInt',
+                  'args': (
+                      {'name': 'maxval', 'type': 'int', 'desc': 'The maximum random value.'},
+                      {'name': 'minval', 'type': 'int', 'desc': 'The minimum random value.', 'default': 0},
+                  ),
+                  'returns': {'type': 'int', 'desc': 'A random integer in the range min-max inclusive.'}}},
+        {'name': 'seed', 'desc': 'The seed used for the generator. Setting this value resets the generator state.',
+         'type': {'type': ['gtor', 'stor'], '_storfunc': '_storSeed', '_gtorfunc': '_gtorSeed',
+                  'returns': {'type': ['str', 'null']}}},
+    )
+    _ismutable = False
+
+    def __init__(self, runt, seed: Optional[str] =None):
+        s_stormtypes.StormType.__init__(self)
+        self.runt = runt
+        self._seed = seed
+        self.robj = random.Random()
+        if seed is not None:
+            self.robj.seed(self._seed, version=2)
+        self.locls.update(self.getObjLocals())
+        self.gtors.update({
+            'seed': self._gtorSeed,
+        })
+        self.stors.update({
+            'seed': self._storSeed,
+        })
+
+    async def stormrepr(self):
+        ret = f'{self._storm_typename}'
+        if self._seed is not None:
+            ret = f'{ret} seed={s_common.trimText(self._seed, n=40)}'
+        return ret
+
+    def getObjLocals(self):
+        return {
+            'int': self._methInt,
+        }
+
+    async def _gtorSeed(self):
+        return self._seed
+
+    async def _storSeed(self, seed):
+        self._seed = await s_stormtypes.tostr(seed, noneok=True)
+        self.robj.seed(self._seed)
+
+    @s_stormtypes.stormfunc(readonly=True)
+    async def _methInt(self, maxval, minval=0):
+        maxval = await s_stormtypes.toint(maxval)
+        minval = await s_stormtypes.toint(minval)
+        if minval > maxval:
+            raise s_exc.BadArg(mesg=f'Minval must be less than or equal to maxval, minval={minval}, maxval={maxval}',
+                               minval=minval, maxval=maxval)
+        return self.robj.randint(minval, maxval)
+
 @s_stormtypes.registry.registerLib
 class LibRandom(s_stormtypes.Lib):
     '''
     A Storm library for generating random values.
     '''
     _storm_locals = (
         {'name': 'int', 'desc': 'Generate a random integer.',
-         'type': {'type': 'function', '_funcname': '_int',
+         'type': {'type': 'function', '_funcname': '_methInt',
                   'args': (
                       {'name': 'maxval', 'type': 'int', 'desc': 'The maximum random value.'},
                       {'name': 'minval', 'type': 'int', 'desc': 'The minimum random value.', 'default': 0},
                   ),
                   'returns': {'type': 'int', 'desc': 'A random integer in the range min-max inclusive.'}}},
+        {'name': 'generator', 'desc': 'Make a random generator with a given seed.',
+         'type': {'type': 'function', '_funcname': '_methGenerator',
+                  'args': (
+                      {'name': 'seed', 'type': 'str', 'default': None,
+                       'desc': 'The seed value used for the random generator.'},
+                  ),
+                  'returns': {'type': 'random', 'desc': 'The random generator object.'}}
+        }
     )
     _storm_lib_path = ('random',)
 
     def getObjLocals(self):
         return {
-            'int': self._int,
+            'int': self._methInt,
+            'generator': self._methGenerator,
         }
 
     @s_stormtypes.stormfunc(readonly=True)
-    async def _int(self, maxval, minval=0):
+    async def _methGenerator(self, seed=None):
+        seed = await s_stormtypes.tostr(seed, noneok=True)
+        return Random(self.runt, seed=seed)
+
+    @s_stormtypes.stormfunc(readonly=True)
+    async def _methInt(self, maxval, minval=0):
         maxval = await s_stormtypes.toint(maxval)
         minval = await s_stormtypes.toint(minval)
         if minval > maxval:

synapse/lib/version.py

@@ -223,6 +223,6 @@ def reqVersion(valu, reqver,
 ##############################################################################
 # The following are touched during the release process by bumpversion.
 # Do not modify these directly.
-version = (2, 182, 0)
+version = (2, 183, 0)
 verstring = '.'.join([str(x) for x in version])
 commit = ''

synapse/models/infotech.py

@@ -2736,15 +2736,12 @@ def getModelDefs(self):
                         'doc': 'The path for the file.',
                     }),
                     ('path:dir', ('file:path', {}), {
-                        'ro': True,
                         'doc': 'The parent directory of the file path (parsed from :path).',
                     }),
                     ('path:ext', ('str', {'lower': True, 'strip': True}), {
-                        'ro': True,
                         'doc': 'The file extension of the file name (parsed from :path).',
                     }),
                     ('path:base', ('file:base', {}), {
-                        'ro': True,
                         'doc': 'The final component of the file path (parsed from :path).',
                     }),
                     ('file', ('file:bytes', {}), {
@@ -2782,15 +2779,12 @@ def getModelDefs(self):
                         'doc': 'The path where the file was created.',
                     }),
                     ('path:dir', ('file:path', {}), {
-                        'ro': True,
                         'doc': 'The parent directory of the file path (parsed from :path).',
                     }),
                     ('path:ext', ('str', {'lower': True, 'strip': True}), {
-                        'ro': True,
                         'doc': 'The file extension of the file name (parsed from :path).',
                     }),
                     ('path:base', ('file:base', {}), {
-                        'ro': True,
                         'doc': 'The final component of the file path (parsed from :path).',
                     }),
                     ('file', ('file:bytes', {}), {
@@ -2816,15 +2810,12 @@ def getModelDefs(self):
                         'doc': 'The path where the file was deleted.',
                     }),
                     ('path:dir', ('file:path', {}), {
-                        'ro': True,
                         'doc': 'The parent directory of the file path (parsed from :path).',
                     }),
                     ('path:ext', ('str', {'lower': True, 'strip': True}), {
-                        'ro': True,
                         'doc': 'The file extension of the file name (parsed from :path).',
                     }),
                     ('path:base', ('file:base', {}), {
-                        'ro': True,
                         'doc': 'The final component of the file path (parsed from :path).',
                     }),
                     ('file', ('file:bytes', {}), {
@@ -2850,15 +2841,12 @@ def getModelDefs(self):
                         'doc': 'The path where the file was read.',
                     }),
                     ('path:dir', ('file:path', {}), {
-                        'ro': True,
                         'doc': 'The parent directory of the file path (parsed from :path).',
                     }),
                     ('path:ext', ('str', {'lower': True, 'strip': True}), {
-                        'ro': True,
                         'doc': 'The file extension of the file name (parsed from :path).',
                     }),
                     ('path:base', ('file:base', {}), {
-                        'ro': True,
                         'doc': 'The final component of the file path (parsed from :path).',
                     }),
                     ('file', ('file:bytes', {}), {
@@ -2884,15 +2872,12 @@ def getModelDefs(self):
                         'doc': 'The path where the file was written to/modified.',
                     }),
                     ('path:dir', ('file:path', {}), {
-                        'ro': True,
                         'doc': 'The parent directory of the file path (parsed from :path).',
                     }),
                     ('path:ext', ('str', {'lower': True, 'strip': True}), {
-                        'ro': True,
                         'doc': 'The file extension of the file name (parsed from :path).',
                     }),
                     ('path:base', ('file:base', {}), {
-                        'ro': True,
                         'doc': 'The final component of the file path (parsed from :path).',
                     }),
                     ('file', ('file:bytes', {}), {