@fontoxml/fontoxml-development-tools 3.11.0 → 3.12.0

package/src/modules/shared/src/controller-templates/command.backend.run.controller.factory.js

@@ -0,0 +1,420 @@
+import fs from 'fs-extra';
+import os from 'os';
+import path from 'path';
+
+import ensureDockerCommands from '../ensureDockerCommands.js';
+import executeAndLog, {
+	getVerbosityLevel,
+	VERBOSITY_LEVEL,
+} from '../executeAndLog.js';
+import setFileVisibility from '../setFileVisibility.js';
+import BackendManifest from './docker/BackendManifest.js';
+import copyWhitelistedFiles from './docker/copyWhitelistedFiles.js';
+import dockerCleanup from './docker/dockerCleanup.js';
+import tryDockerLogout from './docker/tryDockerLogout.js';
+import validateBackendInstance from './docker/validateBackendInstance.js';
+
+/** @typedef {import('../addBackendDockerCommands').AddBackendDockerCommandsOptions} AddBackendDockerCommandsOptions */
+
+/**
+ * @param {string}                  configurationFilePath
+ * @param {string}                  tempDir
+ * @param {{[key: string]: string}} debugEnvEntries
+ * @param {number}                  verbosityLevel
+ * @param {FdtResponse}             res
+ *
+ * @return {Promise<void>}
+ */
+async function copyConfiguration(
+	configurationFilePath,
+	tempDir,
+	debugEnvEntries,
+	verbosityLevel,
+	res
+) {
+	const targetConfiguration = path.join(tempDir, '.env');
+
+	const exists = await fs.exists(configurationFilePath);
+
+	// Read the configuration entries from the .env file or initialize an empty array.
+	const configurationEntries = exists
+		? await fs
+				.readFile(configurationFilePath, 'utf8')
+				.then((data) => data.split(/\r?\n/g))
+		: [];
+
+	// Replace or set the defaults for verbosity.
+	if (verbosityLevel === VERBOSITY_LEVEL.DEBUG) {
+		Object.keys(debugEnvEntries).forEach((key) => {
+			const configurationEntryIndex = configurationEntries.findIndex(
+				(entry) => entry.startsWith(`${key}=`)
+			);
+			const value = debugEnvEntries[key];
+			if (configurationEntryIndex === -1) {
+				configurationEntries.push(`${key}=${value}`);
+			} else {
+				configurationEntries[
+					configurationEntryIndex
+				] = `${key}=${value}`;
+			}
+		});
+	}
+
+	// Ignore options that shouldn't be applied when running through FDT.
+	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.'
+				);
+			}
+		}
+	}
+
+	// Write the configuration to the .env file.
+	const configurationData = configurationEntries.join(os.EOL);
+	await fs.writeFile(targetConfiguration, configurationData, 'utf8');
+}
+
+/**
+ * @param {AddBackendDockerCommandsOptions} options
+ *
+ * @returns {(req: AskNicelyRequest, res: FdtResponse) => Promise<void>}
+ */
+export default function backendRunCommandFactory(options) {
+	return async function backendRunCommand(req, res) {
+		res.caption(req.command.getLongName());
+
+		const directoryPath = path.resolve(
+			req.options.location ? req.options.location : process.cwd()
+		);
+		const temporaryDirectoryPath = path.join(
+			directoryPath,
+			options.temporaryDirectoryName
+		);
+		const configurationFilePath = req.options['config-location']
+			? path.resolve(req.options['config-location'])
+			: path.join(directoryPath, '.env');
+		const manifestFilePath = path.join(
+			directoryPath,
+			options.manifestFileName
+		);
+		const verbosityLevel = getVerbosityLevel(
+			req.options.verbose,
+			req.options.debug
+		);
+		const hasHttps = !!options.defaultHttpsPort;
+		const httpPort =
+			(hasHttps ? req.options['http-port'] : req.options.port) ||
+			options.defaultHttpPort;
+		const httpsPort = req.options['https-port'] || options.defaultHttpsPort;
+		const projectName = hasHttps
+			? `${options.defaultImageName}_${httpPort}_${httpsPort}`
+			: `${options.defaultImageName}_${httpPort}`;
+
+		// Check if the working directory path exists and is a directory.
+		try {
+			const stats = await fs.stat(directoryPath);
+			if (!stats.isDirectory()) {
+				throw new res.InputError(
+					'The provided location is not a directory.'
+				);
+			}
+		} catch (error) {
+			if (error.code === 'ENOENT') {
+				throw new res.InputError(
+					'The provided location does not exist.'
+				);
+			}
+			throw error;
+		}
+
+		// Ensure that the Docker commands are available.
+		await ensureDockerCommands(directoryPath, res, {
+			checkDocker: true,
+			checkDockerCompose: true,
+		});
+
+		let pidToKillOnForceExit = null;
+		const setPidToKillOnForceExit = (processToKill) => {
+			pidToKillOnForceExit = processToKill && processToKill.pid;
+		};
+
+		// Ensure we cleanup before exiting on SIGINT.
+		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)');
+			// eslint-disable-next-line consistent-return
+			return dockerCleanup(
+				temporaryDirectoryPath,
+				projectName,
+				res,
+				verbosityLevel
+			).then(() => {
+				process.exit();
+			});
+		});
+
+		try {
+			await validateBackendInstance(directoryPath, options);
+
+			const configurationFileExists = await fs.exists(
+				configurationFilePath
+			);
+			if (!configurationFileExists) {
+				if (req.options['config-location']) {
+					throw new res.InputError(
+						`${options.productLabel} config "${configurationFilePath}" does not exist.`
+					);
+				}
+				res.notice(
+					`No .env file exists in the directory "${directoryPath}".${
+						options.documentationConfigurationGuide
+							? ` Information about the .env file can be found at ${options.documentationConfigurationGuide}.`
+							: ''
+					}`
+				);
+			}
+
+			// Cleanup possible remaining resources from a previous build or run.
+			await dockerCleanup(
+				temporaryDirectoryPath,
+				projectName,
+				res,
+				verbosityLevel
+			);
+
+			const destroySpinner = res.spinner(
+				`Building development image at "${directoryPath}"...`
+			);
+
+			// Read the manifest file.
+			const manifestObj = await BackendManifest.fromJsonFile(
+				manifestFilePath,
+				options.manifestVersionPropertyName
+			);
+
+			// Retrieve data for the docker image
+			let dockerData;
+			try {
+				const requestObj = {
+					[options.licenseProductName]: {
+						docker: {
+							version: manifestObj.version,
+						},
+					},
+				};
+				const productData = await req.fdt.license.getDataForProducts(
+					requestObj
+				);
+				dockerData =
+					productData.products[options.licenseProductName].docker;
+			} catch (error) {
+				if (error.statusCode === 404) {
+					error.solution = `This error might be caused by requesting a nonexistent ${options.productLabel} version, please check your version.`;
+				}
+				throw error;
+			}
+
+			// Create a hidden temporary directory.
+			await fs.mkdir(temporaryDirectoryPath);
+			await setFileVisibility(temporaryDirectoryPath, false);
+			// Copy the instance files into the temporary directory.
+			const dockerfileContent = await fs.readFile(
+				options.instanceDevBuildDockerfilePath,
+				'utf8'
+			);
+			// Rewrite the image in the Dockerfile.
+			const fixedDockerfileContent = dockerfileContent.replace(
+				'${image}',
+				dockerData.image
+			);
+			await fs.writeFile(
+				path.join(temporaryDirectoryPath, 'Dockerfile'),
+				fixedDockerfileContent,
+				'utf8'
+			);
+			// Copy the dev instance files.
+			await fs.copy(
+				options.instanceDevBuildDirectoryPath,
+				temporaryDirectoryPath
+			);
+			// Rewrite the port in the docker-compose file.
+			const dockerComposeContent = await fs.readFile(
+				path.join(temporaryDirectoryPath, 'docker-compose.yml'),
+				'utf8'
+			);
+			const fixedDockerComposeContent = dockerComposeContent
+				.replace('${containerName}', projectName)
+				.replace('${httpPort}', httpPort)
+				.replace('${httpsPort}', httpsPort);
+			await fs.writeFile(
+				path.join(temporaryDirectoryPath, 'docker-compose.yml'),
+				fixedDockerComposeContent,
+				'utf8'
+			);
+			const temporaryInstanceDirectoryPath = path.join(
+				temporaryDirectoryPath,
+				'instance'
+			);
+			await fs.ensureDir(temporaryInstanceDirectoryPath);
+			// Copy whitelisted files.
+			await copyWhitelistedFiles(
+				options.whitelist,
+				directoryPath,
+				temporaryInstanceDirectoryPath
+			);
+			// Copy configuration.
+			await copyConfiguration(
+				configurationFilePath,
+				temporaryDirectoryPath,
+				options.debugEnvEntries,
+				verbosityLevel,
+				res
+			);
+
+			// Pull the docker image.
+			try {
+				await executeAndLog(
+					res,
+					'docker',
+					[
+						'login',
+						dockerData.registry,
+						'-u',
+						dockerData.login,
+						'-p',
+						dockerData.password,
+					],
+					null,
+					VERBOSITY_LEVEL.NORMAL,
+					false,
+					setPidToKillOnForceExit
+				);
+				await executeAndLog(
+					res,
+					'docker',
+					['pull', dockerData.image],
+					null,
+					verbosityLevel,
+					false,
+					setPidToKillOnForceExit
+				);
+			} catch (error) {
+				await tryDockerLogout(
+					dockerData.registry,
+					res,
+					setPidToKillOnForceExit
+				);
+				throw new res.ErrorWithInnerError(
+					'Failed to retrieve the image file.',
+					error
+				);
+			}
+
+			// Use docker-compose to build the development image.
+			try {
+				await executeAndLog(
+					res,
+					'docker',
+					verbosityLevel === VERBOSITY_LEVEL.DEBUG
+						? ['compose', '-p', projectName, '--verbose', 'build']
+						: ['compose', '-p', projectName, 'build'],
+					temporaryDirectoryPath,
+					verbosityLevel,
+					false,
+					setPidToKillOnForceExit
+				);
+			} finally {
+				await tryDockerLogout(
+					dockerData.registry,
+					res,
+					setPidToKillOnForceExit
+				);
+			}
+
+			// Send telemetry.
+			await req.fdt.license.sendTelemetry({
+				product: req.command.parent.name,
+				type: 'docker',
+				version: manifestObj.version,
+				action: req.command.name,
+			});
+
+			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.
+			// See: https://github.com/docker/compose/issues/3447
+			res.notice(
+				`Starting ${
+					options.productLabel
+				} on "http://localhost:${httpPort}"${
+					hasHttps ? ` and http://localhost::${httpsPort}` : ''
+				}...`
+			);
+			await executeAndLog(
+				res,
+				'docker',
+				verbosityLevel === VERBOSITY_LEVEL.DEBUG
+					? ['compose', '-p', projectName, '--verbose', 'up']
+					: ['compose', '-p', projectName, 'up'],
+				temporaryDirectoryPath,
+				verbosityLevel,
+				true,
+				setPidToKillOnForceExit,
+				// Allow exit code is 130 (128 + 2 = 130; 2 coming from Control-C).
+				[130]
+			);
+
+			// Cleanup temporary directory.
+			await dockerCleanup(
+				temporaryDirectoryPath,
+				projectName,
+				res,
+				verbosityLevel
+			);
+		} catch (error) {
+			if (!stopping) {
+				res.notice(
+					options.documentationExecuteError
+						? `See our documentation at ${options.documentationExecuteError} for help.`
+						: 'See our documentation for help.'
+				);
+			}
+
+			try {
+				await dockerCleanup(
+					temporaryDirectoryPath,
+					projectName,
+					res,
+					verbosityLevel
+				);
+			} catch (_cleanupError) {
+				// Ignore cleanup error.
+			}
+
+			// Re-throw the actual error.
+			throw error;
+		}
+	};
+}

package/src/modules/shared/src/controller-templates/command.backend.upgrade.controller.factory.js

@@ -0,0 +1,79 @@
+import fs from 'fs-extra';
+import path from 'path';
+
+import setFileVisibility from '../setFileVisibility.js';
+import BackendManifest from './docker/BackendManifest.js';
+
+/** @typedef {import('../addBackendDockerCommands').AddBackendDockerCommandsOptions} AddBackendDockerCommandsOptions */
+
+/**
+ * @param {AddBackendDockerCommandsOptions} options
+ *
+ * @returns {(req: AskNicelyRequest, res: FdtResponse) => Promise<void>}
+ */
+export default function backendUpgradeCommandFactory(options) {
+	return async function backendUpgradeCommand(req, res) {
+		res.caption(req.command.getLongName());
+
+		// Check if the given version exist.
+		const sdkVersions = await req.fdt.license.getVersionsForProduct(
+			options.licenseProductName
+		);
+		const version = req.options.version;
+		if (!sdkVersions.includes(version)) {
+			throw new res.ErrorWithSolution(
+				`Could not upgrade to version (${version}), please check if it is a valid version. The latest version is ${sdkVersions.getLatestStable()}.`,
+				`Run \`fdt ${options.commandPrefix} versions\` to get a list of all available versions.`
+			);
+		}
+
+		const destroySpinner = res.spinner(
+			`Upgrading your ${options.productLabel} instance to ${version}...`
+		);
+
+		const directoryPath = path.resolve(
+			req.options.location ? req.options.location : process.cwd()
+		);
+		const manifestFilePath = path.join(
+			directoryPath,
+			options.manifestFileName
+		);
+		let currentVersion;
+
+		try {
+			await setFileVisibility(manifestFilePath, true);
+
+			// Read the manifest file.
+			const manifestObj = await BackendManifest.fromJsonFile(
+				manifestFilePath,
+				options.manifestVersionPropertyName
+			);
+
+			// Update the manifest file.
+			currentVersion = manifestObj.version;
+			manifestObj.version = version;
+			await fs.writeJson(manifestFilePath, manifestObj);
+
+			await setFileVisibility(manifestFilePath, false);
+
+			// Send telemetry.
+			await req.fdt.license.sendTelemetry({
+				product: req.command.parent.name,
+				type: 'docker',
+				version,
+				currentVersion,
+				action: req.command.name,
+			});
+
+			destroySpinner();
+		} catch (error) {
+			res.notice(
+				options.documentationExecuteError
+					? `See our documentation at ${options.documentationExecuteError} for help.`
+					: 'See our documentation for help.'
+			);
+
+			throw error;
+		}
+	};
+}

