@helyx/bot 0.4.9 → 0.4.11

package/dist/numeric-write-behind-proxy.js

@@ -0,0 +1,313 @@
+import {} from "@helyx/sdk";
+import { randomUUID } from "node:crypto";
+import { assertShardMessageSize, SHARD_CONTROL_TIMEOUT_MS, shardNumericCommittedSchema, shardNumericResponseSchema, } from "./shard-contracts.js";
+export class WorkerNumericWriteBehindProxy {
+    #identity;
+    #pending = new Map();
+    #subscribers = new Map();
+    #onMessage = (raw) => {
+        const response = shardNumericResponseSchema.safeParse(raw);
+        if (response.success) {
+            const pending = this.#pending.get(response.data.requestId);
+            if (!pending)
+                return;
+            this.#pending.delete(response.data.requestId);
+            clearTimeout(pending.timer);
+            pending.resolve(response.data);
+            return;
+        }
+        const committed = shardNumericCommittedSchema.safeParse(raw);
+        if (!committed.success ||
+            !sameIdentity(committed.data.identity, this.#identity))
+            return;
+        void this.#handleCommitted(committed.data);
+    };
+    constructor(identity) {
+        this.#identity = identity;
+        process.on("message", this.#onMessage);
+    }
+    async enqueue(input) {
+        try {
+            const result = await this.#call({
+                kind: "enqueue",
+                ...scope(input),
+                guildId: input.guildId,
+                subjectId: input.subjectId,
+                occurredAt: input.occurredAt.toISOString(),
+                cooldownSeconds: input.cooldownSeconds,
+                identity: encodeRecord(input.identity),
+                insert: encodeRecord(input.insert),
+                increments: input.increments,
+                ...(input.maxima
+                    ? {
+                        maxima: Object.fromEntries(Object.entries(input.maxima).map(([field, value]) => [
+                            field,
+                            value.toISOString(),
+                        ])),
+                    }
+                    : {}),
+            });
+            if (typeof result !== "object" ||
+                result === null ||
+                !("outcome" in result) ||
+                ![
+                    "accepted",
+                    "cooldown",
+                    "suppressed",
+                    "paused",
+                    "capacity",
+                    "unavailable",
+                ].includes(String(result.outcome)))
+                throw new Error("Shard numeric enqueue response is invalid");
+            return {
+                outcome: result.outcome,
+            };
+        }
+        catch {
+            return { outcome: "unavailable" };
+        }
+    }
+    async pendingMemberSnapshot(input) {
+        const result = await this.#call({ kind: "pending.member", ...input });
+        return decodeIpcValue(result);
+    }
+    async flushMember(input) {
+        await this.#call({ kind: "flush.member", ...input });
+    }
+    async flushGuild(input) {
+        await this.#call({ kind: "flush.guild", ...input });
+    }
+    async flushSubject(input) {
+        await this.#call({ kind: "flush.subject", ...input });
+    }
+    async flushModule(input) {
+        await this.#call({ kind: "flush.module", ...input });
+    }
+    runMemberBarrier(input, operation) {
+        return this.#barrier("member", input, operation);
+    }
+    runGuildBarrier(input, operation) {
+        return this.#barrier("guild", input, operation);
+    }
+    runSubjectBarrier(input, operation) {
+        return this.#barrier("subject", input, operation);
+    }
+    async suppressSubject(input) {
+        return (await this.#call({
+            kind: "suppress.subject",
+            ...scope(input),
+            subjectId: input.subjectId,
+            cutoff: input.cutoff.toISOString(),
+        }));
+    }
+    async suppressGuild(input) {
+        return (await this.#call({
+            kind: "suppress.guild",
+            ...input,
+        }));
+    }
+    async releaseGuild(input) {
+        return (await this.#call({
+            kind: "release.guild",
+            ...input,
+        }));
+    }
+    async releaseSubject(input) {
+        return (await this.#call({
+            kind: "release.subject",
+            ...input,
+        }));
+    }
+    async clearMemberCooldown(input) {
+        await this.#call({ kind: "cooldown.member.clear", ...input });
+    }
+    async clearSubjectCooldown(input) {
+        await this.#call({ kind: "cooldown.subject.clear", ...input });
+    }
+    subscribeCommitted(input, handler) {
+        const key = scopeKey(input);
+        const subscribers = this.#subscribers.get(key) ?? new Set();
+        subscribers.add(handler);
+        this.#subscribers.set(key, subscribers);
+        return () => {
+            subscribers.delete(handler);
+            if (subscribers.size === 0)
+                this.#subscribers.delete(key);
+        };
+    }
+    stop() {
+        process.off("message", this.#onMessage);
+        for (const [requestId, pending] of this.#pending) {
+            this.#pending.delete(requestId);
+            clearTimeout(pending.timer);
+            pending.resolve({
+                version: 1,
+                type: "helyx.numeric.response",
+                requestId,
+                ok: false,
+                safeCode: "proxy_stopped",
+            });
+        }
+    }
+    async #barrier(barrierType, input, operation) {
+        const acquired = (await this.#call({
+            kind: "barrier.acquire",
+            ...scope(input),
+            barrierType,
+            ...(input.guildId ? { guildId: input.guildId } : {}),
+            ...(input.subjectId ? { subjectId: input.subjectId } : {}),
+        }));
+        let renewalFailure;
+        const renew = setInterval(() => {
+            void this.#call({
+                kind: "barrier.renew",
+                ...scope(input),
+                barrierType,
+                ...(input.guildId ? { guildId: input.guildId } : {}),
+                ...(input.subjectId ? { subjectId: input.subjectId } : {}),
+                barrierId: acquired.barrierId,
+            }).catch((error) => {
+                renewalFailure =
+                    error instanceof Error
+                        ? error
+                        : new Error("Numeric barrier renewal failed");
+            });
+        }, 20_000);
+        renew.unref();
+        try {
+            if (barrierType === "member")
+                await this.flushMember(input);
+            else if (barrierType === "guild")
+                await this.flushGuild(input);
+            else
+                await this.flushSubject(input);
+            const result = await operation();
+            if (renewalFailure)
+                throw renewalFailure;
+            return result;
+        }
+        finally {
+            clearInterval(renew);
+            await this.#call({
+                kind: "barrier.release",
+                ...scope(input),
+                barrierType,
+                ...(input.guildId ? { guildId: input.guildId } : {}),
+                ...(input.subjectId ? { subjectId: input.subjectId } : {}),
+                barrierId: acquired.barrierId,
+            });
+        }
+    }
+    async #handleCommitted(committed) {
+        let response;
+        try {
+            if (new Date(committed.deadlineAt).getTime() <= Date.now())
+                throw new Error("Numeric committed notification expired");
+            const batch = decodeIpcValue(committed.payload);
+            for (const subscriber of this.#subscribers.get(scopeKey(committed.scope)) ?? [])
+                await subscriber(batch);
+            response = {
+                version: 1,
+                type: "helyx.numeric.committed.response",
+                requestId: committed.requestId,
+                identity: this.#identity,
+                ok: true,
+            };
+        }
+        catch {
+            response = {
+                version: 1,
+                type: "helyx.numeric.committed.response",
+                requestId: committed.requestId,
+                identity: this.#identity,
+                ok: false,
+                safeCode: "handler_failed",
+            };
+        }
+        assertShardMessageSize(response);
+        if (process.connected)
+            process.send?.(response);
+    }
+    #call(operation) {
+        if (!process.send)
+            return Promise.reject(new Error("Shard numeric supervisor IPC is unavailable"));
+        const requestId = randomUUID();
+        const request = {
+            version: 1,
+            type: "helyx.numeric.request",
+            requestId,
+            deadlineAt: new Date(Date.now() + SHARD_CONTROL_TIMEOUT_MS).toISOString(),
+            identity: this.#identity,
+            operation,
+        };
+        assertShardMessageSize(request);
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                this.#pending.delete(requestId);
+                reject(new Error("Shard numeric supervisor request timed out"));
+            }, SHARD_CONTROL_TIMEOUT_MS);
+            timer.unref();
+            this.#pending.set(requestId, {
+                timer,
+                resolve: (response) => {
+                    if (response.ok)
+                        resolve(response.result);
+                    else
+                        reject(new Error(`Shard numeric supervisor rejected request: ${response.safeCode}`));
+                },
+            });
+            process.send?.(request);
+        });
+    }
+}
+function scope(input) {
+    return { moduleId: input.moduleId, collection: input.collection };
+}
+function scopeKey(input) {
+    return `${input.moduleId}\u0000${input.collection}`;
+}
+function encodeRecord(input) {
+    const result = {};
+    for (const [field, value] of Object.entries(input)) {
+        if (value instanceof Date)
+            result[field] = { type: "date", value: value.toISOString() };
+        else if (typeof value === "string")
+            result[field] = { type: "string", value };
+        else if (typeof value === "boolean")
+            result[field] = { type: "boolean", value };
+        else
+            result[field] = { type: "number", value };
+    }
+    return result;
+}
+function decodeIpcValue(input) {
+    if (Array.isArray(input))
+        return input.map(decodeIpcValue);
+    if (typeof input !== "object" || input === null)
+        return input;
+    if ("__helyxDate" in input &&
+        typeof input.__helyxDate === "string")
+        return new Date(input.__helyxDate);
+    return Object.fromEntries(Object.entries(input).map(([key, value]) => [key, decodeIpcValue(value)]));
+}
+export function encodeNumericIpcValue(input) {
+    if (input instanceof Date)
+        return { __helyxDate: input.toISOString() };
+    if (Array.isArray(input))
+        return input.map(encodeNumericIpcValue);
+    if (typeof input !== "object" || input === null)
+        return input;
+    return Object.fromEntries(Object.entries(input).map(([key, value]) => [
+        key,
+        encodeNumericIpcValue(value),
+    ]));
+}
+function sameIdentity(left, right) {
+    return (left.generation === right.generation &&
+        left.deploymentOrder === right.deploymentOrder &&
+        left.supervisorId === right.supervisorId &&
+        left.shardId === right.shardId &&
+        left.shardCount === right.shardCount &&
+        left.fencingToken === right.fencingToken);
+}
+//# sourceMappingURL=numeric-write-behind-proxy.js.map

package/dist/numeric-write-behind-redis.d.ts

@@ -0,0 +1,123 @@
+import { type NumericWriteBehindCommittedBatch, type NumericWriteBehindControl, type NumericWriteBehindEnqueueInput, type NumericWriteBehindHealth, type NumericWriteBehindMemberScope, type NumericWriteBehindScope, type NumericWriteBehindService } from "@helyx/sdk";
+import { type NumericBatchWriter, type NumericWriteBehindRegistration } from "@helyx/platform";
+import type { ShardIdentity, ShardNumericRequest } from "./shard-contracts.js";
+interface RedisEvalClient {
+    connect(): Promise<unknown>;
+    quit(): Promise<unknown>;
+    eval(script: string, options: {
+        keys: readonly string[];
+        arguments: readonly string[];
+    }): Promise<unknown>;
+}
+export interface RedisNumericWriteBehindOptions {
+    redisUrl: string;
+    namespace: string;
+    writer: NumericBatchWriter;
+    registrations: readonly NumericWriteBehindRegistration[];
+    client?: RedisEvalClient;
+    flushIntervalMs?: number;
+    capacity?: number;
+    onError?: (error: Error) => void;
+    supervisorId?: string;
+    shardLeaseKeyPrefix?: string;
+    barrierLeaseMs?: number;
+    suppressionDrainTimeoutMs?: number;
+    suppressionPollMs?: number;
+}
+export declare class RedisNumericWriteBehindService implements NumericWriteBehindService, NumericWriteBehindControl {
+    #private;
+    constructor(options: RedisNumericWriteBehindOptions);
+    start(): Promise<void>;
+    enqueue(input: NumericWriteBehindEnqueueInput): Promise<{
+        outcome: "accepted" | "cooldown" | "suppressed" | "paused" | "capacity" | "unavailable";
+    }>;
+    enqueueFenced(input: NumericWriteBehindEnqueueInput, fence: {
+        shardId: number;
+        leaseKey: string;
+        leaseValue: string;
+    }): Promise<{
+        outcome: "accepted" | "cooldown" | "suppressed" | "paused" | "capacity" | "unavailable";
+    }>;
+    pendingMemberSnapshot(input: NumericWriteBehindMemberScope): Promise<{
+        increments: Readonly<Record<string, number>>;
+        maxima: Readonly<Record<string, Date>>;
+        oldestAcceptedAt: Date | null;
+    }>;
+    flushMember(input: NumericWriteBehindMemberScope): Promise<void>;
+    flushGuild(input: NumericWriteBehindScope & {
+        guildId: string;
+    }): Promise<void>;
+    flushSubject(input: NumericWriteBehindScope & {
+        subjectId: string;
+    }): Promise<void>;
+    flushModule(input: NumericWriteBehindScope): Promise<void>;
+    runMemberBarrier<Result>(input: NumericWriteBehindMemberScope, operation: () => Promise<Result>): Promise<Result>;
+    runGuildBarrier<Result>(input: NumericWriteBehindScope & {
+        guildId: string;
+    }, operation: () => Promise<Result>): Promise<Result>;
+    runSubjectBarrier<Result>(input: NumericWriteBehindScope & {
+        subjectId: string;
+    }, operation: () => Promise<Result>): Promise<Result>;
+    suppressSubject(input: NumericWriteBehindScope & {
+        subjectId: string;
+        cutoff: Date;
+    }): Promise<{
+        suppressionId: string;
+        discarded: number;
+    }>;
+    suppressGuild(input: NumericWriteBehindScope & {
+        guildId: string;
+    }): Promise<{
+        suppressionId: string;
+        discarded: number;
+    }>;
+    releaseGuild(input: NumericWriteBehindScope & {
+        guildId: string;
+        suppressionId: string;
+    }): Promise<{
+        released: boolean;
+    }>;
+    releaseSubject(input: NumericWriteBehindScope & {
+        subjectId: string;
+        suppressionId: string;
+    }): Promise<{
+        released: boolean;
+    }>;
+    clearMemberCooldown(input: NumericWriteBehindMemberScope): Promise<void>;
+    clearSubjectCooldown(input: NumericWriteBehindScope & {
+        subjectId: string;
+    }): Promise<void>;
+    subscribeCommitted(input: NumericWriteBehindScope, handler: (batch: NumericWriteBehindCommittedBatch) => void | Promise<void>): () => void;
+    health(): NumericWriteBehindHealth;
+    acquireBarrier(input: {
+        scope: NumericWriteBehindScope;
+        barrierType: "member" | "guild" | "subject";
+        guildId?: string;
+        subjectId?: string;
+    }): Promise<{
+        barrierId: string;
+    }>;
+    releaseBarrier(input: {
+        scope: NumericWriteBehindScope;
+        barrierType: "member" | "guild" | "subject";
+        guildId?: string;
+        subjectId?: string;
+        barrierId: string;
+    }): Promise<void>;
+    renewBarrier(input: {
+        scope: NumericWriteBehindScope;
+        barrierType: "member" | "guild" | "subject";
+        guildId?: string;
+        subjectId?: string;
+        barrierId: string;
+    }): Promise<void>;
+    stop(timeoutMs?: number): Promise<{
+        drained: boolean;
+    }>;
+}
+export declare function executeRedisNumericOperation(service: RedisNumericWriteBehindService, operation: ShardNumericRequest["operation"], fence?: {
+    identity: ShardIdentity;
+    shardLeaseKeyPrefix: string;
+}): Promise<unknown>;
+export {};
+//# sourceMappingURL=numeric-write-behind-redis.d.ts.map