Agent Service (GA)

Agent Service (abbreviated as GA Service) is a core component deployed on the user's server, responsible for handling application management, command execution, and process communication functions.

Service Overview

Service Features

• Deployment Location: User's server locally
• Communication Protocol: HTTP API + JSON-RPC 2.0
• Security: Local file socket communication
• Performance: Low-latency, high-efficiency inter-process communication

API Interface Specification

Response Format

All API interfaces follow a unified response format:

Field	Type	Description
code	number	Status code, success is 200000, failure is non-200000
data	any	Response data
meta	object	Metadata information
msg	string	Response message (English)

API Interface Details

1. Execute Command

Endpoint: /api/command/exec_shell

SDK Support

This method is already encapsulated in the Frontend SDK and can be called directly.

Request Parameters:

{
    "cmd_string": "cat .bashrc",
    "timeout": "1",
    "cwd": "/root",
    "username": "root"
}

Parameter Description:

Parameter	Type	Required	Description
cmd_string	string	Yes	Command string to execute, supports raw command or base64 encoded command
timeout	string	Yes	Command execution timeout (seconds)
cwd	string	No	Working directory for command execution, default is /.__gmssh/bin
username	string	Yes	Username for command execution

Response Example:

{
    "code": 200000,
    "data": "# .bashrc content here...",
    "meta": {
        "close": 0,
        "endpoint": "/api/command/exec_shell"
    },
    "msg": "Successful operation"
}

2. Get Process Port

Endpoint: /api/command/get_process_port

Request Parameters:

{
    "process_name": "test"
}

Parameter Description:

Parameter	Type	Required	Description
process_name	string	Yes	Process name

Response Example:

{
    "code": 200000,
    "data": {
        "port": 17766,
        "pid": 17764
    },
    "meta": {
        "close": 0,
        "endpoint": "/api/command/get_process_port"
    },
    "msg": "Successful operation"
}

3. Execute Script Content

Endpoint: /api/command/exec_script

Request Parameters:

{
    "script": "ZWNobyBoZWxsbw==",
    "timeout": "5"
}

Parameter Description:

Parameter	Type	Required	Description
script	string	Yes	Base64 encoded script content
timeout	string	Yes	Script execution timeout (seconds)

Response Example:

{
    "code": 200000,
    "data": "hello",
    "meta": {
        "close": 0,
        "endpoint": "/api/command/exec_script"
    },
    "msg": "Successful operation"
}

Execution Method Difference

• Execute Command: Equivalent to executing a command in the terminal
• Execute Script: Directly execute script file content

4. Application Status Check

Endpoint: /api/center/check_status

SDK Support

This method is already encapsulated in the Frontend SDK and can be called directly.

Request Parameters:

{
    "app_name": "official/omc",
    "version": "1.0.0",
    "communication_type": "http"
}

Parameter Description:

Parameter	Type	Required	Description
app_name	string	Yes	Application name, format: {org-name}/{app-name}
version	string	Yes	Application version number
communication_type	string	Yes	Communication type: http or socket

5. External Application Access Interface

Endpoint: /api/call/{org-name}/{app-name}/{interface-name}

Request Parameters:

{
    "version": "1.0.0",
    "transport": "http",
    "params": {
        "lang": "zh-CN"
    }
}

Parameter Description:

Parameter	Type	Required	Description
version	string	Yes	External application version number
transport	string	Yes	Communication type: http or socket
params	object	No	Parameters passed to the external application

Response Example:

{
    "code": 200000,
    "data": {
        "code": 200,
        "data": "hello world!",
        "msg": "Operation successful"
    },
    "meta": {
        "close": 0,
        "endpoint": "/api/call/*"
    },
    "msg": "Successful operation"
}

6. Get Files and Directories

Endpoint: api/files/get_dir

Request Parameters:

{
    "path": "/",
    "search": "",
    "all": "",
    "reverse": "False",
    "sort": "name",
    "showRow": 9999,
    "window_id": ""
}

