web_plsql 1.2.0 → 1.3.1

package/src/server/server.js

@@ -1,304 +0,0 @@
-import debugModule from 'debug';
-const debug = debugModule('webplsql:server');
-import http from 'node:http';
-import https from 'node:https';
-import path from 'node:path';
-import {fileURLToPath} from 'node:url';
-import express from 'express';
-import cookieParser from 'cookie-parser';
-import compression from 'compression';
-import {z$configType} from '../types.js';
-import {installShutdown} from '../util/shutdown.js';
-import {poolCreate, poolsClose} from '../util/oracle.js';
-import {handlerUpload} from '../handler/handlerUpload.js';
-import {handlerLogger} from '../handler/handlerLogger.js';
-import {handlerWebPlSql} from '../handler/plsql/handlerPlSql.js';
-import {handlerAdmin} from '../handler/handlerAdmin.js';
-import {readFileSyncUtf8, getJsonFile} from '../util/file.js';
-import {showConfig} from './config.js';
-import {AdminContext} from './adminContext.js';
-
-const __filename = fileURLToPath(import.meta.url);
-const __dirname = path.dirname(__filename);
-
-/**
- * @typedef {import('node:net').Socket} Socket
- * @typedef {import('express').Express} Express
- * @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').configType} configType
- * @typedef {import('../handler/plsql/procedureNamed.js').argsType} argsType
- */
-
-/**
- * @typedef {import('express').RequestHandler & {
- *   procedureNameCache: import('../util/cache.js').Cache<string>;
- *   argumentCache: import('../util/cache.js').Cache<argsType>;
- * }} ExtendedRequestHandler
- */
-
-/**
- * @typedef {object} webServer - Web server interface.
- * @property {configType} config - Configuration object.
- * @property {Pool[]} connectionPools - Oracle connection pools.
- * @property {Express} app - Express app.
- * @property {http.Server | https.Server} server - Native Node http(s) server instance.
- * @property {() => Promise<void>} shutdown - Shutdown function.
- */
-
-/**
- * @typedef {object} sslConfig - SSL configuration.
- * @property {string} keyFilename - key filename.
- * @property {string} certFilename - cert filename.
- */
-
-/**
- * Create HTTPS server.
- * @param {Express} app - express application
- * @param {sslConfig} [ssl] - ssl configuration.
- * @returns {http.Server | https.Server} - server
- */
-export const createServer = (app, ssl) => {
-	if (ssl) {
-		const key = readFileSyncUtf8(ssl.keyFilename);
-		const cert = readFileSyncUtf8(ssl.certFilename);
-
-		return https.createServer({key, cert}, app);
-	} else {
-		return http.createServer(app);
-	}
-};
-
-/**
- * Start server.
- * @param {configType} config - The config.
- * @param {sslConfig} [ssl] - ssl configuration.
- * @returns {Promise<webServer>} - Promise resolving to the web server object.
- */
-export const startServer = async (config, ssl) => {
-	debug('startServer: BEGIN', config, ssl);
-
-	const internalConfig = /** @type {configType} */ (z$configType.parse(config));
-	AdminContext.config = internalConfig;
-
-	showConfig(internalConfig);
-
-	// Create express app
-	const app = express();
-
-	// Default middleware
-	app.use(handlerUpload(internalConfig.uploadFileSizeLimit));
-	app.use(express.json({limit: '50mb'}));
-	app.use(express.urlencoded({limit: '50mb', extended: true}));
-	app.use(cookieParser());
-	app.use(compression());
-
-	// Pause & Admin Auth middleware
-	app.use((req, res, next) => {
-		const adminRoute = internalConfig.adminRoute ?? '/admin';
-
-		// Simple pause check for all PL/SQL routes (not admin)
-		if (AdminContext.paused && !req.path.startsWith(adminRoute)) {
-			res.status(503).send('Server Paused');
-			return;
-		}
-
-		// Basic Auth for Admin Route
-		if (req.path.startsWith(adminRoute)) {
-			const user = internalConfig.adminUser;
-			const pass = internalConfig.adminPassword;
-
-			if (user && pass) {
-				const auth = {login: user, password: pass};
-				const b64auth = (req.headers.authorization ?? '').split(' ')[1] ?? '';
-				const [login, password] = Buffer.from(b64auth, 'base64').toString().split(':');
-
-				if (login !== auth.login || password !== auth.password) {
-					res.set('WWW-Authenticate', 'Basic realm="Admin Console"');
-					res.status(401).send('Authentication required.');
-					return;
-				}
-			}
-		}
-
-		next();
-	});
-
-	// Access log
-	if (internalConfig.loggerFilename.length > 0) {
-		app.use(handlerLogger(internalConfig.loggerFilename));
-	}
-
-	// Admin console
-	const adminRoute = internalConfig.adminRoute ?? '/admin';
-	const adminDirectory = path.resolve(__dirname, '../admin');
-
-	// Ensure trailing slash for admin route to support relative paths
-	app.get(adminRoute, (req, res, next) => {
-		const [path] = req.originalUrl.split('?');
-		if (path === adminRoute) {
-			const query = req.originalUrl.split('?')[1];
-			return res.redirect(adminRoute + '/' + (query ? '?' + query : ''));
-		}
-		next();
-	});
-
-	app.use(adminRoute, handlerAdmin);
-	app.use(adminRoute, express.static(adminDirectory));
-
-	// Serving static files
-	for (const i of internalConfig.routeStatic) {
-		app.use(i.route, express.static(i.directoryPath));
-	}
-
-	/** @type {Pool[]} */
-	const connectionPools = [];
-	AdminContext.pools = connectionPools;
-	AdminContext.caches = [];
-
-	// Oracle pl/sql express middleware
-	for (const i of internalConfig.routePlSql) {
-		// Allocate the Oracle database pool
-		const pool = await poolCreate(i.user, i.password, i.connectString);
-		connectionPools.push(pool);
-
-		const handler = handlerWebPlSql(pool, i);
-
-		// Capture caches for admin console
-		AdminContext.caches.push({
-			poolName: i.route,
-			procedureNameCache: handler.procedureNameCache,
-			argumentCache: handler.argumentCache,
-		});
-
-		app.use([`${i.route}/:name`, i.route], (req, res, next) => {
-			const start = process.hrtime();
-			res.on('finish', () => {
-				const diff = process.hrtime(start);
-				const duration = diff[0] * 1000 + diff[1] / 1_000_000;
-				AdminContext.statsManager.recordRequest(duration, res.statusCode >= 400);
-			});
-			handler(req, res, next);
-		});
-	}
-
-	// Update pools in StatsManager on each rotation
-	const originalRotate = AdminContext.statsManager.rotateBucket.bind(AdminContext.statsManager);
-	AdminContext.statsManager.rotateBucket = () => {
-		const poolSnapshots = AdminContext.pools.map((pool, index) => {
-			const cache = AdminContext.caches[index];
-			const name = cache?.poolName ?? `pool-${index}`;
-			const procStats = cache?.procedureNameCache.getStats();
-			const argStats = cache?.argumentCache.getStats();
-
-			return {
-				name,
-				connectionsOpen: pool.connectionsOpen,
-				connectionsInUse: pool.connectionsInUse,
-				cache: {
-					procedureName: {
-						size: cache?.procedureNameCache.keys().length ?? 0,
-						hits: procStats?.hits ?? 0,
-						misses: procStats?.misses ?? 0,
-					},
-					argument: {
-						size: cache?.argumentCache.keys().length ?? 0,
-						hits: argStats?.hits ?? 0,
-						misses: argStats?.misses ?? 0,
-					},
-				},
-			};
-		});
-		originalRotate(poolSnapshots);
-	};
-
-	// create server
-	debug('startServer: createServer');
-	const server = createServer(app, ssl);
-
-	// Track open connections
-	/** @type {Set<Socket>} */
-	const connections = new Set();
-	server.on('connection', (/** @type {Socket} */ socket) => {
-		connections.add(socket);
-		socket.on('close', () => {
-			connections.delete(socket);
-		});
-	});
-
-	const closeAllConnections = () => {
-		for (const socket of connections) {
-			socket.destroy(); // forcibly closes the connection
-			connections.delete(socket);
-		}
-	};
-
-	const shutdown = async () => {
-		debug('startServer: onShutdown');
-
-		AdminContext.statsManager.stop();
-
-		await poolsClose(connectionPools);
-
-		server.close(() => {
-			console.log('Server has closed');
-			process.exit(0);
-		});
-
-		closeAllConnections();
-	};
-
-	// Install shutdown handler
-	installShutdown(shutdown);
-
-	// Listen
-	debug('startServer: start listener');
-	await /** @type {Promise<void>} */ (
-		new Promise((resolve, reject) => {
-			server
-				.listen(internalConfig.port)
-				.on('listening', () => {
-					debug('startServer: listener running');
-					resolve();
-				})
-				.on('error', (err) => {
-					if ('code' in err) {
-						if (err.code === 'EADDRINUSE') {
-							err.message = `Port ${internalConfig.port} is already in use`;
-						} else if (err.code === 'EACCES') {
-							err.message = `Port ${internalConfig.port} requires elevated privileges`;
-						}
-					}
-					reject(err);
-				});
-		})
-	);
-
-	debug('startServer: END');
-
-	return {
-		config: internalConfig,
-		connectionPools,
-		app,
-		server,
-		shutdown,
-	};
-};
-
-/**
- * Load configuration.
- * @param {string} [filename] - The configuration filename.
- * @returns {configType} - Promise.
- */
-export const loadConfig = (filename = 'config.json') => /** @type {configType} */ (z$configType.parse(getJsonFile(filename)));
-
-/**
- * Start server from config file.
- * @param {string} [filename] - The configuration filename.
- * @param {sslConfig} [ssl] - ssl configuration.
- * @returns {Promise<webServer>} - Promise resolving to the web server object.
- */
-export const startServerConfig = async (filename = 'config.json', ssl) => startServer(loadConfig(filename), ssl);

