@ankorcs/protocol 0.0.0-stage → 0.6.1

package/CHANGELOG.md

@@ -0,0 +1,9 @@
+# Changelog
+
+## 0.6.1
+
+No contract changes. The first release that the release workflow publishes.
+
+## 0.6.0
+
+Initial release.

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 Nicolai Cornelis
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -1,3 +1,73 @@
-# Temporary Holding Version
+# @ankorcs/protocol
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The wire protocol between Ankor game-host agents and the controller that runs them: the agent
+socket, the event-batch upload and the gameplay events it carries, `agent.yml`, and the paths,
+limits and timings both ends share. It holds zod schemas, constants and types, and an `agent.yml`
+renderer.
+
+```sh
+npm install @ankorcs/protocol
+```
+
+```ts
+import { AgentToControllerMessage, PROTOCOL_VERSION } from '@ankorcs/protocol';
+
+const message = AgentToControllerMessage.parse(JSON.parse(frame));
+```
+
+- `@ankorcs/protocol` is the wire: schemas and constants. The
+  [protocol reference](https://docs.ankor.sh/reference/) documents every message from their JSDoc.
+- `@ankorcs/protocol/helpers` has functions both ends share, such as slot layout checks and
+  `gsltHint`. It is not part of the protocol reference.
+- `@ankorcs/protocol/agent-yml` renders the `agent.yml` a service hands a node. It is the only
+  module that loads `yaml`.
+- `@ankorcs/protocol/session` is the controller's session on top of these schemas, described under
+  [Agent session](#agent-session).
+- `@ankorcs/protocol/container` is the interface between the agent and the game containers it runs:
+  the environment the CS2 image and the plugin read, the local plugin socket's messages, the cfg
+  files both sides exec and the handoff to a replacement agent. It is not part of the wire to the
+  controller.
+- `@ankorcs/protocol/node-setup.sh` is the script that installs a game node, which a controller
+  serves to operators at [`SETUP_SCRIPT_PATH`](https://github.com/ankorcs/ankor/blob/e50c71d936be7ef7401fca02723c79f2d550870b/packages/protocol/src/paths.ts).
+- `@ankorcs/protocol/asyncapi.yaml` and `@ankorcs/protocol/agent-yml.schema.json` are the
+  protocol's AsyncAPI 3.1 document and the JSON Schema of `agent.yml`, built from the schemas and
+  their JSDoc.
+
+## Agent session
+
+`@ankorcs/protocol/session` pairs each request with its reply on the agent socket and types the
+reply's `data` by the request. The [protocol overview](https://docs.ankor.sh/protocol/) shows how a
+controller uses it, and [A minimal controller](https://docs.ankor.sh/protocol/minimal-controller/)
+uses it step by step. Each export's JSDoc documents it. Tests drive the session with a fake
+`send` and frames as text.
+
+## Changing the protocol
+
+1. Edit the zod schemas in [`src`](https://github.com/ankorcs/ankor/tree/e50c71d936be7ef7401fca02723c79f2d550870b/packages/protocol/src). JSDoc on a schema or key becomes its description in the
+   reference; per-event semantics belong there, not in the guides.
+   [Conventions](https://github.com/ankorcs/ankor/blob/e50c71d936be7ef7401fca02723c79f2d550870b/packages/protocol/CONVENTIONS.md) says how to write it.
+2. Add or update the message's example in [reference/examples.json](https://github.com/ankorcs/ankor/blob/e50c71d936be7ef7401fca02723c79f2d550870b/packages/protocol/reference/examples.json), and a
+   new message's support and group in [reference/asyncapi.ts](https://github.com/ankorcs/ankor/blob/e50c71d936be7ef7401fca02723c79f2d550870b/packages/protocol/reference/asyncapi.ts).
+3. Run `npm run build`. After `tsc`, it writes `dist/asyncapi.yaml` and `dist/agent-yml.schema.json`.
+   It fails on a missing or mismatched example, an unlisted message, a link it cannot place, or a
+   refinement whose JSDoc does not state its rule. Then
+   [reference/dist-links.ts](https://github.com/ankorcs/ankor/blob/e50c71d936be7ef7401fca02723c79f2d550870b/packages/protocol/reference/dist-links.ts) makes the guide links in the comments of
+   `dist/` absolute, and [tsconfig.dist.json](https://github.com/ankorcs/ankor/blob/e50c71d936be7ef7401fca02723c79f2d550870b/packages/protocol/tsconfig.dist.json) checks that `dist/` still parses
+   and typechecks. The package ships `dist/` and no source. Preview the reference with `npm run docs:dev`
+   from the repository root, at `/reference/`.
+
+- `unsupportedAgentYmlKeys` stays in agent-config.ts, beside the private `agent.yml` schema it reads.
+- values.ts must not import helpers.ts: the cycle through agent-socket.ts would leave its schemas
+  undefined at load. What both need lives in [checks.ts](https://github.com/ankorcs/ankor/blob/e50c71d936be7ef7401fca02723c79f2d550870b/packages/protocol/src/checks.ts).
+- The plugin's C# copies of the contract are kept in step by hand, as
+  [Change the contract](https://github.com/ankorcs/ankor/blob/e50c71d936be7ef7401fca02723c79f2d550870b/DEVELOPMENT.md#change-the-contract) describes.
+- Judge a field against the protocol, not [ankor.sh](https://ankor.sh). A value ankor.sh always sends as a constant, or
+  never reads, can serve another controller. The agent is the only node-side implementation,
+  so it alone shows whether a field is written or read on that side.
+- Make a field only as strict as the agent needs; rules [ankor.sh](https://ankor.sh) sets for its users stay in ankor.sh.
+  A rule both ends depend on is an exported value the agent itself uses, not JSDoc prose.
+- `PROTOCOL_VERSION` is the package's `major.minor`, and a test holds it to `package.json`.
+  [Versioning](https://docs.ankor.sh/protocol/versioning/) says what a minor may change and how a receiver
+  treats what a newer peer adds.
+- Keep a schema a plain `z.object`, so that unknown keys are ignored, and check a new union with
+  `unknownMessageType` from the receiver's side.

package/dist/agent-config.d.ts

@@ -0,0 +1,101 @@
+/**
+ * The `agent.yml` schema that the agent's reader and whoever renders the file for a node share.
+ * Parsing fills in the defaults for the keys the file may leave out.
+ */
+import { z } from 'zod';
+/**
+ * The node's `agent.yml` as the agent reads it. It is {@link RawAgentConfigSchema} with the checks
+ * that span slots, and it fills in `pinned_ip` and `demo_upload` as null when absent.
+ *
+ * Rejected 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
+ * {@link EVENT_RELAY_PORT}, where the agent listens for plugins.
+ */
+export declare const AgentConfigSchema: z.ZodPipe<z.ZodObject<{
+    token: z.ZodString;
+    controller: z.ZodObject<{
+        host: z.ZodString;
+        tls: z.ZodBoolean;
+        socket_path: z.ZodDefault<z.ZodString>;
+        events_path: z.ZodDefault<z.ZodString>;
+    }, z.core.$strip>;
+    pinned_ip: z.ZodOptional<z.ZodString>;
+    cs2_image: z.ZodString;
+    agent_image: z.ZodString;
+    memory_mb: z.ZodOptional<z.ZodNumber>;
+    auto_update: z.ZodDefault<z.ZodBoolean>;
+    official_images_only: z.ZodDefault<z.ZodBoolean>;
+    slots: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        port: z.ZodNumber;
+        tv_port: z.ZodNumber;
+        gslt: z.ZodString;
+    }, z.core.$strip>>;
+    demo_upload: z.ZodOptional<z.ZodObject<{
+        url: z.ZodURL;
+        header: z.ZodOptional<z.ZodObject<{
+            name: z.ZodString;
+            value: z.ZodString;
+        }, z.core.$strip>>;
+        limit_mbit: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>>;
+}, z.core.$strip>, z.ZodTransform<{
+    pinned_ip: string | null;
+    demo_upload: {
+        url: string;
+        header: {
+            name: string;
+            value: string;
+        } | null;
+        limit_mbit: number | null;
+    } | null;
+    token: string;
+    controller: {
+        host: string;
+        tls: boolean;
+        socket_path: string;
+        events_path: string;
+    };
+    cs2_image: string;
+    agent_image: string;
+    auto_update: boolean;
+    official_images_only: boolean;
+    slots: {
+        id: string;
+        port: number;
+        tv_port: number;
+        gslt: string;
+    }[];
+    memory_mb?: number | undefined;
+}, {
+    token: string;
+    controller: {
+        host: string;
+        tls: boolean;
+        socket_path: string;
+        events_path: string;
+    };
+    cs2_image: string;
+    agent_image: string;
+    auto_update: boolean;
+    official_images_only: boolean;
+    slots: {
+        id: string;
+        port: number;
+        tv_port: number;
+        gslt: string;
+    }[];
+    pinned_ip?: string | undefined;
+    memory_mb?: number | undefined;
+    demo_upload?: {
+        url: string;
+        header?: {
+            name: string;
+            value: string;
+        } | undefined;
+        limit_mbit?: number | undefined;
+    } | undefined;
+}>>;
+export type AgentConfig = z.infer<typeof AgentConfigSchema>;
+/** Keys the file carries that this agent does not read, as dotted paths. Parsing ignores them. */
+export declare function unsupportedAgentYmlKeys(raw: unknown): string[];

package/dist/agent-config.js

@@ -0,0 +1,144 @@
+/**
+ * The `agent.yml` schema that the agent's reader and whoever renders the file for a node share.
+ * Parsing fills in the defaults for the keys the file may leave out.
+ */
+import { z } from 'zod';
+import { MAX_SLOTS } from './limits.js';
+import { addGsltIssues, addSlotLayoutIssues } from './helpers.js';
+import { AGENT_MIN_SLOT_PORT, ConfiguredSlot, DemoUploadHeader, DemoUploadLimit, DemoUploadUrl, ImageReference, Ipv4, MemoryLimit, NodeToken, ControllerHost, ControllerPath, } from './values.js';
+import { DEFAULT_EVENTS_PATH, DEFAULT_SOCKET_PATH } from './paths.js';
+const DemoUploadFields = z.object({
+    /**
+     * The `http` or `https` URL finished demos are posted to. Rejected when it carries a user name or a
+     * password, which belong in `header`.
+     */
+    url: DemoUploadUrl,
+    /** One header sent with every upload. */
+    header: DemoUploadHeader.optional(),
+    /**
+     * Megabits a second an upload may send while a game server runs on the node. Without it, uploads
+     * run at full speed.
+     */
+    limit_mbit: DemoUploadLimit.optional(),
+});
+const ControllerFields = z.object({
+    /**
+     * 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.
+     *
+     * Rejected 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.
+     */
+    host: ControllerHost,
+    /** Whether the agent dials `wss://` and `https://` rather than `ws://` and `http://`. */
+    tls: z.boolean(),
+    /** The agent socket's path on `host`, a `/` followed by URL path characters. */
+    socket_path: ControllerPath.default(DEFAULT_SOCKET_PATH),
+    /** The path on `host` that event batches are posted to, a `/` followed by URL path characters. */
+    events_path: ControllerPath.default(DEFAULT_EVENTS_PATH),
+});
+const RawAgentConfigSchema = z
+    .object({
+    /**
+     * 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.**
+     */
+    token: NodeToken,
+    /** Where the agent dials the controller. */
+    controller: ControllerFields,
+    /**
+     * 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.
+     */
+    pinned_ip: Ipv4.optional(),
+    /** The `ankor-cs2` image future game servers run, as a Docker image reference. */
+    cs2_image: ImageReference,
+    /**
+     * The agent's image, which `node-setup.sh --update` runs and the agent replaces itself from, as
+     * a Docker image reference.
+     */
+    agent_image: ImageReference,
+    /**
+     * MiB of memory each game container may use. Without it, game containers are not capped. CS2
+     * installs and updates are exempt.
+     *
+     * Rejected when it is not a whole number from {@link MIN_MEMORY_MB} to {@link MAX_MEMORY_MB}.
+     */
+    memory_mb: MemoryLimit.optional(),
+    /**
+     * 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 {@link IMAGE_UPDATE_POLL_INTERVAL_MS}, and leaves an image named by digest or
+     * by a custom tag alone. When false, only {@link ControllerUpdateCs2 | update_cs2},
+     * {@link ControllerUpdateCs2Image | update_cs2_image} and {@link ControllerUpdateAgent | update_agent} change
+     * the build and the images.
+     */
+    auto_update: z.boolean().default(true),
+    /**
+     * Whether the node runs only the official images: `agent_image` from
+     * {@link OFFICIAL_IMAGES.agent} and `cs2_image` from {@link OFFICIAL_IMAGES.cs2}, with any tag or
+     * digest. While it is on, the agent refuses an {@link ControllerUpdateAgent | update_agent} or
+     * {@link ControllerUpdateCs2Image | update_cs2_image} to any other image with
+     * `image_not_allowed`, and `node-setup.sh` refuses to run one.
+     *
+     * Only the node's operator can turn it off, by setting it to false in the file, to run images of
+     * their own. {@link ControllerSetConfig | set_config} cannot change it. If the `agent.yml` that
+     * `node-setup.sh` fetches from the controller turns it off, the script stops.
+     */
+    official_images_only: z.boolean().default(true),
+    /**
+     * 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.
+     */
+    slots: z.array(ConfiguredSlot).max(MAX_SLOTS),
+    /**
+     * Where finished demos are uploaded. Without it, demos stay on the node.
+     * [Demo uploads](https://docs.ankor.sh/protocol/demos/) describes the request.
+     */
+    demo_upload: DemoUploadFields.optional(),
+});
+/**
+ * The node's `agent.yml` as the agent reads it. It is {@link RawAgentConfigSchema} with the checks
+ * that span slots, and it fills in `pinned_ip` and `demo_upload` as null when absent.
+ *
+ * Rejected 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
+ * {@link EVENT_RELAY_PORT}, where the agent listens for plugins.
+ */
+export const AgentConfigSchema = RawAgentConfigSchema.superRefine((config, ctx) => {
+    // Add list-wide issues not already covered by individual slot schemas.
+    addSlotLayoutIssues(ctx, config.slots, AGENT_MIN_SLOT_PORT, ['slots']);
+    addGsltIssues(ctx, config.slots, ['slots']);
+}).transform((config) => ({
+    ...config,
+    pinned_ip: config.pinned_ip ?? null,
+    demo_upload: config.demo_upload === undefined
+        ? null
+        : { url: config.demo_upload.url, header: config.demo_upload.header ?? null, limit_mbit: config.demo_upload.limit_mbit ?? null },
+}));
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/** Keys the file carries that this agent does not read, as dotted paths. Parsing ignores them. */
+export function unsupportedAgentYmlKeys(raw) {
+    const unknown = (value, known, prefix) => isRecord(value)
+        ? Object.keys(value).filter((key) => !(key in known)).map((key) => `${prefix}${key}`)
+        : [];
+    if (!isRecord(raw)) {
+        return [];
+    }
+    const keys = unknown(raw, RawAgentConfigSchema.shape, '');
+    if (Array.isArray(raw['slots'])) {
+        raw['slots'].forEach((slot, index) => keys.push(...unknown(slot, ConfiguredSlot.shape, `slots.${index}.`)));
+    }
+    keys.push(...unknown(raw['controller'], ControllerFields.shape, 'controller.'));
+    const upload = raw['demo_upload'];
+    keys.push(...unknown(upload, DemoUploadFields.shape, 'demo_upload.'));
+    if (isRecord(upload)) {
+        keys.push(...unknown(upload['header'], DemoUploadHeader.shape, 'demo_upload.header.'));
+    }
+    return keys;
+}

package/dist/agent-image.d.ts

@@ -0,0 +1,12 @@
+export declare const SELF_UPDATE_COMMAND: readonly ["ankor-self-update"];
+export declare const SELF_UPDATE_ENV: {
+    /** The Docker create payload for the replacement container as JSON, including its name. */
+    readonly spec: "ANKOR_SELF_UPDATE_SPEC";
+    /** The id of the container being replaced. */
+    readonly previousId: "ANKOR_SELF_UPDATE_PREVIOUS";
+    /**
+     * Where the helper records a swap that failed, for the agent that comes up after it. A swap that
+     * succeeds removes the record.
+     */
+    readonly failure: "ANKOR_SELF_UPDATE_FAILURE";
+};

package/dist/agent-image.js

@@ -0,0 +1,12 @@
+export const SELF_UPDATE_COMMAND = ['ankor-self-update'];
+export const SELF_UPDATE_ENV = {
+    /** The Docker create payload for the replacement container as JSON, including its name. */
+    spec: 'ANKOR_SELF_UPDATE_SPEC',
+    /** The id of the container being replaced. */
+    previousId: 'ANKOR_SELF_UPDATE_PREVIOUS',
+    /**
+     * Where the helper records a swap that failed, for the agent that comes up after it. A swap that
+     * succeeds removes the record.
+     */
+    failure: 'ANKOR_SELF_UPDATE_FAILURE',
+};