web_plsql 0.5.0 → 0.6.0

package/src/file.js

@@ -0,0 +1,77 @@
+import {promises as fs, readFileSync} from 'node:fs';
+
+/**
+ * Read file.
+ *
+ * @param {string} filePath - File name.
+ * @returns {Promise<Buffer>} The buffer.
+ */
+export const readFile = (filePath) => {
+	try {
+		return fs.readFile(filePath);
+	} catch (err) {
+		/* istanbul ignore next */
+		throw new Error(`Unable to read file "${filePath}"`);
+	}
+};
+
+/**
+ * Remove file.
+ *
+ * @param {string} filePath - File name.
+ * @returns {Promise<void>}.
+ */
+export const removeFile = (filePath) => {
+	try {
+		return fs.unlink(filePath);
+	} catch (err) {
+		/* istanbul ignore next */
+		throw new Error(`Unable to remove file "${filePath}"`);
+	}
+};
+
+/**
+ * Load a json file.
+ *
+ * @param {string} filePath - File name.
+ * @returns {unknown} The json object.
+ */
+export const getJsonFile = (filePath) => {
+	const fileContent = readFileSync(filePath, 'utf8');
+
+	try {
+		return JSON.parse(fileContent);
+	} catch (err) {
+		throw new Error(`Unable to load file "${filePath}"`);
+	}
+};
+
+/**
+ * Is this a directory.
+ * @param {unknown} directoryPath - Directory name.
+ * @returns {Promise<boolean>} - Return true if it is a directory.
+ */
+export const isDirectory = async (directoryPath) => {
+	if (typeof directoryPath !== 'string') {
+		return false;
+	}
+
+	const stats = await fs.stat(directoryPath);
+
+	return stats.isDirectory();
+};
+
+/**
+ * Is this a file.
+ * @param {unknown} filePath - File name.
+ * @returns {Promise<boolean>} - Return true if it is a file.
+ */
+export const isFile = async (filePath) => {
+	if (typeof filePath !== 'string') {
+		return false;
+	}
+
+	const stats = await fs.stat(filePath);
+
+	return stats.isFile();
+};

package/src/handlerLogger.js

@@ -0,0 +1,21 @@
+import debugModule from 'debug';
+const debug = debugModule('webplsql:handlerLogger');
+
+import fs from 'node:fs';
+import path from 'node:path';
+import morgan from 'morgan';
+
+/**
+ * @typedef {import('express').RequestHandler} RequestHandler
+ */
+
+/**
+ * Create the upload middleware.
+ * @param {string} filename - Output filename.
+ * @returns {RequestHandler} - Request handler.
+ */
+export const handlerLogger = (filename) => {
+	debug('register');
+
+	return morgan('combined', {stream: fs.createWriteStream(path.join(process.cwd(), filename), {flags: 'a'})});
+};

package/src/handlerMetrics.js

@@ -0,0 +1,46 @@
+import debugModule from 'debug';
+const debug = debugModule('webplsql:handlerMetrics');
+
+/**
+ * @typedef {import('express').RequestHandler} RequestHandler
+ * @typedef {import('./types.js').metricsType} metricsType
+ */
+
+/**
+ * metrics initializer.
+ * @returns {metricsType} The metrics.
+ */
+export const initMetrics = () => {
+	return {
+		totalRequests: 0,
+		requestsInLastInterval: 0,
+	};
+};
+
+/**
+ * The metrics handler.
+ * @param {metricsType} metrics - the nmetrics.
+ * @returns {RequestHandler} - Request handler.
+ */
+export const handlerMetrics = (metrics) => {
+	debug('register');
+
+	metrics.totalRequests = 0;
+	metrics.requestsInLastInterval = 0;
+
+	return (req, res, next) => {
+		metrics.totalRequests++;
+		metrics.requestsInLastInterval++;
+
+		if (debug.enabled) {
+			const start = process.hrtime();
+			res.on('finish', () => {
+				const [seconds, nanoseconds] = process.hrtime(start);
+				const duration = seconds * 1000 + nanoseconds / 1_000_000;
+				debug(`Request to ${req.params?.name} ${req.url} took ${duration.toFixed(3)}ms`);
+			});
+		}
+
+		next();
+	};
+};

