option domains

Author: amdfxlucas

seedemu/compiler/Docker.py

@@ -1,6 +1,6 @@
 from __future__ import annotations
 from seedemu.core.Emulator import Emulator
-from seedemu.core import Node, Network, Compiler, BaseSystem, BaseOption, Scope, NodeScopeType, NodeScopeTier, OptionHandling, BaseVolume, OptionMode
+from seedemu.core import Node, Network, Compiler, BaseSystem, BaseOption, Scope, NodeScope, NodeScopeType, NodeScopeTier, OptionHandling, BaseVolume, OptionMode
 from seedemu.core.enums import NodeRole, NetworkType
 from .DockerImage import DockerImage
 from .DockerImageConstant import *
@@ -1346,7 +1346,7 @@ def _doCompile(self, emulator: Emulator):
             dummies = local_images + self._makeDummies()
         ), file=open('docker-compose.yml', 'w'))
 
-        self.generateEnvFile(Scope(NodeScopeTier.Global),'')
+        self.generateEnvFile(NodeScope(NodeScopeTier.Global),'')
 
     def _computeComposeTopLvlVolumes(self) -> str:
         """!@brief render the 'volumes:' section of the docker-compose.yml file

seedemu/core/AutonomousSystem.py

@@ -5,7 +5,8 @@
 from .AddressAssignmentConstraint import AddressAssignmentConstraint
 from .enums import NetworkType, NodeRole
 from .Node import Node, Router
-from .Scope import NodeScopeTier, Scope
+from .Scope import NodeScopeTier, Scope, NodeScope, NetScope, NetScopeTier
+from .Option import OptionDomain
 from .Emulator import Emulator
 from .Configurable import Configurable
 from .Customizable import Customizable
@@ -137,9 +138,13 @@ def inheritOptions(self, emulator: Emulator):
         for n in all_nets:
             self.handDown(n) # TODO: this also installs  NodeOptions on the Net... which is no harm, but unnecessary
 
-    def scope(self)-> Scope:
+    def scope(self, domain: OptionDomain = None)-> Scope:
         """return a scope specific to this AS"""
-        return Scope(NodeScopeTier.AS, as_id=self.getAsn())
+        match domain:
+            case OptionDomain.NODE:
+                return NodeScope(NodeScopeTier.AS, as_id=self.getAsn())
+            case OptionDomain.NET:
+                return NetScope(NetScopeTier.Scoped, scope_id=self.getAsn())
 
 
     def configure(self, emulator: Emulator):

seedemu/core/Configurable.py

@@ -55,7 +55,7 @@ def _prepare(self, emulator: Emulator):
             Override this method in your Layer if you want more targeted
             setting of Options i.e. only on border-routers or hosts etc..
         """
-        from .Scope import Scope, NodeScopeTier
+        from .Scope import NodeScope, NodeScopeTier
 
         # set options on nodes directly
         reg = emulator.getRegistry()
@@ -65,7 +65,7 @@ def _prepare(self, emulator: Emulator):
             for o in self.getAvailableOptions():
                 assert o, 'implementation error'
                 # TODO: if o has __prefix attribute add prefix  argument to setOption()
-                n.setOption(o, Scope(NodeScopeTier.Global))
+                n.setOption(o, NodeScope(NodeScopeTier.Global))
 
 
     def configure(self, emulator: Emulator):

seedemu/core/Customizable.py

@@ -2,7 +2,7 @@
 from functools import cmp_to_key
 from typing import Optional, Dict, Tuple
 from seedemu.core.Scope import *
-from seedemu.core.Option import BaseOption, OptionMode
+from seedemu.core.Option import BaseOption, OptionMode, OptionDomain
 
 class Customizable(object):
 
@@ -16,17 +16,22 @@ def __init__(self):  # scope param. actually only for debug/tests  , scope: Scop
         self._config = {}
         self._scope = None
 
-    def scope(self)-> Scope:
-        """!@brief returns a scope that includes only this very customizable instance ,nothing else"""
+    def scope(self, domain: OptionDomain = None)-> Scope:
+        """!@brief returns a scope that includes only this very customizable instance ,nothing else
+        @param domain depending on what you need the scope object for
+                (i.e. for which kind of Option you want to specify the scope for)
+                you might need a different kind of scope
+        """
         # it's only natural for a customizable to know its place in the hierarchy
