@fontoxml/fontoxml-development-tools 3.7.0-beta.7 → 3.8.0

package/src/modules/document-history/src/command.run.controller.js

@@ -0,0 +1,444 @@
+import fs from 'fs-extra';
+import os from 'os';
+import path from 'path';
+
+import cleanup from './utilities/cleanup.js';
+import constants from './utilities/constants.js';
+import copyWhitelistedFiles from './utilities/copyWhitelistedFiles.js';
+import executeAndLog from './utilities/executeAndLog.js';
+import FontoxmlFdhManifest from './utilities/FontoxmlFdhManifest.js';
+import getVerbosityLevel from './utilities/getVerbosityLevel.js';
+import getWhitelist from './utilities/getWhitelist.js';
+import setEntryVisibility from './utilities/setEntryVisibility.js';
+import validateInstance from './utilities/validateInstance.js';
+
+const verboseFdhConfigurationEntries = {
+	Logging__LogLevel__Default: 'Trace',
+};
+
+const DEFAULT_PORT = 6030;
+
+function copyFdhConfiguration(fdhConfiguration, tempDir, verbosityLevel, res) {
+	const targetFdhConfiguration = path.join(tempDir, '.env');
+
+	return fs.exists(fdhConfiguration).then((exists) => {
+		// Read the configuration entries from the .env file or initialize an empty array.
+		let deferred = exists
+			? fs.readFile(fdhConfiguration, 'utf8').then((data) => {
+					return data.split(/\r?\n/g);
+			  })
+			: new Promise((resolve, _reject) => {
+					resolve(new Array(0));
+			  });
+
+		// Replace or set the defaults for verbosity.
+		if (verbosityLevel === constants.VERBOSITY_LEVEL_DEBUG) {
+			deferred = deferred.then((configurationEntries) => {
+				Object.keys(verboseFdhConfigurationEntries).forEach((key) => {
+					const configurationEntryIndex =
+						configurationEntries.findIndex((entry) =>
+							entry.startsWith(`${key}=`)
+						);
+					const value = verboseFdhConfigurationEntries[key];
+					if (configurationEntryIndex === -1) {
+						configurationEntries.push(`${key}=${value}`);
+					} else {
+						configurationEntries[
+							configurationEntryIndex
+						] = `${key}=${value}`;
+					}
+				});
+				return configurationEntries;
+			});
+		}
+
+		// Ignore options that shouldn't be applied when running through FDT.
+		deferred = deferred.then((configurationEntries) => {
+			let i = configurationEntries.length;
+			while (i--) {
+				const configurationLine = configurationEntries[i];
+				if (
+					!configurationLine.startsWith('#') &&
+					configurationLine.indexOf('=') !== -1
+				) {
+					const [key, _value] = configurationLine.split('=', 2);
+
+					if (key === 'ASPNETCORE_URLS') {
+						configurationEntries.splice(i, 1);
+						res.notice(
+							`Notice: The '${key}' configuration option in the '.env' file will be ignored when ` +
+								"running the application using FDT. The FDT '--port' option can be used to run the application " +
+								'under a different port.'
+						);
+					}
+				}
+			}
+			return configurationEntries;
+		});
+
+		// Write the configuration to the .env file.
+		return deferred.then((configurationEntries) => {
+			const configurationData = configurationEntries.join(os.EOL);
+			return fs.writeFile(targetFdhConfiguration, configurationData);
+		});
+	});
+}
+
+export default function runCommand(req, res) {
+	res.caption(req.command.getLongName());
+
+	const directoryPath = path.resolve(
+		req.options.location ? req.options.location : process.cwd()
+	);
+	const temporaryDirectoryPath = path.join(
+		directoryPath,
+		constants.TEMPORARY_DIRECTORY_NAME
+	);
+	const fdhConfigurationFilePath = req.options['config-location']
+		? path.resolve(req.options['config-location'])
+		: path.join(directoryPath, '.env');
+	const manifestFilePath = path.join(
+		directoryPath,
+		constants.MANIFEST_FILENAME
+	);
+	const verbosityLevel = getVerbosityLevel(
+		req.options.verbose,
+		req.options.debug
+	);
+	const port = req.options.port || DEFAULT_PORT;
+	const projectName = `${constants.DEFAULT_IMAGE_NAME}_${port}`;
+
+	let pidToKillOnForceExit = null;
+	const setPidToKillOnForceExit = (processToKill) => {
+		pidToKillOnForceExit = processToKill && processToKill.pid;
+	};
+
+	// Ensure we cleanup before exiting.
+	let stopping = false;
+	process.on('SIGINT', (_code) => {
+		if (stopping) {
+			if (pidToKillOnForceExit) {
+				process.kill(pidToKillOnForceExit);
+			}
+			process.exit();
+			return;
+		}
+
+		stopping = true;
+		res.log('Gracefully stopping... (press Ctrl+C again to force)');
+		return cleanup(
+			temporaryDirectoryPath,
+			projectName,
+			res,
+			verbosityLevel
+		).then(process.exit);
+	});
+
+	return (
+		validateInstance(directoryPath)
+			.then(() => fs.exists(fdhConfigurationFilePath))
+			.then((exists) => {
+				if (!exists) {
+					if (req.options['config-location']) {
+						throw new Error(
+							`Fonto Document History config "${fdhConfigurationFilePath}" does not exist.`
+						);
+					}
+					res.notice(
+						`No .env file exists in the directory "${directoryPath}". See ${constants.DOCUMENTATION_CONFIGURATION_GUIDE} to configure the .env file.`
+					);
+				}
+			})
+			.then(() => fs.exists(manifestFilePath))
+			.then((exists) => {
+				// Verify fontoxmlFdhManifest file is present and valid.
+				if (!exists) {
+					throw new Error(
+						'The Fonto Document History manifest file does not exist.'
+					);
+				} else {
+					return FontoxmlFdhManifest.fromJsonFile(manifestFilePath);
+				}
+			})
+			// Cleanup possible remaining resources from a previous build or run.
+			.then(() =>
+				cleanup(
+					temporaryDirectoryPath,
+					projectName,
+					res,
+					verbosityLevel
+				)
+			)
+			.then(() => {
+				const destroySpinner = res.spinner(
+					`Building development image at "${directoryPath}"...`
+				);
+
+				// Retrieve data for the docker image
+				return FontoxmlFdhManifest.fromJsonFile(manifestFilePath).then(
+					(manifestObj) => {
+						const requestObj = {
+							'document-history': {
+								docker: {
+									version: manifestObj.fdhVersion,
+								},
+							},
+						};
+
+						return req.fdt.license
+							.getDataForProducts(requestObj)
+							.catch((error) => {
+								if (error.statusCode === 404) {
+									error.solution =
+										'This error might be caused by requesting a nonexisting Fonto Document History version, please check your version.';
+								}
+								throw error;
+							})
+							.then((productData) => {
+								const dockerData =
+									productData.products['document-history']
+										.docker;
+
+								// Create a hidden temporary directory.
+								return (
+									fs
+										.mkdir(temporaryDirectoryPath)
+										.then(() =>
+											setEntryVisibility(
+												temporaryDirectoryPath,
+												false
+											)
+										)
+										// Copy the instance files into the temporary directory.
+										.then(() => {
+											// Rewrite the version in the Dockerfile.
+											return fs
+												.readFile(
+													path.join(
+														constants.INSTANCE_BUILD_DIRECTORY_PATH,
+														'Dockerfile'
+													),
+													'utf8'
+												)
+												.then((dockerContent) =>
+													dockerContent.replace(
+														'${fdhImage}',
+														dockerData.image
+													)
+												)
+												.then((fixedDockerContent) =>
+													fs.writeFile(
+														path.join(
+															temporaryDirectoryPath,
+															'Dockerfile'
+														),
+														fixedDockerContent
+													)
+												);
+										})
+										.then(() =>
+											fs.copy(
+												constants.INSTANCE_DEV_BUILD_DIRECTORY_PATH,
+												temporaryDirectoryPath
+											)
+										)
+										.then(() => {
+											// Rewrite the port in the docker-compose file.
+											return fs
+												.readFile(
+													path.join(
+														temporaryDirectoryPath,
+														'docker-compose.yml'
+													),
+													'utf8'
+												)
+												.then((dockerComposeContent) =>
+													dockerComposeContent
+														.replace(
+															'${containerName}',
+															projectName
+														)
+														.replace(
+															'${fdhPort}',
+															port
+														)
+												)
+												.then(
+													(
+														fixedDockerComposeContent
+													) =>
+														fs.writeFile(
+															path.join(
+																temporaryDirectoryPath,
+																'docker-compose.yml'
+															),
+															fixedDockerComposeContent
+														)
+												);
+										})
+										.then(() => [
+											path.join(
+												directoryPath,
+												'Configuration'
+											),
+										])
+										.then(() => getWhitelist())
+										.then((whitelist) =>
+											copyWhitelistedFiles(
+												whitelist,
+												directoryPath,
+												path.join(
+													temporaryDirectoryPath,
+													'instance'
+												)
+											)
+										)
+										.then(() =>
+											copyFdhConfiguration(
+												fdhConfigurationFilePath,
+												temporaryDirectoryPath,
+												verbosityLevel,
+												res
+											)
+										)
+
+										// Pull the docker image
+										.then(() => {
+											return executeAndLog(
+												res,
+												'docker',
+												[
+													'login',
+													dockerData.registry,
+													'-u',
+													dockerData.login,
+													'-p',
+													dockerData.password,
+												],
+												null,
+												constants.VERBOSITY_LEVEL_NORMAL,
+												false,
+												setPidToKillOnForceExit
+											)
+												.then(() =>
+													executeAndLog(
+														res,
+														'docker',
+														[
+															'pull',
+															dockerData.image,
+														],
+														null,
+														verbosityLevel,
+														false,
+														setPidToKillOnForceExit
+													)
+												)
+												.then(() =>
+													executeAndLog(
+														res,
+														'docker',
+														[
+															'logout',
+															dockerData.registry,
+														],
+														null,
+														constants.VERBOSITY_LEVEL_NORMAL,
+														false,
+														setPidToKillOnForceExit
+													)
+												)
+												.catch(() => {
+													throw new Error(
+														'Failed to retrieve the image file.'
+													);
+												});
+										})
+
+										// Use docker-compose to build the development image.
+										.then(() =>
+											executeAndLog(
+												res,
+												'docker-compose',
+												verbosityLevel ===
+													constants.VERBOSITY_LEVEL_DEBUG
+													? [
+															'-p',
+															projectName,
+															'--verbose',
+															'build',
+													  ]
+													: [
+															'-p',
+															projectName,
+															'build',
+													  ],
+												temporaryDirectoryPath,
+												verbosityLevel,
+												false,
+												setPidToKillOnForceExit
+											)
+										)
+										.then(() =>
+											req.fdt.license.sendTelemetry({
+												product:
+													req.command.parent.name,
+												type: 'docker',
+												version: manifestObj.fdhVersion,
+												action: req.command.name,
+											})
+										)
+										.then(() => destroySpinner())
+								);
+							});
+					}
+				);
+			})
+			// Use docker-compose to run the development image. We hard-code verbose to true since docker does not yet support a --quiet or --silent flag. https://github.com/docker/compose/issues/3447
+			.then(() => {
+				res.notice(
+					`Starting Fonto Document History on "http://localhost:${port}"...`
+				);
+				return executeAndLog(
+					res,
+					'docker-compose',
+					verbosityLevel === constants.VERBOSITY_LEVEL_DEBUG
+						? ['-p', projectName, '--verbose', 'up']
+						: ['-p', projectName, 'up'],
+					temporaryDirectoryPath,
+					verbosityLevel,
+					true,
+					setPidToKillOnForceExit
+				);
+			})
+			// Cleanup temporary directory.
+			.then(() =>
+				cleanup(
+					temporaryDirectoryPath,
+					projectName,
+					res,
+					verbosityLevel
+				)
+			)
+			.catch((error) => {
+				if (!stopping) {
+					res.notice(
+						`See our documentation at ${constants.DOCUMENTATION_EXECUTE_ERROR} for help.`
+					);
+				}
+
+				return cleanup(
+					temporaryDirectoryPath,
+					projectName,
+					res,
+					verbosityLevel
+				)
+					.then(() => {
+						throw error;
+					})
+					.catch(() => {
+						throw error;
+					});
+			})
+	);
+}

