@wolfstar/plugin-gateway 0.2.0-next-20260926221949 → 0.2.0-next-20260926222321

package/dist/esm/index.js

@@ -1,5 +1,5 @@
 import { Client, Listener, container } from "@wolfstar/http-framework";
-import { WebSocketManager, WebSocketShardEvents } from "@discordjs/ws";
+import { CloseCodes, DefaultWebSocketManagerOptions, WebSocketManager, WebSocketShardEvents } from "@discordjs/ws";
 import { Client as Client$1 } from "@discordjs/core";
 import { applyGatewayDispatch, autoModerationRuleKey, banKey, emojiKey, integrationKey, inviteKey, memberKey, messageKey, presenceKey, roleKey, scheduledEventKey, soundboardSoundKey, stageInstanceKey, stickerKey, threadMemberKey, voiceStateKey } from "@wolfstar/plugin-cache";
 import { ActivityFlags, ActivityType, AttachmentFlags, AuditLogEvent, ChannelFlags, ChannelType, FormattingPatterns, GatewayDispatchEvents, GatewayIntentBits, GatewayOpcodes, GuildFeature, GuildMemberFlags, GuildPremiumTier, GuildScheduledEventStatus, GuildSystemChannelFlags, GuildWidgetStyle, InviteType, MessageFlags, MessageReferenceType, MessageType, OverwriteType, PermissionFlagsBits, PresenceUpdateStatus, RoleFlags, RouteBases, Routes, StickerFormatType, UserFlags, WebhookType } from "discord-api-types/v10";
@@ -6915,6 +6915,29 @@ var GuildMembersRateLimitError = class extends Error {
 		this.retryAfter = retryAfter;
 	}
 };
+/**
+* Emitted as an `error` when `GatewayClientOptions.sessionStore` fails to read or write the session of a shard.
+*
+* @remarks
+* Neither failure stops the shard: a failed (or timed out) read identifies instead of resuming, and a failed write
+* only means the session may not be resumed after a restart. The store's error is the `cause`.
+*/
+var GatewaySessionStoreError = class extends Error {
+	/**
+	* Whether the store failed to read (`"get"`) or write (`"set"`) the session.
+	*/
+	operation;
+	/**
+	* The shard whose session was read or written.
+	*/
+	shardId;
+	constructor(operation, shardId, cause) {
+		super(`Cannot ${operation === "get" ? "read" : "write"} the session of shard ${shardId} in the session store`, { cause });
+		this.name = "GatewaySessionStoreError";
+		this.operation = operation;
+		this.shardId = shardId;
+	}
+};
 
 //#endregion
 //#region src/managers/GuildMemberManager.ts
@@ -11206,6 +11229,79 @@ var DispatchQueue = class {
 	}
 };
 
