web_plsql 0.5.0 → 0.6.0

package/package.json

@@ -1,85 +1,92 @@
 {
-  "name": "web_plsql",
-  "version": "0.5.0",
-  "author": "Dieter Oberkofler <dieter.oberkofler@gmail.com>",
-  "license": "MIT",
-  "description": "The Express Middleware for Oracle PL/SQL",
-  "keywords": [
-    "node",
-    "nodejs",
-    "express",
-    "middleware",
-    "mod_plsql",
-    "plsql",
-    "pl/sql",
-    "oracle",
-    "ohs",
-    "ords",
-    "gateway",
-    "apex"
-  ],
-  "homepage": "https://github.com/doberkofler/web_plsql",
-  "engines": {
-    "node": ">=16"
-  },
-  "maintainers": [
-    {
-      "name": "Dieter Oberkofler",
-      "email": "dieter.oberkofler@gmail.com"
-    }
-  ],
-  "bugs": {
-    "url": "https://github.com/doberkofler/web_plsql/issues"
-  },
-  "repository": {
-    "type": "git",
-    "url": "git://github.com/doberkofler/web_plsql.git"
-  },
-  "scripts": {
-    "clean": "rimraf access.log lib trace coverage .nyc_output",
-    "build": "tsc --project ./tsconfig.src.json",
-    "eslint": "eslint --cache --report-unused-disable-directives \"./**/*.ts\"",
-    "type-check": "tsc --project ./tsconfig.json --noEmit",
-    "lint": "npm run eslint && npm run type-check",
-    "test": "jest --coverage=false",
-    "test:coverage": "jest",
-    "sample": "node examples/sample.js",
-    "rebuild": "npm run clean && npm run lint && npm run build && npm run test",
-    "create-package": "shx rm -f *.tgz && npm pack",
-    "install": "npm run build"
-  },
-  "dependencies": {
-    "body-parser": "1.20.0",
-    "compression": "1.7.4",
-    "connect-multiparty": "2.2.0",
-    "cookie-parser": "1.4.6",
-    "escape-html": "1.0.3",
-    "express": "4.18.1",
-    "express-status-monitor": "1.3.4",
-    "http-parser-js": "0.5.6",
-    "mkdirp": "1.0.4",
-    "morgan": "1.10.0",
-    "oracledb": "5.3.0"
-  },
-  "devDependencies": {
-    "@types/body-parser": "1.19.2",
-    "@types/compression": "1.7.2",
-    "@types/cookie-parser": "1.4.3",
-    "@types/escape-html": "1.0.2",
-    "@types/mkdirp": "1.0.2",
-    "@types/morgan": "1.9.3",
-    "@types/node": "17.0.31",
-    "@types/oracledb": "5.2.3",
-    "@types/supertest": "2.0.12",
-    "@typescript-eslint/eslint-plugin": "5.22.0",
-    "@typescript-eslint/parser": "5.22.0",
-    "eslint": "8.15.0",
-    "jest": "28.1.0",
-    "rimraf": "3.0.2",
-    "shx": "0.3.4",
-    "supertest": "6.2.3",
-    "ts-jest": "28.0.2",
-    "ts-node": "10.7.0",
-    "typescript": "4.6.4"
-  }
+	"name": "web_plsql",
+	"version": "0.6.0",
+	"author": "Dieter Oberkofler <dieter.oberkofler@gmail.com>",
+	"license": "MIT",
+	"description": "The Express Middleware for Oracle PL/SQL",
+	"keywords": [
+		"node",
+		"nodejs",
+		"express",
+		"middleware",
+		"plsql",
+		"pl/sql",
+		"oracle",
+		"ohs",
+		"ords",
+		"apex"
+	],
+	"homepage": "https://github.com/doberkofler/web_plsql",
+	"engines": {
+		"npm": ">=10.0.0",
+		"node": ">=22.0.0"
+	},
+	"maintainers": [
+		{
+			"name": "Dieter Oberkofler",
+			"email": "dieter.oberkofler@gmail.com"
+		}
+	],
+	"bugs": {
+		"url": "https://github.com/doberkofler/web_plsql/issues"
+	},
+	"repository": {
+		"type": "git",
+		"url": "git://github.com/doberkofler/web_plsql.git"
+	},
+	"files": [
+		"src/",
+		"examples/",
+		"types"
+	],
+	"main": "./src/index.js",
+	"types": "./types/index.d.ts",
+	"type": "module",
+	"scripts": {
+		"lint": "prettier --check . && eslint . && tsc --noEmit",
+		"test": "node --test --test-concurrency=1 \"./tests/**/*.test.js\"",
+		"types": "rm -rf types && tsc  --noEmit false --declaration true --declarationDir types --emitDeclarationOnly true --allowJs true --target es2020 --module es2020 --moduleResolution node src/*.js",
+		"clean": "shx rm -f *.tgz && shx rm -f *.log",
+		"ci": "npm run clean && npm run lint && npm run test",
+		"create-package": "shx rm -f *.tgz && npm pack"
+	},
+	"dependencies": {
+		"basic-auth": "2.0.1",
+		"body-parser": "1.20.3",
+		"compression": "1.7.5",
+		"connect-multiparty": "2.2.0",
+		"cookie-parser": "1.4.7",
+		"debug": "4.4.0",
+		"escape-html": "1.0.3",
+		"express": "4.21.2",
+		"fs-extra": "11.3.0",
+		"http-parser-js": "0.5.9",
+		"morgan": "1.10.0",
+		"multer": "^1.4.5-lts.1",
+		"oracledb": "6.7.1",
+		"rotating-file-stream": "3.2.5",
+		"zod": "3.24.1"
+	},
+	"devDependencies": {
+		"@types/basic-auth": "1.1.8",
+		"@types/body-parser": "1.19.5",
+		"@types/compression": "1.7.5",
+		"@types/cookie-parser": "1.4.8",
+		"@types/debug": "4.1.12",
+		"@types/escape-html": "1.0.4",
+		"@types/fs-extra": "11.0.4",
+		"@types/morgan": "1.9.9",
+		"@types/multer": "^1.4.12",
+		"@types/node": "22.13.1",
+		"@types/oracledb": "6.5.3",
+		"@types/supertest": "6.0.2",
+		"eslint": "9.20.0",
+		"eslint-plugin-jsdoc": "50.6.3",
+		"prettier": "3.5.0",
+		"rimraf": "6.0.1",
+		"shx": "0.3.4",
+		"supertest": "7.0.0",
+		"typescript": "5.7.3",
+		"typescript-eslint": "8.23.0"
+	}
 }