package/src/modules/document-history/src/command.run.js

@@ -0,0 +1,64 @@
+import path from 'path';
+import { fileURLToPath } from 'url';
+
+import constants from './utilities/constants.js';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+export default (moduleRegistration, fdhCommand) => {
+	fdhCommand
+		.addCommand('run', path.resolve(__dirname, 'command.run.controller.js'))
+		.setDescription(
+			'Run a Fonto Document History instance for development purposes. Requires Docker to be installed.'
+		)
+
+		.addOption(
+			'port',
+			'p',
+			'Listen on the specified port instead of listening on the default port (default=6030).'
+		)
+
+		.addOption(
+			'location',
+			'l',
+			'The directory where the instance is located. Defaults to the current working directory.',
+			false
+		)
+		.addOption(
+			'config-location',
+			'c',
+			`The path where the configuration file (.env) is located. Information about the .env file can be found at ${constants.DOCUMENTATION_CONFIGURATION_GUIDE}.`,
+			false
+		)
+
+		.addOption(
+			'verbose',
+			null,
+			'Output default stdout and stderr information.'
+		)
+		.addOption(
+			'debug',
+			null,
+			'Output all debug information. This also overrides the Logging__LogLevel__Default if set.'
+		)
+
+		.addExample(
+			`${moduleRegistration.getAppInfo().name} ${
+				constants.COMMAND_PREFIX
+			} run`,
+			'Build and run a development image using the Fonto Document History instance and configuration located at the current working directory.'
+		)
+		.addExample(
+			`${moduleRegistration.getAppInfo().name} ${
+				constants.COMMAND_PREFIX
+			} run --port 7455`,
+			'Build and run a development image using the Fonto Document History instance and configuration located at the current working directory on the non-default port 7455. '
+		)
+		.addExample(
+			`${moduleRegistration.getAppInfo().name} ${
+				constants.COMMAND_PREFIX
+			} run --location /opt/my-instances/specific-instance/ --config-location /opt/my-instances/.env`,
+			'Build and run a development image using the Fonto Document History instance located at "/opt/my-instances/specific-instance/" using the configuration located at "/opt/my-instances/.env".'
+		);
+};

