This commit is contained in:
Frank Harris 2026-07-02 18:11:32 -05:00
parent a49371c3dd
commit 251af10faf
1190 changed files with 12636 additions and 12476 deletions

12
.github/agent.md vendored
View file

@ -4,7 +4,7 @@
**Prime directive:** Read this document first. Keep `.github/agent.md` identical to this file—any edit here must be mirrored there in the same commit.
## Workspace deliverables (WDS 2025 refresh)
- Use the GSP/WDS/GSW branding across UI, docs, and comments; when heritage context matters add: “GSP is a heavily customized fork of OGP maintained by WDS.”
- Use the GSP/WDS/GSW branding across UI, docs, and comments; when heritage context matters add: “GSP is a heavily customized fork of GSP maintained by WDS.”
- Keep `bootstrap/` current: Ubuntu 24.04 panel + agent installers, Windows Server 2019 (Cygwin) agent installer + service wrapper, and the optional `docker/compose.yml` dev stack. All scripts must be idempotent, echo next steps, and document verify/rollback procedures in their README files.
- Author and maintain admin-only docs in `WDS_Website/content/projects/gsp.md` and `content/docs/gsp/*` (front-matter + the **Admin Documentation** banner). Cross-link these guides from panel features that need deep dives.
- Refresh user-facing help in `Panel/modules/faq/` (RSS + UI) so the seven core topics—panel basics, file browser, Adminer/MySQL, FTP/SFTP, task scheduler, sub-users, and support—link to the latest WDS admin docs.
@ -48,7 +48,7 @@ header('Location: /modules/billing/cart.php');
- `Website/` storefront runtime, payment handlers, provisioning bridge.
- `Panel/modules/config_games/server_configs/` authoritative XML metadata for every supported game.
- `Panel/modules/` control-panel modules.
- `Panel/includes/` & `Panel/ogp_api.php` database layer, shared helpers, remote agent operations.
- `Panel/includes/` & `Panel/gsp_api.php` database layer, shared helpers, remote agent operations.
## 2) Planning mode (default)
While scoping multi-file work, do **not** emit PHP/SQL/XML or run shell commands unless a maintainer explicitly says “Generate code now.” Plans should cover:
@ -57,14 +57,14 @@ While scoping multi-file work, do **not** emit PHP/SQL/XML or run shell commands
- Risks, rollback notes, validation/tests.
## 3) Scope & principles
- **Single session across panel + storefront.** Every billing page must call `session_name('opengamepanel_web')` before `session_start()`. Always keep `$_SESSION['user_id']`, `$_SESSION['users_login']`, `$_SESSION['users_group']`, and `$_SESSION['website_user_id']` in sync so that logging into either surface signs the visitor into both.
- **Single session across panel + storefront.** Every billing page must call `session_name('gameserverpanel_web')` before `session_start()`. Always keep `$_SESSION['user_id']`, `$_SESSION['users_login']`, `$_SESSION['users_group']`, and `$_SESSION['website_user_id']` in sync so that logging into either surface signs the visitor into both.
- **Auth reuse.** Preferred order when verifying credentials: `users_pass_hash` (modern hash) → legacy `users_passwd` (MD5). Upgrading to a modern hash is allowed so long as panel logins keep working.
- **Bridge for panel helpers.** Use `Website/includes/panel_bridge.php` to load panel classes (`OGPDatabase`, `OGPRemoteLibrary`, XML parsers) when the storefront needs to provision servers or read panel-only metadata. Do not reinvent ad-hoc copies of panel logic.
- **Storefront runtime.** Public pages continue to use mysqli with credentials from `Website/includes/config.inc.php`. Provisioning steps may request an `OGPDatabase` handle from the bridge.
- **Bridge for panel helpers.** Use `Website/includes/panel_bridge.php` to load panel classes (`GSPDatabase`, `GSPRemoteLibrary`, XML parsers) when the storefront needs to provision servers or read panel-only metadata. Do not reinvent ad-hoc copies of panel logic.
- **Storefront runtime.** Public pages continue to use mysqli with credentials from `Website/includes/config.inc.php`. Provisioning steps may request an `GSPDatabase` handle from the bridge.
- **Provisioning pipeline.** Always funnel server creation or renewals through the shared provisioner (`Website/includes/provisioner.php`). This helper wraps the old `create_servers.php` logic and ensures PayPal captures, cron jobs, and panel clicks all follow the same code path.
- **Catalog = XML.** Never hardcode game metadata. Parse `Panel/modules/config_games/server_configs/*.xml` at runtime; new XMLs must show up automatically.
- **Regions/Nodes = live DB.** Pull nodes/locations from the panel DB (`gsp_remote_servers`, etc.). Respect admin enable/disable flags and never mirror node lists into flat files.
- **Game XML wiki parity.** We ship a PHP-rendered version of https://github.com/OpenGamePanel/OGP-Website/wiki/XML-Notes inside `Website/` (linked from the storefront admin area). Keep it updated so maintainers can edit XMLs without leaving the repo.
- **Game XML wiki parity.** We ship a PHP-rendered version of https://github.com/GameServerPanel/GSP-Panel/wiki/XML-Notes inside `Website/` (linked from the storefront admin area). Keep it updated so maintainers can edit XMLs without leaving the repo.
## 4) Functional requirements
### 4.1 Catalog (from XML)

