@resolveio/server-lib 22.2.33 → 22.2.34

package/src/server-app.ts

@@ -0,0 +1,2616 @@
+import * as express from 'express';
+import * as xmlParser from 'express-xml-bodyparser';
+import { createServer, Server } from 'http';
+import * as crypto from 'crypto';
+import * as fs from 'fs';
+import * as jwt from 'jsonwebtoken';
+import * as moment from 'moment-timezone';
+import { unpack } from 'msgpackr';
+import * as os from 'os';
+import * as path from 'path';
+import { monitorEventLoopDelay } from 'perf_hooks';
+import * as inspector from 'inspector';
+import { URL } from 'url';
+import * as WebSocket from 'ws';
+
+import { Logs } from './collections/log.collection';
+import { Users } from './collections/user.collection';
+import { CronManager } from './managers/cron.manager';
+import { MethodManager } from './managers/method.manager';
+import { MonitorManager, MonitorManagerFunction } from './managers/monitor.manager';
+import { SubscriptionManager } from './managers/subscription.manager';
+import { ServerResponseModel } from './models/server-message.model';
+import { dateReviver, getBinarySize, isAllowedOrigin, objectIdHexString, round } from './util/common';
+import { ErrorReporter } from './util/error-reporter';
+import { ensureErrorWithCorrelation } from './util/error-tracking';
+
+import { MongoNetworkTimeoutError } from 'mongodb';
+import { setupAuthRoutes } from './http/auth';
+import { setupHealthRoutes } from './http/health';
+import { setupHomeRoutes } from './http/home';
+import { setupSlowQueryPublicationRoutes } from './http/slow-query-publication';
+
+import { WebSocketManager } from './managers/websocket.manager';
+import { WorkerDispatcherManager } from './managers/worker-dispatcher.manager';
+import { WorkerServerManager } from './managers/worker-server.manager';
+import { ResolveIOServer } from './resolveio-server-app';
+
+export class ResolveIOMainServer {
+	private _app: express.Application;
+	private _serverHTTP: Server;
+	private _portHTTP: number;
+	private _serverWSS: WebSocket.Server;
+	private _offlineUpdates = [];
+	public sesMail = false;
+	private publicProgram = false;
+	private _rebootFlag = false;
+
+	private LOGGER = 'ERROR'; //ERROR / DEBUG
+
+	private _websocketManager: WebSocketManager;
+	private _monitorManager: MonitorManager;
+	private _monitorManagerFunction: MonitorManagerFunction;
+	private _subscriptionManager: SubscriptionManager;
+	private _methodManager: MethodManager;
+	private _cronManager: CronManager;
+	private _clientRoutes: string[] = [];
+	private _workerDispatcherManager: WorkerDispatcherManager;
+	private _workerServerManager: WorkerServerManager;
+	private _httpServerClosePromise: Promise<void> | null = null;
+	private _websocketServerClosePromise: Promise<void> | null = null;
+	private _wsConnectDebug = false;
+	private _perfDebug = false;
+	private _perfDebugIntervalMs = 2000;
+	private _perfDebugTimer: NodeJS.Timeout | null = null;
+	private _perfDebugLastCpu: NodeJS.CpuUsage | null = null;
+	private _perfDebugLastTs = 0;
+	private _eventLoopHistogram: ReturnType<typeof monitorEventLoopDelay> | null = null;
+	private _cpuProfileOnStart = false;
+	private _cpuProfileAuto = false;
+	private _cpuProfileDurationMs = 15000;
+	private _cpuProfileThresholdPct = 90;
+	private _cpuProfileTriggerCount = 3;
+	private _cpuProfileHighCount = 0;
+	private _cpuProfileDir: string | null = null;
+	private _cpuProfileSession: inspector.Session | null = null;
+	private _timerDebug = false;
+	private _timerDebugThresholdMs = 50;
+	private _timerDebugMinDelayMs = 5;
+	private _timerDebugSampleRate = 1;
+	private _timerDebugLogLimit = 100;
+	private _timerDebugLogCount = 0;
+	private _aiWorkerDebug = false;
+
+	private _serverStartTime: Date;
+	private _lastErrorMsg: Date = null;
+
+	private _debugMsgRecv = 0;
+	private _debugMsgQueue = 0;
+
+	private _isWorkersEnabled = false;
+	private _isWorkerInstance = false;
+
+	private _safeShutdown = false;
+	private _dynamicAppGatewayEnabled = false;
+	private _dynamicAppGatewayCache = new Map<string, { expiresAt: number; app: any }>();
+	private _socketTier = '';
+	private _maxClientSockets = 0;
+	private _singleIpPerUser = false;
+	private _socketPolicyUpgradeUrl = '';
+
+	private readonly _clientHeartbeatIntervalMs = 20000;
+	private readonly _clientHeartbeatInitialDelayMs = 5000;
+	private readonly _clientHeartbeatBackpressureBytes = 5 * 1024 * 1024;
+	private readonly _dynamicAppGatewayCacheMs = 30 * 1000;
+
+	constructor() {}
+
+	static async create() {
+		const resolveioMainServer = new ResolveIOMainServer();
+		await resolveioMainServer.initialize();
+		return resolveioMainServer;
+	}
+
+	private async initialize() {
+		this._serverStartTime = new Date();
+		this._lastErrorMsg = null;
+		this._wsConnectDebug = this.resolveConnectDebug();
+		this._perfDebug = this.resolvePerfDebug();
+		this._cpuProfileOnStart = this.resolveCpuProfileOnStart();
+		this._cpuProfileAuto = this.resolveCpuProfileAuto();
+		this._cpuProfileDurationMs = this.resolveCpuProfileDurationMs();
+		this._cpuProfileThresholdPct = this.resolveCpuProfileThresholdPct();
+		this._cpuProfileTriggerCount = this.resolveCpuProfileTriggerCount();
+		this._cpuProfileDir = this.resolveCpuProfileDir();
+		this._timerDebug = this.resolveTimerDebug();
+		this._timerDebugThresholdMs = this.resolveTimerDebugThresholdMs();
+		this._timerDebugMinDelayMs = this.resolveTimerDebugMinDelayMs();
+			this._timerDebugSampleRate = this.resolveTimerDebugSampleRate();
+			this._timerDebugLogLimit = this.resolveTimerDebugLogLimit();
+			this._aiWorkerDebug = this.parseDebugFlag(process.env.AI_ASSISTANT_WORKER_DEBUG);
+			this._dynamicAppGatewayEnabled = this.resolveDynamicAppGatewayEnabled();
+			this._socketTier = this.resolveSocketTier();
+			this._maxClientSockets = this.resolveMaxClientSockets(this._socketTier);
+			this._singleIpPerUser = this.resolveSingleIpPerUserPolicy(this._socketTier);
+			this._socketPolicyUpgradeUrl = this.resolveSocketPolicyUpgradeUrl();
+			if (this._maxClientSockets > 0 || this._singleIpPerUser) {
+				console.info(new Date(), '[Socket Policy] configured', {
+					tier: this._socketTier || 'none',
+					maxClientSockets: this._maxClientSockets,
+					singleIpPerUser: this._singleIpPerUser
+				});
+			}
+			this._monitorManager = await MonitorManager.create();
+		this._monitorManagerFunction = new MonitorManagerFunction();
+		this.installTimerDebug();
+		this.startPerfDebug();
+		if (this._cpuProfileOnStart) {
+			this.startCpuProfile('on-start');
+		}
+
+		// Check for workers and decide what to start
+		this._isWorkersEnabled = process.env.IS_WORKERS_ENABLED === 'true';
+		this._isWorkerInstance = process.env.IS_WORKER_INSTANCE === 'true';
+
+		setInterval(() => {
+			if (this._methodManager && this._methodManager.getEnableDebug()) {
+				console.log(new Date(), 'Server App', 'Msg Recv Hits', this._debugMsgRecv);
+				console.log(new Date(), 'Server App', 'Msg Queue Hits', this._debugMsgQueue);
+			}
+
+			this._debugMsgQueue = 0;
+			this._debugMsgRecv = 0;
+		}, 60000);
+
+		process.removeAllListeners('unhandledRejection');
+
+		process.on('unhandledRejection', async (error, rej) => {
+			const { error: normalizedError, correlationId } = ensureErrorWithCorrelation(error);
+
+			if (this._methodManager.getEnableDebug()) {
+				console.error(new Date(), 'ERROR DETECTED w/ Debug Flag Active: unhandledRejection', [normalizedError, rej, { correlationId }]);
+			}
+
+			// Condition to filter out the MongoError with specific codes
+			if (normalizedError && normalizedError['name'] === 'MongoError' && (normalizedError['code'] === 48 || normalizedError['code'] === 26 || normalizedError['code'] === 11000 || normalizedError['code'] === 251)) {
+				return; // Simply return without doing anything further
+			}
+
+			// if (normalizedError && normalizedError['name'] === 'MongoServerError' && (!initServerFlag || normalizedError['code'] === 26 || normalizedError['code'] === 11000 || normalizedError['code'] === 86 || normalizedError['code'] === 251)) {
+			// 	return; // Simply return without doing anything further
+			// }
+
+			if (normalizedError && normalizedError['name'] === 'MongoServerError') {
+				return; // Simply return without doing anything further
+			}
+
+			const errorDetails = {
+				id: correlationId,
+				name: normalizedError?.name,
+				message: normalizedError?.message,
+				stack: normalizedError?.stack,
+				code: normalizedError?.code,
+				codeName: normalizedError?.codeName
+			};
+
+			console.error(new Date(), 'Unhandled Rejection at Promise', [errorDetails]);
+			
+			let diffTimeSec = moment().diff(this._serverStartTime, 'seconds');
+
+			// If this is a MongoNetworkTimeoutError, handle it specifically
+			if (normalizedError && (normalizedError['name'] === 'MongoNetworkTimeoutError' || normalizedError instanceof MongoNetworkTimeoutError)) {
+				if (diffTimeSec > 60 && !this._lastErrorMsg) {
+					this._lastErrorMsg = new Date();
+					setTimeout(() => {
+						this._lastErrorMsg = null;
+					}, 60000);
+
+					// Exiting the process
+					process.exit(1);
+				}
+			}
+			else if (normalizedError && normalizedError['name'] === 'MongoError' && normalizedError['message'] === 'not master') {
+				if (diffTimeSec > 60 && !this._lastErrorMsg) {
+					this._lastErrorMsg = new Date();
+
+					setTimeout(() => {
+						this._lastErrorMsg = null;
+					}, 60000);
+				}
+
+				process.exit(1);
+			}
+			else if (normalizedError && normalizedError['name'] === 'MongoError' && normalizedError['message'] === 'not master and slaveOk=false') {
+				if (diffTimeSec > 60 && !this._lastErrorMsg) {
+					this._lastErrorMsg = new Date();
+
+					setTimeout(() => {
+						this._lastErrorMsg = null;
+					}, 60000);
+				}
+
+				process.exit(1);
+			}
+			else if (normalizedError && normalizedError['name'] !== 'StatusError' && normalizedError['message'] !== '') {
+				if (diffTimeSec > 60 && !this._lastErrorMsg) {
+					this._lastErrorMsg = new Date();
+
+					setTimeout(() => {
+						this._lastErrorMsg = null;
+					}, 60000);
+
+					await this.reportServerError(
+						'SERVER - Unhandled Rejection - ' + ResolveIOServer.getServerConfig()['CLIENT_NAME'],
+						correlationId,
+						errorDetails,
+						{
+							context: 'unhandledRejection',
+							scenario: 'General'
+						}
+					);
+				}
+			}
+		});
+
+		process.on('uncaughtException', async error => {
+			const { error: normalizedError, correlationId } = ensureErrorWithCorrelation(error);
+			console.error(normalizedError, 'Uncaught Exception thrown', { correlationId });
+
+			let diffTimeSec = moment().diff(this._serverStartTime, 'seconds');
+
+			if (diffTimeSec > 60 && !this._lastErrorMsg) {
+				this._lastErrorMsg = new Date();
+
+				setTimeout(() => {
+					this._lastErrorMsg = null;
+				}, 60000);
+				
+				const errorDetails = {
+					id: correlationId,
+					name: normalizedError?.name,
+					message: normalizedError?.message,
+					stack: normalizedError?.stack,
+					code: normalizedError?.code,
+					codeName: normalizedError?.codeName
+				};
+
+				await this.reportServerError(
+					'SERVER - Unhandled Exception - ' + ResolveIOServer.getServerConfig()['CLIENT_NAME'],
+					correlationId,
+					errorDetails,
+					{
+						context: 'uncaughtException'
+					}
+				);
+			}
+		});
+
+		//PM2 wants to reboot/restart
+		process.on('SIGINT', async () => {
+			this._rebootFlag = true;
+			try {
+				await this.shutdownNetworkServers();
+			}
+			catch (error) {
+				console.error(new Date(), 'Error closing network servers (SIGINT)', error);
+			}
+			await this.safeShutdown();
+		});
+
+		process.on('SIGTERM', async () => {
+			this._rebootFlag = true;
+			try {
+				await this.shutdownNetworkServers();
+			}
+			catch (error) {
+				console.error(new Date(), 'Error closing network servers (SIGTERM)', error);
+			}
+			await this.safeShutdown();
+		});
+
+		process.on('SIGQUIT', async () => {
+			this._rebootFlag = true;
+			try {
+				await this.shutdownNetworkServers();
+			}
+			catch (error) {
+				console.error(new Date(), 'Error closing network servers (SIGQUIT)', error);
+			}
+			await this.safeShutdown();
+		});
+
+		if (this.LOGGER === 'DEBUG') {
+			console.log('Starting ResolveIO Server');
+		}
+
+		if (this._isWorkersEnabled) {
+			if (this._isWorkerInstance) {
+				const workerRole = this.resolveWorkerRole();
+				const workerIndex = this.normalizeWorkerSelectorValue(process.env.WORKER_INDEX) || 'UNKNOWN';
+				const workerInstance = this.normalizeWorkerSelectorValue(process.env.NODE_APP_INSTANCE) || 'UNKNOWN';
+				console.log(`Running as Worker: ${workerRole}`, workerIndex, workerInstance);
+				this._methodManager = MethodManager.create(null, this._monitorManagerFunction, this._isWorkersEnabled, this._isWorkerInstance);
+				this._subscriptionManager = SubscriptionManager.createPublicationRegistry(ResolveIOServer.getServerConfig());
+				this._workerServerManager = WorkerServerManager.create(this._methodManager, this.getServerConfig());
+
+				if (process.env.WORKER_INDEX === '0') {
+					this._cronManager = CronManager.create();
+				}
+			}
+			else {
+				console.log('Running as a Server instance', process.env.NODE_APP_INSTANCE);
+				this._websocketManager = WebSocketManager.create(this);
+				this._methodManager = MethodManager.create(this._websocketManager, this._monitorManagerFunction, this._isWorkersEnabled, this._isWorkerInstance);
+				this._workerDispatcherManager = WorkerDispatcherManager.create(this._websocketManager, this._methodManager);
+				this._subscriptionManager = SubscriptionManager.create(this._serverWSS, ResolveIOServer.getServerConfig(), this._monitorManagerFunction);
+				this.startServerInstance();
+				this.listen();
+			}
+		}
+		else {
+			console.log('Running with Workers Disabled', process.env.NODE_APP_INSTANCE);
+			this._websocketManager = WebSocketManager.create(this);
+			this._methodManager = MethodManager.create(this._websocketManager, this._monitorManagerFunction, this._isWorkersEnabled, this._isWorkerInstance);
+			this._subscriptionManager = SubscriptionManager.create(this._serverWSS, ResolveIOServer.getServerConfig(), this._monitorManagerFunction);
+			this._cronManager = CronManager.create();
+			this.startServerInstance();
+			this.listen();
+		}
+	}
+
+	private async shutdownNetworkServers() {
+		await this.closeWebSocketServerGracefully();
+		await this.closeHttpServerGracefully();
+	}
+
+	private async closeHttpServerGracefully() {
+		if (!this._serverHTTP) {
+			return;
+		}
+
+		if (this._httpServerClosePromise !== null) {
+			await this._httpServerClosePromise;
+			return;
+		}
+
+		// eslint-disable-next-line no-restricted-syntax
+		this._httpServerClosePromise = new Promise(resolve => {
+			try {
+				this._serverHTTP.close(error => {
+					if (error && error['code'] !== 'ERR_SERVER_NOT_RUNNING') {
+						console.error(new Date(), 'Error closing HTTP server before shutdown', error);
+					}
+					resolve();
+				});
+			}
+			catch (error) {
+				if (error && error['code'] !== 'ERR_SERVER_NOT_RUNNING') {
+					console.error(new Date(), 'Error closing HTTP server before shutdown', error);
+				}
+				resolve();
+			}
+		});
+
+		await this._httpServerClosePromise;
+	}
+
+	private async closeWebSocketServerGracefully() {
+		if (!this._serverWSS) {
+			return;
+		}
+
+		if (this._websocketServerClosePromise !== null) {
+			await this._websocketServerClosePromise;
+			return;
+		}
+
+		this._serverWSS.clients.forEach(ws => {
+			try {
+				ws.close(1001, 'Server restarting');
+			}
+			catch (error) {
+				console.error(new Date(), 'Error closing WebSocket client before shutdown', error);
+			}
+		});
+
+		// eslint-disable-next-line no-restricted-syntax
+		this._websocketServerClosePromise = new Promise(resolve => {
+			try {
+				this._serverWSS.close(error => {
+					if (error) {
+						console.error(new Date(), 'Error closing WebSocket server before shutdown', error);
+					}
+
+					resolve();
+				});
+			}
+			catch (error) {
+				console.error(new Date(), 'Error closing WebSocket server before shutdown', error);
+				resolve();
+			}
+		});
+
+		await this._websocketServerClosePromise;
+	}
+
+	private startServerInstance() {
+		// Start express app
+		this._app = express();
+
+		// Use built-in express JSON parser
+		this._app.use(express.json({
+			limit: '50mb',
+			reviver: dateReviver // Note: 'reviver' is an option for JSON.parse, which can be passed here
+		}));
+
+		// Use built-in express URL-encoded parser
+		this._app.use(express.urlencoded({
+			limit: '50mb',
+			extended: true, // `extended` must be explicitly true or false
+			parameterLimit: 1000000
+		}));
+
+
+		this._app.use(xmlParser());
+		
+		// Set port
+		this._portHTTP = process.env.NODE_APP_INSTANCE ? parseInt('808' + process.env.NODE_APP_INSTANCE) : 8080;
+
+		if (this.LOGGER === 'DEBUG') {
+			console.log('Setup ports');
+		}
+
+		// Create http server and websock server
+		this.createServer();
+
+		if (this.LOGGER === 'DEBUG') {
+			console.log('Create server');
+		}
+
+		// Set CORS
+		this._app.use(function (req, res, next) {
+			res.setHeader('Access-Control-Allow-Origin', '*');
+			res.setHeader('Access-Control-Allow-Methods', 'GET, POST');
+			res.setHeader('Access-Control-Allow-Headers', 'X-Requested-With,content-type');
+			res.setHeader('Access-Control-Allow-Credentials', 'false');
+			next();
+		});
+
+		if (this.LOGGER === 'DEBUG') {
+			console.log('Setup cors');
+		}
+
+		this.installDynamicAppGatewayMiddleware();
+
+		// Set up http login route
+		setupAuthRoutes(this, this._app, ResolveIOServer.getServerConfig());
+		setupHealthRoutes(this._app);
+		setupSlowQueryPublicationRoutes(this._app);
+
+		if (ResolveIOServer.getServerConfig()['CLIENT_NAME'] === 'ResolveIO' || this.publicProgram) {
+			setupHomeRoutes(this, this._app, ResolveIOServer.getServerConfig());
+		}
+
+		if (this.LOGGER === 'DEBUG') {
+			console.log('Setup express routes');
+		}
+	}
+
+	private installDynamicAppGatewayMiddleware(): void {
+		if (!this._dynamicAppGatewayEnabled) {
+			return;
+		}
+
+		this._app.use(async (req, res, next) => {
+			const appId = this.extractDynamicAppGatewayId(req);
+			if (!appId) {
+				next();
+				return;
+			}
+
+			try {
+				const appDoc = await this.resolveCachedDynamicAppGatewayApp(appId);
+				if (!appDoc) {
+					res.status(404).send(JSON.stringify({
+						error: true,
+						result: 'App not found.'
+					}));
+					return;
+				}
+
+				const allowedHosts = this.resolveDynamicAppAllowedHosts(appDoc);
+				const controlHosts = this.resolveDynamicAppControlHosts();
+				const requestHost = this.normalizeHostname(
+					this.normalizeHeaderValue(req.headers?.['x-forwarded-host'])
+					|| this.normalizeHeaderValue(req.headers?.host)
+				);
+				const originHeader = this.normalizeHeaderValue(req.headers?.origin);
+				const originHost = this.resolveOriginHostname(originHeader);
+
+				if (requestHost && controlHosts.has(requestHost) && !this.isLocalHostname(requestHost)) {
+					res.status(403).send(JSON.stringify({
+						error: true,
+						result: 'App API must be requested from an app domain.'
+					}));
+					return;
+				}
+
+				if (requestHost && !allowedHosts.has(requestHost) && !this.isLocalHostname(requestHost)) {
+					res.status(403).send(JSON.stringify({
+						error: true,
+						result: 'Host not allowed for app API.'
+					}));
+					return;
+				}
+
+				if (originHost && controlHosts.has(originHost) && !this.isLocalHostname(originHost)) {
+					res.status(403).send(JSON.stringify({
+						error: true,
+						result: 'App API origin must be an app domain.'
+					}));
+					return;
+				}
+
+				if (originHost && !allowedHosts.has(originHost)) {
+					res.status(403).send(JSON.stringify({
+						error: true,
+						result: 'Origin not allowed for app API.'
+					}));
+					return;
+				}
+
+				if (originHeader) {
+					this.applyDynamicAppGatewayCorsHeaders(res, originHeader);
+				}
+
+				if (req.method === 'OPTIONS') {
+					res.status(204).end();
+					return;
+				}
+
+				const expectedToken = this.normalizeHeaderValue(appDoc?.rio_token);
+				if (!expectedToken) {
+					res.status(500).send(JSON.stringify({
+						error: true,
+						result: 'App token is not configured.'
+					}));
+					return;
+				}
+
+				const providedToken = this.resolveDynamicAppGatewayToken(req);
+				if (!providedToken || providedToken !== expectedToken) {
+					res.status(401).send(JSON.stringify({
+						error: true,
+						result: 'Invalid or missing RIO token.'
+					}));
+					return;
+				}
+
+				next();
+			}
+			catch (error) {
+				console.error(new Date(), '[DynamicAppGateway] middleware failure', error);
+				res.status(500).send(JSON.stringify({
+					error: true,
+					result: (error as Error)?.message || 'Dynamic app gateway error.'
+				}));
+			}
+		});
+	}
+
+	private resolveDynamicAppGatewayEnabled(): boolean {
+		const config = ResolveIOServer.getServerConfig() || {};
+		const raw = config['AI_CODER_DYNAMIC_APP_GATEWAY'] ?? process.env.AI_CODER_DYNAMIC_APP_GATEWAY;
+		if (raw !== undefined && raw !== null && `${raw}`.trim() !== '') {
+			return this.parseDebugFlag(raw);
+		}
+
+		const urls = [
+			config['ROOT_URL'],
+			config['SEC_ROOT_URL'],
+			config['SERVER_URL'],
+			process.env.ROOT_URL,
+			process.env.SEC_ROOT_URL,
+			process.env.SERVER_URL
+		]
+			.map(value => `${value || ''}`.trim().toLowerCase())
+			.filter(Boolean);
+
+		return urls.some(value => value.includes('aicoder'));
+	}
+
+	private extractDynamicAppGatewayId(req: express.Request): string {
+		const rawPath = `${req.originalUrl || req.url || req.path || ''}`;
+		const normalizedPath = rawPath.split('?')[0];
+		if (!normalizedPath.startsWith('/api/apps/')) {
+			return '';
+		}
+
+		const parts = normalizedPath.split('/').filter(Boolean);
+		if (parts.length < 3) {
+			return '';
+		}
+
+		return `${parts[2] || ''}`.trim();
+	}
+
+	private resolveDynamicAppGatewayToken(req: express.Request): string {
+		const authHeader = this.normalizeHeaderValue(req.headers?.authorization || req.headers?.Authorization);
+		if (authHeader) {
+			const bearerMatch = authHeader.match(/^bearer\s+(.+)$/i);
+			if (bearerMatch && bearerMatch[1]) {
+				return bearerMatch[1].trim();
+			}
+		}
+
+		const headerCandidates = [
+			req.headers?.['x-rio-token'],
+			req.headers?.['x-app-token'],
+			req.headers?.['x-api-key']
+		];
+		for (const candidate of headerCandidates) {
+			const value = this.normalizeHeaderValue(candidate);
+			if (value) {
+				return value;
+			}
+		}
+
+		const body: any = req.body || {};
+		const query: any = req.query || {};
+		const bodyCandidates = [body.rioToken, body.rio_token, body.apiKey, body.token];
+		for (const candidate of bodyCandidates) {
+			const value = this.normalizeHeaderValue(candidate);
+			if (value) {
+				return value;
+			}
+		}
+		const queryCandidates = [query.rioToken, query.rio_token, query.apiKey, query.token];
+		for (const candidate of queryCandidates) {
+			const value = this.normalizeHeaderValue(candidate);
+			if (value) {
+				return value;
+			}
+		}
+
+		return '';
+	}
+
+	private normalizeHeaderValue(value: any): string {
+		if (Array.isArray(value)) {
+			return value.map(entry => `${entry || ''}`.trim()).filter(Boolean).join(',');
+		}
+		return `${value || ''}`.trim();
+	}
+
+	private normalizeHostname(value: string): string {
+		const raw = `${value || ''}`.trim();
+		if (!raw) {
+			return '';
+		}
+
+		let candidate = raw.split(',')[0].trim();
+		if (!candidate) {
+			return '';
+		}
+
+		try {
+			if (candidate.startsWith('http://') || candidate.startsWith('https://')) {
+				return new URL(candidate).hostname.toLowerCase();
+			}
+			if (candidate.includes('/')) {
+				return new URL(`http://${candidate}`).hostname.toLowerCase();
+			}
+		}
+		catch {}
+
+		candidate = candidate.replace(/^\[/, '').replace(/\]$/, '');
+		const lastColon = candidate.lastIndexOf(':');
+		if (lastColon > -1 && candidate.indexOf(':') === lastColon) {
+			candidate = candidate.slice(0, lastColon);
+		}
+		return candidate.toLowerCase();
+	}
+
+	private resolveOriginHostname(origin: string): string {
+		const raw = `${origin || ''}`.trim();
+		if (!raw) {
+			return '';
+		}
+		try {
+			return new URL(raw).hostname.toLowerCase();
+		}
+		catch {
+			return this.normalizeHostname(raw);
+		}
+	}
+
+	private isLocalHostname(hostname: string): boolean {
+		const normalized = this.normalizeHostname(hostname);
+		return normalized === 'localhost' || normalized === '127.0.0.1' || normalized === '::1';
+	}
+
+	private resolveDynamicAppControlHosts(): Set<string> {
+		const config = ResolveIOServer.getServerConfig() || {};
+		const hosts = new Set<string>();
+		const candidates = [
+			config['ROOT_URL'],
+			config['SEC_ROOT_URL'],
+			config['SERVER_URL'],
+			process.env.ROOT_URL,
+			process.env.SEC_ROOT_URL,
+			process.env.SERVER_URL,
+			process.env.AI_CODER_ROOT_URL,
+			process.env.AI_CODER_SEC_ROOT_URL,
+			process.env.AI_CODER_SERVER_URL
+		];
+		for (const candidate of candidates) {
+			const normalized = this.normalizeHostname(`${candidate || ''}`);
+			if (normalized) {
+				hosts.add(normalized);
+			}
+		}
+		return hosts;
+	}
+
+	private resolveDynamicAppAllowedHosts(appDoc: any): Set<string> {
+		const hosts = new Set<string>();
+		const candidates = [
+			appDoc?.domain,
+			appDoc?.backend_domain
+		];
+		if (appDoc?.subdomain && appDoc?.domain_base) {
+			candidates.push(`${appDoc.subdomain}.${appDoc.domain_base}`);
+		}
+
+		for (const candidate of candidates) {
+			const normalized = this.normalizeHostname(`${candidate || ''}`);
+			if (normalized) {
+				hosts.add(normalized);
+			}
+		}
+		return hosts;
+	}
+
+	private applyDynamicAppGatewayCorsHeaders(res: express.Response, origin: string): void {
+		res.setHeader('Access-Control-Allow-Origin', origin);
+		res.setHeader('Vary', 'Origin');
+		res.setHeader('Access-Control-Allow-Methods', 'GET, POST, PUT, PATCH, DELETE, OPTIONS');
+		res.setHeader('Access-Control-Allow-Headers', 'Origin, X-Requested-With, Content-Type, Accept, Authorization, X-Rio-Token, X-API-Key');
+		res.setHeader('Access-Control-Allow-Credentials', 'true');
+		res.setHeader('Access-Control-Max-Age', '600');
+	}
+
+	private async resolveCachedDynamicAppGatewayApp(appId: string): Promise<any | null> {
+		const now = Date.now();
+		const cached = this._dynamicAppGatewayCache.get(appId);
+		if (cached && cached.expiresAt > now) {
+			return cached.app;
+		}
+
+		const db = ResolveIOServer.getMainDB();
+		if (!db) {
+			return null;
+		}
+
+		const appCollection: any = db.collection('ai-coder-apps');
+		const appDoc = await appCollection.findOne(
+			{ _id: appId },
+			{
+				projection: {
+					_id: 1,
+					domain: 1,
+					backend_domain: 1,
+					subdomain: 1,
+					domain_base: 1,
+					rio_token: 1
+				}
+			}
+		);
+		if (!appDoc) {
+			this._dynamicAppGatewayCache.delete(appId);
+			return null;
+		}
+
+		if (!this.normalizeHeaderValue(appDoc.rio_token)) {
+			const generated = crypto.randomBytes(32).toString('hex');
+			await appCollection.updateOne(
+				{ _id: appId },
+				{
+					$set: {
+						rio_token: generated,
+						updatedAt: new Date()
+					}
+				}
+			);
+			appDoc.rio_token = generated;
+		}
+
+		this._dynamicAppGatewayCache.set(appId, {
+			expiresAt: now + this._dynamicAppGatewayCacheMs,
+			app: appDoc
+		});
+		return appDoc;
+	}
+
+	private async safeShutdown() {
+		if (!this._safeShutdown) {
+			console.log(new Date(), 'Safe Shutdown Command Received');
+		}
+
+		if (
+			!this._monitorManagerFunction.getActiveMonitorFunctions().length
+			&& !this._offlineUpdates.length && (!this._workerDispatcherManager || this._workerDispatcherManager.isSafeShutdown())
+		) {
+			if (ResolveIOServer.getMongoConnection()) {
+				try {
+					await ResolveIOServer.getMongoConnection().close(false);
+					console.log(new Date(), 'Safe Exit Complete, Process Exit');
+					process.exit(0);
+				}
+				catch { 
+					process.exit(1); 
+				};
+			}
+			else {
+				process.exit(0);
+			}
+		}
+		else {
+			if (!this._safeShutdown) {
+				this._safeShutdown = true;
+
+				setTimeout(() => {
+					this._safeShutdown = false;
+				}, 1000);
+
+				console.log(new Date(), 'Safe Exit In Progress', 
+					this._monitorManagerFunction.getActiveMonitorFunctions().length,
+					this._offlineUpdates.length
+				);
+			}
+
+			setImmediate(async () => {
+				await this.safeShutdown();
+			});
+		}
+	}
+
+	getIsWorkersEnabled() {
+		return this._isWorkersEnabled;
+	}
+
+	getIsWorkerInstance() {
+		return this._isWorkerInstance;
+	}
+
+	public getWSList() {
+		let res = [];
+		this._serverWSS.clients.forEach((ws: WebSocket) => {
+			res.push(ws['id_socket']);
+		});
+		return res;
+	}
+
+	public getWSUserList() {
+		let res = [];
+		this._serverWSS.clients.forEach((ws: WebSocket) => {
+			res.push(ws['id_user']);
+		});
+		return res;
+	}
+
+	public getHTTPServer() {
+		return this._serverHTTP;
+	}
+
+	public getCronManager() {
+		return this._cronManager;
+	}
+
+	private async reportServerError(
+		subject: string,
+		correlationId: string,
+		context: Record<string, any>,
+		meta?: Record<string, any>,
+		severity = 'error',
+		stackOverride?: string
+	) {
+		const config = ResolveIOServer.getServerConfig();
+		const metadata = Object.assign({}, meta || {});
+		if (correlationId && !metadata.correlationId) {
+			metadata.correlationId = correlationId;
+		}
+
+		await ErrorReporter.report({
+			sourceApp: 'server-app',
+			message: subject,
+			environment: config?.ROOT_URL || process.env.NODE_ENV || 'unknown',
+			clientSlug: ResolveIOServer.getClientName(),
+			clientName: config?.CLIENT_NAME,
+			severity,
+			stack: stackOverride || (typeof context?.stack === 'string' ? context.stack : undefined),
+			context,
+			metadata,
+			correlationId
+		});
+	}
+
+	public getMethodManager() {
+		return this._methodManager;
+	}
+
+	public getSubscriptionManager() {
+		return this._subscriptionManager;
+	}
+
+	public getMonitorManager() {
+		return this._monitorManager;
+	}
+
+	public getRebootFlag() {
+		return this._rebootFlag;
+	}
+
+	public getWebSocketManager(): WebSocketManager {
+		return this._websocketManager;
+	}
+
+	private createServer(): void {
+		this._serverHTTP = createServer(this._app);
+		this._serverHTTP.keepAliveTimeout = 65000;
+		this._serverHTTP.headersTimeout = 66000;
+
+		this._serverWSS = new WebSocket.Server({
+			server: this._serverHTTP,
+			verifyClient: this.publicProgram ? null : (info, cb) => {
+				if (this._rebootFlag) {
+					cb(false, 409, 'Unable To Process');
+				}
+				else {
+					if (this.LOGGER === 'DEBUG') {
+						console.log('Verify Client', info, cb);
+					}
+
+					// If it's a worker, we might skip token checks or do a simple check:
+					if (info.req.url && info.req.url.includes('workerToken=')) {
+						let requestUrl: URL;
+						let rootUrl = ResolveIOServer.getServerConfig()['ROOT_URL'] || 'http://localhost';
+						try {
+							requestUrl = new URL(info.req.url, rootUrl);
+						}
+						catch {
+							cb(false, 400, 'Bad Request');
+							return;
+						}
+
+						let workerToken = requestUrl.searchParams.get('workerToken') || '';
+						let workerIndex = requestUrl.searchParams.get('workerIndex');
+						let workerInstance = requestUrl.searchParams.get('workerInstance');
+						let expectedWorkerToken = String(ResolveIOServer.getServerConfig()['WORKER_TOKEN'] || '');
+
+						if (workerToken === expectedWorkerToken) {
+							if (workerIndex) {
+								info.req['workerIndex'] = workerIndex;
+							}
+							if (workerInstance) {
+								info.req['workerInstance'] = workerInstance;
+							}
+
+							cb(true);
+						}
+						else {
+							cb(false, 401, 'Unauthorized');
+						}
+
+						return;
+					}
+
+					const protocolsHeader = info.req.headers['sec-websocket-protocol'];
+					if (!protocolsHeader || typeof protocolsHeader !== 'string') {
+						cb(false, 401, 'Unauthorized');
+						return;
+					}
+
+					let infoData = protocolsHeader.split(/,/);
+
+					if (!isAllowedOrigin(info.origin, ResolveIOServer.getServerConfig())) {
+						cb(false, 401, 'Unauthorized');
+					}
+					else {
+						let token = infoData[0];
+						if (!token) {
+							cb(false, 401, 'Unauthorized');
+						}
+						else {
+							jwt.verify(token, ResolveIOServer.getServerConfig()['JWT_SECRET'], async (err, decoded) => {
+								if (err) {
+									cb(false, 401, 'Unauthorized');
+								}
+									else {
+										info.req['id_user'] = decoded['id_user'];
+										try {
+											let user = await Users.findById(decoded['id_user']);
+											if (user) {
+												const socketAdmission = await this.evaluateClientSocketAdmission(decoded['id_user'], info.req);
+												if (!socketAdmission.allowed) {
+													cb(false, socketAdmission.statusCode, socketAdmission.message || 'Socket connection rejected.');
+													return;
+												}
+												info.req['user'] = user.fullname;
+												info.req['user_readonly'] = user.readonly || false;
+												info.req['doc_user'] = user;
+												info.req['client_ip'] = socketAdmission.clientIp;
+												cb(true);
+											}
+											else {
+											cb(false);
+										}
+									}
+									catch {
+										cb(false);
+									}
+								}
+							});
+						}
+					}
+				}
+			}
+		});
+	}
+
+	/**
+	 * Listen for connections from clients or workers.
+	 */
+	private listen(): void {
+		const host = process.env.RESOLVEIO_BIND_HOST || '127.0.0.1';
+		this._serverHTTP.listen(this._portHTTP, host, () => {
+			console.log('Running HTTP/WS server on port %s', this._portHTTP);
+		});
+
+			this._serverWSS.on('connection', async (ws, req) => {
+				if (req.url && req.url.includes('workerToken=')) {
+					// It's a WORKER
+					let workerId = objectIdHexString();
+					ws['id_worker'] = workerId;
+					let workerIndex = null;
+					let workerInstance = null;
+					ws['supportsBinary'] = true;
+
+					if (req.url) {
+						let rootUrl = ResolveIOServer.getServerConfig()['ROOT_URL'] || 'http://localhost';
+						try {
+							let requestUrl = new URL(req.url, rootUrl);
+							workerIndex = requestUrl.searchParams.get('workerIndex');
+							workerInstance = requestUrl.searchParams.get('workerInstance');
+						}
+						catch {
+							workerIndex = null;
+							workerInstance = null;
+						}
+					}
+
+					if (!workerIndex && req['workerIndex']) {
+						workerIndex = req['workerIndex'];
+					}
+					if (!workerInstance && req['workerInstance']) {
+						workerInstance = req['workerInstance'];
+					}
+
+					if (workerIndex !== null && workerIndex !== undefined) {
+						ws['workerIndex'] = workerIndex;
+					}
+					if (workerInstance !== null && workerInstance !== undefined) {
+						ws['workerInstance'] = workerInstance;
+					}
+
+					let workerIndexForLog = ws['workerIndex'] || 'UNKNOWN';
+					let workerInstanceForLog = ws['workerInstance'] || 'UNKNOWN';
+					console.log(new Date(), 'Worker Connected', workerIndexForLog, workerInstanceForLog);
+
+					this._workerDispatcherManager.addWorker(ws);
+
+				let interval = null;
+				let lastComm = new Date();
+				let missedPongs = 0;
+				const heartbeatIntervalMs = 30000;
+				const maxMissedPongs = 2;
+				const maxSilenceMs = heartbeatIntervalMs * (maxMissedPongs + 1);
+
+				this._workerDispatcherManager.sendWorkerPayload(ws, 'ping');
+	
+				interval = setInterval(() => {
+					const now = Date.now();
+					const last = lastComm ? lastComm.getTime() : 0;
+					const silenceMs = last ? now - last : maxSilenceMs + 1;
+					if (silenceMs > maxSilenceMs || missedPongs > maxMissedPongs) {
+						this._workerDispatcherManager.disconnectWorker(ws['id_worker']);
+						ws.close();
+						return;
+					}
+					missedPongs += 1;
+					this._workerDispatcherManager.sendWorkerPayload(ws, 'ping');
+				}, heartbeatIntervalMs);
+
+					ws.on('message', (message: WebSocket.RawData) => {
+						lastComm = new Date();
+						if (typeof message === 'string') {
+							if (message === 'ping') {
+								this._workerDispatcherManager.sendWorkerPayload(ws, 'pong');
+							}
+							else if (message === 'pong') {
+								missedPongs = 0;
+							}
+							else {
+								this._workerDispatcherManager.handleWorkerMessage(ws['id_worker'], message);
+							}
+
+							return;
+						}
+
+						let buffer: Buffer;
+
+						if (Buffer.isBuffer(message)) {
+							buffer = message;
+						}
+						else if (Array.isArray(message)) {
+							const chunks = message as unknown as ReadonlyArray<Uint8Array>;
+							buffer = Buffer.concat(chunks);
+						}
+						else if (message instanceof ArrayBuffer) {
+							buffer = Buffer.from(message);
+						}
+						else if (ArrayBuffer.isView(message)) {
+							const view = message as NodeJS.ArrayBufferView;
+							buffer = Buffer.from(view.buffer, view.byteOffset, view.byteLength);
+						}
+						else {
+							buffer = Buffer.from(message as any);
+						}
+
+						if (buffer.length === 4) {
+							let heartbeat = buffer.toString('utf8');
+
+							if (heartbeat === 'ping') {
+								this._workerDispatcherManager.sendWorkerPayload(ws, 'pong');
+								return;
+							}
+							else if (heartbeat === 'pong') {
+								missedPongs = 0;
+								return;
+							}
+						}
+
+						this._workerDispatcherManager.handleWorkerMessage(ws['id_worker'], buffer);
+					});
+
+				ws.on('close', () => {
+					this._workerDispatcherManager.disconnectWorker(ws['id_worker']);
+
+					console.log(new Date(), 'Worker disconnected:', workerId);
+					
+					if (interval) {
+						clearInterval(interval);
+					}
+				});
+
+				ws.on('error', (error) => {
+					this._workerDispatcherManager.disconnectWorker(ws['id_worker']);
+
+					console.error('Error on WS Worker', error);
+					ws.close();
+				});
+			}
+				else {
+					// Normal client
+					ws['id_socket'] = objectIdHexString();
+					ws['supportsBinary'] = true;
+					ws['id_user'] = req['id_user'];
+					ws['user'] = req['user'];
+					ws['user_readonly'] = req['user_readonly'];
+					ws['doc_user'] = req['doc_user'];
+					ws['client_ip'] = this.resolveClientIp(req);
+
+					let socketAdmission: { allowed: boolean, statusCode: number, message: string, clientIp: string };
+					try {
+						socketAdmission = await this.evaluateClientSocketAdmission(ws['id_user'], req);
+					}
+					catch (socketPolicyError) {
+						this.logConnectDebug('WS socket policy evaluation failed', {
+							id_socket: ws['id_socket'],
+							id_user: ws['id_user'],
+							user: ws['user'],
+							ip: ws['client_ip'],
+							error: (socketPolicyError as Error)?.message || socketPolicyError
+						});
+						try {
+							ws.close(1011, 'Socket policy error');
+						}
+						catch {}
+						return;
+					}
+
+					if (!socketAdmission.allowed) {
+						this.logConnectDebug('WS client rejected', {
+							id_socket: ws['id_socket'],
+							id_user: ws['id_user'],
+							user: ws['user'],
+							ip: ws['client_ip'],
+							reason: socketAdmission.message
+						});
+						try {
+							ws.close(1008, this.buildSocketLimitCloseReason());
+						}
+						catch {}
+						return;
+					}
+					ws['client_ip'] = socketAdmission.clientIp || ws['client_ip'];
+
+					this._websocketManager.addWebSocket(ws);
+
+				this.logConnectDebug('WS client connected', {
+						id_socket: ws['id_socket'],
+						id_user: ws['id_user'],
+						user: ws['user'],
+						url: req?.url,
+						ip: ws['client_ip'],
+						origin: req?.headers?.origin
+					});
+
+				setTimeout(async () => {
+					await this.triggerClientHeartbeat(ws);
+				}, this._clientHeartbeatInitialDelayMs);
+
+				if (this.LOGGER === 'DEBUG') {
+					console.log('Connection from user: ' + req['user']);
+				}
+			
+				ws['isAlive'] = true;
+				ws['retryCnt'] = 0;
+				ws.on('pong', () => {
+					ws['isAlive'] = true;
+					ws['pongTime'] = new Date();
+					if (ws['pingTime']) {
+						ws['latency'] = moment.duration(moment(ws['pongTime']).diff(ws['pingTime'])).asMilliseconds();
+						this._subscriptionManager.loggedInLatency(ws);
+					}
+				});
+
+				ws.on('message', async (message: WebSocket.RawData) => {
+					this._debugMsgRecv += 1;
+					let socketData = [];
+					let usedBinary = false;
+					let bufferPayload: Buffer;
+				
+					try {
+						if (typeof message === 'string') {
+							if (message === 'ping' || message === 'pong') {
+								socketData = message;
+							}
+							else {
+								socketData = JSON.parse(message, dateReviver);
+							}
+						}
+						else if (Buffer.isBuffer(message)) {
+							bufferPayload = message;
+							let decodeResult = this.decodeBufferPayload(bufferPayload);
+							socketData = decodeResult.data;
+							usedBinary = decodeResult.usedBinary;
+						}
+						else if (Array.isArray(message)) {
+							bufferPayload = Buffer.concat(message as unknown as ReadonlyArray<Uint8Array>);
+							let decodeResult = this.decodeBufferPayload(bufferPayload);
+							socketData = decodeResult.data;
+							usedBinary = decodeResult.usedBinary;
+						}
+						else if (message instanceof ArrayBuffer) {
+							bufferPayload = Buffer.from(message);
+							let decodeResult = this.decodeBufferPayload(bufferPayload);
+							socketData = decodeResult.data;
+							usedBinary = decodeResult.usedBinary;
+						}
+					else if (ArrayBuffer.isView(message)) {
+						const view = message as NodeJS.ArrayBufferView;
+						bufferPayload = Buffer.from(view.buffer, view.byteOffset, view.byteLength);
+						let decodeResult = this.decodeBufferPayload(bufferPayload);
+						socketData = decodeResult.data;
+						usedBinary = decodeResult.usedBinary;
+					}
+					else {
+						throw new Error('Unsupported WebSocket message type: ' + typeof message);
+					}
+				}
+				catch (e) {
+					console.log('Error - WS message parse', e);
+					const correlationId = objectIdHexString();
+					const context = {
+						rawBinary: bufferPayload ? bufferPayload.toString('base64') : undefined,
+						rawMessage: typeof message === 'string' ? message : undefined,
+						error: e instanceof Error ? { name: e.name, message: e.message, stack: e.stack } : e
+					};
+					await this.reportServerError(
+						'SERVER - JSON Parse Error - ' + ResolveIOServer.getServerConfig()['CLIENT_NAME'],
+						correlationId,
+						context,
+						{ context: 'websocket-message-parse' },
+						'error',
+						e instanceof Error ? e.stack : undefined
+					);
+					return;
+				}
+
+					if (usedBinary) {
+						ws['supportsBinary'] = true;
+					}
+	
+					// call our existing processSocketMessage
+					await this.processSocketMessage(ws, socketData);
+				})
+				.on('end', () => {
+					ws.close();
+				})
+				.on('error', () => {
+					ws.close()
+				})
+				.on('close', async () => {
+					this.logConnectDebug('WS client closed', {
+						id_socket: ws['id_socket'],
+						id_user: ws['id_user'],
+						user: ws['user']
+					});
+					await this.unsubscribeWS(ws);
+				});
+
+				// Do not block message handler registration on DB write; this avoids losing
+				// very-early subscription messages sent immediately after websocket open.
+				setTimeout(async () => {
+					try {
+						await this._subscriptionManager.createLoggedInUser(ws['id_socket']);
+					}
+					catch (error) {
+						console.error(new Date(), 'Error creating logged-in user', ws['id_socket'], error);
+						this.logConnectDebug('Create logged-in user failed', {
+							id_socket: ws['id_socket'],
+							id_user: ws['id_user'],
+							user: ws['user'],
+							error: error?.message || error
+						});
+					}
+				}, 0);
+					}
+				});
+
+		// Keep alive timer
+		setInterval(async () => {
+			for (let ws of this._serverWSS.clients) {
+				if (ws['pingTime'] && Date.now() - ws['pingTime'].getTime() >= this._clientHeartbeatIntervalMs) {
+					if (this.shouldDeferHeartbeat(ws)) {
+						ws['isAlive'] = true;
+						ws['retryCnt'] = 0;
+						ws['pingTime'] = new Date();
+						continue;
+					}
+
+					if (ws['isAlive'] === false) {
+						ws['retryCnt']++;
+						if (ws['retryCnt'] >= 3) {
+							await this.unsubscribeWS(ws);
+						}
+						else {
+							await this.triggerClientHeartbeat(ws);
+						}
+					}
+					else {
+						ws['retryCnt'] = 0;
+						ws['isAlive'] = false;
+						await this.triggerClientHeartbeat(ws);
+					}
+				}
+			}
+		}, this._clientHeartbeatIntervalMs);
+	}
+
+	private async processSocketMessage(ws: WebSocket, socketData: any) {
+		if (typeof socketData === 'string' && socketData === 'ping') {
+			if (ws && ws.readyState === WebSocket.OPEN) {
+				ws.send('pong');
+			}
+			return;
+		}
+		else if (typeof socketData === 'string' && socketData === 'pong') {
+			ws['isAlive'] = true;
+			ws['pongTime'] = new Date();
+			ws['latency'] = moment.duration(moment(ws['pongTime']).diff(ws['pingTime'])).asMilliseconds();
+			this._subscriptionManager.loggedInLatency(ws);
+			return;
+		}
+
+		// If the top level is not an array, let's skip
+		if (!Array.isArray(socketData[0])) {
+			console.log('Invalid message format (expected array of arrays)', socketData);
+			this.logConnectDebug('Invalid message format', {
+				id_socket: ws ? ws['id_socket'] : null,
+				user: ws ? ws['user'] : null,
+				preview: Array.isArray(socketData) ? socketData.slice(0, 3) : socketData
+			});
+			return;
+		}
+
+		// Handle each sub-message
+		for (let message of socketData) {
+			await this.handleClientMessage(ws, message);
+		}
+	}
+
+	private decodeBufferPayload(buffer: Buffer): { data: any; usedBinary: boolean } {
+		const textPayload = buffer.toString('utf8');
+
+		if (this.looksLikeTextPayload(textPayload)) {
+			try {
+				return { data: this.parseTextFallback(textPayload), usedBinary: false };
+			}
+			catch {
+				// fall through to attempt MessagePack decode
+			}
+		}
+
+		try {
+			return { data: unpack(buffer), usedBinary: true };
+		}
+		catch (binaryErr) {
+			try {
+				return { data: this.parseTextFallback(textPayload), usedBinary: false };
+			}
+			catch {
+				throw binaryErr;
+			}
+		}
+	}
+
+	private parseTextFallback(rawMessage: string): any {
+		if (rawMessage === 'ping' || rawMessage === 'pong') {
+			return rawMessage;
+		}
+
+		try {
+			return JSON.parse(rawMessage, dateReviver);
+		}
+		catch (err) {
+			throw err;
+		}
+	}
+
+	private looksLikeTextPayload(text: string): boolean {
+		if (!text) {
+			return false;
+		}
+
+		const trimmed = text.trim();
+		if (!trimmed) {
+			return false;
+		}
+
+		const first = trimmed[0];
+		return first === '[' || first === '{' || first === '"' || first === 'p' || first === 'P';
+	}
+
+	private resolveConnectDebug(): boolean {
+		const config = ResolveIOServer.getServerConfig ? ResolveIOServer.getServerConfig() : null;
+		const raw = process.env.WS_CONNECT_DEBUG
+			?? process.env.CONNECT_DEBUG
+			?? config?.['WS_CONNECT_DEBUG']
+			?? config?.['CONNECT_DEBUG'];
+		return this.parseDebugFlag(raw);
+	}
+
+	private resolvePerfDebug(): boolean {
+		const config = ResolveIOServer.getServerConfig ? ResolveIOServer.getServerConfig() : null;
+		const raw = process.env.PERF_DEBUG
+			?? process.env.CPU_DEBUG
+			?? config?.['PERF_DEBUG']
+			?? config?.['CPU_DEBUG'];
+		return this.parseDebugFlag(raw);
+	}
+
+	private resolveCpuProfileOnStart(): boolean {
+		const config = ResolveIOServer.getServerConfig ? ResolveIOServer.getServerConfig() : null;
+		const raw = process.env.CPU_PROFILE_ON_START
+			?? process.env.CPU_PROFILE_START
+			?? config?.['CPU_PROFILE_ON_START']
+			?? config?.['CPU_PROFILE_START'];
+		return this.parseDebugFlag(raw);
+	}
+
+	private resolveCpuProfileAuto(): boolean {
+		const config = ResolveIOServer.getServerConfig ? ResolveIOServer.getServerConfig() : null;
+		const raw = process.env.CPU_PROFILE_AUTO
+			?? config?.['CPU_PROFILE_AUTO'];
+		return this.parseDebugFlag(raw);
+	}
+
+	private resolveCpuProfileDurationMs(): number {
+		const config = ResolveIOServer.getServerConfig ? ResolveIOServer.getServerConfig() : null;
+		const raw = process.env.CPU_PROFILE_DURATION_MS
+			?? process.env.PERF_PROFILE_DURATION_MS
+			?? config?.['CPU_PROFILE_DURATION_MS']
+			?? config?.['PERF_PROFILE_DURATION_MS'];
+		return this.parsePositiveInt(raw, this._cpuProfileDurationMs);
+	}
+
+	private resolveCpuProfileThresholdPct(): number {
+		const config = ResolveIOServer.getServerConfig ? ResolveIOServer.getServerConfig() : null;
+		const raw = process.env.CPU_PROFILE_THRESHOLD_PCT
+			?? process.env.PERF_PROFILE_THRESHOLD_PCT
+			?? config?.['CPU_PROFILE_THRESHOLD_PCT']
+			?? config?.['PERF_PROFILE_THRESHOLD_PCT'];
+		return this.parsePositiveFloat(raw, this._cpuProfileThresholdPct);
+	}
+
+	private resolveCpuProfileTriggerCount(): number {
+		const config = ResolveIOServer.getServerConfig ? ResolveIOServer.getServerConfig() : null;
+		const raw = process.env.CPU_PROFILE_TRIGGER_COUNT
+			?? config?.['CPU_PROFILE_TRIGGER_COUNT'];
+		return this.parsePositiveInt(raw, this._cpuProfileTriggerCount);
+	}
+
+	private resolveCpuProfileDir(): string | null {
+		const config = ResolveIOServer.getServerConfig ? ResolveIOServer.getServerConfig() : null;
+		const raw = process.env.CPU_PROFILE_DIR
+			?? config?.['CPU_PROFILE_DIR'];
+		return typeof raw === 'string' && raw.trim() ? raw.trim() : null;
+	}
+
+	private resolveTimerDebug(): boolean {
+		const config = ResolveIOServer.getServerConfig ? ResolveIOServer.getServerConfig() : null;
+		const raw = process.env.TIMER_DEBUG
+			?? config?.['TIMER_DEBUG'];
+		return this.parseDebugFlag(raw);
+	}
+
+	private resolveTimerDebugThresholdMs(): number {
+		const config = ResolveIOServer.getServerConfig ? ResolveIOServer.getServerConfig() : null;
+		const raw = process.env.TIMER_DEBUG_THRESHOLD_MS
+			?? config?.['TIMER_DEBUG_THRESHOLD_MS'];
+		return this.parsePositiveFloat(raw, this._timerDebugThresholdMs);
+	}
+
+	private resolveTimerDebugMinDelayMs(): number {
+		const config = ResolveIOServer.getServerConfig ? ResolveIOServer.getServerConfig() : null;
+		const raw = process.env.TIMER_DEBUG_MIN_DELAY_MS
+			?? config?.['TIMER_DEBUG_MIN_DELAY_MS'];
+		return this.parsePositiveFloat(raw, this._timerDebugMinDelayMs);
+	}
+
+	private resolveTimerDebugSampleRate(): number {
+		const config = ResolveIOServer.getServerConfig ? ResolveIOServer.getServerConfig() : null;
+		const raw = process.env.TIMER_DEBUG_SAMPLE_RATE
+			?? config?.['TIMER_DEBUG_SAMPLE_RATE'];
+		const parsed = parseFloat(raw ?? '');
+		if (Number.isFinite(parsed) && parsed > 0 && parsed <= 1) {
+			return parsed;
+		}
+		return this._timerDebugSampleRate;
+	}
+
+	private resolveTimerDebugLogLimit(): number {
+		const config = ResolveIOServer.getServerConfig ? ResolveIOServer.getServerConfig() : null;
+		const raw = process.env.TIMER_DEBUG_LOG_LIMIT
+			?? config?.['TIMER_DEBUG_LOG_LIMIT'];
+		return this.parsePositiveInt(raw, this._timerDebugLogLimit);
+	}
+
+	private normalizeWorkerSelectorValue(value?: string | number | null): string | null {
+		if (value === null || value === undefined) {
+			return null;
+		}
+
+		const normalized = String(value).trim();
+		return normalized.length ? normalized : null;
+	}
+
+	private parseWorkerSelector(value: any): Set<string> | null {
+		if (value === null || value === undefined) {
+			return null;
+		}
+
+		const raw = Array.isArray(value) ? value.join(',') : String(value);
+		const parts = raw.split(',').map(part => part.trim()).filter(Boolean);
+		if (!parts.length) {
+			return null;
+		}
+
+		return new Set(parts);
+	}
+
+	private workerMatchesSelector(
+		workerIndex: string | null,
+		workerInstance: string | null,
+		indexes: Set<string> | null,
+		instances: Set<string> | null
+	): boolean {
+		if (!indexes && !instances) {
+			return false;
+		}
+
+		const indexMatch = indexes ? (workerIndex ? indexes.has(workerIndex) : false) : true;
+		const instanceMatch = instances ? (workerInstance ? instances.has(workerInstance) : false) : true;
+		return indexMatch && instanceMatch;
+	}
+
+	private resolveWorkerRole(): 'Codex' | 'Subscription' | 'Other' {
+		const workerIndex = this.normalizeWorkerSelectorValue(process.env.WORKER_INDEX);
+		const workerInstance = this.normalizeWorkerSelectorValue(process.env.NODE_APP_INSTANCE);
+		const publicationIndexes = this.parseWorkerSelector(
+			process.env.PUBLICATION_WORKER_INDEX
+			|| process.env.SUBSCRIPTION_WORKER_INDEX
+			|| process.env.WORKER_PUBLICATION_INDEX
+		);
+		const publicationInstances = this.parseWorkerSelector(
+			process.env.PUBLICATION_WORKER_INSTANCE
+			|| process.env.SUBSCRIPTION_WORKER_INSTANCE
+			|| process.env.WORKER_PUBLICATION_INSTANCE
+		);
+		const codexIndexes = this.parseWorkerSelector(
+			process.env.AI_ASSISTANT_CODEX_WORKER_INDEX
+			|| process.env.CODEX_WORKER_INDEX
+			|| process.env.WORKER_CODEX_INDEX
+		);
+		const codexInstances = this.parseWorkerSelector(
+			process.env.AI_ASSISTANT_CODEX_WORKER_INSTANCE
+			|| process.env.CODEX_WORKER_INSTANCE
+			|| process.env.WORKER_CODEX_INSTANCE
+		);
+
+		if (this.workerMatchesSelector(workerIndex, workerInstance, publicationIndexes, publicationInstances)) {
+			return 'Subscription';
+		}
+
+		if (this.workerMatchesSelector(workerIndex, workerInstance, codexIndexes, codexInstances)) {
+			return 'Codex';
+		}
+
+		return 'Other';
+	}
+
+	private parsePositiveInt(value: any, fallback: number): number {
+		const parsed = parseInt(value ?? '', 10);
+		if (Number.isNaN(parsed) || parsed <= 0) {
+			return fallback;
+		}
+		return parsed;
+	}
+
+	private parsePositiveFloat(value: any, fallback: number): number {
+		const parsed = parseFloat(value ?? '');
+		if (Number.isNaN(parsed) || parsed <= 0) {
+			return fallback;
+		}
+		return parsed;
+	}
+
+	private startPerfDebug(): void {
+		if (!this._perfDebug || this._perfDebugTimer) {
+			return;
+		}
+
+		this._perfDebugIntervalMs = this.parsePositiveInt(
+			process.env.PERF_DEBUG_INTERVAL_MS ?? process.env.CPU_DEBUG_INTERVAL_MS,
+			this._perfDebugIntervalMs
+		);
+
+		this._perfDebugLastCpu = process.cpuUsage();
+		this._perfDebugLastTs = Date.now();
+		this._eventLoopHistogram = monitorEventLoopDelay({ resolution: 20 });
+		this._eventLoopHistogram.enable();
+
+		this._perfDebugTimer = setInterval(() => {
+			const now = Date.now();
+			const elapsedMs = now - this._perfDebugLastTs;
+			const cpuDiff = this._perfDebugLastCpu ? process.cpuUsage(this._perfDebugLastCpu) : process.cpuUsage();
+			const cpuMs = (cpuDiff.user + cpuDiff.system) / 1000;
+			const cpuPct = elapsedMs > 0 ? (cpuMs / elapsedMs) * 100 : 0;
+
+			const mem = process.memoryUsage();
+			const heapUsedMb = round((mem.heapUsed / 1024 / 1024) * 10) / 10;
+			const rssMb = round((mem.rss / 1024 / 1024) * 10) / 10;
+
+			const handles = typeof (process as any)._getActiveHandles === 'function'
+				? (process as any)._getActiveHandles().length
+				: null;
+			const requests = typeof (process as any)._getActiveRequests === 'function'
+				? (process as any)._getActiveRequests().length
+				: null;
+
+			const histogram = this._eventLoopHistogram;
+			const eventLoop = histogram ? {
+				meanMs: round((histogram.mean / 1e6) * 100) / 100,
+				p50Ms: round((histogram.percentile(50) / 1e6) * 100) / 100,
+				p95Ms: round((histogram.percentile(95) / 1e6) * 100) / 100,
+				p99Ms: round((histogram.percentile(99) / 1e6) * 100) / 100,
+				maxMs: round((histogram.max / 1e6) * 100) / 100
+			} : null;
+			histogram?.reset();
+
+			console.log(new Date(), '[Perf Debug]', JSON.stringify({
+				cpuPct: round(cpuPct * 10) / 10,
+				cpuMs: round(cpuMs),
+				elapsedMs,
+				eventLoop,
+				heapUsedMb,
+				rssMb,
+				activeHandles: handles,
+				activeRequests: requests,
+				msgRecv: this._debugMsgRecv,
+				msgQueue: this._debugMsgQueue
+			}));
+
+			if (this._cpuProfileAuto) {
+				if (cpuPct >= this._cpuProfileThresholdPct) {
+					this._cpuProfileHighCount += 1;
+				}
+				else {
+					this._cpuProfileHighCount = 0;
+				}
+
+				if (this._cpuProfileHighCount >= this._cpuProfileTriggerCount) {
+					this._cpuProfileHighCount = 0;
+					this.startCpuProfile('auto-high-cpu');
+				}
+			}
+
+			this._perfDebugLastCpu = process.cpuUsage();
+			this._perfDebugLastTs = now;
+		}, this._perfDebugIntervalMs);
+	}
+
+	private installTimerDebug(): void {
+		if (!this._timerDebug) {
+			return;
+		}
+
+		const g = global as unknown as { __resolveioTimerDebugInstalled?: boolean };
+		if (g.__resolveioTimerDebugInstalled) {
+			return;
+		}
+		g.__resolveioTimerDebugInstalled = true;
+
+		const originalSetTimeout = global.setTimeout;
+		const originalSetInterval = global.setInterval;
+		const thresholdMs = this._timerDebugThresholdMs;
+		const minDelayMs = this._timerDebugMinDelayMs;
+		const sampleRate = this._timerDebugSampleRate;
+
+		const shouldSample = () => sampleRate >= 1 || Math.random() <= sampleRate;
+
+		const logTimer = (type: string, durationMs: number, delayMs: number | undefined, createdStack: string | undefined) => {
+			if (this._timerDebugLogLimit > 0 && this._timerDebugLogCount >= this._timerDebugLogLimit) {
+				return;
+			}
+			this._timerDebugLogCount += 1;
+			const stackLines = createdStack
+				? createdStack.split('\n').slice(1, 6).map(line => line.trim()).join(' | ')
+				: undefined;
+			console.log(new Date(), '[Timer Debug]', JSON.stringify({
+				type,
+				durationMs: round(durationMs * 10) / 10,
+				delayMs: delayMs ?? null,
+				createdAt: stackLines
+			}));
+		};
+
+		const wrapTimer = (handler: any, type: string, delayMs?: number) => {
+			if (typeof handler !== 'function') {
+				return handler;
+			}
+
+			const createdStack = new Error().stack;
+			const shouldFlagShortDelay = typeof delayMs === 'number' && delayMs <= minDelayMs;
+
+			return function wrappedTimer(this: any, ...args: any[]) {
+				const start = process.hrtime.bigint();
+				try {
+					return handler.apply(this, args);
+				}
+				finally {
+					const elapsedMs = Number(process.hrtime.bigint() - start) / 1e6;
+					if (shouldSample() && (elapsedMs >= thresholdMs || shouldFlagShortDelay)) {
+						logTimer(type, elapsedMs, delayMs, createdStack);
+					}
+				}
+			};
+		};
+
+		global.setTimeout = ((handler: any, timeout?: number, ...args: any[]) => {
+			return originalSetTimeout(wrapTimer(handler, 'setTimeout', timeout), timeout as any, ...args);
+		}) as typeof setTimeout;
+
+		global.setInterval = ((handler: any, timeout?: number, ...args: any[]) => {
+			return originalSetInterval(wrapTimer(handler, 'setInterval', timeout), timeout as any, ...args);
+		}) as typeof setInterval;
+	}
+
+	private startCpuProfile(trigger: string): void {
+		if (this._cpuProfileSession) {
+			return;
+		}
+
+		try {
+			const session = new inspector.Session();
+			session.connect();
+			session.post('Profiler.enable', () => {
+				session.post('Profiler.start', () => {
+					this._cpuProfileSession = session;
+					console.log(new Date(), '[Perf Debug]', 'CPU profile started', trigger);
+					setTimeout(() => {
+						this.stopCpuProfile(trigger);
+					}, this._cpuProfileDurationMs);
+				});
+			});
+		}
+		catch (error) {
+			console.error(new Date(), '[Perf Debug]', 'CPU profile start failed', error);
+		}
+	}
+
+	private stopCpuProfile(trigger: string): void {
+		const session = this._cpuProfileSession;
+		if (!session) {
+			return;
+		}
+
+		session.post('Profiler.stop', (err, res: { profile?: unknown }) => {
+			if (err) {
+				console.error(new Date(), '[Perf Debug]', 'CPU profile stop failed', err);
+			}
+			else {
+				try {
+					const dir = this.resolveWritableProfileDir();
+					const filename = `resolveio-cpuprofile-${process.pid}-${Date.now()}.cpuprofile`;
+					const filePath = path.join(dir, filename);
+					fs.writeFileSync(filePath, JSON.stringify(res?.profile ?? {}));
+					console.log(new Date(), '[Perf Debug]', 'CPU profile saved', filePath, trigger);
+				}
+				catch (writeErr) {
+					console.error(new Date(), '[Perf Debug]', 'CPU profile write failed', writeErr);
+				}
+			}
+
+			try {
+				session.disconnect();
+			}
+			catch {}
+
+			this._cpuProfileSession = null;
+		});
+	}
+
+	private resolveWritableProfileDir(): string {
+		const preferred = this._cpuProfileDir;
+		if (preferred) {
+			try {
+				fs.mkdirSync(preferred, { recursive: true });
+				return preferred;
+			}
+			catch {}
+		}
+
+		return os.tmpdir();
+	}
+
+	private parseDebugFlag(value: any): boolean {
+		if (value === true) {
+			return true;
+		}
+
+		if (value === false || value === null || value === undefined) {
+			return false;
+		}
+
+		if (typeof value === 'number') {
+			return value === 1;
+		}
+
+		if (typeof value === 'string') {
+			const normalized = value.trim().toLowerCase();
+			return ['1', 'true', 'yes', 'y', 'on'].includes(normalized);
+		}
+
+		return false;
+	}
+
+	private parseOptionalBoolean(value: any): boolean | null {
+		if (value === null || value === undefined) {
+			return null;
+		}
+		const normalized = `${value}`.trim();
+		if (!normalized) {
+			return null;
+		}
+		return this.parseDebugFlag(normalized);
+	}
+
+	private parseNonNegativeInt(value: any, fallback: number): number {
+		const parsed = parseInt(`${value ?? ''}`, 10);
+		if (Number.isNaN(parsed) || parsed < 0) {
+			return fallback;
+		}
+		return parsed;
+	}
+
+	private resolveSocketTier(): string {
+		const config = ResolveIOServer.getServerConfig() || {};
+		return `${process.env.AI_CODER_PLAN_TIER || config['AI_CODER_PLAN_TIER'] || ''}`.trim().toLowerCase();
+	}
+
+	private resolveSocketTierKeySuffix(planTier: string): string {
+		return `${planTier || ''}`
+			.trim()
+			.toUpperCase()
+			.replace(/[^A-Z0-9]+/g, '_');
+	}
+
+	private resolveMaxClientSockets(planTier: string): number {
+		const config = ResolveIOServer.getServerConfig() || {};
+		const explicitLimit = this.parseNonNegativeInt(
+			config['AI_CODER_MAX_SOCKETS'] ?? process.env.AI_CODER_MAX_SOCKETS,
+			-1
+		);
+		if (explicitLimit >= 0) {
+			return explicitLimit;
+		}
+
+		const normalizedTier = `${planTier || ''}`.trim().toLowerCase();
+		const tierKeySuffix = this.resolveSocketTierKeySuffix(normalizedTier);
+		if (tierKeySuffix) {
+			const tierLimitKey = `AI_CODER_MAX_SOCKETS_${tierKeySuffix}`;
+			const tierLimit = this.parseNonNegativeInt(
+				config[tierLimitKey] ?? process.env[tierLimitKey],
+				-1
+			);
+			if (tierLimit >= 0) {
+				return tierLimit;
+			}
+		}
+
+		const maxUsers = this.parseNonNegativeInt(
+			config['AI_CODER_MAX_USERS'] ?? process.env.AI_CODER_MAX_USERS,
+			-1
+		);
+		if (maxUsers > 0) {
+			return maxUsers === 1 ? 1 : maxUsers * 2;
+		}
+
+		if (normalizedTier === 'tool') {
+			return 1;
+		}
+		if (normalizedTier === 'small') {
+			return 10;
+		}
+		if (normalizedTier === 'medium') {
+			return 50;
+		}
+		if (normalizedTier === 'large') {
+			return 200;
+		}
+		if (normalizedTier === 'enterprise') {
+			return 0;
+		}
+
+		return 0;
+	}
+
+	private resolveSingleIpPerUserPolicy(planTier: string): boolean {
+		const config = ResolveIOServer.getServerConfig() || {};
+		const normalizedTier = `${planTier || ''}`.trim().toLowerCase();
+		const tierKeySuffix = this.resolveSocketTierKeySuffix(normalizedTier);
+		if (tierKeySuffix) {
+			const tierPolicyKey = `AI_CODER_SINGLE_IP_PER_USER_${tierKeySuffix}`;
+			const tierPolicy = this.parseOptionalBoolean(
+				config[tierPolicyKey] ?? process.env[tierPolicyKey]
+			);
+			if (tierPolicy !== null) {
+				return tierPolicy;
+			}
+		}
+
+		const policy = this.parseOptionalBoolean(
+			config['AI_CODER_SINGLE_IP_PER_USER'] ?? process.env.AI_CODER_SINGLE_IP_PER_USER
+		);
+		if (policy !== null) {
+			return policy;
+		}
+
+		return !!normalizedTier;
+	}
+
+	private resolveSocketPolicyUpgradeUrl(): string {
+		const config = ResolveIOServer.getServerConfig() || {};
+		const direct = `${config['AI_CODER_SOCKET_UPGRADE_URL'] || process.env.AI_CODER_SOCKET_UPGRADE_URL || ''}`.trim();
+		if (direct) {
+			return direct.replace(/\/$/, '');
+		}
+
+		const dashboard = `${config['AI_CODER_CLIENT_DASHBOARD_URL'] || process.env.AI_CODER_CLIENT_DASHBOARD_URL || ''}`.trim();
+		if (dashboard) {
+			return dashboard.replace(/\/$/, '');
+		}
+
+		const root = `${config['AI_CODER_ROOT_URL'] || process.env.AI_CODER_ROOT_URL || config['ROOT_URL'] || process.env.ROOT_URL || ''}`.trim();
+		if (!root) {
+			return '';
+		}
+
+		return `${root.replace(/\/$/, '')}/dashboard/client`;
+	}
+
+	private resolveSocketUpgradeUrlWithAppId(): string {
+		const base = `${this._socketPolicyUpgradeUrl || ''}`.trim();
+		if (!base) {
+			return '';
+		}
+		const appId = `${process.env.AI_CODER_APP_ID || ''}`.trim();
+		if (!appId) {
+			return base;
+		}
+		const separator = base.includes('?') ? '&' : '?';
+		return `${base}${separator}appId=${encodeURIComponent(appId)}`;
+	}
+
+	private normalizeIpAddress(value: any): string {
+		let ip = `${value || ''}`.trim();
+		if (!ip) {
+			return '';
+		}
+		if (ip.includes(',')) {
+			ip = ip.split(',')[0].trim();
+		}
+		if (ip.startsWith('::ffff:')) {
+			ip = ip.slice(7);
+		}
+		if (/^\d+\.\d+\.\d+\.\d+:\d+$/.test(ip)) {
+			ip = ip.split(':')[0].trim();
+		}
+		if (ip === '::1') {
+			return '127.0.0.1';
+		}
+		return ip.toLowerCase();
+	}
+
+	private resolveClientIp(req: any): string {
+		const forwardedFor = this.normalizeHeaderValue(req?.headers?.['x-forwarded-for']);
+		if (forwardedFor) {
+			return this.normalizeIpAddress(forwardedFor);
+		}
+		const realIp = this.normalizeHeaderValue(req?.headers?.['x-real-ip']);
+		if (realIp) {
+			return this.normalizeIpAddress(realIp);
+		}
+		const socketIp = req?.socket?.remoteAddress || req?.connection?.remoteAddress || req?.ip || '';
+		return this.normalizeIpAddress(socketIp);
+	}
+
+	private buildSocketLimitMessage(activeSockets: number): string {
+		const tierLabel = this._socketTier ? this._socketTier[0].toUpperCase() + this._socketTier.slice(1) : 'Current';
+		const upgradeUrl = this.resolveSocketUpgradeUrlWithAppId();
+		const base = `Socket connection limit reached (${activeSockets}/${this._maxClientSockets}) for the ${tierLabel} tier.`;
+		if (!upgradeUrl) {
+			return `${base} Upgrade to increase capacity.`;
+		}
+		return `${base} Upgrade at ${upgradeUrl}.`;
+	}
+
+	private buildSocketLimitCloseReason(): string {
+		return `Socket limit reached (${this._maxClientSockets})`;
+	}
+
+	private async disconnectUserSocketsFromDifferentIps(idUser: string, incomingIp: string): Promise<number> {
+		if (!this._websocketManager) {
+			return 0;
+		}
+
+		const normalizedUser = `${idUser || ''}`.trim();
+		const normalizedIncomingIp = this.normalizeIpAddress(incomingIp);
+		if (!normalizedUser || !normalizedIncomingIp) {
+			return 0;
+		}
+
+		const userSockets = this._websocketManager.getUserWebSockets(normalizedUser);
+		let disconnected = 0;
+		for (const existingSocket of userSockets) {
+			const existingIp = this.normalizeIpAddress(existingSocket?.['client_ip']);
+			if (!existingIp || existingIp === normalizedIncomingIp) {
+				continue;
+			}
+
+			this.logConnectDebug('WS single-ip enforcement disconnect', {
+				id_socket: existingSocket?.['id_socket'],
+				id_user: normalizedUser,
+				existingIp,
+				incomingIp: normalizedIncomingIp
+			});
+
+			await this.unsubscribeWS(existingSocket);
+			if (existingSocket.readyState === WebSocket.OPEN || existingSocket.readyState === WebSocket.CONNECTING) {
+				try {
+					existingSocket.close(1008, 'Signed in from another IP');
+				}
+				catch {}
+			}
+			disconnected += 1;
+		}
+
+		return disconnected;
+	}
+
+	private async evaluateClientSocketAdmission(idUser: string, req: any): Promise<{ allowed: boolean, statusCode: number, message: string, clientIp: string }> {
+		const normalizedUser = `${idUser || ''}`.trim();
+		const clientIp = this.resolveClientIp(req);
+
+		if (this._singleIpPerUser) {
+			await this.disconnectUserSocketsFromDifferentIps(normalizedUser, clientIp);
+		}
+
+		if (this._maxClientSockets > 0 && this._websocketManager) {
+			const activeSockets = this._websocketManager.getActiveWebSocketCount();
+			if (activeSockets >= this._maxClientSockets) {
+				const message = this.buildSocketLimitMessage(activeSockets);
+				this.logConnectDebug('WS socket limit blocked', {
+					id_user: normalizedUser,
+					clientIp,
+					activeSockets,
+					maxClientSockets: this._maxClientSockets
+				});
+				return {
+					allowed: false,
+					statusCode: 429,
+					message,
+					clientIp
+				};
+			}
+		}
+
+		return {
+			allowed: true,
+			statusCode: 200,
+			message: '',
+			clientIp
+		};
+	}
+
+	private logConnectDebug(message: string, details?: Record<string, unknown>): void {
+		if (!this._wsConnectDebug) {
+			return;
+		}
+
+		if (details) {
+			console.log(new Date(), '[Connect Debug]', message, JSON.stringify(details));
+		}
+		else {
+			console.log(new Date(), '[Connect Debug]', message);
+		}
+	}
+
+	private async triggerClientHeartbeat(ws: WebSocket): Promise<void> {
+		if (!ws || ws.readyState !== WebSocket.OPEN) {
+			return;
+		}
+
+		ws['pingTime'] = new Date();
+
+		try {
+			if (typeof ws.ping === 'function') {
+				ws.ping();
+			}
+		}
+		catch (err) {
+			if (this._methodManager?.getEnableDebug()) {
+				console.log(new Date(), 'Server App', 'Error WS Ping Frame', err);
+			}
+			await this.unsubscribeWS(ws);
+			return;
+		}
+
+		ws.send('ping', async (error) => {
+			if (error) {
+				if (this._methodManager?.getEnableDebug()) {
+					console.log(new Date(), 'Server App', 'Error WS Ping');
+				}
+				await this.unsubscribeWS(ws);
+			}
+		});
+	}
+
+	private shouldDeferHeartbeat(ws: WebSocket): boolean {
+		if (!ws || ws.readyState !== WebSocket.OPEN) {
+			return false;
+		}
+
+		const bufferedAmount = typeof ws.bufferedAmount === 'number' ? ws.bufferedAmount : 0;
+		return bufferedAmount >= this._clientHeartbeatBackpressureBytes;
+	}
+
+	private async handleClientMessage(ws: WebSocket, msg: any[]): Promise<void> {
+		// This is basically your old logic from processSocketMessage,
+		// but we'll insert our worker-queue logic for "method" calls.
+		try {
+			let messageRoute = msg[0];
+			let messageDate = msg[1];
+			let messageId = msg[2];
+			let type = msg[3];
+
+			if (!this.publicProgram && this._clientRoutes.some(a => messageRoute.includes(a)) && !ws['doc_user'].roles.groups.some(a => a.views.some(b => messageRoute.includes(b) || b.includes(messageRoute))) && !ws['doc_user'].roles.super_admin) {
+				return;
+			}
+
+			if (type === 'subscription') {
+				let subType = msg[4];
+				let pub = msg[5];
+				this.logConnectDebug('Subscription message', {
+					subType,
+					publication: pub,
+					messageId,
+					messageRoute,
+					args: Math.max(0, msg.length - 6),
+					id_socket: ws ? ws['id_socket'] : null,
+					user: ws ? ws['user'] : null
+				});
+
+				if (subType === 'sub') {
+					await this._subscriptionManager.subscribe(messageRoute, messageDate, ws, messageId, pub, msg.slice(6));
+				}
+				else {
+					this._subscriptionManager.unsubscribe(messageRoute, messageDate, ws, messageId, pub, msg.slice(6));
+				}
+			}
+			else if (!this.publicProgram && type === 'offline') {
+				let serverRes: ServerResponseModel = {
+					messageId: messageId,
+					hasError: false,
+					data: 'ACK'
+				};
+
+				if (ws && ws.readyState === WebSocket.OPEN) {
+					this._websocketManager.send(ws, serverRes);
+				}
+
+				this._offlineUpdates.push(ws);
+				let offlineUpdates = msg[4];
+
+				for (let i = 0; i < offlineUpdates.length; i++) {
+					let update = offlineUpdates[i];
+
+					let data = update.data;
+
+					// eslint-disable-next-line no-unused-vars
+					let updateRoute = data.shift();
+					// eslint-disable-next-line no-unused-vars
+					let updateDate = data.shift();
+					let updateMessageId = data.shift();
+					// eslint-disable-next-line no-unused-vars
+					let updateType = data.shift();
+					let method = data.shift();
+
+					let serverResMethod: ServerResponseModel = {
+						messageId: updateMessageId,
+						hasError: false,
+						data: 'ACK'
+					};
+
+					if (ws && ws.readyState === WebSocket.OPEN) {
+						this._websocketManager.send(ws, serverResMethod);
+					}
+
+					if (method === 'insertDocument' && data[0] === 'driver-gps') {
+						continue;
+					}
+					
+					if (method !== 'reportBuilderGetResults' && method !== 'reportBuilderGetDistinctValue' && method !== 'reportBuilderBuildTree' && method !== 'generatePDF' && method !== 'getWOOfflineData' && method !== 'countQuery' && method !== 'countWithQuery' && method !== 'countCollectionWithQuery' && method !== 'find' && method !== 'findOne' && method !== 'findWithOptions' && method !== 'getDrivers' && method !== 'processAirdropDistribution' && method !== 'qbHandleResponse') {
+						if (
+							ResolveIOServer.shouldWriteLogsOffline()
+						) {
+							ResolveIOServer.getLocalLogManager().writeLog({
+								type: 'log',
+								data: {
+									_id: objectIdHexString(),
+									createdAt: new Date(),
+									type: 'client-request',
+									collection: '',
+									id_document: '',
+									payload: getBinarySize(JSON.stringify([data])) < 1000000 ? JSON.stringify([data], null, 2) : 'Too Big',
+									method: method,
+									id_user: ws['id_user'] || '',
+									user: ws['user'] || '',
+									messageId: messageId,
+									route: messageRoute,
+									instance_index: process.env.NODE_APP_INSTANCE || '0'
+								}
+							});
+						}
+						else {
+							await Logs.insertOne({
+								_id: objectIdHexString(),
+								type: 'client-request',
+								collection: '',
+								id_document: '',
+								payload: getBinarySize(JSON.stringify([data])) < 1000000 ? JSON.stringify([data], null, 2) : 'Too Big',
+								method: method,
+								id_user: ws['id_user'] || '',
+								user: ws['user'] || '',
+								messageId: messageId,
+								route: messageRoute,
+								client: 'ResolveIO',
+								instance: ResolveIOServer.getInstanceHost(),
+								instance_index: process.env.NODE_APP_INSTANCE || '0'
+							});
+						}
+					}
+
+					if (this._methodManager._methods[method]) {
+						try {
+							await this._methodManager.callMethod.call(Object.assign({}, this._methodManager, MethodManager.prototype, {id_user: ws['id_user'], user: ws['user'], id_ws: ws['id_socket']}), method, ...data);
+						}
+						catch (err) {
+							console.log(new Date(), 'Offline Error', JSON.stringify(err, null, 2));
+						}
+
+						if (method === 'updateDocumentOffline' || method === 'updateDocumentPropsOffline') {
+							ResolveIOServer.getMongoManager().invalidateQueryCache(data[0]);
+						}
+					}
+					else {
+						console.log('Offline - Could not find method: ' + method);
+					}
+				}
+
+				this._offlineUpdates.splice(this._offlineUpdates.map(a => a['id_socket']).indexOf(ws['id_socket']), 1);
+			}
+			else {
+				// It's presumably a 'method' or something else
+				let dataCopy = [...msg];
+
+				dataCopy.shift();
+				// eslint-disable-next-line no-unused-vars
+				let date = dataCopy.shift();
+				let msgId = dataCopy.shift();
+				let msgType = dataCopy.shift();
+				
+				if (msgType === 'method') {
+					let methodName = dataCopy.shift();
+
+					if (ws['user_readonly']) {
+						return;
+					}
+
+					if (methodName !== 'reportBuilderGetResults' && methodName !== 'reportBuilderGetDistinctValue' && methodName !== 'reportBuilderBuildTree' && methodName !== 'generatePDF' && methodName !== 'getWOOfflineData' && methodName !== 'countQuery' && methodName !== 'countWithQuery' && methodName !== 'countCollectionWithQuery' && methodName !== 'find' && methodName !== 'findOne' && methodName !== 'findWithOptions' && methodName !== 'getDrivers' && methodName !== 'processAirdropDistribution') {
+						if (
+							ResolveIOServer.shouldWriteLogsOffline()
+						) {
+							ResolveIOServer.getLocalLogManager().writeLog({
+								type: 'log',
+								data: {
+									_id: objectIdHexString(),
+									createdAt: new Date(),
+									type: 'client-request',
+									collection: '',
+									id_document: '',
+									payload: getBinarySize(JSON.stringify([dataCopy])) < 1000000 ? JSON.stringify([dataCopy], null, 2) : 'Too Big',
+									method: methodName,
+									id_user: ws['id_user'] || '',
+									user: ws['user'] || '',
+									messageId: messageId,
+									route: messageRoute,
+									instance_index: process.env.NODE_APP_INSTANCE || '0'
+								}
+							});
+						}
+						else {
+							await Logs.insertOne({
+								_id: objectIdHexString(),
+								type: 'client-request',
+								collection: '',
+								id_document: '',
+								payload: getBinarySize(JSON.stringify([dataCopy])) < 1000000 ? JSON.stringify([dataCopy], null, 2) : 'Too Big',
+								method: methodName,
+								id_user: ws['id_user'] || '',
+								user: ws['user'] || '',
+								messageId: messageId,
+								route: messageRoute,
+								client: 'ResolveIO',
+								instance: ResolveIOServer.getInstanceHost(),
+								instance_index: process.env.NODE_APP_INSTANCE || '0'
+							});
+						}
+					}
+
+					// Immediately ACK
+					let ack: ServerResponseModel = {
+						messageId: msgId,
+						hasError: false,
+						data: 'ACK'
+					};
+
+					if (ws && ws.readyState === WebSocket.OPEN) {
+						this._websocketManager.send(ws, ack);
+					}
+
+					let method = this._methodManager.getMethod(methodName);
+					const forceWorker = this._isWorkersEnabled && !!method?.forceWorker;
+					const targetWorkerIndex = this._isWorkersEnabled && method ? method.targetWorkerIndex : null;
+					const targetWorkerInstance = this._isWorkersEnabled && method ? method.targetWorkerInstance : null;
+					const hasWorkerForMethod = this._workerDispatcherManager ? this._workerDispatcherManager.hasWorkersForMethod(methodName) : false;
+					const isAiCodex = methodName === 'aiCoderTerminalRunCodex' || methodName === 'aiCoderAppRunCodex';
+					const isExcludedFromWorker = (
+						methodName === 'find' ||
+						methodName === 'insertDocument' ||
+						methodName === 'countWithQuery' ||
+						methodName === 'findOne' ||
+						methodName === 'updateDocumentProps' ||
+						methodName === 'findWithOptions' ||
+						methodName === 'updateDocument' ||
+						methodName === 'insertErrorLog' ||
+						methodName === 'removeDocument' ||
+						methodName === 'supportCreateBillingUser' ||
+						methodName === 'getSignedUrl' ||
+						methodName === 'getSignedUrls' ||
+						methodName === 'getSignedUrlWithId' ||
+						methodName === 'incorrectUser' ||
+						methodName === 'reloadWS' ||
+						methodName === 'reconnectWS' ||
+						methodName === 'disconnectWS'
+					);
+
+					if ((targetWorkerIndex || targetWorkerInstance || forceWorker) && this._isWorkersEnabled && !hasWorkerForMethod && this._methodManager.getEnableDebug()) {
+						console.warn(new Date(), '[WorkerDispatcher] Worker unavailable, running method locally', {
+							method: methodName,
+							targetWorkerIndex: targetWorkerIndex || null,
+							targetWorkerInstance: targetWorkerInstance || null,
+							forceWorker
+						});
+					}
+
+					const shouldDispatchToWorker = (
+						method &&
+						!method.skipWorker &&
+						this._isWorkersEnabled &&
+						this._workerDispatcherManager &&
+						hasWorkerForMethod &&
+						(forceWorker || !isExcludedFromWorker)
+					);
+
+					if (isAiCodex && this._aiWorkerDebug) {
+						const queueSnapshot = this._workerDispatcherManager ? this._workerDispatcherManager.getQueueSnapshot() : null;
+						console.log(new Date(), '[AI Worker Debug] dispatch check', {
+							isWorkersEnabled: this._isWorkersEnabled,
+							isWorkerInstance: this._isWorkerInstance,
+							forceWorker,
+							hasWorkerForMethod,
+							targetWorkerIndex: targetWorkerIndex || null,
+							targetWorkerInstance: targetWorkerInstance || null,
+							shouldDispatchToWorker,
+							queueSnapshot
+						});
+					}
+
+					if (shouldDispatchToWorker) {
+						this._workerDispatcherManager.sendClientTask(msgId, methodName, dataCopy, {
+							id_user: ws['id_user'],
+							user: ws['user'],
+							id_ws: ws['id_socket']
+						});
+					}
+					else {
+						// No worker available: do method locally
+						if (methodName === 'aiCoderTerminalRunCodex' || methodName === 'aiCoderAppRunCodex') {
+							if (this._aiWorkerDebug) {
+								console.warn(new Date(), '[AI Worker Debug] AI execution running locally', {
+									isWorkersEnabled: this._isWorkersEnabled,
+									isWorkerInstance: this._isWorkerInstance,
+									targetWorkerIndex: targetWorkerIndex || null,
+									targetWorkerInstance: targetWorkerInstance || null,
+									hasWorkerForMethod
+								});
+							}
+							setTimeout(async () => {
+								try {
+									await this.callMethodLocally(ws, msgId, methodName, dataCopy);
+								}
+								catch (error) {
+									console.error(new Date(), 'AI execution run failed:', error);
+								}
+							}, 0);
+						}
+						else {
+							await this.callMethodLocally(ws, msgId, methodName, dataCopy);
+						}
+					}
+				}
+			}
+		}
+		catch (err) {
+			throw err;
+		}
+	}
+
+	/**
+	 * callMethodLocally is your old approach for invoking the method in-process.
+	 */
+	private async callMethodLocally(ws: WebSocket, messageId: number, method: string, params: any[]) {
+		let serverRes: ServerResponseModel = {
+			messageId: messageId,
+			hasError: false,
+			data: null
+		};
+		try {
+			// You can keep your logging code (LogMethodLatencies, Logs.insertOne, etc.)
+			let result = await this._methodManager.callMethod.call(
+				Object.assign({}, this._methodManager, MethodManager.prototype, {
+					id_user: ws['id_user'],
+					user: ws['user'],
+					id_ws: ws['id_socket']
+				}),
+				method,
+				...params
+			);
+
+			serverRes.data = result;
+			if (this._aiWorkerDebug && typeof method === 'string' && method.startsWith('ai')) {
+				let resultBytes: number | null = null;
+				try {
+					resultBytes = Buffer.byteLength(JSON.stringify(result));
+				}
+				catch {
+					resultBytes = null;
+				}
+				console.log(new Date(), '[AI Worker Debug] local method result', {
+					method,
+					messageId,
+					id_socket: ws ? ws['id_socket'] : null,
+					id_user: ws ? ws['id_user'] : null,
+					resultBytes
+				});
+			}
+		}
+		catch (err) {
+			serverRes.hasError = true;
+			serverRes.data = err || 'Unknown error';
+		}
+
+		if (ws && ws.readyState === WebSocket.OPEN) {
+			this._websocketManager.send(ws, serverRes);
+		}
+	}
+
+	
+
+	/**
+	 * Cleanly remove a client from the subscription manager, etc.
+	 */
+	public async unsubscribeWS(ws: WebSocket) {
+		if (this._subscriptionManager && this._methodManager.getEnableDebug()) {
+			console.log(new Date(), 'Server App', 'Unsub WS', ws['user'], ws['id_socket']);
+		}
+		this.logConnectDebug('WS unsubscribe', {
+			id_socket: ws ? ws['id_socket'] : null,
+			id_user: ws ? ws['id_user'] : null,
+			user: ws ? ws['user'] : null
+		});
+		await this._subscriptionManager.unsubscribeAll(ws);
+		ws.removeAllListeners();
+		ws = null;
+	}
+
+	public getApp() {
+		return this._app;
+	}
+
+	public getServerConfig() {
+		return ResolveIOServer.getServerConfig();
+	}
+
+	public getWorkerDispatcherManager() {
+		return this._workerDispatcherManager;
+	}
+
+	public getWorkerServerManager() {
+		return this._workerServerManager;
+	}
+}