@helyx/bot 0.4.9 → 0.4.13

package/dist/guilds.d.ts

@@ -2,5 +2,24 @@ import { type DatabasePool, type GuildShardOwnership } from "@helyx/database";
 import type { ModuleDefinition } from "@helyx/sdk";
 import { type Client } from "discord.js";
 import type { InteractionLogger } from "./interactions.js";
-export declare function installGuildTracking(client: Client, database: DatabasePool, modules: readonly ModuleDefinition[], logger: InteractionLogger, enabledByDefaultModuleIds?: ReadonlySet<string>, ownership?: GuildShardOwnership): (readyClient: Client<true>) => Promise<void>;
+export interface GuildReconciliationHealth {
+    status: "pending" | "running" | "healthy" | "failed" | "stopped";
+    lastStartedAt?: string;
+    lastSucceededAt?: string;
+    durationMs?: number;
+    examinedRows: number;
+    refreshedGuilds: number;
+    removedGuilds: number;
+    rejectedFences: number;
+    unavailableGuilds: number;
+    failureReasonCode?: string | undefined;
+    nextScheduledAt?: string | undefined;
+}
+export interface GuildTrackingPreparation {
+    (readyClient: Client<true>): Promise<void>;
+    reconcile(reason: "ready" | "resume" | "periodic"): Promise<void>;
+    health(): GuildReconciliationHealth;
+    stop(): void;
+}
+export declare function installGuildTracking(client: Client, database: DatabasePool, modules: readonly ModuleDefinition[], logger: InteractionLogger, enabledByDefaultModuleIds?: ReadonlySet<string>, ownership?: GuildShardOwnership, reconciliationIntervalMs?: number, shardCount?: number): GuildTrackingPreparation;
 //# sourceMappingURL=guilds.d.ts.map

package/dist/guilds.js

@@ -1,7 +1,24 @@
 import { InstallationRepository, } from "@helyx/database";
 import { Events } from "discord.js";
