@harperfast/harper 5.0.0-alpha.10 → 5.0.0-beta.1

package/components/operationsValidation.js

@@ -0,0 +1,246 @@
+'use strict';
+
+const Joi = require('joi');
+const fs = require('fs-extra');
+const path = require('path');
+const validator = require('../validation/validationWrapper.js');
+const envMangr = require('../utility/environment/environmentManager.js');
+const hdbTerms = require('../utility/hdbTerms.ts');
+const hdbLogger = require('../utility/logging/harper_logger.js');
+const { hdbErrors } = require('../utility/errors/hdbError.js');
+const { HDB_ERROR_MSGS } = hdbErrors;
+
+// File name can only be alphanumeric, dash and underscores
+const PROJECT_FILE_NAME_REGEX = /^[a-zA-Z0-9-_]+$/;
+
+module.exports = {
+	getDropCustomFunctionValidator,
+	setCustomFunctionValidator,
+	addComponentValidator,
+	dropCustomFunctionProjectValidator,
+	packageComponentValidator,
+	deployComponentValidator,
+	setComponentFileValidator,
+	getComponentFileValidator,
+	dropComponentFileValidator,
+};
+
+/**
+ * Check to see if a project dir exists in the custom functions dir.
+ * @param checkExists - determine if validator returns error if exists or vice versa
+ * @param project
+ * @param helpers
+ * @returns {*}
+ */
+function checkProjectExists(checkExists, project, helpers) {
+	try {
+		const cfDir = envMangr.get(hdbTerms.CONFIG_PARAMS.COMPONENTSROOT);
+		const projectDir = path.join(cfDir, project);
+
+		if (!fs.existsSync(projectDir)) {
+			if (checkExists) {
+				return helpers.message(HDB_ERROR_MSGS.NO_PROJECT);
+			}
+
+			return project;
+		}
+
+		if (checkExists) {
+			return project;
+		}
+
+		return helpers.message(HDB_ERROR_MSGS.PROJECT_EXISTS);
+	} catch (err) {
+		hdbLogger.error(err);
+		return helpers.message(HDB_ERROR_MSGS.VALIDATION_ERR);
+	}
+}
+
+function checkFilePath(path, helpers) {
+	if (path.includes('..')) return helpers.message('Invalid file path');
+	return path;
+}
+
+/**
+ * Check the custom functions dir to see if a file exists.
+ * @param project
+ * @param type
+ * @param file
+ * @param helpers
+ * @returns {*}
+ */
+function checkFileExists(project, type, file, helpers) {
+	try {
+		const cfDir = envMangr.get(hdbTerms.CONFIG_PARAMS.COMPONENTSROOT);
+		const filePath = path.join(cfDir, project, type, file + '.js');
+		if (!fs.existsSync(filePath)) {
+			return helpers.message(HDB_ERROR_MSGS.NO_FILE);
+		}
+
+		return file;
+	} catch (err) {
+		hdbLogger.error(err);
+		return helpers.message(HDB_ERROR_MSGS.VALIDATION_ERR);
+	}
+}
+
+/**
+ * Used to validate getCustomFunction and dropCustomFunction
+ * @param req
+ * @returns {*}
+ */
+function getDropCustomFunctionValidator(req) {
+	const getFuncSchema = Joi.object({
+		project: Joi.string()
+			.pattern(PROJECT_FILE_NAME_REGEX)
+			.custom(checkProjectExists.bind(null, true))
+			.required()
+			.messages({ 'string.pattern.base': HDB_ERROR_MSGS.BAD_PROJECT_NAME }),
+		type: Joi.string().valid('helpers', 'routes').required(),
+		file: Joi.string()
+			.pattern(PROJECT_FILE_NAME_REGEX)
+			.custom(checkFileExists.bind(null, req.project, req.type))
+			.custom(checkFilePath)
+			.required()
+			.messages({ 'string.pattern.base': HDB_ERROR_MSGS.BAD_FILE_NAME }),
+	});
+
+	return validator.validateBySchema(req, getFuncSchema);
+}
+
+/**
+ * Validate setCustomFunction requests.
+ * @param req
+ * @returns {*}
+ */
+function setCustomFunctionValidator(req) {
+	const setFuncSchema = Joi.object({
+		project: Joi.string()
+			.pattern(PROJECT_FILE_NAME_REGEX)
+			.custom(checkProjectExists.bind(null, true))
+			.required()
+			.messages({ 'string.pattern.base': HDB_ERROR_MSGS.BAD_PROJECT_NAME }),
+		type: Joi.string().valid('helpers', 'routes').required(),
+		file: Joi.string().custom(checkFilePath).required(),
+		function_content: Joi.string().required(),
+	});
+
+	return validator.validateBySchema(req, setFuncSchema);
+}
+
+/**
+ * Validate set_component_file requests.
+ * @param req
+ * @returns {*}
+ */
+function setComponentFileValidator(req) {
+	const setCompSchema = Joi.object({
+		project: Joi.string()
+			.pattern(PROJECT_FILE_NAME_REGEX)
+			.required()
+			.messages({ 'string.pattern.base': HDB_ERROR_MSGS.BAD_PROJECT_NAME }),
+		file: Joi.string().custom(checkFilePath).required(),
+		payload: Joi.string().allow('').optional(),
+		encoding: Joi.string().valid('utf8', 'ASCII', 'binary', 'hex', 'base64', 'utf16le', 'latin1', 'ucs2').optional(),
+	});
+
+	return validator.validateBySchema(req, setCompSchema);
+}
+
+function dropComponentFileValidator(req) {
+	const dropCompSchema = Joi.object({
+		project: Joi.string()
+			.pattern(PROJECT_FILE_NAME_REGEX)
+			.required()
+			.messages({ 'string.pattern.base': HDB_ERROR_MSGS.BAD_PROJECT_NAME }),
+		file: Joi.string().custom(checkFilePath).optional(),
+	});
+
+	return validator.validateBySchema(req, dropCompSchema);
+}
+
+function getComponentFileValidator(req) {
+	const getCompSchema = Joi.object({
+		project: Joi.string().required(),
+		file: Joi.string().custom(checkFilePath).required(),
+		encoding: Joi.string().valid('utf8', 'ASCII', 'binary', 'hex', 'base64', 'utf16le', 'latin1', 'ucs2').optional(),
+	});
+
+	return validator.validateBySchema(req, getCompSchema);
+}
+
+/**
+ * Validate addCustomFunctionProject requests.
+ * @param req
+ * @returns {*}
+ */
+function addComponentValidator(req) {
+	const addFuncSchema = Joi.object({
+		project: Joi.string()
+			.pattern(PROJECT_FILE_NAME_REGEX)
+			.custom(checkProjectExists.bind(null, false))
+			.required()
+			.messages({ 'string.pattern.base': HDB_ERROR_MSGS.BAD_PROJECT_NAME }),
+		template: Joi.string().optional(),
+		install_command: Joi.string().optional(),
+		install_timeout: Joi.number().optional(),
+	});
+
+	return validator.validateBySchema(req, addFuncSchema);
+}
+
+/**
+ * Validate dropCustomFunctionProject requests.
+ * @param req
+ * @returns {*}
+ */
+function dropCustomFunctionProjectValidator(req) {
+	const dropFuncSchema = Joi.object({
+		project: Joi.string()
+			.pattern(PROJECT_FILE_NAME_REGEX)
+			.custom(checkProjectExists.bind(null, true))
+			.required()
+			.messages({ 'string.pattern.base': HDB_ERROR_MSGS.BAD_PROJECT_NAME }),
+	});
+
+	return validator.validateBySchema(req, dropFuncSchema);
+}
+
+/**
+ * Validate packageCustomFunctionProject requests.
+ * @param req
+ * @returns {*}
+ */
+function packageComponentValidator(req) {
+	const packageProjSchema = Joi.object({
+		project: Joi.string()
+			.pattern(PROJECT_FILE_NAME_REGEX)
+			.required()
+			.messages({ 'string.pattern.base': HDB_ERROR_MSGS.BAD_PROJECT_NAME }),
+		skip_node_modules: Joi.boolean(),
+		skip_symlinks: Joi.boolean(),
+	});
+
+	return validator.validateBySchema(req, packageProjSchema);
+}
+
+/**
+ * Validate deployComponent requests.
+ * @param req
+ * @returns {*}
+ */
+function deployComponentValidator(req) {
+	const deployProjSchema = Joi.object({
+		project: Joi.string()
+			.pattern(PROJECT_FILE_NAME_REGEX)
+			.required()
+			.messages({ 'string.pattern.base': HDB_ERROR_MSGS.BAD_PROJECT_NAME }),
+		package: Joi.string().optional(),
+		restart: Joi.alternatives().try(Joi.boolean(), Joi.string().valid('rolling')).optional(),
+		install_command: Joi.string().optional(),
+		install_timeout: Joi.number().optional(),
+		force: Joi.boolean().optional(),
+	});
+
+	return validator.validateBySchema(req, deployProjSchema);
+}

