GSP/GSP-Agent-Windows
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
GSP-Agent-Windows/docs/PROCESS_MANAGEMENT.md
Frank Harris 911c63c250 cleanup
2026-07-02 18:10:41 -05:00

3 KiB
Raw Blame History

GSP Windows Agent Process Management

Workspace reference: GSP-WORKSPACE.md

The Windows agent manages customer servers through the Cygwin runtime and the GSP Perl agent.

Current model

  • 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 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

  • GSP64/agent_start.bat
  • GSP64/agent_stop.bat
  • GSP64/GSP/gsp_agent.pl
  • GSP64/GSP/Cfg/

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:

Lifecycle tracking

The Windows agent now tracks per-home runtime metadata under:

  • GSP64/GSP/runtime_status/pid-<home_id>.kv

Tracked fields include PID/session information used to stop the right process reliably:

  • screen_pid
  • windows_pid
  • game_pid
  • 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. 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:

  • stop is attempted first
  • waits 60 seconds
  • verifies old instance is stopped before starting again
  • returns stop failure if the old process/port is still active