package/src/modules/document-history/src/command.upgrade.controller.js

@@ -0,0 +1,52 @@
+import fs from 'fs-extra';
+import path from 'path';
+
+import constants from './utilities/constants.js';
+import FontoxmlFdhManifest from './utilities/FontoxmlFdhManifest.js';
+import setEntryVisibility from './utilities/setEntryVisibility.js';
+
+export default async function upgradeCommand(req, res) {
+	res.caption(req.command.getLongName());
+
+	// Check if the given version exist.
+	const sdkVersions = await req.fdt.license.getVersionsForProduct(
+		'document-history'
+	);
+	const version = req.options.version;
+	if (!sdkVersions.includes(version)) {
+		throw new Error(
+			`Could not upgrade to version (${version}), please check if it is a valid version. The latest version is ${sdkVersions.getLatestStable()}, run \`fdt document-history versions\` to get a list of all available versions.`
+		);
+	}
+
+	const destroySpinner = res.spinner(
+		`Upgrading your Fonto Document History instance to ${version}...`
+	);
+
+	const directoryPath = path.resolve(
+		req.options.location ? req.options.location : process.cwd()
+	);
+	const manifestFilePath = path.join(
+		directoryPath,
+		constants.MANIFEST_FILENAME
+	);
+	let currentVersion;
+	return setEntryVisibility(manifestFilePath, true)
+		.then(() => FontoxmlFdhManifest.fromJsonFile(manifestFilePath))
+		.then((manifest) => {
+			currentVersion = manifest.fdhVersion;
+			manifest.fdhVersion = version;
+			return fs.writeJson(manifestFilePath, manifest);
+		})
+		.then(() => setEntryVisibility(manifestFilePath, false))
+		.then(() =>
+			req.fdt.license.sendTelemetry({
+				product: req.command.parent.name,
+				type: 'docker',
+				version,
+				currentVersion,
+				action: req.command.name,
+			})
+		)
+		.then(() => destroySpinner());
+}

