feat(h5p-server): added forward proxy support (#1414)

docs/SUMMARY.md

@@ -13,6 +13,7 @@
   * [Customization](advanced/customization.md)
   * [Performance optimizations](advanced/performance-optimizations.md)
   * [Privacy](advanced/privacy.md)
+  * [Forward proxy support](advanced/proxy.md)
 - NPM packages
   - h5p-mongos3
     * [Mongo/S3 Content Storage](packages/h5p-mongos3/mongo-s3-content-storage.md)

docs/advanced/proxy.md

@@ -0,0 +1,26 @@
+# Forward proxy support
+
+@lumieducation/h5p-server has to make outgoing HTTPS requests to contact the H5P
+Hub. If your network requires the use of a forward proxy to reach the Internet,
+you must configure @lumieducation/h5p-server to use it for the HTTPS requests.
+
+There are two ways of enabling the proxy:
+
+1. Set the `proxy` property in IH5PConfig like this:
+    ```json
+    {
+        "proxy": {
+            "host": "10.1.2.3",
+            "port": 8080,
+            "protocol": "https" // can also be left out or set to "http" if your proxy can't be accessed with https
+        }
+    }
+    ```
+
+2. Set the HTTPS_PROXY environment variable like this:
+
+    ``HTTPS_PROXY=http://10.1.2.3:8080``
+    or
+    ``HTTPS_PROXY=https://10.1.2.3:8080``
+
+    (depending on whether your proxy can be accessed with https).

packages/h5p-server/package.json

@@ -53,6 +53,7 @@
         "debug": "^4.1.1",
         "fs-extra": "^9.0.0",
         "get-all-files": "^3.0.0",
+        "https-proxy-agent": "^5.0.0",
         "image-size": "^1.0.0",
         "jsonpath": "^1.0.2",
         "merge": "^2.0.0",

packages/h5p-server/src/ContentHub.ts

@@ -1,8 +1,9 @@
-import axios from 'axios';
-import H5pError from './helpers/H5pError';
+import { AxiosInstance } from 'axios';
 
-import Logger from './helpers/Logger';
+import HttpClient from './helpers/HttpClient';
 import { IH5PConfig, IKeyValueStorage } from './types';
+import H5pError from './helpers/H5pError';
+import Logger from './helpers/Logger';
 
 const log = new Logger('ContentHub');
 
@@ -14,8 +15,11 @@ export default class ContentHub {
      */
     constructor(private config: IH5PConfig, private storage: IKeyValueStorage) {
         log.info(`initialize`);
+        this.httpClient = HttpClient(config);
     }
 
+    private httpClient: AxiosInstance;
+
     getMetadata = async (lang?: string): Promise<any> => {
         const updateKey = lang
             ? `contentHubMetadataUpdate-${lang}`
@@ -59,7 +63,7 @@ export default class ContentHub {
             }
         }
 
-        const response = await axios.get(
+        const response = await this.httpClient.get(
             lang
                 ? `${this.config.contentHubMetadataEndpoint}?lang=${isoLanguage}`
                 : this.config.contentHubMetadataEndpoint,

packages/h5p-server/src/ContentTypeCache.ts

@@ -1,4 +1,4 @@
-import axios from 'axios';
+import { AxiosInstance } from 'axios';
 import { crc32 } from 'crc';
 import * as merge from 'merge';
 import * as qs from 'qs';
@@ -12,6 +12,7 @@ import {
     IRegistrationData,
     IUsageStatistics
 } from './types';
+import HttpClient from './helpers/HttpClient';
 
 const log = new Logger('ContentTypeCache');
 
@@ -39,10 +40,13 @@ export default class ContentTypeCache {
         log.info(`initialize`);
         this.config = config;
         this.storage = storage;
+        this.httpClient = HttpClient(config);
     }
 
     private config: IH5PConfig;
     private storage: IKeyValueStorage;
+    private httpClient: AxiosInstance;
+
     /**
      * Converts an entry from the H5P Hub into a format with flattened versions and integer date values.
      * @param entry the entry as received from H5P Hub
@@ -102,8 +106,7 @@ export default class ContentTypeCache {
                 this.compileUsageStatistics()
             );
         }
-
-        const response = await axios.post(
+        const response = await this.httpClient.post(
             this.config.hubContentTypesEndpoint,
             qs.stringify(formData)
         );
@@ -222,7 +225,7 @@ export default class ContentTypeCache {
         if (this.config.uuid && this.config.uuid !== '') {
             return this.config.uuid;
         }
-        const response = await axios.post(
+        const response = await this.httpClient.post(
             this.config.hubRegistrationEndpoint,
             this.compileRegistrationData()
         );

packages/h5p-server/src/ContentTypeInformationRepository.ts

@@ -1,4 +1,4 @@
-import axios from 'axios';
+import { AxiosInstance } from 'axios';
 import * as fsExtra from 'fs-extra';
 import promisepipe from 'promisepipe';
 import { withFile } from 'tmp-promise';
@@ -17,9 +17,9 @@ import {
     ITranslationFunction,
     IUser
 } from './types';
-
 import Logger from './helpers/Logger';
 import TranslatorWithFallback from './helpers/TranslatorWithFallback';
+import HttpClient from './helpers/HttpClient';
 
 const log = new Logger('ContentTypeInformationRepository');
 
@@ -55,9 +55,11 @@ export default class ContentTypeInformationRepository {
                 'hub'
             ]);
         }
+        this.httpClient = HttpClient(config);
     }
 
     private translator: TranslatorWithFallback;
+    private httpClient: AxiosInstance;
 
     /**
      * Gets the information about available content types with all the extra
@@ -132,7 +134,7 @@ export default class ContentTypeInformationRepository {
         }
 
         // Download content type package from the Hub
-        const response = await axios.get(
+        const response = await this.httpClient.get(
             this.config.hubContentTypesEndpoint + machineName,
             { responseType: 'stream' }
         );

packages/h5p-server/src/H5PEditor.ts

@@ -939,7 +939,8 @@ export default class H5PEditor {
             async ({ path: tmpFile }) => {
                 await downloadFile(
                     `${this.config.contentHubContentEndpoint}/${contentHubId}/export`,
-                    tmpFile
+                    tmpFile,
+                    this.config
                 );
                 log.debug(`Hub content downloaded to ${tmpFile}`);
                 return this.uploadPackage(tmpFile, user);

packages/h5p-server/src/helpers/HttpClient.ts

@@ -0,0 +1,33 @@
+import axios, { AxiosInstance } from 'axios';
+// We need to use https-proxy-agent as the default Axios proxy functionality
+// doesn't work with https.
+import HttpsProxyAgent from 'https-proxy-agent';
+import { IH5PConfig } from '../types';
+
+/**
+ * Creates an Axios instance that supports corporate HTTPS proxies.
+ * The proxy can either be configured in the config's proxy property or by
+ * setting the environment variable HTTPS_PROXY.
+ * @param config the H5P config object
+ * @returns the AxiosInstance
+ */
+const getClient = (config: IH5PConfig): AxiosInstance => {
+    let proxyAgent;
+
+    if (config.proxy) {
+        proxyAgent = HttpsProxyAgent({
+            host: config.proxy.host,
+            port: config.proxy.port,
+            protocol: config.proxy.protocol === 'https' ? 'https:' : undefined
+        });
+    } else if (process.env.HTTPS_PROXY) {
+        proxyAgent = HttpsProxyAgent(process.env.HTTPS_PROXY);
+    }
+
+    return axios.create({
+        proxy: proxyAgent ? false : undefined,
+        httpsAgent: proxyAgent
+    });
+};
+
+export default getClient;

packages/h5p-server/src/helpers/downloadFile.ts

@@ -1,9 +1,11 @@
-import axios, { AxiosError } from 'axios';
+import { AxiosError } from 'axios';
 import fs from 'fs';
-
 import * as stream from 'stream';
 import { promisify } from 'util';
+
+import { IH5PConfig } from '../types';
 import H5pError from './H5pError';
+import HttpClient from './HttpClient';
 
 const finished = promisify(stream.finished);
 
@@ -16,10 +18,12 @@ const finished = promisify(stream.finished);
  */
 export async function downloadFile(
     fileUrl: string,
-    outputLocationPath: string
+    outputLocationPath: string,
+    config: IH5PConfig
 ): Promise<any> {
     const writer = fs.createWriteStream(outputLocationPath);
-    return axios({
+    const client = HttpClient(config);
+    return client({
         method: 'get',
         url: fileUrl,
         responseType: 'stream'

packages/h5p-server/src/implementation/H5PConfig.ts

@@ -90,12 +90,17 @@ export default class H5PConfig implements IH5PConfig {
         [machineName: string]: string[];
     };
     public playUrl: string = '/play';
+    public proxy?: {
+        host: string;
+        port: number;
+        protocol?: 'http' | 'https';
+    };
     public sendUsageStatistics: boolean = false;
     public setFinishedUrl: string = '/setFinished';
     public siteType: 'local' | 'network' | 'internet' = 'local';
     public temporaryFileLifetime: number = 120 * 60 * 1000; // 120 minutes
     public temporaryFilesUrl: string = '/temp-files';
-    public uuid: string = ''; // TODO: revert to''
+    public uuid: string = '';
 
     private storage: IKeyValueStorage;
 
@@ -121,6 +126,7 @@ export default class H5PConfig implements IH5PConfig {
         await this.loadSettingFromStorage('maxFileSize');
         await this.loadSettingFromStorage('maxTotalSize');
         await this.loadSettingFromStorage('playerAddons');
+        await this.loadSettingFromStorage('proxy');
         await this.loadSettingFromStorage('sendUsageStatistics');
         await this.loadSettingFromStorage('siteType');
         await this.loadSettingFromStorage('uuid');
@@ -148,6 +154,7 @@ export default class H5PConfig implements IH5PConfig {
         await this.saveSettingToStorage('maxFileSize');
         await this.saveSettingToStorage('maxTotalSize');
         await this.saveSettingToStorage('playerAddons');
+        await this.saveSettingToStorage('proxy');
         await this.saveSettingToStorage('sendUsageStatistics');
         await this.saveSettingToStorage('siteType');
         await this.saveSettingToStorage('uuid');

packages/h5p-server/src/types.ts

@@ -1511,8 +1511,27 @@ export interface IH5PConfig {
      */
     playUrl: string;
     /**
-     * If true, the instance will send usage statistics to the H5P Hub whenever it looks for new content types or updates.
-     * User-configurable.
+     * Allows settings a http(s) proxy for outgoing requests. No proxy will be
+     * used if left undefined (or the one specified in the HTTPS_PROXY
+     * environment variable).
+     */
+    proxy?: {
+        /**
+         * The hostname of the proxy without any protocol prefix (e.g. only 10.1.2.3)
+         */
+        host: string;
+        /**
+         * The port of the proxy, e.g. 8080.
+         */
+        port: number;
+        /**
+         * The protocol to use to access the proxy. Can be left undefined if http is used.
+         */
+        protocol?: 'http' | 'https';
+    };
+    /**
+     * If true, the instance will send usage statistics to the H5P Hub whenever
+     * it looks for new content types or updates. User-configurable.
      */
     sendUsageStatistics: boolean;
     /**