@ankorcs/protocol 0.0.0-stage → 0.6.1

package/dist/plugin-socket.js

@@ -0,0 +1,160 @@
+/**
+ * The messages of the agent's local plugin socket: sequenced events and status from the plugin, and
+ * commands and acknowledgements from the agent.
+ */
+import { z } from 'zod';
+import { AGENT_ERRORS, AgentBackup, AgentPhaseChange, AgentScore, ServerState, } from './index.js';
+import { EventBatchFrame, EventSeq, RoundNumber } from './index.js';
+/**
+ * One sequenced event, which the plugin sends and the agent spools without its `type`, then uploads
+ * as an {@link EventBatchFrame} of an {@link EventBatch | event_batch}. `seq` runs from 0 without gaps.
+ * The frame names no server, because the connection's key already proves which one it is.
+ *
+ * A frame carries at most {@link MAX_FRAME_BYTES}, which is no more than
+ * {@link EVENT_BATCH_MAX_BYTES}, so every event the agent accepts fits an upload batch once stored.
+ * The plugin drops a larger event before sending it, and the agent ends a socket that sends one.
+ *
+ * After a gap past the events it stored, or with more than {@link RELAY_QUEUE_MAX_FRAMES} events or
+ * {@link RELAY_QUEUE_MAX_BYTES} of them waiting to be stored, the agent accepts no more history and
+ * ends the socket with code `1000` once the rest is stored. The plugin reconnects and resends from its last
+ * {@link EventAck | ack}.
+ */
+export const PluginEventFrame = EventBatchFrame.extend({
+    type: z.literal('event'),
+});
+/**
+ * Acknowledges that every frame with `seq <= to_seq` is stored on the node, so the plugin may
+ * discard them.
+ *
+ * The agent sends it as frames are stored, and on every connect once the server has events on the
+ * node, so a reconnecting plugin resends only what follows. An `ack` past the last frame the plugin
+ * sent breaks the stream, and the plugin drops the connection.
+ */
+export const EventAck = z.object({
+    type: z.literal('ack'),
+    to_seq: EventSeq,
+});
+/**
+ * A game server's state, which the plugin sends in answer to every
+ * {@link PluginGetServerStatus | get_server_status}. The plugin also sends it unasked once when it
+ * connects and once when it turns `ready`.
+ */
+export const ServerStatus = ServerState.extend({
+    type: z.literal('server_status'),
+    /**
+     * The `request_id` of the {@link PluginGetServerStatus | get_server_status} this answers. Null
+     * when the request had none or the status was sent unasked.
+     */
+    request_id: z.string().max(64).nullable(),
+});
+/**
+ * Tells the agent that the plugin is about to run `quit` after its match, with every event
+ * acknowledged and the demo finished. The agent stops a server that is still running
+ * {@link QUIT_TIMEOUT_SECONDS} later. Like {@link ServerStatus | server_status}, it is not resent,
+ * so one sent without a connection is lost.
+ */
+export const Quitting = z.object({
+    type: z.literal('quitting'),
+});
+/**
+ * The match moved to another phase, which the plugin sends whether or not the match sends
+ * statistics, and the agent forwards as {@link AgentPhaseChange | phase_change}. Like
+ * {@link ServerStatus | server_status}, it is sent once and lost without a connection.
+ */
+export const PluginPhaseChange = AgentPhaseChange.omit({ allocation_id: true });
+/**
+ * The match's score changed, which the plugin sends like {@link PluginPhaseChange | phase_change},
+ * and the agent forwards as {@link AgentScore | score}.
+ */
+export const PluginScore = AgentScore.omit({ allocation_id: true });
+/**
+ * The `round_backup` of a match that sends no statistics, which the plugin
+ * sends like {@link PluginPhaseChange | phase_change}, and the agent forwards as
+ * {@link AgentBackup | backup}. `backup` holds the complete event, unchanged, as the
+ * event stream would carry it.
+ */
+export const PluginBackup = AgentBackup.omit({ allocation_id: true });
+/** Why a plugin did not carry out a command, as an {@link AgentErrorCode}. */
+export const CommandRefusal = z.enum([
+    AGENT_ERRORS.noMatch, AGENT_ERRORS.notInWarmup, AGENT_ERRORS.teamEmpty,
+    AGENT_ERRORS.noBackup, AGENT_ERRORS.notLive, AGENT_ERRORS.atHalftime,
+    AGENT_ERRORS.unsupportedRequest,
+]);
+/** The plugin's answer to a command that carries a `request_id`. */
+export const CommandResult = z.object({
+    type: z.literal('command_result'),
+    /** The `request_id` of the command this answers. */
+    request_id: z.string().max(64),
+    /** Why the plugin refused the command. Null when the plugin carried it out. */
+    error: CommandRefusal.nullable(),
+});
+/**
+ * What a plugin sends its agent: sequenced {@link PluginEventFrame | event} frames, its
+ * {@link ServerStatus | server_status}, {@link PluginPhaseChange | phase_change},
+ * {@link PluginScore | score}, {@link PluginBackup | backup},
+ * {@link CommandResult | command_result} and {@link Quitting | quitting}.
+ */
+export const PluginToAgentMessage = z.discriminatedUnion('type', [PluginEventFrame, ServerStatus, PluginPhaseChange, PluginScore, PluginBackup, CommandResult, Quitting]);
+/**
+ * Asks the plugin for its server's state, which the plugin answers with a
+ * {@link ServerStatus | server_status}.
+ */
+export const PluginGetServerStatus = z.object({
+    type: z.literal('get_server_status'),
+    /**
+     * An id that the answering {@link ServerStatus | server_status} carries back, to match it to this
+     * request. Null for none.
+     */
+    request_id: z.string().max(64).nullable(),
+});
+/**
+ * Runs a server console command. The plugin answers with a {@link CommandResult | command_result}
+ * once it has handed the command to the engine.
+ */
+export const ExecCommand = z.object({
+    type: z.literal('exec'),
+    /** The console command line. */
+    command: z.string(),
+    /** An id that the answering {@link CommandResult | command_result} carries back. */
+    request_id: z.string().max(64),
+});
+/**
+ * Loads the server's backup of a round, as {@link ControllerRestoreRound | restore_round} from the controller
+ * asks. The plugin runs `mp_backup_restore_load_file` on the file the engine wrote for it
+ * and answers with a {@link CommandResult | command_result}.
+ */
+export const PluginRestoreRound = z.object({
+    type: z.literal('restore_round'),
+    /** The round to play on from, one-based. */
+    round: RoundNumber,
+    /** An id that the answering {@link CommandResult | command_result} carries back. */
+    request_id: z.string().max(64),
+});
+/**
+ * Starts a match in warmup whatever its `ready_mode`, as {@link ControllerStartMatch | start_match} from
+ * the controller asks. The plugin answers with a {@link CommandResult | command_result}.
+ */
+export const PluginStartMatch = z.object({
+    type: z.literal('start_match'),
+    /** An id that the answering {@link CommandResult | command_result} carries back. */
+    request_id: z.string().max(64),
+});
+/**
+ * What the agent asks of a game server.
+ *
+ * - `exec`: relays {@link ControllerConsoleCommand | console_command} from the controller.
+ * - `restore_round`: relays {@link ControllerRestoreRound | restore_round} from the controller.
+ * - `start_match`: relays {@link ControllerStartMatch | start_match} from the controller.
+ * - `get_server_status`: the agent's own request.
+ */
+export const PluginCommand = z.discriminatedUnion('type', [ExecCommand, PluginRestoreRound, PluginStartMatch, PluginGetServerStatus]);
+/**
+ * What the agent sends a plugin: commands, and an {@link EventAck | ack} once events are stored on
+ * the node.
+ *
+ * When the agent ends a plugin's socket, it sends a close frame whose reason says why: `1001` when
+ * the agent shuts down, and `1000` when the plugin must replay its history, when a newer connection
+ * of the same server takes its place, or when the server's launch has ended. The plugin reconnects
+ * after each and resends from its last {@link EventAck | ack}.
+ */
+export const AgentToPluginMessage = z.discriminatedUnion('type', [...PluginCommand.options, EventAck]);

