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

Codex documentstion created

Browse source
This commit is contained in:
Frank Harris 2026-06-05 11:07:47 -05:00
parent 3dc017421e
commit b5dcf01a8c
27 changed files with 6648 additions and 1069 deletions
Download patch file Download diff file Expand all files Collapse all files

103
docs/architecture/PANEL_AGENT_FLOW.md Normal file
View file

@ -0,0 +1,103 @@
# Panel Agent Flow
## Overview
The Panel does not directly run servers. It prepares the request, sends it to the agent, and interprets the response.
```text
User action
-> Panel module page
-> OGPRemoteLibrary in lib_remote.php
-> XML-RPC request to agent /RPC2
-> ogp_agent.pl method
-> local screen/process/port work
-> return status or payload
-> Panel renders result
```
## Request Path
Important Panel files:
- `Panel/includes/lib_remote.php`
- `Panel/modules/gamemanager/start_server.php`
- `Panel/modules/gamemanager/stop_server.php`
- `Panel/modules/gamemanager/restart_server.php`
- `Panel/modules/gamemanager/server_monitor.php`
- `Panel/modules/gamemanager/view_server_log.php`
- `Panel/modules/gamemanager/get_server_log.php`
- `Panel/modules/gamemanager/home_handling_functions.php`
### Start
1. Panel loads the selected server home and game XML.
2. Panel composes startup parameters from stored values and XML templates.
3. Panel calls `universal_start` on the agent.
4. Agent creates the `screen` session and starts the server command.
5. Panel polls `remote_server_status`.
6. When the agent reports that the process/session exists and the game port listens, the server is treated as ONLINE.
### Stop
1. Panel calls `remote_stop_server`.
2. Agent sends the configured graceful stop command if one exists.
3. Agent watches the session/process and required port.
4. If the session/process does not exit in time, the agent escalates to screen quit or process kill.
5. Panel treats the server as stopped only when the agent confirms it is actually gone.
### Restart
Restart should be:
```text
stop
-> wait
-> start
```
The wait period should be explicit and visible in logs. Restart should not depend on marker files or query success.
### Status
1. Panel calls `remote_server_status`.
2. Agent checks:
- managed screen/session
- PID or process tree when available
- required game port
- optional query/RCON ports
3. Agent returns a structured status object.
4. Panel maps the result to the UI state.
### Logs
1. Panel calls `get_log`.
2. Agent returns the latest screen or console log data.
3. The log view updates via AJAX instead of full-page refresh.
4. The UI should preserve scroll position and only auto-scroll when the user is already at the bottom.
## Data Returned by Status
Recommended status fields:
- `status`
- `ready`
- `process_running`
- `session_running`
- `game_port_listening`
- `query_port_listening`
- `rcon_port_listening`
- `pid`
- `session_name`
- `ip`
- `port`
- `query_port`
- `last_error`
- optional query metadata
## Practical Notes
- The Panel should not mark a server failed only because query metadata was unavailable.
- The agent should be the source of truth.
- Marker files may exist, but they should be treated as hints only.
- The same high-level flow should work for Linux and Windows/Cygwin.

159
docs/architecture/REPOSITORY_OVERVIEW.md Normal file
View file

@ -0,0 +1,159 @@
# Repository Overview
## Purpose
This repository contains the GSP game server hosting platform:
- `Panel` - the web control panel and customer/admin UI.
- `Agent_Linux` - the Linux agent that starts, stops, monitors, updates, and logs game servers.
- `Agent-Windows` - the Windows/Cygwin agent that mirrors the Linux agent as closely as possible.
- `Website` - the public marketing, customer, and commerce site.
## Top-Level Layout
```text
/
Agent_Linux/
Agent-Windows/
Panel/
Website/
docs/
```
## Major Components
### Panel
The Panel is the orchestration layer. It:
- loads module pages from `Panel/modules/*`
- talks to agents through `Panel/includes/lib_remote.php`
- stores panel-side state in the database
- renders server lifecycle, file, backup, scheduler, Workshop, support, and billing pages
Important Panel files:
- `Panel/includes/lib_remote.php`
- `Panel/modules/gamemanager/home_handling_functions.php`
- `Panel/modules/gamemanager/server_monitor.php`
- `Panel/modules/config_games/schema_server_config.xml`
- `Panel/modules/addonsmanager/module.php`
- `Panel/modules/cron/module.php`
- `Panel/modules/user_games/module.php`
### Agents
The agents are the execution layer. They:
- launch game servers inside `screen`
- stop and restart servers
- read logs
- run updates and install jobs
- execute scheduler jobs
- report status back to the Panel
Important agent files:
- `Agent_Linux/ogp_agent.pl`
- `Agent-Windows/ogp_agent.pl`
- `Agent_Linux/startups/`
- `Agent-Windows/ServerFiles/`
- `Agent_Linux/php-query/`
- `Agent-Windows/php-query/`
### Website
The Website is separate from the server runtime path. It is used for:
- public product pages
- documentation links
- customer onboarding
- billing and commerce surfaces
## Panel <-> Agent Communication
The Panel uses XML-RPC over HTTP to call methods exposed by `ogp_agent.pl`.
The remote wrapper lives in:
- `Panel/includes/lib_remote.php`
The most important calls are:
- `universal_start`
- `remote_stop_server`
- `remote_restart_server`
- `remote_server_status`
- `is_screen_running`
- `get_log`
- `remote_query`
- scheduler methods
The agents decode the request, execute the action locally, and return a status code or payload.
## Database Usage
The Panel database stores:
- server homes and assigned ports
- game definitions and mod mappings
- user permissions and subusers
- scheduler definitions and related data
- content and Workshop metadata
- tickets/support records
- billing and provisioning records
Key tables discovered in current code:
- `server_homes`
- `home_ip_ports`
- `game_mods`
- `status_cache`
- `config_homes`
- `config_mods`
- `addons`
- `server_content_workshop`
- `server_content_manifest`
- `server_content_install_history`
- `tickets`
- `ticket_messages`
- `ticket_attachments`
- `ticket_settings`
- billing-related tables in `Panel/modules/billing`
The agents also keep runtime files such as screen logs, update logs, scheduler state, and helper manifests, but those should be treated as runtime state rather than the source of truth.
## Startup Flow
1. User clicks start in the Panel.
2. Panel builds the startup command from the game XML and stored server parameters.
3. Panel sends `universal_start` to the agent.
4. Agent creates a `screen` session and launches the server command.
5. Panel polls status and logs.
6. If the managed session exists and the required port listens, the server is considered online.
## Status Reporting Flow
The desired status flow is:
```text
Panel asks agent for status
-> agent checks managed session/process
-> agent checks required listening port
-> agent optionally performs query metadata lookup
-> agent returns structured status
-> Panel renders ONLINE / STARTING / STOPPING / UNRESPONSIVE / OFFLINE / UNKNOWN
```
Query results are metadata only. They are not the source of truth for online/offline state.
## What To Read First
For future investigations, start with:
1. `docs/development/CODEX_GUIDE.md`
2. `docs/architecture/PANEL_AGENT_FLOW.md`
3. `docs/modules/GAMEMANAGER.md`
4. `docs/features/STATUS_SYSTEM.md`
5. `docs/features/XML_SYSTEM.md`