@x-tech-laboratories/x-libs 0.14.1 → 0.14.2

package/dist/server/agents/hub.js

@@ -0,0 +1,241 @@
+// The agents the server can reach, by host name: those that have dialled in with their host's declared key or a token
+// the app issued, and the one built into the server for its own machine. A host with a declared key logs in only with
+// that key, so a leaked token cannot stand in for it.
+// ── Imports ──────────────────────────────────────────────────────────────────
+import { randomBytes } from "node:crypto";
+import { EventEmitter } from "node:events";
+import { parse_public_key, verify_challenge } from "../../agent/keys.js";
+import { encode_message, is_agent_message, key_host_header, parse_agent_message, } from "../../agent/protocol.js";
+import { AgentError, ended_stream } from "./agent.js";
+import { AgentConnection } from "./connection.js";
+// Close codes the hub hangs up with.
+export const close_codes = {
+    protocol: 4002,
+    replaced: 4003,
+    revoked: 4004,
+    no_hello: 4005,
+    bad_key: 4006,
+};
+const default_connection = {
+    window_in_bytes: 1024 * 1024,
+    request_timeout_in_milliseconds: 60_000,
+    heartbeat_in_milliseconds: 15_000,
+};
+// ── Hub ──────────────────────────────────────────────────────────────────────
+export class AgentHub extends EventEmitter {
+    app;
+    local;
+    tokens;
+    on_message;
+    hello_timeout;
+    connection_options;
+    connections = new Map();
+    logins = new WeakMap();
+    // Each host's declared public key, with the line it was read from.
+    agent_keys = new Map();
+    constructor(options) {
+        super();
+        this.app = options.app;
+        this.local = options.local === undefined ? null : { ...options.local };
+        this.tokens = options.tokens ?? null;
+        this.on_message = options.on_message ?? null;
+        this.hello_timeout = options.hello_timeout_in_milliseconds ?? 10_000;
+        this.connection_options = { ...default_connection, ...options.connection };
+    }
+    // The host the built-in agent answers for, which follows the config as it names this server's own host.
+    set_local_host(host) {
+        if (this.local !== null)
+            this.local.host = host;
+    }
+    // ── Enrolment ────────────────────────────────────────────────────────────
+    // Takes each host's declared OpenSSH public key line, and hangs up on an agent whose host's key is new, changed or
+    // gone, so it logs in again the way the config now asks.
+    set_agent_keys(lines) {
+        const next = new Map([...lines].map(([host, line]) => [host, { line, key: parse_public_key(line) }]));
+        for (const host of new Set([...this.agent_keys.keys(), ...next.keys()])) {
+            if (this.agent_keys.get(host)?.line === next.get(host)?.line)
+                continue;
+            this.disconnect(host, close_codes.revoked, "The host's declared agent key changed.");
+        }
+        this.agent_keys = next;
+    }
+    has_agent_key(host) {
+        return this.agent_keys.has(host);
+    }
+    // The hosts with a declared key, in order.
+    declared_hosts() {
+        return [...this.agent_keys.keys()].sort();
+    }
+    // Hangs up on a host's agent that logged in with a token, as when the app replaces or revokes that token.
+    disconnect_token_login(host, reason) {
+        const connection = this.connections.get(host);
+        if (connection !== undefined && this.logins.get(connection) === "token")
+            connection.close(close_codes.revoked, reason);
+    }
+    // The host an Authorization header's bearer token belongs to.
+    authenticate(authorization) {
+        const match = /^Bearer\s+(\S+)$/.exec(authorization ?? "");
+        return match === null || this.tokens === null ? null : this.tokens.host_for(match[1]);
+    }
+    // Who an agent's upgrade request says it is: the host it names to log in with that host's key, or a token's host.
+    admit(headers) {
+        const header = key_host_header(this.app.name);
+        const named = headers[header];
+        if (typeof named === "string" && named !== "") {
+            if (named === this.local?.host)
+                return { error: `'${named}' is the server's own host, which needs no agent.` };
+            if (!this.agent_keys.has(named))
+                return { error: `Host '${named}' has no declared agent key.` };
+            return { host: named, login: "key" };
+        }
+        if (this.tokens === null)
+            return { error: `Name the host in the ${header} header.` };
+        const host = this.authenticate(headers.authorization);
+        if (host === null)
+            return { error: "This agent token is not enrolled." };
+        if (this.agent_keys.has(host))
+            return { error: `Host '${host}' has a declared agent key, so it logs in with that key, not a token.` };
+        return { host, login: "token" };
+    }
+    // ── Connections ──────────────────────────────────────────────────────────
+    // Takes a socket whose upgrade named the host, and waits for its hello before using it; one logging in with its key
+    // is sent a nonce first, which its hello must carry signed.
+    accept(socket, host, login) {
+        let connection = null;
+        const hello_timer = setTimeout(() => socket.close(close_codes.no_hello, "No hello came."), this.hello_timeout);
+        const nonce = login === "key" ? randomBytes(32).toString("base64url") : null;
+        if (nonce !== null)
+            socket.send(encode_message({ type: "challenge", nonce }, this.app));
+        socket.on("message", (raw, is_binary) => {
+            const data = as_buffer(raw);
+            if (connection !== null) {
+                connection.receive(data, is_binary);
+                return;
+            }
+            const hello = is_binary ? null : parse_agent_message(data.toString("utf8"), this.app);
+            if (hello === null || !is_agent_message(hello) || hello.type !== "hello")
+                return;
+            clearTimeout(hello_timer);
+            if (hello.protocol !== this.app.protocol_version) {
+                socket.close(close_codes.protocol, `This server speaks agent protocol ${this.app.protocol_version}, not ${hello.protocol}.`);
+                return;
+            }
+            const { signature, ...greeting } = hello;
+            if (nonce !== null && !this.proves_key(host, nonce, signature)) {
+                socket.close(close_codes.bad_key, `The agent's key is not the one declared for ${host}.`);
+                return;
+            }
+            this.connections.get(host)?.close(close_codes.replaced, "A newer connection from the same host replaced this one.");
+            const current = new AgentConnection(socket, this.app, host, greeting, this.connection_options);
+            current.on_message = (message) => this.on_message?.(host, message, current);
+            connection = current;
+            this.connections.set(host, current);
+            this.logins.set(current, login);
+            this.emit("connect", this.status_of(current));
+        });
+        socket.on("error", () => { });
+        socket.on("close", () => {
+            clearTimeout(hello_timer);
+            if (connection === null)
+                return;
+            connection.closed(`The agent on ${host} disconnected.`);
+            if (this.logins.get(connection) === "token")
+                this.tokens?.seen?.(host);
+            if (this.connections.get(host) !== connection)
+                return;
+            this.connections.delete(host);
+            this.emit("disconnect", host);
+        });
+    }
+    proves_key(host, nonce, signature) {
+        const declared = this.agent_keys.get(host);
+        return declared !== undefined && typeof signature === "string" && verify_challenge(declared.key, this.app.name, host, nonce, signature);
+    }
+    disconnect(host, code = 1000, reason = "The server hung up.") {
+        this.connections.get(host)?.close(code, reason);
+    }
+    close() {
+        for (const host of this.connections.keys())
+            this.disconnect(host, 1001, "The server is stopping.");
+    }
+    is_connected(host) {
+        return this.local?.host === host || this.connections.get(host)?.is_open === true;
+    }
+    status(host) {
+        if (this.local?.host === host)
+            return local_status(host);
+        const connection = this.connections.get(host);
+        return connection?.is_open ? this.status_of(connection) : null;
+    }
+    // The built-in agent, then every connected one.
+    statuses() {
+        const remote = [...this.connections.values()].filter((connection) => connection.is_open).map((connection) => this.status_of(connection));
+        return this.local === null ? remote : [local_status(this.local.host), ...remote];
+    }
+    // The host's agent, or null when it is not connected.
+    agent(host) {
+        if (this.local?.host === host)
+            return this.local.agent;
+        const connection = this.connections.get(host);
+        return connection?.is_open ? connection : null;
+    }
+    // ── Commands ─────────────────────────────────────────────────────────────
+    // A run on a host with no agent answers with exit code -1 rather than rejecting, as a command that failed does.
+    run(host, task, options) {
+        const agent = this.agent(host);
+        return agent === null ? Promise.resolve({ exit_code: -1, stdout: "", stderr: not_connected(host) }) : agent.run(task, options);
+    }
+    stream(host, task, options = {}) {
+        return this.agent(host)?.stream(task, options) ?? ended_stream(not_connected(host));
+    }
+    start(host, run_id, task, options = {}) {
+        return this.require(host).then((agent) => agent.start(run_id, task, options));
+    }
+    poll(host, run_id, offset) {
+        return this.require(host).then((agent) => agent.poll(run_id, offset));
+    }
+    attach(host, run_id, offset) {
+        return this.agent(host)?.attach(run_id, offset) ?? ended_stream(not_connected(host));
+    }
+    stop(host, run_id) {
+        return this.require(host).then((agent) => agent.stop(run_id));
+    }
+    forget(host, run_id) {
+        return this.require(host).then((agent) => agent.forget(run_id));
+    }
+    runs(host) {
+        return this.require(host).then((agent) => agent.runs());
+    }
+    request(host, type, body = {}) {
+        return this.require(host).then((agent) => agent.request(type, body));
+    }
+    async require(host) {
+        const agent = this.agent(host);
+        if (agent === null)
+            throw new AgentError(not_connected(host), true);
+        return agent;
+    }
+    status_of(connection) {
+        return {
+            host: connection.host,
+            reported_host: connection.hello.host,
+            agent_version: connection.hello.agent_version,
+            connected_epoch: connection.connected_epoch,
+            built_in: false,
+            login: this.logins.get(connection) ?? null,
+            runs: connection.hello.runs,
+        };
+    }
+}
+// ── Helpers ──────────────────────────────────────────────────────────────────
+function not_connected(host) {
+    return `No agent is connected for ${host}.`;
+}
+function local_status(host) {
+    return { host, reported_host: host, agent_version: "built in", connected_epoch: 0, built_in: true, login: null, runs: [] };
+}
+function as_buffer(raw) {
+    if (Array.isArray(raw))
+        return Buffer.concat(raw);
+    return Buffer.isBuffer(raw) ? raw : Buffer.from(raw);
+}