-export function installGuildTracking(client, database, modules, logger, enabledByDefaultModuleIds = new Set(), ownership) {
+const RECONCILIATION_PAGE_SIZE = 250;
+const DEFAULT_RECONCILIATION_INTERVAL_MS = 15 * 60 * 1_000;
+export function installGuildTracking(client, database, modules, logger, enabledByDefaultModuleIds = new Set(), ownership, reconciliationIntervalMs = DEFAULT_RECONCILIATION_INTERVAL_MS, shardCount) {
+    if (!Number.isSafeInteger(reconciliationIntervalMs) ||
+        reconciliationIntervalMs < 60_000)
+        throw new Error("Guild reconciliation interval must be at least one minute");
     const repository = new InstallationRepository(database);
+    let prepared = false;
+    let stopped = false;
+    let reconciliation;
+    let timer;
+    let health = {
+        status: "pending",
+        examinedRows: 0,
+        refreshedGuilds: 0,
+        removedGuilds: 0,
+        rejectedFences: 0,
+        unavailableGuilds: 0,
+    };
     async function syncGuild(guild) {
         const record = await repository.syncGuild({
             guildId: guild.id,
@@ -39,10 +56,16 @@ export function installGuildTracking(client, database, modules, logger, enabledB
     client.on(Events.GuildDelete, (guild) => {
         void repository
             .markGuildRemoved(guild.id, ownership)
+            .then((changed) => {
+            logger.info({
+                event: "guild.removed",
+                outcome: changed ? "changed" : "rejected_or_duplicate",
+            }, "Discord guild removal observation persisted");
+        })
             .catch((error) => {
             logger.error({
                 event: "guild.remove_failed",
-                guildId: guild.id,
+                reasonCode: "database_write_failed",
                 error: safeError(error),
             }, "Guild removal tracking failed");
         });
@@ -50,14 +73,131 @@ export function installGuildTracking(client, database, modules, logger, enabledB
     client.on(Events.GuildUnavailable, (guild) => {
         logger.warn({ event: "guild.unavailable", guildId: guild.id }, "Discord guild is temporarily unavailable; installation remains active");
     });
-    return async (readyClient) => {
-        for (const guild of readyClient.guilds.cache.values())
-            await syncGuild(guild);
-        logger.info({
-            event: "guilds.synchronised",
-            guildCount: readyClient.guilds.cache.size,
-        }, "Discord guild installations synchronised");
+    async function runReconciliation(reason) {
+        if (stopped || !prepared || !client.isReady())
+            return;
+        if (reconciliation)
+            return reconciliation;
+        reconciliation = (async () => {
+            const startedAt = Date.now();
+            health = {
+                ...health,
+                status: "running",
+                lastStartedAt: new Date(startedAt).toISOString(),
+                failureReasonCode: undefined,
+                nextScheduledAt: undefined,
+            };
+            let examinedRows = 0;
+            let refreshedGuilds = 0;
+            let removedGuilds = 0;
+            let rejectedFences = 0;
+            const observedGuildIds = new Set(client.guilds.cache.keys());
+            const unavailableGuilds = [...client.guilds.cache.values()].filter((guild) => !guild.available).length;
+            try {
+                for (const guild of client.guilds.cache.values()) {
+                    if (stopped)
+                        return;
+                    await syncGuild(guild);
+                    refreshedGuilds += 1;
+                }
+                let cursor;
+                do {
+                    if (stopped || !client.isReady())
+                        return;
+                    const page = await repository.listActiveGuildIdsForOwnership({
+                        ...(ownership ? { ownership } : {}),
+                        ...(ownership && shardCount !== undefined ? { shardCount } : {}),
+                        ...(cursor ? { cursor } : {}),
+                        limit: RECONCILIATION_PAGE_SIZE,
+                    });
+                    examinedRows += page.guildIds.length;
+                    if (ownership)
+                        await repository.adoptGuildsForReconciliation({
+                            guildIds: page.guildIds,
+                            ownership,
+                            shardCount: shardCount,
+                        });
+                    const absent = page.guildIds.filter((guildId) => !observedGuildIds.has(guildId));
+                    const result = await repository.markGuildsRemovedForReconciliation({
+                        guildIds: absent,
+                        ...(ownership ? { ownership } : {}),
+                    });
+                    removedGuilds += result.changed;
+                    rejectedFences += result.rejectedFence;
+                    cursor = page.nextCursor;
+                } while (cursor);
+                const completedAt = Date.now();
+                health = {
+                    status: "healthy",
+                    lastStartedAt: new Date(startedAt).toISOString(),
+                    lastSucceededAt: new Date(completedAt).toISOString(),
+                    durationMs: completedAt - startedAt,
+                    examinedRows,
+                    refreshedGuilds,
+                    removedGuilds,
+                    rejectedFences,
+                    unavailableGuilds,
+                    nextScheduledAt: new Date(completedAt + reconciliationIntervalMs).toISOString(),
+                };
+                logger.info({
+                    event: "guild.reconciliation_completed",
+                    reason,
+                    durationMs: health.durationMs,
+                    examinedRows,
+                    refreshedGuilds,
+                    removedGuilds,
+                    rejectedFences,
+                    unavailableGuilds,
+                }, "Discord guild presence reconciliation completed");
+            }
+            catch (error) {
+                health = {
+                    status: "failed",
+                    lastStartedAt: new Date(startedAt).toISOString(),
+                    durationMs: Date.now() - startedAt,
+                    examinedRows,
+                    refreshedGuilds,
+                    removedGuilds,
+                    rejectedFences,
+                    unavailableGuilds,
+                    failureReasonCode: "reconciliation_failed",
+                    nextScheduledAt: new Date(Date.now() + reconciliationIntervalMs).toISOString(),
+                };
+                logger.error({
+                    event: "guild.reconciliation_failed",
+                    reason,
+                    reasonCode: health.failureReasonCode,
+                    error: safeError(error),
+                }, "Discord guild presence reconciliation failed");
+            }
+        })().finally(() => {
+            reconciliation = undefined;
+        });
+        return reconciliation;
+    }
+    const prepare = async (readyClient) => {
+        if (stopped || !readyClient.isReady())
+            return;
+        prepared = true;
+        await runReconciliation("ready");
+        if (!timer) {
+            timer = setInterval(() => void runReconciliation("periodic"), reconciliationIntervalMs);
+            timer.unref();
+        }
+    };
+    client.on(Events.ShardResume, () => {
+        void runReconciliation("resume");
+    });
+    prepare.reconcile = runReconciliation;
+    prepare.health = () => ({ ...health });
+    prepare.stop = () => {
+        stopped = true;
+        if (timer)
+            clearInterval(timer);
+        timer = undefined;
+        health = { ...health, status: "stopped", nextScheduledAt: undefined };
     };
+    return prepare;
 }
 function safeError(error) {
     const value = error instanceof Error ? error : new Error(String(error));

package/dist/index.d.ts

@@ -9,5 +9,5 @@ export interface BotHandle {
 export declare function startBot(processEnvironment?: NodeJS.ProcessEnv): Promise<BotHandle>;
 export declare function resolveBotWorkerEntryPoint(entryUrl?: string): string;
 export declare function readBotVersion(): string;
-export declare function gatewayIntentsForModules(modules: readonly ModuleDefinition[]): GatewayIntentBits[];
+export declare function gatewayIntentsForModules(modules: readonly ModuleDefinition[], messageContentEnabled?: boolean): GatewayIntentBits[];
 //# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -1,6 +1,6 @@
 import { parseBotEnvironment } from "@helyx/config";
 import { safeError, ServiceRegistry } from "@helyx/core";
-import { checkDatabaseConnection, createDatabasePool, InteractionSessionRepository, RateLimitRepository, runCoreMigrations, runConfiguredModuleMigrations, } from "@helyx/database";
+import { checkDatabaseConnection, createDatabasePool, AuditRepository, InteractionSessionRepository, RateLimitRepository, runCoreMigrations, runConfiguredModuleMigrations, VerificationSetupRepository, } from "@helyx/database";
 import { createRuntime } from "@helyx/framework";
 import { createPlatformServices, PostgresPrivacyProviderExecutor, } from "@helyx/platform";
 import { HELYX_SERVICE_NAMES, } from "@helyx/sdk";
@@ -18,9 +18,10 @@ import { loadConfiguredModulePackages, platformServiceOptions, } from "./modules
 import { resolveModulePackageSpecifiers } from "./module-configuration.js";
 import { createPermissionsModule } from "./permissions-module.js";
 import { createManagementModule } from "./management-module.js";
-import { DiscordMemberRoleService, DiscordResourceInspection, installModuleEvents, } from "./events.js";
+import { DiscordMessageDeliveryService, DiscordMemberEnforcementService, DiscordMemberRoleService, DiscordVerificationMemberService, DiscordVerificationSetupService, DiscordResourceInspection, installModuleEvents, } from "./events.js";
 import { DiscordModuleLoggingService } from "./module-logging.js";
 import { BotControlService, createBotControlServer, DiscordGuildResourceDirectory, } from "./control-server.js";
+import { HttpVerificationService } from "./verification-service.js";
 import { startShardSupervisor } from "./shard-supervisor.js";
 import { parseShardWorkerLaunchContract, startShardWorker, } from "./shard-worker.js";
 import { createDeveloperOperationsModule } from "./developer-operations-module.js";
@@ -29,6 +30,7 @@ import { createSupportModule } from "./support-module.js";
 import { DiscordOwnedMessageDeletionService } from "./discord-owned-message-service.js";
 import { CoreResourceAuthorizationService } from "./resource-authorization.js";
 import { createLocalScheduledTaskRoute, createScheduledTaskRunner, schedulerOperationalHealth, } from "./scheduled-task-runner.js";
+import { createLocalNumericWriteBehind } from "./numeric-write-behind.js";
 export { loadConfiguredModulePackages } from "./modules.js";
 export { resolveModulePackageSpecifiers } from "./module-configuration.js";
 export * from "./control-server.js";
@@ -86,15 +88,17 @@ async function startUnshardedBot(processEnvironment) {
             verifiedMigrationCount: migrationResult.verified.length,
         }, "Core database ready");
         const cleanupExpiredCoreRecords = async () => {
-            const [sessions, rateLimits] = await Promise.all([
+            const [sessions, rateLimits, verificationAudit] = await Promise.all([
                 new InteractionSessionRepository(database).deleteExpired(),
                 new RateLimitRepository(database).deleteExpired(),
+                new AuditRepository(database).deleteModuleEventsOlderThanMonths("helyx.verification", 12),
             ]);
-            if (sessions > 0 || rateLimits > 0) {
+            if (sessions > 0 || rateLimits > 0 || verificationAudit > 0) {
                 bootstrapLogger.info({
                     event: "database.retention_cleaned",
                     interactionSessions: sessions,
                     rateLimitWindows: rateLimits,
+                    verificationAuditEvents: verificationAudit,
                 }, "Expired core records removed");
             }
         };
@@ -125,7 +129,7 @@ async function startUnshardedBot(processEnvironment) {
         }, "Module databases ready");
         const featureModules = modulePackages.map(({ definition }) => definition);
         const client = new Client({
-            intents: gatewayIntentsForModules(featureModules),
+            intents: gatewayIntentsForModules(featureModules, environment.HELYX_MESSAGE_CONTENT_ENABLED),
             partials: [Partials.Message, Partials.Channel, Partials.Reaction],
             allowedMentions: { parse: [] },
         });
@@ -234,15 +238,37 @@ async function startUnshardedBot(processEnvironment) {
             ...publicModules,
             ...(operationsModule ? [operationsModule] : []),
         ];
-        const platformServices = new Map(createPlatformServices(database, publicModules, platformServiceOptions(environment, publicModules)));
+        const platformServices = new Map();
+        const serviceAccess = new ServiceRegistry(platformServices);
+        for (const [name, service] of createPlatformServices(database, publicModules, {
+            ...platformServiceOptions(environment, publicModules),
+            activationServices: serviceAccess,
+        })) {
+            platformServices.set(name, service);
+        }
+        if (environment.HELYX_VERIFICATION_ENABLED &&
+            environment.HELYX_VERIFICATION_URL &&
+            environment.HELYX_VERIFICATION_INTERNAL_SECRET) {
+            platformServices.set(HELYX_SERVICE_NAMES.verification, new HttpVerificationService({
+                baseUrl: environment.HELYX_VERIFICATION_URL,
+                internalSecret: environment.HELYX_VERIFICATION_INTERNAL_SECRET,
+                installationId: environment.HELYX_VERIFICATION_INSTALLATION_ID,
+                publicSigningKeys: environment.HELYX_VERIFICATION_SIGNING_PUBLIC_KEYS,
+            }));
+            platformServices.set(HELYX_SERVICE_NAMES.verificationMembers, new DiscordVerificationMemberService(client));
+            platformServices.set(HELYX_SERVICE_NAMES.verificationSetup, new DiscordVerificationSetupService(client, new VerificationSetupRepository(database)));
+        }
+        const numericWriteBehind = createLocalNumericWriteBehind(platformServices, publicModules);
+        platformServices.set(HELYX_SERVICE_NAMES.numericWriteBehind, numericWriteBehind);
         platformServices.set(HELYX_SERVICE_NAMES.resourceAuthorization, new CoreResourceAuthorizationService(platformServices.get(HELYX_SERVICE_NAMES.permissions)));
+        platformServices.set(HELYX_SERVICE_NAMES.discordMessages, new DiscordMessageDeliveryService(client));
         platformServices.set(HELYX_SERVICE_NAMES.discordOwnedMessages, new DiscordOwnedMessageDeletionService(client));
+        platformServices.set(HELYX_SERVICE_NAMES.memberEnforcement, new DiscordMemberEnforcementService(client));
         platformServices.set(HELYX_SERVICE_NAMES.memberRoles, new DiscordMemberRoleService(client));
         platformServices.set(HELYX_SERVICE_NAMES.discordResources, new DiscordResourceInspection(client));
         if (featureModules.some(({ manifest }) => manifest.id === "helyx.logging")) {
             platformServices.set(HELYX_SERVICE_NAMES.moduleLogging, new DiscordModuleLoggingService(client, database, publicModules, bootstrapLogger));
         }
-        const serviceAccess = new ServiceRegistry(platformServices);
         const runtime = createRuntime({
             modules,
             logger: bootstrapLogger,
@@ -255,7 +281,7 @@ async function startUnshardedBot(processEnvironment) {
             ...(cloudManagementModule ? [cloudManagementModule.manifest.id] : []),
             ...(operationsModule ? [operationsModule.manifest.id] : []),
         ]);
-        const prepareGuilds = installGuildTracking(client, database, publicModules, bootstrapLogger, enabledCoreModuleIds);
+        const prepareGuilds = installGuildTracking(client, database, publicModules, bootstrapLogger, enabledCoreModuleIds, undefined, environment.HELYX_GUILD_RECONCILIATION_INTERVAL_SECONDS * 1_000);
         const commandsReady = installInteractions(client, modules, {
             ...(environment.DISCORD_INTERNAL_GUILD_ID
                 ? { internalGuildId: environment.DISCORD_INTERNAL_GUILD_ID }
@@ -287,6 +313,7 @@ async function startUnshardedBot(processEnvironment) {
             if (shuttingDown)
                 return;
             shuttingDown = true;
+            prepareGuilds.stop();
             process.off("SIGINT", onSigint);
             process.off("SIGTERM", onSigterm);
             if (retentionCleanupTimer)
@@ -305,14 +332,29 @@ async function startUnshardedBot(processEnvironment) {
                     process.exitCode = 1;
                     bootstrapLogger.error({ event: "control.stop_failed", error: safeError(error) }, "Private bot control shutdown failed");
                 });
-            try {
-                await moduleEvents.stop();
-                await runtime.stop();
-            }
-            catch (error) {
+            await moduleEvents.stop().catch((error) => {
+                process.exitCode = 1;
+                bootstrapLogger.error({ event: "module_events.stop_failed", error: safeError(error) }, "Module event shutdown failed");
+            });
+            await runtime.stop().catch((error) => {
                 process.exitCode = 1;
                 bootstrapLogger.error({ event: "runtime.stop_failed", error: safeError(error) }, "Runtime shutdown failed");
-            }
+            });
+            await numericWriteBehind
+                .stop()
+                .then(({ drained }) => {
+                if (drained)
+                    return;
+                process.exitCode = 1;
+                bootstrapLogger.error({ event: "numeric_write_behind.shutdown_not_drained" }, "Numeric write-behind exceeded its bounded shutdown drain");
+            })
+                .catch((error) => {
+                process.exitCode = 1;
+                bootstrapLogger.error({
+                    event: "numeric_write_behind.shutdown_failed",
+                    error: safeError(error),
+                }, "Numeric write-behind shutdown failed");
+            });
             await client.destroy();
             await closeDatabase();
         }
@@ -364,13 +406,26 @@ async function startUnshardedBot(processEnvironment) {
             await cloudConnector.stop().catch(() => undefined);
             if (controlServer)
                 await controlServer.close().catch(() => undefined);
-            try {
-                await moduleEvents.stop();
-                await runtime.stop();
-            }
-            catch (stopError) {
+            await moduleEvents.stop().catch((stopError) => {
+                bootstrapLogger.error({
+                    event: "module_events.cleanup_failed",
+                    error: safeError(stopError),
+                }, "Module event cleanup failed");
+            });
+            await runtime.stop().catch((stopError) => {
                 bootstrapLogger.error({ event: "runtime.cleanup_failed", error: safeError(stopError) }, "Runtime cleanup failed");
-            }
+            });
+            const numericCleanup = await numericWriteBehind
+                .stop()
+                .catch((stopError) => {
+                bootstrapLogger.error({
+                    event: "numeric_write_behind.cleanup_failed",
+                    error: safeError(stopError),
+                }, "Numeric write-behind cleanup failed");
+                return { drained: false };
+            });
+            if (!numericCleanup.drained)
+                bootstrapLogger.error({ event: "numeric_write_behind.cleanup_not_drained" }, "Numeric write-behind cleanup did not drain");
             await client.destroy();
             throw error;
         }
@@ -407,16 +462,27 @@ function deploymentReference(processEnvironment) {
         processEnvironment.GIT_COMMIT_SHA;
     return value?.trim().slice(0, 12) || undefined;
 }
-export function gatewayIntentsForModules(modules) {
+export function gatewayIntentsForModules(modules, messageContentEnabled = false) {
     const intents = [GatewayIntentBits.Guilds];
     if (modules.some((module) => module.events?.messageReactionAdd?.length ||
         module.events?.messageReactionRemove?.length)) {
         intents.push(GatewayIntentBits.GuildMessageReactions);
     }
-    if (modules.some((module) => module.events?.messageDelete?.length)) {
+    const hasPrivilegedMessageCreate = modules.some((module) => module.events?.privilegedMessageCreate?.length);
+    const requiresMessageContent = modules.some((module) => module.requiredDiscordCapabilities?.includes("message-content"));
+    if (((hasPrivilegedMessageCreate || requiresMessageContent) &&
+        messageContentEnabled) ||
+        modules.some((module) => module.events?.guildMessageCreate?.length ||
+            module.events?.messageDelete?.length)) {
         intents.push(GatewayIntentBits.GuildMessages);
     }
-    if (modules.some((module) => module.events?.guildMemberAdd?.length)) {
+    if ((hasPrivilegedMessageCreate || requiresMessageContent) &&
+        messageContentEnabled) {
+        intents.push(GatewayIntentBits.MessageContent);
+    }
+    if (modules.some((module) => module.requiredDiscordCapabilities?.includes("guild-members") ||
+        module.events?.guildMemberAdd?.length ||
+        module.events?.guildMemberRemove?.length)) {
         intents.push(GatewayIntentBits.GuildMembers);
     }
     if (modules.some((module) => module.events?.guildEmojiDelete?.length ||