-        if not self._scope: return Scope(NodeScopeTier.Global) # maybe introduce a ScopeTier.NONE for this...
+        if not self._scope: return NodeScope(NodeScopeTier.Global) # maybe introduce a ScopeTier.NONE for this...
         else: return self._scope
 
 
     def getScopedOption(self, key: str, scope: Scope = None, prefix: str = None) -> Optional[Tuple[BaseOption, Scope]]:
         """! @brief retrieves an option along with the most specific Scope in which it was set.
         """
-        if not scope:  scope = self.scope()
+        from seedemu.core.OptionRegistry import OptionRegistry
+        if not scope:  scope = self.scope(domain=OptionRegistry().getDomain(key, prefix))
 
         keys = [key]
 
@@ -76,15 +81,32 @@ def getOption(self, key: str, scope: Scope = None, prefix: str = None ) -> Optio
             return None
 
     def _possible_scopes(scope: Scope) -> List[Scope]:
-        possible_scopes = [
-            Scope(NodeScopeTier.Node, scope._node_type, 
-                  as_id=scope.asn, node_id=scope._node_id) if scope._node_id and scope._as_id and scope._node_type else None,   # Node-specific + type
-            Scope(NodeScopeTier.Node,node_id=scope._node_id, as_id=scope._as_id) if scope._node_id and scope._as_id else None,   # Node-specific
-            Scope(NodeScopeTier.AS, scope._node_type, as_id=scope._as_id) if scope._as_id and scope._node_type else None,   # AS & Type
-            Scope(NodeScopeTier.AS, NodeScopeType.ANY, as_id=scope._as_id) if scope._as_id else None,    # AS-wide
-            Scope(NodeScopeTier.Global, scope._node_type),   # Global & Type
-            Scope(NodeScopeTier.Global)                     # Global (fallback)
-        ]
+        if isinstance(scope, NodeScope):
+            possible_scopes = [
+                NodeScope(NodeScopeTier.Node, scope._node_type, 
+                      as_id=scope.asn, node_id=scope._node_id) if scope._node_id and scope._as_id and scope._node_type else None,   # Node-specific + type
+                NodeScope(NodeScopeTier.Node,node_id=scope._node_id, as_id=scope._as_id) if scope._node_id and scope._as_id else None,   # Node-specific
+                NodeScope(NodeScopeTier.AS, scope._node_type, as_id=scope._as_id) if scope._as_id and scope._node_type else None,   # AS & Type
+                NodeScope(NodeScopeTier.AS, NodeScopeType.ANY, as_id=scope._as_id) if scope._as_id else None,    # AS-wide
+                NodeScope(NodeScopeTier.Global, scope._node_type),   # Global & Type
+                NodeScope(NodeScopeTier.Global)                     # Global (fallback)
+            ]
+        if isinstance(scope, NetScope):
+            possible_scopes = [
+                NetScope(NetScopeTier.Individual,net_type=scope.type, scope_id=scope.scope, net_id=scope.net ) 
+                if scope.scope and scope.net and scope.type else None, # Net specific + type
+                NetScope(NetScopeTier.Individual, scope_id=scope.scope, net_id=scope.net ) 
+                if scope.scope and scope.net else None, # Net specific
+
+                NetScope(NetScopeTier.Scoped, scope.type, scope_id=scope.scope) 
+                if scope.scope and scope.type else None,   # scope & Type
+                NetScope(NetScopeTier.Scoped, NetScopeType.ANY, scope_id=scope.scope)
+                if scope.scope else None,    # scope-wide
+
+                NetScope(NetScopeTier.Global, net_type=scope.type),
+                NetScope(NetScopeTier.Global)
+            ]
+
         return possible_scopes
 
     def _getKeys(self) -> List[str]:
@@ -108,15 +130,29 @@ def handDown(self, child: 'Customizable'):
             i.e. ASes are a collection of Nodes.
             This methods performs the inheritance of options from parent to child.
         """
-        
-        try: # scopes could be incomparable
-            assert self.scope()>child.scope(), 'logic error - cannot inherit options from more general scopes'
-        except :
-            pass
+        from .Network import Network
+        from .Node import Node
+        dom = OptionDomain.NET if type(child)== Network else OptionDomain.NODE
+        s1=self.scope(dom)
+        s2=child.scope(dom)
+
+       
+        assert not s1 < s2, 'logic error - cannot inherit options from more general scopes'
 
         for k, val in self._config.items():
             for (op, s) in val:
-                child.setOption(op, s)
+                if self.valid_down(op,child):
+                    child.setOption(op, s)
+
+    @staticmethod
+    def valid_down(op, child):
+            from .Network import Network
+            from .Node import Node
+            # enforce option-domains only at the lowest granularity (customizable hierarchy): Nodes and Networks
+            # Any aggregates of higher levels i.e. ASes, ISDs (that don't inherit neither Node nor Network)
+            #  can have Options of mixed domains
+            return not ((op.optiondomain() == OptionDomain.NET and issubclass(type(child), Node)) or 
+                        (issubclass( type(child), Network) and op.optiondomain()==OptionDomain.NODE ) )
 
     def setOption(self, op: BaseOption, scope: Scope = None ):
         """! @brief set option within the given scope.
