# Service Plugin Specifications

Document Version	Content Revision	Reviser	Revision Date
V1.0	Added basic content for plugin specifications	Wang Yao	2023-11-25
V1.1	Added description for Hooks	Wang Yao	2024-01-12
V1.2	Added description for visual configuration standards	Guochenghao	2024-02-22

# Basic Requirements

There are no strict programming language requirements for service plugins; you can choose an appropriate programming language. However, please pay attention to the following points:

The program should run directly on the target device. If it relies on a runtime environment, it should operate normally once the environment is configured.
Avoid relying on the system's dynamic link libraries. If system dynamic link libraries are used, ensure that the corresponding libraries are also installed on the target device.
If the program depends on dynamic libraries, it can use relative paths to place the dynamic library alongside the program.
If the program is written in a compiled language (e.g., C, C++, Go), it needs to be compiled into an executable file.
If the program is written in an interpreted language (e.g., Python, JS, Java), it needs to declare the interpreter type or package the interpreter together with the program.
The program and its necessary dependencies must be grouped together.
Service management only supports computers running Windows, Linux, and macOS; it does not support mobile platforms (Android, iOS).
It supports running service management on domestic operating systems, such as Kylin and UOS.
Programs with a GUI (e.g., WPF, Qt, Unity) are not supported.
If it's a B/S architecture program, it's feasible to internally provide a web service on the server.
Services running in nohup mode are not supported.

# Program Development Recommendations

It is recommended to store program data in the user directory or the program’s relative directory, rather than an absolute path.
Programs can access the current user directory using HOME or USERPROFILE.
If the configuration and data files are stored in a relative path, they need to be declared in the description file's datas field to prevent them from being overwritten during program updates.
It is advisable to capture program termination signals to save relevant data and close file connections before the program ends, to prevent data file corruption.
If the program requires a longer time to process the finalization tasks, please adjust the stop_timeout duration to ensure there is ample time to handle this, otherwise, if the program takes too long to stop, it will be considered unresponsive, triggering forced termination logic.
The program may enable any number of subprocesses, but it should not start processes that do not have a parent-child relationship with the main process. If service management cannot accurately determine the subprocess's relationship, it may fail to terminate the process correctly.
The program should not run in nohup mode.
The program does not need to set up process guardians, as service management itself comes with process guardian functionality.

# Plugin Description Specification daemon.json

Complete example of a description file:

{
  "id": "",
  "interpreter": "node",
  "interpreter_self": "",
  "interpreter_args": [],
  "path": "./ccs_pro.js",
  "pkg": "com.sansi.ccs-pro",
  "version": "2.2.27",
  "log_file": "",
  "pid_file": "",
  "icon": "favicon.ico",
  "name": "Universal Central Control",
  "description": "Universal Central Control System (CCS Pro)",
  "args": [],
  "auto_start": true,
  "auto_restart": true,
  "restart_max": 3,
  "restart_delay": 0,
  "cwd": "",
  "env_vars": [],
  "port": 3436,
  "port_type": "HTTP",
  "os": "",
  "arch": "",
  "is_match": true,
  "stop_timeout": 5000,
  "doc": "https://ccs-pro.sansi.io/",
  "api_doc": "http://{{currentIp}}:{{currentPort}}/docs/api/",
  "homepage": "http://{{currentIp}}:{{currentPort}}",
  "configs": [
    {
      "title": "Server Configuration",
      "type": "json",
      "path": "{{home}}/Sansi/CCS-Platform/config/ccs-server.json",
      "schema": "{{app}}/config/ccs-server.schema.zh_CN.json"
    },
    {
      "title": "Client Configuration",
      "type": "json",
      "path": "{{home}}/Sansi/CCS-Platform/config/ccs-editor.json",
      "schema": "{{app}}/config/ccs-editor.schema.zh_CN.json"
    }
  ],
  "gateway": [
    {
      "enable": true,
      "gateWayType": "HTTP",
      "apiPath": "http://127.0.0.1:3436",
      "apiPrefix": "/sansi/ccs",
      "removePrefix": false
    }
  ],
  "datas": [
    "{{app}}/date/*", "{{app}}/config/app.json"
  ],
  "logs": [
    "{{app}}/logs/*"
	],
  "firewall_enable": true,
  "firewall_ports": [
    "3436"
  ],
  "hooks": [
  	{
  		"type": "HTTP",
  		"stage": "PreStop",
  		"timeout": 10000,
  		"data": {
				"http": {
					"method": "GET",
					"url": "http://{{currentIp}}:{{currentPort}}/test"
				}
  		}
  	},
    {
      "type": "HTTP",
      "stage": "PreUnInstall",
      "timeout": 10000,
      "data": {
        "http": {
          "method": "GET",
          "url": "http://127.0.0.1:1280/sansi/daemon/api/v1/daemon/config"
        }
      }
    }
  ]
}

# Field Descriptions

