feat(core): host status api

tabarra · tabarra · commit 7bd5f0e6000d · 2025-02-24T14:00:00.000-03:00
diff --git a/core/boot/getHostVars.ts b/core/boot/getHostVars.ts
@@ -10,6 +10,13 @@ import consts from '@shared/consts';
  */
 export const hostEnvVarSchemas = {
     //General
+    API_TOKEN: z.union([
+        z.literal('disabled'),
+        z.string().regex(
+            /^[A-Za-z0-9_-]{16,48}$/,
+            'Token must be alphanumeric, underscores or dashes only, and between 16 and 48 characters long.'
+        ),
+    ]),
     DATA_PATH: z.string().min(1).refine(
         (val) => path.isAbsolute(val),
         'DATA_PATH must be an absolute path'
diff --git a/core/globalData.ts b/core/globalData.ts
@@ -292,6 +292,7 @@ if (netInterface) {
  * MARK: GENERAL
  */
 const forceGameName = hostVars.GAME_NAME;
+const hostApiToken = hostVars.API_TOKEN;
 
 const forceMaxClients = handleMultiVar(
     'MAX_SLOTS',
@@ -545,6 +546,7 @@ export const txHostConfig = Object.freeze({
     forceGameName,
     forceMaxClients,
     forceQuietMode,
+    hostApiToken,
 
     //Networking
     txaUrl,
diff --git a/core/modules/CacheStore.ts b/core/modules/CacheStore.ts
@@ -3,6 +3,7 @@ import fsp from 'node:fs/promises';
 import throttle from 'lodash-es/throttle.js';
 import consoleFactory from '@lib/console';
 import { txDevEnv, txEnv } from '@core/globalData';
+import type { z, ZodSchema } from 'zod';
 const console = consoleFactory(modulename);
 
 
@@ -50,6 +51,15 @@ export default class CacheStore {
         return this.#cache.get(key);
     }
 
+    getTyped<T extends ZodSchema>(key: string, schema: T): z.infer<T> | undefined {
+        if (!(this.#cache instanceof Map)) return undefined;
+        const value = this.#cache.get(key);
+        if (!value) return undefined;
+        const parsed = schema.safeParse(value);
+        if (parsed.success) return parsed.data;
+        return undefined;
+    }
+
     set(key: string, value: AcceptedCachedTypes) {
         if (!(this.#cache instanceof Map)) return false;
         if (!isAcceptedType(value)) throw new Error(`Value of type ${typeof value} is not acceptable.`);
diff --git a/core/modules/FxRunner/index.ts b/core/modules/FxRunner/index.ts
@@ -4,7 +4,7 @@ import StreamValues from 'stream-json/streamers/StreamValues';
 import { customAlphabet } from 'nanoid/non-secure';
 import dict49 from 'nanoid-dictionary/nolookalikes';
 import consoleFactory from '@lib/console';
-import { validateFixServerConfig } from '@lib/fxserver/fxsConfigHelper';
+import { resolveCFGFilePath, validateFixServerConfig } from '@lib/fxserver/fxsConfigHelper';
 import { msToShortishDuration } from '@lib/misc';
 import { SYM_SYSTEM_AUTHOR } from '@lib/symbols';
 import { UpdateConfigKeySet } from '@modules/ConfigStore/utils';
@@ -13,6 +13,7 @@ import ProcessManager, { ChildProcessStateInfo } from './ProcessManager';
 import handleFd3Messages from './handleFd3Messages';
 import ConsoleLineEnum from '@modules/Logger/FXServerLogger/ConsoleLineEnum';
 import { txHostConfig } from '@core/globalData';
+import path from 'node:path';
 const console = consoleFactory('FXRunner');
 const genMutex = customAlphabet(dict49, 5);
 
@@ -469,23 +470,27 @@ export default class FxRunner {
      * The resolved paths of the server
      * FIXME: check where those paths are needed and only calculate what is relevant
      */
-    // public get serverPaths() {
-    //     if (!this.isConfigured) return;
-    //     return {
-    //         data: {
-    //             absolute: 'xxx',
-    //         },
-    //         //TODO: cut paste logic from resolveCFGFilePath
-    //         resources: {
-    //             //???
-    //         },
-    //         cfg: {
-    //             fileName: 'xxx',
-    //             relativePath: 'xxx',
-    //             absolutePath: 'xxx',
-    //         }
-    //     };
-    // }
+    public get serverPaths() {
+        if (!this.isConfigured) return;
+        return {
+            dataPath: path.normalize(txConfig.server.dataPath!), //to maintain consistency
+            cfgPath: resolveCFGFilePath(txConfig.server.cfgPath, txConfig.server.dataPath!),
+        }
+        // return {
+        //     data: {
+        //         absolute: 'xxx',
+        //     },
+        //     //TODO: cut paste logic from resolveCFGFilePath
+        //     resources: {
+        //         //???
+        //     },
+        //     cfg: {
+        //         fileName: 'xxx',
+        //         relativePath: 'xxx',
+        //         absolutePath: 'xxx',
+        //     }
+        // };
+    }
 
 
     /**
diff --git a/core/modules/Logger/handlers/server.js b/core/modules/Logger/handlers/server.js
@@ -228,6 +228,15 @@ export default class ServerLogger extends LoggerBase {
             if (typeof eventData.data?.projectName === 'string' && eventData.data.projectName.length) {
                 txCore.cacheStore.set('fxsRuntime:projectName', eventData.data.projectName);
             }
+            if (typeof eventData.data?.gameName === 'string' && eventData.data.gameName.length) {
+                if(eventData.data.gameName === 'gta5'){
+                    txCore.cacheStore.set('fxsRuntime:gameName', 'fivem');
+                } else if (eventData.data.gameName === 'rdr3') {
+                    txCore.cacheStore.set('fxsRuntime:gameName', 'redm');
+                } else {
+                    txCore.cacheStore.delete('fxsRuntime:gameName');
+                }
+            }
 
         } else if (eventData.type === 'DebugMessage') {
             eventMessage = (typeof eventData.data === 'string')
diff --git a/core/modules/WebServer/middlewares/authMws.ts b/core/modules/WebServer/middlewares/authMws.ts
@@ -3,6 +3,7 @@ import consoleFactory from '@lib/console';
 import { checkRequestAuth } from "../authLogic";
 import { ApiAuthErrorResp, ApiToastResp, GenericApiErrorResp } from "@shared/genericApiTypes";
 import { InitializedCtx } from '../ctxTypes';
+import { txHostConfig } from '@core/globalData';
 const console = consoleFactory(modulename);
 
 const webLogoutPage = `<style>
@@ -37,6 +38,62 @@ body {
 </script>`;
 
 
+/**
+ * For the hosting provider routes
+ */
+export const hostAuthMw = async (ctx: InitializedCtx, next: Function) => {
+    const docs = 'https://aka.cfx.re/txadmin-env-config';
+
+    //Token disabled
+    if (txHostConfig.hostApiToken === 'disabled') {
+        return await next();
+    }
+
+    //Token undefined
+    if (!txHostConfig.hostApiToken) {
+        return ctx.send({
+            error: 'token not configured',
+            desc: 'need to configure the TXHOST_API_TOKEN environment variable to be able to use the status endpoint',
+            docs,
+        });
+    }
+
+    //Token available
+    let tokenProvided: string | undefined;
+    const headerToken = ctx.headers['x-txadmin-envtoken'];
+    if (typeof headerToken === 'string' && headerToken) {
+        tokenProvided = headerToken;
+    }
+    const paramsToken = ctx.query.envtoken;
+    if (typeof paramsToken === 'string' && paramsToken) {
+        tokenProvided = paramsToken;
+    }
+    if (headerToken && paramsToken) {
+        return ctx.send({
+            error: 'token conflict',
+            desc: 'cannot use both header and query token',
+            docs,
+        });
+    }
+    if (!tokenProvided) {
+        return ctx.send({
+            error: 'token missing',
+            desc: 'a token needs to be provided in the header or query string',
+            docs,
+        });
+    }
+    if (tokenProvided !== txHostConfig.hostApiToken) {
+        return ctx.send({
+            error: 'invalid token',
+            desc: 'the token provided does not match the TXHOST_API_TOKEN environment variable',
+            docs,
+        });
+    }
+
+    return await next();
+};
+
+
 /**
  * Intercom auth middleware
  * This does not set ctx.admin and does not use session/cookies whatsoever.
diff --git a/core/modules/WebServer/router.ts b/core/modules/WebServer/router.ts
@@ -3,7 +3,7 @@ import Router from '@koa/router';
 import KoaRateLimit from 'koa-ratelimit';
 
 import * as routes from '@routes/index';
-import { apiAuthMw, intercomAuthMw, webAuthMw } from './middlewares/authMws';
+import { apiAuthMw, hostAuthMw, intercomAuthMw, webAuthMw } from './middlewares/authMws';
 
 
 /**
@@ -114,6 +114,9 @@ export default () => {
     router.get('/whitelist/:table', apiAuthMw, routes.whitelist_list);
     router.post('/whitelist/:table/:action', apiAuthMw, routes.whitelist_actions);
 
+    //Host routes
+    router.get('/host/status', hostAuthMw, routes.host_status);
+
     //DevDebug routes - no auth
     if (txDevEnv.ENABLED) {
         router.get('/dev/:scope', routes.dev_get);
diff --git a/core/routes/hostStatus.ts b/core/routes/hostStatus.ts
@@ -0,0 +1,10 @@
+import { txHostConfig } from '@core/globalData';
+import type { InitializedCtx } from '@modules/WebServer/ctxTypes';
+
+
+/**
+ * Returns host status information
+ */
+export default async function HostStatus(ctx: InitializedCtx) {
+    return ctx.send(txManager.hostStatus);
+};
diff --git a/core/routes/index.ts b/core/routes/index.ts
@@ -63,14 +63,15 @@ export { default as whitelist_page } from './whitelist/page';
 export { default as whitelist_list } from './whitelist/list';
 export { default as whitelist_actions } from './whitelist/actions';
 
-
 export { default as advanced_page } from './advanced/get';
 export { default as advanced_actions } from './advanced/actions';
 
 //FIXME: reorganizar TODAS rotas de logs, incluindo listagem e download
 export { default as serverLog } from './serverLog.js';
 export { default as serverLogPartial } from './serverLogPartial.js';
 
+export { default as host_status } from './hostStatus';
+
 export {
     get as dev_get,
     post as dev_post,
diff --git a/core/txManager.ts b/core/txManager.ts
@@ -6,8 +6,27 @@ import { TxConfigState } from "@shared/enums";
 import type { GlobalStatusType } from "@shared/socketioTypes";
 import quitProcess from "@lib/quitProcess";
 import consoleFactory, { processStdioEnsureEol, setTTYTitle } from "@lib/console";
+import { z } from "zod";
 const console = consoleFactory('Manager');
 
+//Types
+type HostStatusType = {
+    //txAdmin state
+    cfgPath: string | null;
+    dataPath: string | null;
+    isConfigured: boolean;
+    playerCount: number;
+    status: typeof txCore.fxMonitor.currentStatus;
+
+    //Detected at runtime
+    cfxId: string | null;
+    gameName: 'fivem' | 'redm' | null;
+    joinLink: string | null;
+    joinDeepLink: string | null;
+    playerSlots: number | null;
+    projectName: string | null;
+}
+
 
 /**
  * This class is for "high order" logic and methods that shouldn't live inside any specific component.
@@ -125,6 +144,31 @@ export default class TxManager {
     }
 
 
+    /**
+     * Returns the status object that is sent to the host status endpoint
+     */
+    get hostStatus(): HostStatusType {
+        const serverPaths = txCore.fxRunner.serverPaths;
+        const cfxId = txCore.cacheStore.getTyped('fxsRuntime:cfxId', z.string()) ?? null;
+        return {
+            //txAdmin state
+            isConfigured: this.configState === TxConfigState.Ready,
+            dataPath: serverPaths?.dataPath ?? null,
+            cfgPath: serverPaths?.cfgPath ?? null,
+            playerCount: txCore.fxPlayerlist.onlineCount,
+            status: txCore.fxMonitor.currentStatus,
+
+            //Detected at runtime
+            cfxId,
+            gameName: txCore.cacheStore.getTyped('fxsRuntime:gameName', z.enum(['fivem', 'redm'])) ?? null,
+            joinDeepLink: cfxId ? `fivem://connect/cfx.re/join/${cfxId}` : null,
+            joinLink: cfxId ? `https://cfx.re/join/${cfxId}` : null,
+            playerSlots: txCore.cacheStore.getTyped('fxsRuntime:maxClients', z.number()) ?? null,
+            projectName: txCore.cacheStore.getTyped('fxsRuntime:projectName', z.string()) ?? null,
+        }
+    }
+
+
     /**
      * Returns the global status object that is sent to the clients
      */
@@ -141,7 +185,6 @@ export default class TxManager {
                 name: txConfig.general.serverName,
                 whitelist: txConfig.whitelist.mode,
             },
-            // @ts-ignore scheduler type narrowing is wrong because cant use "as const" in javascript
             scheduler: txCore.fxScheduler.getStatus(), //no push events, updated every Scheduler.checkSchedule()
         }
     }
diff --git a/docs/env-config.md b/docs/env-config.md
@@ -58,6 +58,13 @@ The specific way to set up those variables vary from system to system, and there
     - If true, do not pipe the FXServer's stdout/stderr to txAdmin's stdout, meaning that you will only be able to see the server output by visiting the txAdmin Live Console page.
     - If enabled, server owners won't be able to disable it in `txAdmin -> Settings -> FXServer` page.
     - <mark>NOTE:</mark> We recommend that Game Server Providers enable this option.
+- **TXHOST_API_TOKEN**
+    - **Default value:** _undefined_.
+    - **Options:** `disabled` or a string matching `/^[A-Za-z0-9_-]{16,48}$/`.
+    - The token to be able to access the `/host/status` endpoint via the `x-txadmin-envtoken` HTTP header, or the `?envtoken=` URL parameter.
+    - If token is _undefined_: endpoint disabled & unavailable.
+    - If token is string `disabled`: endpoint will be publicly available without any restrictions.
+    - If token is present: endpoint requires the token to be present.
 
 ### Networking
 - **TXHOST_TXA_URL:**
