AWS SDK v3 Proxy

A wrapper for adding proxy support to AWS SDK v3 clients

This wrapper adds a proxy configuration to AWS SDK clients by checking environment variables and attaching the necessary request handler. By default, an error will be thrown if no proxy is found in process.env, but also has options to not throw which can be useful when developing other node utilities using this library.

Note: http_proxy and HTTP_PROXY take precedence over https_proxy and HTTPS_PROXY. If you would like to change this behavior it can be specified in the options.

Install

npm install aws-sdk-v3-proxy

Usage

HTTP Proxy

// process.env.HTTP_PROXY = 'http://127.0.0.1'
import { S3Client } from '@aws-sdk/client-s3';
import { addProxyToClient } from 'aws-sdk-v3-proxy';

const client = addProxyToClient(new S3Client({}));
// `client` now has HTTP proxy config at 'http://127.0.0.1'

or

import { S3Client } from '@aws-sdk/client-s3';
import { addProxyToClient } from 'aws-sdk-v3-proxy';

const client = addProxyToClient(new S3Client({}), {
  httpProxy: 'http://127.0.0.1',
});
// `client` now has HTTP proxy config at 'http://127.0.0.1'

HTTPS Proxy

// process.env.HTTPS_PROXY = 'https://127.0.0.1'
import { S3Client } from '@aws-sdk/client-s3';
import { addProxyToClient } from 'aws-sdk-v3-proxy';

const client = addProxyToClient(new S3Client({}));
// `client` now has HTTPS proxy config at 'https://127.0.0.1'

or

import { S3Client } from '@aws-sdk/client-s3';
import { addProxyToClient } from 'aws-sdk-v3-proxy';

const client = addProxyToClient(new S3Client({}), {
  httpsProxy: 'https://127.0.0.1',
});
// `client` now has HTTPS proxy config at 'https://127.0.0.1'

No Proxy with exception disabled

// process.env.HTTPS_PROXY = undefined
// process.env.HTTP_PROXY = undefined
import { S3Client } from '@aws-sdk/client-s3';
import { addProxyToClient } from 'aws-sdk-v3-proxy';

const client = addProxyToClient(new S3Client({}), { throwOnNoProxy: false });
// `client` has no proxy assigned and no error thrown

Proxy with certs in header

// process.env.HTTPS_PROXY = 'https://127.0.0.1'
import { readFileSync } from 'fs';
import { S3Client } from '@aws-sdk/client-s3';
import { addProxyToClient } from 'aws-sdk-v3-proxy';

const client = addProxyToClient(new S3Client({}), {
  agentOptions: {
    ca: [readFileSync('custom-proxy-cert.pem').toString()],
  },
});

// `client` now has HTTPS proxy config at 'https://127.0.0.1' with ca `custom-proxy-cert.pem`

API

addProxyToClient(client, options?)

client

Type: Object

Any client from @aws-sdk.

options

Type: object

throwOnNoProxy

Type: boolean Default: true

Throw an error if no proxy is found in the environment.

httpsOnly

Type: boolean Default: false

Can be specified in cases where you have both http_proxy and https_proxy set, and would like to override the default behavior of the http_proxy taking precedence.

debug

Type: boolean Default: false

Toggles additional logging for debugging.

httpProxy

Type: string

The URL for the HTTP proxy server. If not specified, the value of process.env.http_proxy or process.env.HTTP_RPOXY will be used.

httpsProxy

The URL for the HTTPS proxy server. If not specified, the value of process.env.https_proxy or process.env.HTTPS_RPOXY will be used.

agentOptions

Type: HttpsProxyAgentOptions

Used to pass specific options to the proxy agent.

Security

See CONTRIBUTING for more information.

License

This project is licensed under the Apache-2.0 License.