package/src/types.js

@@ -1,150 +0,0 @@
-import z from 'zod';
-
-/**
- * @typedef {import('oracledb').BindParameter} BindParameter
- * @typedef {import('oracledb').Connection} Connection
- * @typedef {import('express').CookieOptions} CookieOptions
- * @typedef {import('express').Request} Request
- */
-
-/**
- * @typedef {'basic' | 'debug'} errorStyleType
- */
-export const z$errorStyleType = z.enum(['basic', 'debug']);
-
-/**
- * @typedef {object} configStaticType
- * @property {string} route - The Static route path.
- * @property {string} directoryPath - The Static directory.
- */
-export const z$configStaticType = z.strictObject({
-	route: z.string(),
-	directoryPath: z.string(),
-});
-
-/**
- * @typedef {(connection: Connection, procedure: string) => void | Promise<void>} transactionCallbackType
- * @typedef {'commit' | 'rollback' | transactionCallbackType | undefined | null} transactionModeType
- */
-
-/**
- * @typedef {object} configPlSqlHandlerType
- * @property {string} defaultPage - The default page.
- * @property {string} [pathAlias] - The path alias.
- * @property {string} [pathAliasProcedure] - The path alias.
- * @property {string} documentTable - The document table.
- * @property {string[]} [exclusionList] - The exclusion list.
- * @property {string} [requestValidationFunction] - The request validation function.
- * @property {Record<string, string>} [cgi] - The additional CGI.
- * @property {transactionModeType} [transactionMode] - Specifies an optional transaction mode.
- * "commit" this automatically commits any open transaction after each request. This is the defaults because this is what mod_plsql and ohs are doing.
- * "rollback" this automatically rolles back any open transaction after each request.
- * "transactionCallbackType" this allows to defined a custom handler as a JavaScript function.
- * @property {errorStyleType} errorStyle - The error style.
- */
-export const z$configPlSqlHandlerType = z.strictObject({
-	defaultPage: z.string(),
-	pathAlias: z.string().optional(),
-	pathAliasProcedure: z.string().optional(),
-	documentTable: z.string(),
-	exclusionList: z.array(z.string()).optional(),
-	requestValidationFunction: z.string().optional(),
-	transactionMode: z.unknown().optional(),
-	errorStyle: z$errorStyleType,
-});
-
-/**
- * @typedef {object} configPlSqlConfigType
- * @property {string} route - The PL/SQL route path.
- * @property {string} user - The Oracle username.
- * @property {string} password - The Oracle password.
- * @property {string} connectString - The Oracle connect string.
- */
-export const z$configPlSqlConfigType = z.strictObject({
-	route: z.string(),
-	user: z.string(),
-	password: z.string(),
-	connectString: z.string(),
-});
-
-/**
- * @typedef {configPlSqlHandlerType & configPlSqlConfigType} configPlSqlType
- */
-export const z$configPlSqlType = z.strictObject({
-	...z$configPlSqlHandlerType.shape,
-	...z$configPlSqlConfigType.shape,
-});
-
-/**
- * @typedef {object} configType
- * @property {number} port - The server port number.
- * @property {configStaticType[]} routeStatic - The static routes.
- * @property {configPlSqlType[]} routePlSql - The PL/SQL routes.
- * @property {number} [uploadFileSizeLimit] - Maximum size of each uploaded file in bytes or no limit if omitted.
- * @property {string} loggerFilename - name of the request logger filename or '' if not required.
- * @property {string} [adminRoute] - Optional route for the admin console (defaults to /admin).
- * @property {string} [adminUser] - Optional username for admin console basic auth.
- * @property {string} [adminPassword] - Optional password for admin console basic auth.
- */
-export const z$configType = z.strictObject({
-	port: z.number(),
-	routeStatic: z.array(z$configStaticType),
-	routePlSql: z.array(z$configPlSqlType),
-	uploadFileSizeLimit: z.number().optional(),
-	loggerFilename: z.string(),
-	adminRoute: z.string().optional(),
-	adminUser: z.string().optional(),
-	adminPassword: z.string().optional(),
-});
-
-/**
- * Environment variables as string key-value pairs
- * @typedef {Record<string, string>} environmentType
- */
-
-/**
- * Oracle database bind parameter configuration
- * @typedef {Record<string, BindParameter>} BindParameterConfig
- */
-
-/**
- * Arguments object with string or string array values
- * @typedef {Record<string, string | string[]>} argObjType
- */
-
-/**
- * File upload metadata
- * @typedef {object} fileUploadType
- * @property {string} fieldname - The field value.
- * @property {string} originalname - The filename.
- * @property {string} encoding - The encoding.
- * @property {string} mimetype - The mimetype.
- * @property {string} filename - The filename.
- * @property {string} path - The path.
- * @property {number} size - The size.
- */
-
-/**
- * @typedef {object} cookieType
- * @property {string} name - The name of the cookie.
- * @property {string} value - The value of the cookie.
- * @property {CookieOptions} options - The cookie options.
- */
-
-/**
- * @typedef {object} pageType - The page.
- * @property {string | import('node:stream').Readable} body - The body of the page.
- * @property {object} head - The head of the page.
- * @property {cookieType[]} head.cookies - The cookies.
- * @property {string} [head.contentType] - The content type.
- * @property {number} [head.contentLength] - The content length.
- * @property {number} [head.statusCode] - The status code.
- * @property {string} [head.statusDescription] - The status description.
- * @property {string} [head.redirectLocation] - The redirect location.
- * @property {Record<string, string>} head.otherHeaders - The other headers.
- * @property {string} [head.server] - The server.
- * @property {object} file - The file.
- * @property {string | null} file.fileType - The file type.
- * @property {number | null} file.fileSize - The file size.
- * @property {import('node:stream').Readable | Buffer | null} file.fileBlob - The file blob.
- */

