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

cleanup

Browse source
This commit is contained in:
Frank Harris 2026-07-02 18:10:41 -05:00
parent 2d16aeb91a
commit 911c63c250
10605 changed files with 2485 additions and 2340 deletions
Download patch file Download diff file Expand all files Collapse all files

2
docs/AGENT_ACTIVITY_EVENTS.md
View file

@ -4,7 +4,7 @@ The Windows/Cygwin agent can report meaningful server lifecycle events to the GS
## Configuration
Set these values in `OGP64/OGP/Cfg/Config.pm`:
Set these values in `GSP64/GSP/Cfg/Config.pm`:
```perl
agent_event_url => 'https://panel.example.com/agent_event_receiver.php',

10
docs/AGENT_ARCHITECTURE.md
View file

@ -16,11 +16,11 @@ This repository owns the Windows execution engine for GSP.
| Path | Purpose |
| --- | --- |
| `OGP64/bin/` | Cygwin runtime binaries |
| `OGP64/OGP/ogp_agent.pl` | Core OGP Perl agent |
| `OGP64/agent_start.bat` | Manual startup launcher |
| `OGP64/agent_stop.bat` | Manual shutdown launcher |
| `OGP64/OGP/Cfg/` | Runtime configuration and templates |
| `GSP64/bin/` | Cygwin runtime binaries |
| `GSP64/GSP/gsp_agent.pl` | Core GSP Perl agent |
| `GSP64/agent_start.bat` | Manual startup launcher |
| `GSP64/agent_stop.bat` | Manual shutdown launcher |
| `GSP64/GSP/Cfg/` | Runtime configuration and templates |
## Design rule

4
docs/CYGWIN_INTEGRATION.md
View file

@ -2,7 +2,7 @@
Workspace reference: [`GSP-WORKSPACE.md`](../../GSP-WORKSPACE.md)
The Windows agent depends on Cygwin to provide the Linux-like execution environment expected by the OGP Perl agent.
The Windows agent depends on Cygwin to provide the Linux-like execution environment expected by the GSP Perl agent.
## What Cygwin provides
@ -13,7 +13,7 @@ The Windows agent depends on Cygwin to provide the Linux-like execution environm
## Operational rule
Startup scripts should detect the bundled Cygwin root first and fall back only when the bundled environment is missing. The launcher should point to the actual bundled `OGP64` tree, not to an unrelated system installation.
Startup scripts should detect the bundled Cygwin root first and fall back only when the bundled environment is missing. The launcher should point to the actual bundled `GSP64` tree, not to an unrelated system installation.
## Maintenance rule

28
docs/GSP_WINDOWS_AGENT_PORT_VALIDATION.md
View file

@ -4,7 +4,7 @@ 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`.
The Windows agent is a Cygwin-packaged GSP Perl agent. The maintained runtime lives under `GSP64/`, and the core service is `GSP64/GSP/gsp_agent.pl`.
## Documentation Review Notes
@ -16,8 +16,8 @@ Reviewed local project documentation:
- `docs/COMMAND_EXECUTION.md`
- `docs/PROCESS_MANAGEMENT.md`
- `docs/PANEL_INTEGRATION.md`
- `OGP64/OGP/README.md`
- `OGP64/OGP/documentation/agent-guide.md`
- `GSP64/GSP/README.md`
- `GSP64/GSP/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:
@ -31,27 +31,27 @@ Documentation not found in this repository:
Windows startup flow:
1. `OGP64/agent_start.bat` sets the Cygwin path and validates `OGP64/OGP/ogp_agent.pl`.
1. `GSP64/agent_start.bat` sets the Cygwin path and validates `GSP64/GSP/gsp_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`.
3. It runs `perl -c ./gsp_agent.pl`.
4. It launches the agent from `/GSP`.
Shutdown flow:
1. `OGP64/agent_stop.bat` reads known PID files.
1. `GSP64/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`
- shared key configured in `GSP64/GSP/Cfg/Config.pm`
- command dispatch table in `GSP64/GSP/gsp_agent.pl`
- structured status command: `server_status`
Server launch process:
- Panel calls `universal_start`.
- Agent writes a startup hint under `/OGP/startups`.
- Agent writes a startup hint under `/GSP/startups`.
- Agent launches the server inside a managed screen session.
- The game command receives Panel-generated startup parameters, including the assigned game port.
@ -112,7 +112,7 @@ The status result now keeps the existing compatibility fields and adds richer fi
Panel Game Monitor
-> Panel/includes/lib_remote.php remote_server_status()
-> XML-RPC server_status
-> OGP64/OGP/ogp_agent.pl
-> GSP64/GSP/gsp_agent.pl
-> managed screen/session check
-> configured port validation
-> structured status hash
@ -154,11 +154,11 @@ The Panel currently passes the assigned game port plus derived query and RCON po
Changed agent file:
- `OGP64/OGP/ogp_agent.pl`
- `GSP64/GSP/gsp_agent.pl`
Changed default config file:
- `OGP64/OGP/Cfg/Preferences.pm.default`
- `GSP64/GSP/Cfg/Preferences.pm.default`
The agent does not introduce a new RPC. It extends the existing `server_status` response.
@ -187,7 +187,7 @@ Validation scenarios:
Manual Windows validation:
1. Start the agent with `C:\OGP64\agent_start.bat`.
1. Start the agent with `C:\GSP64\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`.

17
docs/PANEL_INTEGRATION.md
View file

@ -6,8 +6,8 @@ The Panel is authoritative. The Windows agent executes the work the Panel reques
## Integration points
- shared key and RPC configuration live in `OGP64/OGP/Cfg/Config.pm`
- startup preferences live in `OGP64/OGP/Cfg/bash_prefs.cfg`
- shared key and RPC configuration live in `GSP64/GSP/Cfg/Config.pm`
- startup preferences live in `GSP64/GSP/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
@ -36,3 +36,16 @@ The Panel remains the source of truth for assigned ports. The Windows agent vali
Detailed design:
- [`GSP_WINDOWS_AGENT_PORT_VALIDATION.md`](GSP_WINDOWS_AGENT_PORT_VALIDATION.md)
## Server Content Runtime
Windows now mirrors the Linux server-content runtime layout for server-owned sidecars, bots, hooks, and generated content helpers:
- `_gsp_content/hooks/`
- `_gsp_content/generated/`
- `_gsp_content/runtime/`
- `_gsp_content/runtime/server_content.pids`
Stop and restart clean this runtime before main game process escalation. The main server PID remains tracked through `runtime_status/pid-<home_id>.kv`; `server_content.pids` must only contain server-content watchdog/app PIDs.
Legacy `_alsoRun.bat` support remains compatibility-only. When `_alsoRun.pid` is present, the Windows agent imports those PIDs into the server-content cleanup path so Panel Start/Stop/Restart does not leave legacy helper processes behind.

