feat: add proxy support

Author: daniel-jones-dev

CHANGELOG.md

@@ -5,6 +5,11 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 
+## [Unreleased]
+### Added
+* Add proxy support.
+
+
 ## [1.4.0] - 2022-08-09
 ### Added
 * Add `createGlossaryWithCsv()` allowing glossaries downloaded from website to
@@ -99,6 +104,7 @@ client library took over this package name. Thanks to
 ownership.
 
 
+[Unreleased]: https://github.com/DeepLcom/deepl-node/compare/v1.4.0...HEAD
 [1.4.0]: https://github.com/DeepLcom/deepl-node/compare/v1.3.2...v1.4.0
 [1.3.2]: https://github.com/DeepLcom/deepl-node/compare/v1.3.1...v1.3.2
 [1.3.1]: https://github.com/DeepLcom/deepl-node/compare/v1.2.2...v1.3.1

README.md

@@ -385,6 +385,9 @@ The available options are:
 -   `headers`: extra HTTP headers attached to every HTTP request. By default, no
     extra headers are used. Note that Authorization and User-Agent headers are
     added automatically but may be overridden by this option.
+-   `proxy`: define the hostname, and port of the proxy server, and optionally
+    the protocol, and authorization (as an auth object with username and
+    password fields).
 
 #### Logging
 