package/src/handlerPlSql.js

@@ -0,0 +1,65 @@
+/*
+ *	Express middleware for Oracle PL/SQL
+ */
+
+import debugModule from 'debug';
+const debug = debugModule('webplsql:handlerPlSql');
+
+import url from 'node:url';
+import {processRequest} from './request.js';
+import {RequestError} from './requestError.js';
+import {errorPage} from './errorPage.js';
+
+/**
+ * @typedef {import('express').RequestHandler} RequestHandler
+ * @typedef {import('express').Request} Request
+ * @typedef {import('express').Response} Response
+ * @typedef {import('express').NextFunction} NextFunction
+ * @typedef {import('oracledb').Pool} Pool
+ * @typedef {import('./types.js').environmentType} environmentType
+ * @typedef {import('./types.js').configPlSqlHandlerType} configPlSqlHandlerType
+ */
+
+/**
+ * express.Request handler
+ * @param {Request} req - The req object represents the HTTP request.
+ * @param {Response} res - The res object represents the HTTP response that an Express app sends when it gets an HTTP request.
+ * @param {NextFunction} next - The next function.
+ * @param {Pool} connectionPool - The connection pool.
+ * @param {configPlSqlHandlerType} options - the options for the middleware.
+ */
+const requestHandler = async (req, res, next, connectionPool, options) => {
+	try {
+		// should we switch to the default page if there is one defined
+		if (typeof req.params.name !== 'string' || req.params.name.length === 0) {
+			if (typeof options.defaultPage === 'string' && options.defaultPage.length > 0) {
+				const newUrl = url.resolve(`${req.originalUrl}/${options.defaultPage}`, '');
+				debug(`Redirect to the url "${newUrl}"`);
+				res.redirect(newUrl);
+			} else {
+				/* istanbul ignore next */
+				errorPage(req, res, options, new RequestError('No procedure name given and no default page has been specified'));
+			}
+		} else {
+			await processRequest(req, res, options, connectionPool);
+		}
+	} catch (err) {
+		/* istanbul ignore next */
+		errorPage(req, res, options, err);
+	}
+};
+
+/**
+ * Express middleware.
+ *
+ * @param {Pool} connectionPool - The connection pool.
+ * @param {configPlSqlHandlerType} config - The configuration options.
+ * @returns {RequestHandler} - The handler.
+ */
+export const handlerWebPlSql = (connectionPool, config) => {
+	debug('options', config);
+
+	return (req, res, next) => {
+		void requestHandler(req, res, next, connectionPool, config);
+	};
+};

package/src/handlerUpload.js

@@ -0,0 +1,32 @@
+import path from 'node:path';
+import multer from 'multer';
+
+/**
+ * @typedef {import('express').RequestHandler} RequestHandler
+ * @typedef {import('express').Response} Response
+ * @typedef {import('express').NextFunction} NextFunction
+ * @typedef {import('oracledb').Pool} Pool
+ * @typedef {import('./types.js').environmentType} environmentType
+ * @typedef {import('./types.js').configType} configType
+ */
+
+/**
+ * Create the upload middleware.
+ * @returns {RequestHandler} - Request handler.
+ */
+export const handlerUpload = () => {
+	const upload = multer({
+		storage: multer.diskStorage({
+			destination: '/tmp/uploads',
+			filename: (req, file, cb) => {
+				const uniqueSuffix = `${Date.now()}-${Math.round(Math.random() * 1e9)}`;
+				cb(null, `${file.fieldname}-${uniqueSuffix}${path.extname(file.originalname)}`);
+			},
+		}),
+		limits: {
+			fileSize: 50 * 1024 * 1024, // 50MB limit
+		},
+	});
+
+	return upload.any();
+};

package/src/index.js

@@ -0,0 +1,17 @@
+// server
+export {startServer} from './server.js';
+export * from './shutdown.js';
+
+// handler
+export {handlerWebPlSql} from './handlerPlSql.js';
+export {handlerLogger} from './handlerLogger.js';
+export {initMetrics, handlerMetrics} from './handlerMetrics.js';
+export {handlerUpload} from './handlerUpload.js';
+
+// oracle
+export * from './oracle.js';
+
+// util
+export * from './file.js';
+export * from './tty.js';
+export * from './version.js';

