@babylonjs-toolkit/server 0.0.0-stage → 9.35.0

package/lib/admin/AlertChannels.js

@@ -0,0 +1,120 @@
+// Alert channels (game-server-admin-console D24, DR §8 channel payloads): a generic webhook, Slack, Discord, Microsoft
+// Teams and PagerDuty Events v2, each one fetch POST with a timeout. Channel secrets (url, routingKey) stay in the store
+// and never leave the server: views show the url as scheme://host/… and the routing key as set / not set.
+import { ALERT_CHANNEL_TIMEOUT_MS } from "./AdminConstants.js";
+/** Slack and Discord emoji of a firing alert. */
+const FIRING_EMOJI = ":rotating_light:";
+/** Slack and Discord emoji of a resolved alert. */
+const RESOLVED_EMOJI = ":white_check_mark:";
+/** The PagerDuty event source of an alert without an instance. */
+const DEFAULT_PAGERDUTY_SOURCE = "babylon-game-server";
+/** The Microsoft Teams card type and context (connector MessageCard). */
+const TEAMS_CARD_TYPE = "MessageCard";
+const TEAMS_CARD_CONTEXT = "https://schema.org/extensions";
+/** Delivers alerts to their channels. */
+export class AlertChannels {
+    /** Request timeout of a delivery, in milliseconds. */
+    timeoutMs;
+    /**
+     * Creates the deliverer.
+     * @param timeoutMs Request timeout, in milliseconds. Default ALERT_CHANNEL_TIMEOUT_MS.
+     */
+    constructor(timeoutMs = ALERT_CHANNEL_TIMEOUT_MS) {
+        this.timeoutMs = timeoutMs;
+    }
+    /**
+     * Posts an alert to a channel with its DR §8 payload. A network failure, a timeout or a non-2xx answer is an
+     * outcome, never a throw.
+     * @param channel The channel with its secrets.
+     * @param alert The alert.
+     * @param state Whether it fired or resolved.
+     * @param pagerDutyUrl The PagerDuty Events v2 URL (tests replace it, R10).
+     * @returns Whether it was delivered, and why not.
+     */
+    async deliver(channel, alert, state, pagerDutyUrl) {
+        const targetUrl = (channel.kind === "pagerduty") ? pagerDutyUrl : channel.url;
+        if (targetUrl == null || targetUrl === "")
+            return { ok: false, error: "the channel has no URL" };
+        try {
+            const answer = await fetch(targetUrl, {
+                method: "POST",
+                headers: { "content-type": "application/json" },
+                body: JSON.stringify(alertPayloadOf(channel, alert, state)),
+                signal: AbortSignal.timeout(this.timeoutMs)
+            });
+            await answer.arrayBuffer();
+            return answer.ok ? { ok: true, error: null } : { ok: false, error: "the channel answered " + answer.status };
+        }
+        catch (error) {
+            return { ok: false, error: (error instanceof Error) ? error.message : String(error) };
+        }
+    }
+}
+/**
+ * The JSON body a channel receives (DR §8).
+ * @param channel The channel.
+ * @param alert The alert.
+ * @param state Whether it fired or resolved.
+ * @returns The payload.
+ */
+export function alertPayloadOf(channel, alert, state) {
+    const text = alertText(alert, state);
+    switch (channel.kind) {
+        case "slack":
+            return { text: text };
+        case "discord":
+            return { content: text };
+        case "teams":
+            return { "@type": TEAMS_CARD_TYPE, "@context": TEAMS_CARD_CONTEXT, summary: alert.summary, text: text };
+        case "pagerduty":
+            return {
+                routing_key: channel.routingKey,
+                event_action: (state === "firing") ? "trigger" : "resolve",
+                dedup_key: alert.alertId,
+                payload: { summary: alert.summary, source: alert.processId ?? DEFAULT_PAGERDUTY_SOURCE, severity: alert.severity }
+            };
+        default:
+            return { alertId: alert.alertId, ruleId: alert.ruleId, severity: alert.severity, state: state, summary: alert.summary, processId: alert.processId, firedAt: alert.firedAt, resolvedAt: alert.resolvedAt };
+    }
+}
+/**
+ * A channel as the console sees it: the url without its path, the routing key as set / not set.
+ * @param channel The stored channel.
+ * @returns The view.
+ */
+export function alertChannelView(channel) {
+    return {
+        channelId: channel.channelId,
+        kind: channel.kind,
+        name: channel.name,
+        url: maskedUrl(channel.url),
+        routingKey: (channel.routingKey != null && channel.routingKey !== "") ? "set" : "not set"
+    };
+}
+/**
+ * The chat text of an alert: "<emoji> [<severity>] <summary>".
+ * @param alert The alert.
+ * @param state Whether it fired or resolved.
+ * @returns The text.
+ */
+function alertText(alert, state) {
+    const emoji = (state === "firing") ? FIRING_EMOJI : RESOLVED_EMOJI;
+    const resolvedSuffix = (state === "resolved") ? " (resolved)" : "";
+    return emoji + " [" + alert.severity + "] " + alert.summary + resolvedSuffix;
+}
+/**
+ * A URL shown as scheme://host/… so its secret path never reaches the console.
+ * @param url The stored URL, or null.
+ * @returns The masked URL, or null.
+ */
+function maskedUrl(url) {
+    if (url == null)
+        return null;
+    try {
+        const parsed = new URL(url);
+        return parsed.protocol + "//" + parsed.host + "/…";
+    }
+    catch {
+        return "…";
+    }
+}

