docs: add analysis on ghost process and launcher cleanup

2026-02-26 09:21:48 -03:00 · 2026-02-01 23:16:26 +08:00
parent 6ee23e1944
commit 38d436ceb7
4 changed files with 636 additions and 0 deletions
--- a/docs/LAUNCHER_TERMINATION_ANALYSIS.md
+++ b/docs/LAUNCHER_TERMINATION_ANALYSIS.md
@@ -0,0 +1,273 @@
+# Launcher Process Termination & Cleanup Analysis
+
+## Overview
+This document analyzes how the Hytale-F2P launcher handles process cleanup, event termination, and resource deallocation during shutdown.
+
+## Shutdown Flow
+
+### 1. **Primary Termination Events** (main.js)
+
+#### Event: `before-quit` (Line 438)
+```javascript
+app.on('before-quit', () => {
+  console.log('=== LAUNCHER BEFORE QUIT ===');
+  cleanupDiscordRPC();
+});
+```
+- Called by Electron before the app starts quitting
+- Ensures Discord RPC is properly disconnected and destroyed
+- Gives async cleanup a chance to run
+
+#### Event: `window-all-closed` (Line 443)
+```javascript
+app.on('window-all-closed', () => {
+  console.log('=== LAUNCHER CLOSING ===');
+  app.quit();
+});
+```
+- Triggered when all Electron windows are closed
+- Initiates app.quit() to cleanly exit
+
+#### Event: `closed` (Line 174)
+```javascript
+mainWindow.on('closed', () => {
+  console.log('Main window closed, cleaning up Discord RPC...');
+  cleanupDiscordRPC();
+});
+```
+- Called when the main window is actually destroyed
+- Additional Discord RPC cleanup as safety measure
+
+---
+
+## 2. **Discord RPC Cleanup** (Lines 59-89, 424-436)
+
+### cleanupDiscordRPC() Function
+```javascript
+async function cleanupDiscordRPC() {
+  if (!discordRPC) return;
+  try {
+    console.log('Cleaning up Discord RPC...');
+    discordRPC.clearActivity();
+    await new Promise(r => setTimeout(r, 100));  // Wait for clear to propagate
+    discordRPC.destroy();
+    console.log('Discord RPC cleaned up successfully');
+  } catch (error) {
+    console.log('Error cleaning up Discord RPC:', error.message);
+  } finally {
+    discordRPC = null;  // Null out the reference
+  }
+}
+```
+
+**What it does:**
+1. Checks if Discord RPC is initialized
+2. Clears the current activity (disconnects from Discord)
+3. Waits 100ms for the clear to propagate
+4. Destroys the Discord RPC client
+5. Nulls out the reference to prevent memory leaks
+6. Error handling ensures cleanup doesn't crash the app
+
+**Quality:** ✅ **Proper cleanup with error handling**
+
+---
+
+## 3. **Game Process Handling** (gameLauncher.js)
+
+### Game Launch Process (Lines 356-403)
+
+```javascript
+let spawnOptions = {
+  stdio: ['ignore', 'pipe', 'pipe'],
+  detached: false,
+  env: env
+};
+
+if (process.platform === 'win32') {
+  spawnOptions.shell = false;
+  spawnOptions.windowsHide = true;
+  spawnOptions.detached = true;      // ← Game runs independently
+  spawnOptions.stdio = 'ignore';     // ← Fully detach stdio
+}
+
+const child = spawn(clientPath, args, spawnOptions);
+
+// Windows: Release process reference immediately
+if (process.platform === 'win32') {
+  child.unref();  // ← Allows Node.js to exit without waiting for game
+}
+```
+
+**Critical Analysis:**
+- ✅ **Windows detached mode**: Game process is spawned detached and stdio is ignored
+- ✅ **child.unref()**: Removes the Node process from the event loop
+- ⚠️ **No event listeners**: Once detached, the launcher doesn't track the game process
+
+**Potential Issue:**
+The game process is completely detached and unrefed, which is correct. However, if the game crashes and respawns (or multiple instances), these orphaned processes could accumulate.
+
+---
+
+## 4. **Download/File Transfer Cleanup** (fileManager.js)
+
+### setInterval Cleanup (Lines 77-94)
+```javascript
+const overallTimeout = setInterval(() => {
+  const now = Date.now();
+  const timeSinceLastProgress = now - lastProgressTime;
+  
+  if (timeSinceLastProgress > 900000 && hasReceivedData) {
+    console.log('Download stalled for 15 minutes, aborting...');
+    controller.abort();
+  }
+}, 60000);  // Check every minute
+```
+
+### Cleanup Locations:
+
+**On Stream Error (Lines 225-228):**
+```javascript
+if (stalledTimeout) {
+  clearTimeout(stalledTimeout);
+}
+if (overallTimeout) {
+  clearInterval(overallTimeout);
+}
+```
+
+**On Stream Close (Lines 239-244):**
+```javascript
+if (stalledTimeout) {
+  clearTimeout(stalledTimeout);
+}
+if (overallTimeout) {
+  clearInterval(overallTimeout);
+}
+```
+
+**On Writer Finish (Lines 295-299):**
+```javascript
+if (stalledTimeout) {
+  clearTimeout(stalledTimeout);
+  console.log('Cleared stall timeout after writer finished');
+}
+if (overallTimeout) {
+  clearInterval(overallTimeout);
+  console.log('Cleared overall timeout after writer finished');
+}
+```
+
+**Quality:** ✅ **Proper cleanup with multiple safeguards**
+- Intervals are cleared in all exit paths
+- No orphaned setInterval/setTimeout calls
+
+---
+
+## 5. **Electron Auto-Updater** (Lines 184-237)
+
+```javascript
+autoUpdater.autoDownload = true;
+autoUpdater.autoInstallOnAppQuit = true;
+
+autoUpdater.on('update-downloaded', (info) => {
+  // ...
+});
+```
+
+**Auto-Updater Cleanup:** ✅
+- Electron handles auto-updater cleanup automatically
+- No explicit cleanup needed (Electron manages lifecycle)
+
+---
+
+## Summary: Process Termination Quality
+
+| Component | Status | Notes |
+|-----------|--------|-------|
+| **Discord RPC** | ✅ **Good** | Properly destroyed with error handling |
+| **Main Window** | ✅ **Good** | Cleanup called on closed and before-quit |
+| **Game Process** | ✅ **Good** | Detached and unref'd on Windows |
+| **Download Intervals** | ✅ **Good** | Cleared in all exit paths |
+| **Event Listeners** | ⚠️ **Mixed** | Main listeners properly removed, but IPC handlers remain registered (normal) |
+| **Overall** | ✅ **Good** | Proper cleanup architecture |
+
+---
+
+## Potential Improvements
+
+### 1. **Add Explicit Process Tracking (Optional)**
+Currently, the launcher doesn't track child processes. We could add:
+```javascript
+// Track all spawned processes for cleanup
+const childProcesses = new Set();
+
+app.on('before-quit', () => {
+  // Kill any remaining child processes
+  for (const proc of childProcesses) {
+    if (proc && !proc.killed) {
+      proc.kill('SIGTERM');
+    }
+  }
+});
+```
+
+### 2. **Auto-Updater Resource Cleanup (Minor)**
+Add explicit cleanup for auto-updater listeners:
+```javascript
+app.on('before-quit', () => {
+  autoUpdater.removeAllListeners();
+});
+```
+
+### 3. **Graceful Shutdown Timeout (Safety)**
+Add a safety timeout to force exit if cleanup hangs:
+```javascript
+app.on('before-quit', () => {
+  const forceExitTimeout = setTimeout(() => {
+    console.warn('Cleanup timeout - forcing exit');
+    process.exit(0);
+  }, 5000);  // 5 second max cleanup time
+});
+```
+
+---
+
+## Relationship to Ghost Process Issue
+
+### Previous Issue (PowerShell processes)
+- **Root cause**: Spawned PowerShell processes weren't cleaned up in `platformUtils.js`
+- **Fixed by**: Replacing `execSync()` with `spawnSync()` + timeouts
+
+### Launcher Termination
+- **Status**: ✅ **No critical issues found**
+- **Discord RPC**: Properly cleaned up
+- **Game process**: Properly detached
+- **Intervals**: Properly cleared
+- **No memory leaks detected**
+
+The launcher's termination flow is solid. The ghost process issue was specific to PowerShell process spawning during GPU detection, not the launcher's shutdown process.
+
+---
+
+## Testing Checklist
+
+To verify proper launcher termination:
+
+- [ ] Start launcher → Close window → Check Task Manager for lingering processes
+- [ ] Start launcher → Launch game → Close launcher → Check for orphaned processes
+- [ ] Start launcher → Download something → Cancel mid-download → Check for setInterval processes
+- [ ] Disable Discord RPC → Start launcher → Close → No Discord processes remain
+- [ ] Check Windows Event Viewer → No unhandled exceptions on launcher exit
+- [ ] Multiple launch/close cycles → No memory growth in Task Manager
+
+---
+
+## Conclusion
+
+The Hytale-F2P launcher has **good shutdown hygiene**:
+- ✅ Discord RPC is properly cleaned
+- ✅ Game process is properly detached
+- ✅ Download intervals are properly cleared
+- ✅ Event handlers are properly registered
+
+The ghost process issue was **not** caused by the launcher's termination logic, but by the PowerShell GPU detection functions, which has already been fixed.