package/src/oracle.js

@@ -0,0 +1,80 @@
+import debugModule from 'debug';
+const debug = debugModule('webplsql:oracle');
+
+import oracledb from 'oracledb';
+
+/**
+ * @typedef {import('oracledb').Pool} Pool
+ */
+
+/**
+ * Test is the connection is valid.
+ * @param {Pool} connectionPool - database connection
+ * @returns {Promise<boolean>} - success
+ */
+export const connectionValid = async (connectionPool) => {
+	let connection;
+	try {
+		connection = await connectionPool.getConnection();
+		debug('connection valid');
+		return true;
+	} catch (err) {
+		debug('connection broken', err);
+		return false;
+	} finally {
+		if (connection) {
+			await connection.release();
+		}
+	}
+};
+
+/**
+ * Allocate the Oracle database pool.
+ * @param {string} user - The database user name.
+ * @param {string} password - The password of the database user.
+ * @param {string} connectString - The Oracle database instance to connect to. The string can be an Easy Connect string, or a Net Service Name from a tnsnames.ora file, or the name of a local Oracle database instance.
+ * @param {number} poolMin - The minimum number of connections a connection pool maintains.
+ * @param {number} poolMax - The maximum number of connections to which a connection pool can grow.
+ * @returns {Promise<Pool>} - The connection pool.
+ */
+export const poolCreate = async (user, password, connectString, poolMin = 10, poolMax = 1000) => {
+	const pool = await oracledb.createPool({
+		user, // The database user name.
+		password, // The password of the database user.
+		connectString, // The Oracle database instance to connect to. The string can be an Easy Connect string, or a Net Service Name from a tnsnames.ora file, or the name of a local Oracle database instance.
+		poolMin, // The minimum number of connections a connection pool maintains, even when there is no activity to the target database.
+		poolMax, // The maximum number of connections to which a connection pool can grow.
+		poolIncrement: 10, // The number of connections that are opened whenever a connection request exceeds the number of currently open connections.
+		queueTimeout: 1000, // The number of milliseconds after which connection requests waiting in the connection request queue are terminated. If queueTimeout is 0, then queued connection requests are never terminated.
+	});
+
+	const valid = await connectionValid(pool);
+	if (!valid) {
+		await poolClose(pool);
+		throw new Error(`Unable to connect with Oracle Database as ${user}@${connectString}`);
+	}
+
+	return pool;
+};
+
+/**
+ * Close the Oracle database pool.
+ * @param {Pool} pool - The connection pool.
+ * @returns {Promise<void>}
+ */
+export const poolClose = async (pool) => {
+	try {
+		await pool.close(0);
+	} catch (err) {
+		debug('Cannot close pool', err);
+	}
+};
+
+/**
+ * Close the Oracle database pools.
+ * @param {Pool[]} pools - The connection pools.
+ * @returns {Promise<void>}
+ */
+export const poolsClose = async (pools) => {
+	await Promise.all(pools.map(poolClose));
+};

package/src/parsePage.js