+//#endregion
+//#region src/util/sessions.ts
+/**
+* Sits between `@discordjs/ws` and a {@link GatewaySessionStore}, which `@discordjs/ws` would otherwise read on every
+* dispatch and heartbeat, and write on every sequence change, while holding the dispatch back.
+*
+* @remarks
+* The session of a shard is read from the store once, when the shard first connects, then served from memory. Writes
+* never hold a dispatch back either: they run in the background, one at a time per shard, and the ones queued while a
+* write is in flight collapse into a single write of the latest session. A stored sequence is therefore slightly
+* behind after a crash, which Discord handles by replaying the dispatches since then.
+*
+* @internal
+*/
+var GatewaySessionMirror = class {
+	#store;
+	#timeout;
+	#onError;
+	#sessions = /* @__PURE__ */ new Map();
+	#pending = /* @__PURE__ */ new Map();
+	#writes = /* @__PURE__ */ new Map();
+	constructor(store, timeout, onError) {
+		this.#store = store;
+		this.#timeout = timeout;
+		this.#onError = onError;
+	}
+	async get(shardId) {
+		if (this.#sessions.has(shardId)) return this.#sessions.get(shardId);
+		const session = await this.read(shardId);
+		if (!this.#sessions.has(shardId)) this.#sessions.set(shardId, session);
+		return this.#sessions.get(shardId);
+	}
+	set(shardId, info) {
+		this.#sessions.set(shardId, info);
+		const queued = this.#pending.has(shardId);
+		this.#pending.set(shardId, info);
+		if (queued) return;
+		const previous = this.#writes.get(shardId) ?? Promise.resolve();
+		this.#writes.set(shardId, previous.then(() => this.write(shardId)));
+	}
+	/**
+	* Resolves once every session written so far reached the store.
+	*/
+	async flush() {
+		await Promise.all(this.#writes.values());
+	}
+	async read(shardId) {
+		let timer;
+		try {
+			const read = Promise.resolve(this.#store.get(shardId));
+			if (this.#timeout === null) return await read;
+			const timeout = this.#timeout;
+			return await Promise.race([read, new Promise((_, reject) => {
+				timer = setTimeout(() => reject(/* @__PURE__ */ new Error(`Timed out after ${timeout}ms`)), timeout);
+			})]);
+		} catch (error) {
+			this.#onError(new GatewaySessionStoreError("get", shardId, error));
+			return null;
+		} finally {
+			if (timer) clearTimeout(timer);
+		}
+	}
+	async write(shardId) {
+		const info = this.#pending.get(shardId);
+		this.#pending.delete(shardId);
+		try {
+			await this.#store.set(shardId, info);
+		} catch (error) {
+			this.#onError(new GatewaySessionStoreError("set", shardId, error));
+		}
+	}
+};
+
 //#endregion
 //#region src/GatewayClient.ts
 /**
@@ -11267,6 +11363,9 @@ var GatewayClient = class extends Client {
 	dispatchTimeout;
 	#queue = new DispatchQueue();
 	#shardCount;
+	#sessions = null;
+	#keepSessions = false;
+	#destroying = null;
 	constructor(options) {
 		super(options);
 		container.gatewayClient = this;
@@ -11288,6 +11387,7 @@ var GatewayClient = class extends Client {
 		this.presences = new PresenceManager(this);
 		this.gateway = new WebSocketManager({
 			...options.gateway,
+			...this.sessionCallbacks(options),
 			token: options.discordToken ?? process.env.DISCORD_TOKEN,
 			intents: options.intents,
 			rest: container.rest,
@@ -11322,9 +11422,33 @@ var GatewayClient = class extends Client {
 	}
 	/**
 	* Disconnects every shard from the gateway. The HTTP server, if listening, is left untouched.
+	*
+	* @remarks
+	* By default, the shards close their sessions, which Discord invalidates. Pass `resumable: true` to keep them
+	* resumable instead, e.g. on a graceful shutdown before a deploy. Either way, it waits for the sessions to be
+	* written to {@link GatewayClientOptions.sessionStore}.
+	*
+	* A call made while another one is still disconnecting the shards joins it, keeping the first call's `resumable`.
+	*
+	* @param options Whether to keep the sessions resumable.
 	*/
-	async destroy() {
-		await this.gateway.destroy();
+	destroy(options = {}) {
+		this.#destroying ??= this.disconnect(options.resumable ?? false).finally(() => {
+			this.#destroying = null;
+		});
+		return this.#destroying;
+	}
+	async disconnect(resumable) {
+		this.#keepSessions = resumable;
+		try {
+			await this.gateway.destroy(this.#keepSessions ? {
+				code: CloseCodes.Resuming,
+				reason: "Resumable shutdown"
+			} : {});
+		} finally {
+			this.#keepSessions = false;
+		}
+		await this.#sessions?.flush();
 		await this.idle();
 	}
 	/**
@@ -11503,6 +11627,23 @@ var GatewayClient = class extends Client {
 			if (timer) clearTimeout(timer);
 		}
 	}
+	sessionCallbacks(options) {
+		const { sessionStore, gateway } = options;
+		if (sessionStore && (gateway?.retrieveSessionInfo || gateway?.updateSessionInfo)) throw new TypeError("sessionStore replaces gateway.retrieveSessionInfo and gateway.updateSessionInfo, pass one or the other");
+		let retrieve = gateway?.retrieveSessionInfo ?? DefaultWebSocketManagerOptions.retrieveSessionInfo;
+		let update = gateway?.updateSessionInfo ?? DefaultWebSocketManagerOptions.updateSessionInfo;
+		if (sessionStore) {
+			const timeout = options.sessionStoreTimeout === void 0 ? 5e3 : options.sessionStoreTimeout;
+			const sessions = new GatewaySessionMirror(sessionStore, timeout, (error) => this.reportError(error, `the session store ${error.operation}`, error.shardId));
+			this.#sessions = sessions;
+			retrieve = (shardId) => sessions.get(shardId);
+			update = (shardId, info) => sessions.set(shardId, info);
+		}
+		return {
+			retrieveSessionInfo: retrieve,
+			updateSessionInfo: (shardId, info) => info === null && this.#keepSessions ? void 0 : update(shardId, info)
+		};
+	}
 	reportError(error, type, shardId) {
 		if (this.listenerCount("error") > 0) this.emit("error", error);
 		else this.logger.error(`[Gateway] [Shard ${shardId}] Failed to process ${type}:`, error);
@@ -11547,5 +11688,5 @@ function RegisterAsGatewayListener(event, options = {}) {
 }
 
 //#endregion
-export { Action, ActionsManager, Activity, ActivityFlagsBitField, AnnouncementChannel, AnnouncementThreadChannel, AnonymousGuild, AppliedTagsMixin, Attachment, AttachmentFlagsBitField, AutoModerationActionExecution, AutoModerationRule, AutoModerationRuleManager, BaseChannel, BaseChannelMixin, BaseInvite, BitField, CachedManager, CategoryChannel, Channel, ChannelFlagsBitField, ChannelManager, ChannelMessageManager, ChannelOwnerMixin, ChannelParentMixin, ChannelPermissionMixin, ChannelSlowmodeMixin, ChannelThreadManager, ChannelThreadsMixin, ChannelTopicMixin, ChannelWebhooksMixin, ClientUser, DMChannel, DMChannelMixin, DispatchAction, DispatchHandlers, DispatchQueue, DispatchTimeoutError, Embed, Emoji, EventGatewayListener, ForumChannel, GatewayClient, GroupDMChannel, GroupDMInvite, GroupDMMixin, Guild, GuildAuditLogsEntry, GuildBan, GuildBanManager, GuildChannelManager, GuildChannelMixin, GuildEmoji, GuildEmojiManager, GuildEmojiRoleManager, GuildIntegrationManager, GuildInvite, GuildInviteManager, GuildManager, GuildMember, GuildMemberFlagsBitField, GuildMemberManager, GuildMemberRoleManager, GuildMembersRateLimitError, GuildMembersTimeoutError, GuildOnboarding, GuildOnboardingPrompt, GuildOnboardingPromptOption, GuildPreview, GuildScheduledEvent, GuildScheduledEventManager, GuildSoundboardSoundManager, GuildStickerManager, GuildTemplate, GuildTemplateManager, Integration, IntentsBitField, InviteGuild, MediaChannel, Message, MessageFlagsBitField, MessageManager, MessageMentions, MessageReaction, Mixin, MultiDispatchAction, MultiDispatchHandlers, NumberFlagsBitField, PermissionOverwriteManager, PermissionOverwrites, PermissionsBitField, Poll, PollAnswer, Presence, PresenceManager, PrivateThreadChannel, PublicThreadChannel, ReactionEmoji, ReactionManager, ReactionUserManager, RegisterAsGatewayListener, RichPresenceAssets, Role, RoleFlagsBitField, RoleManager, SoundboardSound, StageChannel, StageInstance, StageInstanceManager, Sticker, StickerPack, Structure, SystemChannelFlagsBitField, TextChannel, TextChannelMixin, ThreadChannelMemberManager, ThreadChannelMixin, ThreadManager, ThreadMember, ThreadMemberManager, ThreadOnlyChannelMixin, Typing, User, UserFlagsBitField, UserManager, VoiceChannel, VoiceChannelMixin, VoiceState, VoiceStateManager, Webhook, WebhookManager, WelcomeScreen, Widget, WidgetMember, compareRolePositions, computeChannelPermissions, computeGuildPermissions, computePermissionsIn, computeTargetPermissions, createChannel, createInvite, dispatchPartition, getGatewayClient, isDeepEqual, isThreadChannelType, kClone, kData, kPatch, kRelations, resolveId, resolveMessageOptions, resolveOverwriteOptions, snowflakeTimestamp, toAPIOverwrite, toChannelBody };
+export { Action, ActionsManager, Activity, ActivityFlagsBitField, AnnouncementChannel, AnnouncementThreadChannel, AnonymousGuild, AppliedTagsMixin, Attachment, AttachmentFlagsBitField, AutoModerationActionExecution, AutoModerationRule, AutoModerationRuleManager, BaseChannel, BaseChannelMixin, BaseInvite, BitField, CachedManager, CategoryChannel, Channel, ChannelFlagsBitField, ChannelManager, ChannelMessageManager, ChannelOwnerMixin, ChannelParentMixin, ChannelPermissionMixin, ChannelSlowmodeMixin, ChannelThreadManager, ChannelThreadsMixin, ChannelTopicMixin, ChannelWebhooksMixin, ClientUser, DMChannel, DMChannelMixin, DispatchAction, DispatchHandlers, DispatchQueue, DispatchTimeoutError, Embed, Emoji, EventGatewayListener, ForumChannel, GatewayClient, GatewaySessionStoreError, GroupDMChannel, GroupDMInvite, GroupDMMixin, Guild, GuildAuditLogsEntry, GuildBan, GuildBanManager, GuildChannelManager, GuildChannelMixin, GuildEmoji, GuildEmojiManager, GuildEmojiRoleManager, GuildIntegrationManager, GuildInvite, GuildInviteManager, GuildManager, GuildMember, GuildMemberFlagsBitField, GuildMemberManager, GuildMemberRoleManager, GuildMembersRateLimitError, GuildMembersTimeoutError, GuildOnboarding, GuildOnboardingPrompt, GuildOnboardingPromptOption, GuildPreview, GuildScheduledEvent, GuildScheduledEventManager, GuildSoundboardSoundManager, GuildStickerManager, GuildTemplate, GuildTemplateManager, Integration, IntentsBitField, InviteGuild, MediaChannel, Message, MessageFlagsBitField, MessageManager, MessageMentions, MessageReaction, Mixin, MultiDispatchAction, MultiDispatchHandlers, NumberFlagsBitField, PermissionOverwriteManager, PermissionOverwrites, PermissionsBitField, Poll, PollAnswer, Presence, PresenceManager, PrivateThreadChannel, PublicThreadChannel, ReactionEmoji, ReactionManager, ReactionUserManager, RegisterAsGatewayListener, RichPresenceAssets, Role, RoleFlagsBitField, RoleManager, SoundboardSound, StageChannel, StageInstance, StageInstanceManager, Sticker, StickerPack, Structure, SystemChannelFlagsBitField, TextChannel, TextChannelMixin, ThreadChannelMemberManager, ThreadChannelMixin, ThreadManager, ThreadMember, ThreadMemberManager, ThreadOnlyChannelMixin, Typing, User, UserFlagsBitField, UserManager, VoiceChannel, VoiceChannelMixin, VoiceState, VoiceStateManager, Webhook, WebhookManager, WelcomeScreen, Widget, WidgetMember, compareRolePositions, computeChannelPermissions, computeGuildPermissions, computePermissionsIn, computeTargetPermissions, createChannel, createInvite, dispatchPartition, getGatewayClient, isDeepEqual, isThreadChannelType, kClone, kData, kPatch, kRelations, resolveId, resolveMessageOptions, resolveOverwriteOptions, snowflakeTimestamp, toAPIOverwrite, toChannelBody };
 //# sourceMappingURL=index.js.map