@ankorcs/protocol 0.0.0-stage → 0.6.1

package/dist/checks.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Plain checks the schemas and the helpers share. Nothing here imports the rest of the contract.
+ */
+/** The validation message for a slot id that is not 1 to 32 letters, digits, `_` or `-`. */
+export declare const SLOT_ID_MESSAGE = "slot id must be 1-32 of [A-Za-z0-9_-] (it becomes part of a container name)";
+/** The validation message for a `controller.host` that {@link isControllerHost} rejects. */
+export declare const CONTROLLER_HOST_MESSAGE = "must be a host with an optional port and no scheme or path, e.g. cs.example.com, 192.168.0.10:3000 or [fd00::1]";
+/** Whether a value is a dotted-quad IPv4 address. */
+export declare function isIpv4(value: string): boolean;
+/**
+ * The hostname inside a `host[:port]`, without the brackets of an IPv6 literal. Null for a value
+ * that is not a host with an optional port.
+ */
+export declare function hostnameOf(host: string): string | null;
+/**
+ * Whether a value is a valid `controller.host`, by the rules that `agent.yml`, its editors and the
+ * node-setup script agree on.
+ */
+export declare function isControllerHost(value: string): boolean;

package/dist/checks.js

@@ -0,0 +1,40 @@
+/**
+ * Plain checks the schemas and the helpers share. Nothing here imports the rest of the contract.
+ */
+/** The validation message for a slot id that is not 1 to 32 letters, digits, `_` or `-`. */
+export const SLOT_ID_MESSAGE = 'slot id must be 1-32 of [A-Za-z0-9_-] (it becomes part of a container name)';
+/** The validation message for a `controller.host` that {@link isControllerHost} rejects. */
+export const CONTROLLER_HOST_MESSAGE = 'must be a host with an optional port and no scheme or path, e.g. cs.example.com, 192.168.0.10:3000 or [fd00::1]';
+const IPV4 = /^(25[0-5]|2[0-4]\d|1\d\d|[1-9]?\d)(\.(25[0-5]|2[0-4]\d|1\d\d|[1-9]?\d)){3}$/;
+/** Whether a value is a dotted-quad IPv4 address. */
+export function isIpv4(value) {
+    return IPV4.test(value);
+}
+/**
+ * The hostname inside a `host[:port]`, without the brackets of an IPv6 literal. Null for a value
+ * that is not a host with an optional port.
+ */
+export function hostnameOf(host) {
+    // URL parsing normalizes these away, but callers append paths to the original host.
+    if (/[\s\p{Cc}/\\?#]/u.test(host)) {
+        return null;
+    }
+    let url;
+    try {
+        url = new URL(`http://${host}`);
+    }
+    catch {
+        return null;
+    }
+    if (url.username !== '' || url.password !== '' || url.search !== '' || url.hash !== '' || url.pathname !== '/') {
+        return null;
+    }
+    return url.hostname === '' ? null : url.hostname.replace(/^\[|\]$/g, '');
+}
+/**
+ * Whether a value is a valid `controller.host`, by the rules that `agent.yml`, its editors and the
+ * node-setup script agree on.
+ */
+export function isControllerHost(value) {
+    return hostnameOf(value) !== null;
+}

package/dist/container.d.ts

@@ -0,0 +1,190 @@
+/**
+ * The interface between the agent and the game containers it runs, outside the wire to the
+ * controller: the environment the CS2 image and the plugin read, the plugin's config file, where
+ * recordings land and how they are named, the cfg files both sides exec, the local plugin socket
+ * and the handoff to a replacement agent. `packages/plugin/core/Wire/Launch.cs` mirrors the
+ * plugin's half.
+ */
+import { z } from 'zod';
+export * from './plugin-socket.js';
+export * from './agent-image.js';
+/** The path of the agent's local plugin socket. */
+export declare const PLUGIN_WS_PATH = "/ws/plugin";
+/**
+ * The environment variables the image entrypoint reads. The plugin also reads `startMap` and
+ * `workshopMap` to know when its map is loaded.
+ */
+export declare const CS2_ENV: {
+    /** The server's Game Server Login Token. */
+    readonly srcdsToken: "SRCDS_TOKEN";
+    readonly port: "CS2_PORT";
+    readonly tvPort: "CS2_TV_PORT";
+    /** `+tv_enable`, `1` or `0`. GOTV starts with the map, so it is set on the command line. */
+    readonly tvEnable: "CS2_TV_ENABLE";
+    readonly gamePassword: "CS2_PASSWORD";
+    readonly maxPlayers: "CS2_MAXPLAYERS";
+    /** `+game_type`, from {@link GAME_MODE_ARGS}. */
+    readonly gameType: "CS2_GAME_TYPE";
+    /** `+game_mode`, from {@link GAME_MODE_ARGS}. */
+    readonly gameMode: "CS2_GAME_MODE";
+    readonly startMap: "CS2_STARTMAP";
+    /**
+     * Passed separately so the entrypoint places `host_workshop_map` after the stock bootstrap map.
+     */
+    readonly workshopMap: "CS2_WORKSHOP_MAP";
+    /** The Steam Web API key that workshop downloads need, as `-authkey`. */
+    readonly authKey: "CS2_AUTHKEY";
+    readonly extraArgs: "CS2_EXTRA_ARGS";
+    readonly updateOnly: "CS2_UPDATE_ONLY";
+    readonly validate: "CS2_VALIDATE";
+    /** Empties the install volume before steamcmd runs. */
+    readonly reinstall: "CS2_REINSTALL";
+    /** Whole gigabytes the entrypoint requires free before it lets steamcmd stage anything. */
+    readonly minFreeGb: "CS2_MIN_FREE_GB";
+};
+/**
+ * The `+game_type` and `+game_mode` for each {@link GameMode}, as `gamemodes.txt` numbers them. The
+ * plugin's `CfgNames.Mode` maps the same pairs back to the modes' cfgs.
+ */
+export declare const GAME_MODE_ARGS: {
+    readonly casual: {
+        readonly gameType: 0;
+        readonly gameMode: 0;
+    };
+    readonly competitive: {
+        readonly gameType: 0;
+        readonly gameMode: 1;
+    };
+    readonly wingman: {
+        readonly gameType: 0;
+        readonly gameMode: 2;
+    };
+    readonly rush: {
+        readonly gameType: 0;
+        readonly gameMode: 6;
+    };
+    readonly arms_race: {
+        readonly gameType: 1;
+        readonly gameMode: 0;
+    };
+    readonly demolition: {
+        readonly gameType: 1;
+        readonly gameMode: 1;
+    };
+    readonly deathmatch: {
+        readonly gameType: 1;
+        readonly gameMode: 2;
+    };
+    readonly custom: {
+        readonly gameType: 3;
+        readonly gameMode: 0;
+    };
+};
+/** The environment variables that only the plugin reads. */
+export declare const ANKOR_ENV: {
+    /** The local relay the plugin dials for its slot. */
+    readonly wsUrl: "ANKOR_WS_URL";
+    /**
+     * The server's `allocation_id`, which identifies its events. A plugin without one sends nothing.
+     */
+    readonly allocationId: "ANKOR_ALLOCATION_ID";
+    readonly debugCaptureDir: "ANKOR_DEBUG_CAPTURE_DIR";
+};
+/** Where the cs2 image keeps its addon overlay. The agent copies it out once per image id. */
+export declare const IMAGE_OVERLAY_DIR = "/opt/ankor/overlay";
+/** The game installation inside the container. Per-slot writable paths shadow parts of it. */
+export declare const GAME_INSTALL_DIR = "/home/steam/cs2-dedicated";
+/**
+ * The slot's writable directory, relative to {@link GAME_INSTALL_DIR}. It holds everything per slot
+ * that the agent, the plugin and the engine share. The agent lays out its contents, so a new file
+ * or directory in it needs no mountpoint in the install.
+ */
+export declare const ANKOR_DIR = "game/csgo/ankor";
+/** GOTV recordings, relative to {@link GAME_INSTALL_DIR}, kept until uploaded. */
+export declare const DEMO_DIR = "game/csgo/ankor/demos";
+/** The engine's round backups, relative to {@link GAME_INSTALL_DIR}, emptied at every launch. */
+export declare const BACKUP_DIR = "game/csgo/ankor/backups";
+/**
+ * The file name of the engine's backup of a round, from the rounds played before it. The engine
+ * numbers a backup by those rounds in two digits or more, so `ankor_round13.txt` is round 14's.
+ */
+export declare function backupFileName(roundsPlayed: number): string;
+/**
+ * The launch's `restore.file` as the agent wrote it, relative to {@link GAME_INSTALL_DIR}. It is
+ * absent on a launch without a restore.
+ */
+export declare const RESTORE_FILE = "game/csgo/ankor/restore.txt";
+/**
+ * The match the server plays, relative to {@link GAME_INSTALL_DIR}. Every match server has it as
+ * {@link MatchConfig} in JSON, and a server without a match has none.
+ */
+export declare const MATCH_CONFIG_FILE = "game/csgo/ankor/match.json";
+/**
+ * The suffix the plugin adds to a recording's path to create a file once the recording is
+ * finished. The agent uploads a `.dem` only once that file exists.
+ */
+export declare const DEMO_READY_SUFFIX = ".ready";
+/**
+ * The plugin's SwiftlyS2 config file, rendered per launch and bind-mounted over the image's copy.
+ * Keys are PascalCase because the framework's configuration provider reads them that way.
+ */
+export declare const PluginConfigFile: z.ZodObject<{
+    Chat: z.ZodObject<{
+        Tag: z.ZodString;
+        TagColor: z.ZodEnum<{
+            white: "white";
+            darkred: "darkred";
+            lightpurple: "lightpurple";
+            green: "green";
+            olive: "olive";
+            lime: "lime";
+            red: "red";
+            gray: "gray";
+            lightyellow: "lightyellow";
+            yellow: "yellow";
+            silver: "silver";
+            bluegrey: "bluegrey";
+            lightblue: "lightblue";
+            blue: "blue";
+            darkblue: "darkblue";
+            purple: "purple";
+            magenta: "magenta";
+            lightred: "lightred";
+            gold: "gold";
+            orange: "orange";
+        }>;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+export type PluginConfigFile = z.infer<typeof PluginConfigFile>;
+/**
+ * Bytes in the largest frame the local event socket carries, on both the plugin's and the relay's
+ * side. It is at most {@link EVENT_BATCH_MAX_BYTES}, so an event that fits a frame fits an upload
+ * batch.
+ */
+export declare const MAX_FRAME_BYTES: number;
+/**
+ * Events a plugin may have waiting to be stored on the node. Past this or
+ * {@link RELAY_QUEUE_MAX_BYTES}, its history pauses.
+ */
+export declare const RELAY_QUEUE_MAX_FRAMES = 512;
+/** Bytes of events a plugin may have waiting to be stored on the node. */
+export declare const RELAY_QUEUE_MAX_BYTES: number;
+/**
+ * The directory under `cfg/` that the image ships its cfgs in. The plugin execs them, and a launch
+ * may exec any of them.
+ */
+export declare const CFG_DIR = "ankor";
+export declare const CFG_NAMES: {
+    /**
+     * Ankor's settings, which the plugin runs over the game mode's cfg on every map load and when a
+     * match goes live.
+     */
+    readonly base: "ankor/base";
+    readonly warmup: "ankor/warmup";
+    readonly knife: "ankor/knife";
+    /**
+     * The cfg the agent renders per launch at `cfg/ankor_launch.cfg`. The plugin runs it after
+     * `base`.
+     */
+    readonly launch: "ankor_launch";
+};

package/dist/container.js

@@ -0,0 +1,144 @@
+/**
+ * The interface between the agent and the game containers it runs, outside the wire to the
+ * controller: the environment the CS2 image and the plugin read, the plugin's config file, where
+ * recordings land and how they are named, the cfg files both sides exec, the local plugin socket
+ * and the handoff to a replacement agent. `packages/plugin/core/Wire/Launch.cs` mirrors the
+ * plugin's half.
+ */
+import { z } from 'zod';
+import { ChatColor } from './index.js';
+export * from './plugin-socket.js';
+export * from './agent-image.js';
+/** The path of the agent's local plugin socket. */
+export const PLUGIN_WS_PATH = '/ws/plugin';
+/**
+ * The environment variables the image entrypoint reads. The plugin also reads `startMap` and
+ * `workshopMap` to know when its map is loaded.
+ */
+export const CS2_ENV = {
+    /** The server's Game Server Login Token. */
+    srcdsToken: 'SRCDS_TOKEN',
+    port: 'CS2_PORT',
+    tvPort: 'CS2_TV_PORT',
+    /** `+tv_enable`, `1` or `0`. GOTV starts with the map, so it is set on the command line. */
+    tvEnable: 'CS2_TV_ENABLE',
+    gamePassword: 'CS2_PASSWORD',
+    maxPlayers: 'CS2_MAXPLAYERS',
+    /** `+game_type`, from {@link GAME_MODE_ARGS}. */
+    gameType: 'CS2_GAME_TYPE',
+    /** `+game_mode`, from {@link GAME_MODE_ARGS}. */
+    gameMode: 'CS2_GAME_MODE',
+    startMap: 'CS2_STARTMAP',
+    /**
+     * Passed separately so the entrypoint places `host_workshop_map` after the stock bootstrap map.
+     */
+    workshopMap: 'CS2_WORKSHOP_MAP',
+    /** The Steam Web API key that workshop downloads need, as `-authkey`. */
+    authKey: 'CS2_AUTHKEY',
+    extraArgs: 'CS2_EXTRA_ARGS',
+    updateOnly: 'CS2_UPDATE_ONLY',
+    validate: 'CS2_VALIDATE',
+    /** Empties the install volume before steamcmd runs. */
+    reinstall: 'CS2_REINSTALL',
+    /** Whole gigabytes the entrypoint requires free before it lets steamcmd stage anything. */
+    minFreeGb: 'CS2_MIN_FREE_GB',
+};
+/**
+ * The `+game_type` and `+game_mode` for each {@link GameMode}, as `gamemodes.txt` numbers them. The
+ * plugin's `CfgNames.Mode` maps the same pairs back to the modes' cfgs.
+ */
+export const GAME_MODE_ARGS = {
+    casual: { gameType: 0, gameMode: 0 },
+    competitive: { gameType: 0, gameMode: 1 },
+    wingman: { gameType: 0, gameMode: 2 },
+    rush: { gameType: 0, gameMode: 6 },
+    arms_race: { gameType: 1, gameMode: 0 },
+    demolition: { gameType: 1, gameMode: 1 },
+    deathmatch: { gameType: 1, gameMode: 2 },
+    custom: { gameType: 3, gameMode: 0 },
+};
+/** The environment variables that only the plugin reads. */
+export const ANKOR_ENV = {
+    /** The local relay the plugin dials for its slot. */
+    wsUrl: 'ANKOR_WS_URL',
+    /**
+     * The server's `allocation_id`, which identifies its events. A plugin without one sends nothing.
+     */
+    allocationId: 'ANKOR_ALLOCATION_ID',
+    debugCaptureDir: 'ANKOR_DEBUG_CAPTURE_DIR',
+};
+/** Where the cs2 image keeps its addon overlay. The agent copies it out once per image id. */
+export const IMAGE_OVERLAY_DIR = '/opt/ankor/overlay';
+/** The game installation inside the container. Per-slot writable paths shadow parts of it. */
+export const GAME_INSTALL_DIR = '/home/steam/cs2-dedicated';
+/**
+ * The slot's writable directory, relative to {@link GAME_INSTALL_DIR}. It holds everything per slot
+ * that the agent, the plugin and the engine share. The agent lays out its contents, so a new file
+ * or directory in it needs no mountpoint in the install.
+ */
+export const ANKOR_DIR = 'game/csgo/ankor';
+/** GOTV recordings, relative to {@link GAME_INSTALL_DIR}, kept until uploaded. */
+export const DEMO_DIR = `${ANKOR_DIR}/demos`;
+/** The engine's round backups, relative to {@link GAME_INSTALL_DIR}, emptied at every launch. */
+export const BACKUP_DIR = `${ANKOR_DIR}/backups`;
+/**
+ * The file name of the engine's backup of a round, from the rounds played before it. The engine
+ * numbers a backup by those rounds in two digits or more, so `ankor_round13.txt` is round 14's.
+ */
+export function backupFileName(roundsPlayed) {
+    return `ankor_round${String(roundsPlayed).padStart(2, '0')}.txt`;
+}
+/**
+ * The launch's `restore.file` as the agent wrote it, relative to {@link GAME_INSTALL_DIR}. It is
+ * absent on a launch without a restore.
+ */
+export const RESTORE_FILE = `${ANKOR_DIR}/restore.txt`;
+/**
+ * The match the server plays, relative to {@link GAME_INSTALL_DIR}. Every match server has it as
+ * {@link MatchConfig} in JSON, and a server without a match has none.
+ */
+export const MATCH_CONFIG_FILE = `${ANKOR_DIR}/match.json`;
+/**
+ * The suffix the plugin adds to a recording's path to create a file once the recording is
+ * finished. The agent uploads a `.dem` only once that file exists.
+ */
+export const DEMO_READY_SUFFIX = '.ready';
+/**
+ * The plugin's SwiftlyS2 config file, rendered per launch and bind-mounted over the image's copy.
+ * Keys are PascalCase because the framework's configuration provider reads them that way.
+ */
+export const PluginConfigFile = z.object({
+    Chat: z.object({ Tag: z.string(), TagColor: ChatColor }),
+});
+/**
+ * Bytes in the largest frame the local event socket carries, on both the plugin's and the relay's
+ * side. It is at most {@link EVENT_BATCH_MAX_BYTES}, so an event that fits a frame fits an upload
+ * batch.
+ */
+export const MAX_FRAME_BYTES = 2 << 20;
+/**
+ * Events a plugin may have waiting to be stored on the node. Past this or
+ * {@link RELAY_QUEUE_MAX_BYTES}, its history pauses.
+ */
+export const RELAY_QUEUE_MAX_FRAMES = 512;
+/** Bytes of events a plugin may have waiting to be stored on the node. */
+export const RELAY_QUEUE_MAX_BYTES = 4 << 20;
+/**
+ * The directory under `cfg/` that the image ships its cfgs in. The plugin execs them, and a launch
+ * may exec any of them.
+ */
+export const CFG_DIR = 'ankor';
+export const CFG_NAMES = {
+    /**
+     * Ankor's settings, which the plugin runs over the game mode's cfg on every map load and when a
+     * match goes live.
+     */
+    base: `${CFG_DIR}/base`,
+    warmup: `${CFG_DIR}/warmup`,
+    knife: `${CFG_DIR}/knife`,
+    /**
+     * The cfg the agent renders per launch at `cfg/ankor_launch.cfg`. The plugin runs it after
+     * `base`.
+     */
+    launch: 'ankor_launch',
+};