@babylonjs-toolkit/server 0.0.0-stage → 9.35.1

package/lib/admin/ColyseusCloudClient.d.ts

@@ -0,0 +1,313 @@
+import type { CloudHistoryResolution, CloudLogLines, CloudLogStream, CloudProblemView } from "./AdminApiTypes.js";
+/** A region of a Cloud location. */
+export interface CloudApiRegion {
+    code: string;
+    city: string;
+    country: string;
+}
+/** A location's plan. */
+export interface CloudApiPlan {
+    vcpus: number;
+    ram_mb: number;
+    transfer_gb: number;
+}
+/** An instance in GET /applications. */
+export interface CloudApiInstance {
+    id: number;
+    endpoint: string | null;
+    status: string;
+    deploy_status: string | null;
+    deployed_at: string | null;
+}
+/** A location in GET /applications. */
+export interface CloudApiLocation {
+    id: number;
+    region: CloudApiRegion;
+    status: string;
+    scale_strategy: string;
+    endpoint: string | null;
+    plan: CloudApiPlan;
+    instances: CloudApiInstance[];
+}
+/** An application in GET /applications. */
+export interface CloudApiApplication {
+    id: number;
+    slug: string;
+    name: string;
+    maintenance_mode: boolean;
+    created_at: string;
+    locations: CloudApiLocation[];
+}
+/** Load figures of a total or a history point. */
+export interface CloudApiTotals {
+    ccu: number;
+    rooms: number;
+    cpu_percent: number;
+    memory_percent: number;
+}
+/** A process in GET /metrics/current. */
+export interface CloudApiProcess {
+    id: number;
+    status: string;
+    started_at: string | null;
+    restarts: number;
+    cpu_percent: number;
+    memory_mb: number;
+    ccu: number;
+    rooms: number;
+    node_version: string;
+}
+/** An instance sample in GET /metrics/current (values null when silent). */
+export interface CloudApiInstanceSample {
+    id: number;
+    sampled_at: string | null;
+    ccu: number | null;
+    rooms: number | null;
+    cpu_percent: number | null;
+    memory_percent: number | null;
+    processes: CloudApiProcess[];
+}
+/** A location in GET /metrics/current. */
+export interface CloudApiLocationMetrics {
+    id: number;
+    region: string;
+    totals: CloudApiTotals | null;
+    instances: CloudApiInstanceSample[];
+}
+/** GET /applications/{slug}/metrics/current. */
+export interface CloudApiCurrentMetrics {
+    application: string;
+    window_minutes: number;
+    locations: CloudApiLocationMetrics[];
+}
+/** A point in GET /metrics. */
+export interface CloudApiHistoryPoint extends CloudApiTotals {
+    time: string;
+}
+/** A location in GET /metrics. */
+export interface CloudApiLocationHistory {
+    id: number;
+    region: string;
+    points: CloudApiHistoryPoint[];
+}
+/** GET /applications/{slug}/metrics. */
+export interface CloudApiHistory {
+    application: string;
+    resolution: CloudHistoryResolution;
+    from: string;
+    to: string;
+    locations: CloudApiLocationHistory[];
+}
+/** A day in GET /egress. */
+export interface CloudApiEgressDay {
+    date: string;
+    outgoing_bytes: number;
+    incoming_bytes: number;
+}
+/** A location in GET /egress. */
+export interface CloudApiLocationEgress {
+    id: number;
+    region: string;
+    outgoing_bytes: number;
+    incoming_bytes: number;
+    days: CloudApiEgressDay[];
+}
+/** GET /applications/{slug}/egress. */
+export interface CloudApiEgress {
+    application: string;
+    from: string;
+    to: string;
+    collected_at: string | null;
+    locations: CloudApiLocationEgress[];
+}
+/** A deploy in GET /deploys. */
+export interface CloudApiDeploy {
+    id: number;
+    status: string;
+    branch: string;
+    commit: string | null;
+    message: string | null;
+    started_at: string;
+    finished_at: string | null;
+}
+/** GET /deploys/{id} data. */
+export interface CloudApiDeployDetail extends CloudApiDeploy {
+    output: string | null;
+}
+/** The billing account in GET /billing. */
+export interface CloudApiAccount {
+    currency: string;
+    credit_balance: number;
+    balance_due: number;
+    unused_time_credit: number;
+}
+/** A subscription in GET /billing. */
+export interface CloudApiSubscription {
+    status: string;
+    monthly_price: number;
+    current_period_end: string;
+    cancel_at_period_end: boolean;
+}
+/** An application in GET /billing. */
+export interface CloudApiBillingApplication {
+    id: number;
+    slug: string;
+    name: string;
+    subscription: CloudApiSubscription | null;
+}
+/** GET /billing. */
+export interface CloudApiBilling {
+    account: CloudApiAccount | null;
+    applications: CloudApiBillingApplication[];
+    fetched_at: string;
+}
+/** A Colyseus Cloud API failure: a non-2xx answer (plain-text proxy errors included) or no answer at all. */
+export declare class ColyseusCloudApiError extends Error {
+    /** HTTP status, or 0 when Colyseus did not answer. */
+    readonly status: number;
+    /** Colyseus's error code, or one derived from the status ("rate_limited", "unavailable", "server_error", "invalid_request", "unreachable"). */
+    readonly code: string;
+    /** Seconds to wait before retrying (429, 5xx and no answer), or null when retrying sooner will not help. */
+    readonly retryAfterSeconds: number | null;
+    /**
+     * Creates the error.
+     * @param status HTTP status, or 0 for no answer.
+     * @param code Stable error code.
+     * @param message Human-readable explanation (never contains the token).
+     * @param retryAfterSeconds Seconds to wait, or null.
+     */
+    constructor(status: number, code: string, message: string, retryAfterSeconds: number | null);
+    /**
+     * The error as the console shows it.
+     * @returns The problem view.
+     */
+    toProblem(): CloudProblemView;
+}
+/**
+ * Seconds to wait after a failed answer (Colyseus's polling guide): Retry-After for 429 and 5xx, at least
+ * COLYSEUS_CLOUD_MIN_RETRY_SECONDS, COLYSEUS_CLOUD_DEFAULT_RETRY_SECONDS when missing or not a number; null otherwise.
+ * @param status The HTTP status.
+ * @param retryAfterHeader The Retry-After header, or null.
+ * @returns Seconds, or null.
+ */
+export declare function retryAfterSecondsOf(status: number, retryAfterHeader: string | null): number | null;
+/**
+ * The error of a non-2xx answer: Colyseus's JSON code and message when present, else the plain text with a code from
+ * the status (429 "rate_limited", 502/503/504 "unavailable", other 5xx "server_error", else "invalid_request").
+ * @param response The failed answer.
+ * @returns The error.
+ */
+export declare function cloudErrorOf(response: Response): Promise<ColyseusCloudApiError>;
+/** Reads the Colyseus Cloud API with a team API token (read-only, GET only). */
+export declare class ColyseusCloudClient {
+    /** Base URL without a trailing slash. */
+    private readonly baseUrl;
+    /** The team API token, sent as a Bearer token and never logged. */
+    private readonly apiToken;
+    /** Request timeout, in milliseconds. */
+    private readonly timeoutMs;
+    /**
+     * Creates a client.
+     * @param apiUrl The API base URL (config admin.colyseusCloud.apiUrl).
+     * @param apiToken The team API token.
+     * @param timeoutMs Request timeout in milliseconds.
+     */
+    constructor(apiUrl: string, apiToken: string, timeoutMs?: number);
+    /**
+     * GET /applications: the team's applications with their locations and instances.
+     * @returns The applications.
+     * @throws ColyseusCloudApiError on a failed or missing answer.
+     */
+    listApplications(): Promise<CloudApiApplication[]>;
+    /**
+     * GET /applications/{slug}/metrics/current: the latest sample of every location, instance and process.
+     * @param slug The application slug.
+     * @returns The current metrics.
+     * @throws ColyseusCloudApiError on a failed or missing answer.
+     */
+    currentMetrics(slug: string): Promise<CloudApiCurrentMetrics>;
+    /**
+     * GET /applications/{slug}/metrics: the load history of every location.
+     * @param slug The application slug.
+     * @param resolution "minute" (last 24 hours) or "day" (last 30 days).
+     * @returns The history.
+     * @throws ColyseusCloudApiError on a failed or missing answer.
+     */
+    metricsHistory(slug: string, resolution: CloudHistoryResolution): Promise<CloudApiHistory>;
+    /**
+     * GET /applications/{slug}/egress: the traffic of the last 30 days per location and day.
+     * @param slug The application slug.
+     * @returns The traffic.
+     * @throws ColyseusCloudApiError on a failed or missing answer.
+     */
+    egress(slug: string): Promise<CloudApiEgress>;
+    /**
+     * GET /applications/{slug}/deploys: the most recent deploys, newest first.
+     * @param slug The application slug.
+     * @param limit How many deploys to read.
+     * @returns The deploys.
+     * @throws ColyseusCloudApiError on a failed or missing answer.
+     */
+    deploys(slug: string, limit: number): Promise<CloudApiDeploy[]>;
+    /**
+     * GET /applications/{slug}/deploys/{deployId}: one deploy with its build and deploy output.
+     * @param slug The application slug.
+     * @param deployId Colyseus's deploy id.
+     * @returns The deploy with its output.
+     * @throws ColyseusCloudApiError on a failed or missing answer.
+     */
+    deploy(slug: string, deployId: number): Promise<CloudApiDeployDetail>;
+    /**
+     * GET /billing: the team owner's billing account and every application's subscription.
+     * @returns The billing figures.
+     * @throws ColyseusCloudApiError on a failed or missing answer.
+     */
+    billing(): Promise<CloudApiBilling>;
+    /**
+     * GET /applications/{slug}/instances/{instanceId}/logs: the newest log lines of one instance as plain text.
+     * @param slug The application slug.
+     * @param instanceId Colyseus's instance id.
+     * @param stream Which output stream to read.
+     * @param lines How many lines to read.
+     * @returns The log text.
+     * @throws ColyseusCloudApiError on a failed or missing answer.
+     */
+    instanceLogs(slug: string, instanceId: number, stream: CloudLogStream, lines: CloudLogLines): Promise<string>;
+    /**
+     * The path of one application, with its slug encoded.
+     * @param slug The application slug.
+     * @returns "/applications/{slug}".
+     */
+    private applicationPath;
+    /**
+     * Removes the token from a text before it becomes an error message: fetch rejects a token with an invalid header
+     * character (such as a newline from a multi-line .env value) with an error that quotes the whole Authorization value.
+     * @param text The text, e.g. fetch's error message.
+     * @returns The text with every occurrence of the token replaced by REDACTED_TOKEN.
+     */
+    private withoutToken;
+    /**
+     * GETs a JSON answer.
+     * @param path The path after the base URL.
+     * @param query Query parameters (empty object: none).
+     * @returns The parsed body.
+     * @throws ColyseusCloudApiError on a failed or missing answer.
+     */
+    private requestJson;
+    /**
+     * GETs a plain-text answer.
+     * @param path The path after the base URL.
+     * @param query Query parameters.
+     * @returns The text.
+     * @throws ColyseusCloudApiError on a failed or missing answer.
+     */
+    private requestText;
+    /**
+     * Sends one GET with the token and the timeout.
+     * @param path The path after the base URL.
+     * @param query Query parameters.
+     * @returns The successful answer.
+     * @throws ColyseusCloudApiError on a non-2xx answer or no answer.
+     */
+    private send;
+}

package/lib/admin/ColyseusCloudClient.js

@@ -0,0 +1,272 @@
+// Read-only client of the Colyseus Cloud API behind the console's Colyseus Cloud page (colyseus-cloud-console D2, D5).
+// It knows HTTP and Colyseus's raw shapes only; ColyseusCloudViews converts them and ColyseusCloudService times them.
+import { COLYSEUS_CLOUD_DEFAULT_RETRY_SECONDS, COLYSEUS_CLOUD_MIN_RETRY_SECONDS, COLYSEUS_CLOUD_TIMEOUT_MS } from "./AdminConstants.js";
+/** HTTP status of a rate-limited answer. */
+const HTTP_TOO_MANY_REQUESTS = 429;
+/** First HTTP status of a server error. */
+const HTTP_SERVER_ERROR_START = 500;
+/** HTTP statuses of a gateway that could not reach Colyseus. */
+const GATEWAY_STATUSES = new Set([502, 503, 504]);
+/** What replaces the token in an error message (fetch echoes an invalid Authorization value in its error, D2). */
+const REDACTED_TOKEN = "[redacted]";
+/** A Colyseus Cloud API failure: a non-2xx answer (plain-text proxy errors included) or no answer at all. */
+export class ColyseusCloudApiError extends Error {
+    /** HTTP status, or 0 when Colyseus did not answer. */
+    status;
+    /** Colyseus's error code, or one derived from the status ("rate_limited", "unavailable", "server_error", "invalid_request", "unreachable"). */
+    code;
+    /** Seconds to wait before retrying (429, 5xx and no answer), or null when retrying sooner will not help. */
+    retryAfterSeconds;
+    /**
+     * Creates the error.
+     * @param status HTTP status, or 0 for no answer.
+     * @param code Stable error code.
+     * @param message Human-readable explanation (never contains the token).
+     * @param retryAfterSeconds Seconds to wait, or null.
+     */
+    constructor(status, code, message, retryAfterSeconds) {
+        super(message);
+        this.name = "ColyseusCloudApiError";
+        this.status = status;
+        this.code = code;
+        this.retryAfterSeconds = retryAfterSeconds;
+    }
+    /**
+     * The error as the console shows it.
+     * @returns The problem view.
+     */
+    toProblem() {
+        return { status: this.status, code: this.code, message: this.message };
+    }
+}
+/**
+ * Whether a parsed JSON value is Colyseus's error body.
+ * @param value The parsed body.
+ * @returns True for { error: { code: string, message: string } }.
+ */
+function isCloudApiErrorBody(value) {
+    if (typeof value !== "object" || value == null)
+        return false;
+    const error = value.error;
+    if (typeof error !== "object" || error == null)
+        return false;
+    const fields = error;
+    return typeof fields.code === "string" && typeof fields.message === "string";
+}
+/**
+ * Seconds to wait after a failed answer (Colyseus's polling guide): Retry-After for 429 and 5xx, at least
+ * COLYSEUS_CLOUD_MIN_RETRY_SECONDS, COLYSEUS_CLOUD_DEFAULT_RETRY_SECONDS when missing or not a number; null otherwise.
+ * @param status The HTTP status.
+ * @param retryAfterHeader The Retry-After header, or null.
+ * @returns Seconds, or null.
+ */
+export function retryAfterSecondsOf(status, retryAfterHeader) {
+    if (status !== HTTP_TOO_MANY_REQUESTS && status < HTTP_SERVER_ERROR_START)
+        return null;
+    const headerSeconds = Number(retryAfterHeader);
+    const seconds = (Number.isFinite(headerSeconds) && headerSeconds > 0) ? headerSeconds : COLYSEUS_CLOUD_DEFAULT_RETRY_SECONDS;
+    return Math.max(COLYSEUS_CLOUD_MIN_RETRY_SECONDS, seconds);
+}
+/**
+ * The error code of a failed answer that carries no Colyseus error body, derived from its status.
+ * @param status The HTTP status.
+ * @returns "rate_limited" for 429, "unavailable" for 502/503/504, "server_error" for another 5xx, else "invalid_request".
+ */
+function errorCodeOfStatus(status) {
+    if (status === HTTP_TOO_MANY_REQUESTS)
+        return "rate_limited";
+    if (GATEWAY_STATUSES.has(status))
+        return "unavailable";
+    if (status >= HTTP_SERVER_ERROR_START)
+        return "server_error";
+    return "invalid_request";
+}
+/**
+ * Parses a body as JSON without throwing.
+ * @param text The body text.
+ * @returns The parsed value, or undefined when the text is not JSON (a plain-text proxy answer).
+ */
+function parseJsonOrUndefined(text) {
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * The error of a non-2xx answer: Colyseus's JSON code and message when present, else the plain text with a code from
+ * the status (429 "rate_limited", 502/503/504 "unavailable", other 5xx "server_error", else "invalid_request").
+ * @param response The failed answer.
+ * @returns The error.
+ */
+export async function cloudErrorOf(response) {
+    const status = response.status;
+    const retryAfterSeconds = retryAfterSecondsOf(status, response.headers.get("retry-after"));
+    const text = await response.text().catch(() => "");
+    const body = parseJsonOrUndefined(text);
+    if (isCloudApiErrorBody(body))
+        return new ColyseusCloudApiError(status, body.error.code, body.error.message, retryAfterSeconds);
+    const message = text.trim() || "Colyseus Cloud answered " + status;
+    return new ColyseusCloudApiError(status, errorCodeOfStatus(status), message, retryAfterSeconds);
+}
+/** Reads the Colyseus Cloud API with a team API token (read-only, GET only). */
+export class ColyseusCloudClient {
+    /** Base URL without a trailing slash. */
+    baseUrl;
+    /** The team API token, sent as a Bearer token and never logged. */
+    apiToken;
+    /** Request timeout, in milliseconds. */
+    timeoutMs;
+    /**
+     * Creates a client.
+     * @param apiUrl The API base URL (config admin.colyseusCloud.apiUrl).
+     * @param apiToken The team API token.
+     * @param timeoutMs Request timeout in milliseconds.
+     */
+    constructor(apiUrl, apiToken, timeoutMs = COLYSEUS_CLOUD_TIMEOUT_MS) {
+        this.baseUrl = apiUrl.replace(/\/+$/, "");
+        this.apiToken = apiToken;
+        this.timeoutMs = timeoutMs;
+    }
+    /**
+     * GET /applications: the team's applications with their locations and instances.
+     * @returns The applications.
+     * @throws ColyseusCloudApiError on a failed or missing answer.
+     */
+    async listApplications() {
+        return (await this.requestJson("/applications", {})).data;
+    }
+    /**
+     * GET /applications/{slug}/metrics/current: the latest sample of every location, instance and process.
+     * @param slug The application slug.
+     * @returns The current metrics.
+     * @throws ColyseusCloudApiError on a failed or missing answer.
+     */
+    async currentMetrics(slug) {
+        return await this.requestJson(this.applicationPath(slug) + "/metrics/current", {});
+    }
+    /**
+     * GET /applications/{slug}/metrics: the load history of every location.
+     * @param slug The application slug.
+     * @param resolution "minute" (last 24 hours) or "day" (last 30 days).
+     * @returns The history.
+     * @throws ColyseusCloudApiError on a failed or missing answer.
+     */
+    async metricsHistory(slug, resolution) {
+        return await this.requestJson(this.applicationPath(slug) + "/metrics", { resolution: resolution });
+    }
+    /**
+     * GET /applications/{slug}/egress: the traffic of the last 30 days per location and day.
+     * @param slug The application slug.
+     * @returns The traffic.
+     * @throws ColyseusCloudApiError on a failed or missing answer.
+     */
+    async egress(slug) {
+        return await this.requestJson(this.applicationPath(slug) + "/egress", {});
+    }
+    /**
+     * GET /applications/{slug}/deploys: the most recent deploys, newest first.
+     * @param slug The application slug.
+     * @param limit How many deploys to read.
+     * @returns The deploys.
+     * @throws ColyseusCloudApiError on a failed or missing answer.
+     */
+    async deploys(slug, limit) {
+        return (await this.requestJson(this.applicationPath(slug) + "/deploys", { limit: String(limit) })).data;
+    }
+    /**
+     * GET /applications/{slug}/deploys/{deployId}: one deploy with its build and deploy output.
+     * @param slug The application slug.
+     * @param deployId Colyseus's deploy id.
+     * @returns The deploy with its output.
+     * @throws ColyseusCloudApiError on a failed or missing answer.
+     */
+    async deploy(slug, deployId) {
+        return (await this.requestJson(this.applicationPath(slug) + "/deploys/" + deployId, {})).data;
+    }
+    /**
+     * GET /billing: the team owner's billing account and every application's subscription.
+     * @returns The billing figures.
+     * @throws ColyseusCloudApiError on a failed or missing answer.
+     */
+    async billing() {
+        return await this.requestJson("/billing", {});
+    }
+    /**
+     * GET /applications/{slug}/instances/{instanceId}/logs: the newest log lines of one instance as plain text.
+     * @param slug The application slug.
+     * @param instanceId Colyseus's instance id.
+     * @param stream Which output stream to read.
+     * @param lines How many lines to read.
+     * @returns The log text.
+     * @throws ColyseusCloudApiError on a failed or missing answer.
+     */
+    async instanceLogs(slug, instanceId, stream, lines) {
+        const path = this.applicationPath(slug) + "/instances/" + instanceId + "/logs";
+        return await this.requestText(path, { stream: stream, lines: String(lines) });
+    }
+    /**
+     * The path of one application, with its slug encoded.
+     * @param slug The application slug.
+     * @returns "/applications/{slug}".
+     */
+    applicationPath(slug) {
+        return "/applications/" + encodeURIComponent(slug);
+    }
+    /**
+     * Removes the token from a text before it becomes an error message: fetch rejects a token with an invalid header
+     * character (such as a newline from a multi-line .env value) with an error that quotes the whole Authorization value.
+     * @param text The text, e.g. fetch's error message.
+     * @returns The text with every occurrence of the token replaced by REDACTED_TOKEN.
+     */
+    withoutToken(text) {
+        if (this.apiToken === "")
+            return text;
+        return text.replaceAll(this.apiToken, REDACTED_TOKEN);
+    }
+    /**
+     * GETs a JSON answer.
+     * @param path The path after the base URL.
+     * @param query Query parameters (empty object: none).
+     * @returns The parsed body.
+     * @throws ColyseusCloudApiError on a failed or missing answer.
+     */
+    async requestJson(path, query) {
+        const response = await this.send(path, query);
+        return await response.json();
+    }
+    /**
+     * GETs a plain-text answer.
+     * @param path The path after the base URL.
+     * @param query Query parameters.
+     * @returns The text.
+     * @throws ColyseusCloudApiError on a failed or missing answer.
+     */
+    async requestText(path, query) {
+        const response = await this.send(path, query);
+        return await response.text();
+    }
+    /**
+     * Sends one GET with the token and the timeout.
+     * @param path The path after the base URL.
+     * @param query Query parameters.
+     * @returns The successful answer.
+     * @throws ColyseusCloudApiError on a non-2xx answer or no answer.
+     */
+    async send(path, query) {
+        const queryText = new URLSearchParams(query).toString();
+        const url = this.baseUrl + path + (queryText === "" ? "" : "?" + queryText);
+        let response;
+        try {
+            response = await fetch(url, { method: "GET", headers: { authorization: "Bearer " + this.apiToken, accept: "application/json" }, signal: AbortSignal.timeout(this.timeoutMs) });
+        }
+        catch (error) {
+            const reason = this.withoutToken((error instanceof Error) ? error.message : String(error));
+            throw new ColyseusCloudApiError(0, "unreachable", "Colyseus Cloud did not answer: " + reason, COLYSEUS_CLOUD_DEFAULT_RETRY_SECONDS);
+        }
+        if (!response.ok)
+            throw await cloudErrorOf(response);
+        return response;
+    }
+}

package/lib/admin/ColyseusCloudRoutes.d.ts

@@ -0,0 +1,8 @@
+import { type AdminApiRouter } from "./AdminApiRouter.js";
+import type { AdminServices } from "./AdminServices.js";
+/**
+ * Registers the five Colyseus Cloud routes.
+ * @param router The admin API router.
+ * @param services The shared services.
+ */
+export declare function registerColyseusCloudRoutes(router: AdminApiRouter, services: AdminServices): void;

package/lib/admin/ColyseusCloudRoutes.js

@@ -0,0 +1,91 @@
+// The Colyseus Cloud page's routes (colyseus-cloud-console D7, D9, D10): the summary, the load history, billing,
+// deploy output and instance logs. Every route reads ColyseusCloudService; only deploy output and logs reach the Cloud
+// API, on request. All are reads: no step-up, no audit entry, API keys allowed.
+import { AdminRequestError } from "./AdminApiRouter.js";
+/** HTTP status of a successful read. */
+const HTTP_OK = 200;
+/** HTTP status of an invalid id or query. */
+const HTTP_BAD_REQUEST = 400;
+/** HTTP status of a route parameter that is missing (the router always fills matched ones). */
+const HTTP_NOT_FOUND = 404;
+/** The number of log lines a request without `lines` reads. */
+const DEFAULT_LOG_LINES = 100;
+/** The numbers of log lines Colyseus serves. */
+const LOG_LINE_CHOICES = [100, 500];
+/** The log streams Colyseus serves. */
+const LOG_STREAMS = ["all", "out", "err"];
+/** The stream a log request without `stream` reads. */
+const DEFAULT_LOG_STREAM = "all";
+/** A positive whole number without leading zeros. */
+const POSITIVE_ID_PATTERN = /^[1-9][0-9]*$/;
+/**
+ * Registers the five Colyseus Cloud routes.
+ * @param router The admin API router.
+ * @param services The shared services.
+ */
+export function registerColyseusCloudRoutes(router, services) {
+    const routes = [
+        { method: "GET", pattern: "cloud", permission: "cloud.view", requiresStepUp: false, auditAction: null, handler: async () => ({ status: HTTP_OK, body: await services.colyseusCloud.readSummary() }) },
+        { method: "GET", pattern: "cloud/history", permission: "cloud.view", requiresStepUp: false, auditAction: null, handler: async (request) => ({ status: HTTP_OK, body: await services.colyseusCloud.readHistory() }) },
+        { method: "GET", pattern: "cloud/billing", permission: "cloud.billing", requiresStepUp: false, auditAction: null, handler: async () => ({ status: HTTP_OK, body: await services.colyseusCloud.readBilling() }) },
+        { method: "GET", pattern: "cloud/deploys/:deployId", permission: "cloud.view", requiresStepUp: false, auditAction: null, handler: async (request) => ({ status: HTTP_OK, body: await services.colyseusCloud.readDeploy(positiveIdOf(request.params.deployId, "deployId")) }) },
+        { method: "GET", pattern: "cloud/instances/:instanceId/logs", permission: "logs.view", requiresStepUp: false, auditAction: null, handler: async (request) => ({ status: HTTP_OK, body: await readInstanceLogs(services, request) }) }
+    ];
+    for (const route of routes)
+        router.register(route);
+}
+/**
+ * GET cloud/instances/:instanceId/logs: validates the id, stream and lines, then reads the logs through the fleet gate.
+ * @param services The shared services.
+ * @param request The request (params instanceId; query stream, lines).
+ * @returns The logs view.
+ * @throws AdminRequestError 400 for an invalid id, stream or lines, or the service's refusals.
+ */
+async function readInstanceLogs(services, request) {
+    const instanceId = positiveIdOf(request.params.instanceId, "instanceId");
+    const stream = streamOf(request.query.get("stream"));
+    const lines = linesOf(request.query.get("lines"));
+    return await services.colyseusCloud.readLogs(instanceId, stream, lines);
+}
+/**
+ * A positive whole-number id of a route parameter.
+ * @param text The parameter value.
+ * @param name The parameter name, for the error message.
+ * @returns The id.
+ * @throws AdminRequestError 400 when it is not a positive whole number (404 when the parameter is missing).
+ */
+function positiveIdOf(text, name) {
+    if (text == null)
+        throw new AdminRequestError(HTTP_NOT_FOUND, name + " is missing");
+    if (!POSITIVE_ID_PATTERN.test(text))
+        throw new AdminRequestError(HTTP_BAD_REQUEST, name + " must be a positive whole number");
+    return Number(text);
+}
+/**
+ * The log stream of a query value.
+ * @param text The `stream` query value, or null.
+ * @returns "all" when empty, else the value.
+ * @throws AdminRequestError 400 for any other value.
+ */
+function streamOf(text) {
+    if (text == null || text === "")
+        return DEFAULT_LOG_STREAM;
+    const stream = LOG_STREAMS.find((candidate) => candidate === text);
+    if (stream == null)
+        throw new AdminRequestError(HTTP_BAD_REQUEST, "stream must be all, out or err");
+    return stream;
+}
+/**
+ * The number of log lines of a query value.
+ * @param text The `lines` query value, or null.
+ * @returns DEFAULT_LOG_LINES when empty, else the value.
+ * @throws AdminRequestError 400 for any other value.
+ */
+function linesOf(text) {
+    if (text == null || text === "")
+        return DEFAULT_LOG_LINES;
+    const lines = LOG_LINE_CHOICES.find((candidate) => String(candidate) === text);
+    if (lines == null)
+        throw new AdminRequestError(HTTP_BAD_REQUEST, "lines must be 100 or 500");
+    return lines;
+}