updates to example service and documentation supporting it

daemon/examples/myservices/sample.py

@@ -2,57 +2,81 @@
 Sample user-defined service.
 """
 
-from core.misc.ipaddress import Ipv4Prefix
 from core.service import CoreService
+from core.service import ServiceMode
 
 
+## Custom CORE Service
 class MyService(CoreService):
-    """
-    This is a sample user-defined service.
-    """
-    # a unique name is required, without spaces
+    ### Service Attributes
+
+    # Name used as a unique ID for this service and is required, no spaces.
     name = "MyService"
-    # you can create your own group here
+    # Allows you to group services within the GUI under a common name.
     group = "Utility"
-    # list executables that this service requires
+    # Executables this service depends on to function, if executable is not on the path, service will not be loaded.
     executables = ()
-    # list of other services this service depends on
+    # Services that this service depends on for startup, tuple of service names.
     dependencies = ()
-    # per-node directories
+    # Directories that this service will create within a node.
     dirs = ()
-    # generated files (without a full path this file goes in the node's dir,
-    #  e.g. /tmp/pycore.12345/n1.conf/)
-    configs = ("myservice.sh",)
-    # list of startup commands, also may be generated during startup
-    startup = ("sh myservice.sh",)
-    # list of shutdown commands
+    # Files that this service will generate, without a full path this file goes in the node's directory.
+    # e.g. /tmp/pycore.12345/n1.conf/myfile
+    configs = ("sh myservice1.sh", "sh myservice2.sh")
+    # Commands used to start this service, any non-zero exit code will cause a failure.
+    startup = ("sh %s" % configs[0], "sh %s" % configs[1])
+    # Commands used to validate that a service was started, any non-zero exit code will cause a failure.
+    validate = ()
+    # Validation mode, used to determine startup success.
+    # * NON_BLOCKING    - runs startup commands, and validates success with validation commands
+    # * BLOCKING        - runs startup commands, and validates success with the startup commands themselves
+    # * TIMER           - runs startup commands, and validates success by waiting for "validation_timer" alone
+    validation_mode = ServiceMode.NON_BLOCKING
+    # Time for a service to wait before running validation commands or determining success in TIMER mode.
+    validation_timer = 0
+    # Shutdown commands to stop this service.
     shutdown = ()
 
+    ### On Load
+    @classmethod
+    def on_load(cls):
+        # Provides a way to run some arbitrary logic when the service is loaded, possibly to help facilitate
+        # dynamic settings for the environment.
+        pass
+
+    ### Get Configs
+    @classmethod
+    def get_configs(cls, node):
+        # Provides a way to dynamically generate the config files from the node a service will run.
+        # Defaults to the class definition and can be left out entirely if not needed.
+        return cls.configs
+
+    ### Generate Config
     @classmethod
     def generate_config(cls, node, filename):
-        """
-        Return a string that will be written to filename, or sent to the
-        GUI for user customization.
-        """
+        # Returns a string representation for a file, given the node the service is starting on the config filename
+        # that this information will be used for. This must be defined, if "configs" are defined.
         cfg = "#!/bin/sh\n"
-        cfg += "# auto-generated by MyService (sample.py)\n"
 
-        for ifc in node.netifs():
-            cfg += 'echo "Node %s has interface %s"\n' % (node.name, ifc.name)
-            # here we do something interesting
-            cfg += "\n".join(map(cls.subnetentry, ifc.addrlist))
-            break
+        if filename == cls.configs[0]:
+            cfg += "# auto-generated by MyService (sample.py)\n"
+            for ifc in node.netifs():
+                cfg += 'echo "Node %s has interface %s"\n' % (node.name, ifc.name)
+        elif filename == cls.configs[1]:
+            cfg += "echo hello"
+
         return cfg
 
-    @staticmethod
-    def subnetentry(x):
-        """
-        Generate a subnet declaration block given an IPv4 prefix string
-        for inclusion in the config file.
-        """
-        if x.find(":") >= 0:
-            # this is an IPv6 address
-            return ""
-        else:
-            net = Ipv4Prefix(x)
-            return 'echo "  network %s"' % net
+    ### Get Startup
+    @classmethod
+    def get_startup(cls, node):
+        # Provides a way to dynamically generate the startup commands from the node a service will run.
+        # Defaults to the class definition and can be left out entirely if not needed.
+        return cls.startup
+
+    ### Get Validate
+    @classmethod
+    def get_validate(cls, node):
+        # Provides a way to dynamically generate the validate commands from the node a service will run.
+        # Defaults to the class definition and can be left out entirely if not needed.
+        return cls.validate