package/dist/server/agents/local.d.ts

@@ -0,0 +1,24 @@
+import { LongRuns, type LongRunOptions } from "../../agent/long_runs.ts";
+import type { AppRequests } from "../../agent/session.ts";
+import type { TaskRunner } from "../../agent/tasks.ts";
+import { type Agent, type AgentRunOptions, type AgentStreamOptions, type CommandStream, type LongRun, type LongRunPoll, type RunResult } from "./agent.ts";
+export interface LocalAgentOptions<Task> {
+    runner: TaskRunner<Task>;
+    long_runs?: LongRunOptions;
+    requests?: AppRequests;
+}
+export declare class LocalAgent<Task> implements Agent<Task> {
+    readonly long_runs: LongRuns<Task>;
+    private readonly runner;
+    private readonly requests;
+    constructor(state_directory: string, options: LocalAgentOptions<Task>);
+    run(task: Task, options: AgentRunOptions): Promise<RunResult>;
+    stream(task: Task, options?: AgentStreamOptions): CommandStream;
+    start(run_id: string, task: Task, options?: AgentStreamOptions): Promise<LongRun>;
+    poll(run_id: string, offset: number): Promise<LongRunPoll>;
+    attach(run_id: string, offset: number): CommandStream;
+    stop(run_id: string): Promise<LongRun>;
+    forget(run_id: string): Promise<void>;
+    runs(): Promise<LongRun[]>;
+    request(type: string, body?: Record<string, unknown>): Promise<unknown>;
+}

