diff --git a/docs/services.md b/docs/services.md index d2911d81..9f47ae48 100644 --- a/docs/services.md +++ b/docs/services.md @@ -145,7 +145,7 @@ ideas for a service before adding a new service type. ### Creating New Services -1. Modify the [Example Service File](../daemon/examples/myservices/sample.py) +1. Modify the example service shown below to do what you want. It could generate config/script files, mount per-node directories, start processes/scripts, etc. sample.py is a Python file that defines one or more classes to be imported. You can create multiple Python @@ -174,3 +174,121 @@ ideas for a service before adding a new service type. If you have created a new service type that may be useful to others, please consider contributing it to the CORE project. + +#### Example Custom Service + +Below is the skeleton for a custom service with some documentation. Most +people would likely only setup the required class variables **(name/group)**. +Then define the **configs** (files they want to generate) and implement the +**generate_confifs** function to dynamically create the files wanted. Finally +the **startup** commands would be supplied, which typically tends to be +running the shell files generated. + +```python +from core.services.coreservices import CoreService, ServiceMode + + +class MyService(CoreService): + """ + Custom CORE Service + + :var str name: name used as a unique ID for this service and is required, no spaces + :var str group: allows you to group services within the GUI under a common name + :var tuple executables: executables this service depends on to function, if executable is + not on the path, service will not be loaded + :var tuple dependencies: services that this service depends on for startup, tuple of service names + :var tuple dirs: directories that this service will create within a node + :var tuple configs: 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 + :var tuple startup: commands used to start this service, any non-zero exit code will cause a failure + :var tuple validate: commands used to validate that a service was started, any non-zero exit code + will cause a failure + :var ServiceMode validation_mode: 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 + :var int validation_timer: time in seconds for a service to wait for validation, before determining + success in TIMER/NON_BLOCKING modes. + :var float validation_validation_period: period in seconds to wait before retrying validation, + only used in NON_BLOCKING mode + :var tuple shutdown: shutdown commands to stop this service + """ + + name = "MyService" + group = "Utility" + executables = () + dependencies = () + dirs = () + configs = ("myservice1.sh", "myservice2.sh") + startup = tuple(f"sh {x}" for x in configs) + validate = () + validation_mode = ServiceMode.NON_BLOCKING + validation_timer = 5 + validation_period = 0.5 + shutdown = () + + @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. + + :return: nothing + """ + pass + + @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. + + :param node: core node that the service is being ran on + :return: tuple of config files to create + """ + return cls.configs + + @classmethod + def generate_config(cls, node, filename): + """ + 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. + + :param node: core node that the service is being ran on + :param str filename: configuration file to generate + :return: configuration file content + :rtype: str + """ + cfg = "#!/bin/sh\n" + + if filename == cls.configs[0]: + cfg += "# auto-generated by MyService (sample.py)\n" + for ifc in node.netifs(): + cfg += f'echo "Node {node.name} has interface {ifc.name}"\n' + elif filename == cls.configs[1]: + cfg += "echo hello" + + return cfg + + @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. + + :param node: core node that the service is being ran on + :return: tuple of startup commands to run + """ + return cls.startup + + @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. + + :param node: core node that the service is being ran on + :return: tuple of commands to validate service startup with + """ + return cls.validate +```