View file

@ -4,7 +4,7 @@
**Prime directive:** Read this document first. Keep `.github/agent.md` identical to this file—any edit here must be mirrored there in the same commit.
## Workspace deliverables (WDS 2025 refresh)
- Use the GSP/WDS/GSW branding across UI, docs, and comments; when heritage context matters add: “GSP is a heavily customized fork of OGP maintained by WDS.”
- Use the GSP/WDS/GSW branding across UI, docs, and comments; when heritage context matters add: “GSP is a heavily customized fork of GSP maintained by WDS.”
- Keep `bootstrap/` current: Ubuntu 24.04 panel + agent installers, Windows Server 2019 (Cygwin) agent installer + service wrapper, and the optional `docker/compose.yml` dev stack. All scripts must be idempotent, echo next steps, and document verify/rollback procedures in their README files.
- Author and maintain admin-only docs in `WDS_Website/content/projects/gsp.md` and `content/docs/gsp/*` (front-matter + the **Admin Documentation** banner). Cross-link these guides from panel features that need deep dives.
- Refresh user-facing help in `Panel/modules/faq/` (RSS + UI) so the seven core topics—panel basics, file browser, Adminer/MySQL, FTP/SFTP, task scheduler, sub-users, and support—link to the latest WDS admin docs.
@ -48,7 +48,7 @@ header('Location: /modules/billing/cart.php');
- `Website/` storefront runtime, payment handlers, provisioning bridge.
- `Panel/modules/config_games/server_configs/` authoritative XML metadata for every supported game.
- `Panel/modules/` control-panel modules.
- `Panel/includes/` & `Panel/ogp_api.php` database layer, shared helpers, remote agent operations.
- `Panel/includes/` & `Panel/gsp_api.php` database layer, shared helpers, remote agent operations.
## 2) Planning mode (default)
While scoping multi-file work, do **not** emit PHP/SQL/XML or run shell commands unless a maintainer explicitly says “Generate code now.” Plans should cover:
@ -57,14 +57,14 @@ While scoping multi-file work, do **not** emit PHP/SQL/XML or run shell commands
- Risks, rollback notes, validation/tests.
## 3) Scope & principles
- **Single session across panel + storefront.** Every billing page must call `session_name('opengamepanel_web')` before `session_start()`. Always keep `$_SESSION['user_id']`, `$_SESSION['users_login']`, `$_SESSION['users_group']`, and `$_SESSION['website_user_id']` in sync so that logging into either surface signs the visitor into both.
- **Single session across panel + storefront.** Every billing page must call `session_name('gameserverpanel_web')` before `session_start()`. Always keep `$_SESSION['user_id']`, `$_SESSION['users_login']`, `$_SESSION['users_group']`, and `$_SESSION['website_user_id']` in sync so that logging into either surface signs the visitor into both.
- **Auth reuse.** Preferred order when verifying credentials: `users_pass_hash` (modern hash) → legacy `users_passwd` (MD5). Upgrading to a modern hash is allowed so long as panel logins keep working.
- **Bridge for panel helpers.** Use `Website/includes/panel_bridge.php` to load panel classes (`OGPDatabase`, `OGPRemoteLibrary`, XML parsers) when the storefront needs to provision servers or read panel-only metadata. Do not reinvent ad-hoc copies of panel logic.
- **Storefront runtime.** Public pages continue to use mysqli with credentials from `Website/includes/config.inc.php`. Provisioning steps may request an `OGPDatabase` handle from the bridge.
- **Bridge for panel helpers.** Use `Website/includes/panel_bridge.php` to load panel classes (`GSPDatabase`, `GSPRemoteLibrary`, XML parsers) when the storefront needs to provision servers or read panel-only metadata. Do not reinvent ad-hoc copies of panel logic.
- **Storefront runtime.** Public pages continue to use mysqli with credentials from `Website/includes/config.inc.php`. Provisioning steps may request an `GSPDatabase` handle from the bridge.
- **Provisioning pipeline.** Always funnel server creation or renewals through the shared provisioner (`Website/includes/provisioner.php`). This helper wraps the old `create_servers.php` logic and ensures PayPal captures, cron jobs, and panel clicks all follow the same code path.
- **Catalog = XML.** Never hardcode game metadata. Parse `Panel/modules/config_games/server_configs/*.xml` at runtime; new XMLs must show up automatically.
- **Regions/Nodes = live DB.** Pull nodes/locations from the panel DB (`gsp_remote_servers`, etc.). Respect admin enable/disable flags and never mirror node lists into flat files.
- **Game XML wiki parity.** We ship a PHP-rendered version of https://github.com/OpenGamePanel/OGP-Website/wiki/XML-Notes inside `Website/` (linked from the storefront admin area). Keep it updated so maintainers can edit XMLs without leaving the repo.
- **Game XML wiki parity.** We ship a PHP-rendered version of https://github.com/GameServerPanel/GSP-Panel/wiki/XML-Notes inside `Website/` (linked from the storefront admin area). Keep it updated so maintainers can edit XMLs without leaving the repo.
## 4) Functional requirements
### 4.1 Catalog (from XML)

