@ankorcs/protocol 0.0.0-stage → 0.6.1

package/dist/agent-yml.d.ts

@@ -0,0 +1,21 @@
+import type { z } from 'zod';
+import { AgentConfigSchema, type AgentConfig } from './agent-config.js';
+/**
+ * The keys the controller owns. An absent key is left alone, and `null` removes it from the file.
+ */
+export type AgentYmlFields = Partial<Pick<AgentConfig, 'token' | 'controller' | 'cs2_image' | 'agent_image' | 'pinned_ip' | 'auto_update' | 'demo_upload' | 'slots'>> & {
+    /** Null removes the cap. */
+    memory_mb?: number | null;
+};
+/** The given fields under their `agent.yml` keys, in file order. */
+export declare function agentYmlEntries(fields: AgentYmlFields): [string, unknown][];
+/**
+ * The keys the controller owns, as `agent.yml` takes them. A key that the file may leave out may
+ * be left out here too.
+ */
+export type AgentYmlInput = Omit<z.input<typeof AgentConfigSchema>, 'official_images_only'>;
+/**
+ * Renders the keys the controller owns as `agent.yml`, leaving out a key at its default. It throws
+ * on input that `agent.yml` would not accept.
+ */
+export declare function renderAgentYml(input: AgentYmlInput): string;

package/dist/agent-yml.js

@@ -0,0 +1,71 @@
+/**
+ * The `agent.yml` that a controller renders for a node. Its layout is part of the contract,
+ * because `node-setup.sh` reads the images back out with `sed`, so those top-level scalars stay
+ * unindented and unquoted.
+ */
+import { Document } from 'yaml';
+import { AgentConfigSchema } from './agent-config.js';
+import { DEFAULT_EVENTS_PATH, DEFAULT_SOCKET_PATH } from './paths.js';
+/** The given fields under their `agent.yml` keys, in file order. */
+export function agentYmlEntries(fields) {
+    const entries = [];
+    if (fields.token !== undefined) {
+        entries.push(['token', fields.token]);
+    }
+    if (fields.controller !== undefined) {
+        const controller = fields.controller;
+        entries.push(['controller', {
+                host: controller.host,
+                tls: controller.tls,
+                ...(controller.socket_path === DEFAULT_SOCKET_PATH ? {} : { socket_path: controller.socket_path }),
+                ...(controller.events_path === DEFAULT_EVENTS_PATH ? {} : { events_path: controller.events_path }),
+            }]);
+    }
+    if (fields.cs2_image !== undefined) {
+        entries.push(['cs2_image', fields.cs2_image]);
+    }
+    if (fields.agent_image !== undefined) {
+        entries.push(['agent_image', fields.agent_image]);
+    }
+    if (fields.pinned_ip !== undefined) {
+        entries.push(['pinned_ip', fields.pinned_ip]);
+    }
+    if (fields.memory_mb !== undefined) {
+        entries.push(['memory_mb', fields.memory_mb]);
+    }
+    // The default stays out of the file.
+    if (fields.auto_update !== undefined) {
+        entries.push(['auto_update', fields.auto_update ? null : false]);
+    }
+    if (fields.demo_upload !== undefined) {
+        const upload = fields.demo_upload;
+        entries.push(['demo_upload', upload === null ? null : {
+                url: upload.url,
+                ...(upload.header === null ? {} : { header: { name: upload.header.name, value: upload.header.value } }),
+                ...(upload.limit_mbit === null ? {} : { limit_mbit: upload.limit_mbit }),
+            }]);
+    }
+    if (fields.slots !== undefined) {
+        entries.push(['slots', fields.slots.map((slot) => ({
+                id: slot.id, port: slot.port, tv_port: slot.tv_port, gslt: slot.gslt,
+            }))]);
+    }
+    return entries;
+}
+/**
+ * Renders the keys the controller owns as `agent.yml`, leaving out a key at its default. It throws
+ * on input that `agent.yml` would not accept.
+ */
+export function renderAgentYml(input) {
+    const config = AgentConfigSchema.parse(input);
+    const values = Object.fromEntries(agentYmlEntries(config).filter(([, value]) => value !== null));
+    const document = new Document(values);
+    document.commentBefore = [
+        ' agent.yml for this Ankor node.',
+        " Keep it secret: it carries this node's auth token and its slots' GSLTs.",
+        '',
+        ' The controller can manage some parts of this file remotely.',
+        ' See https://docs.ankor.sh for documentation and setup help.'
+    ].join('\n');
+    return document.toString();
+}