package/components/packageComponent.ts

@@ -0,0 +1,39 @@
+import { join } from 'path';
+import tar from 'tar-fs';
+import { createGzip } from 'node:zlib';
+
+/**
+ * Package a directory into a tarball, base64 encoded
+ * @param directory
+ */
+export function packageDirectory(
+	directory: string,
+	options: { skip_node_modules?: boolean; skip_symlinks?: boolean } = { skip_node_modules: false, skip_symlinks: false }
+): Promise<Buffer> {
+	return new Promise((resolve, reject) => {
+		// for deployComponent to a remote server, we need to tar the local directory
+		const chunks = [];
+		// pack the directory
+		tar
+			.pack(directory, {
+				dereference: !options.skip_symlinks,
+				ignore: options.skip_node_modules
+					? (name: string) => {
+							return name.includes('node_modules') || name.includes(join('cache', 'webpack'));
+						}
+					: undefined,
+				map: (header) => {
+					if (header.type === 'directory') {
+						header.mode = 0o755;
+					}
+					return header;
+				},
+			})
+			.pipe(createGzip())
+			.on('data', (chunk: Buffer) => chunks.push(chunk))
+			.on('end', () => {
+				resolve(Buffer.concat(chunks));
+			})
+			.on('error', reject);
+	});
+}

