Add optional server-side player keepalive to reap dead connections (#912)

Author: marekl11

.changeset/server-player-keepalive.md

@@ -0,0 +1,6 @@
+---
+'@epicgames-ps/lib-pixelstreamingsignalling-ue5.7': patch
+'@epicgames-ps/wilbur': patch
+---
+
+Add an optional server-side keepalive that disconnects players whose connection has died without a clean close. Previously `KeepaliveMonitor` was only used on the client, so a player whose socket dropped silently (sleeping laptop, lost Wi-Fi, killed tab) stayed subscribed until the OS TCP keepalive reaped it, which could hold a `maxSubscribers` slot in the meantime. The new `IServerConfig.playerKeepaliveTimeout` controls this; the signalling server exposes it as `--player_keepalive_timeout <milliseconds>` (default 30000, 0 disables).

Signalling/src/SignallingServer.ts

@@ -8,7 +8,12 @@ import { SFUConnection } from './SFUConnection';
 import { Logger } from './Logger';
 import { StreamerRegistry } from './StreamerRegistry';
 import { PlayerRegistry } from './PlayerRegistry';
-import { Messages, MessageHelpers, SignallingProtocol } from '@epicgames-ps/lib-pixelstreamingcommon-ue5.7';
+import {
+    Messages,
+    MessageHelpers,
+    SignallingProtocol,
+    KeepaliveMonitor
+} from '@epicgames-ps/lib-pixelstreamingcommon-ue5.7';
 import { stringify } from './Utils';
 
 /**
@@ -45,6 +50,10 @@ export interface IServerConfig {
 
     // Max number of players per streamer.
     maxSubscribers?: number;
+
+    // Idle timeout in milliseconds after which a player that has stopped responding to keepalive
+    // pings is forcibly disconnected. 0 (the default) disables the check.
+    playerKeepaliveTimeout?: number;
 }
 
 export type ProtocolConfig = {
@@ -159,6 +168,25 @@ export class SignallingServer {
             Logger.info(`Player %s (%s) disconnected.`, newPlayer.playerId, request.socket.remoteAddress);
         });
 
+        // Optionally monitor the player connection for liveness. A player whose socket dies without
+        // a clean close frame (sleeping laptop, dropped Wi-Fi, killed tab) is otherwise only removed
+        // once the OS TCP keepalive eventually reaps it, leaving it subscribed in the meantime. When
+        // maxSubscribers is set this can hold a slot that no live player is using. We use
+        // ws.terminate() rather than a graceful close because a dead peer never completes the close
+        // handshake. The monitor stops itself on transport 'close', so no manual teardown is needed.
+        const keepaliveTimeout = this.config.playerKeepaliveTimeout || 0;
+        if (keepaliveTimeout > 0) {
+            const keepalive = new KeepaliveMonitor(newPlayer.protocol, keepaliveTimeout);
+            keepalive.onTimeout = () => {
+                Logger.info(
+                    `Player %s (%s) failed keepalive - terminating dead connection.`,
+                    newPlayer.playerId,
+                    request.socket.remoteAddress
+                );
+                ws.terminate();
+            };
+        }
+
         this.sendConfigMessage(newPlayer);
     }
 

SignallingWebServer/README.md

@@ -50,6 +50,8 @@ Options:
   --player_port <port>          Sets the listening port for player connections. (default: "80")
   --sfu_port <port>             Sets the listening port for SFU connections. (default: "8889")
   --max_players <number>        Sets the maximum number of subscribers per streamer. 0 = unlimited (default: "0")
+  --player_keepalive_timeout <milliseconds>
+                                Disconnect a player after this many milliseconds without a keepalive response. 0 = disabled (default: "30000")
   --serve                       Enables the webserver on player_port. (default: true)
   --http_root <path>            Sets the path for the webserver root. (default: "D:\\PixelStreamingInfrastructure\\SignallingWebServer\\www")
   --homepage <filename>         The default html file to serve on the web server. (default: "player.html")

SignallingWebServer/src/index.ts

@@ -108,6 +108,11 @@ program
         'Sets the maximum number of subscribers per streamer. 0 = unlimited',
         config_file.max_players || '0'
     )
+    .option(
+        '--player_keepalive_timeout <milliseconds>',
+        'Disconnect a player after this many milliseconds without a keepalive response. 0 = disabled',
+        config_file.player_keepalive_timeout || '30000'
+    )
     .option('--serve', 'Enables the webserver on player_port.', config_file.serve || false)
     .option(
         '--http_root <path>',
@@ -270,7 +275,8 @@ const serverOpts: IServerConfig = {
     playerPort: options.player_port,
     sfuPort: options.sfu_port,
     peerOptions: options.peer_options,
-    maxSubscribers: options.max_players
+    maxSubscribers: options.max_players,
+    playerKeepaliveTimeout: Number(options.player_keepalive_timeout)
 };
 
 const shouldServerStart = options.serve || options.rest_api;