@babylonjs-toolkit/server 0.0.0-stage → 9.35.0

package/lib/admin/RedisAdminStore.d.ts

@@ -0,0 +1,114 @@
+import type { Redis } from "ioredis";
+import { type AdminClock } from "./AdminClock.js";
+import { type AdminCollection, type ChainedRecordBuilder, type AdminStore, type AdminStream, type RecordQuery, type StoredDocument, type StoredRecord } from "./AdminStore.js";
+/** Admin data in Redis (D7). */
+export declare class RedisAdminStore implements AdminStore {
+    /** Always "redis". */
+    readonly kind: "redis";
+    /** Redis outlives every instance. */
+    readonly isPersistent: boolean;
+    /** The shared client (RedisPresence quits it, R4). */
+    private readonly redis;
+    /** The clock of `updatedAt` and `at`. */
+    private readonly clock;
+    /** A connection of its own for WATCH/MULTI, made on the first chained append, so no shared command clears the WATCH. */
+    private chainClient;
+    /** The pending chained append, so this process runs one WATCH at a time on chainClient. */
+    private chainQueue;
+    /**
+     * Wraps the shared client.
+     * @param redis The ioredis client also given to RedisPresence.
+     * @param clock The clock of stored times.
+     */
+    constructor(redis: Redis, clock?: AdminClock);
+    /**
+     * Reads one document.
+     * @param collection The collection.
+     * @param documentId The document id.
+     * @returns The document, or null.
+     */
+    getDocument<Value>(collection: AdminCollection, documentId: string): Promise<StoredDocument<Value> | null>;
+    /**
+     * Reads every document of a collection.
+     * @param collection The collection.
+     * @returns The documents.
+     */
+    listDocuments<Value>(collection: AdminCollection): Promise<StoredDocument<Value>[]>;
+    /**
+     * Writes a document through PUT_DOCUMENT_SCRIPT.
+     * @param collection The collection.
+     * @param documentId The document id.
+     * @param value The document.
+     * @param expectedRevision The revision read, or null for no check.
+     * @returns The stored document.
+     * @throws AdminConflictError on a stale expectedRevision.
+     */
+    putDocument<Value>(collection: AdminCollection, documentId: string, value: Value, expectedRevision: number | null): Promise<StoredDocument<Value>>;
+    /**
+     * Deletes a document.
+     * @param collection The collection.
+     * @param documentId The document id.
+     * @returns True when it existed.
+     */
+    deleteDocument(collection: AdminCollection, documentId: string): Promise<boolean>;
+    /**
+     * Appends a record: INCR gives the sequence, ZADD stores it.
+     * @param stream The stream.
+     * @param value The record.
+     * @returns The stored record.
+     */
+    appendRecord<Value>(stream: AdminStream, value: Value): Promise<StoredRecord<Value>>;
+    /**
+     * Appends a record built from the newest one: WATCH the sequence, read the newest record, build, then MULTI (SET
+     * the sequence + ZADD) EXEC, retried up to CHAINED_APPEND_ATTEMPTS times when another instance appended first (R21).
+     * @param stream The stream.
+     * @param build Builds the value.
+     * @returns The stored record.
+     * @throws Error when every attempt lost the race.
+     */
+    appendChainedRecord<Value>(stream: AdminStream, build: ChainedRecordBuilder<Value>): Promise<StoredRecord<Value>>;
+    /**
+     * Reads records with ZRANGEBYSCORE / ZREVRANGEBYSCORE.
+     * @param stream The stream.
+     * @param query The range, limit and order.
+     * @returns The records.
+     */
+    readRecords<Value>(stream: AdminStream, query: RecordQuery): Promise<StoredRecord<Value>[]>;
+    /**
+     * Removes records older than the cutoff, oldest first in batches of TRIM_BATCH_SIZE.
+     * @param stream The stream.
+     * @param cutoff The oldest time kept.
+     * @returns How many were removed.
+     */
+    trimRecordsBefore(stream: AdminStream, cutoff: Date): Promise<number>;
+    /**
+     * Keeps only the newest records (ZREMRANGEBYRANK).
+     * @param stream The stream.
+     * @param keepCount How many to keep.
+     * @returns How many were removed.
+     */
+    trimRecordsToCount(stream: AdminStream, keepCount: number): Promise<number>;
+    /**
+     * Takes the lease with SET NX PX, or renews it when this holder already has it.
+     * @param leaseName The lease.
+     * @param holderId The would-be holder.
+     * @param ttlMilliseconds The lease length.
+     * @returns True when this holder now holds it.
+     */
+    tryAcquireLease(leaseName: string, holderId: string, ttlMilliseconds: number): Promise<boolean>;
+    /** Closes the store's own WATCH connection; the shared client belongs to RedisPresence (R4). */
+    close(): Promise<void>;
+    /**
+     * One chained append with its retries (see appendChainedRecord).
+     * @param stream The stream.
+     * @param build Builds the value.
+     * @returns The stored record.
+     * @throws Error when every attempt lost the race.
+     */
+    private appendChainedOnce;
+}
+/**
+ * @param stream The stream.
+ * @returns The key of its sequence counter.
+ */
+export declare function sequenceKey(stream: AdminStream): string;

