# 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. |
| `exec` | Execute a constrained agent-side command | `gamemanager` fallback status checks, admin tooling | The Game Monitor currently uses this only as a fallback to test whether the configured game port is listening with `ss`/`netstat`. Customer input must not be passed through this path. |
| `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. |
| `component_update` | Queue a Git-based agent code update | Update module | Admin-only. Uses encrypted XML-RPC, validates repo/branch/source/destination, launches a detached updater, preserves agent config/runtime/server data, and returns queued status plus an agent log path. |
| `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`

The Panel Game Monitor has a defensive fallback path while the structured status system is still being hardened:

```text
remote_server_status if available
  -> is_screen_running fallback
  -> agent-side port listening check through exec
  -> LGSL/GameQ only for optional player/map/query metadata
```

A confirmed managed screen/session, process flag, or listening game port is enough for the Panel to display `ONLINE`. Query failure alone must not produce `OFFLINE` or `UNKNOWN`.

Current compatibility behavior:

- New agents should expose `server_status` / `remote_server_status`.
- Older agents may only expose `is_screen_running` and generic `exec`.
- The Panel therefore falls back to `is_screen_running` and an agent-side port check.
- Agents report `ONLINE` when the configured game port is listening even if the managed screen/session cannot be found, with `last_error` carrying the warning.
- LGSL/GameQ/Steam query data is optional metadata only.

## 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 dedicated preformatted log panel via AJAX
```

### Remote Agent Component Update

```text
Panel update page
  -> component_update(payload)
Agent
  -> validate repo, branch, source folder, destination
  -> write detached updater script
  -> return queued + log path
Updater script
  -> clone/fetch repository into staging
  -> copy Agent_Linux or Agent-Windows folder only
  -> preserve Cfg, ServerFiles, Schedule, logs, steamcmd, startups, pid files
  -> validate ogp_agent.pl
  -> restart agent through systemd or screen fallback
```

## 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.