package/src/cgi.js

@@ -0,0 +1,127 @@
+/*
+ *	Prepare the CGI information
+ */
+
+import os from 'node:os';
+import {URL} from 'node:url';
+
+/**
+ * @typedef {import('express').Request} Request
+ * @typedef {import('./types.js').environmentType} environmentType
+ * @typedef {import('./types.js').configPlSqlType} configPlSqlType
+ */
+
+/** @type {environmentType} */
+const DEFAULT_CGI = {
+	PLSQL_GATEWAY: 'WebDb',
+	GATEWAY_IVERSION: '2',
+	SERVER_SOFTWARE: 'web_plsql',
+	GATEWAY_INTERFACE: 'CGI/1.1',
+	SERVER_PORT: '',
+	SERVER_NAME: os.hostname(),
+	REQUEST_METHOD: '',
+	PATH_INFO: '',
+	SCRIPT_NAME: '',
+	REMOTE_ADDR: '',
+	SERVER_PROTOCOL: '',
+	REQUEST_PROTOCOL: '',
+	REMOTE_USER: '',
+	HTTP_COOKIE: '',
+	HTTP_USER_AGENT: '',
+	HTTP_HOST: '',
+	HTTP_ACCEPT: '',
+	HTTP_ACCEPT_ENCODING: '',
+	HTTP_ACCEPT_LANGUAGE: '',
+	HTTP_REFERER: '',
+	HTTP_X_FORWARDED_FOR: '',
+	WEB_AUTHENT_PREFIX: '',
+	DAD_NAME: '',
+	DOC_ACCESS_PATH: 'doc',
+	DOCUMENT_TABLE: '',
+	PATH_ALIAS: '',
+	REQUEST_CHARSET: 'UTF8',
+	REQUEST_IANA_CHARSET: 'UTF-8',
+	SCRIPT_PREFIX: '',
+};
+
+/**
+ * Create the HTTP_COOKIE string
+ *
+ * @param {Request} req - The req object represents the HTTP request.
+ * @returns {string} - The string representation of the cookies.
+ */
+const getCookieString = (req) => {
+	let cookieString = '';
+
+	for (const propName in req.cookies) {
+		cookieString += `${propName}=${req.cookies[propName]};`;
+	}
+
+	return cookieString;
+};
+
+/**
+ * Get the script name and DAD name from a URL
+ *
+ * @param {Request} req - The req object represents the HTTP request.
+ * @returns {{script: string; prefix: string; dad: string}} - The DAD structure.
+ */
+const getPath = (req) => {
+	// create a valid url
+	const validUrl = `${req.protocol}://${os.hostname()}${req.originalUrl}`;
+
+	// get the pathname from the url (new URL('https://example.org/abc/xyz?123').pathname => /abc/xyz)
+	const pathname = new URL(validUrl).pathname;
+
+	const tmp = trimPath(pathname.substring(0, pathname.lastIndexOf('/') + 1));
+	const script = `/${tmp}`;
+	const prefix = `/${tmp.substring(0, tmp.lastIndexOf('/'))}`;
+	const dad = tmp.substring(tmp.indexOf('/') + 1);
+
+	return {script, prefix, dad};
+};
+
+/**
+ * Get a path that is not enclodes in slashes
+ *
+ * @param {string} value - The value to trim.
+ * @returns {string} - The trimmed value.
+ */
+const trimPath = (value) => value.replace(/^\/+|\/+$/g, '');
+
+/**
+ * Create a CGI object
+ *
+ * @param {Request} req - The req object represents the HTTP request.
+ * @param {string} doctable - The document table.
+ * @param {environmentType} cgi - The additional cgi.
+ * @returns {environmentType} CGI object
+ */
+export const getCGI = (req, doctable, cgi) => {
+	const PROTOCOL = req.protocol ? req.protocol.toUpperCase() : '';
+	const PATH = getPath(req);
+
+	/** @type {environmentType} */
+	const CGI = {
+		SERVER_PORT: typeof req.socket.localPort === 'number' ? req.socket.localPort.toString() : '',
+		REQUEST_METHOD: req.method,
+		PATH_INFO: req.params.name,
+		SCRIPT_NAME: PATH.script,
+		REMOTE_ADDR: (req.ip ?? '').replace('::ffff:', ''),
+		SERVER_PROTOCOL: `${PROTOCOL}/${req.httpVersion}`,
+		REQUEST_PROTOCOL: PROTOCOL,
+		HTTP_COOKIE: getCookieString(req),
+		HTTP_USER_AGENT: req.get('user-agent') ?? '',
+		HTTP_HOST: req.get('host') ?? '',
+		HTTP_ACCEPT: req.get('accept') ?? '',
+		HTTP_ACCEPT_ENCODING: req.get('accept-encoding') ?? '',
+		HTTP_ACCEPT_LANGUAGE: req.get('accept-language') ?? '',
+		HTTP_REFERER: req.get('referer') ?? '',
+		HTTP_X_FORWARDED_FOR: req.get('x-forwarded-for') ?? '',
+		DAD_NAME: PATH.dad,
+		DOCUMENT_TABLE: doctable,
+		SCRIPT_PREFIX: PATH.prefix,
+	};
+
+	return Object.assign({}, DEFAULT_CGI, CGI, cgi);
+};