package/components/requestRestart.ts

@@ -0,0 +1,26 @@
+import { Status } from '../server/status/index.ts';
+
+let restartArrayBuffer: ArrayBuffer;
+let restartNeededArray: Uint8Array;
+
+function ensureInitialized() {
+	if (!restartArrayBuffer) {
+		restartArrayBuffer = Status.primaryStore.getUserSharedBuffer('restart-needed', new ArrayBuffer(1));
+		restartNeededArray = new Uint8Array(restartArrayBuffer);
+	}
+}
+
+export function requestRestart() {
+	ensureInitialized();
+	restartNeededArray[0] = 1;
+}
+
+export function restartNeeded() {
+	ensureInitialized();
+	return restartNeededArray[0] === 1;
+}
+
+export function resetRestartNeeded() {
+	ensureInitialized();
+	restartNeededArray[0] = 0;
+}

package/components/resolveBaseURLPath.ts

@@ -0,0 +1,38 @@
+export class InvalidBaseURLPathError extends Error {
+	constructor(urlPath: string) {
+		super(`urlPath must not contain '..'. Received: '${urlPath}'`);
+	}
+}
+
+/**
+ * Resolve the base URL path based on the component name and `urlPath` configuration option.
+ *
+ * For example, resolving the component config `urlPath` value for component `test-component`:
+ * - `undefined`, `''`, `'/'` -> `'/'`
+ * - `'static'`, `'/static/'`, `'/static'`, `'static/'` -> `'/static/'`
+ * - `'v1/static'`, `'/v1/static/'`, `'/v1/static'`, `'v1/static/'` -> `'/v1/static/'`
+ * - `'./static'`, `'./static/'` -> `'/test-component/static/'`
+ * - `'.'`, `'./'` -> `'/test-component/'`
+ * - `'..'`, `'../'`, `'../static'`, `'./..'` -> Error
+ */
+export function resolveBaseURLPath(name: string, urlPath?: string): string {
+	if (urlPath?.includes('..')) {
+		throw new InvalidBaseURLPathError(urlPath);
+	}
+
+	let baseURLPath = urlPath || '/';
+
+	if (baseURLPath === '.' || baseURLPath.startsWith('./')) {
+		baseURLPath = `/${name}${baseURLPath.slice(1)}`;
+	}
+
+	if (!baseURLPath.startsWith('/')) {
+		baseURLPath = `/${baseURLPath}`;
+	}
+
+	if (!baseURLPath.endsWith('/')) {
+		baseURLPath = `${baseURLPath}/`;
+	}
+
+	return baseURLPath;
+}