package/src/modules/document-history/src/command.upgrade.js

@@ -0,0 +1,44 @@
+import path from 'path';
+import { fileURLToPath } from 'url';
+
+import constants from './utilities/constants.js';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+export default (moduleRegistration, fdhCommand) => {
+	fdhCommand
+		.addCommand(
+			'upgrade',
+			path.resolve(__dirname, 'command.upgrade.controller.js')
+		)
+		.setDescription(
+			'Upgrade an existing Fonto Document History instance to the specified version.'
+		)
+
+		.addOption(
+			'location',
+			'l',
+			'The directory of the instance to upgrade. If not set this defaults to the current working directory.',
+			false
+		)
+		.addOption(
+			'version',
+			null,
+			'The version to upgrade to. Can be either a specific version or "nightly". Be warned: nightly can be unstable or may not work at all.',
+			true
+		)
+
+		.addExample(
+			`${moduleRegistration.getAppInfo().name} ${
+				constants.COMMAND_PREFIX
+			} upgrade --version x.x.x`,
+			'Upgrade the Fonto Document History instance located at the current working directory to version x.x.x.'
+		)
+		.addExample(
+			`${moduleRegistration.getAppInfo().name} ${
+				constants.COMMAND_PREFIX
+			} upgrade --location /opt/my-instance/ --version x.x.x`,
+			'Upgrade the Fonto Document History instance located at "/opt/my-instance/" to version x.x.x.'
+		);
+};

