GSP/GSP-Agent-Windows
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
GSP-Agent-Windows/docs/GSP_WINDOWS_AGENT_PORT_VALIDATION.md

7.7 KiB
Raw Permalink Blame History

GSP Windows Agent Port Validation

Workspace reference: GSP-WORKSPACE.md

Current Behavior

The Windows agent is a Cygwin-packaged OGP Perl agent. The maintained runtime lives under OGP64/, and the core service is OGP64/OGP/ogp_agent.pl.

Documentation Review Notes

Reviewed local project documentation:

  • README.md
  • docs/AGENT_ARCHITECTURE.md
  • docs/CYGWIN_INTEGRATION.md
  • docs/COMMAND_EXECUTION.md
  • docs/PROCESS_MANAGEMENT.md
  • docs/PANEL_INTEGRATION.md
  • OGP64/OGP/README.md
  • OGP64/OGP/documentation/agent-guide.md
  • related GSP Panel docs under ../GSP/docs/architecture/ and ../GSP/docs/features/STATUS_SYSTEM.md

Documentation not found in this repository:

  • AGENTS.md
  • CODEX_PROJECT_GUIDE.md
  • a dedicated protocol/API document before this feature note
  • a dedicated networking/status validation document before this feature note

Architecture Discovery

Windows startup flow:

  1. OGP64/agent_start.bat sets the Cygwin path and validates OGP64/OGP/ogp_agent.pl.
  2. The batch script creates missing config files from .default templates.
  3. It runs perl -c ./ogp_agent.pl.
  4. It launches the agent from /OGP.

Shutdown flow:

  1. OGP64/agent_stop.bat reads known PID files.
  2. It sends termination signals through the bundled Cygwin kill.exe.

Communication with Panel:

  • XML-RPC over /RPC2
  • shared key configured in OGP64/OGP/Cfg/Config.pm
  • command dispatch table in OGP64/OGP/ogp_agent.pl
  • structured status command: server_status

Server launch process:

  • Panel calls universal_start.
  • Agent writes a startup hint under /OGP/startups.
  • Agent launches the server inside a managed screen session.
  • The game command receives Panel-generated startup parameters, including the assigned game port.

Server stop process:

  • Panel calls stop_server.
  • Agent writes a STOPPING status hint.
  • Agent removes the startup flag and kills the managed process tree.

Server status process:

  • Panel calls server_status when available.
  • Agent checks the managed screen session.
  • Agent validates Panel-provided ports.
  • Agent returns a compatibility status plus richer port fields.

Before this change, the structured server_status RPC used these inputs:

  • home_id
  • server_ip
  • server_port
  • query_port
  • rcon_port
  • startup_timeout
  • state_hint

The agent checked the managed GNU Screen session and probed ports with netstat. It primarily treated the game port as the readiness indicator and returned compatibility fields such as status, ready, process_running, session_running, game_port_listening, query_port_listening, and rcon_port_listening.

This was better than checking only a process, but it still had gaps:

  • it did not expose a complete expected/listening/missing port list
  • it only modeled game/query/RCON ports as individual checks
  • it did not return the requested Stopped, Starting, Running, Warning, and Failed state model
  • it preferred netstat, while Windows can expose listening ports through .NET networking APIs

Proposed Behavior

The agent should validate only the ports assigned by the Panel for the specific server.

The Panel remains the source of truth for expected ports. The agent must not scan random application ports, guess ports, or hardcode game-specific port rules.

The status result now keeps the existing compatibility fields and adds richer fields:

  • ProcessRunning
  • StatusState
  • ExpectedPorts
  • ListeningPorts
  • MissingPorts
  • CPUUsage
  • MemoryUsage
  • PortValidationEnabled
  • StartupValidationTimeoutSeconds
  • PortCheckIntervalSeconds

Architecture Overview

Panel Game Monitor
  -> Panel/includes/lib_remote.php remote_server_status()
  -> XML-RPC server_status
  -> OGP64/OGP/ogp_agent.pl
  -> managed screen/session check
  -> configured port validation
  -> structured status hash
  -> Panel display logic

Status Flow

  1. Panel calls server_status with the server's assigned game/query/RCON ports.
  2. Agent checks the managed screen session for home_id.
  3. Agent builds ExpectedPorts from the Panel-provided ports.
  4. Agent collects listening ports using PowerShell/.NET System.Net.NetworkInformation.IPGlobalProperties when available.
  5. Agent falls back to netstat -an if PowerShell/.NET collection fails.
  6. Agent compares expected ports with active TCP/UDP listeners.
  7. Agent returns old compatibility fields and new detailed fields.

State Model

StatusState Meaning Compatibility status
Stopped No managed process/session and no configured port evidence. OFFLINE
Starting Process/session exists, but required ports are not listening yet. STARTING
Running Process/session exists and all expected ports are listening. ONLINE
Warning Process/session exists and only some expected ports are listening, or ports listen without the managed session. ONLINE
Failed Process/session exists and no expected ports are listening after timeout. UNRESPONSIVE

The compatibility status field is intentionally preserved so existing Panel code does not break.

Panel Integration

Current Panel integration is already compatible:

  • Panel/includes/lib_remote.php::remote_server_status()
  • Panel/modules/gamemanager/home_handling_functions.php::get_agent_server_status()

The Panel currently passes the assigned game port plus derived query and RCON ports. Future Panel work can pass multiple ports in the existing query_port or rcon_port strings using comma, semicolon, or whitespace-separated values, with optional protocol markers such as 2302/udp or tcp:27015.

Agent Integration

Changed agent file:

  • OGP64/OGP/ogp_agent.pl

Changed default config file:

  • OGP64/OGP/Cfg/Preferences.pm.default

The agent does not introduce a new RPC. It extends the existing server_status response.

Configuration Options

Add these keys to Cfg/Preferences.pm:

Key Default Purpose
PortValidationEnabled 1 Enables configured port validation.
StartupValidationTimeoutSeconds 180 Time before a process with no listening required ports is treated as failed.
PortCheckIntervalSeconds 5 Polling interval for future startup wait loops. Current RPC checks once per call.

Testing Plan

Validation scenarios:

Scenario Expected result
Process/session running and all expected ports listening StatusState=Running, status=ONLINE
Process/session running and some expected ports listening StatusState=Warning, status=ONLINE, missing ports listed
Process/session running and no ports before timeout StatusState=Starting, status=STARTING
Process/session running and no ports after timeout StatusState=Failed, status=UNRESPONSIVE
No process/session and no expected ports listening StatusState=Stopped, status=OFFLINE
No process/session but expected port is listening StatusState=Running or Warning, status=ONLINE, warning message

Manual Windows validation:

  1. Start the agent with C:\OGP64\agent_start.bat.
  2. Start a test server from the Panel.
  3. Confirm server_status reports Starting until assigned ports bind.
  4. Confirm all assigned ports appear under ExpectedPorts.
  5. Confirm matching ports appear under ListeningPorts.
  6. Confirm unbound assigned ports appear under MissingPorts.

Future Enhancements

  • Add Panel-side support for passing a first-class array of expected ports instead of overloading optional port strings.
  • Add per-game startup timeout values from XML or Panel settings.
  • Add process-specific CPU and memory usage when the game server PID tree can be mapped reliably.
  • Add automated integration tests that call the XML-RPC endpoint on a Windows/Cygwin test host.