package/src/error.js

@@ -0,0 +1,24 @@
+import {inspect} from './trace.js';
+
+/**
+ * Convert Error to a string.
+ *
+ * @param {unknown} error - The error.
+ * @returns {string} The string representation.
+ */
+export const errorToString = (error) => {
+	if (typeof error === 'string') {
+		return error;
+	} else if (error instanceof Error) {
+		const parts = [error.name];
+		if (typeof error.message === 'string' && error.message.length > 0) {
+			parts.push(error.message);
+		}
+		if (typeof error.stack === 'string' && error.stack.length > 0) {
+			parts.push(error.stack);
+		}
+		return parts.join('\n');
+	} else {
+		return inspect(error);
+	}
+};

package/src/errorPage.js

@@ -0,0 +1,296 @@
+/*
+ *	Error handling
+ */
+
+import util from 'node:util';
+import escape from 'escape-html';
+import {ProcedureError} from './procedureError.js';
+import {RequestError} from './requestError.js';
+import {inspectRequest, logToFile} from './trace.js';
+import {errorToString} from './error.js';
+
+/**
+ * @typedef {import('express').Request} Request
+ * @typedef {import('express').Response} Response
+ * @typedef {import('./types.js').BindParameterConfig} BindParameterConfig
+ * @typedef {import('./types.js').environmentType} environmentType
+ * @typedef {import('./types.js').configPlSqlHandlerType} configPlSqlHandlerType
+ * @typedef {{html: string; text: string}} outputType
+ */
+
+/**
+ *	Convert value to string
+ *	@param {unknown} value - The value to convert.
+ *	@returns {string} - The string representation of the value.
+ */
+const inspect = (value) => util.inspect(value, {showHidden: false, depth: null, colors: false});
+
+/**
+ *	Convert LF and/or CR to <br>
+ *	@param {string} text - The text to convert.
+ *	@returns {string} - The converted text.
+ */
+const convertToHtml = (text) => {
+	let html = escape(text);
+
+	html = html.replace(/(?:\r\n|\r|\n)/g, '<br />');
+	html = html.replace(/\t/g, '&nbsp;&nbsp;&nbsp;');
+
+	return html;
+};
+
+/**
+ *	Get html
+ *	@param {string} text - The text to convert.
+ *	@returns {string} - The converted text.
+ */
+const getHtml = (text) => `<p>${convertToHtml(text)}</p>`;
+
+/**
+ *	Get text header
+ *	@param {string} text - The text to convert.
+ *	@returns {string} - The converted text.
+ */
+const getHeaderText = (text) => `\n${text}\n${'='.repeat(text.length)}\n`;
+
+/**
+ *	Get html header
+ *	@param {string} text - The text to convert.
+ *	@returns {string} - The converted text.
+ */
+const getHeaderHtml = (text) => `<h1>${text}</h1>`;
+
+/**
+ *	Get text
+ *	@param {string} text - The text to convert.
+ *	@returns {string} - The converted text.
+ */
+const getText = (text) => `${text}\n`;
+
+/**
+ * Get evnironment
+ *	@param {outputType} output - The output.
+ *	@param {environmentType} environment - The environment.
+ */
+const getEnvironment = (output, environment) => {
+	let html = '<table>';
+	let text = '';
+
+	try {
+		for (const key in environment) {
+			html += `<tr><td>${key}:</td><td>${environment[key]}</td></tr>`;
+			text += `${key}=${environment[key]}\n`;
+		}
+	} catch (err) {
+		/* istanbul ignore next */
+		output.html += errorToString(err);
+
+		/* istanbul ignore next */
+		output.text += errorToString(err);
+
+		/* istanbul ignore next */
+		return;
+	}
+
+	html += '</table>';
+
+	output.html += html;
+	output.text += text;
+};
+
+/**
+ *	Show an error page
+ *	@param {Request} req - The req object represents the HTTP request.
+ *	@param {unknown} error - The error.
+ *	@returns {outputType} - The output.
+ */
+const getError = (req, error) => {
+	let timestamp = new Date();
+	let message = '';
+	/** @type {environmentType | null} */
+	let environment = null;
+	/** @type {string | null} */
+	let sql = null;
+	/** @type {BindParameterConfig} */
+	let bind = {};
+
+	// what type of Error did we receive
+	if (error instanceof ProcedureError) {
+		timestamp = error.timestamp;
+		/* istanbul ignore next */
+		message = error.stack ?? '';
+		environment = error.environment;
+		sql = error.sql;
+		bind = error.bind;
+	} else if (error instanceof RequestError) {
+		timestamp = error.timestamp;
+		/* istanbul ignore next */
+		message = error.stack ?? '';
+	} else if (error instanceof Error) {
+		/* istanbul ignore next */
+		message = errorToString(error);
+	} else {
+		if (typeof error === 'string') {
+			/* istanbul ignore next */
+			message = `${error}\n`;
+		}
+		try {
+			/* istanbul ignore next */
+			new Error();
+		} catch (err) {
+			/* istanbul ignore next */
+			message += errorToString(err);
+		}
+	}
+
+	/** @type {outputType} */
+	const output = {
+		html: '',
+		text: '',
+	};
+
+	// timestamp
+	let header = 'TIMESTAMP';
+	output.html += getHeaderHtml(header);
+	output.html += getHtml(timestamp.toUTCString());
+
+	// error
+	header = 'ERROR';
+	output.html += getHeaderHtml(header);
+	output.html += getHtml(message);
+	output.text += getHeaderText(header);
+	output.text += getText(message);
+
+	// request
+	header = 'REQUEST';
+	output.text += getHeaderText(header);
+	output.text += getText(inspectRequest(req));
+
+	// parameters
+	if (typeof sql === 'string' && bind) {
+		header = 'PROCEDURE';
+		output.html += getHeaderHtml(header);
+		output.text += getHeaderText(header);
+		getProcedure(output, sql, bind);
+	}
+
+	// environment
+	if (environment) {
+		header = 'ENVIRONMENT';
+		output.html += getHeaderHtml(header);
+		output.text += getHeaderText(header);
+		getEnvironment(output, environment);
+	}
+
+	return output;
+};
+
+/**
+ *	Get procedure
+ *	@param {outputType} output - The output.
+ *	@param {string} sql - The SQL to execute.
+ *	@param {BindParameterConfig} bind - The bind parameters.
+ */
+const getProcedure = (output, sql, bind) => {
+	let html = '<table>';
+	let text = '';
+
+	text += `PROCEDURE: ${sql}\n`;
+	html += `<tr><td>PROCEDURE:</td><td>${sql}</td></tr>`;
+
+	try {
+		/* istanbul ignore else */
+		for (const key in bind) {
+			const value = inspect(bind[key].val);
+
+			html += `<tr><td>${key}:</td><td>${value}</td></tr>`;
+			text += `${key}: ${value}\n`;
+		}
+	} catch (err) {
+		/* istanbul ignore next */
+		output.html += err instanceof Error ? err.toString() : 'ERROR';
+
+		/* istanbul ignore next */
+		output.text += err instanceof Error ? err.toString() : 'ERROR';
+		/* istanbul ignore next */
+		return;
+	}
+
+	html += '</table>';
+
+	output.html += html;
+	output.text += text;
+};
+
+/**
+ *	getHtmlPage
+ *	@param {string} body - The body.
+ *	@returns {string} - The html page.
+ */
+const getHtmlPage = (body) => `<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<title>web_plsql error page</title>
+<style type="text/css">
+html {
+	font-family: monospace, sans-serif;
+	font-size: 12px;
+}
+h1 {
+	font-size: 16px;
+	padding: 2px;
+	background-color: #cc0000;
+}
+</style>
+</head>
+<body>
+${body}
+</body>
+</html>
+`;
+
+/**
+ * Show an error page
+ *
+ * @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 {configPlSqlHandlerType} options - The configuration options.
+ * @param {unknown} error - The error.
+ */
+export const errorPage = (req, res, options, error) => {
+	let output = {
+		html: '',
+		text: '',
+	};
+
+	// get the error description
+	try {
+		output = getError(req, error);
+	} catch (err) {
+		/* istanbul ignore next */
+		const header = 'ERROR';
+
+		/* istanbul ignore next */
+		const message = errorToString(err);
+
+		/* istanbul ignore next */
+		output.html += getHeaderHtml(header) + getHtml(message);
+
+		/* istanbul ignore next */
+		output.text += getHeaderHtml(header) + getHtml(message);
+	}
+
+	// trace to file
+	logToFile(output.text);
+
+	// console
+	console.error(output.text);
+
+	// show page
+	if (options.errorStyle === 'basic') {
+		res.status(404).send('Page not found');
+	} else {
+		res.status(404).send(getHtmlPage(output.html));
+	}
+};