package/dist/session.d.ts

@@ -0,0 +1,127 @@
+/**
+ * One connected agent, from the controller's side of the agent socket. The controller hands the
+ * session each frame that arrives and a function that writes one, so any WebSocket server works.
+ */
+import type { z } from 'zod';
+import { AgentToControllerMessage, ControllerToAgentMessage, type AgentError, type ReplyData, type RequestType } from './index.js';
+/** Milliseconds a request waits for its reply unless the session or the call sets another wait. */
+export declare const DEFAULT_REQUEST_TIMEOUT_MS = 30000;
+/**
+ * How long `request` waits for its reply, when other requests wait `wait`. A
+ * {@link ControllerStopServer | stop_server} replies once its container stopped, so it waits
+ * {@link STOP_TIMEOUT_SECONDS} and {@link STOP_REPLY_MARGIN_SECONDS}, whatever `wait` is. Null waits until
+ * the socket closes. A controller that relays requests through something with its own deadline
+ * gives that deadline this wait too.
+ */
+export declare function replyWait(request: {
+    type: string;
+}, wait: number): number;
+export declare function replyWait(request: {
+    type: string;
+}, wait: number | null): number | null;
+/**
+ * A request as the controller builds it: its `type` and fields, without the `id` that the session
+ * picks. Fields with a default may be left out, since the session sends what the schema accepts.
+ */
+export type SessionRequest<T extends RequestType = RequestType> = Extract<z.input<typeof ControllerToAgentMessage>, {
+    type: T;
+}> extends infer M ? M extends unknown ? Omit<M, 'id'> : never : never;
+/**
+ * A frame the controller sends that gets no reply: {@link ControllerWelcome | welcome},
+ * {@link ControllerHelloRefused | hello_refused}, the watches {@link ControllerWatchResources | watch_resources}
+ * and {@link ControllerWatchLogs | watch_logs}, and {@link ControllerCheckCs2Build | check_cs2_build}.
+ */
+export type ControllerNotice = Exclude<ControllerToAgentMessage, {
+    id: string;
+}>;
+/** A frame the agent sends that is not a reply. */
+export type AgentReport = Exclude<AgentToControllerMessage, {
+    type: 'reply';
+}>;
+/** A {@link AgentReply | reply} that the agent sent. */
+export type AgentReplyMessage = Extract<AgentToControllerMessage, {
+    type: 'reply';
+}>;
+/** One way a frame failed the contract, as zod reports it. */
+export type ContractIssue = NonNullable<ReturnType<typeof AgentToControllerMessage.safeParse>['error']>['issues'][number];
+/**
+ * How a request came out.
+ *
+ * - `ok`: the agent replied that the request succeeded.
+ * - `error`: the agent replied that it refused or failed the request.
+ * - `timeout`: no reply came before the request's wait ran out.
+ * - `closed`: the socket closed before a reply came.
+ *
+ * After `timeout` or `closed`, the agent may still have done the work, and its reports say whether
+ * it did.
+ */
+export type RequestResult<T extends RequestType> = {
+    status: 'ok';
+    data: ReplyData<T>;
+} | {
+    status: 'error';
+    error: AgentError;
+} | {
+    status: 'timeout';
+} | {
+    status: 'closed';
+};
+/**
+ * What one received frame was.
+ *
+ * - `report`: an {@link AgentReport}.
+ * - `reply`: a reply, which the frame carries. `answered` is `true` when the reply settled the
+ *   request it answers, and `false` when it answered no open request, as one past its timeout does.
+ * - `unsupported`: a message whose `type` this version does not have, from a newer agent. Skip it.
+ * - `invalid`: any other frame that failed the contract, one of a known type included. `issues`
+ *   lists how, and is empty for a frame that is not JSON. `detail` joins the issues for a log line.
+ */
+export type ReceivedFrame = {
+    kind: 'report';
+    message: AgentReport;
+} | {
+    kind: 'reply';
+    answered: boolean;
+    message: AgentReplyMessage;
+} | {
+    kind: 'unsupported';
+    type: string;
+} | {
+    kind: 'invalid';
+    detail: string;
+    issues: ContractIssue[];
+};
+export interface AgentSessionOptions {
+    /** Writes one text frame to this agent's socket. */
+    send: (text: string) => void;
+    /**
+     * Milliseconds a request waits for its reply. Null waits until the socket closes. A
+     * {@link ControllerStopServer | stop_server} waits as long as its stop takes instead: see
+     * {@link replyWait}.
+     */
+    timeoutMs?: number | null;
+}
+export interface RequestOptions {
+    /** Milliseconds this request waits for its reply, in place of the session's wait; not for a stop, which waits by its grace. */
+    timeoutMs?: number | null;
+}
+export interface AgentSession {
+    /**
+     * Sends a request under an id that the session picks, and resolves with its reply, a timeout or
+     * the socket's close. After the agent's {@link AgentShutdown | shutdown}, it sends nothing and
+     * resolves with the `shutting_down` error the agent would answer.
+     */
+    request<R extends SessionRequest>(request: R, options?: RequestOptions): Promise<RequestResult<R['type']>>;
+    /** Sends a frame that gets no reply. */
+    notify(message: ControllerNotice): void;
+    /** Reads one frame the agent sent, as it arrived on the socket. */
+    receive(raw: string | ArrayBuffer | Uint8Array): ReceivedFrame;
+    /** Reads one frame the agent sent that the controller has already parsed from JSON. */
+    receiveParsed(json: unknown): ReceivedFrame;
+    /**
+     * Tells the session that the socket closed. Every open request ends `closed`, and later ones end
+     * `closed` immediately.
+     */
+    closed(): void;
+}
+export declare function createAgentSession(options: AgentSessionOptions): AgentSession;