@@ -401,6 +404,19 @@ log.getLogger('deepl').setLevel('debug'); // Or 'info'
 The `loglevel` package also supports plugins, see
 [the documentation](https://www.npmjs.com/package/loglevel#plugins).
 
+#### Proxy configuration
+
+You can configure a proxy by specifying the `proxy` argument when constructing a
+`deepl.Translator`:
+
+```javascript
+const proxy = {host: 'localhost', port: 3000};
+const deepl = new deepl.Translator('YOUR_AUTH_KEY', options);
+```
+
+The proxy argument is passed to the underlying `axios` request, see the
+[documentation for axios][axios-proxy-docs].
+
 ### Request retries
 
 Requests to the DeepL API that fail due to transient conditions (for example,
@@ -440,6 +456,7 @@ environment variables defined referring to the mock-server.
 
 [api-docs]: https://www.deepl.com/docs-api?utm_source=github&utm_medium=github-nodejs-readme
 [api-docs-csv-format]: https://www.deepl.com/docs-api/managing-glossaries/supported-glossary-formats/?utm_source=github&utm_medium=github-nodejs-readme
+[axios-proxy-docs]: https://axios-http.com/docs/req_config
 [create-account]: https://www.deepl.com/pro?utm_source=github&utm_medium=github-nodejs-readme#developer
 [deepl-mock]: https://www.github.com/DeepLcom/deepl-mock
 [issues]: https://www.github.com/DeepLcom/deepl-node/issues

src/client.ts

@@ -9,6 +9,7 @@ import axios, { AxiosError, AxiosRequestConfig } from 'axios';
 import { URLSearchParams } from 'url';
 import FormData from 'form-data';
 import { IncomingMessage } from 'http';
+import { ProxyConfig } from './types';
 
 type HttpMethod = 'GET' | 'DELETE' | 'POST';
 
@@ -84,17 +85,20 @@ export class HttpClient {
     private readonly headers: Record<string, string>;
     private readonly minTimeout: number;
     private readonly maxRetries: number;
+    private readonly proxy?: ProxyConfig;
 
     constructor(
         serverUrl: string,
         headers: Record<string, string>,
         maxRetries: number,
         minTimeout: number,
+        proxy?: ProxyConfig,
     ) {
         this.serverUrl = serverUrl;
         this.headers = headers;
         this.maxRetries = maxRetries;
         this.minTimeout = minTimeout;
+        this.proxy = proxy;
     }
 
     prepareRequest(
@@ -133,6 +137,7 @@ export class HttpClient {
                 axiosRequestConfig.data = options.data;
             }
         }
+        axiosRequestConfig.proxy = this.proxy;
         return axiosRequestConfig;
     }
 

src/index.ts

@@ -478,7 +478,13 @@ export class Translator {
 
         const maxRetries = options?.maxRetries !== undefined ? options.maxRetries : 5;
         const minTimeout = options?.minTimeout !== undefined ? options.minTimeout : 5000;
-        this.httpClient = new HttpClient(serverUrl, headers, maxRetries, minTimeout);
+        this.httpClient = new HttpClient(
+            serverUrl,
+            headers,
+            maxRetries,
+            minTimeout,
+            options?.proxy,
+        );
     }
 
     /**

src/types.ts

@@ -2,6 +2,20 @@
 // Use of this source code is governed by an MIT
 // license that can be found in the LICENSE file.
 
+/**
+ * Optional proxy configuration, may be specified as proxy in TranslatorOptions.
+ * @see TranslatorOptions.proxy
+ */
+export interface ProxyConfig {
+    host: string;
+    port: number;
+    auth?: {
+        username: string;
+        password: string;
+    };
+    protocol?: string;
+}
+
 /**
  * Options that can be specified when constructing a Translator.
  */
@@ -30,6 +44,11 @@ export interface TranslatorOptions {
      * if this value is unspecified is 10 seconds (10000).
      */
     minTimeout?: number;
+
+    /**
+     * Define the host, port and protocol of the proxy server.
+     */
+    proxy?: ProxyConfig;
 }
 
 export type Formality = 'less' | 'more' | 'default';

tests/core.ts

@@ -44,6 +44,8 @@ const internalExampleText: Record<string, string> = {
 };
 
 const usingMockServer = process.env.DEEPL_MOCK_SERVER_PORT !== undefined;
+const usingMockProxyServer =
+    usingMockServer && process.env.DEEPL_MOCK_PROXY_SERVER_PORT !== undefined;
 
 /**
  * Creates a random authKey for testing purposes. Only valid if using mock-server.
@@ -84,6 +86,7 @@ export interface TestTranslatorOptions {
     randomAuthKey?: boolean;
     maxRetries?: number;
     minTimeout?: number;
+    proxy?: deepl.ProxyConfig;
 
     mockServerNoResponseTimes?: number;
     mockServer429ResponseTimes?: number;
@@ -161,14 +164,24 @@ export function makeTranslator(options?: TestTranslatorOptions) {
         headers: sessionHeaders,
         minTimeout: options?.minTimeout,
         maxRetries: options?.maxRetries,
+        proxy: options?.proxy,
     });
 }
 
 // Use instead of it(...) for tests that require a mock-server
 export const withMockServer = usingMockServer ? it : it.skip;
+// Use instead of it(...) for tests that require a mock-server with proxy
+export const withMockProxyServer = usingMockProxyServer ? it : it.skip;
 // Use instead of it(...) for tests that cannot run using mock-server
 export const withRealServer = usingMockServer ? it.skip : it;
 
+const proxyUrlString = process.env.DEEPL_PROXY_URL;
+const proxyUrl = proxyUrlString ? new URL(proxyUrlString) : undefined;
+const proxyConfigHost = proxyUrl ? proxyUrl.hostname : '';
+const proxyConfigPort = parseInt(process.env.DEEPL_MOCK_PROXY_SERVER_PORT || '');
+
+export const proxyConfig: deepl.ProxyConfig = { host: proxyConfigHost, port: proxyConfigPort };
+
 // Wrap setTimeout() with Promise
 export const timeout = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms));
 
@@ -180,7 +193,9 @@ module.exports = {
     exampleLargeDocumentOutput,
     tempFiles,
     withMockServer,
+    withMockProxyServer,
     withRealServer,
     makeTranslator,
     timeout,
+    proxyConfig,
 };

tests/general.test.ts

@@ -6,7 +6,14 @@ import * as deepl from 'deepl-node';
 
 import fs from 'fs';
 
-import { exampleText, tempFiles, withMockServer, makeTranslator } from './core';
+import {
+    exampleText,
+    tempFiles,
+    withMockServer,
+    withMockProxyServer,
+    makeTranslator,
+    proxyConfig,
+} from './core';
 
 const serverUrl = process.env.DEEPL_SERVER_URL;
 
@@ -94,6 +101,21 @@ describe('general', () => {
         expect(deepl.isFreeAccountAuthKey('0000')).toBe(false);
     });
 
+    withMockProxyServer('should support proxy usage', async () => {
+        const translator = makeTranslator({
+            mockServerExpectProxy: true,
+            randomAuthKey: true,
+        });
+        const translatorWithProxy = makeTranslator({
+            mockServerExpectProxy: true,
+            randomAuthKey: true,
+            proxy: proxyConfig,
+        });
+
+        await expect(translator.getUsage()).rejects.toThrowError(deepl.DeepLError);
+        await translatorWithProxy.getUsage();
+    });
+
     withMockServer('should throw ConnectionError with timed-out responses', async () => {
         const translator = makeTranslator({
             mockServerNoResponseTimes: 2,