3.1.1. Service implementation

This article explain how to add additional service to the plateform, or replace existing ones, for testing, mocking, or custom hardware specialization.

Services respond to some defined methods, and can be orchestrated by the admin embedded. Adminembedded can be used to deploy, start, stop, restart, or undeploy services.

Services are only XML RPC services, and can be written in any language that can generate XML RPC services. It can be configured using environment variables.

A Manifest file describe the service, and is used to deploy it. manifest.json is a file read by the admin embedded for operations.

3.1.1.1. Steps to implement a service

        graph TD
    A[Start] --> B[Implement service, in an executable]
    B --> C[create a manifest.json file]
    C --> D[test service deployement]
    D --> E[Monitor service]
    

3.1.1.2. Manifest description

a service start with the manifest.json descriptor, explaining the id of the application, and hosted services.

the application_commandline member explain the executable to execute

{
    "application_id":"",
    "application_name": "dev_mock_transfert",
    "application_version": "1.0",
    "application_description": "transfer_logic",
    "application_commandline": "/bin/python3 transfert.py", 
    "monitoring_status_file_path": "status.json",
    "running_user": "use",
    "additional_properties": {},
    "content_path": "content_path",
    "service_name": "transfer",
    "service_port": 8013
}

Manifest fields description :

Field	Mandatory Value	Description	Value Type, examples
application_id	N	this application id is populated from the application_name and the application version,	“” empty valule for non deployed application, this field is rewrite by the adminembedded when deployed
application_name	Y	this is the application name, this value MUST_NOT contains some fancy characters. Underscore are accepted
application_version	Y	version of the application, this field is free, no special characters in it
application_description	N	free text to explain the application description, and gives information about the application for new users
application_commandline	Y	this is the commandline launch for the application. applications have a principal executable
monitoring_status_file_path	N	path for the status file (will be written when deployed / activated)
running_user		user used to run ther service	NOTE : Not used YET, as V1 version
additional_properties	Y	Configuration parameters for the application, written when the application is activated	{ “additional_properties”: {“PRELOADED_JOBS”: “[{“name”:”display”,”cron”:”* * * * “,”activated”:true, “service_name”:”test_service”, “service_method”:”test_method”, “service_params”:”test_params”}, {“name”:”supervisor”,”cron”:”/20 * * * *”,”activated”:true, “service_name”:”test_service”, “service_method”:”test_method”, “service_params”:”test_params” }]” }
content_path	N	written at activation / deployment to specify the write folder for the application
service_name	N	comma separated service names, hosted by the application	There may be multiple services implemented in this executable / bundle
service_port	Y if some services are hosted	tcp xml-rpc ports for contacting the services by the admin embedded

3.1.1.3. Process execution environment variables

the application runner / service runner, execute the given process with additional environement variables :

pub const ENV_APPLICATION_CONTENT_PATH: &str = "APPLICATION_CONTENT_PATH";
pub const ENV_APPLICATION_STATUS_PATH: &str = "APPLICATION_STATUS_PATH";
pub const ENV_APPLICATION_DEPLOYMENT_PATH: &str = "APPLICATION_DEPLOYMENT_PATH";

Theses environment variables explain the environement for the executable, ie : the folder where the application can write, save the content, and gives status.

Environment variable description:

Environment variable	Description	Required Permissions
APPLICATION_CONTENT_PATH	Folder for the application to write state IN	Read/Write access required. Application must be able to create, modify, and delete files in this directory.
APPLICATION_STATUS_PATH	File for status reporting	Read/Write access required. Application must be able to create and update this status file. Parent directory must be writable.
APPLICATION_DEPLOYMENT_PATH	Folder of the deployed application	Read-only access required. Application needs to read its deployed resources but should not modify this directory.

Note: Ensure that the running service user (specified in running_user) has the appropriate filesystem permissions for these paths. The service runner will validate permissions during startup.

3.1.1.4. Command description - Schema - Optional extension

Services may describe their own services, using a specific format. This format may be converted in a standard one for interaction.

The file is located in the bundled app, and distributed, using the describe() command

{
  "name": "admin",
  "description": "admin core functionalities, used to manage the node",
  "methods": {
    "execute_command": {
      "name": "execute_command",
      "description": "execute a raw command",
      "parameters": [
        {
          "name": "command",
          "description": "the command to execute",
          "required": true,
          "default_value": null,
          "parameter_type": "string"
        }
      ],
      "returns": "string"
    },
    "activate_app": {
      "name": "activate_app",
      "description": "activate an application",
      "parameters": [
        {
          "name": "application_id",
          "description": "the id of the application",
          "required": true,
          "default_value": null,
          "parameter_type": "string"
        },
        {
          "name": "additional_env_variable",
          "description": "the additional configuration env variable that overload the default ones",
          "required": false,
          "default_value": null,
          "parameter_type": "json:object"
        },
        {
          "name": "managed",
          "description": "if true, the application will be managed by the admin",
          "required": false,
          "default_value": null,
          "parameter_type": "boolean"
        }
      ],
      "returns": "void"
    },
    "get_build_version": {
      "name": "get_build_version",
      "description": "get the build version",
      "parameters": [],
      "returns": "string"
    },
    "deploy_app": {
      "name": "deploy_app",
      "description": "deploy an application",
      "parameters": [
        {
          "name": "app_bundle",
          "description": "the bundle reference of the application",
          "required": true,
          "default_value": null,
          "parameter_type": "string"
        },
        {
          "name": "parameter_only_genuine",
          "description": "if true, the application will be deployed only if the parameter is genuine",
          "required": false,
          "default_value": null,
          "parameter_type": "boolean"
        }
      ],
      "returns": "void"
    },
    "stop_app": {
      "name": "stop_app",
      "description": "stop an application",
      "parameters": [
        {
          "name": "application_id",
          "description": "the id of the application",
          "required": true,
          "default_value": null,
          "parameter_type": "string"
        }
      ],
      "returns": "void"
    },
    "get_application_list": {
      "name": "get_application_list",
      "description": "get the application list",
      "parameters": [],
      "returns": "string"
    },
    "get_machine_id": {
      "name": "get_machine_id",
      "description": "get the machine id",
      "parameters": [],
      "returns": "string"
    },
    "deactivate_app": {
      "name": "deactivate_app",
      "description": "deactivate an application, the application will not be able to be stopped or started. To re-use the application, i'll need to be re-activated",
      "parameters": [
        {
          "name": "application_id",
          "description": "the id of the application",
          "required": true,
          "default_value": null,
          "parameter_type": "string"
        }
      ],
      "returns": "void"
    },
    "list_services": {
      "name": "list_services",
      "description": "list all the services",
      "parameters": [],
      "returns": "json"
    },
    "get_app_status": {
      "name": "get_app_status",
      "description": "get the status of an application",
      "parameters": [],
      "returns": "json"
    },
    "send_event": {
      "name": "send_event",
      "description": "send an event",
      "parameters": [
        {
          "name": "sender",
          "description": "the sender of the event",
          "required": true,
          "default_value": null,
          "parameter_type": "string"
        },
        {
          "name": "event_name",
          "description": "the name of the event",
          "required": true,
          "default_value": null,
          "parameter_type": "string"
        },
        {
          "name": "event_data",
          "description": "the data of the event",
          "required": false,
          "default_value": null,
          "parameter_type": "json:object"
        }
      ],
      "returns": "void"
    },
    "call_service": {
      "name": "call_service",
      "description": "call a service on an application",
      "parameters": [
        {
          "name": "service_name",
          "description": "the name of the service to call",
          "required": true,
          "default_value": null,
          "parameter_type": "string"
        },
        {
          "name": "method_name",
          "description": "the name of the method to call",
          "required": true,
          "default_value": null,
          "parameter_type": "string"
        },
        {
          "name": "parameters",
          "description": "the parameters of the method to call",
          "required": false,
          "default_value": null,
          "parameter_type": "json"
        }
      ],
      "returns": "any"
    },
    "undeploy_app": {
      "name": "undeploy_app",
      "description": "undeploy an application",
      "parameters": [
        {
          "name": "application_id",
          "description": "the id of the application",
          "required": true,
          "default_value": null,
          "parameter_type": "string"
        }
      ],
      "returns": "void"
    },
    "start_app": {
      "name": "start_app",
      "description": "start an application that is deployed",
      "parameters": [
        {
          "name": "application_id",
          "description": "the id of the application",
          "required": true,
          "default_value": null,
          "parameter_type": "string"
        },
        {
          "name": "managed",
          "description": "if true, the application will be managed by the admin",
          "required": false,
          "default_value": null,
          "parameter_type": "boolean"
        }
      ],
      "returns": "void"
    },
    "reset_factory": {
      "name": "reset_factory",
      "description": "reset to factory setup, this means all the saved data will be erased, before the reset",
      "parameters": [
        {
          "name": "reset_factory_configuration",
          "description": "the path to the command file, that initialize the node",
          "required": true,
          "default_value": null,
          "parameter_type": "string"
        }
      ],
      "returns": "void"
    }
  }
}