diff --git a/code-samples/additional-info/proxy/14/index.js b/code-samples/additional-info/proxy/14/index.js new file mode 100644 index 000000000..89338325d --- /dev/null +++ b/code-samples/additional-info/proxy/14/index.js @@ -0,0 +1,43 @@ +const { ProxyAgent } = require('undici'); +const { Client } = require('discord.js'); +const { bootstrap } = require('global-agent'); + +bootstrap(); + +class NodeGlobalProxy { + config = { + http: '', + https: '', + }; + + constructor(config) { + this.config = config; + } + + start() { + global.GLOBAL_AGENT.HTTP_PROXY = this.config.http; + global.GLOBAL_AGENT.HTTPS_PROXY = this.config.https; + } + + stop() { + global.GLOBAL_AGENT.HTTP_PROXY = null; + global.GLOBAL_AGENT.HTTPS_PROXY = null; + } +} + +const proxy = new NodeGlobalProxy({ + http: 'http://my-proxy-server:port', + https: 'http://my-proxy-server:port', +}); + +proxy.start(); + +// eslint-disable-next-line no-unused-vars +const client = new Client({ + // other client options + rest: { + agent: new ProxyAgent('http://my-proxy-server:port'), + }, +}); + +client.login('your-token-goes-here'); diff --git a/guide/.vuepress/sidebar.ts b/guide/.vuepress/sidebar.ts index f90da926b..96347dbe2 100644 --- a/guide/.vuepress/sidebar.ts +++ b/guide/.vuepress/sidebar.ts @@ -150,6 +150,7 @@ export default { '/additional-info/collections.md', '/additional-info/async-await.md', '/additional-info/rest-api.md', + '/additional-info/proxy.md', '/additional-info/changes-in-v13.md', '/additional-info/changes-in-v14.md', ], diff --git a/guide/additional-info/proxy.md b/guide/additional-info/proxy.md new file mode 100644 index 000000000..2677bc542 --- /dev/null +++ b/guide/additional-info/proxy.md @@ -0,0 +1,119 @@ +# Using a proxy with Discord.js + +It may be necessary to use a proxy when using Discord.js, for example when you are deploying your bot on a server that has a web filtering firewall that only allows outside traffic through the proxy. This guide will show you how to set up a proxy with Discord.js. + +A proxy for Discord.js requires 2 separate setups, one for REST and one for WebSocket. + +## Prerequisites + +In order to set up a proxy for Discord.js, you will need to install the following packages: + +:::: code-group +::: code-group-item npm + +```sh:no-line-numbers +npm install undici global-agent +``` + +::: +::: code-group-item yarn + +```sh:no-line-numbers +yarn add undici global-agent +``` + +::: +::: code-group-item pnpm + +```sh:no-line-numbers +pnpm add undici global-agent +``` + +::: +::: code-group-item bun + +```sh:no-line-numbers +bun add undici global-agent +``` + +::: +:::: + +## Setting up the proxy for REST calls + +To set up a proxy for REST calls, you should provide a custom `ProxyAgent` to the `Client` constructor. The `ProxyAgent` must be imported from the `undici` package, which is the package that `@discordjs/rest` uses to make HTTP requests. + +```js {6-8} +const { ProxyAgent } = require('undici'); +const { Client } = require('discord.js'); + +const myClient = new Client({ + // other client options + rest: { + agent: new ProxyAgent('http://my-proxy-server:port'), + }, +}); +``` + +:::tip +For further information on the `undici` `ProxyAgent`, please refer to the [undici documentation](https://undici.nodejs.org/#/docs/api/ProxyAgent.md). +::: + +## Setting up the proxy for WebSocket + +To set up a proxy for WebSocket, you can use the `global-agent` package. You will need to provide some custom configuration to activate it: + +```js {1-24} +const { bootstrap } = require('global-agent'); + +bootstrap(); + +class NodeGlobalProxy { + config = { + http: '', + https: '', + }; + + constructor(config) { + this.config = config; + } + + start() { + global.GLOBAL_AGENT.HTTP_PROXY = this.config.http; + global.GLOBAL_AGENT.HTTPS_PROXY = this.config.https; + } + + stop() { + global.GLOBAL_AGENT.HTTP_PROXY = null; + global.GLOBAL_AGENT.HTTPS_PROXY = null; + } +} + +module.exports = { + NodeGlobalProxy, +}; +``` + +Now in the file where you create your client, you can import the `NodeGlobalProxy` class and start it with the proxy URL: + +```js {2,4-7,9} +const { Client } = require('discord.js'); +const { NodeGlobalProxy } = require('./NodeGlobalProxy'); + +const proxy = new NodeGlobalProxy({ + http: 'http://my-proxy-server:port', + https: 'http://my-proxy-server:port', +}); + +proxy.start(); + +const client = new Client({ + // client options, including the proxy agent as described above +}); + +client.login('your-token-goes-here'); +``` + +## Resulting code + +