@babylonjs-toolkit/server 0.0.0-stage → 9.35.1

package/lib/admin/FleetDirectory.d.ts

@@ -0,0 +1,323 @@
+import type { TlsMaterial } from "../TlsCertificates.js";
+import type { AdminLogLevel, AdminNoticePayload, DedicatedStartedBy, DrainStartedView, InstanceHeartbeat, InstancesDrainRequest, InstanceView, LobbyKickRequest, LobbyKickView, LogEntryView, MaintenanceState, NoticeSentView, PlayerSummaryView, SceneCheckView, SessionSummaryView } from "./AdminApiTypes.js";
+import type { AdminCoreServices } from "./AdminServices.js";
+import type { AdminCollection } from "./AdminStore.js";
+import type { LogFilter } from "./LogBuffer.js";
+/** Arguments and results of every fleet command (R15). Commands with nothing to pass or return use null. */
+export interface FleetCommandContract {
+    describeSessions: {
+        arguments: null;
+        result: SessionSummaryView[];
+    };
+    searchPlayers: {
+        arguments: {
+            search: string;
+            includeAddresses: boolean;
+        };
+        result: PlayerSummaryView[];
+    };
+    setMaintenance: {
+        arguments: MaintenanceState;
+        result: null;
+    };
+    clearMaintenance: {
+        arguments: null;
+        result: null;
+    };
+    drain: {
+        arguments: InstancesDrainRequest;
+        result: DrainStartedView;
+    };
+    sendNotice: {
+        arguments: {
+            roomId: string | null;
+            playerId: number;
+            notice: AdminNoticePayload;
+        };
+        result: NoticeSentView;
+    };
+    disconnectBanned: {
+        arguments: {
+            banIds: string[];
+            message: string;
+        };
+        result: {
+            disconnected: number;
+        };
+    };
+    kickFromLobby: {
+        arguments: LobbyKickRequest;
+        result: LobbyKickView;
+    };
+    readLogs: {
+        arguments: {
+            filter: LogFilter;
+            afterSequence: number;
+            limit: number;
+        };
+        result: LogEntryView[];
+    };
+    setLogLevel: {
+        arguments: {
+            level: AdminLogLevel;
+            revertAfterMinutes: number;
+        };
+        result: null;
+    };
+    checkDedicatedScene: {
+        arguments: {
+            sceneName: string;
+        };
+        result: SceneCheckView;
+    };
+    startDedicated: {
+        arguments: {
+            sceneName: string;
+            sessionName: string;
+            startedBy: DedicatedStartedBy;
+        };
+        result: {
+            roomId: string;
+        };
+    };
+    reloadAuthKeys: {
+        arguments: null;
+        result: null;
+    };
+}
+/** Names of the commands one instance can ask another to run (D16). */
+export type FleetCommandName = keyof FleetCommandContract;
+/** The arguments of a command. */
+export type FleetCommandArguments<Name extends FleetCommandName> = FleetCommandContract[Name]["arguments"];
+/** The result of a command. */
+export type FleetCommandResult<Name extends FleetCommandName> = FleetCommandContract[Name]["result"];
+/** Runs one command on this instance. */
+export type FleetCommandHandler<Name extends FleetCommandName> = (commandArguments: FleetCommandArguments<Name>) => Promise<FleetCommandResult<Name>>;
+/** A command request on the bus. */
+export interface FleetCommand {
+    commandId: string;
+    name: FleetCommandName;
+    arguments: unknown;
+    replyTopic: string;
+    fromProcessId: string;
+}
+/** A command reply on the bus. */
+export interface FleetCommandReply {
+    commandId: string;
+    processId: string;
+    ok: boolean;
+    result: unknown;
+    error: string | null;
+    /** The HTTP status of an AdminRequestError the handler threw, so the caller answers with it; else null. */
+    status: number | null;
+}
+/** A fan-out result: failed instances are reported, not thrown. */
+export interface FleetFanOutResult<Result> {
+    results: {
+        processId: string;
+        result: Result;
+    }[];
+    failures: {
+        processId: string;
+        error: string;
+    }[];
+}
+/** One instance's entry in the heartbeat hash: its newest heartbeat and the one its counter rates are measured from. */
+export interface StoredHeartbeat {
+    /** The newest heartbeat. */
+    heartbeat: InstanceHeartbeat;
+    /** The latest earlier heartbeat with different counters, or null before there is one. */
+    previous: InstanceHeartbeat | null;
+}
+/** One instance as the overview reads it: its view and the heartbeat its rates are measured from. */
+export interface FleetInstanceRecord {
+    /** The instance row. */
+    view: InstanceView;
+    /** The earlier heartbeat of the rates, or null. */
+    previous: InstanceHeartbeat | null;
+}
+/** Calls back on an announced change of a store collection. */
+export type FleetChangeListener = (collection: AdminCollection) => void;
+/** Heartbeats, the command bus and change announcements of this instance. */
+export declare class FleetDirectory {
+    /** The shared core services. */
+    private readonly services;
+    /** Command handlers by name (each name once). */
+    private readonly handlers;
+    /** Listeners of change announcements. */
+    private readonly changeListeners;
+    /** The event-loop delay histogram, while started. */
+    private eventLoopMonitor;
+    /** The heartbeat timer, while started. */
+    private heartbeatTimer;
+    /** True while a heartbeat is being written, so a slow store never stacks them. */
+    private isWritingHeartbeat;
+    /** The newest heartbeat this instance wrote, or null. */
+    private lastHeartbeat;
+    /** The heartbeat the counter rates are measured from, or null. */
+    private rateBaseHeartbeat;
+    /** The counter snapshot of the newest heartbeat (the metrics cache hands the same object until it renews). */
+    private lastSnapshot;
+    /** CPU time used up to the last heartbeat. */
+    private lastCpuUsage;
+    /** High-resolution time of the last CPU sample, in nanoseconds. */
+    private lastCpuSampleAt;
+    /** Real time of the last "heartbeat failed" warning, in milliseconds. */
+    private lastHeartbeatWarningAt;
+    /** The subscribed command listener, while started. */
+    private readonly commandListener;
+    /** The subscribed change listener, while started. */
+    private readonly changeListener;
+    /**
+     * Prepares the directory; nothing is published until start().
+     * @param services The shared core services.
+     */
+    constructor(services: AdminCoreServices);
+    /** This instance's process id (matchMaker.processId, R5). */
+    get localProcessId(): string;
+    /** True when Redis connects the fleet; false for a single instance. */
+    get isScaledOut(): boolean;
+    /** Starts heartbeats, command handling and change announcements; the first heartbeat is written at once. */
+    start(): Promise<void>;
+    /** Stops heartbeats and command handling and removes this instance's heartbeat (R4). */
+    stop(): Promise<void>;
+    /**
+     * Every known instance with its status, newest heartbeat first.
+     * @returns The instance rows.
+     */
+    listInstances(): Promise<InstanceView[]>;
+    /**
+     * Every known instance with the heartbeat its rates are measured from, newest heartbeat first. Instances silent
+     * for FLEET_LOST_AFTER_MS are "lost"; those silent for FLEET_FORGET_AFTER_MS are removed from the hash.
+     * @returns The records.
+     */
+    listInstanceRecords(): Promise<FleetInstanceRecord[]>;
+    /**
+     * Drops (and forgets) each lost instance whose public address a newer live instance now serves: that instance was
+     * restarted in its place, so it is no longer lost (T14: restarting a lost instance resolves its alert).
+     * @param records The instances, newest heartbeat first.
+     * @returns The records without the restarted instances.
+     */
+    private withoutRestartedInstances;
+    /**
+     * Runs a command on one instance: in-process when it is this one, else over the bus.
+     * @param processId The instance.
+     * @param name The command.
+     * @param commandArguments Its arguments.
+     * @returns The command's result.
+     * @throws AdminRequestError 404 for an unknown or lost instance, 504 when no reply came in time, or the status the
+     *     handler refused with.
+     */
+    runOn<Name extends FleetCommandName>(processId: string, name: Name, commandArguments: FleetCommandArguments<Name>): Promise<FleetCommandResult<Name>>;
+    /**
+     * Runs a command on every live instance (this one always included).
+     * @param name The command.
+     * @param commandArguments Its arguments.
+     * @returns Each instance's result, and the instances that failed.
+     */
+    runOnAll<Name extends FleetCommandName>(name: Name, commandArguments: FleetCommandArguments<Name>): Promise<FleetFanOutResult<FleetCommandResult<Name>>>;
+    /**
+     * Registers this instance's handler of a command.
+     * @param name The command.
+     * @param handler Runs it; its arguments and result are copies (structured clones).
+     * @throws Error when the command already has a handler.
+     */
+    handle<Name extends FleetCommandName>(name: Name, handler: FleetCommandHandler<Name>): void;
+    /**
+     * Publishes that a store collection changed, so every instance (this one included) reloads it.
+     * @param collection The collection.
+     */
+    announceChange(collection: AdminCollection): Promise<void>;
+    /**
+     * Calls back on every announced change (any instance, this one included).
+     * @param listener The listener.
+     */
+    onChange(listener: FleetChangeListener): void;
+    /**
+     * The presence every instance shares (Redis when scaled out). Colyseus sets it when the server listens.
+     * @returns The presence.
+     */
+    private presence;
+    /**
+     * Runs a registered handler on this instance with copies of the arguments and the result, since local presence
+     * hands objects over by reference.
+     * @param name The command.
+     * @param commandArguments Its arguments.
+     * @returns A copy of the result.
+     * @throws AdminRequestError 501 when no handler is registered.
+     */
+    private runLocally;
+    /**
+     * Sends a command to another instance and waits for its reply on a per-command topic.
+     * @param processId The instance.
+     * @param name The command.
+     * @param commandArguments Its arguments.
+     * @returns The result.
+     * @throws AdminRequestError on a failed reply or after FLEET_COMMAND_TIMEOUT_MS.
+     */
+    private sendCommand;
+    /**
+     * Subscribes to a command's reply topic, publishes the command and resolves with the reply.
+     * @param command The command.
+     * @param processId The instance it goes to.
+     * @returns The reply.
+     * @throws AdminRequestError 504 after FLEET_COMMAND_TIMEOUT_MS.
+     */
+    private awaitReply;
+    /**
+     * Runs a command another instance sent and publishes the reply.
+     * @param command The command.
+     */
+    private receiveCommand;
+    /**
+     * Runs a received command and turns its outcome into a reply.
+     * @param command The command.
+     * @returns The reply.
+     */
+    private answerCommand;
+    /**
+     * Calls every change listener; a listener that throws is logged and the others still run.
+     * @param collection The changed collection.
+     */
+    private notifyChange;
+    /**
+     * Removes a long-lost instance from the heartbeat hash.
+     * @param processId The instance.
+     */
+    private forgetInstance;
+    /** Builds and writes this instance's heartbeat; a failure is logged at warn once per minute (DR §9). */
+    private writeHeartbeat;
+    /**
+     * Builds the next heartbeat entry, moving the rate base forward whenever the counters were renewed.
+     * @returns The entry to store.
+     */
+    private nextStoredHeartbeat;
+    /**
+     * This instance's heartbeat now (DR §6.5).
+     * @param snapshot The metrics counters, or null when metrics are off (the counters are then 0).
+     * @returns The heartbeat.
+     */
+    private buildHeartbeat;
+    /**
+     * CPU use since the last heartbeat, as a percent of one core (user plus system time over elapsed time).
+     * @returns The percent.
+     */
+    private sampleCpuPercent;
+    /**
+     * The mean event-loop delay since the last heartbeat; the histogram restarts afterwards.
+     * @returns The delay, in milliseconds (0 before any sample).
+     */
+    private sampleEventLoopLag;
+    /**
+     * Logs a failed heartbeat at warn, at most once per HEARTBEAT_WARNING_INTERVAL_MS.
+     * @param error What failed.
+     */
+    private warnHeartbeatFailure;
+}
+/**
+ * Days until the served certificate expires (DR §8), rounded down.
+ * @param material The TLS material served now, or null without TLS.
+ * @param nowMilliseconds The current time.
+ * @returns The days left (negative once expired), or null without TLS or for an unreadable certificate.
+ */
+export declare function certificateDaysLeft(material: TlsMaterial | null, nowMilliseconds: number): number | null;