package/src/modules/shared/src/controller-templates/command.backend.versions.controller.factory.js

@@ -0,0 +1,23 @@
+/** @typedef {import('../addBackendVersionsCommands').AddBackendVersionsCommandsOptions} AddBackendVersionsCommandsOptions */
+
+/**
+ * @param {AddBackendVersionsCommandsOptions} options
+ *
+ * @returns {(req: AskNicelyRequest, res: FdtResponse) => Promise<void>}
+ */
+export default function backendVersionsCommandFactory(options) {
+	return async function backendVersionsCommand(req, res) {
+		res.caption(req.command.getLongName());
+
+		const all = req.options.all;
+		const destroySpinner = res.spinner(
+			`Retrieving ${all ? 'all ' : ''}${options.productLabel} versions...`
+		);
+		const sdkVersions = await req.fdt.license.getVersionsForProduct(
+			options.licenseProductName
+		);
+		destroySpinner();
+		res.caption(`${options.productLabel} versions`);
+		res.list(all ? sdkVersions.getAll() : sdkVersions.getAllStable(), '-');
+	};
+}

package/src/modules/shared/src/controller-templates/docker/BackendManifest.js

@@ -0,0 +1,42 @@
+import fs from 'fs-extra';
+
+export default class BackendManifest {
+	/**
+	 * @param {string} versionPropertyName
+	 * @param {string} version
+	 */
+	constructor(versionPropertyName, version) {
+		this.versionPropertyName = versionPropertyName;
+		this.version = version;
+	}
+
+	toJSON() {
+		return {
+			[this.versionPropertyName]: this.version,
+		};
+	}
+
+	/**
+	 * @param {string} filePath
+	 * @param {string} versionPropertyName
+	 *
+	 * @return {Promise<BackendManifest>}
+	 */
+	static async fromJsonFile(filePath, versionPropertyName) {
+		if (!(await fs.exists(filePath))) {
+			throw new Error(`The manifest file ${filePath} does not exist.`);
+		}
+
+		const json = await fs.readJson(filePath);
+		const version = json[versionPropertyName];
+		if (!version) {
+			throw new Error(
+				`The manifest file does not contain a '${versionPropertyName}'.`
+			);
+		}
+		return new BackendManifest(
+			versionPropertyName,
+			json[versionPropertyName]
+		);
+	}
+}

package/src/modules/shared/src/controller-templates/docker/copyWhitelistedFiles.js

@@ -0,0 +1,23 @@
+import fs from 'fs-extra';
+import path from 'path';
+
+/**
+ * @param {string[]} whitelist
+ * @param {string}   sourceDirectory
+ * @param {string}   destinationDirectory
+ *
+ * @return {Promise<void>}
+ */
+export default async function copyWhitelistedFiles(
+	whitelist,
+	sourceDirectory,
+	destinationDirectory
+) {
+	for (const item of whitelist) {
+		const itemPath = path.join(sourceDirectory, item);
+		const exists = await fs.exists(itemPath);
+		if (exists) {
+			await fs.copy(itemPath, path.join(destinationDirectory, item));
+		}
+	}
+}