16
.github/module-map.md vendored
View file

@ -6,16 +6,16 @@ This file captures how the control panel, storefront, agents, and helper scripts
| Area | Key files | Responsibilities | Downstream callers |
| --- | --- | --- | --- |
| Database bootstrap | `Panel/includes/functions.php`, `Panel/includes/database_mysqli.php` | Creates the `OGPDatabase` instance and exposes helpers such as `resultQuery()`, `addGameHome()`, and logging. | Every panel page, `Website/Website/includes/panel_bridge.php`, cron jobs. |
| Session helpers | `includes/helpers.php` (`startSession()`) | Sets `session_name('opengamepanel_web')`, sanitizes request vars, loads locales. | `index.php`, `home.php`, provisioning pages, storefront session bridge. |
| Database bootstrap | `Panel/includes/functions.php`, `Panel/includes/database_mysqli.php` | Creates the `GSPDatabase` instance and exposes helpers such as `resultQuery()`, `addGameHome()`, and logging. | Every panel page, `Website/Website/includes/panel_bridge.php`, cron jobs. |
| Session helpers | `includes/helpers.php` (`startSession()`) | Sets `session_name('gameserverpanel_web')`, sanitizes request vars, loads locales. | `index.php`, `home.php`, provisioning pages, storefront session bridge. |
| Remote control | `Panel/includes/lib_remote.php` | Wraps agent RPC (install/update, FTP user management, rsync, SteamCMD). | `Panel/modules/gamemanager/*`, `Website/create_servers.php`, cron jobs. |
| XML parser | `Panel/modules/config_games/server_config_parser.php` | Converts `Panel/modules/config_games/server_configs/*.xml` into PHP arrays used for provisioning and pricing metadata. | `Panel/modules/gamemanager`, `Website/` (catalog + provisioner), cron installers. |
| API surface | `ogp_api.php`, `includes/api_functions.php` | HTTP API for third-party tooling. Exposes operations such as starting/stopping homes, querying stats. | Mobile apps, automated provisioning, selected billing workflows. |
| API surface | `gsp_api.php`, `includes/api_functions.php` | HTTP API for third-party tooling. Exposes operations such as starting/stopping homes, querying stats. | Mobile apps, automated provisioning, selected billing workflows. |
| Cron/automation | `scripts/` (`cron-shop.php`, `status/*`, etc.) | Suspends/unsuspends services, refreshes status caches, runs backups. | Triggered via system cron or panel scheduler. |
## High-level flows
1. **Auth/session** Driven by `index.php` (panel) and `Website/login.php` (storefront). Both set `$_SESSION['user_id']`, `users_login`, `users_group`, and `website_user_id`. The shared session cookie `opengamepanel_web` means logging into either surface immediately authenticates the other.
1. **Auth/session** Driven by `index.php` (panel) and `Website/login.php` (storefront). Both set `$_SESSION['user_id']`, `users_login`, `users_group`, and `website_user_id`. The shared session cookie `gameserverpanel_web` means logging into either surface immediately authenticates the other.
2. **Catalog** `modules/config_games` hosts XML definitions. Panel modules (`gamemanager`, `config_games`) and storefront pages (`serverlist.php`, `order.php`, documentation pages, and the XML-notes mirror) parse these files for display and provisioning metadata.
3. **Provisioning** Orders land in `gsp_billing_orders`. `Website/create_servers.php` allocates homes, assigns nodes/IPs, configures mods, kicks off SteamCMD/rsync/manual installers, and then syncs the resulting `home_id` back into `billing_orders`, `billing_invoices`, and `billing_transactions` so paid services never stay orphaned. The same provisioner is invoked by:
- PayPal capture endpoint (`Website/api/capture_order.php`).
@ -40,14 +40,14 @@ This file captures how the control panel, storefront, agents, and helper scripts
| `extras`, `addonsmanager` | Workshop/add-on management. Server Content workshop installs now share validation/runtime helpers across admin, user, and API flows, and sync bundled workshop scripts into each homes `gsp_server_content/scripts/workshop/` directory before execution. | Hooks into game homes after provisioning and uses agent-side SteamCMD copy/install workflows. |
| `litefm`, `ftp`, `TS3Admin` | File managers and TeamSpeak controllers. | Depend on homes and remote server credentials set during provisioning. |
| `news`, `circular`, `faq` | Content modules for panel UI. | Use standard MVC wrappers, share session/auth. |
| `cron` | Scheduler UI feeding `scripts/` commands. | Maintains job metadata that OS cron reads, including scheduler-triggered Server Content actions via `ogp_api.php?server_content/run_scheduled_action` and `modules/addonsmanager/server_content_actions.php`. |
| `cron` | Scheduler UI feeding `scripts/` commands. | Maintains job metadata that OS cron reads, including scheduler-triggered Server Content actions via `gsp_api.php?server_content/run_scheduled_action` and `modules/addonsmanager/server_content_actions.php`. |
## Storefront (`Panel/modules/billing` runtime + `Website/` compatibility wrappers)
| Area | Key files | Notes |
| --- | --- | --- |
| Public pages | `Panel/modules/billing/index.php`, `serverlist.php`, `order.php`, `cart.php`, `payment_success.php`, `docs.php` | Runtime now lives under `Panel/modules/billing`. `Website/*.php` wrappers proxy legacy paths to these files. |
| Auth | `Panel/modules/billing/login.php`, `register.php`, `reset_password.php`, `forgot_password.php`, `includes/login_required.php`, `includes/admin_auth.php` | Share `opengamepanel_web` session, call into panel DB to validate roles. |
| Auth | `Panel/modules/billing/login.php`, `register.php`, `reset_password.php`, `forgot_password.php`, `includes/login_required.php`, `includes/admin_auth.php` | Share `gameserverpanel_web` session, call into panel DB to validate roles. |
| Admin | `Panel/modules/billing/admin.php`, `adminserverlist.php`, `admin_orders.php`, `admin_coupons.php`, `admin_config.php`, `my_orders_panel.php` | Manage services, coupons, prices, and provisioning. `adminserverlist.php` controls service availability per node. |
| PayPal API | `Panel/modules/billing/api/create_order.php`, `api/capture_order.php`, `paypal/webhook.php`, `logs/payment_capture.log` | Implements REST checkout. Legacy `Website/api/*` and `Website/paypal/webhook.php` wrappers proxy to module runtime. |
| Provisioning bridge | `Panel/modules/billing/create_servers.php`, `includes/provisioner.php`, `includes/panel_bridge.php` | Shared between panel module and storefront backend. Encapsulates whole server creation/renewal pipeline. |
@ -67,11 +67,11 @@ This file captures how the control panel, storefront, agents, and helper scripts
- **Users** `gsp_users` table is shared. Registration uses `Website/register.php`, admin pages use `Panel/modules/user_admin`. Password upgrades must not break panel logins.
- **Billing tables** `gsp_billing_services`, `gsp_billing_orders`, `gsp_billing_invoices`, `gsp_billing_coupons`. Admin edits (pricing, enable/disable, locations) are done via `adminserverlist.php`; automation uses `cron-shop.php`.
- **Homes/Mods/IPs** Stored in `gsp_game_homes`, `gsp_game_mods`, `gsp_remote_server_ips`. Provisioner writes to these tables; `gamemanager`, `litefm`, `ftp`, and `user_games` read them.
- **Logging** `$db->logger()` writes to `ogp_logs`. Storefront-specific logs live in `Website/logs/` for quick inspection (payment capture, provisioning outcomes, coupon usage).
- **Logging** `$db->logger()` writes to `gsp_logs`. Storefront-specific logs live in `Website/logs/` for quick inspection (payment capture, provisioning outcomes, coupon usage).
## Usage tips
1. **Need a DB object inside `Website/`?** Include `Website/includes/panel_bridge.php` and call `billing_get_panel_db()`. It sets up constants, loads helpers, and caches the `OGPDatabase` instance so multi-call flows (e.g., capture → provision → email) reuse it.
1. **Need a DB object inside `Website/`?** Include `Website/includes/panel_bridge.php` and call `billing_get_panel_db()`. It sets up constants, loads helpers, and caches the `GSPDatabase` instance so multi-call flows (e.g., capture → provision → email) reuse it.
2. **Want to change provisioning?** Update `Website/includes/provisioner.php` once. `create_servers.php`, PayPal webhooks, cron jobs, and admin repair flows all use it.
3. **Working on XML or documentation?** Update the XML file under `Panel/modules/config_games/server_configs/`, regenerate docs if needed, and keep the PHP XML-notes mirror (`Website/docs/xml_notes.php`) accurate so the admin link stays trustworthy.
4. **Need to know who uses a table?** Search `.github/module-map.md` first; the table above lists the canonical readers/writers for each major schema.