package/components/status/ComponentStatus.ts

@@ -0,0 +1,110 @@
+/**
+ * ComponentStatus Class
+ *
+ * This module contains the ComponentStatus class which represents an individual
+ * component's status with methods for status management.
+ */
+
+import { type ComponentStatusLevel, COMPONENT_STATUS_LEVELS } from './types.ts';
+
+/**
+ * Component status information class
+ */
+export class ComponentStatus {
+	/** Last time this status was checked/updated */
+	public lastChecked: Date;
+	/** Current status level */
+	public status: ComponentStatusLevel;
+	/** Human-readable status message */
+	public message?: string;
+	/** Error information if status is 'error' */
+	public error?: Error | string;
+
+	constructor(status: ComponentStatusLevel, message?: string, error?: Error | string) {
+		this.lastChecked = new Date();
+		this.status = status;
+		this.message = message;
+		this.error = error;
+	}
+
+	/**
+	 * Update the status level and refresh the timestamp
+	 */
+	public updateStatus(status: ComponentStatusLevel, message?: string): void {
+		this.status = status;
+		this.message = message;
+		this.lastChecked = new Date();
+		// Clear error when status is not ERROR
+		if (status !== COMPONENT_STATUS_LEVELS.ERROR) {
+			this.error = undefined;
+		}
+	}
+
+	/**
+	 * Set status to healthy
+	 */
+	public markHealthy(message?: string): void {
+		this.updateStatus(COMPONENT_STATUS_LEVELS.HEALTHY, message || 'Component is healthy');
+	}
+
+	/**
+	 * Set status to error
+	 */
+	public markError(error: Error | string, message?: string): void {
+		this.status = COMPONENT_STATUS_LEVELS.ERROR;
+		this.error = error;
+		this.message = message || (typeof error === 'string' ? error : error.message);
+		this.lastChecked = new Date();
+	}
+
+	/**
+	 * Set status to warning
+	 */
+	public markWarning(message: string): void {
+		this.updateStatus(COMPONENT_STATUS_LEVELS.WARNING, message);
+	}
+
+	/**
+	 * Set status to loading
+	 */
+	public markLoading(message?: string): void {
+		this.updateStatus(COMPONENT_STATUS_LEVELS.LOADING, message || 'Component is loading');
+	}
+
+	/**
+	 * Check if component is healthy
+	 */
+	public isHealthy(): boolean {
+		return this.status === COMPONENT_STATUS_LEVELS.HEALTHY;
+	}
+
+	/**
+	 * Check if component has an error
+	 */
+	public hasError(): boolean {
+		return this.status === COMPONENT_STATUS_LEVELS.ERROR;
+	}
+
+	/**
+	 * Check if component is loading
+	 */
+	public isLoading(): boolean {
+		return this.status === COMPONENT_STATUS_LEVELS.LOADING;
+	}
+
+	/**
+	 * Check if component has a warning
+	 */
+	public hasWarning(): boolean {
+		return this.status === COMPONENT_STATUS_LEVELS.WARNING;
+	}
+
+	/**
+	 * Get a summary string of the component status
+	 */
+	public getSummary(): string {
+		const statusText = this.status.toUpperCase();
+		const messageText = this.message ? `: ${this.message}` : '';
+		return `${statusText}${messageText}`;
+	}
+}

package/components/status/ComponentStatusRegistry.ts

