@zhin.js/adapter-discord 1.1.3 → 1.1.5

package/lib/protocol.d.ts

@@ -1,4 +1,3 @@
-/** Discord Gateway protocol helpers. Canonicalization is owned by Core. */
 import { type ConversationRef } from '@zhin.js/im-contract';
 import type { Segment } from '@zhin.js/core/runtime';
 export interface DiscordActivity {
@@ -12,6 +11,9 @@ export interface DiscordEndpointConfig {
     readonly token: string;
     /** Default `gateway`. `interactions` uses httpHostToken POST + Ed25519 verify. */
     readonly connection?: 'gateway' | 'interactions';
+    /** Test instance only: ws://127.0.0.1:PORT/ fault proxy. */
+    readonly restApiProxy?: import('./rest-api-proxy.js').DiscordRestApiProxy;
+    readonly gatewayFaultProxyUrl?: string;
     readonly intents?: readonly number[];
     readonly enableSlashCommands?: boolean;
     readonly globalCommands?: boolean;
@@ -27,6 +29,9 @@ export interface ResolvedDiscordGatewayConfig {
     readonly connection: 'gateway';
     readonly id: string;
     readonly token: string;
+    /** Test instance only: ws://127.0.0.1:PORT/ fault proxy. */
+    readonly restApiProxy?: import('./rest-api-proxy.js').DiscordRestApiProxy;
+    readonly gatewayFaultProxyUrl?: string;
     readonly intents?: readonly number[];
     readonly enableSlashCommands: boolean;
     readonly globalCommands: boolean;
@@ -70,6 +75,7 @@ export interface DiscordInboundMessage {
     readonly mentionedBot?: boolean;
 }
 export interface DiscordButtonInbound {
+    readonly guildId?: string;
     readonly id: string;
     readonly customId: string;
     readonly channelId: string;
@@ -94,6 +100,10 @@ export interface DiscordOutboundActionRow {
     components: DiscordOutboundComponentButton[];
 }
 export interface DiscordOutboundBody {
+    readonly reply?: {
+        readonly messageReference: string;
+        readonly failIfNotExists: boolean;
+    };
     readonly content?: string;
     readonly embeds?: ReadonlyArray<Record<string, unknown>>;
     readonly files?: ReadonlyArray<{

package/lib/protocol.js

@@ -1,9 +1,14 @@
+import { validateDiscordGatewayFaultProxy } from './gateway-fault-proxy.js';
 /** Discord Gateway protocol helpers. Canonicalization is owned by Core. */
 import { createPublicKey, verify as cryptoVerify } from 'node:crypto';
 import { isMediaRef } from '@zhin.js/im-contract';
 import { formatCompact, getLogger } from '@zhin.js/logger';
 const logger = getLogger('discord');
 export function resolveDiscordConfig(config) {
+    if (config.restApiProxy && (!Number.isInteger(config.restApiProxy.port) || config.restApiProxy.port < 1 || config.restApiProxy.port > 65535))
+        throw new TypeError('Invalid Discord restApiProxy port');
+    if (config.restApiProxy && config.connection === 'interactions')
+        throw new TypeError('Discord restApiProxy requires gateway mode');
     const id = requiredEndpointField(config.id, 'id');
     const token = requiredEndpointField(config.token, 'token');
     const connection = config.connection ?? 'gateway';
@@ -25,6 +30,8 @@ export function resolveDiscordConfig(config) {
         connection: 'gateway',
         id,
         token,
+        ...(config.restApiProxy ? { restApiProxy: config.restApiProxy } : {}),
+        gatewayFaultProxyUrl: config.gatewayFaultProxyUrl ? validateDiscordGatewayFaultProxy(config.gatewayFaultProxyUrl) : undefined,
         intents: config.intents,
         enableSlashCommands: config.enableSlashCommands === true,
         globalCommands: config.globalCommands === true,
@@ -168,6 +175,7 @@ export function formatOutboundBody(payload) {
     const embeds = [];
     const files = [];
     let components;
+    let reply;
     for (const item of segments) {
         if (typeof item === 'string') {
             content += item;
@@ -209,8 +217,13 @@ export function formatOutboundBody(payload) {
                     }));
                     break;
                 }
+                const extension = {
+                    'image/png': 'png', 'image/jpeg': 'jpg', 'image/gif': 'gif',
+                    'image/webp': 'webp', 'audio/mpeg': 'mp3', 'audio/ogg': 'ogg',
+                    'audio/wav': 'wav', 'video/mp4': 'mp4', 'video/webm': 'webm',
+                }[media.mime_type?.split(';')[0].trim().toLowerCase() ?? ''];
                 const name = media.file_name
-                    ?? (typeof data.name === 'string' && data.name ? data.name : item.type);
+                    ?? (typeof data.name === 'string' && data.name ? data.name : `${item.type}${extension ? `.${extension}` : ''}`);
                 if (media.kind === 'url') {
                     files.push({ name, url: media.value });
                 }
@@ -231,6 +244,14 @@ export function formatOutboundBody(payload) {
                 }
                 break;
             }
+            case 'reply':
+                if (typeof data.message_id === 'string' && data.message_id) {
+                    reply = { messageReference: data.message_id, failIfNotExists: true };
+                }
+                break;
+            case 'share':
+                embeds.push({ title: String(data.title ?? ''), url: String(data.url ?? ''), description: String(data.description ?? data.content ?? ''), ...(data.image ? { image: { url: String(data.image) } } : {}) });
+                break;
             case 'embed':
                 embeds.push({ ...data });
                 break;
@@ -259,6 +280,7 @@ export function formatOutboundBody(payload) {
         ...(embeds.length > 0 ? { embeds: embeds.slice(0, 10) } : {}),
         ...(files.length > 0 ? { files } : {}),
         ...(components ? { components } : {}),
+        ...(reply ? { reply } : {}),
     };
 }
 export function activityTypeCode(type) {

package/lib/rest-api-proxy.d.ts

@@ -0,0 +1,8 @@
+import { Agent } from 'undici';
+export interface DiscordRestApiProxy {
+    readonly port: number;
+}
+/** JSON REST only, fixed Discord TLS identity and loopback TCP route. */
+export declare function createDiscordRestApiAgent(proxy: DiscordRestApiProxy): Agent & {
+    destroyProxy(): Promise<void>;
+};

package/lib/rest-api-proxy.js

@@ -0,0 +1,47 @@
+import tls from 'node:tls';
+import { Agent } from 'undici';
+/** JSON REST only, fixed Discord TLS identity and loopback TCP route. */
+export function createDiscordRestApiAgent(proxy) {
+    const pending = new Set();
+    let closed = false;
+    const agent = new Agent({ connect(options, callback) {
+            if (closed) {
+                queueMicrotask(() => callback(new Error('Discord REST proxy stopped'), null));
+                return;
+            }
+            if (options.hostname !== 'discord.com' || options.protocol !== 'https:' || Number(options.port || 443) !== 443) {
+                queueMicrotask(() => callback(new Error('Discord REST proxy rejected destination identity'), null));
+                return;
+            }
+            const socket = tls.connect({ host: '127.0.0.1', port: proxy.port,
+                servername: 'discord.com', rejectUnauthorized: true, ALPNProtocols: ['http/1.1'] });
+            let complete = false;
+            const finish = (error) => {
+                if (complete)
+                    return;
+                complete = true;
+                pending.delete(cancel);
+                clearTimeout(timer);
+                socket.off('error', onError);
+                if (error) {
+                    socket.destroy();
+                    callback(error, null);
+                }
+                else
+                    callback(null, socket);
+            };
+            const cancel = () => finish(new Error('Discord REST proxy stopped'));
+            pending.add(cancel);
+            const onError = (error) => finish(error);
+            const timer = setTimeout(() => finish(new Error('Discord REST proxy TLS connection timed out')), 10_000);
+            timer.unref();
+            socket.once('error', onError);
+            socket.once('secureConnect', () => finish());
+        } });
+    return Object.assign(agent, { async destroyProxy() {
+            closed = true;
+            for (const cancel of [...pending])
+                cancel();
+            await agent.destroy();
+        } });
+}

package/lib/side-event-dispatch.js

@@ -1,18 +1,17 @@
-import { buildNotice, senderFromId } from '@zhin.js/core';
+import { composeSideEventName, buildNotice, senderFromId } from '@zhin.js/core';
 import { formatCompact } from '@zhin.js/logger';
 export function receiveDiscordGuildMemberSideEvent(emit, configId, kind, event, logger) {
     if (!emit)
         return;
     void emit('notice.receive', buildNotice(event, {
-        $id: `discord:guild_member:${kind}:${event.guildId}:${event.userId}:${Date.now()}`,
-        $adapter: 'discord',
-        $endpoint: configId,
-        $type: 'notice',
-        $scene_id: event.guildId,
-        $scene_type: 'group',
-        $sub_type: kind,
-        $actor: senderFromId(event.userId, event.userName),
-        $timestamp: Date.now(),
+        id: `discord:guild_member:${kind}:${event.guildId}:${event.userId}:${Date.now()}`,
+        clientAdapter: 'discord',
+        endpointId: configId,
+        type: 'notice',
+        // Guild membership does not identify a replyable channel.
+        name: composeSideEventName('notice', 'group', kind),
+        target: senderFromId(event.userId, event.userName),
+        timestamp: Date.now(),
     })).catch((err) => {
         logger.warn(formatCompact({
             op: 'discord_side_event_failed',

package/lib/webhook.d.ts

@@ -3,11 +3,12 @@
  */
 import type { IncomingMessage, ServerResponse } from 'node:http';
 import type { HttpHost, HttpRouteRegistration } from '@zhin.js/host-http';
-import { type DiscordInboundMessage, type ResolvedDiscordInteractionsConfig } from './protocol.js';
+import { type DiscordInboundMessage, type DiscordButtonInbound, type ResolvedDiscordInteractionsConfig } from './protocol.js';
 export interface DiscordInteractionsHandler {
     readonly config: ResolvedDiscordInteractionsConfig;
     readonly isOpen: boolean;
     admit(msg: DiscordInboundMessage): void;
+    admitButton(interaction: DiscordButtonInbound): void;
     admitPlatform(event: Record<string, unknown>): void;
 }
 export declare function registerDiscordInteractionRoutes(http: HttpHost, handler: DiscordInteractionsHandler): HttpRouteRegistration[];

package/lib/webhook.js

@@ -37,6 +37,20 @@ export async function handleDiscordInteractionRequest(request, response, handler
             writeJson(response, 200, { type: INTERACTION_RESPONSE_PONG });
             return;
         }
+        if (interaction.type === 3) {
+            const data = interaction.data;
+            if (data?.component_type === 2 && typeof data.custom_id === 'string') {
+                if (!handler.isOpen) {
+                    response.writeHead(503);
+                    response.end('Unavailable');
+                    return;
+                }
+                const message = interactionToInboundMessage(interaction);
+                handler.admitButton({ id: message.id, customId: data.custom_id, channelId: message.channelId, channelKind: message.channelKind, userId: message.authorId, userName: message.authorName, ...(message.guildId ? { guildId: message.guildId } : {}), sourceMessageId: interaction.message?.id });
+                writeJson(response, 200, { type: 6 });
+                return;
+            }
+        }
         if (interaction.type === INTERACTION_TYPE_APPLICATION_COMMAND) {
             if (handler.isOpen) {
                 handler.admit(interactionToInboundMessage(interaction));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhin.js/adapter-discord",
-  "version": "1.1.3",
+  "version": "1.1.5",
   "description": "Zhin.js Discord adapter for Plugin Runtime (Gateway WebSocket)",
   "type": "module",
   "main": "./lib/index.js",
@@ -33,23 +33,26 @@
   },
   "dependencies": {
     "discord.js": "^14.27.0",
-    "@zhin.js/adapter": "1.1.15",
-    "@zhin.js/agent-feature": "1.1.2",
-    "@zhin.js/core": "1.1.38",
+    "@discordjs/ws": "1.2.3",
+    "@discordjs/collection": "2.1.1",
+    "undici": "6.28.0",
+    "@zhin.js/adapter": "1.1.16",
+    "@zhin.js/agent-feature": "1.1.3",
+    "@zhin.js/core": "1.1.40",
     "@zhin.js/feature-kit": "1.1.2",
-    "@zhin.js/host-http": "1.1.2",
-    "@zhin.js/im-contract": "1.1.2",
+    "@zhin.js/host-http": "1.1.3",
+    "@zhin.js/im-contract": "1.1.3",
     "@zhin.js/logger": "1.1.1",
-    "@zhin.js/permission": "1.1.2",
-    "@zhin.js/skill": "1.1.2",
-    "@zhin.js/tool": "1.1.2"
+    "@zhin.js/permission": "1.1.3",
+    "@zhin.js/skill": "1.1.3",
+    "@zhin.js/tool": "1.1.3"
   },
   "peerDependencies": {
     "zod": "^4.0.0",
-    "@zhin.js/adapter": "^1.1.15",
-    "@zhin.js/command": "^1.1.2",
-    "@zhin.js/core": "^1.1.38",
-    "zhin.js": "^1.1.3"
+    "@zhin.js/adapter": "^1.1.16",
+    "@zhin.js/command": "^1.1.4",
+    "@zhin.js/core": "^1.1.40",
+    "zhin.js": "^1.1.5"
   },
   "peerDependenciesMeta": {
     "@zhin.js/command": {
@@ -67,8 +70,8 @@
     "typescript": "^6.0.3",
     "vitest": "^4.1.10",
     "zod": "^4.4.3",
-    "@zhin.js/host-http": "1.1.2",
-    "zhin.js": "1.1.3"
+    "@zhin.js/host-http": "1.1.3",
+    "zhin.js": "1.1.5"
   },
   "files": [
     "adapters",

package/schema.json

@@ -185,6 +185,26 @@
           "id": {
             "type": "string",
             "description": "Discord bot name"
+          },
+          "gatewayFaultProxyUrl": {
+            "type": "string",
+            "pattern": "^(?:ws://127\\.0\\.0\\.1:[0-9]+/?|\\$\\{[A-Za-z_][A-Za-z0-9_]*\\})$",
+            "description": "Isolated acceptance only: loopback Gateway fault proxy; REST unchanged."
+          },
+          "restApiProxy": {
+            "type": "object",
+            "additionalProperties": false,
+            "properties": {
+              "port": {
+                "type": "integer",
+                "minimum": 1,
+                "maximum": 65535
+              }
+            },
+            "required": [
+              "port"
+            ],
+            "description": "Gateway测试实例REST专用故障代理：discord.com:443固定loopback TCP，保留SNI/证书校验，独立于Gateway代理"
           }
         },
         "required": [
@@ -197,6 +217,11 @@
       "type": "string",
       "default": "",
       "description": "命令前缀（默认 '' 无前缀，任意文本按命令匹配；如 '/' 要求 / 开头）。endpoints[i] 可逐项覆盖"
+    },
+    "gatewayFaultProxyUrl": {
+      "type": "string",
+      "pattern": "^(?:ws://127\\.0\\.0\\.1:[0-9]+/?|\\$\\{[A-Za-z_][A-Za-z0-9_]*\\})$",
+      "description": "Isolated acceptance only: loopback Gateway fault proxy; REST unchanged."
     }
   },
   "required": [

package/src/endpoint.ts

@@ -1,16 +1,18 @@
-import { Endpoint } from 'zhin.js/adapter';
+import { createDiscordRestApiAgent } from './rest-api-proxy.js';
 /**
  * DiscordEndpoint — lifecycle, outbound, admit, gateway / interactions modes, agent tool surface.
  */
 import { ChannelType } from 'discord.js';
-import type {
-  EndpointChannel,
-  EndpointContentPort,
-  EndpointContentResolveContext,
-  EndpointControl,
-  EndpointGroup,
-  EndpointManagement,
-  EndpointSendRequest,
+import {
+  Endpoint, createEndpointLifecycle,
+  type EndpointChannel,
+  type EndpointContentPort,
+  type EndpointContentResolveContext,
+  type EndpointControl,
+  type EndpointGroup,
+  type EndpointManagement,
+  type EndpointSendRequest,
+  type EndpointTransportState,
 } from 'zhin.js/adapter';
 import type { HttpHost, HttpRouteRegistration } from '@zhin.js/host-http';
 import {
@@ -69,7 +71,9 @@ export class DiscordGatewayEndpoint extends Endpoint<DiscordClientTransport> {
   readonly #fetch: typeof globalThis.fetch;
   #client: DiscordClientTransport | null = null;
   #open = false;
-  #started = false;
+  readonly #lifecycle = createEndpointLifecycle({ name: 'discord', reconnect: false });
+  #cleanup?: () => Promise<void>;
+  #retiring?: Promise<void>;
   readonly management: EndpointManagement = createDiscordEndpointManagement(
     () => this.#requireClient(),
   );
@@ -104,21 +108,44 @@ export class DiscordGatewayEndpoint extends Endpoint<DiscordClientTransport> {
     return this.#requireClient();
   }
 
+  get transportState(): EndpointTransportState | undefined {
+    if (this.#lifecycle.state !== 'open') return this.#lifecycle.state;
+    if (!this.#client) return 'closed';
+    if (!this.#client.isReady) return this.#lifecycle.state;
+    return this.#client.isReady() ? 'open' : 'reconnecting';
+  }
+
   async start(): Promise<void> {
-    if (this.#started) return;
-    this.#started = true;
+    await this.#retiring;
+    await this.#lifecycle.start(async handle => {
+    let cleanup: (() => Promise<void>) | undefined; let cancelled = false;
     try {
       const intents = this.#options.config.intents?.length
         ? [...this.#options.config.intents]
         : DEFAULT_INTENTS;
-      this.#client = this.#createClient(intents);
-      await connectDiscordGatewayClient(this.#client, this.#options.config, {
+      const restAgent = this.#options.config.restApiProxy ? createDiscordRestApiAgent(this.#options.config.restApiProxy) : undefined;
+      let client: DiscordClientTransport;
+      try { client = this.#createClient(intents, this.#options.config.gatewayFaultProxyUrl, restAgent ? { agent: restAgent } : undefined); }
+      catch (error) { await restAgent?.destroyProxy(); throw error; }
+      this.#client = client;
+      const abort = new AbortController(); let stopping: Promise<void> | undefined;
+      cleanup = () => {
+        cancelled = true;
+        abort.abort();
+        if (this.#client === client) this.#client = null;
+        return stopping ??= (async () => { client.removeAllListeners(); try { await client.destroy(); } finally { await restAgent?.destroyProxy(); } })();
+      };
+      this.#cleanup = cleanup;
+      handle.onForceClose(() => { void cleanup?.().catch(() => {}); });
+      await connectDiscordGatewayClient(client, this.#options.config, {
         onPlatformEvent: (name, event) => {
+          if (this.#client !== client) return;
           void this.#emitPlatformEvent(name, event);
         },
-        onMessage: (msg) => this.admit(msg),
-        onButton: (interaction) => this.admitButton(interaction),
+        onMessage: (msg) => { if (this.#client === client) return this.admit(msg); },
+        onButton: (interaction) => { if (this.#client === client) return this.admitButton(interaction); },
         onGuildMemberAdd: (member) => {
+          if (this.#client !== client) return;
           receiveDiscordGuildMemberSideEvent(
             (name, payload) => this.emit(name, payload),
             this.#options.config.id,
@@ -128,6 +155,7 @@ export class DiscordGatewayEndpoint extends Endpoint<DiscordClientTransport> {
           );
         },
         onGuildMemberRemove: (member) => {
+          if (this.#client !== client) return;
           receiveDiscordGuildMemberSideEvent(
             (name, payload) => this.emit(name, payload),
             this.#options.config.id,
@@ -136,7 +164,8 @@ export class DiscordGatewayEndpoint extends Endpoint<DiscordClientTransport> {
             this.#logger,
           );
         },
-      });
+      }, abort.signal);
+      if (abort.signal.aborted || this.#client !== client) return;
       this.#logger.info(formatCompact({
         op: 'connect',
         endpoint: this.#options.config.id,
@@ -144,10 +173,13 @@ export class DiscordGatewayEndpoint extends Endpoint<DiscordClientTransport> {
         user: this.#client.user?.tag,
       }));
     } catch (error) {
-      await this.stop();
+      const stopped = cancelled;
+      try { await cleanup?.(); } catch { /* original connect failure wins */ }
+      if (stopped) return;
       this.#logger.error('Failed to connect Discord gateway:', error);
       throw error;
     }
+    });
   }
 
   open(): void {
@@ -160,16 +192,13 @@ export class DiscordGatewayEndpoint extends Endpoint<DiscordClientTransport> {
 
   async stop(): Promise<void> {
     this.#open = false;
-    if (this.#client) {
-      try {
-        this.#client.removeAllListeners();
-        await this.#client.destroy();
-      } catch {
-        /* ignore */
-      }
-      this.#client = null;
-    }
-    this.#started = false;
+    const cleanup = this.#cleanup;
+    this.#cleanup = undefined;
+    this.#lifecycle.stop();
+    const retiring = this.#retiring ?? Promise.resolve().then(async () => { try { await cleanup?.(); } catch { /* best-effort SDK shutdown */ } });
+    this.#retiring = retiring;
+    await retiring;
+    if (this.#retiring === retiring) this.#retiring = undefined;
     this.#logger.debug(formatCompact({ op: 'disconnect' }));
   }
 
@@ -271,13 +300,25 @@ export class DiscordGatewayEndpoint extends Endpoint<DiscordClientTransport> {
   }
 
   async #sendBody(channelId: string, body: DiscordOutboundBody): Promise<string> {
-    const channel = await this.#requireClient().channels.fetch(channelId);
-    if (!channel || !channel.isTextBased() || !channel.send) {
-      throw new Error(`Channel ${channelId} is not a text channel`);
+    let stage = 'fetch_channel';
+    try {
+      const channel = await this.#requireClient().channels.fetch(channelId);
+      if (!channel || !channel.isTextBased() || !channel.send) {
+        throw new Error(`Channel ${channelId} is not a text channel`);
+      }
+      stage = 'render';
+      const options = await toMessageCreateOptions(body);
+      stage = 'send';
+      const result = await channel.send(options);
+      return result.id;
+    } catch (error) {
+      const details = error as { code?: unknown; status?: unknown };
+      this.#logger.warn(formatCompact({ op: 'discord_send_failed', stage,
+        code: typeof details?.code === 'number' ? details.code : 'unknown',
+        status: typeof details?.status === 'number' ? details.status : undefined,
+      }));
+      throw error;
     }
-    const options = await toMessageCreateOptions(body);
-    const result = await channel.send(options);
-    return result.id;
   }
 
   #requireClient(): DiscordClientTransport {
@@ -430,6 +471,31 @@ export class DiscordInteractionsEndpoint extends Endpoint<DiscordRestClient> {
     });
   }
 
+  /** Test / internal: admit a button interaction when open. */
+  admitButton(interaction: DiscordButtonInbound): void {
+    if (!this.#open) return;
+    const conversation = discordInboundConversation(String(this.#options.id), interaction);
+    void this.emit('message.receive', {
+      conversation,
+      message: { conversation, id: interaction.id },
+      content: formatButtonContent(interaction),
+      segments: formatButtonSegments(interaction),
+      sender: { id: interaction.userId, name: interaction.userName },
+      endpointId: this.#options.config.id,
+      metadata: Object.freeze({
+        eventType: 'button',
+        payload: interaction.customId,
+        sourceMessageId: interaction.sourceMessageId,
+      }),
+    }).catch((err) => {
+      this.#logger.warn(formatCompact({
+        op: 'discord_gateway_receive_failed',
+        target: `${conversation.kind}:${conversation.id}`,
+        error: err instanceof Error ? err.message : String(err),
+      }));
+    });
+  }
+
   admitPlatform(event: Record<string, unknown>): void {
     if (!this.#open) return;
     const type = typeof event.type === 'number' ? `interaction.${event.type}` : 'interaction';

package/src/gateway-fault-proxy.ts

@@ -0,0 +1,82 @@
+import { getLogger, formatCompact } from '@zhin.js/logger';
+import { Collection } from '@discordjs/collection';
+import {
+  SimpleContextFetchingStrategy, WebSocketShard, WebSocketShardEvents,
+  managerToFetchingStrategyOptions,
+  type IShardingStrategy, type SessionInfo, type WebSocketManager,
+  type WebSocketShardDestroyOptions,
+} from '@discordjs/ws';
+
+export function validateDiscordGatewayFaultProxy(value: string): string {
+  const url = new URL(value);
+  if (url.protocol !== 'ws:' || url.hostname !== '127.0.0.1' || !url.port || url.username || url.password || url.pathname !== '/' || url.search || url.hash) throw new Error('Discord gateway fault proxy must be ws://127.0.0.1:PORT/');
+  return url.origin;
+}
+
+/** Public gateway host only; credentials and arbitrary proxy targets are rejected. */
+export function discordGatewayProxyURL(proxy: string, upstream: string): string {
+  const origin = validateDiscordGatewayFaultProxy(proxy); const target = new URL(upstream);
+  if (target.protocol !== 'wss:' || !/^gateway(?:-[a-z0-9-]+)?\.discord\.gg$/.test(target.hostname)
+    || (target.port && target.port !== '443') || target.username || target.password || target.pathname !== '/' || target.hash
+    || [...target.searchParams].some(([key, value]) => !(key === 'v' && /^\d{1,2}$/.test(value)) && !(key === 'encoding' && value === 'json') && !(key === 'compress' && value === 'zlib-stream'))) throw new Error('Invalid Discord gateway host');
+  return `${origin}/__discord_gateway/${target.hostname}`;
+}
+
+/** Undo only this proxy's exact internal route when SDK updates sequence. */
+export function canonicalDiscordGatewayURL(proxy: string, value: string): string {
+  const origin = validateDiscordGatewayFaultProxy(proxy); const url = new URL(value);
+  if (url.origin !== origin) { discordGatewayProxyURL(proxy, value); return value; }
+  const host = url.pathname.match(/^\/__discord_gateway\/(gateway(?:-[a-z0-9-]+)?\.discord\.gg)$/)?.[1];
+  if (!host || url.username || url.password || url.search || url.hash) throw new Error('Invalid internal Discord gateway route');
+  return `wss://${host}/`;
+}
+
+/** Keeps SDK heartbeat/Identify/Resume. Only connection URLs use the test proxy. */
+export class DiscordFaultProxyStrategy implements IShardingStrategy {
+  #failureReject!: (error: Error) => void;
+  readonly #failure = new Promise<never>((_, reject) => { this.#failureReject = reject; });
+  readonly #diagnosed = new Set<string>();
+  readonly #shards = new Collection<number, WebSocketShard>();
+  constructor(readonly manager: WebSocketManager, readonly proxy: string) { validateDiscordGatewayFaultProxy(proxy); void this.#failure.catch(() => {}); }
+  async spawn(shardIds: number[]): Promise<void> {
+    const options = await managerToFetchingStrategyOptions(this.manager);
+    const mapped = { ...options, gatewayInformation: { ...options.gatewayInformation, url: discordGatewayProxyURL(this.proxy, options.gatewayInformation.url) } };
+    for (const shardId of shardIds) {
+      const context = new SimpleContextFetchingStrategy(this.manager, mapped);
+      const retrieve = context.retrieveSessionInfo.bind(context); const update = context.updateSessionInfo.bind(context);
+      const invalid = () => {
+        const error = new Error('Invalid Discord gateway session'); this.#failureReject(error);
+        void Promise.resolve(this.manager.emit(WebSocketShardEvents.Error, { error, shardId })).catch(() => {});
+        void shard.destroy({ code: 1000, reason: 'Invalid gateway session' }).catch(() => {});
+      };
+      context.retrieveSessionInfo = async (id: number): Promise<SessionInfo | null> => {
+        try {
+          const session = await retrieve(id);
+          if (!session) return null;
+          const canonical = canonicalDiscordGatewayURL(this.proxy, session.resumeURL);
+          const target = new URL(canonical);
+          if (!this.#diagnosed.has(target.hostname) && this.#diagnosed.size < 8) {
+            this.#diagnosed.add(target.hostname);
+            getLogger('discord').debug(formatCompact({ op: 'discord_gateway_resume_target', hostname: target.hostname, pathIsRoot: target.pathname === '/', queryKeys: [...new Set(target.searchParams.keys())].join(',') }));
+          }
+          return { ...session, resumeURL: discordGatewayProxyURL(this.proxy, canonical) };
+        } catch { invalid(); return null; }
+      };
+      context.updateSessionInfo = async (id, session) => {
+        try { return await update(id, session ? { ...session, resumeURL: canonicalDiscordGatewayURL(this.proxy, session.resumeURL) } : null); }
+        catch { invalid(); }
+      };
+      const shard = new WebSocketShard(context, shardId);
+      for (const event of Object.values(WebSocketShardEvents)) shard.on(event, (payload?: object) => this.manager.emit(event, { ...payload, shardId } as never));
+      this.#shards.set(shardId, shard);
+    }
+  }
+  async connect(): Promise<void> { await Promise.race([Promise.all([...this.#shards.values()].map(shard => shard.connect())), this.#failure]); }
+  async destroy(options?: Omit<WebSocketShardDestroyOptions, 'recover'>): Promise<void> {
+    await Promise.all([...this.#shards.values()].map(shard => shard.destroy(options))); this.#shards.clear();
+  }
+  async send(shardId: number, payload: Parameters<WebSocketShard['send']>[0]): Promise<void> {
+    const shard = this.#shards.get(shardId); if (!shard) throw new RangeError('Discord shard not found'); await shard.send(payload);
+  }
+  async fetchStatus() { return this.#shards.mapValues(shard => shard.status); }
+}