package/dist/server/agents/local.js

@@ -0,0 +1,62 @@
+// The agent built into the server for its own machine. It runs commands itself with no socket between, through the
+// same code a remote agent uses, so a command behaves the same on every host.
+// ── Imports ──────────────────────────────────────────────────────────────────
+import { LongRuns } from "../../agent/long_runs.js";
+import { AgentError, ended_stream, } from "./agent.js";
+// ── Local agent ──────────────────────────────────────────────────────────────
+export class LocalAgent {
+    long_runs;
+    runner;
+    requests;
+    // Long runs keep their output under the state directory, so they outlive a restart of the server.
+    constructor(state_directory, options) {
+        this.runner = options.runner;
+        this.long_runs = new LongRuns(state_directory, options.runner, options.long_runs);
+        this.requests = options.requests ?? {};
+    }
+    run(task, options) {
+        return this.runner.run(task, options);
+    }
+    stream(task, options = {}) {
+        if (this.runner.stream === undefined)
+            return ended_stream("This agent does not stream its tasks.");
+        return this.runner.stream(task, options);
+    }
+    start(run_id, task, options = {}) {
+        return as_agent_error(() => this.long_runs.start(run_id, task, options.stdin ?? null));
+    }
+    poll(run_id, offset) {
+        return as_agent_error(() => this.long_runs.poll(run_id, offset));
+    }
+    attach(run_id, offset) {
+        try {
+            return this.long_runs.tail(run_id, offset);
+        }
+        catch (error) {
+            return ended_stream(error.message);
+        }
+    }
+    stop(run_id) {
+        return as_agent_error(() => this.long_runs.stop(run_id));
+    }
+    forget(run_id) {
+        return as_agent_error(() => this.long_runs.forget(run_id));
+    }
+    async runs() {
+        return this.long_runs.list();
+    }
+    request(type, body = {}) {
+        if (!Object.hasOwn(this.requests, type))
+            return Promise.reject(new AgentError(`This agent does not know the request '${type}'.`));
+        const message = { ...body, type, id: "local" };
+        return as_agent_error(() => this.requests[type](message));
+    }
+}
+async function as_agent_error(work) {
+    try {
+        return await work();
+    }
+    catch (error) {
+        throw error instanceof AgentError ? error : new AgentError(error.message);
+    }
+}

package/dist/server/agents/route.d.ts

@@ -0,0 +1,3 @@
+import type { FastifyInstance } from "fastify";
+import type { AgentHub } from "./hub.ts";
+export declare function register_agent_route<Task>(app: FastifyInstance, hub: AgentHub<Task>, path?: string): Promise<void>;

package/dist/server/agents/route.js

@@ -0,0 +1,24 @@
+// The WebSocket agents dial in on. The upgrade names the host, by the header an agent logging in with its key sends or
+// by the token in its Authorization header, so an unknown one is refused before any socket opens.
+// ── Imports ──────────────────────────────────────────────────────────────────
+import fastify_websocket from "@fastify/websocket";
+// A run's output can be large, so one message may be up to this size.
+const largest_message_in_bytes = 64 * 1024 * 1024;
+// ── Route ────────────────────────────────────────────────────────────────────
+export async function register_agent_route(app, hub, path = "/api/agent") {
+    await app.register(fastify_websocket, { options: { maxPayload: largest_message_in_bytes } });
+    const admitted = new WeakMap();
+    app.get(path, {
+        websocket: true,
+        preValidation: async (request, reply) => {
+            const admission = hub.admit(request.headers);
+            if ("error" in admission)
+                return reply.code(401).send({ error: admission.error });
+            admitted.set(request, admission);
+        },
+    }, (socket, request) => {
+        const { host, login } = admitted.get(request);
+        hub.accept(socket, host, login);
+    });
+    app.addHook("onClose", async () => hub.close());
+}

package/dist/server/backup_files.d.ts

@@ -0,0 +1,3 @@
+import type { BackupNaming, BackupStore } from "../backups.ts";
+export declare function backup_path(folder: string, naming: BackupNaming, name: string): string;
+export declare function file_backup_store(folder: () => string, naming: BackupNaming, copy_to: (path: string) => void): BackupStore;

package/dist/server/backup_files.js

@@ -0,0 +1,25 @@
+// Backups kept as files in a folder on disk, for an app's main process or server.
+import { mkdirSync, readdirSync, rmSync, statSync } from "node:fs";
+import { join } from "node:path";
+// The path of a backup in the folder, refusing any name the naming did not write.
+export function backup_path(folder, naming, name) {
+    if (!naming.pattern.test(name))
+        throw new Error(`not a backup name: ${name}`);
+    return join(folder, name);
+}
+// A folder of backup files, made when first used; copy_to writes the app's data to the path it is given, such as through SQLite's own backup.
+export function file_backup_store(folder, naming, copy_to) {
+    const path_of = (name) => backup_path(folder(), naming, name);
+    return {
+        list: () => {
+            mkdirSync(folder(), { recursive: true });
+            return readdirSync(folder()).filter((name) => naming.pattern.test(name)).map((name) => ({ name, size_bytes: statSync(path_of(name)).size }));
+        },
+        take: (name) => {
+            mkdirSync(folder(), { recursive: true });
+            copy_to(path_of(name));
+            return statSync(path_of(name)).size;
+        },
+        remove: (name) => rmSync(path_of(name)),
+    };
+}

package/dist/server/config.d.ts

@@ -0,0 +1,39 @@
+export interface ConfigOption {
+    variable?: string;
+    flag?: string;
+    help: string;
+    placeholder?: string;
+    default?: string;
+    required?: boolean;
+}
+export interface ServerConfigSpec<Name extends string = never> {
+    program: string;
+    summary: string;
+    env_prefix: string;
+    default_port: number;
+    options?: Record<Name, ConfigOption>;
+    built_in?: Partial<Record<BuiltInName, Partial<ConfigOption>>>;
+    web_folder_default?: string;
+    secret?: string | false;
+    argv?: string[];
+    env?: Record<string, string | undefined>;
+    exit_on_help?: boolean;
+}
+export interface ServerConfig<Name extends string = never> {
+    host: string;
+    port: number;
+    web_folder: string;
+    secret: string;
+    values: Record<Name, string | undefined>;
+    usage: string;
+}
+type BuiltInName = "host" | "port" | "web_folder";
+export declare class HelpRequested extends Error {
+    readonly usage: string;
+    constructor(usage: string);
+}
+export declare const loopback_hosts: string[];
+export declare function is_loopback(host: string): boolean;
+export declare function read_secret_file(path: string): string;
+export declare function read_server_config<Name extends string = never>(spec: ServerConfigSpec<Name>): ServerConfig<Name>;
+export {};

package/dist/server/config.js

@@ -0,0 +1,109 @@
+// A server's settings from the command line and the environment: the address and port, the web folder, the app's own
+// options, and the secret browsers sign in with, read from a file or a variable. Without a secret the server may only
+// listen on this machine.
+// ── Imports ──────────────────────────────────────────────────────────────────
+import { readFileSync } from "node:fs";
+import { parseArgs } from "node:util";
+export class HelpRequested extends Error {
+    usage;
+    constructor(usage) {
+        super(usage);
+        this.usage = usage;
+    }
+}
+// ── Settings ─────────────────────────────────────────────────────────────────
+export const loopback_hosts = ["127.0.0.1", "::1", "localhost"];
+export function is_loopback(host) {
+    return loopback_hosts.includes(host);
+}
+// ── Secrets ──────────────────────────────────────────────────────────────────
+// The file's text without its final newline; an unreadable or empty file is an error.
+export function read_secret_file(path) {
+    let secret;
+    try {
+        secret = readFileSync(path, "utf8").replace(/\r?\n$/, "");
+    }
+    catch (error) {
+        throw new Error(`Could not read the secret at ${path}: ${error.message}`);
+    }
+    if (secret.trim() === "")
+        throw new Error(`The secret at ${path} is empty`);
+    return secret.trim();
+}
+// ── Reading ──────────────────────────────────────────────────────────────────
+function capitals(name) {
+    return name.replaceAll("-", "_").toUpperCase();
+}
+function usage_text(program, summary, options, secret_note) {
+    const entries = Object.values(options);
+    const synopsis = entries
+        .map((option) => (option.required ? `--${option.flag} ${option.placeholder}` : `[--${option.flag} ${option.placeholder}]`))
+        .join(" ");
+    const flag_width = Math.max(...entries.map((option) => option.flag.length)) + 2;
+    const variable_width = Math.max(...entries.map((option) => option.variable.length));
+    const rows = entries.map((option) => {
+        const suffix = option.default === undefined ? "" : ` (default ${option.default})`;
+        return `  ${`--${option.flag}`.padEnd(flag_width)}  ${option.variable.padEnd(variable_width)}  ${option.help}${suffix}`;
+    });
+    return `Usage: ${program} ${synopsis}\n\n${summary} Every option can also be set in the environment:\n${rows.join("\n")}${secret_note}`;
+}
+export function read_server_config(spec) {
+    const { env_prefix, argv = process.argv.slice(2), env = process.env, exit_on_help = true } = spec;
+    const secret_name = spec.secret === undefined ? "token" : spec.secret;
+    const own = (spec.options ?? {});
+    const changes = spec.built_in ?? {};
+    const built_in = {
+        host: { help: "the address to listen on", placeholder: "<address>", default: "127.0.0.1", ...changes.host },
+        port: { help: "the port to listen on", placeholder: "<number>", default: String(spec.default_port), ...changes.port },
+    };
+    if (spec.web_folder_default !== undefined) {
+        built_in.web_folder = { help: "the built web page", placeholder: "<folder>", default: spec.web_folder_default, ...changes.web_folder };
+    }
+    const options = Object.fromEntries(Object.entries({ ...own, ...built_in }).map(([name, option]) => [name, {
+            ...option,
+            variable: option.variable ?? `${env_prefix}_${capitals(name)}`,
+            flag: option.flag ?? name.replaceAll("_", "-"),
+            placeholder: option.placeholder ?? "<value>",
+        }]));
+    const secret_note = secret_name === false ? "" : `\n\nThe ${secret_name} browsers sign in with is read from the file named by ${env_prefix}_${capitals(secret_name)}_FILE,\nor from ${env_prefix}_${capitals(secret_name)}. Without one the server only listens on this machine.`;
+    const usage = usage_text(spec.program, spec.summary, options, secret_note);
+    const { values: flags } = parseArgs({
+        args: argv,
+        options: { ...Object.fromEntries(Object.values(options).map((option) => [option.flag, { type: "string" }])), help: { type: "boolean" } },
+    });
+    if (flags.help) {
+        if (!exit_on_help)
+            throw new HelpRequested(usage);
+        console.log(usage);
+        process.exit(0);
+    }
+    const value_of = (name) => {
+        const option = options[name];
+        return flags[option.flag] ?? env[option.variable] ?? option.default;
+    };
+    for (const [name, option] of Object.entries(options)) {
+        if (option.required && value_of(name) === undefined)
+            throw new Error(`no ${option.flag} given\n\n${usage}`);
+    }
+    const port_text = value_of("port");
+    const port = Number(port_text);
+    if (!Number.isInteger(port) || port < 1 || port > 65535)
+        throw new Error(`not a port: ${port_text}`);
+    let secret = "";
+    if (secret_name !== false) {
+        const secret_file = env[`${env_prefix}_${capitals(secret_name)}_FILE`];
+        secret = secret_file ? read_secret_file(secret_file) : (env[`${env_prefix}_${capitals(secret_name)}`] ?? "").trim();
+    }
+    const host = value_of("host");
+    if (secret_name !== false && secret === "" && !is_loopback(host)) {
+        throw new Error(`listening on ${host} needs a ${secret_name}; set ${env_prefix}_${capitals(secret_name)}_FILE or ${env_prefix}_${capitals(secret_name)}`);
+    }
+    return {
+        host,
+        port,
+        web_folder: "web_folder" in options ? value_of("web_folder") : "",
+        secret,
+        values: Object.fromEntries(Object.keys(own).map((name) => [name, value_of(name)])),
+        usage,
+    };
+}

package/dist/server/cors.d.ts

@@ -0,0 +1,8 @@
+import type { FastifyInstance } from "fastify";
+export interface OpenCorsOptions {
+    methods?: string[];
+    allowed_headers?: string[];
+    client_id_header?: string;
+    max_age_seconds?: number;
+}
+export declare function register_open_cors(app: FastifyInstance, options?: OpenCorsOptions): Promise<void>;

package/dist/server/cors.js

@@ -0,0 +1,13 @@
+// Cross-origin access for an API that a native or mobile shell calls from a page of its own: any origin may, since a
+// browser sends no cookies with such a call and the server's secret is still needed.
+import fastify_cors from "@fastify/cors";
+import { default_client_id_header } from "./events.js";
+export async function register_open_cors(app, options = {}) {
+    const { methods = ["GET", "POST"], allowed_headers = [], client_id_header = default_client_id_header, max_age_seconds = 86_400 } = options;
+    await app.register(fastify_cors, {
+        origin: "*",
+        methods,
+        allowedHeaders: ["authorization", "content-type", client_id_header, ...allowed_headers],
+        maxAge: max_age_seconds,
+    });
+}

package/dist/server/events.d.ts

@@ -0,0 +1,33 @@
+import type { FastifyInstance, FastifyRequest } from "fastify";
+export interface EventStreamOptions {
+    heartbeat_ms?: number;
+    retry_ms?: number;
+    hello_event?: string | null;
+    changed_event?: string;
+    client_id_header?: string;
+}
+export interface StreamClient {
+    id: string;
+    request: FastifyRequest;
+}
+export interface SendOptions {
+    event?: string;
+    except_client_id?: string;
+    to?: (client: StreamClient) => boolean;
+}
+export declare const default_client_id_header = "x-client-id";
+export declare class EventStream {
+    readonly heartbeat_ms: number;
+    readonly retry_ms: number;
+    readonly hello_event: string | null;
+    readonly changed_event: string;
+    readonly client_id_header: string;
+    private readonly streams;
+    constructor(options?: EventStreamOptions);
+    get client_count(): number;
+    client_id_of(request: FastifyRequest): string;
+    send(data: string, options?: SendOptions): void;
+    announce_change(except_client_id?: string): void;
+    register(app: FastifyInstance, path?: string): void;
+    close(): void;
+}