From eedc3e8fb3e1cb0cf18e5f9d06584282390c3629 Mon Sep 17 00:00:00 2001 From: Frank Harris Date: Mon, 8 Jun 2026 11:33:22 -0500 Subject: [PATCH] docs --- OGP64/OGP/documentation/agent-guide.md | 2 ++ README.md | 40 ++++++++++++++++++++++++++ docs/AGENT_ARCHITECTURE.md | 27 +++++++++++++++++ docs/COMMAND_EXECUTION.md | 25 ++++++++++++++++ docs/CYGWIN_INTEGRATION.md | 20 +++++++++++++ docs/PANEL_INTEGRATION.md | 15 ++++++++++ docs/PROCESS_MANAGEMENT.md | 23 +++++++++++++++ 7 files changed, 152 insertions(+) create mode 100644 README.md create mode 100644 docs/AGENT_ARCHITECTURE.md create mode 100644 docs/COMMAND_EXECUTION.md create mode 100644 docs/CYGWIN_INTEGRATION.md create mode 100644 docs/PANEL_INTEGRATION.md create mode 100644 docs/PROCESS_MANAGEMENT.md diff --git a/OGP64/OGP/documentation/agent-guide.md b/OGP64/OGP/documentation/agent-guide.md index 1c5f2fe..846ec99 100644 --- a/OGP64/OGP/documentation/agent-guide.md +++ b/OGP64/OGP/documentation/agent-guide.md @@ -2,6 +2,8 @@ This Markdown file mirrors the internal WDS wiki instructions so you can ship it with release archives or import it into any other knowledge base. +Workspace reference: [`GSP-WORKSPACE.md`](../../../../GSP-WORKSPACE.md) + ## Purpose The Windows agent bundles Cygwin, Perl, GNU Screen, and helper scripts so the GameServer Panel can manage Windows Server 2019/2022 game hosts. It exposes the same RPC surface as the Linux agent and expects the same shared key. diff --git a/README.md b/README.md new file mode 100644 index 0000000..c69e22b --- /dev/null +++ b/README.md @@ -0,0 +1,40 @@ +# GSP Windows Agent + +Cygwin-based packaging tree for the GSP Windows agent. The maintained runtime lives under `OGP64/`, which contains the Cygwin environment, the bundled OGP Perl agent, startup scripts, and supporting files. + +Workspace reference: [`GSP-WORKSPACE.md`](../GSP-WORKSPACE.md) + +## What this repository owns + +- Windows/Cygwin agent packaging +- startup and stop scripts +- bundled runtime files for the OGP Perl agent +- Windows-specific installation and update helpers +- Windows agent documentation + +## Runtime model + +The Windows agent mirrors the Linux agent as closely as practical while using Cygwin to provide the command and process model expected by the OGP Perl agent. + +## Important paths + +| Path | Purpose | +| --- | --- | +| `OGP64/` | Cygwin root and runtime bundle | +| `OGP64/OGP/ogp_agent.pl` | Core Windows agent Perl service | +| `OGP64/agent_start.bat` | Root launcher used to start the agent manually | +| `OGP64/agent_stop.bat` | Root launcher used to stop the agent manually | +| `OGP64/OGP/Cfg/` | Runtime config and template files | + +## Documentation entry points + +- [`docs/AGENT_ARCHITECTURE.md`](docs/AGENT_ARCHITECTURE.md) +- [`docs/CYGWIN_INTEGRATION.md`](docs/CYGWIN_INTEGRATION.md) +- [`docs/COMMAND_EXECUTION.md`](docs/COMMAND_EXECUTION.md) +- [`docs/PROCESS_MANAGEMENT.md`](docs/PROCESS_MANAGEMENT.md) +- [`docs/PANEL_INTEGRATION.md`](docs/PANEL_INTEGRATION.md) + +## Related documentation + +- [`OGP64/OGP/README.md`](OGP64/OGP/README.md) +- [`OGP64/OGP/documentation/agent-guide.md`](OGP64/OGP/documentation/agent-guide.md) diff --git a/docs/AGENT_ARCHITECTURE.md b/docs/AGENT_ARCHITECTURE.md new file mode 100644 index 0000000..59cfe5a --- /dev/null +++ b/docs/AGENT_ARCHITECTURE.md @@ -0,0 +1,27 @@ +# GSP Windows Agent Architecture + +Workspace reference: [`GSP-WORKSPACE.md`](../../GSP-WORKSPACE.md) + +This repository owns the Windows execution engine for GSP. + +## Responsibilities + +- expose the same agent RPC surface as the Linux agent +- launch and monitor customer game servers on Windows +- manage lifecycle operations using Cygwin-compatible tooling +- execute panel-approved commands and scripts +- return logs, status, and command results + +## Primary runtime pieces + +| 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 | + +## Design rule + +Keep the Windows agent behavior as close to Linux as possible, but isolate unavoidable platform differences in the Windows layer. diff --git a/docs/COMMAND_EXECUTION.md b/docs/COMMAND_EXECUTION.md new file mode 100644 index 0000000..09f9c4e --- /dev/null +++ b/docs/COMMAND_EXECUTION.md @@ -0,0 +1,25 @@ +# GSP Windows Agent Command Execution + +Workspace reference: [`GSP-WORKSPACE.md`](../../GSP-WORKSPACE.md) + +The Panel sends remote requests to the Windows agent. The agent translates those requests into local actions inside the Cygwin runtime. + +## Execution model + +1. Receive a panel request. +2. Validate the request. +3. Run the requested command or lifecycle action through the agent runtime. +4. Capture output and exit status. +5. Return the result to the Panel. + +## Common actions + +- start / stop / restart servers +- install or update files +- inspect logs +- report process state +- run scheduled maintenance + +## Rule + +Do not allow customer input to become arbitrary shell code. The agent should only execute validated, panel-generated requests. diff --git a/docs/CYGWIN_INTEGRATION.md b/docs/CYGWIN_INTEGRATION.md new file mode 100644 index 0000000..a628052 --- /dev/null +++ b/docs/CYGWIN_INTEGRATION.md @@ -0,0 +1,20 @@ +# GSP Windows Agent Cygwin Integration + +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. + +## What Cygwin provides + +- `bash` +- GNU Screen-compatible behavior where used +- Perl runtime compatibility +- Unix-style path and shell semantics for the agent scripts + +## 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. + +## Maintenance rule + +Keep Cygwin-specific behavior isolated to this repository so the Panel can continue to treat the Windows and Linux agents as equivalent execution targets. diff --git a/docs/PANEL_INTEGRATION.md b/docs/PANEL_INTEGRATION.md new file mode 100644 index 0000000..554cd62 --- /dev/null +++ b/docs/PANEL_INTEGRATION.md @@ -0,0 +1,15 @@ +# GSP Windows Agent Panel Integration + +Workspace reference: [`GSP-WORKSPACE.md`](../../GSP-WORKSPACE.md) + +The Panel is authoritative. The Windows agent executes the work the Panel requests. + +## Integration points + +- 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 + +## 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. diff --git a/docs/PROCESS_MANAGEMENT.md b/docs/PROCESS_MANAGEMENT.md new file mode 100644 index 0000000..dc87806 --- /dev/null +++ b/docs/PROCESS_MANAGEMENT.md @@ -0,0 +1,23 @@ +# GSP Windows Agent Process Management + +Workspace reference: [`GSP-WORKSPACE.md`](../../GSP-WORKSPACE.md) + +The Windows agent manages customer servers through the Cygwin runtime and the OGP Perl agent. + +## Current model + +- `OGP64` is the Cygwin root for the maintained launcher +- process state is tracked through the agent runtime and PID files +- 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/` + +## Rule + +Keep startup and stop behavior visible and explicit. Failures should be reported in the same console when launched manually.