package/src/util/cache.js

@@ -1,123 +0,0 @@
-/**
- * @template T
- * @typedef {{hitCount: number, value: T}} cacheEntryType
- */
-
-/**
- * Generic Cache class with LFU (Least Frequently Used) eviction policy.
- * @template T
- */
-export class Cache {
-	/**
-	 * @param {number} maxSize - Maximum number of entries in the cache.
-	 */
-	constructor(maxSize = 10000) {
-		/** @type {Map<string, cacheEntryType<T>>} */
-		this.cache = new Map();
-		this.maxSize = maxSize;
-		this.hits = 0;
-		this.misses = 0;
-	}
-
-	/**
-	 * Get an entry from the cache.
-	 * @param {string} key - The key.
-	 * @returns {T | undefined} - The value or undefined if not found.
-	 */
-	get(key) {
-		const entry = this.cache.get(key);
-		if (entry) {
-			entry.hitCount++;
-			this.hits++;
-			return entry.value;
-		}
-		this.misses++;
-		return undefined;
-	}
-
-	/**
-	 * Set an entry in the cache.
-	 * @param {string} key - The key.
-	 * @param {T} value - The value.
-	 */
-	set(key, value) {
-		// If updating an existing key, preserve its hitCount?
-		// Typically LFU implies resetting or keeping.
-		// For simplicity and avoiding complex aging, if we set it again, we reset hitCount or keep it?
-		// The requirement is "cache invalidation" (delete) or "cache loading" (set).
-		// If we overwrite, it's usually a new value. Let's reset hitCount to 0 for a fresh start or 1.
-
-		// Ensure we have space
-		if (this.cache.size >= this.maxSize && !this.cache.has(key)) {
-			this.prune();
-		}
-
-		this.cache.set(key, {hitCount: 0, value});
-	}
-
-	/**
-	 * Delete an entry from the cache.
-	 * @param {string} key - The key.
-	 */
-	delete(key) {
-		this.cache.delete(key);
-	}
-
-	/**
-	 * Clear the cache.
-	 */
-	clear() {
-		this.cache.clear();
-		this.hits = 0;
-		this.misses = 0;
-	}
-
-	/**
-	 * Prune the cache by removing the least frequently used entries.
-	 * Removes 10% of the cache size.
-	 */
-	prune() {
-		// Convert cache entries to an array
-		const entries = Array.from(this.cache.entries());
-
-		// Sort entries by hitCount in ascending order
-		entries.sort((a, b) => a[1].hitCount - b[1].hitCount);
-
-		// Remove the bottom 10%
-		const removeCount = Math.max(1, Math.floor(this.maxSize * 0.1));
-		const keysToRemove = entries.slice(0, removeCount).map(([key]) => key);
-
-		for (const key of keysToRemove) {
-			this.cache.delete(key);
-		}
-	}
-
-	/**
-	 * Get the size of the cache.
-	 * @returns {number} - The size.
-	 */
-	get size() {
-		return this.cache.size;
-	}
-
-	/**
-	 * Get all keys in the cache.
-	 * @returns {string[]} - The keys.
-	 */
-	keys() {
-		return Array.from(this.cache.keys());
-	}
-
-	/**
-	 * Get cache statistics.
-	 * @returns {{size: number, maxSize: number, hits: number, misses: number}} - The statistics.
-	 */
-	getStats() {
-		return {
-			size: this.cache.size,
-			maxSize: this.maxSize,
-			hits: this.hits,
-			misses: this.misses,
-		};
-	}
-}