package/lib/admin/AlertEngine.d.ts

@@ -0,0 +1,231 @@
+import type { AdminAlertSeverity, AlertChannelView, AlertRuleId, AlertRuleView, AlertsRulesRequest, AlertView, CreateAlertChannelRequest, PageView } from "./AdminApiTypes.js";
+import type { AdminCoreServices } from "./AdminServices.js";
+import type { FleetDirectory } from "./FleetDirectory.js";
+import { type MetricsSampler } from "./MetricsSampler.js";
+import type { ServerEvents } from "./ServerEvents.js";
+/** A built-in rule: its label, default threshold and unit, default duration and severity (DR §8). */
+interface AlertRuleDefinition {
+    label: string;
+    threshold: number | null;
+    thresholdUnit: string | null;
+    forMinutes: number;
+    severity: AdminAlertSeverity;
+}
+/** The built-in rules (DR §8). Every rule starts enabled. */
+export declare const ALERT_RULE_DEFINITIONS: Record<AlertRuleId, AlertRuleDefinition>;
+/** Called when an alert fires (the onAlertFired admin hook, R29). */
+export type AlertFiredListener = (alert: AlertView) => void;
+/** The rules, channels and alert history of the fleet. */
+export declare class AlertEngine {
+    /** The shared core services. */
+    private readonly services;
+    /** The fleet directory (heartbeats). */
+    private readonly fleet;
+    /** The activity feed's server events. */
+    private readonly serverEvents;
+    /** This instance's metrics history (dedicated overruns without Redis). */
+    private readonly metricsSampler;
+    /** The channel deliverer. */
+    private readonly channels;
+    /** When each rule started breaching on this leader, in milliseconds. */
+    private readonly breachingSince;
+    /** Listeners of fired alerts. */
+    private readonly firedListeners;
+    /** The newest audit sequence already read, or null before the first evaluation. */
+    private lastAuditSequence;
+    /** True once the default rules were written to the store. */
+    private hasSeededRules;
+    /**
+     * Creates the engine; nothing runs until the leader calls evaluate().
+     * @param services The shared core services.
+     * @param fleet The fleet directory.
+     * @param serverEvents The activity feed's server events.
+     * @param metricsSampler This instance's metrics history.
+     */
+    constructor(services: AdminCoreServices, fleet: FleetDirectory, serverEvents: ServerEvents, metricsSampler: MetricsSampler);
+    /**
+     * Calls back whenever an alert fires.
+     * @param listener The listener.
+     */
+    onAlertFired(listener: AlertFiredListener): void;
+    /** One leader evaluation (DR §7.9): every enabled, unsilenced rule is checked, fired or resolved. */
+    evaluate(): Promise<void>;
+    /**
+     * Every rule with its settings (stored settings over the defaults).
+     * @returns The rules, in the table's order.
+     */
+    listRules(): Promise<AlertRuleView[]>;
+    /**
+     * Changes a rule's settings (PUT alerts/rules/:ruleId).
+     * @param ruleId The rule.
+     * @param request The new settings.
+     * @returns The rule.
+     * @throws AdminRequestError 404 for an unknown rule, 400 for an unknown channel or severity.
+     */
+    updateRule(ruleId: string, request: AlertsRulesRequest): Promise<AlertRuleView>;
+    /**
+     * Silences a rule for some minutes (0 ends a silence).
+     * @param ruleId The rule.
+     * @param minutes How long.
+     * @returns The rule.
+     * @throws AdminRequestError 404 for an unknown rule, 400 for a negative duration.
+     */
+    silenceRule(ruleId: string, minutes: number): Promise<AlertRuleView>;
+    /**
+     * Every channel, secrets masked.
+     * @returns The channels, oldest first.
+     */
+    listChannels(): Promise<AlertChannelView[]>;
+    /**
+     * Adds a channel (POST alerts/channels).
+     * @param request The channel.
+     * @param createdBy Who adds it.
+     * @returns The channel, secrets masked.
+     * @throws AdminRequestError 400 for an unknown kind, a missing name, URL or routing key.
+     */
+    createChannel(request: CreateAlertChannelRequest, createdBy: string): Promise<AlertChannelView>;
+    /**
+     * Removes a channel and takes it off every rule.
+     * @param channelId The channel.
+     * @throws AdminRequestError 404 for an unknown channel.
+     */
+    deleteChannel(channelId: string): Promise<void>;
+    /**
+     * Sends a test alert to a channel (POST alerts/channels/:channelId/test).
+     * @param channelId The channel.
+     * @returns Whether it was delivered.
+     * @throws AdminRequestError 404 for an unknown channel.
+     */
+    testChannel(channelId: string): Promise<{
+        delivered: boolean;
+        error: string | null;
+    }>;
+    /**
+     * One page of the alert history, newest first.
+     * @param state Only "firing" or "resolved" alerts, or null for both.
+     * @param page The page, from 1.
+     * @returns The page and the number of matches.
+     */
+    listAlerts(state: AlertView["state"] | null, page: number): Promise<PageView<AlertView>>;
+    /**
+     * Acknowledges an alert: records who saw it and when.
+     * @param alertId The alert.
+     * @param acknowledgedBy The admin's name.
+     * @returns The alert.
+     * @throws AdminRequestError 404 for an unknown alert.
+     */
+    acknowledge(alertId: string, acknowledgedBy: string): Promise<AlertView>;
+    /** Writes the default rules the store does not have yet, once record keeping is on (R3). */
+    private seedRulesOnce;
+    /**
+     * Reads what every rule needs once: the instances, the new audit records and the dedicated overrun rate.
+     * @returns The context.
+     */
+    private buildContext;
+    /**
+     * Checks one rule and fires or resolves its alert (DR §7.9).
+     * @param rule The rule's settings.
+     * @param context The evaluation context.
+     * @param firing The rule's firing alert, or null.
+     */
+    private evaluateRule;
+    /**
+     * Whether a rule breaches now (DR §8 conditions).
+     * @param rule The rule's settings.
+     * @param context The evaluation context.
+     * @returns The breach, or null.
+     */
+    private breachOf;
+    /**
+     * nearLimits: an instance hosts at least threshold percent of limits.maxSessions.
+     * @param upInstances The live instances.
+     * @param thresholdPercent The threshold, in percent.
+     * @returns The breach, or null.
+     */
+    private nearLimitsBreach;
+    /**
+     * newAdminAddress: a new second-factor sign-in from an address the account did not use in the lookback period. An
+     * account's first sign-in never counts.
+     * @param context The evaluation context.
+     * @returns The breach, or null.
+     */
+    private newAdminAddressBreach;
+    /**
+     * Audit records appended since the last evaluation. The first evaluation only notes where the stream ends.
+     * @returns The new records, oldest first.
+     */
+    private readNewAuditRecords;
+    /**
+     * The fleet's dedicated tick overruns per minute between each live instance's last two metrics samples.
+     * @param upInstances The live instances.
+     * @returns The rate.
+     */
+    private dedicatedOverrunsPerMinute;
+    /**
+     * An instance's last two metrics samples: from this instance's ring, or from the store stream with Redis.
+     * @param instance The instance.
+     * @returns At most two samples, oldest first.
+     */
+    private lastTwoSamples;
+    /**
+     * Fires an alert: stores it, delivers it to the rule's channels, records a server event and calls the listeners.
+     * Event rules store it resolved at once (one alert per event).
+     * @param rule The rule.
+     * @param breach What breaches.
+     * @param now The evaluation time.
+     */
+    private fire;
+    /**
+     * Resolves a firing alert and delivers the resolve.
+     * @param rule The rule.
+     * @param firing The firing alert.
+     */
+    private resolve;
+    /**
+     * Delivers an alert to every channel of its rule (missing channels are skipped).
+     * @param rule The rule.
+     * @param alert The alert.
+     * @param state Fired or resolved.
+     * @returns One delivery entry per channel.
+     */
+    private deliverToRule;
+    /**
+     * Every alert in its newest state, newest fired first.
+     * @returns The alerts.
+     */
+    private currentAlerts;
+    /**
+     * The firing alert of each rule.
+     * @returns Rule id → firing alert.
+     */
+    private firingAlertsByRule;
+    /**
+     * Every rule's settings, stored or default.
+     * @returns The records, in the table's order.
+     */
+    private ruleRecords;
+    /**
+     * The stored rule documents.
+     * @returns Rule id → document.
+     */
+    private storedRules;
+    /**
+     * The stored channels.
+     * @returns The channels.
+     */
+    private channelRecords;
+    /**
+     * A known rule's stored document.
+     * @param ruleId The rule.
+     * @returns The document, or null while the rule has its defaults.
+     * @throws AdminRequestError 404 for an unknown rule.
+     */
+    private requireRule;
+    /**
+     * Checks that every channel id exists.
+     * @param channelIds The channel ids.
+     * @throws AdminRequestError 400 naming the first unknown channel.
+     */
+    private requireChannels;
+}
+export {};