package/dist/session.js

@@ -0,0 +1,114 @@
+import { AGENT_ERRORS, AgentToControllerMessage, STOP_REPLY_MARGIN_SECONDS, STOP_TIMEOUT_SECONDS, ControllerToAgentMessage, } from './index.js';
+import { unknownMessageType } from './helpers.js';
+/** Milliseconds a request waits for its reply unless the session or the call sets another wait. */
+export const DEFAULT_REQUEST_TIMEOUT_MS = 30_000;
+export function replyWait(request, wait) {
+    if (request.type !== 'stop_server') {
+        return wait;
+    }
+    return (STOP_TIMEOUT_SECONDS + STOP_REPLY_MARGIN_SECONDS) * 1000;
+}
+const decoder = new TextDecoder();
+function invalid(issues) {
+    return { kind: 'invalid', detail: issues.map((issue) => `${issue.path.join('.')}: ${issue.message}`).join('; '), issues };
+}
+export function createAgentSession(options) {
+    const pending = new Map();
+    const sessionTimeout = options.timeoutMs === undefined ? DEFAULT_REQUEST_TIMEOUT_MS : options.timeoutMs;
+    let isClosed = false;
+    // After the agent's shutdown, it refuses every new request, so the session answers for it.
+    let isStopping = false;
+    function take(id) {
+        const open = pending.get(id);
+        if (open !== undefined) {
+            pending.delete(id);
+            clearTimeout(open.timer);
+        }
+        return open;
+    }
+    /** The call's wait, else the session's; a stop's by its grace period as parsed with its default. */
+    function waitFor(message, requestOptions) {
+        return replyWait(message, requestOptions.timeoutMs !== undefined ? requestOptions.timeoutMs : sessionTimeout);
+    }
+    function receiveParsed(json) {
+        const unknownType = unknownMessageType(AgentToControllerMessage, json);
+        if (unknownType !== null) {
+            return { kind: 'unsupported', type: unknownType };
+        }
+        const parsed = AgentToControllerMessage.safeParse(json);
+        if (!parsed.success) {
+            return invalid(parsed.error.issues);
+        }
+        const message = parsed.data;
+        if (message.type !== 'reply') {
+            if (message.type === 'shutdown') {
+                isStopping = true;
+            }
+            return { kind: 'report', message };
+        }
+        const open = pending.get(message.reply_to);
+        if (open === undefined) {
+            return { kind: 'reply', answered: false, message };
+        }
+        if (message.request !== null && message.request !== open.type) {
+            return invalid([{
+                    code: 'custom',
+                    path: ['request'],
+                    message: `the reply to ${open.type} ${message.reply_to} names ${message.request}`,
+                    input: message.request,
+                }]);
+        }
+        take(message.reply_to);
+        open.settle(message.ok ? { status: 'ok', data: message.data } : { status: 'error', error: message.error });
+        return { kind: 'reply', answered: true, message };
+    }
+    return {
+        request(request, requestOptions = {}) {
+            if (isClosed) {
+                return Promise.resolve({ status: 'closed' });
+            }
+            if (isStopping) {
+                return Promise.resolve({ status: 'error', error: { code: AGENT_ERRORS.shuttingDown, detail: 'the agent is shutting down' } });
+            }
+            const id = crypto.randomUUID();
+            // A throw in here, from the contract or the socket, rejects the promise.
+            return new Promise((resolve) => {
+                const message = ControllerToAgentMessage.parse({ ...request, id });
+                const timeoutMs = waitFor(message, requestOptions);
+                const timer = timeoutMs === null ? undefined : setTimeout(() => {
+                    take(id);
+                    resolve({ status: 'timeout' });
+                }, timeoutMs);
+                // The reply's `request` was checked against this type before it settles the promise.
+                pending.set(id, { type: request.type, settle: resolve, timer });
+                try {
+                    options.send(JSON.stringify(message));
+                }
+                catch (error) {
+                    take(id);
+                    throw error;
+                }
+            });
+        },
+        notify(message) {
+            options.send(JSON.stringify(ControllerToAgentMessage.parse(message)));
+        },
+        receive(raw) {
+            let json;
+            try {
+                json = JSON.parse(typeof raw === 'string' ? raw : decoder.decode(raw));
+            }
+            catch {
+                return { kind: 'invalid', detail: 'not JSON', issues: [] };
+            }
+            return receiveParsed(json);
+        },
+        receiveParsed,
+        closed() {
+            isClosed = true;
+            for (const id of [...pending.keys()]) {
+                take(id)?.settle({ status: 'closed' });
+            }
+        },
+    };
+}