package/src/util/errorToString.js

@@ -1,24 +0,0 @@
-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/util/file.js

@@ -1,91 +0,0 @@
-import {promises as fs, readFileSync} from 'node:fs';
-
-/**
- * Read file.
- *
- * @param {string} filePath - File name.
- * @returns {string} The string.
- */
-export const readFileSyncUtf8 = (filePath) => {
-	try {
-		return readFileSync(filePath, 'utf8');
-	} catch (err) {
-		throw new Error(`Unable to read file "${filePath}"`);
-	}
-};
-
-/**
- * Read file.
- *
- * @param {string} filePath - File name.
- * @returns {Promise<Buffer>} The buffer.
- */
-export const readFile = async (filePath) => {
-	try {
-		return await fs.readFile(filePath);
-	} catch (err) {
-		throw new Error(`Unable to read file "${filePath}"`);
-	}
-};
-
-/**
- * Remove file.
- *
- * @param {string} filePath - File name.
- * @returns {Promise<void>}.
- */
-export const removeFile = async (filePath) => {
-	try {
-		return await fs.unlink(filePath);
-	} catch (err) {
-		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) => {
-	try {
-		const fileContent = readFileSync(filePath, 'utf8');
-		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;
-	}
-
-	try {
-		const stats = await fs.stat(filePath);
-		return stats.isFile();
-	} catch {
-		return false;
-	}
-};