GSP/Panel
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

complete codex docs

Browse source
This commit is contained in:
Frank Harris 2026-06-05 11:37:09 -05:00
parent b5dcf01a8c
commit 3cefad183d
62 changed files with 2730 additions and 50 deletions
Download patch file Download diff file Expand all files Collapse all files

66
docs/architecture/AI_GSP_ARCHITECTURE.md Normal file
View file

@ -0,0 +1,66 @@
# GSP Component Architecture
This repository contains the related GSP components together:
- `/Agent-Windows` - Cygwin/Windows game server agent.
- `/Agent_Linux` - Linux game server agent.
- `/Panel` - PHP control panel used by customers and staff.
- `/Website` - public website and related customer-facing pages.
## Panel And Agent Communication
The Panel talks to agents through XML-RPC using the encrypted parameter helpers in `Panel/includes/lib_remote.php`. The Panel should request actions from the agent and treat the agent as the source of truth for server state.
The shared server control backend is still `screen` for both Linux and Cygwin/Windows agents. The Panel should not decide that a game server is online only because a web request, LGSL query, or GameQ query succeeded.
## Status Source Of Truth
The agent is the source of truth for start, stop, restart, and status. Marker files such as `SERVER_STOPPED` or startup flag files may still exist for legacy autorestart and startup bookkeeping, but they are not trusted as the current server state.
The minimum readiness check is:
1. The configured process/session exists.
2. The configured game port is listening.
LGSL/GameQ query data is optional metadata only. It can provide player counts, maps, hostname, and other query details. If query fails while the process/session exists and the game port is listening, the Panel should show the server as online with a small "query info unavailable" note.
## Status Model
- `OFFLINE`: no managed process/session and no listening game port.
- `STARTING`: managed process/session exists, but the game port is not listening yet.
- `ONLINE`: managed process/session exists and the game port is listening.
- `STOPPING`: stop was requested and the managed process/session still exists.
- `UNRESPONSIVE`: the managed process/session exists but the game port did not become ready before timeout, or stop did not complete cleanly.
- `UNKNOWN`: the agent cannot be reached or did not return structured status.
## Start
Start should launch the configured screen/session and immediately report a starting state if the session exists. Slow games, including Arma 2 and DayZ Mod, must not be marked failed just because LGSL/GameQ did not answer quickly.
Startup timeout should be configurable per game XML when possible, with a default of 180 seconds.
## Stop
Stop should issue the configured graceful control command when available. The agent then checks whether the managed screen/session is gone and whether the game port is no longer listening. If the process/session remains after the wait period, the agent escalates by closing the screen session.
The Panel should only show stopped after the agent confirms `OFFLINE`.
## Restart
Restart is intentionally simple:
1. Stop server.
2. Wait 60 seconds.
3. Start server.
Do not use a separate shortcut that skips stop verification or depends on query responses.
## Log Viewer
The gamemanager log viewer should update the log text through AJAX/live fetches only. It should not reload the full page for each refresh and should not show the old manual refresh interval dropdown or plus/update button.
The live log should preserve mobile scrolling behavior and only auto-scroll when the user is already near the bottom.
## Agent Parity
Keep Linux and Cygwin/Windows agent behavior as similar as possible. Both should continue using `screen` as the shared backend for now and expose the same status model to the Panel.

129
docs/architecture/API_REFERENCE.md Normal file
View file