package/lib/admin/RedisAdminStore.js

@@ -0,0 +1,258 @@
+// The Redis backend of the admin store (game-server-admin-console D7, DR §6.1), shared by every instance of a fleet.
+// Documents are one hash per collection written by a compare-and-set script; streams are sorted sets scored by sequence.
+import { ADMIN_REDIS_PREFIX } from "./AdminConstants.js";
+import { SYSTEM_CLOCK } from "./AdminClock.js";
+import { AdminConflictError, clampRecordLimit } from "./AdminStore.js";
+/**
+ * Writes a document when its revision matches. KEYS[1] = the collection hash; ARGV = id, expected revision ("" for no
+ * check), value JSON, ISO time. Returns { 1, stored JSON } on success or { 0, current JSON or "" } on a conflict.
+ */
+const PUT_DOCUMENT_SCRIPT = `
+local current = redis.call('HGET', KEYS[1], ARGV[1])
+local revision = 0
+if current then revision = cjson.decode(current).revision end
+if ARGV[2] ~= '' and tonumber(ARGV[2]) ~= revision then return {0, current or ''} end
+local stored = '{"revision":' .. (revision + 1) .. ',"updatedAt":' .. cjson.encode(ARGV[4]) .. ',"value":' .. ARGV[3] .. '}'
+redis.call('HSET', KEYS[1], ARGV[1], stored)
+return {1, stored}
+`;
+/** Extends a lease its holder already holds. KEYS[1] = the lease key; ARGV = holder id, TTL in milliseconds. */
+const RENEW_LEASE_SCRIPT = `
+if redis.call('GET', KEYS[1]) == ARGV[1] then
+  redis.call('PEXPIRE', KEYS[1], ARGV[2])
+  return 1
+end
+return 0
+`;
+/** Attempts of a chained append before it gives up (another instance kept appending, R21). */
+const CHAINED_APPEND_ATTEMPTS = 10;
+/** Records read per round while trimming by time. */
+const TRIM_BATCH_SIZE = 500;
+/** Number of keys the scripts take. */
+const SINGLE_KEY = 1;
+/** The script answer flag of a successful write. */
+const WRITE_SUCCEEDED = 1;
+/** Admin data in Redis (D7). */
+export class RedisAdminStore {
+    /** Always "redis". */
+    kind = "redis";
+    /** Redis outlives every instance. */
+    isPersistent = true;
+    /** The shared client (RedisPresence quits it, R4). */
+    redis;
+    /** The clock of `updatedAt` and `at`. */
+    clock;
+    /** A connection of its own for WATCH/MULTI, made on the first chained append, so no shared command clears the WATCH. */
+    chainClient = null;
+    /** The pending chained append, so this process runs one WATCH at a time on chainClient. */
+    chainQueue = Promise.resolve();
+    /**
+     * Wraps the shared client.
+     * @param redis The ioredis client also given to RedisPresence.
+     * @param clock The clock of stored times.
+     */
+    constructor(redis, clock = SYSTEM_CLOCK) {
+        this.redis = redis;
+        this.clock = clock;
+    }
+    /**
+     * Reads one document.
+     * @param collection The collection.
+     * @param documentId The document id.
+     * @returns The document, or null.
+     */
+    async getDocument(collection, documentId) {
+        const json = await this.redis.hget(documentKey(collection), documentId);
+        return (json != null) ? toDocument(documentId, json) : null;
+    }
+    /**
+     * Reads every document of a collection.
+     * @param collection The collection.
+     * @returns The documents.
+     */
+    async listDocuments(collection) {
+        const fields = await this.redis.hgetall(documentKey(collection));
+        return Object.entries(fields).map(([documentId, json]) => toDocument(documentId, json));
+    }
+    /**
+     * Writes a document through PUT_DOCUMENT_SCRIPT.
+     * @param collection The collection.
+     * @param documentId The document id.
+     * @param value The document.
+     * @param expectedRevision The revision read, or null for no check.
+     * @returns The stored document.
+     * @throws AdminConflictError on a stale expectedRevision.
+     */
+    async putDocument(collection, documentId, value, expectedRevision) {
+        const expectedText = (expectedRevision != null) ? String(expectedRevision) : "";
+        const updatedAt = new Date(this.clock.now()).toISOString();
+        const answer = await this.redis.eval(PUT_DOCUMENT_SCRIPT, SINGLE_KEY, documentKey(collection), documentId, expectedText, JSON.stringify(value), updatedAt);
+        const [flag, json] = answer;
+        if (flag !== WRITE_SUCCEEDED)
+            throw new AdminConflictError((json !== "") ? toDocument(documentId, json) : null);
+        return toDocument(documentId, json);
+    }
+    /**
+     * Deletes a document.
+     * @param collection The collection.
+     * @param documentId The document id.
+     * @returns True when it existed.
+     */
+    async deleteDocument(collection, documentId) {
+        return (await this.redis.hdel(documentKey(collection), documentId)) > 0;
+    }
+    /**
+     * Appends a record: INCR gives the sequence, ZADD stores it.
+     * @param stream The stream.
+     * @param value The record.
+     * @returns The stored record.
+     */
+    async appendRecord(stream, value) {
+        const sequence = await this.redis.incr(sequenceKey(stream));
+        const record = { sequence: sequence, at: new Date(this.clock.now()).toISOString(), value: value };
+        await this.redis.zadd(streamKey(stream), sequence, JSON.stringify(record));
+        return record;
+    }
+    /**
+     * Appends a record built from the newest one: WATCH the sequence, read the newest record, build, then MULTI (SET
+     * the sequence + ZADD) EXEC, retried up to CHAINED_APPEND_ATTEMPTS times when another instance appended first (R21).
+     * @param stream The stream.
+     * @param build Builds the value.
+     * @returns The stored record.
+     * @throws Error when every attempt lost the race.
+     */
+    appendChainedRecord(stream, build) {
+        const run = () => this.appendChainedOnce(stream, build);
+        const next = this.chainQueue.then(run, run);
+        this.chainQueue = next.catch(() => undefined);
+        return next;
+    }
+    /**
+     * Reads records with ZRANGEBYSCORE / ZREVRANGEBYSCORE.
+     * @param stream The stream.
+     * @param query The range, limit and order.
+     * @returns The records.
+     */
+    async readRecords(stream, query) {
+        const lowest = (query.afterSequence != null) ? "(" + query.afterSequence : "-inf";
+        const highest = (query.beforeSequence != null) ? "(" + query.beforeSequence : "+inf";
+        const limit = clampRecordLimit(query.limit);
+        const members = query.newestFirst
+            ? await this.redis.zrevrangebyscore(streamKey(stream), highest, lowest, "LIMIT", 0, limit)
+            : await this.redis.zrangebyscore(streamKey(stream), lowest, highest, "LIMIT", 0, limit);
+        return members.map((member) => JSON.parse(member));
+    }
+    /**
+     * Removes records older than the cutoff, oldest first in batches of TRIM_BATCH_SIZE.
+     * @param stream The stream.
+     * @param cutoff The oldest time kept.
+     * @returns How many were removed.
+     */
+    async trimRecordsBefore(stream, cutoff) {
+        const cutoffMilliseconds = cutoff.getTime();
+        let removedCount = 0;
+        for (;;) {
+            const members = await this.redis.zrange(streamKey(stream), 0, TRIM_BATCH_SIZE - 1);
+            const records = members.map((member) => JSON.parse(member));
+            const expired = records.filter((record) => Date.parse(record.at) < cutoffMilliseconds);
+            if (expired.length === 0)
+                return removedCount;
+            const lastExpiredSequence = expired[expired.length - 1].sequence;
+            removedCount += await this.redis.zremrangebyscore(streamKey(stream), "-inf", lastExpiredSequence);
+            if (expired.length < records.length || records.length < TRIM_BATCH_SIZE)
+                return removedCount;
+        }
+    }
+    /**
+     * Keeps only the newest records (ZREMRANGEBYRANK).
+     * @param stream The stream.
+     * @param keepCount How many to keep.
+     * @returns How many were removed.
+     */
+    async trimRecordsToCount(stream, keepCount) {
+        return this.redis.zremrangebyrank(streamKey(stream), 0, -(Math.max(0, keepCount) + 1));
+    }
+    /**
+     * Takes the lease with SET NX PX, or renews it when this holder already has it.
+     * @param leaseName The lease.
+     * @param holderId The would-be holder.
+     * @param ttlMilliseconds The lease length.
+     * @returns True when this holder now holds it.
+     */
+    async tryAcquireLease(leaseName, holderId, ttlMilliseconds) {
+        const taken = await this.redis.set(leaseKey(leaseName), holderId, "PX", ttlMilliseconds, "NX");
+        if (taken != null)
+            return true;
+        const renewed = await this.redis.eval(RENEW_LEASE_SCRIPT, SINGLE_KEY, leaseKey(leaseName), holderId, String(ttlMilliseconds));
+        return renewed === WRITE_SUCCEEDED;
+    }
+    /** Closes the store's own WATCH connection; the shared client belongs to RedisPresence (R4). */
+    async close() {
+        await this.chainQueue;
+        if (this.chainClient != null)
+            await this.chainClient.quit();
+        this.chainClient = null;
+    }
+    /**
+     * One chained append with its retries (see appendChainedRecord).
+     * @param stream The stream.
+     * @param build Builds the value.
+     * @returns The stored record.
+     * @throws Error when every attempt lost the race.
+     */
+    async appendChainedOnce(stream, build) {
+        this.chainClient ??= this.redis.duplicate();
+        const client = this.chainClient;
+        for (let attempt = 0; attempt < CHAINED_APPEND_ATTEMPTS; attempt++) {
+            await client.watch(sequenceKey(stream));
+            const lastSequence = Number(await client.get(sequenceKey(stream)) ?? 0);
+            const newest = await client.zrevrange(streamKey(stream), 0, 0);
+            const previous = (newest.length > 0) ? JSON.parse(newest[0]) : null;
+            const sequence = lastSequence + 1;
+            const at = new Date(this.clock.now()).toISOString();
+            const record = { sequence: sequence, at: at, value: build(previous, sequence, at) };
+            const committed = await client.multi().set(sequenceKey(stream), String(sequence)).zadd(streamKey(stream), sequence, JSON.stringify(record)).exec();
+            if (committed != null)
+                return record;
+        }
+        throw new Error("could not append to " + stream + " after " + CHAINED_APPEND_ATTEMPTS + " attempts");
+    }
+}
+/**
+ * @param collection The collection.
+ * @returns Its hash key.
+ */
+function documentKey(collection) {
+    return ADMIN_REDIS_PREFIX + "doc:" + collection;
+}
+/**
+ * @param stream The stream.
+ * @returns Its sorted set key.
+ */
+function streamKey(stream) {
+    return ADMIN_REDIS_PREFIX + "stream:" + stream;
+}
+/**
+ * @param stream The stream.
+ * @returns The key of its sequence counter.
+ */
+export function sequenceKey(stream) {
+    return ADMIN_REDIS_PREFIX + "seq:" + stream;
+}
+/**
+ * @param leaseName The lease.
+ * @returns Its key.
+ */
+function leaseKey(leaseName) {
+    return ADMIN_REDIS_PREFIX + "lease:" + leaseName;
+}
+/**
+ * Parses a hash field into a document.
+ * @param documentId The id.
+ * @param json The stored JSON.
+ * @returns The document.
+ */
+function toDocument(documentId, json) {
+    const entry = JSON.parse(json);
+    return { id: documentId, revision: entry.revision, updatedAt: entry.updatedAt, value: entry.value };
+}