Parameter Description:

Parameter	Type	Required	Description
path	string	Yes	Directory path, e.g., "/" for root directory
search	string	No	Search keyword for filtering file names
all	string	No	Whether to show all files
reverse	string	No	Reverse order, "True" or "False"
sort	string	No	Sort method: "name", "size", "time"
showRow	number	No	Display row limit, default 9999 (max)
window_id	string	No	Window ID identifier

7. Create File

Endpoint: /api/files/create_file

Request Parameters:

{
    "path": "/demo.txt"
}

Parameter Description:

Parameter	Type	Required	Description
path	string	Yes	Absolute file path

8. Delete File

Endpoint: /api/files/delete_file

Request Parameters:

{
    "path": "/demo.txt"
}

9. Create Directory

Endpoint: /api/files/create_dir

Request Parameters:

{
    "path": "/demo"
}

10. Delete Directory

Endpoint: /api/files/delete_dir

Request Parameters:

{
    "path": "/demo"
}

11. Read File Content

Endpoint: /api/files/read_file_body

Request Parameters:

{
    "path": "/demo.txt",
    "auto_create": "0"
}

Parameter Description:

Parameter	Type	Required	Description
path	string	Yes	Absolute file path
auto_create	string	Yes	Auto-create file, 0 = no, 1 = yes

12. Rename File/Directory

Endpoint: /api/files/mv_file

Request Parameters:

{
    "sfile": "/demo.txt",
    "dfile": "/example.txt",
    "rename": true
}

Parameter Description:

Parameter	Type	Required	Description
sfile	string	Yes	Old file absolute path
dfile	string	Yes	New file absolute path
rename	bool	Yes	If false, force move (delete if new file exists)

13. Copy File/Directory

Endpoint: /api/files/copy_file

Request Parameters:

{
    "sfile": "/demo",
    "dfile": "/example"
}

JSON-RPC Interface Specification

GA Service also provides JSON-RPC 2.0 interfaces based on Unix Domain Socket, supporting high-performance local inter-process communication.

Connection Method

Unix Socket File Path:

/.__gmssh/tmp/rpc.sock

Protocol Specification

• Protocol Version: JSON-RPC 2.0
• Transport Protocol: Unix Domain Socket
• Data Format: JSON
• Character Encoding: UTF-8

Request Format

{
    "jsonrpc": "2.0",
    "method": "method_name",
    "params": {
        "param1": "value1",
        "param2": "value2"
    },
    "id": 1
}

Field Description:

Field	Type	Required	Description
jsonrpc	string	Yes	Protocol version, fixed as "2.0"
method	string	Yes	Method name to call
params	object/array	No	Method parameters
id	number/string	Yes	Request identifier for matching responses

JSON-RPC Interface Details

1. Log Report Interface (Important)

Method Name: log_report

Request Parameters:

{
    "plugin_name": "user",
    "plugin_name_des": "User Module",
    "fn_name": "add_user",
    "fn_name_des": "Add User",
    "data": data,
    "o_name": "New user: xxx"
}

Parameter Description:

Parameter	Type	Required	Description
plugin_name	string	Yes	Plugin name
plugin_name_des	string	Yes	Plugin name description
fn_name	string	Yes	Function name
fn_name_des	string	Yes	Function name description
data	string	Yes	Request data
o_name	string	Yes	Operation details

Environment Variables

IsClean

Scope: Only available in the application's uninstall.sh script

Value Description:

• true: User chose to clear application data
• false: User chose to keep application data

Usage Example:

#!/bin/bash

if [ "$IsClean" = "true" ]; then
    echo "Clearing application data..."
    rm -rf ./data/
    rm -rf ./config/
else
    echo "Keeping application data"
fi

Best Practices

• Always check the IsClean environment variable in uninstall scripts
• Handle data cleanup logic appropriately based on user choice
• Add appropriate log output for troubleshooting