@ -0,0 +1,129 @@
# API Reference
## Overview
Panel-Agent communication uses XML-RPC over HTTP.
Main transport wrapper:
- `Panel/includes/lib_remote.php`
Main agent implementation files:
- `Agent_Linux/ogp_agent.pl`
- `Agent-Windows/ogp_agent.pl`
The Panel encrypts arguments before sending them to the agent. The agent decodes them, performs the requested action locally, then returns a status or payload.
## General Call Pattern
```text
Panel module
-> OGPRemoteLibrary method in lib_remote.php
-> XML-RPC request to agent /RPC2
-> agent subroutine in ogp_agent.pl
-> local screen/process/file/network action
-> return code or structured payload
```
## Core RPC Methods
| RPC / Wrapper | Purpose | Common Callers | Notes |
|---|---|---|---|
| `status_chk` | Quick agent reachability check | Panel health checks | Returns a lightweight online/offline/encryption state. |
| `rfile_exists` | Test if a remote file exists | File/content helpers | Used for safe file checks before read/write actions. |
| `get_log` | Fetch screen or console log text | `gamemanager` | Returns log content plus a status code. |
| `remote_stop_server` / `stop_server` | Stop a game server | `gamemanager`, scheduler actions | Takes control protocol and home path data. |
| `remote_send_rcon_command` / `send_rcon_command` | Send RCON/console command | `gamemanager`, `rcon`, scheduler warnings | Useful for warning messages and admin commands. |
| `remote_readfile` / `readfile` | Read a remote file | File editor, config tools | Must remain path-safe. |
| `remote_writefile` / `writefile` | Write a remote file | File editor, config tools | Must remain path-safe. |
| `universal_start` | Start a game server | `gamemanager` | Launches a managed `screen` session. |
| `is_screen_running` | Test whether a managed screen session exists | `gamemanager`, monitor pages | Legacy/simple screen check, not full readiness. |
| `remote_server_status` / `server_status` | Structured server status | `gamemanager` | The preferred source for online/start/stop state. |
| `remote_restart_server` / `restart_server` | Restart a server | `gamemanager` | Intended to be stop, wait, start. |
| `remote_query` | Query game metadata | `gamemanager` | Optional metadata only. |
| `steam_cmd` / `steam` / `automatic_steam_update` | SteamCMD-based update flows | Update actions, Workshop/install tools | Used by Steam-based server maintenance. |
| `start_file_download` | Download external content | Update/content tools | Returns a PID or progress handle. |
| `uncompress_file` | Extract archives | Content installers | Used for zip/tar package installs. |
| `remote_dirlist` / `remote_dirlistfm` | Read remote directory listings | File manager | Used for browse views. |
| `cpu_count`, `renice_process`, `force_cpu` | System/process control helpers | Update/start flows | Used during server launch optimization. |
| `clone_home` / `remove_home` | Duplicate or delete a server home | Provisioning/admin tools | Used during provisioning and teardown. |
| `secure_path`, `get_chattr` | Path safety and attribute helpers | File and security tools | Helps enforce control-path rules. |
| `ftp_mgr` | FTP management helper | FTP module | Used to manage server FTP state. |
| `compress_files` | Archive files | Backup/content tools | Candidate building block for backups. |
| `start_fastdl` / `stop_fastdl` / `restart_fastdl` / `fastdl_status` | FastDL service management | `fast_download` | Source/GoldSrc web distribution support. |
| `scheduler_*` methods | Task list and task CRUD | `cron` | Agent-owned scheduler implementation. |
| `agent_restart` | Restart the agent itself | Admin maintenance | Node maintenance action. |
| `shell_action` | Run a shell action in a controlled way | Advanced agent operations | Should remain tightly permissioned. |
| `send_steam_guard_code` | Submit Steam Guard code | Steam authenticated installs | Used for authenticated SteamCMD workflows. |
| `steam_workshop` / `get_workshop_mods_info` | Workshop-related helper calls | Workshop/content flows | Active in current module work, but still being consolidated. |
## Status And Return Patterns
Return values differ by method, but common patterns are:
- `1` or positive values for success
- `0` for offline/unavailable
- `-1` or another negative value for error
- structured arrays/hashes for richer status methods
`remote_server_status` is the important structured response. It should return the agent as source of truth for:
- `OFFLINE`
- `STARTING`
- `ONLINE`
- `STOPPING`
- `UNRESPONSIVE`
- `UNKNOWN`
## Sequence Diagrams
### Start
```text
Panel
-> universal_start
Agent
-> create screen session
-> launch server command
Panel
-> remote_server_status polling
Agent
-> session/process + port checks
Panel
-> render STARTING / ONLINE / UNRESPONSIVE
```
### Stop
```text
Panel
-> remote_stop_server
Agent
-> graceful stop command if available
-> wait for session/process exit
-> escalate to kill if needed
Panel
-> remote_server_status polling
Agent
-> confirm OFFLINE or UNRESPONSIVE
```
### Logs
```text
Panel log page
-> get_log
Agent
-> read screen log or console log
Panel
-> refresh textarea via AJAX
```
## Error Handling Notes
- Do not treat query failure as a start failure by itself.
- Do not treat marker-file presence as the source of truth.
- Do not expose raw shell execution to customers through generic RPC routes.
- When a method returns a payload, record the error text in the Panel UI if the operation fails.