package/dist/agent-yml.schema.json

@@ -0,0 +1,160 @@
+{
+  "type": "object",
+  "properties": {
+    "token": {
+      "type": "string",
+      "pattern": "^[A-Za-z0-9]{32,128}$",
+      "description": "The node token from the controller, 32 to 128 letters and digits. [Node tokens](https://docs.ankor.sh/protocol/#node-tokens) explains how one is made. **Keep the file secret.**"
+    },
+    "controller": {
+      "type": "object",
+      "properties": {
+        "host": {
+          "type": "string",
+          "description": "The controller's host with an optional port, without scheme or path, such as `cs.example.com`, `192.168.0.10:3000` or `[fd00::1]`. The agent may dial over IPv6, but players need IPv4.\n\nRejected when it contains whitespace, a control character, `/`, `\\`, `?` or `#`. It is also rejected unless `http://` followed by the value parses as a URL that has a host, an optional port and nothing else, such as a user name."
+        },
+        "tls": {
+          "type": "boolean",
+          "description": "Whether the agent dials `wss://` and `https://` rather than `ws://` and `http://`."
+        },
+        "socket_path": {
+          "default": "/ws/agent",
+          "type": "string",
+          "maxLength": 255,
+          "pattern": "^\\/(?:[A-Za-z0-9\\-._~!$&'()*+,;=:@/]|%[0-9A-Fa-f]{2})*$",
+          "description": "The agent socket's path on `host`, a `/` followed by URL path characters."
+        },
+        "events_path": {
+          "default": "/api/node/events",
+          "type": "string",
+          "maxLength": 255,
+          "pattern": "^\\/(?:[A-Za-z0-9\\-._~!$&'()*+,;=:@/]|%[0-9A-Fa-f]{2})*$",
+          "description": "The path on `host` that event batches are posted to, a `/` followed by URL path characters."
+        }
+      },
+      "required": [
+        "host",
+        "tls"
+      ],
+      "description": "Where the agent dials the controller."
+    },
+    "pinned_ip": {
+      "type": "string",
+      "description": "The IPv4 address players connect to, in place of the one the agent looks up. Rejected unless it is four numbers from 0 to 255 joined by dots, each without leading zeros."
+    },
+    "cs2_image": {
+      "type": "string",
+      "pattern": "^[A-Za-z0-9][A-Za-z0-9._\\-/:@]{0,254}$",
+      "description": "The `ankor-cs2` image future game servers run, as a Docker image reference."
+    },
+    "agent_image": {
+      "type": "string",
+      "pattern": "^[A-Za-z0-9][A-Za-z0-9._\\-/:@]{0,254}$",
+      "description": "The agent's image, which `node-setup.sh --update` runs and the agent replaces itself from, as a Docker image reference."
+    },
+    "memory_mb": {
+      "type": "integer",
+      "minimum": 1024,
+      "maximum": 65536,
+      "description": "MiB of memory each game container may use. Without it, game containers are not capped. CS2 installs and updates are exempt.\n\nRejected when it is not a whole number from 1024 to 65536."
+    },
+    "auto_update": {
+      "default": true,
+      "type": "boolean",
+      "description": "Whether the agent keeps the node up to date on its own. It updates CS2 to the newest public build and refuses launches while it is behind that build. It also moves `cs2_image` and `agent_image` to the newest release or rebuild in their major. It reads their tags from the registry every 60 minutes, and leaves an image named by digest or by a custom tag alone. When false, only [`update_cs2`](asyncapi.yaml#/components/schemas/ControllerUpdateCs2), [`update_cs2_image`](asyncapi.yaml#/components/schemas/ControllerUpdateCs2Image) and [`update_agent`](asyncapi.yaml#/components/schemas/ControllerUpdateAgent) change the build and the images."
+    },
+    "official_images_only": {
+      "default": true,
+      "type": "boolean",
+      "description": "Whether the node runs only the official images: `agent_image` from `ghcr.io/ankorcs/ankor-agent` and `cs2_image` from `ghcr.io/ankorcs/ankor-cs2`, with any tag or digest. While it is on, the agent refuses an [`update_agent`](asyncapi.yaml#/components/schemas/ControllerUpdateAgent) or [`update_cs2_image`](asyncapi.yaml#/components/schemas/ControllerUpdateCs2Image) to any other image with `image_not_allowed`, and `node-setup.sh` refuses to run one.\n\nOnly the node's operator can turn it off, by setting it to false in the file, to run images of their own. [`set_config`](asyncapi.yaml#/components/schemas/ControllerSetConfig) cannot change it. If the `agent.yml` that `node-setup.sh` fetches from the controller turns it off, the script stops."
+    },
+    "slots": {
+      "maxItems": 64,
+      "type": "array",
+      "items": {
+        "type": "object",
+        "properties": {
+          "id": {
+            "type": "string",
+            "pattern": "^[A-Za-z0-9_-]{1,32}$",
+            "description": "The slot's id, 1 to 32 letters, digits, `_` and `-`. It is unique on its node."
+          },
+          "port": {
+            "type": "integer",
+            "minimum": 1,
+            "maximum": 65535,
+            "description": "The game port, UDP. Every `port` and `tv_port` on a node is different, free on the host, and not 4500, the port the agent listens on for plugins. [Host networking](https://docs.ankor.sh/how-it-works/#host-networking) explains why."
+          },
+          "tv_port": {
+            "type": "integer",
+            "minimum": 1,
+            "maximum": 65535,
+            "description": "The GOTV port, UDP, under the same rules as `port`."
+          },
+          "gslt": {
+            "type": "string",
+            "pattern": "^[A-Za-z0-9]{10,64}$",
+            "description": "The slot's Game Server Login Token, which every server in the slot logs in with. It is 10 to 64 letters and digits. [Game Server Login Tokens](https://docs.ankor.sh/requirements/#game-server-login-tokens) explains them."
+          }
+        },
+        "required": [
+          "id",
+          "port",
+          "tv_port",
+          "gslt"
+        ]
+      },
+      "description": "The node's game server slots. Empty for a node that runs no servers yet. Such a node connects and reports, but accepts no launch."
+    },
+    "demo_upload": {
+      "type": "object",
+      "properties": {
+        "url": {
+          "type": "string",
+          "maxLength": 255,
+          "format": "uri",
+          "description": "The `http` or `https` URL finished demos are posted to. Rejected when it carries a user name or a password, which belong in `header`."
+        },
+        "header": {
+          "type": "object",
+          "properties": {
+            "name": {
+              "type": "string",
+              "pattern": "^[A-Za-z0-9-]{1,64}$",
+              "description": "The header's name, up to 64 letters, digits and `-`. Rejected when it is, in any case, one of `host`, `content-type`, `content-length`, `transfer-encoding`, `connection`, `keep-alive`, `upgrade`, `expect`, `te`, `trailer`, `ankor-protocol`, `ankor-file-name`, `ankor-match-id` and `ankor-allocation-id`, which the agent sets itself or which change how the request is framed."
+            },
+            "value": {
+              "type": "string",
+              "maxLength": 1024,
+              "pattern": "^[^\\r\\n\\u0000]*$",
+              "description": "The header's value, sent verbatim, without line breaks."
+            }
+          },
+          "required": [
+            "name",
+            "value"
+          ],
+          "description": "One header sent with every upload."
+        },
+        "limit_mbit": {
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 10000,
+          "description": "Megabits a second an upload may send while a game server runs on the node. Without it, uploads run at full speed."
+        }
+      },
+      "required": [
+        "url"
+      ],
+      "description": "Where finished demos are uploaded. Without it, demos stay on the node. [Demo uploads](https://docs.ankor.sh/protocol/demos/) describes the request."
+    }
+  },
+  "required": [
+    "token",
+    "controller",
+    "cs2_image",
+    "agent_image",
+    "slots"
+  ],
+  "description": "The node's `agent.yml` as the agent reads it. It is [`RawAgentConfigSchema`](https://docs.ankor.sh/configuration/#agentyml) with the checks that span slots, and it fills in `pinned_ip` and `demo_upload` as null when absent.\n\nRejected when two `slots` share an `id` or a `gslt`, or when two ports are equal. Every slot's `port` and `tv_port` count, so a slot's two ports differ too. It is also rejected when a port is 4500, where the agent listens for plugins."
+}