refixed the server query
This commit is contained in:
parent
eedc3e8fb3
commit
e2dd5a496c
8 changed files with 539 additions and 20 deletions
202
docs/GSP_WINDOWS_AGENT_PORT_VALIDATION.md
Normal file
202
docs/GSP_WINDOWS_AGENT_PORT_VALIDATION.md
Normal file
|
|
@ -0,0 +1,202 @@
|
|||
# GSP Windows Agent Port Validation
|
||||
|
||||
Workspace reference: [`GSP-WORKSPACE.md`](../../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
|
||||
|
||||
```text
|
||||
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.
|
||||
|
|
@ -9,7 +9,16 @@ The Panel is authoritative. The Windows agent executes the work the Panel reques
|
|||
- shared key and RPC configuration live in `OGP64/OGP/Cfg/Config.pm`
|
||||
- startup preferences live in `OGP64/OGP/Cfg/bash_prefs.cfg`
|
||||
- the Panel talks to the same command surface as the Linux agent wherever practical
|
||||
- game server readiness is reported through the existing `server_status` RPC, extended with expected/listening/missing port details
|
||||
|
||||
## Compatibility rule
|
||||
|
||||
The Windows agent should mirror the Linux agent behaviorally as much as possible so the Panel can treat both platforms as one product family.
|
||||
|
||||
## Status validation
|
||||
|
||||
The Panel remains the source of truth for assigned ports. The Windows agent validates only the ports supplied by the Panel for a specific server.
|
||||
|
||||
Detailed design:
|
||||
|
||||
- [`GSP_WINDOWS_AGENT_PORT_VALIDATION.md`](GSP_WINDOWS_AGENT_PORT_VALIDATION.md)
|
||||
|
|
|
|||
|
|
@ -8,6 +8,7 @@ The Windows agent manages customer servers through the Cygwin runtime and the OG
|
|||
|
||||
- `OGP64` is the Cygwin root for the maintained launcher
|
||||
- process state is tracked through the agent runtime and PID files
|
||||
- configured port validation is handled by `server_status` in `OGP64/OGP/ogp_agent.pl`
|
||||
- manual startup and shutdown are handled by the root batch scripts
|
||||
- Windows-specific user and service assumptions belong here, not in the Panel
|
||||
|
||||
|
|
@ -21,3 +22,9 @@ The Windows agent manages customer servers through the Cygwin runtime and the OG
|
|||
## Rule
|
||||
|
||||
Keep startup and stop behavior visible and explicit. Failures should be reported in the same console when launched manually.
|
||||
|
||||
## Port validation
|
||||
|
||||
Detailed status validation design:
|
||||
|
||||
- [`GSP_WINDOWS_AGENT_PORT_VALIDATION.md`](GSP_WINDOWS_AGENT_PORT_VALIDATION.md)
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue