@helyx/bot 0.3.1 → 0.4.1

package/dist/shard-coordinator.js

@@ -0,0 +1,620 @@
+import { randomUUID } from "node:crypto";
+import { createClient } from "redis";
+import { z } from "zod";
+import { SHARD_CONTROL_MAX_BYTES, assertShardMessageSize, shardCloudRequestSchema, shardCloudResponseSchema, shardControlRequestSchema, shardControlResponseSchema, shardIdentitySchema, shardProcessHealthSchema, } from "./shard-contracts.js";
+const LEASE_TTL_MS = 30_000;
+const HEALTH_TTL_MS = 30_000;
+const GENERATION_TTL_MS = 30_000;
+const RESPONSE_TTL_SECONDS = 20;
+const ROUTE_POLL_MS = 40;
+const generationDescriptorSchema = z
+    .object({
+    version: z.literal(1),
+    applicationId: z.string().regex(/^\d{17,20}$/u),
+    environment: z.enum(["development", "test", "production"]),
+    generation: z.string().regex(/^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/u),
+    shardCount: z.number().int().min(1).max(4_096),
+    catalogueHash: z.string().regex(/^[a-f0-9]{64}$/u),
+})
+    .strict();
+const deploymentOrderSchema = z
+    .number()
+    .int()
+    .positive()
+    .max(Number.MAX_SAFE_INTEGER);
+const activeGenerationSchema = generationDescriptorSchema.extend({
+    deploymentOrder: deploymentOrderSchema,
+});
+const leaseSchema = z
+    .object({
+    generation: generationDescriptorSchema.shape.generation,
+    deploymentOrder: deploymentOrderSchema,
+    supervisorId: z.uuid(),
+    shardId: z.number().int().min(0).max(4_095),
+    fencingToken: z.number().int().positive(),
+})
+    .strict();
+const legacyLeaseSchema = leaseSchema.omit({ deploymentOrder: true }).strict();
+const leaderLeaseSchema = z
+    .object({
+    generation: generationDescriptorSchema.shape.generation,
+    supervisorId: z.uuid(),
+    fencingToken: z.number().int().positive(),
+})
+    .strict();
+const remoteRequestSchema = z.discriminatedUnion("target", [
+    z
+        .object({
+        version: z.literal(1),
+        type: z.literal("helyx.remote.request"),
+        target: z.literal("shard"),
+        targetShardId: z.number().int().min(0).max(4_095),
+        request: shardControlRequestSchema,
+    })
+        .strict(),
+    z
+        .object({
+        version: z.literal(1),
+        type: z.literal("helyx.remote.request"),
+        target: z.literal("leader"),
+        request: shardControlRequestSchema,
+    })
+        .strict(),
+    z
+        .object({
+        version: z.literal(1),
+        type: z.literal("helyx.remote.request"),
+        target: z.literal("leader-cloud"),
+        generation: generationDescriptorSchema.shape.generation,
+        fencingToken: z.number().int().positive(),
+        request: shardCloudRequestSchema,
+    })
+        .strict(),
+]);
+const storedHealthSchema = z
+    .object({
+    identity: shardIdentitySchema,
+    health: shardProcessHealthSchema,
+})
+    .strict();
+export class RedisShardCoordinator {
+    supervisorId = randomUUID();
+    #command;
+    #subscriber;
+    #prefix;
+    #onError;
+    #handler;
+    #leaderHandler;
+    #cloudHandler;
+    constructor(redisUrl, namespace, options = {}) {
+        this.#prefix = `helyx:shard:v1:${namespace}`;
+        this.#command = createClient({ url: redisUrl });
+        this.#subscriber = this.#command.duplicate();
+        this.#onError = options.onError ?? (() => undefined);
+        this.#command.on("error", (error) => this.#report(error));
+        this.#subscriber.on("error", (error) => this.#report(error));
+    }
+    async start(handler, leaderHandler, cloudHandler) {
+        this.#handler = handler;
+        this.#leaderHandler = leaderHandler;
+        this.#cloudHandler = cloudHandler;
+        await Promise.all([this.#command.connect(), this.#subscriber.connect()]);
+        await this.#subscriber.subscribe(this.#requestChannel(), (raw) => {
+            void this.#handleRemoteRequest(raw).catch((error) => this.#report(error));
+        });
+    }
+    async checkReady() {
+        if (!this.#command.isReady || !this.#subscriber.isReady)
+            throw new Error("Shard Redis coordinator is unavailable");
+        await this.#command.ping();
+    }
+    async assertGeneration(descriptor, proposedDeploymentOrder) {
+        const accepted = generationDescriptorSchema.parse(descriptor);
+        const deploymentOrder = deploymentOrderSchema.parse(proposedDeploymentOrder);
+        const active = activeGenerationSchema.parse({
+            ...accepted,
+            deploymentOrder,
+        });
+        const serialized = JSON.stringify(active);
+        const created = await this.#command.set(this.#generationKey(), serialized, {
+            NX: true,
+            PX: GENERATION_TTL_MS,
+        });
+        if (created === "OK")
+            return deploymentOrder;
+        const current = await this.#command.get(this.#generationKey());
+        const parsed = activeGenerationSchema.safeParse(parseJson(current ?? ""));
+        if (parsed.success) {
+            if (JSON.stringify(withoutDeploymentOrder(parsed.data)) !==
+                JSON.stringify(accepted))
+                throw new Error("Shard coordination namespace is owned by an incompatible generation");
+            if (!current ||
+                !(await compareAndExpire(this.#command, this.#generationKey(), current, GENERATION_TTL_MS)))
+                throw new Error("Shard coordination generation changed while it was being validated");
+            return parsed.data.deploymentOrder;
+        }
+        const legacy = generationDescriptorSchema.safeParse(parseJson(current ?? ""));
+        if (!legacy.success ||
+            JSON.stringify(legacy.data) !== JSON.stringify(accepted) ||
+            !current)
+            throw new Error("Shard coordination namespace is owned by an incompatible generation");
+        const upgraded = await compareAndReplace(this.#command, this.#generationKey(), current, serialized, GENERATION_TTL_MS);
+        if (upgraded)
+            return deploymentOrder;
+        const winner = activeGenerationSchema.safeParse(parseJson((await this.#command.get(this.#generationKey())) ?? ""));
+        if (winner.success &&
+            JSON.stringify(withoutDeploymentOrder(winner.data)) ===
+                JSON.stringify(accepted))
+            return winner.data.deploymentOrder;
+        throw new Error("Shard coordination namespace is owned by an incompatible generation");
+    }
+    async refreshGeneration(descriptor, deploymentOrder) {
+        return compareAndExpire(this.#command, this.#generationKey(), JSON.stringify(activeGenerationSchema.parse({
+            ...generationDescriptorSchema.parse(descriptor),
+            deploymentOrder,
+        })), GENERATION_TTL_MS);
+    }
+    async claimShard(descriptor, shardId, deploymentOrder) {
+        const accepted = generationDescriptorSchema.parse(descriptor);
+        const acceptedDeploymentOrder = deploymentOrderSchema.parse(deploymentOrder);
+        if (!Number.isInteger(shardId) ||
+            shardId < 0 ||
+            shardId >= accepted.shardCount)
+            throw new Error("Shard claim ID is outside the active generation");
+        const leasePrefix = JSON.stringify({
+            generation: accepted.generation,
+            deploymentOrder: acceptedDeploymentOrder,
+            supervisorId: this.supervisorId,
+            shardId,
+        }).slice(0, -1);
+        const result = await this.#command.eval(`-- atomic-shard-claim
+       if redis.call('GET', KEYS[1]) ~= ARGV[1] then return 0 end
+       if redis.call('EXISTS', KEYS[2]) == 1 then return -1 end
+       local fencing_token = redis.call('INCR', KEYS[3])
+       local lease = ARGV[2] .. ',"fencingToken":' ..
+         tostring(fencing_token) .. '}'
+       redis.call('SET', KEYS[2], lease, 'PX', ARGV[3], 'NX')
+       return fencing_token`, {
+            keys: [
+                this.#generationKey(),
+                this.#shardLeaseKey(shardId),
+                this.#fenceKey(acceptedDeploymentOrder),
+            ],
+            arguments: [
+                JSON.stringify({
+                    ...accepted,
+                    deploymentOrder: acceptedDeploymentOrder,
+                }),
+                leasePrefix,
+                String(LEASE_TTL_MS),
+            ],
+        });
+        if (typeof result !== "number" || result < 1)
+            return undefined;
+        const lease = leaseSchema.parse({
+            generation: accepted.generation,
+            deploymentOrder: acceptedDeploymentOrder,
+            supervisorId: this.supervisorId,
+            shardId,
+            fencingToken: result,
+        });
+        return lease;
+    }
+    renewShard(lease) {
+        const accepted = leaseSchema.parse(lease);
+        return compareAndExpire(this.#command, this.#shardLeaseKey(accepted.shardId), JSON.stringify(accepted), LEASE_TTL_MS);
+    }
+    releaseShard(lease) {
+        const accepted = leaseSchema.parse(lease);
+        return compareAndDelete(this.#command, this.#shardLeaseKey(accepted.shardId), JSON.stringify(accepted));
+    }
+    async getShardLease(shardId) {
+        const raw = await this.#command.get(this.#shardLeaseKey(shardId));
+        return parseLease(raw);
+    }
+    async getShardLeases(shardCount) {
+        if (!Number.isInteger(shardCount) || shardCount < 1 || shardCount > 4_096)
+            throw new Error("Shard lease count is invalid");
+        const values = await this.#command.mGet(Array.from({ length: shardCount }, (_, shardId) => this.#shardLeaseKey(shardId)));
+        return values.flatMap((raw) => {
+            const lease = parseLease(raw);
+            return lease ? [lease] : [];
+        });
+    }
+    async acquireLeader(descriptor, deploymentOrder) {
+        const accepted = generationDescriptorSchema.parse(descriptor);
+        const acceptedDeploymentOrder = deploymentOrderSchema.parse(deploymentOrder);
+        const leasePrefix = JSON.stringify({
+            generation: accepted.generation,
+            supervisorId: this.supervisorId,
+        }).slice(0, -1);
+        const result = await this.#command.eval(`-- atomic-leader-claim
+       if redis.call('GET', KEYS[1]) ~= ARGV[1] then return 0 end
+       if redis.call('EXISTS', KEYS[2]) == 1 then return -1 end
+       local fencing_token = redis.call('INCR', KEYS[3])
+       local lease = ARGV[2] .. ',"fencingToken":' ..
+         tostring(fencing_token) .. '}'
+       redis.call('SET', KEYS[2], lease, 'PX', ARGV[3], 'NX')
+       return fencing_token`, {
+            keys: [
+                this.#generationKey(),
+                this.#leaderLeaseKey(),
+                this.#leaderFenceKey(),
+            ],
+            arguments: [
+                JSON.stringify({
+                    ...accepted,
+                    deploymentOrder: acceptedDeploymentOrder,
+                }),
+                leasePrefix,
+                String(LEASE_TTL_MS),
+            ],
+        });
+        if (typeof result !== "number" || result < 1)
+            return undefined;
+        const lease = leaderLeaseSchema.parse({
+            generation: accepted.generation,
+            supervisorId: this.supervisorId,
+            fencingToken: result,
+        });
+        return lease;
+    }
+    renewLeader(lease) {
+        const accepted = leaderLeaseSchema.parse(lease);
+        return compareAndExpire(this.#command, this.#leaderLeaseKey(), JSON.stringify(accepted), LEASE_TTL_MS);
+    }
+    releaseLeader(lease) {
+        const accepted = leaderLeaseSchema.parse(lease);
+        return compareAndDelete(this.#command, this.#leaderLeaseKey(), JSON.stringify(accepted));
+    }
+    async getLeaderLease() {
+        const raw = await this.#command.get(this.#leaderLeaseKey());
+        if (!raw)
+            return undefined;
+        const parsed = leaderLeaseSchema.safeParse(parseJson(raw));
+        return parsed.success ? parsed.data : undefined;
+    }
+    async routeRemote(lease, request) {
+        const acceptedLease = leaseSchema.parse(lease);
+        const acceptedRequest = shardControlRequestSchema.parse(request);
+        if (acceptedRequest.generation !== acceptedLease.generation ||
+            acceptedRequest.fencingToken !== acceptedLease.fencingToken)
+            throw new Error("Shard route ownership changed");
+        const envelope = remoteRequestSchema.parse({
+            version: 1,
+            type: "helyx.remote.request",
+            target: "shard",
+            targetShardId: acceptedLease.shardId,
+            request: acceptedRequest,
+        });
+        assertShardMessageSize(envelope);
+        const listeners = await this.#command.publish(this.#requestChannel(acceptedLease.supervisorId), JSON.stringify(envelope));
+        if (listeners < 1)
+            throw new Error("Owning shard supervisor is unavailable");
+        const deadline = new Date(acceptedRequest.deadlineAt).getTime();
+        const responseKey = this.#responseKey(acceptedRequest.requestId);
+        while (Date.now() < deadline) {
+            const raw = await this.#command.get(responseKey);
+            if (raw) {
+                await this.#command.del(responseKey);
+                const parsed = shardControlResponseSchema.parse(parseJson(raw));
+                assertShardMessageSize(parsed);
+                return parsed;
+            }
+            await wait(ROUTE_POLL_MS);
+        }
+        throw new Error("Shard control request timed out");
+    }
+    async routeLeader(lease, request) {
+        const acceptedLease = leaderLeaseSchema.parse(lease);
+        const acceptedRequest = shardControlRequestSchema.parse(request);
+        if (acceptedRequest.generation !== acceptedLease.generation ||
+            acceptedRequest.fencingToken !== acceptedLease.fencingToken)
+            throw new Error("Shard leader ownership changed");
+        const envelope = remoteRequestSchema.parse({
+            version: 1,
+            type: "helyx.remote.request",
+            target: "leader",
+            request: acceptedRequest,
+        });
+        assertShardMessageSize(envelope);
+        const listeners = await this.#command.publish(this.#requestChannel(acceptedLease.supervisorId), JSON.stringify(envelope));
+        if (listeners < 1)
+            throw new Error("Shard leader is unavailable");
+        return this.#waitForResponse(acceptedRequest);
+    }
+    async routeLeaderCloud(lease, request) {
+        const acceptedLease = leaderLeaseSchema.parse(lease);
+        const acceptedRequest = shardCloudRequestSchema.parse(request);
+        const currentLeader = await this.getLeaderLease();
+        if (!currentLeader ||
+            currentLeader.supervisorId !== acceptedLease.supervisorId ||
+            currentLeader.generation !== acceptedLease.generation ||
+            currentLeader.fencingToken !== acceptedLease.fencingToken)
+            throw new Error("Shard leader ownership changed");
+        const envelope = remoteRequestSchema.parse({
+            version: 1,
+            type: "helyx.remote.request",
+            target: "leader-cloud",
+            generation: acceptedLease.generation,
+            fencingToken: acceptedLease.fencingToken,
+            request: acceptedRequest,
+        });
+        assertShardMessageSize(envelope);
+        const listeners = await this.#command.publish(this.#requestChannel(acceptedLease.supervisorId), JSON.stringify(envelope));
+        if (listeners < 1)
+            throw new Error("Shard leader is unavailable");
+        const deadline = new Date(acceptedRequest.deadlineAt).getTime();
+        const responseKey = this.#responseKey(acceptedRequest.requestId);
+        while (Date.now() < deadline) {
+            const raw = await this.#command.get(responseKey);
+            if (raw) {
+                await this.#command.del(responseKey);
+                const parsed = shardCloudResponseSchema.parse(parseJson(raw));
+                assertShardMessageSize(parsed);
+                return parsed;
+            }
+            await wait(ROUTE_POLL_MS);
+        }
+        throw new Error("Shard cloud request timed out");
+    }
+    async reserveSessionStarts(count, available, resetAfterMs) {
+        if (!Number.isInteger(count) ||
+            count < 1 ||
+            !Number.isInteger(available) ||
+            available < 0 ||
+            !Number.isFinite(resetAfterMs) ||
+            resetAfterMs < 0)
+            throw new Error("Discord session-start reservation is invalid");
+        const result = await this.#command.eval(`local current = redis.call('GET', KEYS[1])
+       if not current then
+         current = ARGV[1]
+         redis.call('SET', KEYS[1], current, 'PX', ARGV[3], 'NX')
+         current = redis.call('GET', KEYS[1])
+       elseif tonumber(ARGV[1]) < tonumber(current) then
+         current = ARGV[1]
+         redis.call('SET', KEYS[1], current, 'PX', ARGV[3], 'XX')
+       end
+       if tonumber(current) < tonumber(ARGV[2]) then return 0 end
+       redis.call('DECRBY', KEYS[1], ARGV[2])
+       return 1`, {
+            keys: [`${this.#prefix}:session-starts`],
+            arguments: [
+                String(available),
+                String(count),
+                String(Math.max(1_000, resetAfterMs)),
+            ],
+        });
+        return result === 1;
+    }
+    async acquireIdentifyPermit(shardId, maxConcurrency, timeoutMs) {
+        const bucket = shardId % maxConcurrency;
+        const deadline = Date.now() + timeoutMs;
+        while (Date.now() < deadline) {
+            const acquired = await this.#command.set(`${this.#prefix}:identify:${String(bucket)}`, `${this.supervisorId}:${String(shardId)}`, { NX: true, PX: 5_500 });
+            if (acquired === "OK")
+                return true;
+            await wait(100);
+        }
+        return false;
+    }
+    async setHealth(identity, health) {
+        const value = storedHealthSchema.parse({ identity, health });
+        await this.#command.set(this.#healthKey(identity.shardId), JSON.stringify(value), { PX: HEALTH_TTL_MS });
+    }
+    async getHealth(shardCount) {
+        if (!Number.isInteger(shardCount) || shardCount < 1 || shardCount > 4_096)
+            throw new Error("Shard health count is invalid");
+        const values = await this.#command.mGet(Array.from({ length: shardCount }, (_, shardId) => this.#healthKey(shardId)));
+        return values.flatMap((raw) => {
+            if (!raw)
+                return [];
+            const parsed = storedHealthSchema.safeParse(parseJson(raw));
+            return parsed.success ? [parsed.data] : [];
+        });
+    }
+    async stop() {
+        await Promise.allSettled([
+            this.#subscriber.isOpen
+                ? this.#subscriber.unsubscribe(this.#requestChannel())
+                : Promise.resolve(),
+            this.#subscriber.isOpen ? this.#subscriber.quit() : Promise.resolve(),
+            this.#command.isOpen ? this.#command.quit() : Promise.resolve(),
+        ]);
+    }
+    async #handleRemoteRequest(raw) {
+        if (Buffer.byteLength(raw, "utf8") > SHARD_CONTROL_MAX_BYTES)
+            return;
+        const envelope = remoteRequestSchema.safeParse(parseJson(raw));
+        if (!envelope.success || !this.#handler)
+            return;
+        if (new Date(envelope.data.request.deadlineAt).getTime() <= Date.now())
+            return;
+        if (envelope.data.target === "leader-cloud") {
+            const request = envelope.data.request;
+            const leader = await this.getLeaderLease();
+            if (!leader ||
+                leader.supervisorId !== this.supervisorId ||
+                leader.generation !== envelope.data.generation ||
+                leader.fencingToken !== envelope.data.fencingToken ||
+                !this.#cloudHandler)
+                return this.#writeCloudResponse({
+                    version: 1,
+                    type: "helyx.cloud.response",
+                    requestId: request.requestId,
+                    ok: false,
+                    message: "Shard leader ownership changed",
+                });
+            const response = await this.#cloudHandler(request).catch(() => ({
+                version: 1,
+                type: "helyx.cloud.response",
+                requestId: request.requestId,
+                ok: false,
+                message: "Cloud leader is temporarily unavailable",
+            }));
+            await this.#writeCloudResponse(response);
+            return;
+        }
+        if (envelope.data.target === "leader") {
+            const request = envelope.data.request;
+            const leader = await this.getLeaderLease();
+            if (!leader ||
+                leader.supervisorId !== this.supervisorId ||
+                leader.generation !== request.generation ||
+                leader.fencingToken !== request.fencingToken ||
+                !this.#leaderHandler)
+                return this.#writeResponse({
+                    version: 1,
+                    type: "helyx.control.response",
+                    requestId: request.requestId,
+                    ok: false,
+                    status: 503,
+                    message: "Shard leader ownership changed",
+                });
+            const response = await this.#leaderHandler(request).catch(() => ({
+                version: 1,
+                type: "helyx.control.response",
+                requestId: request.requestId,
+                ok: false,
+                status: 503,
+                message: "Shard leader is temporarily unavailable",
+            }));
+            await this.#writeResponse(response);
+            return;
+        }
+        const { targetShardId, request } = envelope.data;
+        const lease = await this.getShardLease(targetShardId);
+        if (!lease ||
+            lease.supervisorId !== this.supervisorId ||
+            lease.generation !== request.generation ||
+            lease.fencingToken !== request.fencingToken)
+            return this.#writeResponse({
+                version: 1,
+                type: "helyx.control.response",
+                requestId: request.requestId,
+                ok: false,
+                status: 503,
+                message: "Shard ownership changed",
+            });
+        const response = await this.#handler(targetShardId, request).catch(() => ({
+            version: 1,
+            type: "helyx.control.response",
+            requestId: request.requestId,
+            ok: false,
+            status: 503,
+            message: "Owning shard is temporarily unavailable",
+        }));
+        await this.#writeResponse(response);
+    }
+    async #writeResponse(response) {
+        const accepted = shardControlResponseSchema.parse(response);
+        assertShardMessageSize(accepted);
+        await this.#command.set(this.#responseKey(accepted.requestId), JSON.stringify(accepted), { EX: RESPONSE_TTL_SECONDS });
+    }
+    async #writeCloudResponse(response) {
+        const accepted = shardCloudResponseSchema.parse(response);
+        assertShardMessageSize(accepted);
+        await this.#command.set(this.#responseKey(accepted.requestId), JSON.stringify(accepted), { EX: RESPONSE_TTL_SECONDS });
+    }
+    async #waitForResponse(request) {
+        const deadline = new Date(request.deadlineAt).getTime();
+        const responseKey = this.#responseKey(request.requestId);
+        while (Date.now() < deadline) {
+            const raw = await this.#command.get(responseKey);
+            if (raw) {
+                await this.#command.del(responseKey);
+                const parsed = shardControlResponseSchema.parse(parseJson(raw));
+                assertShardMessageSize(parsed);
+                return parsed;
+            }
+            await wait(ROUTE_POLL_MS);
+        }
+        throw new Error("Shard control request timed out");
+    }
+    #generationKey() {
+        return `${this.#prefix}:generation`;
+    }
+    #shardLeaseKey(shardId) {
+        return `${this.#prefix}:lease:shard:${String(shardId)}`;
+    }
+    #fenceKey(deploymentOrder) {
+        return `${this.#prefix}:fence:deployment:${String(deploymentOrder)}:claim`;
+    }
+    #leaderLeaseKey() {
+        return `${this.#prefix}:lease:leader`;
+    }
+    #leaderFenceKey() {
+        return `${this.#prefix}:fence:leader`;
+    }
+    #requestChannel(supervisorId = this.supervisorId) {
+        return `${this.#prefix}:request:${supervisorId}`;
+    }
+    #responseKey(requestId) {
+        return `${this.#prefix}:response:${requestId}`;
+    }
+    #healthKey(shardId) {
+        return `${this.#prefix}:health:${String(shardId)}`;
+    }
+    #report(error) {
+        this.#onError(error instanceof Error ? error : new Error("Unknown shard Redis failure"));
+    }
+}
+async function compareAndExpire(client, key, expected, milliseconds) {
+    const result = await client.eval(`if redis.call('GET', KEYS[1]) == ARGV[1] then
+       return redis.call('PEXPIRE', KEYS[1], ARGV[2])
+     end
+     return 0`, { keys: [key], arguments: [expected, String(milliseconds)] });
+    return result === 1;
+}
+async function compareAndDelete(client, key, expected) {
+    const result = await client.eval(`if redis.call('GET', KEYS[1]) == ARGV[1] then
+       return redis.call('DEL', KEYS[1])
+     end
+     return 0`, { keys: [key], arguments: [expected] });
+    return result === 1;
+}
+async function compareAndReplace(client, key, expected, replacement, milliseconds) {
+    const result = await client.eval(`if redis.call('GET', KEYS[1]) == ARGV[1] then
+       redis.call('SET', KEYS[1], ARGV[2], 'PX', ARGV[3])
+       return 1
+     end
+     return 0`, {
+        keys: [key],
+        arguments: [expected, replacement, String(milliseconds)],
+    });
+    return result === 1;
+}
+function parseJson(value) {
+    try {
+        return JSON.parse(value);
+    }
+    catch {
+        return null;
+    }
+}
+function parseLease(raw) {
+    if (!raw)
+        return undefined;
+    const value = parseJson(raw);
+    const parsed = leaseSchema.safeParse(value);
+    if (parsed.success)
+        return parsed.data;
+    const legacy = legacyLeaseSchema.safeParse(value);
+    return legacy.success
+        ? leaseSchema.parse({ ...legacy.data, deploymentOrder: 1 })
+        : undefined;
+}
+function withoutDeploymentOrder(active) {
+    return {
+        version: active.version,
+        applicationId: active.applicationId,
+        environment: active.environment,
+        generation: active.generation,
+        shardCount: active.shardCount,
+        catalogueHash: active.catalogueHash,
+    };
+}
+function wait(milliseconds) {
+    return new Promise((resolveWait) => setTimeout(resolveWait, milliseconds));
+}
+//# sourceMappingURL=shard-coordinator.js.map

package/dist/shard-router.d.ts

@@ -0,0 +1,28 @@
+import { type BotControlHandler } from "./control-server.js";
+import { type ShardControlRequest, type ShardControlResponse } from "./shard-contracts.js";
+import type { ShardCoordinator, ShardLeaderLease, ShardLease } from "./shard-coordinator.js";
+type LocalDispatcher = (shardId: number, request: ShardControlRequest) => Promise<ShardControlResponse>;
+export declare class ShardControlRouter implements BotControlHandler {
+    #private;
+    private readonly input;
+    constructor(input: {
+        generation: string;
+        shardCount: number;
+        localLeases: ReadonlyMap<number, ShardLease>;
+        dispatchLocal: LocalDispatcher;
+        privacy?: Pick<BotControlHandler, "listPrivacyProviders" | "capturePrivacy" | "erasePrivacy">;
+        localLeaderLease?: ShardLeaderLease;
+        coordinator?: ShardCoordinator;
+    });
+    getGuildState(guildId: string): ReturnType<BotControlHandler["getGuildState"]>;
+    setModuleStatus(input: Parameters<BotControlHandler["setModuleStatus"]>[0]): ReturnType<BotControlHandler["setModuleStatus"]>;
+    updateConfiguration(input: Parameters<BotControlHandler["updateConfiguration"]>[0]): ReturnType<BotControlHandler["updateConfiguration"]>;
+    updatePermissions(input: Parameters<BotControlHandler["updatePermissions"]>[0]): ReturnType<BotControlHandler["updatePermissions"]>;
+    updateLoggingPolicy(input: Parameters<BotControlHandler["updateLoggingPolicy"]>[0]): ReturnType<BotControlHandler["updateLoggingPolicy"]>;
+    executeDashboardAction(input: Parameters<BotControlHandler["executeDashboardAction"]>[0]): ReturnType<BotControlHandler["executeDashboardAction"]>;
+    listPrivacyProviders(): ReturnType<BotControlHandler["listPrivacyProviders"]>;
+    capturePrivacy(input: Parameters<BotControlHandler["capturePrivacy"]>[0]): ReturnType<BotControlHandler["capturePrivacy"]>;
+    erasePrivacy(input: Parameters<BotControlHandler["erasePrivacy"]>[0]): ReturnType<BotControlHandler["erasePrivacy"]>;
+}
+export {};
+//# sourceMappingURL=shard-router.d.ts.map