package/src/modules/document-history/src/command.versions.controller.js

@@ -1,6 +1,4 @@
-'use strict';
-
-module.exports = async function versionsCommand(req, res) {
+export default async function versionsCommand(req, res) {
 	res.caption(req.command.getLongName());
 
 	const all = req.options.all;
@@ -13,4 +11,4 @@ module.exports = async function versionsCommand(req, res) {
 	destroySpinner();
 	res.caption('Fonto Document History versions');
 	res.list(all ? sdkVersions.getAll() : sdkVersions.getAllStable(), '-');
-};
+}

package/src/modules/document-history/src/command.versions.js

@@ -1,8 +1,15 @@
-'use strict';
+import path from 'path';
+import { fileURLToPath } from 'url';
 
-module.exports = (moduleRegistration, fdhCommand) => {
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+export default (moduleRegistration, fdhCommand) => {
 	fdhCommand
-		.addCommand('versions', './command.versions.controller')
+		.addCommand(
+			'versions',
+			path.resolve(__dirname, 'command.versions.controller.js')
+		)
 		.setDescription('List the available Fonto Document History versions.')
 
 		.addHiddenOption(

package/src/modules/document-history/src/utilities/FontoxmlFdhManifest.js

@@ -0,0 +1,30 @@
+import fs from 'fs-extra';
+
+export default class FontoxmlFdhManifest {
+	constructor(fdhVersion) {
+		this.fdhVersion = fdhVersion;
+	}
+
+	static fromJsonFile(filePath) {
+		return fs
+			.exists(filePath)
+			.then((exists) => {
+				if (!exists) {
+					throw new Error(`The file ${filePath} does not exist.`);
+				}
+			})
+			.then(() => fs.readJson(filePath))
+			.then((content) => {
+				FontoxmlFdhManifest.validate(content);
+				return new FontoxmlFdhManifest(content.fdhVersion);
+			});
+	}
+
+	static validate(input) {
+		if (!input.fdhVersion) {
+			throw new Error(
+				"The Fonto Document History manifest file does not contain a 'fdhVersion'."
+			);
+		}
+	}
+}