Field Name (json)	Field Type	Default Value	Reference Values	Field Description
id	string		QwOUYfIY	Program ID (auto-generated, cannot be modified through config update)
interpreter	string		node / java / python	Interpreter, such as python3, node, java, can be empty
interpreter_self	string		./bin/node.exe	Self-provided interpreter for the service
interpreter_args	[]string	[]	["-jar","-Dfile.encoding=utf-8"]	Arguments for the interpreter
path	string		./app.js	Program path (cannot be modified through config update)
pkg	string		com.sansi.demo	Unique identifier for the program
version	string	"1.0.0"	1.0.0	Program version number (cannot be modified through config update)
log_file	string	"/logs.log"	""	Log file location (cannot be customized or modified through config update)
pid_file	string	"/pid"	""	PID file (cannot be customized or modified through config update)
icon	string		./icon.png	Program icon
name	string		XX Service	Program name
description	string		Service providing XX functionality	Program description
args	[]string	[]	["--port", "8080"]	Program arguments
auto_start	*bool	true	true	Automatically start; this application will start automatically after install and daemon startup
auto_restart	*bool	true	true	Automatically restart
restart_max	*int	3	3	Maximum restart attempts; 0 means unlimited
restart_delay	*int	0	1000	Restart delay time, in milliseconds
cwd	string		"./"	Program working directory
env_vars	[]string	[]	["KEY=sdfsdfsss"]	Environment variables
port	int		3436	Running port
port_type	string		HTTP / TCP / UDP / Websocket	Type of the running port
os	string		"" / windows / linux / darwin	Supported operating systems; if empty indicates no OS restrictions
arch	string		"" / amd64 / arm64	Supported CPU architecture; if empty indicates no architecture restrictions (amd64 implies the same as x64, x86-64 cannot be written as x64)
is_match	bool		true	Whether the operating system and architecture are compatible (calculated automatically, no setup needed)
stop_timeout	*int	5000	0	Timeout duration when stopping the service, in milliseconds
doc	string		https://ccs-pro.sansi.io/	Documentation for the current service; can use currentPort to represent the current service's IP and currentPort for its port
api_doc	string		https://ccs-pro.sansi.io/	API documentation for the current service; similar usage for currentPort
homepage	string		https://ccs-pro.sansi.io/	Home page address for the current service; similar usage for currentPort
configs	[]Config	[]	See the above example	List of program configuration information; can use app to represent current program directories, and home to represent user directories accessible to the program.
datas	[]string	[]	["/data/*", "/config/conf.json"]	List of data for the current program; this directory will be retained during program upgrades. Suitable for programs and data located in relative paths.
logs	[]string	[]	["/logs/*"]	List of logs for the current program; this directory will also be retained during upgrades, suitable for programs and logs located in relative paths.
firewall_enable	bool	true	true	Whether to enable the firewall
firewall_ports	[]string	[]	["1234", "3456-3467", "8033"]	Open ports for the firewall, inbound direction
hooks	[]Hook	[]	See the above example	Callback properties for various stages of service operation

# Gateway

The gateway is used to apply for request proxies in Xuandao Intelligent Control, without exposing the real address to the outside world. Each service can apply for multiple gateway proxies.

In the entire Xuandao Intelligent Control platform, all gateway prefixes must be unique.

{
  "gateway": [
    {
      "enable": true,
      "gateWayType": "HTTP",
      "apiPath": "http://127.0.0.1:3436",
      "apiPrefix": "/sansi/ccs",
      "removePrefix": false
    }
  ]
}

Field Descriptions

Field	Type	Meaning	Supported Parameters
enable	bool	Whether to enable the gateway	true / false
gateWayType	string	Gateway type	HTTP、WebSocket
apiPath	string	Real address
removePrefix	bool	Whether to remove the prefix

# Hooks

Hooks are callback properties for the various stages of service operation. Currently, they only support HTTP calls. Note that in their URLs, the fields and are supported, where currentIp represents the IP address of the current service, and currentPort represents the currently opened port of the service.

A single hook entry looks like this:

{
  "type": "HTTP",
  "stage": "PreStop",
  "timeout": 10000,
  "data": {
    "http": {
      "method": "GET",
      "url": "http://{{currentIp}}:{{currentPort}}/test"
    }
  }
}

Field Descriptions

Field	Type	Meaning	Supported Parameters
type	string	Hook type	HTTP
stage	int	Hook stage	PreInstall, PostInstall, PreUnInstall, PostUnInstall, PreStart, PostStart, PreStop, PostStop, PreBackup, PostBackup, PreRestore, PostRestore
timeout	int	Timeout duration for this stage (milliseconds)	Less than or equal to 0 will take the default value of 10 seconds
data	HookData	Hook data	See below
data.http	HookDataHttp	HTTP type data	Currently does not support calls with a body
data.http.method	string	Request method	GET, POST, PUT, DELETE
data.http.url	string	Request address	Supports and fields; currentIp represents the IP address of the current service, and currentPort represents the currently opened port of the service

# Visual Configuration Specification schema.zh_CN.json

Below is the configuration file for the server.

Effect of the visualized backend.

Use schema.zh_CN.json to explain the fields in the configuration file.

schema.zh_CN.json 示例

[
  {
    "props": {
      "header": "Central Control Server"
    },
    "formProps": {
      "labelWidth": "100px"
    },
    "fields": [
      {
        "name": "auth_enable",
        "component": "switch",
        "formProps": {
          "label": "Enable User Authentication:"
        },
        "inputProps": {}
      },
      {
        "name": "database",
        "component": "select",
        "formProps": {
          "label": "Authentication Method:"
        },
        "inputProps": {
          "options": [
            {
              "label": "Built-in Database",
              "value": "nedb"
            },
            {
              "label": "User Authentication Service",
              "value": "oauth"
            }
          ]
        }
      },
      {
        "name": "oauth_url",
        "component": "input",
        "formProps": {
          "label": "User Authentication Service:"
        },
        "inputProps": {}
      }
    ]
  }
]

Edit daemon.json，load schema.zh_CN.json file

The directory structure is as follows:

Default Parser Types:

component	Supported Field Properties	Description
input	string	Text input box
link	string	Link
select	string	Content selector (single choice)
switch	boolean	Switch button
date-picker	string	Date picker
time-picker	string	Time picker
color-picker	string	Color picker
rate	number	Rating

← Quick Start