39
docs/PROCESS_MANAGEMENT.md
View file

@ -2,22 +2,22 @@
Workspace reference: [`GSP-WORKSPACE.md`](../../GSP-WORKSPACE.md)
The Windows agent manages customer servers through the Cygwin runtime and the OGP Perl agent.
The Windows agent manages customer servers through the Cygwin runtime and the GSP Perl agent.
## Current model
- `OGP64` is the Cygwin root for the maintained launcher
- `GSP64` 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`
- configured port validation is handled by `server_status` in `GSP64/GSP/gsp_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
## Important files
- `OGP64/agent_start.bat`
- `OGP64/agent_stop.bat`
- `OGP64/OGP/ogp_agent.pl`
- `OGP64/OGP/Cfg/`
- `GSP64/agent_start.bat`
- `GSP64/agent_stop.bat`
- `GSP64/GSP/gsp_agent.pl`
- `GSP64/GSP/Cfg/`
## Rule
@ -33,7 +33,7 @@ Detailed status validation design:
The Windows agent now tracks per-home runtime metadata under:
- `OGP64/OGP/runtime_status/pid-<home_id>.kv`
- `GSP64/GSP/runtime_status/pid-<home_id>.kv`
Tracked fields include PID/session information used to stop the right process reliably:
@ -43,21 +43,34 @@ Tracked fields include PID/session information used to stop the right process re
- `ip`
- `port`
Server-owned content runtimes are tracked separately under each server home:
- `_gsp_content/hooks/`
- `_gsp_content/generated/`
- `_gsp_content/runtime/`
- `_gsp_content/runtime/server_content.pids`
The main game server PID must remain in `runtime_status/pid-<home_id>.kv`, not in `server_content.pids`. The server-content PID file is reserved for hook, sidecar, bot, watchdog, and generated content application PIDs owned by that server.
## Stop escalation flow
When stop is requested, the agent now:
1. marks status hint as `STOPPING`
2. removes startup flag for `<ip>-<port>`
3. kills tracked PIDs (`screen_pid`, `windows_pid`, `game_pid`) if present
4. kills managed screen session
5. checks if the game port is still listening and kills the owning PID
6. verifies stop success (no managed session, no tracked running PID, no listening game port)
7. writes status hint `STOPPED` only after verification passes
3. cleans server-owned content PIDs from `_gsp_content/runtime/server_content.pids`, watchdogs before app PIDs
4. imports legacy `_alsoRun.pid` entries into the server-content PID registry when present
5. kills tracked main server PIDs (`screen_pid`, `windows_pid`, `game_pid`) if present
6. kills managed screen session
7. checks if the game port is still listening and kills the owning PID
8. verifies stop success (no managed session, no tracked running PID, no listening game port)
9. writes status hint `STOPPED` only after verification passes
The agent no longer creates or reads `SERVER_STOPPED`/`Server_Stopped` marker files for lifecycle control.
Autorestart loop control now uses agent-owned runtime status hints (`STARTING`/`STOPPING`/`STOPPED`) instead of game-home marker files.
Legacy `_alsoRun.bat` is treated as compatibility input only. New sidecars, bots, and hooks should be represented as server-owned content runtime and recorded in `server_content.pids` so stop and restart can clean them reliably.
## Restart behavior
Restart remains stop-first and now guards against duplicates:

14
docs/WINDOWS_AGENT_UPDATE_BAT.md
View file

@ -21,13 +21,13 @@ Place `Update-Agent.bat` in the repository root:
The current repository layout expects the managed start and stop launchers here:
- `OGP64\agent_start.bat`
- `OGP64\agent_stop.bat`
- `GSP64\agent_start.bat`
- `GSP64\agent_stop.bat`
If those are missing, the updater tries the obvious fallback launchers:
- `OGP64\OGP\Install\agent_start.bat`
- `OGP64\OGP\Install\agent_stop.bat`
- `GSP64\GSP\Install\agent_start.bat`
- `GSP64\GSP\Install\agent_stop.bat`
## How to run it
@ -85,8 +85,8 @@ origin/%BRANCH%
It reuses:
- `OGP64\agent_stop.bat`
- `OGP64\agent_start.bat`
- `GSP64\agent_stop.bat`
- `GSP64\agent_start.bat`
That keeps update behavior aligned with the normal manual agent lifecycle.
@ -115,4 +115,4 @@ The repository should contain the Windows agent code and bundled runtime files,
- The Git checkout root is the correct update boundary.
- The active branch should be `unstable` by default.
- The existing root launchers under `OGP64\` are the preferred lifecycle scripts.
- The existing root launchers under `GSP64\` are the preferred lifecycle scripts.