package/lib/admin/RolloutCoordinator.d.ts

@@ -0,0 +1,99 @@
+import type { RolloutsRequest, RolloutView } from "./AdminApiTypes.js";
+import type { AdminCoreServices } from "./AdminServices.js";
+import type { FleetDirectory } from "./FleetDirectory.js";
+import type { ServerEvents } from "./ServerEvents.js";
+/** The commands of POST rollouts/:rolloutId/:command. */
+export type RolloutCommand = "pause" | "resume" | "cancel";
+/** Starts, steers and drives the fleet's rolling updates. */
+export declare class RolloutCoordinator {
+    /** The shared core services. */
+    private readonly services;
+    /** The fleet directory (instances and the drain command). */
+    private readonly fleet;
+    /** The activity feed's server events. */
+    private readonly serverEvents;
+    /**
+     * Creates the coordinator; nothing runs until the leader ticks.
+     * @param services The shared core services.
+     * @param fleet The fleet directory.
+     * @param serverEvents The activity feed's server events.
+     */
+    constructor(services: AdminCoreServices, fleet: FleetDirectory, serverEvents: ServerEvents);
+    /**
+     * Every rollout, newest first.
+     * @returns The rollouts.
+     */
+    list(): Promise<RolloutView[]>;
+    /**
+     * Starts a rollout over the live instances (POST rollouts). The instance that starts it goes last, so it keeps
+     * answering the console for as long as possible.
+     * @param request The notice and timeouts.
+     * @param startedBy Who starts it.
+     * @returns The rollout.
+     * @throws AdminRequestError 409 with fewer than two live instances or while another rollout is unfinished, 400 for
+     *     negative times.
+     */
+    start(request: RolloutsRequest, startedBy: string): Promise<RolloutView>;
+    /**
+     * Pauses, resumes or cancels a rollout. Resuming a failed step gives it another perInstanceTimeoutMinutes.
+     * @param rolloutId The rollout.
+     * @param command The command.
+     * @returns The rollout.
+     * @throws AdminRequestError 404 for an unknown rollout or command, 409 when the rollout cannot take the command.
+     */
+    command(rolloutId: string, command: string): Promise<RolloutView>;
+    /** The leader tick: moves every running rollout on by one decision. */
+    tick(): Promise<void>;
+    /**
+     * Runs the current step of a running rollout (DR §7.8 steps 1–4), or finishes the rollout.
+     * @param record The rollout, changed in place.
+     */
+    private advance;
+    /**
+     * Sends a step's drain (with the rollout's notice) to its instance.
+     * @param record The rollout.
+     * @param step The step.
+     * @param now The clock time.
+     */
+    private startDrain;
+    /**
+     * Marks a step replaced once its instance is gone and a replacement is ready, or fails it after the timeout.
+     * @param record The rollout.
+     * @param step The step.
+     * @param now The clock time.
+     * @param stepStartedAt When the step's drain started, in milliseconds.
+     */
+    private checkReplacement;
+    /**
+     * A ready instance that joined after the rollout started, runs at least its starting version and replaces no other
+     * step yet.
+     * @param record The rollout.
+     * @param instances The fleet now.
+     * @returns The replacement, or undefined.
+     */
+    private findReplacement;
+    /**
+     * Resumes a paused rollout; its failed step waits for a replacement again.
+     * @param record The rollout, changed in place.
+     * @throws AdminRequestError 409 unless it is paused.
+     */
+    private resumeRollout;
+    /**
+     * Stores a rollout the tick changed; a pause or cancel stored meanwhile wins and the change is dropped.
+     * @param stored The rollout as read.
+     * @param record The rollout after the tick.
+     */
+    private saveIfChanged;
+    /**
+     * Every stored rollout.
+     * @returns The documents.
+     */
+    private storedRollouts;
+}
+/**
+ * Compares two dotted versions by their numeric parts ("9.30.1" < "9.31.0"); a non-numeric part counts as 0.
+ * @param left One version.
+ * @param right The other.
+ * @returns A negative number, 0 or a positive number.
+ */
+export declare function compareVersions(left: string, right: string): number;