package/dist/values.d.ts

@@ -0,0 +1,186 @@
+/** Value types that more than one wire and `agent.yml` share. */
+import { z } from 'zod';
+/** The loopback port the agent listens on for plugins. No slot may use it. */
+export declare const EVENT_RELAY_PORT = 4500;
+/** The highest port a slot may use, for its game port and its GOTV port. */
+export declare const MAX_PORT = 65535;
+/**
+ * The lowest port `agent.yml` permits for a slot. A configuration front end may require a higher
+ * one.
+ */
+export declare const AGENT_MIN_SLOT_PORT = 1;
+/** A slot id: 1 to 32 letters, digits, `_` or `-`. It becomes part of the game container's name. */
+export declare const SLOT_ID_PATTERN: RegExp;
+/** A slot's two ports, before the controller has given it an id. */
+export type SlotPorts = Omit<ServerSlot, 'id'>;
+/**
+ * The shape of a node token. It has letters and digits only, so that it reads the same in a
+ * header, a YAML file and a shell.
+ */
+export declare const NODE_TOKEN_PATTERN: RegExp;
+/** What a node presents as `Authorization: Bearer <token>` on every request. */
+export declare const NodeToken: z.ZodString;
+/**
+ * The id the controller picks for each server it launches. It identifies that server and its
+ * events from then on.
+ *
+ * The id is a lowercase UUID, new for every launch. UUIDv7 is recommended, because its time-ordered
+ * values keep a database index on it compact as events arrive.
+ */
+export declare const AllocationId: z.ZodUUID;
+/** A slot's id, which is also part of the names of its containers. */
+export declare const SlotId: z.ZodString;
+/** A TCP or UDP port. */
+export declare const Port: z.ZodNumber;
+/** A slot's id and ports. */
+export declare const ServerSlot: z.ZodObject<{
+    id: z.ZodString;
+    port: z.ZodNumber;
+    tv_port: z.ZodNumber;
+}, z.core.$strip>;
+export type ServerSlot = z.infer<typeof ServerSlot>;
+/** The shape of a Game Server Login Token as Steam issues them. */
+export declare const GSLT_PATTERN: RegExp;
+/** A Game Server Login Token, which the servers of a slot log in to Steam with. */
+export declare const Gslt: z.ZodString;
+/**
+ * The last ten characters of a token, which the agent reports instead of the token. They are enough
+ * to tell apart every token on one Steam account.
+ */
+export declare const GsltHint: z.ZodString;
+/**
+ * Whether Steam accepts a slot's token.
+ *
+ * - `ok`: a logon with the token succeeded, either the agent's own or that of a server that
+ *   turned `ready`.
+ * - `invalid`: Steam refused the token.
+ * - `unchecked`: the agent has seen neither since the token was set.
+ */
+export declare const GsltState: z.ZodEnum<{
+    ok: "ok";
+    invalid: "invalid";
+    unchecked: "unchecked";
+}>;
+export type GsltState = z.infer<typeof GsltState>;
+/** A slot as `agent.yml` holds it, with its full token. */
+export declare const ConfiguredSlot: z.ZodObject<{
+    id: z.ZodString;
+    port: z.ZodNumber;
+    tv_port: z.ZodNumber;
+    gslt: z.ZodString;
+}, z.core.$strip>;
+export type ConfiguredSlot = z.infer<typeof ConfiguredSlot>;
+/**
+ * A slot as the agent reports it, with the last ten characters of its token in place of the token.
+ */
+export declare const ReportedSlot: z.ZodObject<{
+    id: z.ZodString;
+    port: z.ZodNumber;
+    tv_port: z.ZodNumber;
+    gslt_hint: z.ZodString;
+}, z.core.$strip>;
+export type ReportedSlot = z.infer<typeof ReportedSlot>;
+/** A Docker image reference, as `cs2_image` and `agent_image` in `agent.yml` hold it. */
+export declare const ImageReference: z.ZodString;
+/**
+ * MiB of memory each game container may use. CS2 installs and updates are exempt.
+ *
+ * Rejected when it is not a whole number from {@link MIN_MEMORY_MB} to {@link MAX_MEMORY_MB}.
+ */
+export declare const MemoryLimit: z.ZodNumber;
+/**
+ * The repository of each official image. With `official_images_only` on, a node runs an image only
+ * from its kind's repository, with any tag or digest, such as `ghcr.io/ankorcs/ankor-agent:0.8`.
+ */
+export declare const OFFICIAL_IMAGES: {
+    readonly agent: "ghcr.io/ankorcs/ankor-agent";
+    readonly cs2: "ghcr.io/ankorcs/ankor-cs2";
+};
+/**
+ * A dotted IPv4 address. Rejected unless it is four numbers from 0 to 255 joined by dots, each
+ * without leading zeros.
+ */
+export declare const Ipv4: z.ZodString;
+/**
+ * A host with an optional port and no scheme or path, such as `cs.example.com`,
+ * `192.168.0.10:3000` or `[fd00::1]`.
+ *
+ * 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.
+ */
+export declare const ControllerHost: z.ZodString;
+/**
+ * A path on the controller's host. It starts with `/`, followed by URL path characters and percent
+ * escapes, without a query or fragment.
+ */
+export declare const ControllerPath: z.ZodString;
+/**
+ * The URL finished demos are posted to. A target that needs credentials takes them in the configured
+ * `header`, such as `Authorization: Basic …`, which the node reports only as a hash.
+ *
+ * Rejected when the URL carries a user name or a password.
+ */
+export declare const DemoUploadUrl: z.ZodURL;
+/**
+ * Header names, in lower case, that a demo upload's configured header cannot take: the ones the
+ * agent sets itself on every upload, and the ones that change how the request is framed.
+ */
+export declare const RESERVED_DEMO_HEADERS: readonly ["host", "content-type", "content-length", "transfer-encoding", "connection", "keep-alive", "upgrade", "expect", "te", "trailer", string, ...string[]];
+/**
+ * One header sent with every demo upload, verbatim: any name the target expects, such as an API key
+ * header or `Authorization: Basic …`, except the {@link RESERVED_DEMO_HEADERS}.
+ */
+export declare const DemoUploadHeader: z.ZodObject<{
+    name: z.ZodString;
+    value: z.ZodString;
+}, z.core.$strip>;
+/** Whole megabits a second, from 1 to 10 Gbit/s. */
+export declare const DemoUploadLimit: z.ZodNumber;
+/** Where finished demos go. The header, when set, is sent verbatim and is the only credential. */
+export declare const DemoUpload: z.ZodObject<{
+    url: z.ZodURL;
+    header: z.ZodNullable<z.ZodObject<{
+        name: z.ZodString;
+        value: z.ZodString;
+    }, z.core.$strip>>;
+    limit_mbit: z.ZodNullable<z.ZodNumber>;
+}, z.core.$strip>;
+export type DemoUpload = z.infer<typeof DemoUpload>;
+/**
+ * A demo upload as the node reports it, with the header's value replaced by its hash, because the
+ * value is a credential that the controller set.
+ */
+export declare const ReportedDemoUpload: z.ZodObject<{
+    url: z.ZodURL;
+    limit_mbit: z.ZodNullable<z.ZodNumber>;
+    header: z.ZodNullable<z.ZodObject<{
+        name: z.ZodString;
+        value_sha256: z.ZodString;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type ReportedDemoUpload = z.infer<typeof ReportedDemoUpload>;
+/**
+ * A demo upload as {@link ControllerSetConfig | set_config} sets it. A header without its value keeps the
+ * value the node has.
+ */
+export declare const DemoUploadEdit: z.ZodObject<{
+    url: z.ZodURL;
+    limit_mbit: z.ZodNullable<z.ZodNumber>;
+    header: z.ZodNullable<z.ZodObject<{
+        name: z.ZodString;
+        value: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type DemoUploadEdit = z.infer<typeof DemoUploadEdit>;
+/**
+ * Where a node dials the controller: a host with an optional port, whether it encrypts, and the
+ * paths it reaches there.
+ */
+export declare const ControllerAddress: z.ZodObject<{
+    host: z.ZodString;
+    tls: z.ZodBoolean;
+    socket_path: z.ZodString;
+    events_path: z.ZodString;
+}, z.core.$strip>;
+export type ControllerAddress = z.infer<typeof ControllerAddress>;