@babylonjs-toolkit/server 0.0.0-stage → 9.35.1

package/lib/admin/ColyseusCloudService.d.ts

@@ -0,0 +1,180 @@
+import type { CloudBillingView, CloudDeployDetailView, CloudHistoryView, CloudLogLines, CloudLogStream, CloudLogsView, CloudPart, ColyseusCloudFeature, ColyseusCloudView } from "./AdminApiTypes.js";
+import type { AdminCoreServices } from "./AdminServices.js";
+/** The leader-refreshed, store-shared cache of the Colyseus Cloud API behind the console's Colyseus Cloud page (D2–D5). */
+export declare class ColyseusCloudService {
+    /** Whether the page applies (D8). */
+    readonly feature: ColyseusCloudFeature;
+    /** The admin services this cache reads the config, store and clock from. */
+    private readonly services;
+    /** Null unless a token is configured. */
+    private readonly client;
+    /** Host name of publicUrl, to mark this console's own instance (D11). */
+    private readonly ownHostName;
+    /** Deploy output this process fetched recently, by deploy id (D5). */
+    private readonly deployDetails;
+    /**
+     * Creates the cache; nothing is requested until the leader calls refreshDue or a route asks.
+     * @param services The admin core services (config, store, clock and the refresh test hook).
+     * @param environment The process environment (COLYSEUS_CLOUD marks Colyseus Cloud, D8).
+     */
+    constructor(services: AdminCoreServices, environment?: NodeJS.ProcessEnv);
+    /** True when a Cloud API token is configured, so the leader refreshes and the routes answer. */
+    get isConfigured(): boolean;
+    /**
+     * One leader refresh pass (D3–D5): unless a Cloud 429 pauses the fleet, refreshes "applications" when due and then,
+     * once an application is chosen, every other due resource in RESOURCE_REFRESH_ORDER, stopping at the first 429.
+     * Always reports the pass to the colyseusCloudRefreshed hook (D17), early returns included.
+     */
+    refreshDue(): Promise<void>;
+    /**
+     * GET cloud: the feature, the application choice and the overview, load, deploys and egress parts (always answers).
+     * @returns The summary view.
+     */
+    readSummary(): Promise<ColyseusCloudView>;
+    /**
+     * GET cloud/history: the load history of the last 30 days, one point a day (an empty part while no application is
+     * chosen). The last 24 hours are the console's own Metrics page, so Colyseus's minute history is not read.
+     * @returns The history part.
+     * @throws AdminRequestError 404 when no token is configured.
+     */
+    readHistory(): Promise<CloudPart<CloudHistoryView>>;
+    /**
+     * GET cloud/billing: the billing account and this application's subscription (an empty part while no application is chosen).
+     * @returns The billing part.
+     * @throws AdminRequestError 404 when no token is configured.
+     */
+    readBilling(): Promise<CloudPart<CloudBillingView>>;
+    /**
+     * GET cloud/deploys/:deployId: one deploy with its output, fetched on request and reused by this process for
+     * COLYSEUS_CLOUD_DEPLOY_DETAIL_CACHE_MS (D5).
+     * @param deployId Colyseus's deploy id.
+     * @returns The deploy with its output.
+     * @throws AdminRequestError 404 without a token, an application or such a deploy; 503 while a Cloud 429 pauses the
+     *     fleet (detail: the ISO time it ends); 502 when Colyseus failed.
+     */
+    readDeploy(deployId: number): Promise<CloudDeployDetailView>;
+    /**
+     * GET cloud/instances/:instanceId/logs: an instance's newest log lines, at most one Cloud request per
+     * COLYSEUS_CLOUD_LOG_INTERVAL_MS for the whole fleet; another asker of the same instance, stream and lines within
+     * COLYSEUS_CLOUD_SHARED_LOGS_MS gets that answer (D5, D10).
+     * @param instanceId Colyseus's instance id.
+     * @param stream Which output stream to read.
+     * @param lines How many lines to read.
+     * @returns The logs.
+     * @throws AdminRequestError 404 without a token, an application or such an instance; 409 when the instance is not
+     *     running; 429 when the limit allows no request yet (detail: the next allowed ISO time); 502 when Colyseus failed.
+     */
+    readLogs(instanceId: number, stream: CloudLogStream, lines: CloudLogLines): Promise<CloudLogsView>;
+    /**
+     * The body of one refresh pass (§7 steps 1–5).
+     * @param now The clock time of the pass, in milliseconds.
+     */
+    private refreshPass;
+    /**
+     * Whether a resource should be refreshed now: never attempted, its retryAt reached, or its refresh interval since
+     * the last attempt elapsed (each within COLYSEUS_CLOUD_DUE_TOLERANCE_MS, so a slightly early tick still counts).
+     * @param resource The resource.
+     * @param nowMilliseconds The clock time of the pass.
+     * @returns True when due.
+     */
+    private isDue;
+    /**
+     * Fetches one resource and stores its snapshot: the new data on success; on a Cloud error the last good data with
+     * the problem and, for a 5xx or no answer, the retryAt Colyseus asked for. A 429 also pauses the fleet.
+     * @param resource The resource.
+     * @param fetchData Requests and converts the resource.
+     * @param nowMilliseconds The clock time of the pass.
+     * @returns False after a 429 (the pass must stop), else true.
+     * @throws Any error other than ColyseusCloudApiError (the leader logs it).
+     */
+    private refreshResource;
+    /**
+     * Pauses every refresh of the fleet after a Cloud 429 until Colyseus's Retry-After (D5).
+     * @param retryAfterSeconds Colyseus's wait, or null for COLYSEUS_CLOUD_DEFAULT_RETRY_SECONDS.
+     * @param nowMilliseconds The current clock time.
+     * @returns The ISO time the pause ends.
+     */
+    private writeRateLimit;
+    /**
+     * The client, for the routes that call the Cloud API on request.
+     * @returns The client.
+     * @throws AdminRequestError 404 when no token is configured.
+     */
+    private requireClient;
+    /**
+     * The application the page shows, from the stored choice.
+     * @returns The application.
+     * @throws AdminRequestError 404 while none is chosen (D9).
+     */
+    private requireApplication;
+    /**
+     * Reads a stored resource snapshot.
+     * @param resource The resource.
+     * @returns The snapshot, or null before its first attempt.
+     */
+    private readSnapshot;
+    /**
+     * Stores a resource snapshot (last writer wins: only the leader refreshes).
+     * @param resource The resource.
+     * @param snapshot The snapshot.
+     */
+    private writeSnapshot;
+    /**
+     * A per-application part (history or billing): empty while no application is chosen (D9).
+     * @param resource The resource.
+     * @returns The part.
+     * @throws AdminRequestError 404 when no token is configured.
+     */
+    private readApplicationPart;
+    /**
+     * GET cloud while no token is configured: the feature with empty parts.
+     * @param nowMilliseconds The current clock time.
+     * @returns The summary view.
+     */
+    private emptySummary;
+    /**
+     * The route error of a failed deploy output request: 404 for an unknown deploy, 503 after a 429 (which also pauses
+     * the fleet), else 502.
+     * @param error What the request threw.
+     * @param nowMilliseconds The clock time of the request.
+     * @returns The route error.
+     * @throws The error itself when it is not a ColyseusCloudApiError.
+     */
+    private deployRequestError;
+    /**
+     * Reads the fleet-wide log gate.
+     * @returns The gate document, or null before the first log request.
+     */
+    private readLogGate;
+    /**
+     * Claims the next log request for this process through the gate's revision, so two processes never both send one.
+     * @param gate The gate as read, or null when none exists yet.
+     * @param nowMilliseconds The current clock time.
+     * @returns True when claimed; false when another process claimed it first.
+     */
+    private claimLogGate;
+    /**
+     * While the gate is closed: the last log answer when it is of the same instance, stream and lines and recent enough,
+     * else a 429 naming when the next request is allowed.
+     * @param instanceId The asked instance.
+     * @param stream The asked stream.
+     * @param lines The asked number of lines.
+     * @param nextAllowedMilliseconds When the next log request is allowed, in clock milliseconds.
+     * @param nowMilliseconds The current clock time.
+     * @returns The shared answer.
+     * @throws AdminRequestError 429 when there is nothing to share.
+     */
+    private sharedLogsOrRefusal;
+    /**
+     * Sends the claimed log request; on a Cloud error, honours its Retry-After in the gate and maps it to a route error.
+     * @param client The Cloud API client.
+     * @param slug The application slug.
+     * @param instanceId The instance.
+     * @param stream The stream.
+     * @param lines The number of lines.
+     * @param nowMilliseconds The clock time of the request.
+     * @returns The log text.
+     * @throws AdminRequestError 409 when the instance is not running, 429 when Colyseus refused, else 502.
+     */
+    private fetchLogs;
+}

package/lib/admin/ColyseusCloudService.js

@@ -0,0 +1,476 @@
+// The cache behind the console's Colyseus Cloud page (colyseus-cloud-console D2–D5, D9, D10, D17): the fleet leader
+// refreshes every Cloud API resource at Colyseus's own cadence into the admin store collection "colyseusCloud", and
+// every process's routes read that collection. Only deploy output and instance logs call the Cloud API on request,
+// under Colyseus's limits: deploy output is cached per process, logs are gated fleet-wide and shared.
+import { AdminRequestError } from "./AdminApiRouter.js";
+import { COLYSEUS_CLOUD_DEFAULT_RETRY_SECONDS, COLYSEUS_CLOUD_DEPLOY_DETAIL_CACHE_MS, COLYSEUS_CLOUD_DEPLOY_LIMIT, COLYSEUS_CLOUD_DUE_TOLERANCE_MS, COLYSEUS_CLOUD_LOG_INTERVAL_MS, COLYSEUS_CLOUD_REFRESH_SECONDS, COLYSEUS_CLOUD_SHARED_LOGS_MS, MILLISECONDS_PER_SECOND } from "./AdminConstants.js";
+import { AdminConflictError } from "./AdminStore.js";
+import { ColyseusCloudApiError, ColyseusCloudClient } from "./ColyseusCloudClient.js";
+import { colyseusCloudFeatureOf, ownHostNameOf } from "./ColyseusCloudSettings.js";
+import { partOf, resolveApplication, toBillingView, toDeployDetailView, toDeployView, toEgressView, toHistoryView, toLoadView } from "./ColyseusCloudViews.js";
+/** HTTP status when there is no token, no chosen application, or no such deploy or instance. */
+const HTTP_NOT_FOUND = 404;
+/** HTTP status when an instance is not running. */
+const HTTP_CONFLICT = 409;
+/** HTTP status when Colyseus's log limit allows no request yet. */
+const HTTP_TOO_MANY_REQUESTS = 429;
+/** HTTP status when Colyseus failed. */
+const HTTP_BAD_GATEWAY = 502;
+/** HTTP status while Colyseus asked to wait. */
+const HTTP_SERVICE_UNAVAILABLE = 503;
+/** The store collection of every Cloud document (D3). */
+const CLOUD_COLLECTION = "colyseusCloud";
+/** Store id of the fleet-wide pause after a Cloud 429 (D5). */
+const RATE_LIMIT_DOCUMENT_ID = "rateLimit";
+/** Store id of the fleet-wide log request gate (D5). */
+const LOG_GATE_DOCUMENT_ID = "logGate";
+/** Store id of the last log answer, shared with later askers (D5). */
+const LAST_LOGS_DOCUMENT_ID = "lastLogs";
+/**
+ * Refresh order after "applications": the live figures first (D4). Colyseus's 24-hour minute history is not read, because
+ * the console's own Metrics page already covers the last 24 hours.
+ */
+const RESOURCE_REFRESH_ORDER = ["metricsCurrent", "deploys", "egress", "metricsDay", "billing"];
+/** Message of a Cloud route while no application is chosen or no token is set (D9). */
+const NOT_CONFIGURED_MESSAGE = "no Colyseus Cloud application is available: set a Cloud API token and, if the team has several applications, the application slug";
+/** The leader-refreshed, store-shared cache of the Colyseus Cloud API behind the console's Colyseus Cloud page (D2–D5). */
+export class ColyseusCloudService {
+    /** Whether the page applies (D8). */
+    feature;
+    /** The admin services this cache reads the config, store and clock from. */
+    services;
+    /** Null unless a token is configured. */
+    client;
+    /** Host name of publicUrl, to mark this console's own instance (D11). */
+    ownHostName;
+    /** Deploy output this process fetched recently, by deploy id (D5). */
+    deployDetails = new Map();
+    /**
+     * Creates the cache; nothing is requested until the leader calls refreshDue or a route asks.
+     * @param services The admin core services (config, store, clock and the refresh test hook).
+     * @param environment The process environment (COLYSEUS_CLOUD marks Colyseus Cloud, D8).
+     */
+    constructor(services, environment = process.env) {
+        this.services = services;
+        this.feature = colyseusCloudFeatureOf(services.config, environment);
+        const settings = services.config.admin.colyseusCloud;
+        this.client = (settings.apiToken != null) ? new ColyseusCloudClient(settings.apiUrl, settings.apiToken) : null;
+        this.ownHostName = ownHostNameOf(services.config);
+    }
+    /** True when a Cloud API token is configured, so the leader refreshes and the routes answer. */
+    get isConfigured() {
+        return this.client != null;
+    }
+    /**
+     * One leader refresh pass (D3–D5): unless a Cloud 429 pauses the fleet, refreshes "applications" when due and then,
+     * once an application is chosen, every other due resource in RESOURCE_REFRESH_ORDER, stopping at the first 429.
+     * Always reports the pass to the colyseusCloudRefreshed hook (D17), early returns included.
+     */
+    async refreshDue() {
+        const now = this.services.clock.now();
+        try {
+            await this.refreshPass(now);
+        }
+        finally {
+            this.services.colyseusCloudRefreshed(now);
+        }
+    }
+    /**
+     * GET cloud: the feature, the application choice and the overview, load, deploys and egress parts (always answers).
+     * @returns The summary view.
+     */
+    async readSummary() {
+        const now = this.services.clock.now();
+        if (!this.isConfigured)
+            return this.emptySummary(now);
+        const choice = await this.readSnapshot("applications");
+        const overview = (choice != null) ? { ...choice, data: choice.data?.application ?? null } : null;
+        const choiceProblem = (choice?.data == null) ? choice?.problem ?? null : null;
+        return {
+            feature: this.feature,
+            applicationChoices: choice?.data?.choices ?? [],
+            setupProblem: choice?.data?.setupProblem ?? choiceProblem,
+            overview: partOf(overview, COLYSEUS_CLOUD_REFRESH_SECONDS.applications, now),
+            load: partOf(await this.readSnapshot("metricsCurrent"), COLYSEUS_CLOUD_REFRESH_SECONDS.metricsCurrent, now),
+            deploys: partOf(await this.readSnapshot("deploys"), COLYSEUS_CLOUD_REFRESH_SECONDS.deploys, now),
+            egress: partOf(await this.readSnapshot("egress"), COLYSEUS_CLOUD_REFRESH_SECONDS.egress, now)
+        };
+    }
+    /**
+     * GET cloud/history: the load history of the last 30 days, one point a day (an empty part while no application is
+     * chosen). The last 24 hours are the console's own Metrics page, so Colyseus's minute history is not read.
+     * @returns The history part.
+     * @throws AdminRequestError 404 when no token is configured.
+     */
+    async readHistory() {
+        return await this.readApplicationPart("metricsDay");
+    }
+    /**
+     * GET cloud/billing: the billing account and this application's subscription (an empty part while no application is chosen).
+     * @returns The billing part.
+     * @throws AdminRequestError 404 when no token is configured.
+     */
+    async readBilling() {
+        return await this.readApplicationPart("billing");
+    }
+    /**
+     * GET cloud/deploys/:deployId: one deploy with its output, fetched on request and reused by this process for
+     * COLYSEUS_CLOUD_DEPLOY_DETAIL_CACHE_MS (D5).
+     * @param deployId Colyseus's deploy id.
+     * @returns The deploy with its output.
+     * @throws AdminRequestError 404 without a token, an application or such a deploy; 503 while a Cloud 429 pauses the
+     *     fleet (detail: the ISO time it ends); 502 when Colyseus failed.
+     */
+    async readDeploy(deployId) {
+        const client = this.requireClient();
+        const application = await this.requireApplication();
+        const now = this.services.clock.now();
+        const cached = this.deployDetails.get(deployId);
+        if (cached != null && now - cached.fetchedAtMilliseconds < COLYSEUS_CLOUD_DEPLOY_DETAIL_CACHE_MS)
+            return cached.view;
+        const rateLimit = await this.services.store.getDocument(CLOUD_COLLECTION, RATE_LIMIT_DOCUMENT_ID);
+        if (rateLimit != null && Date.parse(rateLimit.value.blockedUntil) > now)
+            throw rateLimitedError(rateLimit.value.blockedUntil);
+        try {
+            const view = toDeployDetailView(await client.deploy(application.slug, deployId));
+            this.deployDetails.set(deployId, { view: view, fetchedAtMilliseconds: now });
+            return view;
+        }
+        catch (error) {
+            throw await this.deployRequestError(error, now);
+        }
+    }
+    /**
+     * GET cloud/instances/:instanceId/logs: an instance's newest log lines, at most one Cloud request per
+     * COLYSEUS_CLOUD_LOG_INTERVAL_MS for the whole fleet; another asker of the same instance, stream and lines within
+     * COLYSEUS_CLOUD_SHARED_LOGS_MS gets that answer (D5, D10).
+     * @param instanceId Colyseus's instance id.
+     * @param stream Which output stream to read.
+     * @param lines How many lines to read.
+     * @returns The logs.
+     * @throws AdminRequestError 404 without a token, an application or such an instance; 409 when the instance is not
+     *     running; 429 when the limit allows no request yet (detail: the next allowed ISO time); 502 when Colyseus failed.
+     */
+    async readLogs(instanceId, stream, lines) {
+        const client = this.requireClient();
+        const application = await this.requireApplication();
+        if (!hasInstance(application, instanceId))
+            throw new AdminRequestError(HTTP_NOT_FOUND, "no such instance in " + application.slug);
+        const now = this.services.clock.now();
+        const gate = await this.readLogGate();
+        const nextAllowed = (gate != null) ? Date.parse(gate.value.nextAllowedAt) : 0;
+        if (now < nextAllowed)
+            return await this.sharedLogsOrRefusal(instanceId, stream, lines, nextAllowed, now);
+        if (!(await this.claimLogGate(gate, now))) {
+            const claimedGate = await this.readLogGate();
+            const claimedNextAllowed = (claimedGate != null) ? Date.parse(claimedGate.value.nextAllowedAt) : now + COLYSEUS_CLOUD_LOG_INTERVAL_MS;
+            return await this.sharedLogsOrRefusal(instanceId, stream, lines, claimedNextAllowed, now);
+        }
+        const text = await this.fetchLogs(client, application.slug, instanceId, stream, lines, now);
+        const view = { instanceId: instanceId, stream: stream, lines: lines, text: text, fetchedAt: isoTimeOf(now), isShared: false, nextAllowedAt: isoTimeOf(now + COLYSEUS_CLOUD_LOG_INTERVAL_MS) };
+        await this.services.store.putDocument(CLOUD_COLLECTION, LAST_LOGS_DOCUMENT_ID, view, null);
+        return view;
+    }
+    /**
+     * The body of one refresh pass (§7 steps 1–5).
+     * @param now The clock time of the pass, in milliseconds.
+     */
+    async refreshPass(now) {
+        const client = this.client;
+        if (client == null)
+            return;
+        const rateLimit = await this.services.store.getDocument(CLOUD_COLLECTION, RATE_LIMIT_DOCUMENT_ID);
+        if (rateLimit != null && Date.parse(rateLimit.value.blockedUntil) > now)
+            return;
+        if (await this.isDue("applications", now)) {
+            const configuredSlug = this.services.config.admin.colyseusCloud.application;
+            const fetchChoice = async () => resolveApplication(await client.listApplications(), configuredSlug, this.ownHostName);
+            if (!(await this.refreshResource("applications", fetchChoice, now)))
+                return;
+        }
+        const choice = await this.readSnapshot("applications");
+        const application = choice?.data?.application ?? null;
+        if (application == null)
+            return;
+        for (const resource of RESOURCE_REFRESH_ORDER) {
+            if (!(await this.isDue(resource, now)))
+                continue;
+            const fetchData = () => fetchApplicationResource(client, resource, application.slug);
+            if (!(await this.refreshResource(resource, fetchData, now)))
+                return;
+        }
+    }
+    /**
+     * Whether a resource should be refreshed now: never attempted, its retryAt reached, or its refresh interval since
+     * the last attempt elapsed (each within COLYSEUS_CLOUD_DUE_TOLERANCE_MS, so a slightly early tick still counts).
+     * @param resource The resource.
+     * @param nowMilliseconds The clock time of the pass.
+     * @returns True when due.
+     */
+    async isDue(resource, nowMilliseconds) {
+        const snapshot = await this.readSnapshot(resource);
+        if (snapshot == null)
+            return true;
+        const toleratedNow = nowMilliseconds + COLYSEUS_CLOUD_DUE_TOLERANCE_MS;
+        if (snapshot.retryAt != null)
+            return toleratedNow >= Date.parse(snapshot.retryAt);
+        return toleratedNow >= Date.parse(snapshot.attemptedAt) + COLYSEUS_CLOUD_REFRESH_SECONDS[resource] * MILLISECONDS_PER_SECOND;
+    }
+    /**
+     * Fetches one resource and stores its snapshot: the new data on success; on a Cloud error the last good data with
+     * the problem and, for a 5xx or no answer, the retryAt Colyseus asked for. A 429 also pauses the fleet.
+     * @param resource The resource.
+     * @param fetchData Requests and converts the resource.
+     * @param nowMilliseconds The clock time of the pass.
+     * @returns False after a 429 (the pass must stop), else true.
+     * @throws Any error other than ColyseusCloudApiError (the leader logs it).
+     */
+    async refreshResource(resource, fetchData, nowMilliseconds) {
+        const previous = await this.readSnapshot(resource);
+        const attemptedAt = isoTimeOf(nowMilliseconds);
+        try {
+            const data = await fetchData();
+            await this.writeSnapshot(resource, { data: data, fetchedAt: attemptedAt, attemptedAt: attemptedAt, retryAt: null, problem: null });
+            return true;
+        }
+        catch (error) {
+            if (!(error instanceof ColyseusCloudApiError))
+                throw error;
+            const isRateLimited = error.status === HTTP_TOO_MANY_REQUESTS;
+            // A 429 pauses the whole fleet instead (rateLimit), so only a 5xx or no answer sets this resource's retryAt.
+            const retryAt = (!isRateLimited && error.retryAfterSeconds != null) ? isoTimeOf(nowMilliseconds + error.retryAfterSeconds * MILLISECONDS_PER_SECOND) : null;
+            await this.writeSnapshot(resource, { data: previous?.data ?? null, fetchedAt: previous?.fetchedAt ?? null, attemptedAt: attemptedAt, retryAt: retryAt, problem: error.toProblem() });
+            if (isRateLimited)
+                await this.writeRateLimit(error.retryAfterSeconds, nowMilliseconds);
+            return !isRateLimited;
+        }
+    }
+    /**
+     * Pauses every refresh of the fleet after a Cloud 429 until Colyseus's Retry-After (D5).
+     * @param retryAfterSeconds Colyseus's wait, or null for COLYSEUS_CLOUD_DEFAULT_RETRY_SECONDS.
+     * @param nowMilliseconds The current clock time.
+     * @returns The ISO time the pause ends.
+     */
+    async writeRateLimit(retryAfterSeconds, nowMilliseconds) {
+        const blockedUntil = isoTimeOf(nowMilliseconds + (retryAfterSeconds ?? COLYSEUS_CLOUD_DEFAULT_RETRY_SECONDS) * MILLISECONDS_PER_SECOND);
+        await this.services.store.putDocument(CLOUD_COLLECTION, RATE_LIMIT_DOCUMENT_ID, { blockedUntil: blockedUntil }, null);
+        return blockedUntil;
+    }
+    /**
+     * The client, for the routes that call the Cloud API on request.
+     * @returns The client.
+     * @throws AdminRequestError 404 when no token is configured.
+     */
+    requireClient() {
+        if (this.client == null)
+            throw new AdminRequestError(HTTP_NOT_FOUND, NOT_CONFIGURED_MESSAGE);
+        return this.client;
+    }
+    /**
+     * The application the page shows, from the stored choice.
+     * @returns The application.
+     * @throws AdminRequestError 404 while none is chosen (D9).
+     */
+    async requireApplication() {
+        const choice = await this.readSnapshot("applications");
+        const application = choice?.data?.application ?? null;
+        if (application == null)
+            throw new AdminRequestError(HTTP_NOT_FOUND, NOT_CONFIGURED_MESSAGE);
+        return application;
+    }
+    /**
+     * Reads a stored resource snapshot.
+     * @param resource The resource.
+     * @returns The snapshot, or null before its first attempt.
+     */
+    async readSnapshot(resource) {
+        const stored = await this.services.store.getDocument(CLOUD_COLLECTION, resource);
+        return stored?.value ?? null;
+    }
+    /**
+     * Stores a resource snapshot (last writer wins: only the leader refreshes).
+     * @param resource The resource.
+     * @param snapshot The snapshot.
+     */
+    async writeSnapshot(resource, snapshot) {
+        await this.services.store.putDocument(CLOUD_COLLECTION, resource, snapshot, null);
+    }
+    /**
+     * A per-application part (history or billing): empty while no application is chosen (D9).
+     * @param resource The resource.
+     * @returns The part.
+     * @throws AdminRequestError 404 when no token is configured.
+     */
+    async readApplicationPart(resource) {
+        this.requireClient();
+        const now = this.services.clock.now();
+        const choice = await this.readSnapshot("applications");
+        const snapshot = (choice?.data?.application != null) ? await this.readSnapshot(resource) : null;
+        return partOf(snapshot, COLYSEUS_CLOUD_REFRESH_SECONDS[resource], now);
+    }
+    /**
+     * GET cloud while no token is configured: the feature with empty parts.
+     * @param nowMilliseconds The current clock time.
+     * @returns The summary view.
+     */
+    emptySummary(nowMilliseconds) {
+        return {
+            feature: this.feature,
+            applicationChoices: [],
+            setupProblem: null,
+            overview: partOf(null, COLYSEUS_CLOUD_REFRESH_SECONDS.applications, nowMilliseconds),
+            load: partOf(null, COLYSEUS_CLOUD_REFRESH_SECONDS.metricsCurrent, nowMilliseconds),
+            deploys: partOf(null, COLYSEUS_CLOUD_REFRESH_SECONDS.deploys, nowMilliseconds),
+            egress: partOf(null, COLYSEUS_CLOUD_REFRESH_SECONDS.egress, nowMilliseconds)
+        };
+    }
+    /**
+     * The route error of a failed deploy output request: 404 for an unknown deploy, 503 after a 429 (which also pauses
+     * the fleet), else 502.
+     * @param error What the request threw.
+     * @param nowMilliseconds The clock time of the request.
+     * @returns The route error.
+     * @throws The error itself when it is not a ColyseusCloudApiError.
+     */
+    async deployRequestError(error, nowMilliseconds) {
+        if (!(error instanceof ColyseusCloudApiError))
+            throw error;
+        if (error.status === HTTP_NOT_FOUND)
+            return new AdminRequestError(HTTP_NOT_FOUND, "no such deploy");
+        if (error.status === HTTP_TOO_MANY_REQUESTS)
+            return rateLimitedError(await this.writeRateLimit(error.retryAfterSeconds, nowMilliseconds));
+        return new AdminRequestError(HTTP_BAD_GATEWAY, "Colyseus Cloud: " + error.message, error.code);
+    }
+    /**
+     * Reads the fleet-wide log gate.
+     * @returns The gate document, or null before the first log request.
+     */
+    async readLogGate() {
+        return await this.services.store.getDocument(CLOUD_COLLECTION, LOG_GATE_DOCUMENT_ID);
+    }
+    /**
+     * Claims the next log request for this process through the gate's revision, so two processes never both send one.
+     * @param gate The gate as read, or null when none exists yet.
+     * @param nowMilliseconds The current clock time.
+     * @returns True when claimed; false when another process claimed it first.
+     */
+    async claimLogGate(gate, nowMilliseconds) {
+        const claim = { nextAllowedAt: isoTimeOf(nowMilliseconds + COLYSEUS_CLOUD_LOG_INTERVAL_MS) };
+        try {
+            await this.services.store.putDocument(CLOUD_COLLECTION, LOG_GATE_DOCUMENT_ID, claim, gate?.revision ?? 0);
+            return true;
+        }
+        catch (error) {
+            if (error instanceof AdminConflictError)
+                return false;
+            throw error;
+        }
+    }
+    /**
+     * While the gate is closed: the last log answer when it is of the same instance, stream and lines and recent enough,
+     * else a 429 naming when the next request is allowed.
+     * @param instanceId The asked instance.
+     * @param stream The asked stream.
+     * @param lines The asked number of lines.
+     * @param nextAllowedMilliseconds When the next log request is allowed, in clock milliseconds.
+     * @param nowMilliseconds The current clock time.
+     * @returns The shared answer.
+     * @throws AdminRequestError 429 when there is nothing to share.
+     */
+    async sharedLogsOrRefusal(instanceId, stream, lines, nextAllowedMilliseconds, nowMilliseconds) {
+        const nextAllowedAt = isoTimeOf(nextAllowedMilliseconds);
+        const last = await this.services.store.getDocument(CLOUD_COLLECTION, LAST_LOGS_DOCUMENT_ID);
+        const isSameRequest = last != null && last.value.instanceId === instanceId && last.value.stream === stream && last.value.lines === lines;
+        if (last != null && isSameRequest && nowMilliseconds - Date.parse(last.value.fetchedAt) < COLYSEUS_CLOUD_SHARED_LOGS_MS) {
+            return { ...last.value, isShared: true, nextAllowedAt: nextAllowedAt };
+        }
+        throw new AdminRequestError(HTTP_TOO_MANY_REQUESTS, "Colyseus Cloud allows two log requests a minute. Ask again after " + nextAllowedAt + ".", nextAllowedAt);
+    }
+    /**
+     * Sends the claimed log request; on a Cloud error, honours its Retry-After in the gate and maps it to a route error.
+     * @param client The Cloud API client.
+     * @param slug The application slug.
+     * @param instanceId The instance.
+     * @param stream The stream.
+     * @param lines The number of lines.
+     * @param nowMilliseconds The clock time of the request.
+     * @returns The log text.
+     * @throws AdminRequestError 409 when the instance is not running, 429 when Colyseus refused, else 502.
+     */
+    async fetchLogs(client, slug, instanceId, stream, lines, nowMilliseconds) {
+        try {
+            return await client.instanceLogs(slug, instanceId, stream, lines);
+        }
+        catch (error) {
+            if (!(error instanceof ColyseusCloudApiError))
+                throw error;
+            if (error.retryAfterSeconds != null) {
+                const reopenedGate = { nextAllowedAt: isoTimeOf(nowMilliseconds + error.retryAfterSeconds * MILLISECONDS_PER_SECOND) };
+                await this.services.store.putDocument(CLOUD_COLLECTION, LOG_GATE_DOCUMENT_ID, reopenedGate, null);
+            }
+            throw logRequestError(error, nowMilliseconds);
+        }
+    }
+}
+/**
+ * Requests and converts one per-application resource (§7 step 5).
+ * @param client The Cloud API client.
+ * @param resource The resource.
+ * @param slug The application slug.
+ * @returns The converted data of the resource's snapshot.
+ * @throws ColyseusCloudApiError on a failed or missing answer.
+ */
+async function fetchApplicationResource(client, resource, slug) {
+    switch (resource) {
+        case "metricsCurrent":
+            return toLoadView(await client.currentMetrics(slug));
+        case "deploys":
+            return (await client.deploys(slug, COLYSEUS_CLOUD_DEPLOY_LIMIT)).map(toDeployView);
+        case "egress":
+            return toEgressView(await client.egress(slug));
+        case "metricsDay":
+            return toHistoryView(await client.metricsHistory(slug, "day"));
+        case "billing":
+            return toBillingView(await client.billing(), slug);
+    }
+}
+/**
+ * Whether an application has an instance in any of its locations.
+ * @param application The application.
+ * @param instanceId Colyseus's instance id.
+ * @returns True when one of its locations lists the instance.
+ */
+function hasInstance(application, instanceId) {
+    return application.locations.some((location) => location.instances.some((instance) => instance.id === instanceId));
+}
+/**
+ * The 503 of deploy output while a Cloud 429 pauses the fleet.
+ * @param blockedUntil When the pause ends (ISO).
+ * @returns The route error, its detail the end of the pause.
+ */
+function rateLimitedError(blockedUntil) {
+    return new AdminRequestError(HTTP_SERVICE_UNAVAILABLE, "Colyseus Cloud asked to wait. Try again after " + blockedUntil + ".", blockedUntil);
+}
+/**
+ * The route error of a failed log request.
+ * @param error The Cloud error.
+ * @param nowMilliseconds The clock time of the request.
+ * @returns 409 when the instance is not running, 429 (detail: when to ask again) when Colyseus refused, else 502.
+ */
+function logRequestError(error, nowMilliseconds) {
+    if (error.status === HTTP_CONFLICT)
+        return new AdminRequestError(HTTP_CONFLICT, "The instance is not running, so its logs cannot be read.", error.code);
+    if (error.status === HTTP_TOO_MANY_REQUESTS) {
+        const retryAt = isoTimeOf(nowMilliseconds + (error.retryAfterSeconds ?? COLYSEUS_CLOUD_DEFAULT_RETRY_SECONDS) * MILLISECONDS_PER_SECOND);
+        return new AdminRequestError(HTTP_TOO_MANY_REQUESTS, error.message, retryAt);
+    }
+    return new AdminRequestError(HTTP_BAD_GATEWAY, "Colyseus Cloud: " + error.message, error.code);
+}
+/**
+ * An ISO time from clock milliseconds.
+ * @param milliseconds Milliseconds since the Unix epoch.
+ * @returns The ISO time.
+ */
+function isoTimeOf(milliseconds) {
+    return new Date(milliseconds).toISOString();
+}

package/lib/admin/ColyseusCloudSettings.d.ts

@@ -0,0 +1,16 @@
+import { type GameServerConfig } from "../GameServerConfig.js";
+import type { ColyseusCloudFeature } from "./AdminApiTypes.js";
+/**
+ * Whether the console's Colyseus Cloud page applies to this server (colyseus-cloud-console D8): "configured" when a
+ * Cloud API token is set, "setupNeeded" on Colyseus Cloud without one (the page explains how to add it), else "off".
+ * @param config The resolved server config.
+ * @param environment The process environment (COLYSEUS_CLOUD is set only on Colyseus Cloud).
+ * @returns The feature state.
+ */
+export declare function colyseusCloudFeatureOf(config: GameServerConfig, environment: NodeJS.ProcessEnv): ColyseusCloudFeature;
+/**
+ * The host name players reach this server at, from publicUrl, used to mark this console's own Cloud instance (D11).
+ * @param config The resolved server config.
+ * @returns The host name, or null when publicUrl is unset or not a URL.
+ */
+export declare function ownHostNameOf(config: GameServerConfig): string | null;