@@ -126,6 +162,8 @@ def setOption(self, op: BaseOption, scope: Scope = None ):
         # Everything else would be counterintuitive i.e. setting individual node overrides through the 
         # API of the AS , rather than the respective node's itself
 
+        assert self.valid_down(op, self), 'input error'
+
         if not scope:  scope = self.scope()
 
         opname = op.name

seedemu/core/InternetExchange.py

@@ -36,7 +36,7 @@ def __init__(self, id: int, prefix: str = "auto", aac: AddressAssignmentConstrai
         network = IPv4Network(prefix) if prefix != "auto" else IPv4Network("10.{}.0.0/24".format(self.__id))
 
         self.__name = 'ix{}'.format(str(self.__id))
-        self.__net = Network(self.__name, NetworkType.InternetExchange, network, aac, False)
+        self.__net = Network(self.__name, NetworkType.InternetExchange, network, aac, False, scope=str(id))
 
         if create_rs:
             self.__rs = Router(self.__name, NodeRole.RouteServer, self.__id)      

seedemu/core/Network.py

@@ -10,6 +10,7 @@
 from .Customizable import Customizable
 from .Scope import Scope,NetScope, NetScopeTier, NetScopeType
 from typing import Dict, Tuple, List
+from .OptionUtil import OptionDomain
 
 class Network(Printable, Registrable, Vertex, Customizable):
     """!
@@ -68,10 +69,19 @@ def __init__(self, name: str, type: NetworkType, prefix: IPv4Network, aac: Addre
         self.__rap = None
         self.__ecp = None
 
-    def scope(self)-> Scope:
+    def scope(self, domain: OptionDomain = None)-> Scope:
         """return a Scope that is specific to this Network"""
-        return NetScope(tier=NetScopeTier.Individual,
-                        net_type=NetScopeType.from_net(self),
+
+        assert domain in [OptionDomain.NET, None], 'input error'
+        match (nt:=NetScopeType.from_net(self)):
+            case NetScopeType.XC:
+                return NetScope(tier=NetScopeTier.Individual,
+                        net_type=nt,
+                        scope_id=0, # scope of XC nets is None otherwise
+                        net_id=self.getName())
+            case _:
+                return NetScope(tier=NetScopeTier.Individual,
+                        net_type=nt,
                         scope_id=int(self.__scope),
                         net_id=self.getName())
 

seedemu/core/Node.py

@@ -8,6 +8,7 @@
 from .Registry import Registrable
 from .Emulator import Emulator
 from .Customizable import Customizable
+from .OptionUtil import OptionDomain
 from .Volume import BaseVolume
 from .Configurable import Configurable
 from .enums import NetworkType
@@ -291,8 +292,9 @@ def __init__(self, name: str, role: NodeRole, asn: int, scope: str = None):
         self.__note = None
 
 
-    def scope(self)-> Scope:
-        return Scope(NodeScopeTier.Node,
+    def scope(self, domain: OptionDomain = None)-> Scope:
+        assert domain in [OptionDomain.NODE, None], 'input error'
+        return NodeScope(NodeScopeTier.Node,
                      node_type=NodeScopeType.from_node(self),
                      node_id=self.getName(),
                      as_id=self.getAsn())
@@ -360,6 +362,7 @@ def configure(self, emulator: Emulator):
             else:
                 # netname = 'as{}.{}_as{}.{}'.format(self.getAsn(), self.getName(), peerasn, peername)
                 netname = ''.join(choice(ascii_letters) for i in range(10))
+                # TOODO scope of XC nets ?! pair of both ASes .. ?!
                 net = Network(netname, NetworkType.CrossConnect, localaddr.network, direct = False) # TODO: XC nets w/ direct flag?
                 net.setDefaultLinkProperties(latency, bandwidth, packetDrop).setMtu(mtu) # Set link properties
                 self.__joinNetwork(reg.register('xc', 'net', netname, net), str(localaddr.ip))

seedemu/core/Option.py

@@ -1,6 +1,5 @@
-from enum import Flag, auto
 from typing import List, Optional, Type, Any
-
+from .OptionUtil import *
 
 
 class AutoRegister():
@@ -74,17 +73,6 @@ def components_recursive(cls, prefix: str = None) -> Optional[List['BaseComponen
                 opts.extend(c.components_recursive(prefix = f'{cls.getName()}_{c.getName()}'))
         return opts
 
-class OptionMode(Flag):
-    """!@brief characteristics of an option,
-        during which time it might be changed or set
-    """
-    # static/hardcoded (require re-compile + image-rebuild to change)
-    BUILD_TIME = auto()
-    # i.e. envsubst (require only docker compose stop/start )
-    RUN_TIME = auto()
-
-
-
 class OptionGroupMeta(type): # or BaseComponentMeta ..
     """Metaclass to auto-register nested options within a group."""
 
@@ -112,6 +100,7 @@ def __new__(cls, name, bases, class_dict):
                     # prefixed_name = f"{name}_{attr_value.name()}"
                     # better call new_cls.add() # here
                     new_cls._children[attr_value.name] = attr_value
+                    attr_value.domain = new_cls.optiondomain()
             # don't register nested options twice (but only once as child of the parent 'composite')
             if '.' not in qname or qname.startswith('SEEDEmuOptionSystemTestCase'):
                 OptionRegistry().register(new_cls)
@@ -121,6 +110,17 @@ def __new__(cls, name, bases, class_dict):
 class BaseOption(BaseComponent, metaclass=OptionGroupMeta):
     """! a base class for KEY-VALUE pairs representing Settings, Parameters or Feature Flags"""
 
+    domain: OptionDomain = None # set by the parent option container
+
+    @property
+    def domain(self) -> OptionDomain:
+        # if domain not specified by parent container,
+        # user must implement optiondomain()
+        if (d:= self.__class__.domain) != None:
+            return d
+        else:
+            return self.optiondomain()
+
     def __eq__(self, other):
         if not other: return False
 
@@ -139,10 +139,15 @@ def value(self, new_value: str):
         """Should allow setting a new value."""
         pass
 
+    @classmethod
+    def optiondomain(cls) -> OptionDomain:
+       return cls.domain
+
     @property
     def mode(self)->OptionMode:
         """Should return the mode of the option."""
         pass
+
     @mode.setter
     def mode(self, new_mode: OptionMode):
         pass
@@ -161,6 +166,7 @@ class Option(BaseOption):
     """
     # Immutable class variable to be defined in subclasses
     value_type: Type[Any]
+    
 
     def __init__(self, value: Optional[Any] = None, mode: OptionMode = None):
         cls = self.__class__
@@ -229,6 +235,8 @@ def value(self, new_value: Any):
         assert new_value != None, 'Logic Error - option value cannot be None!'
         self._mutable_value = new_value
 
+    
+
     @property
     def mode(self):
         if (mode := self._mutable_mode) != None:
@@ -246,6 +254,12 @@ def description(cls) -> str:
             and its allowed values
         """
         return cls.__doc__ or "No documentation available."
+    
+    @classmethod
+    def domain(cls) -> OptionDomain:
+        """ the types of entities that a given Option 
+        can apply or refer to"""
+        return OptionDomain.NODE
 
 
 #class ScopedOption:
@@ -257,6 +271,7 @@ def description(cls) -> str:
 
 class BaseOptionGroup(BaseComponent , metaclass=OptionGroupMeta):
     _children = {}
+    domain: OptionDomain = None
 
 
     def describe(self) -> str:
@@ -275,4 +290,8 @@ def get(self, option_name: str) -> Optional[BaseComponent]:
 
     @classmethod
     def components(cls):
-        return [v for _, v in cls._children.items()]
+        return [v for _, v in cls._children.items()]
+    
+    @classmethod
+    def optiondomain(cls) -> OptionDomain:
+        return cls.domain

seedemu/core/OptionRegistry.py

@@ -1,4 +1,4 @@
-from typing import Dict, Type
+from typing import Dict, Type, Optional
 
 
 class SingletonMeta(type):
@@ -51,6 +51,14 @@ def create_option(cls, name: str, *args, **kwargs) -> 'Option':
         # Instantiate with given arguments
         return option_cls(*args[1:], **kwargs)
 
+    @classmethod
+    def getDomain(cls, key: str, prefix: str = None) -> Optional['OptionDomain']:
+        o = cls.getType(key, prefix)
+        if o:
+            return o.optiondomain()
+        else:
+            return None
+
 
     @classmethod
     def getType(cls, name: str, prefix: str = None) -> Type['BaseComponent']: