# API Documentation

All API responses are returned in JSON format:

**Success Response:**
```json
{
  "success": true,
  "message": "success message",
  "data": { ... }
}
```

**Error Response:**
```json
{
  "success": false,
  "message": "error message"
}
```

**Important Notes:**
- For all requests: Authentication token and timestamp are sent in HTTP headers (prefixed with `X-`)
- For **POST** requests: Other data is sent in the request body as JSON
- For **GET** requests: All data is sent in HTTP headers (prefixed with `X-`)
- All requests require authentication (except `/register`, `/login`, `/system/getStatus`, `/system/getSoftwareInfo`)
- Timestamps are in milliseconds (Unix timestamp)

---

## Get System Status

**Endpoint:** `/system/getStatus`  
**Method:** GET  
**Auth Required:** No  
**Permission Level:** None

Get the current system status.

**Response:**
```json
{
  "success": true,
  "message": "getStatus",
  "data": {
    "Status": "Online"
  }
}
```

| Field | Type | Description |
|-------|------|-------------|
| Status | string | System status: "Online" or "Offline" |

---

## Get Software Info

**Endpoint:** `/system/getSoftwareInfo`  
**Method:** GET  
**Auth Required:** No  
**Permission Level:** None

Get software version and build information.

**Response:**
```json
{
  "success": true,
  "message": "getSoftwareInfo",
  "data": {
    "Name": "Super-frpc",
    "Version": "0.0.1",
    "Developer": "Madobi Nanami",
    "BuildVer": 1,
    "Description": "",
    "BuildType": "debug"
  }
}
```

| Field | Type | Description |
|-------|------|-------------|
| Name | string | Software name |
| Version | string | Software version |
| Developer | string | Developer name |
| BuildVer | int16 | Build version number |
| Description | string | Software description |
| BuildType | string | Build type: "debug" or "release" |

---

## Register User

**Endpoint:** `/register`  
**Method:** POST  
**Content-Type:** application/json
**Permission Level:** None

**Request Headers:**
```
X-Timestamp: 1704067200000
```

**Request Body:**
```json
{
  "username": "your_username",
  "passwd": "YourPass123!"
}
```

| Header | Type | Required | Description |
|--------|------|----------|-------------|
| X-Timestamp | int64 | Yes | Client timestamp in milliseconds |

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| username | string | Yes | Username (no special characters) |
| passwd | string | Yes | Password (must contain uppercase, lowercase, digit, and special character, min 8 chars) |
| type | string | No | User type: superuser, admin, visitor (default: visitor) |

**Response:**
```json
{
  "success": true,
  "message": "user registered successfully",
  "data": {
    "userID": 1,
    "username": "your_username",
    "type": "admin"
  }
}
```
> New user only can register as visitor, superuser and admin need to contact the administrator to apply.

---

## Login

**Endpoint:** `/login`  
**Method:** POST  
**Content-Type:** application/json  
**Permission Level:** None

**Request Headers:**
```
X-Timestamp: 1704067200000
```

**Request Body:**
```json
{
  "username": "your_username",
  "passwd": "YourPass123!"
}
```

| Header | Type | Required | Description |
|--------|------|----------|-------------|
| X-Timestamp | int64 | Yes | Client timestamp in milliseconds |

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| username | string | Yes | Username |
| passwd | string | Yes | Password |

**Response:**
```json
{
  "success": true,
  "message": "login successful",
  "data": {
    "token": "xxxxxxxxxxxxx",
    "userID": 1,
    "username": "your_username",
    "type": "admin"
  }
}
```

---

## Logout

**Endpoint:** `/logout`  
**Method:** GET  
**Auth Required:** Yes (token)
**Permission Level:** None

**Request Headers:**
```
X-Token: your_token
X-Timestamp: 1704067200000
```
| Header | Type | Required | Description |
|--------|------|----------|-------------|
| X-Token | string | Yes | Authentication token |
| X-Timestamp | int64 | Yes | Client timestamp in milliseconds |

**Response:**
```json
{
  "success": true,
  "message": "Logout successful"
}
```

---

## Create User

**Endpoint**: `/userMgr/create`  
**Method**: POST  
**Content-Type**: application/json  
**Auth Required**: Yes (token)  
**Permission Level**: Superuser

**Request Headers**:
```
X-Token: your_token
X-Timestamp: 1704067200000
```

**Request Body**:
```json
{
  "username": "new_user",
  "passwd": "NewPass123!",
  "type": "admin"
}
```

**Response**:
```json
{
  "success": true,
  "message": "User created successfully",
  "data": {
    "userID": 2,
    "username": "new_user",
    "type": "admin"
  }
}
```

---

## Remove User

**Endpoint**: `/userMgr/remove`  
**Method**: POST  
**Content-Type**: application/json  
**Auth Required**: Yes (token)  
**Permission Level**: Superuser

**Request Headers**:
```
X-Token: your_token
X-Timestamp: 1704067200000
```

**Request Body**:
```json
{
  "targetUserID": 2
}
```

**Response**:
```json
{
  "success": true,
  "message": "User removed successfully"
}
```

---

## List Users

**Endpoint**: `/userMgr/list`  
**Method**: GET  
**Auth Required**: Yes (token)  
**Permission Level**: Superuser

**Request Headers**:
```
X-Token: your_token
X-Timestamp: 1704067200000
```

**Response**:
```json
{
  "success": true,
  "message": "User list retrieved successfully",
  "data": [
    {
      "UserID": 1,
      "Username": "admin",
      "Passwd": "",
      "Type": "superuser",
      "CreatedAt": "2024-01-01 12:00:00"
    },
    {
      "UserID": 2,
      "Username": "new_user",
      "Passwd": "",
      "Type": "admin",
      "CreatedAt": "2024-01-02 14:30:00"
    }
  ]
}
```

| Field | Type | Description |
|-------|------|-------------|
| UserID | int | User ID |
| Username | string | Username |
| Type | string | User type: superuser, admin, visitor |
| CreatedAt | string | User creation time (YYYY-MM-DD HH:MM:SS format) |

---

## List Active Sessions

**Endpoint**: `/sessionMgr/list`  
**Method**: GET  
**Auth Required**: Yes (token)  
**Permission Level**: Superuser, Admin

**Request Headers**:
```
X-Token: your_token
X-Timestamp: 1704067200000
```

| Header | Type | Required | Description |
|--------|------|----------|-------------|
| X-Token | string | Yes | Authentication token |
| X-Timestamp | int64 | Yes | Client timestamp in milliseconds |

**Response**:
```json
{
  "success": true,
  "message": "Active sessions listed",
  "data": [
    {
      "ID": "session-5f4dcc3b5aa765d61d8327deb882cf99-1704067200000",
      "UserID": 1,
      "Username": "admin",
      "ExpireAt": "2024-01-01T01:00:00Z"
    },
    {
      "ID": "session-7c6a180b36896a0a8c010710c0780347-1704067210000",
      "UserID": 2,
      "Username": "new_user",
      "ExpireAt": "2024-01-01T01:00:10Z"
    }
  ]
}
```

| Field | Type | Description |
|-------|------|-------------|
| ID | string | Unique session ID |
| UserID | int | User ID |
| Username | string | Username |
| ExpireAt | string | Session expiration time (ISO 8601 format) |

---

## Remove Session

**Endpoint**: `/sessionMgr/remove`  
**Method**: POST  
**Content-Type**: application/json  
**Auth Required**: Yes (token)  
**Permission Level**: Superuser

**Request Headers**:
```
X-Token: your_token
X-Timestamp: 1704067200000
```

**Request Body**:
```json
{
  "sessionID": "session-5f4dcc3b5aa765d61d8327deb882cf99-1704067200000"
}
```

| Header | Type | Required | Description |
|--------|------|----------|-------------|
| X-Token | string | Yes | Authentication token |
| X-Timestamp | int64 | Yes | Client timestamp in milliseconds |

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| sessionID | string | Yes | Session ID to remove |

**Response**:
```json
{
  "success": true,
  "message": "Session removed successfully"
}
```

> **Note**: This endpoint requires superuser permission. It removes a session by its sessionID and also removes the associated token, forcing the user to re-login.

---

## Create frpc Instance

**Endpoint:** `/frpcAct/instanceMgr/create`  
**Method:** POST  
**Content-Type:** application/json  
**Auth Required:** Yes (token)  
**Permission Level:** Admin

**Request Headers:**
```
X-Token: your_token
X-Timestamp: 1704067200000
```

**Request Body:**
```json
{
  "instanceInfo": {
    "name": "my_frpc",
    "serverAddr": "127.0.0.1",
    "serverPort": "7000",
    "auth_method": "token"
  },
  "bootAtStart": true,
  "runUser": "root",
  "additionalProperties": {
    "pool_count": 5
  }
}
```

| Header | Type | Required | Description |
|--------|------|----------|-------------|
| X-Token | string | Yes | Authentication token |
| X-Timestamp | int64 | Yes | Client timestamp in milliseconds |

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| instanceInfo.name | string | Yes | Instance name |
| instanceInfo.serverAddr | string | Yes | frps server address |
| instanceInfo.serverPort | string | Yes | frps server port |
| instanceInfo.auth_method | string | Yes | Authentication method |
| bootAtStart | bool | No | Auto-start on system boot (default: false) |
| runUser | string | No | Run as user (default: root) |
| additionalProperties | object | No | Additional frpc configuration |

**Response:**
```json
{
  "success": true,
  "message": "instance created successfully",
  "data": {
    "name": "my_frpc",
    "configPath": "./configs/superfrpc_user_my_frpc.toml",
    "bootAtStart": true
  }
}
```

---

## Delete frpc Instance

**Endpoint:** `/frpcAct/instanceMgr/delete`  
**Method:** POST  
**Content-Type:** application/json  
**Auth Required:** Yes (token)  
**Permission Level:** Admin

**Request Headers:**
```
X-Token: your_token
X-Timestamp: 1704067200000
```

**Request Body:**
```json
{
  "instanceID": "1"
}
```

| Header | Type | Required | Description |
|--------|------|----------|-------------|
| X-Token | string | Yes | Authentication token |
| X-Timestamp | int64 | Yes | Client timestamp in milliseconds |

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| instanceID | string | Yes | Instance ID (the ID of the frpc instance) |

**Response:**
```json
{
  "success": true,
  "message": "instance deleted successfully",
  "data": {
    "instanceID": 1,
    "name": "my_frpc"
  }
}
```

| Field | Type | Description |
|-------|------|-------------|
| instanceID | int | Instance ID |
| name | string | Name of the deleted frpc instance |

---

## Modify frpc Instance

**Endpoint:** `/frpcAct/instanceMgr/modify`  
**Method:** POST  
**Content-Type:** application/json  
**Auth Required:** Yes (token)  
**Permission Level:** Admin

Modify instance configuration. Supports two modification types: `configFile` (modify frpc config file) and `systemConfig` (modify system-level settings).

**Request Headers:**
```
X-Token: your_token
X-Timestamp: 1704067200000
```

### Type 1: Modify Config File (configFile)

Modify fields in the `[common]` section of the frpc configuration file. Only `[common]` section fields can be modified, `[[proxies]]` sections will not be affected.

**Request Body:**
```json
{
  "instanceID": "1",
  "type": "configFile",
  "modifiedData": {
    "server_addr": "192.168.1.1",
    "server_port": "7000",
    "auth_method": "token",
    "auth_token": "my_secret_token"
  }
}
```

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| instanceID | string | Yes | Instance ID (the ID of the frpc instance) |
| type | string | Yes | Modification type: `configFile` or `systemConfig` |
| modifiedData | object | Yes | Key-value pairs of fields to modify in `[common]` section |

**Response:**
```json
{
  "success": true,
  "message": "Config file modified successfully",
  "data": {
    "instanceID": 1,
    "configPath": "./configs/superfrpc_user_my_frpc.toml"
  }
}
```

### Type 2: Modify System Config (systemConfig)

Modify system-level settings such as instance name, boot-at-start configuration, and run user. These changes will also update the operating system service configuration.

**Request Body:**
```json
{
  "instanceID": "1",
  "type": "systemConfig",
  "modifiedData": {
    "name": "new_frpc_name",
    "bootAtStart": true,
    "runUser": "www-data"
  }
}
```

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| instanceID | string | Yes | Instance ID (the ID of the frpc instance) |
| type | string | Yes | Modification type: `configFile` or `systemConfig` |
| modifiedData.name | string | No | New instance name (renames config file if changed) |
| modifiedData.bootAtStart | bool | No | Auto-start on system boot |
| modifiedData.runUser | string | No | User to run the frpc instance as |

**Response:**
```json
{
  "success": true,
  "message": "System config modified successfully",
  "data": {
    "instanceID": 1,
    "configPath": "./configs/superfrpc_user_new_frpc_name.toml",
    "bootAtStart": true,
    "runUser": "www-data"
  }
}
```

**Response with bootServiceError (when boot service operations fail):**
```json
{
  "success": true,
  "message": "System config modified successfully",
  "data": {
    "instanceName": "new_frpc_name",
    "instanceID": 1,
    "configPath": "./configs/superfrpc_user_new_frpc_name.toml",
    "bootAtStart": true,
    "runUser": "www-data",
    "bootServiceError": "Failed to create boot service: unsupported init system"
  }
}
```

> **Note about bootServiceError:**
> - The `bootServiceError` field appears in the response when boot service operations (create/remove) fail
> - This field is only present when there is an error; it will not be included in the response if operations succeed
> - The overall request still returns `success: true` because the system config modification (database update, config file rename, etc.) succeeded
> - Common scenarios where `bootServiceError` may appear:
>   - Enabling `bootAtStart` when the init system is not supported (e.g., on Windows or systems without systemd/init.d)
>   - Disabling `bootAtStart` when the service file cannot be removed due to permission issues
>   - Changing instance name or run user when `bootAtStart` is enabled (requires removing old service and creating new one)
> - The error message provides detailed information about what went wrong, which should be displayed to the user
> - Frontend applications should check for this field and display the error message to the user, even though the request was technically successful

---

## Start frpc Instance

**Endpoint:** `/frpcAct/instanceMgr/start`  
**Method:** POST  
**Content-Type:** application/json  
**Auth Required:** Yes (token)  
**Permission Level:** Admin

Start a frpc instance. The instance can be started as a background process on Windows (hidden window) or as a systemd/init.d service on Linux.

**Request Headers:**
```
X-Token: your_token
X-Timestamp: 1704067200000
```

**Request Body:**
```json
{
  "instanceID": "1"
}
```

| Header | Type | Required | Description |
|--------|------|----------|-------------|
| X-Token | string | Yes | Authentication token |
| X-Timestamp | int64 | Yes | Client timestamp in milliseconds |

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| instanceID | string | Yes | ID of the instance to start |

**Response (Windows):**
```json
{
  "success": true,
  "message": "Instance started successfully",
  "data": {}
}
```

**Response (Linux systemd):**
```json
{
  "success": true,
  "message": "Instance started successfully",
  "data": {}
}
```

**Response (Linux init.d):**
```json
{
  "success": true,
  "message": "Instance started successfully",
  "data": {}
}
```

---

## Stop frpc Instance

**Endpoint:** `/frpcAct/instanceMgr/stop`  
**Method:** POST  
**Content-Type:** application/json  
**Auth Required:** Yes (token)  
**Permission Level:** Admin

Stop a running frpc instance. On Windows, this stops the frpc process. On Linux, this stops the systemd/init.d service.

**Request Headers:**
```
X-Token: your_token
X-Timestamp: 1704067200000
```

**Request Body:**
```json
{
  "instanceID": "1"
}
```

| Header | Type | Required | Description |
|--------|------|----------|-------------|
| X-Token | string | Yes | Authentication token |
| X-Timestamp | int64 | Yes | Client timestamp in milliseconds |

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| instanceID | string | Yes | ID of the instance to stop |

**Response (Windows):**
```json
{
  "success": true,
  "message": "Instance stopped successfully",
  "data": {}
}
```

**Response (Linux systemd):**
```json
{
  "success": true,
  "message": "Instance stopped successfully",
  "data": {}
}
```

**Response (Linux init.d):**
```json
{
  "success": true,
  "message": "Instance stopped successfully",
  "data": {}
}
```

---

## Restart frpc Instance

**Endpoint:** `/frpcAct/instanceMgr/restart`  
**Method:** POST  
**Content-Type:** application/json  
**Auth Required:** Yes (token)  
**Permission Level:** Admin

Restart a frpc instance. This stops and then starts the instance again.

**Request Headers:**
```
X-Token: your_token
X-Timestamp: 1704067200000
```

**Request Body:**
```json
{
  "instanceID": "1"
}
```

| Header | Type | Required | Description |
|--------|------|----------|-------------|
| X-Token | string | Yes | Authentication token |
| X-Timestamp | int64 | Yes | Client timestamp in milliseconds |

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| instanceID | string | Yes | ID of the instance to restart |

**Response (Windows):**
```json
{
  "success": true,
  "message": "Instance restarted successfully",
  "data": {}
}
```

**Response (Linux systemd):**
```json
{
  "success": true,
  "message": "Instance restarted successfully",
  "data": {}
}
```

**Response (Linux init.d):**
```json
{
  "success": true,
  "message": "Instance restarted successfully",
  "data": {}
}
```

---

## Get frpc Instance Status

**Endpoint:** `/frpcAct/instanceMgr/status`  
**Method:** GET  
**Auth Required:** Yes (token)  
**Permission Level:** Visitor

Check the running status of a frpc instance.

**Request Headers:**
```
X-Token: your_token
X-Timestamp: 1704067200000
```

**Query Parameters:**
```
instanceID=1
```

| Header | Type | Required | Description |
|--------|------|----------|-------------|
| X-Token | string | Yes | Authentication token |
| X-Timestamp | int64 | Yes | Client timestamp in milliseconds |

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| instanceID | string | Yes | ID of the instance to check |

**Response (running):**
```json
{
  "success": true,
  "message": "Instance status retrieved successfully",
  "data": {
    "name": "my_frpc",
    "initSystem": "systemd",
    "serviceName": "superfrpc_admin_my_frpc",
    "isRunning": true
  }
}
```

**Response (stopped):**
```json
{
  "success": true,
  "message": "Instance status retrieved successfully",
  "data": {
    "name": "my_frpc",
    "initSystem": "systemd",
    "serviceName": "superfrpc_admin_my_frpc",
    "isRunning": false
  }
}
```

| Field | Type | Description |
|-------|------|-------------|
| name | string | Name of the frpc instance |
| initSystem | string | Operating system init system: "windows", "systemd", or "init.d" |
| serviceName | string | Service name (Linux only) |
| isRunning | boolean | Instance running status: true (running) or false (stopped) |

---  

## Create Proxy

**Endpoint:** `/frpcAct/proxyMgr/create`  
**Method:** POST  
**Content-Type:** application/json  
**Auth Required:** Yes (token)  
**Permission Level:** Admin

Create a new proxy configuration for an existing frpc instance. The proxy configuration will be appended to the instance's config file.

**Request Headers:**
```
X-Token: your_token
X-Timestamp: 1704067200000
```

**Request Body:**
```json
{
  "instanceID": "1",
  "proxyInfo": {
    "name": "ssh_proxy",
    "type": "tcp",
    "localIP": "127.0.0.1",
    "localPort": "22",
    "remotePort": "6000"
  }
}
```

| Header | Type | Required | Description |
|--------|------|----------|-------------|
| X-Token | string | Yes | Authentication token |
| X-Timestamp | int64 | Yes | Client timestamp in milliseconds |

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| instanceID | string | Yes | Instance ID (the ID of the frpc instance) |
| proxyInfo.name | string | Yes | Proxy name |
| proxyInfo.type | string | Yes | Proxy type (e.g., tcp, udp, http, https) |
| proxyInfo.localIP | string | Yes | Local IP address to forward to |
| proxyInfo.localPort | string | Yes | Local port to forward from |
| proxyInfo.remotePort | string | Yes | Remote port on frps to expose |

**Response:**
```json
{
  "success": true,
  "message": "Proxy created successfully",
  "data": {
    "instanceID": 1,
    "configPath": "./configs/superfrpc_user_my_frpc.toml",
    "proxyName": "ssh_proxy"
  }
}
```

| Field | Type | Description |
|-------|------|-------------|
| instanceID | int | Instance ID |
| configPath | string | Path to the configuration file |
| proxyName | string | Name of the created proxy |

**Config File Format:**

The proxy configuration will be appended to the instance's config file in the following format:

```toml
[[proxies]]
name = ssh_proxy
type = tcp
local_ip = 127.0.0.1
local_port = 22
remote_port = 6000
```

> **Note:** 
> - The proxy configuration is appended to the existing config file
> - The instance must already exist before creating a proxy
> - This endpoint does not modify the database, only the config file
> - The frpc service needs to be restarted for changes to take effect

---

## Delete Proxy

**Endpoint:** `/frpcAct/proxyMgr/delete`  
**Method:** POST  
**Content-Type:** application/json  
**Auth Required:** Yes (token)  
**Permission Level:** Admin

Delete an existing proxy configuration from an frpc instance. The proxy configuration will be removed from the instance's config file.

**Request Headers:**
```
X-Token: your_token
X-Timestamp: 1704067200000
```

**Request Body:**
```json
{
  "instanceID": "1",
  "proxyName": "ssh_proxy"
}
```

| Header | Type | Required | Description |
|--------|------|----------|-------------|
| X-Token | string | Yes | Authentication token |
| X-Timestamp | int64 | Yes | Client timestamp in milliseconds |

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| instanceID | string | Yes | Instance ID (the ID of the frpc instance) |
| proxyName | string | Yes | Name of the proxy to delete |

**Response:**
```json
{
  "success": true,
  "message": "Proxy deleted successfully",
  "data": {
    "instanceID": 1,
    "configPath": "./configs/superfrpc_user_my_frpc.toml",
    "proxyName": "ssh_proxy"
  }
}
```

| Field | Type | Description |
|-------|------|-------------|
| instanceID | int | Instance ID |
| configPath | string | Path to the configuration file |
| proxyName | string | Name of the deleted proxy |

> **Note:** 
> - The proxy configuration is removed from the existing config file
> - The instance must already exist before deleting a proxy
> - This endpoint does not modify the database, only the config file
> - The frpc service needs to be restarted for changes to take effect

---

## List Proxies

**Endpoint:** `/frpcAct/proxyMgr/list`  
**Method:** GET  
**Auth Required:** Yes (token)  
**Permission Level:** None (any permission level)

Retrieve a list of all proxy configurations for a specific frpc instance. The proxy configurations are read from the instance's config file.

**Request Headers:**
```
X-Token: your_token
X-Timestamp: 1704067200000
```

**Query Parameters:**
```
?instanceID=1
```

| Header | Type | Required | Description |
|--------|------|----------|-------------|
| X-Token | string | Yes | Authentication token |
| X-Timestamp | int64 | Yes | Client timestamp in milliseconds |

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| instanceID | string | Yes | Instance ID (the ID of the frpc instance) |

**Response:**
```json
{
  "success": true,
  "message": "Proxies listed successfully",
  "data": {
    "instanceID": 1,
    "proxyCount": 2,
    "proxies": [
      {
        "name": "ssh_proxy",
        "type": "tcp",
        "localIP": "127.0.0.1",
        "localPort": "22",
        "remotePort": "6000"
      },
      {
        "name": "web_proxy",
        "type": "http",
        "localIP": "127.0.0.1",
        "localPort": "8080",
        "remotePort": "80"
      }
    ]
  }
}
```

| Field | Type | Description |
|-------|------|-------------|
| instanceID | int | Instance ID |
| proxyCount | int | Number of proxies |
| proxies | array | List of proxy configurations |

**Proxy Object:**
| Field | Type | Description |
|-------|------|-------------|
| name | string | Proxy name |
| type | string | Proxy type (e.g., tcp, udp, http, https) |
| localIP | string | Local IP address to forward to |
| localPort | string | Local port to forward from |
| remotePort | string | Remote port on frps to expose |

> **Note:** 
> - The proxy configurations are read from the existing config file
> - This endpoint does not modify the database, only reads the config file
> - The returned proxy list represents the current configuration in the file
> - Changes to the config file will be reflected in subsequent requests

---

## List frpc Instances

**Endpoint:** `/frpcAct/instanceMgr/list`  
**Method:** GET  
**Auth Required:** Yes (token)  
**Permission Level:** Admin

Retrieve a list of all frpc instances on the server.

**Request Headers:**
```
X-Token: your_token
X-Timestamp: 1704067200000
```

| Header | Type | Required | Description |
|--------|------|----------|-------------|
| X-Token | string | Yes | Authentication token |
| X-Timestamp | int64 | Yes | Client timestamp in milliseconds |

**Response (admin/superuser):**
```json
{
  "success": true,
  "message": "instances retrieved successfully",
  "data": [
    {
      "instanceID": 1,
      "name": "my_frpc",
      "serverAddr": "127.0.0.1",
      "serverPort": "7000",
      "auth_method": "token",
      "bootAtStart": true,
      "runUser": "root",
      "configPath": "./configs/superfrpc_user_my_frpc.toml",
      "createdAt": "2024-01-01T00:00:00Z",
      "createdBy": "admin"
    }
  ]
}
```

**Response (visitor):**
```json
{
  "success": true,
  "message": "instances retrieved successfully",
  "data": [
    {
      "instanceID": 1,
      "name": "my_frpc",
      "bootAtStart": true,
      "runUser": "root",
      "configPath": "./configs/superfrpc_user_my_frpc.toml",
      "createdAt": "2024-01-01T00:00:00Z",
      "createdBy": "admin"
    }
  ]
}
```

| Field | Type | Description |
|-------|------|-------------|
| instanceID | int | Instance ID |
| name | string | Instance name |
| serverAddr | string | frps server address (admin/superuser only) |
| serverPort | string | frps server port (admin/superuser only) |
| auth_method | string | Authentication method (admin/superuser only) |
| bootAtStart | bool | Auto-start on system boot |
| runUser | string | User to run the frpc instance as |
| configPath | string | Path to the configuration file |
| createdAt | string | Instance creation time (ISO 8601 format) |
| createdBy | string | Username of the user who created this instance |

> Note: Visitor users do not see sensitive information (serverAddr, serverPort, auth_method).

---

## Real-time Log Streaming (WebSocket)

**Endpoint:** `/system/getLogs`  
**Protocol:** WebSocket  
**Auth Required:** Yes (token)  
**Permission Level:** None

Establish a WebSocket connection to receive real-time log streaming from the server.

### Connection

Connect to `ws://localhost:8080/system/getLogs` (or `wss://` for secure connection).

**Query Parameters:**
- `token`: Authentication token (optional, for tracking which user is viewing logs)

**Example:**
```
ws://localhost:8080/logs?token=your_token_here
```

### Message Format

Logs are sent as JSON messages with the following structure:

```json
{
  "level": 1,
  "content": "Log message content",
  "timestamp": "2024-01-01 12:00:00.000"
}
```

| Field | Type | Description |
|-------|------|-------------|
| level | int | Log level: 0=DEBUG, 1=INFO, 2=WARNING, 3=ERROR, 4=FATAL |
| content | string | Log message content |
| timestamp | string | Log timestamp (YYYY-MM-DD HH:MM:SS.mmm format) |

### Log Levels

| Level | Name | Description |
|-------|------|-------------|
| 0 | DEBUG | Debug messages (only visible when debug mode is enabled) |
| 1 | INFO | Informational messages |
| 2 | WARNING | Warning messages |
| 3 | ERROR | Error messages |
| 4 | FATAL | Fatal/critical messages |

### Behavior

1. **On Connection**: The server immediately sends the last 100 log entries
2. **Streaming**: All new log entries are pushed in real-time to all connected clients
3. **Multi-client**: Multiple clients can connect simultaneously and receive the same log stream
4. **History**: Only the most recent 100 log entries are kept in memory

### Example Usage (JavaScript)

```javascript
const socket = new WebSocket('ws://localhost:8080/logs?token=your_token');

socket.onopen = () => {
  console.log('Connected to log server');
};

socket.onmessage = (event) => {
  const log = JSON.parse(event.data);
  console.log(`[${log.timestamp}] ${log.content}`);
  
  // Log level example
  const levels = ['DEBUG', 'INFO', 'WARNING', 'ERROR', 'FATAL'];
  console.log(`[${levels[log.level]}] ${log.content}`);
};

socket.onclose = () => {
  console.log('Disconnected from log server');
};

socket.onerror = (error) => {
  console.error('WebSocket error:', error);
};
```
---

## User Permissions

| Permission | superuser | admin | visitor |
|------------|-----------|-------|---------|
| Create instance | ✓ | ✓ | ✗ |
| Delete instance | ✓ | ✓ | ✗ |
| Modify instance | ✓ | ✓ | ✗ |
| List instances | ✓ | ✓ | ✓ (limited) |
| Manage users | ✓ | ✗ | ✗ |
| List active sessions | ✓ | ✓ | ✗ |
| View logs | ✓ | ✓ | ✓ |

---

## Timestamp Validation

All requests include a `timeStamp` field (Unix timestamp in milliseconds). The server validates that the timestamp is within ±3000ms of the server time. This prevents replay attacks.

---

## Password Requirements

Passwords must meet the following complexity requirements:
- At least 8 characters
- At least one uppercase letter (A-Z)
- At least one lowercase letter (a-z)
- At least one digit (0-9)
- At least one special character (!@#$%^&*()_+-=[]{}|;:,.<>?)

---

## Token

Tokens are valid for 1 hour. After expiration, users need to re-login to get a new token.

---

## Generated Config Files

Instance configuration files are saved in the specified `instancePath` with the naming convention:
```
superfrpc_<username>_<instanceName>.toml
```

Example: `superfrpc_admin_my_frpc.toml`

---

## Error Codes

| Code | Message | Description |
|------|---------|-------------|
| 400 | Bad Request | Invalid request parameters |
| 401 | Unauthorized | Missing or invalid authentication token |
| 403 | Forbidden | Insufficient permissions |
| 404 | Not Found | Resource not found |
| 500 | Internal Server Error | Server internal error |

---

## Rate Limiting

The API implements rate limiting to prevent abuse:
- Login attempts: Maximum 5 attempts per minute per IP
- All other endpoints: 100 requests per minute per token

Exceeding rate limits will result in temporary IP or token blocking.