@@ -0,0 +1,193 @@
+/**
+ * @typedef {import('./types.js').pageType} pageType
+ * @typedef {import('./types.js').cookieType} cookieType
+ */
+
+/**
+ *	Parse the header and split it up into the individual components
+ *
+ * @param {string} text - The text returned from the PL/SQL procedure.
+ * @returns {pageType} - The parsed page.
+ */
+export const parsePage = (text) => {
+	/** @type {pageType} */
+	const page = {
+		body: '',
+		head: {
+			cookies: [],
+			otherHeaders: {},
+		},
+		file: {
+			fileType: null,
+			fileSize: null,
+			fileBlob: null,
+		},
+	};
+
+	//
+	//	1)	Split up the text in header and body
+	//
+
+	// Find the end of the header identified by \n\n
+	let head = '';
+	const headerEndPosition = text.indexOf('\n\n');
+	if (headerEndPosition === -1) {
+		head = text;
+	} else {
+		head = text.substring(0, headerEndPosition + 2);
+		page.body = text.substring(headerEndPosition + 2);
+	}
+
+	//
+	//	2)	parse the headers
+	//
+
+	head.split('\n').forEach((line) => {
+		const header = getHeader(line);
+
+		if (header) {
+			switch (header.name.toLowerCase()) {
+				case 'set-cookie':
+					{
+						const cookie = parseCookie(header.value);
+						/* istanbul ignore else */
+						if (cookie !== null) {
+							page.head.cookies.push(cookie);
+						}
+					}
+					break;
+
+				case 'content-type':
+					page.head.contentType = header.value;
+					break;
+
+				case 'x-db-content-length':
+					{
+						const contentLength = parseInt(header.value, 10);
+						/* istanbul ignore else */
+						if (!Number.isNaN(contentLength)) {
+							page.head.contentLength = contentLength;
+						}
+					}
+					break;
+
+				case 'status':
+					{
+						const statusCode = parseInt(header.value, 10);
+						/* istanbul ignore else */
+						if (!Number.isNaN(statusCode)) {
+							page.head.statusCode = statusCode;
+							const index = header.value.indexOf(' ');
+							/* istanbul ignore else */
+							if (index !== -1) {
+								page.head.statusDescription = header.value.substring(index + 1);
+							}
+						}
+					}
+					break;
+
+				case 'location':
+					page.head.redirectLocation = header.value;
+					break;
+
+				case 'x-oracle-ignore':
+					break;
+
+				default:
+					page.head.otherHeaders[header.name] = header.value;
+					break;
+			}
+		}
+	});
+
+	return page;
+};
+
+/**
+ *	Get a header line
+ *	@param {string} line - The line
+ *	@returns {{name: string, value: string} | null} - The header.
+ */
+const getHeader = (line) => {
+	const index = line.indexOf(':');
+
+	if (index !== -1) {
+		return {
+			name: line.substring(0, index).trim(),
+			value: line.substring(index + 1).trim(),
+		};
+	}
+
+	return null;
+};
+
+/**
+ *	Parses a cookie string
+ *	@param {string} text - The cookie string.
+ *	@returns {cookieType | null} - The parsed cookie.
+ */
+const parseCookie = (text) => {
+	// validate
+	/* istanbul ignore next */
+	if (typeof text !== 'string' || text.trim().length === 0) {
+		return null;
+	}
+
+	// split the cookie into it's parts
+	let cookieElements = text.split(';');
+
+	// trim cookie elements
+	cookieElements = cookieElements.map((element) => element.trim());
+
+	// get name and value
+	const index = cookieElements[0].indexOf('=');
+	/* istanbul ignore next */
+	if (index <= 0) {
+		// if the index is -1, there is no equal sign and if it's 0 the name is empty
+		return null;
+	}
+
+	/** @type {cookieType} */
+	const cookie = {
+		name: cookieElements[0].substring(0, index).trim(),
+		value: cookieElements[0].substring(index + 1).trim(),
+	};
+
+	// remove the fisrt element
+	cookieElements.shift();
+
+	// get the other options
+	cookieElements.forEach((element) => {
+		if (element.startsWith('path=')) {
+			cookie.path = element.substring(5);
+		} else if (element.toLowerCase().startsWith('domain=')) {
+			cookie.domain = element.substring(7);
+		} else if (element.toLowerCase().startsWith('secure=')) {
+			/* istanbul ignore next */
+			cookie.secure = element.substring(7);
+		} else if (element.toLowerCase().startsWith('expires=')) {
+			const date = tryDecodeDate(element.substring(8));
+			if (date) {
+				cookie.expires = date;
+			}
+		} else if (element.toLowerCase().startsWith('httponly')) {
+			cookie.httpOnly = true;
+		}
+	});
+
+	return cookie;
+};
+
+/**
+ * Try to decode a date
+ * @param {string} value - The value to decode.
+ * @returns {Date | null} - The decoded date or null.
+ */
+const tryDecodeDate = (value) => {
+	try {
+		return new Date(value);
+	} catch (err) {
+		/* istanbul ignore next */
+		return null;
+	}
+};