@@ -0,0 +1,251 @@
+/**
+ * ComponentStatusRegistry Class
+ *
+ * This module contains the ComponentStatusRegistry class which provides
+ * centralized management of component health status.
+ */
+
+import { ComponentStatus } from './ComponentStatus.ts';
+import {
+	type ComponentStatusLevel,
+	COMPONENT_STATUS_LEVELS,
+	type AggregatedComponentStatus,
+	type ComponentApplicationStatus,
+} from './types.ts';
+import { crossThreadCollector, StatusAggregator } from './crossThread.ts';
+import { ComponentStatusOperationError } from './errors.ts';
+
+/**
+ * Map of component names to their status information
+ */
+export type ComponentStatusMap = Map<string, ComponentStatus>;
+
+/**
+ * Component Status Registry Class
+ * Provides a centralized registry for managing component health status
+ */
+export class ComponentStatusRegistry {
+	private statusMap: ComponentStatusMap = new Map();
+
+	/**
+	 * Reset the component status registry, clearing all existing status data
+	 * This should be called when the component system starts up
+	 */
+	public reset(): void {
+		this.statusMap = new Map();
+	}
+
+	/**
+	 * Register or update component health status
+	 * This function allows components to report their own health status
+	 */
+	public setStatus(
+		componentName: string,
+		status: ComponentStatusLevel,
+		message?: string,
+		error?: Error | string
+	): void {
+		if (!componentName || typeof componentName !== 'string') {
+			throw new ComponentStatusOperationError(
+				String(componentName),
+				'setStatus',
+				'Component name must be a non-empty string'
+			);
+		}
+
+		if (!Object.values(COMPONENT_STATUS_LEVELS).includes(status)) {
+			throw new ComponentStatusOperationError(
+				componentName,
+				'setStatus',
+				`Invalid status level: ${status}. Must be one of: ${Object.values(COMPONENT_STATUS_LEVELS).join(', ')}`
+			);
+		}
+
+		this.statusMap.set(componentName, new ComponentStatus(status, message, error));
+	}
+
+	/**
+	 * Get the current status of a component
+	 */
+	public getStatus(componentName: string): ComponentStatus | undefined {
+		return this.statusMap.get(componentName);
+	}
+
+	/**
+	 * Get all component statuses
+	 */
+	public getAllStatuses(): ComponentStatusMap {
+		return this.statusMap;
+	}
+
+	/**
+	 * Report component as healthy
+	 */
+	public reportHealthy(componentName: string, message?: string): void {
+		this.setStatus(componentName, COMPONENT_STATUS_LEVELS.HEALTHY, message);
+	}
+
+	/**
+	 * Report component error
+	 */
+	public reportError(componentName: string, error: Error | string, message?: string): void {
+		this.setStatus(componentName, COMPONENT_STATUS_LEVELS.ERROR, message, error);
+	}
+
+	/**
+	 * Report component warning
+	 */
+	public reportWarning(componentName: string, message: string): void {
+		this.setStatus(componentName, COMPONENT_STATUS_LEVELS.WARNING, message);
+	}
+
+	/**
+	 * Component Lifecycle Management
+	 */
+
+	/**
+	 * Initialize component as loading - call this when component loading begins
+	 */
+	public initializeLoading(componentName: string, message?: string): void {
+		this.setStatus(componentName, COMPONENT_STATUS_LEVELS.LOADING, message || 'Component is loading');
+	}
+
+	/**
+	 * Mark component as successfully loaded
+	 */
+	public markLoaded(componentName: string, message?: string): void {
+		this.setStatus(componentName, COMPONENT_STATUS_LEVELS.HEALTHY, message || 'Component loaded successfully');
+	}
+
+	/**
+	 * Mark component as failed to load
+	 */
+	public markFailed(componentName: string, error: Error | string, message?: string): void {
+		this.setStatus(componentName, COMPONENT_STATUS_LEVELS.ERROR, message, error);
+	}
+
+	/**
+	 * Get all components with a specific status level
+	 */
+	public getComponentsByStatus(statusLevel: ComponentStatusLevel): Array<{ name: string; status: ComponentStatus }> {
+		const result: Array<{ name: string; status: ComponentStatus }> = [];
+		for (const [name, status] of this.statusMap) {
+			if (status.status === statusLevel) {
+				result.push({ name, status });
+			}
+		}
+		return result;
+	}
+
+	/**
+	 * Get a summary of all component statuses
+	 */
+	public getStatusSummary(): Record<ComponentStatusLevel, number> {
+		const summary: Record<ComponentStatusLevel, number> = {
+			[COMPONENT_STATUS_LEVELS.HEALTHY]: 0,
+			[COMPONENT_STATUS_LEVELS.ERROR]: 0,
+			[COMPONENT_STATUS_LEVELS.WARNING]: 0,
+			[COMPONENT_STATUS_LEVELS.LOADING]: 0,
+			[COMPONENT_STATUS_LEVELS.UNKNOWN]: 0,
+		};
+
+		for (const status of this.statusMap.values()) {
+			summary[status.status]++;
+		}
+
+		return summary;
+	}
+
+	/**
+	 * Static method to get aggregated component statuses from all threads
+	 * Returns a Map with one entry per component showing overall status and thread distribution
+	 */
+	public static async getAggregatedFromAllThreads(
+		registry: ComponentStatusRegistry
+	): Promise<Map<string, AggregatedComponentStatus>> {
+		const allStatuses = await crossThreadCollector.collect(registry);
+		return StatusAggregator.aggregate(allStatuses);
+	}
+
+	/**
+	 * Get aggregated status for a specific component and all its sub-components
+	 * This method handles both exact matches and sub-component aggregation
+	 *
+	 * @param componentName - The component name to look up (e.g., "application-template", "http")
+	 * @param consolidatedStatuses - Pre-fetched consolidated statuses from all threads (optional, will fetch if not provided)
+	 * @returns Aggregated status information for the component
+	 */
+	public async getAggregatedStatusFor(
+		componentName: string,
+		consolidatedStatuses?: Map<string, AggregatedComponentStatus>
+	): Promise<ComponentApplicationStatus> {
+		// Get consolidated statuses from all threads if not provided
+		if (!consolidatedStatuses) {
+			consolidatedStatuses = await ComponentStatusRegistry.getAggregatedFromAllThreads(this);
+		}
+
+		// Collect all statuses related to this component
+		const allStatuses = [];
+		const componentPrefix = componentName + '.';
+
+		// Add exact match if exists
+		const exactMatch = consolidatedStatuses.get(componentName);
+		if (exactMatch) {
+			allStatuses.push({ key: componentName, ...exactMatch });
+		}
+
+		// Add sub-component statuses
+		for (const [statusKey, statusValue] of consolidatedStatuses) {
+			if (statusKey.startsWith(componentPrefix)) {
+				allStatuses.push({ key: statusKey, ...statusValue });
+			}
+		}
+
+		if (allStatuses.length === 0) {
+			// No status found at all
+			return {
+				status: COMPONENT_STATUS_LEVELS.UNKNOWN,
+				message: 'The component has not been loaded yet (may need a restart)',
+				lastChecked: { workers: {} },
+			};
+		}
+
+		// Aggregate all statuses
+		const hasErrors = allStatuses.some((s) => s.status === COMPONENT_STATUS_LEVELS.ERROR);
+		const hasLoading = allStatuses.some((s) => s.status === COMPONENT_STATUS_LEVELS.LOADING);
+
+		const overallStatus = hasErrors
+			? COMPONENT_STATUS_LEVELS.ERROR
+			: hasLoading
+				? COMPONENT_STATUS_LEVELS.LOADING
+				: COMPONENT_STATUS_LEVELS.HEALTHY;
+
+		// Show details if anything is not healthy
+		let overallMessage = 'All components loaded successfully';
+		const details: Record<string, { status: ComponentStatusLevel; message?: string }> = {};
+
+		if (hasErrors || hasLoading) {
+			const problemStatuses = allStatuses.filter(
+				(s) => s.status === COMPONENT_STATUS_LEVELS.ERROR || s.status === COMPONENT_STATUS_LEVELS.LOADING
+			);
+			overallMessage = problemStatuses.map((s) => `${s.key}: ${s.latestMessage || s.status}`).join('; ');
+
+			// Include details for debugging
+			for (const status of allStatuses) {
+				if (status.status !== COMPONENT_STATUS_LEVELS.HEALTHY) {
+					details[status.key] = {
+						status: status.status,
+						message: status.latestMessage,
+					};
+				}
+			}
+		}
+
+		return {
+			status: overallStatus,
+			message: overallMessage,
+			...(Object.keys(details).length > 0 && { details }),
+			lastChecked: allStatuses[0]?.lastChecked || { workers: {} },
+		};
+	}
+}