web_plsql 0.18.0 → 1.2.0

package/types/handler/handlerAdmin.d.ts

@@ -0,0 +1,79 @@
+/**
+ * @typedef {import('express').Request} Request
+ * @typedef {import('express').Response} Response
+ * @typedef {import('express').NextFunction} NextFunction
+ */
+/**
+ * @typedef {import('../util/statsManager.js').Bucket} Bucket
+ */
+/**
+ * @typedef {object} StatsSummary
+ * @property {Date} startTime - Server start time.
+ * @property {number} totalRequests - Total requests handled.
+ * @property {number} totalErrors - Total errors encountered.
+ * @property {number} avgResponseTime - Lifetime average response time.
+ * @property {number} minResponseTime - Lifetime minimum response time.
+ * @property {number} maxResponseTime - Lifetime maximum response time.
+ * @property {number} maxRequestsPerSecond - Lifetime maximum requests per second.
+ * @property {object} maxMemory - Lifetime memory extremes.
+ * @property {number} maxMemory.heapUsedMax - Maximum heap used.
+ * @property {number} maxMemory.heapTotalMax - Maximum heap total.
+ * @property {number} maxMemory.rssMax - Maximum RSS.
+ * @property {number} maxMemory.externalMax - Maximum external memory.
+ * @property {object} cpu - Lifetime CPU extremes.
+ * @property {number} cpu.max - Max CPU.
+ * @property {number} cpu.userMax - Max user CPU.
+ * @property {number} cpu.systemMax - Max system CPU.
+ */
+export const handlerAdmin: import("express-serve-static-core").Router;
+export type Request = import("express").Request;
+export type Response = import("express").Response;
+export type NextFunction = import("express").NextFunction;
+export type Bucket = import("../util/statsManager.js").Bucket;
+export type StatsSummary = {
+    /**
+     * - Server start time.
+     */
+    startTime: Date;
+    /**
+     * - Total requests handled.
+     */
+    totalRequests: number;
+    /**
+     * - Total errors encountered.
+     */
+    totalErrors: number;
+    /**
+     * - Lifetime average response time.
+     */
+    avgResponseTime: number;
+    /**
+     * - Lifetime minimum response time.
+     */
+    minResponseTime: number;
+    /**
+     * - Lifetime maximum response time.
+     */
+    maxResponseTime: number;
+    /**
+     * - Lifetime maximum requests per second.
+     */
+    maxRequestsPerSecond: number;
+    /**
+     * - Lifetime memory extremes.
+     */
+    maxMemory: {
+        heapUsedMax: number;
+        heapTotalMax: number;
+        rssMax: number;
+        externalMax: number;
+    };
+    /**
+     * - Lifetime CPU extremes.
+     */
+    cpu: {
+        max: number;
+        userMax: number;
+        systemMax: number;
+    };
+};

package/types/handler/plsql/errorPage.d.ts

@@ -8,3 +8,4 @@ export type outputType = {
     html: string;
     text: string;
 };
+export type messageType = import("../../util/trace.js").messageType;

package/types/handler/plsql/handlerPlSql.d.ts

@@ -1,4 +1,4 @@
-export function handlerWebPlSql(connectionPool: Pool, config: configPlSqlHandlerType): RequestHandler;
+export function handlerWebPlSql(connectionPool: Pool, config: configPlSqlHandlerType): WebPlSqlRequestHandler;
 export type RequestHandler = import("express").RequestHandler;
 export type Request = import("express").Request;
 export type Response = import("express").Response;
@@ -6,3 +6,8 @@ export type NextFunction = import("express").NextFunction;
 export type Pool = import("oracledb").Pool;
 export type environmentType = import("../../types.js").environmentType;
 export type configPlSqlHandlerType = import("../../types.js").configPlSqlHandlerType;
+export type WebPlSqlRequestHandler = import("express").RequestHandler & {
+    procedureNameCache: Cache<string>;
+    argumentCache: Cache<import("./procedureNamed.js").argsType>;
+};
+import { Cache } from '../../util/cache.js';

package/types/handler/plsql/owaPageStream.d.ts

@@ -0,0 +1,28 @@
+/**
+ * @typedef {import('oracledb').Connection} Connection
+ * @typedef {import('../../types.js').BindParameterConfig} BindParameterConfig
+ */
+export class OWAPageStream extends Readable {
+    /**
+     * @param {Connection} databaseConnection - The database connection.
+     */
+    constructor(databaseConnection: Connection);
+    databaseConnection: oracledb.Connection;
+    chunkSize: number;
+    isDone: boolean;
+    /**
+     * Fetch a chunk of the page from the database.
+     * @returns {Promise<string[]>} The array of lines fetched.
+     */
+    fetchChunk(): Promise<string[]>;
+    /**
+     * Add initial body content to the stream.
+     * @param {string} content - The initial content to prepend.
+     * @returns {void}
+     */
+    addBody(content: string): void;
+}
+export type Connection = import("oracledb").Connection;
+export type BindParameterConfig = import("../../types.js").BindParameterConfig;
+import { Readable } from 'node:stream';
+import oracledb from 'oracledb';

package/types/handler/plsql/procedure.d.ts

@@ -1,4 +1,5 @@
-export function invokeProcedure(req: Request, res: Response, argObj: argObjType, cgiObj: environmentType, filesToUpload: fileUploadType[], options: configPlSqlHandlerType, databaseConnection: Connection): Promise<void>;
+export function invokeProcedure(req: Request, res: Response, argObj: argObjType, cgiObj: environmentType, filesToUpload: fileUploadType[], options: configPlSqlHandlerType, databaseConnection: Connection, procedureNameCache: ProcedureNameCache, argumentCache: ArgumentCache): Promise<void>;
+export type TraceEntry = import("../../admin/js/types.js").TraceEntry;
 export type Request = import("express").Request;
 export type Response = import("express").Response;
 export type Connection = import("oracledb").Connection;
@@ -8,3 +9,5 @@ export type fileUploadType = import("../../types.js").fileUploadType;
 export type environmentType = import("../../types.js").environmentType;
 export type configPlSqlHandlerType = import("../../types.js").configPlSqlHandlerType;
 export type BindParameterConfig = import("../../types.js").BindParameterConfig;
+export type ProcedureNameCache = import("../../util/cache.js").Cache<string>;
+export type ArgumentCache = import("../../util/cache.js").Cache<import("./procedureNamed.js").argsType>;

package/types/handler/plsql/procedureNamed.d.ts

@@ -1,5 +1,5 @@
 export function getBinding(argName: string, argValue: unknown, argType: string): BindParameter;
-export function getProcedureNamed(req: Request, procName: string, argObj: argObjType, databaseConnection: Connection): Promise<{
+export function getProcedureNamed(req: Request, procName: string, argObj: argObjType, databaseConnection: Connection, argumentCache: ArgumentCache): Promise<{
     sql: string;
     bind: BindParameterConfig;
 }>;
@@ -11,7 +11,4 @@ export type argObjType = import("../../types.js").argObjType;
 export type BindParameterConfig = import("../../types.js").BindParameterConfig;
 export type BindParameter = import("../../types.js").BindParameter;
 export type argsType = Record<string, string>;
-export type cacheEntryType = {
-    hitCount: number;
-    args: argsType;
-};
+export type ArgumentCache = import("../../util/cache.js").Cache<argsType>;

package/types/handler/plsql/procedureSanitize.d.ts

@@ -1,4 +1,4 @@
-export function sanitizeProcName(procName: string, databaseConnection: Connection, options: configPlSqlHandlerType): Promise<string>;
+export function sanitizeProcName(procName: string, databaseConnection: Connection, options: configPlSqlHandlerType, procedureNameCache: ProcedureNameCache): Promise<string>;
 export type Request = import("express").Request;
 export type Response = import("express").Response;
 export type Connection = import("oracledb").Connection;
@@ -8,7 +8,4 @@ export type fileUploadType = import("../../types.js").fileUploadType;
 export type environmentType = import("../../types.js").environmentType;
 export type configPlSqlHandlerType = import("../../types.js").configPlSqlHandlerType;
 export type BindParameterConfig = import("../../types.js").BindParameterConfig;
-export type cacheEntryType = {
-    hitCount: number;
-    valid: boolean;
-};
+export type ProcedureNameCache = import("../../util/cache.js").Cache<string>;

package/types/handler/plsql/procedureVariable.d.ts

@@ -1,4 +1,4 @@
-export function getProcedureVariable(req: Request, procName: string, argObj: argObjType): {
+export function getProcedureVariable(_req: Request, procName: string, argObj: argObjType): {
     sql: string;
     bind: BindParameterConfig;
 };

package/types/handler/plsql/request.d.ts

@@ -1,7 +1,9 @@
-export function processRequest(req: Request, res: Response, options: configPlSqlHandlerType, connectionPool: Pool): Promise<void>;
+export function processRequest(req: Request, res: Response, options: configPlSqlHandlerType, connectionPool: Pool, procedureNameCache: ProcedureNameCache, argumentCache: ArgumentCache): Promise<void>;
 export type Request = import("express").Request;
 export type Response = import("express").Response;
 export type Pool = import("oracledb").Pool;
 export type Connection = import("oracledb").Connection;
 export type argObjType = import("../../types.js").argObjType;
 export type configPlSqlHandlerType = import("../../types.js").configPlSqlHandlerType;
+export type ProcedureNameCache = import("../../util/cache.js").Cache<string>;
+export type ArgumentCache = import("../../util/cache.js").Cache<import("./procedureNamed.js").argsType>;

package/types/handler/plsql/sendResponse.d.ts

@@ -1,4 +1,4 @@
-export function sendResponse(req: Request, res: Response, page: pageType): Promise<void>;
+export function sendResponse(_req: Request, res: Response, page: pageType): Promise<void>;
 export type Request = import("express").Request;
 export type Response = import("express").Response;
 export type CookieOptions = import("express").CookieOptions;

package/types/index.d.ts

@@ -6,6 +6,5 @@ export * from "./util/file.js";
 export { handlerWebPlSql } from "./handler/plsql/handlerPlSql.js";
 export { handlerLogger } from "./handler/handlerLogger.js";
 export { handlerUpload } from "./handler/handlerUpload.js";
-export { handlerMetrics } from "./handler/handlerMetrics.js";
 import oracledb from 'oracledb';
 export { createServer, startServer, loadConfig, startServerConfig } from "./server/server.js";

package/types/server/adminContext.d.ts

@@ -0,0 +1,17 @@
+export namespace AdminContext {
+    let startTime: Date;
+    let config: configType | null;
+    let pools: Pool[];
+    let caches: Array<{
+        poolName: string;
+        procedureNameCache: Cache;
+        argumentCache: Cache;
+    }>;
+    let paused: boolean;
+    let statsManager: StatsManager;
+}
+export type Pool = import("oracledb").Pool;
+export type configType = import("../types.js").configType;
+export type argsType = import("../handler/plsql/procedureNamed.js").argsType;
+export type Cache = import("../util/cache.js").Cache<unknown>;
+import { StatsManager } from '../util/statsManager.js';

package/types/server/server.d.ts

@@ -10,6 +10,11 @@ export type NextFunction = import("express").NextFunction;
 export type Pool = import("oracledb").Pool;
 export type environmentType = import("../types.js").environmentType;
 export type configType = import("../types.js").configType;
+export type argsType = import("../handler/plsql/procedureNamed.js").argsType;
+export type ExtendedRequestHandler = import("express").RequestHandler & {
+    procedureNameCache: import("../util/cache.js").Cache<string>;
+    argumentCache: import("../util/cache.js").Cache<argsType>;
+};
 /**
  * - Web server interface.
  */

package/types/types.d.ts

@@ -92,6 +92,9 @@ export const z$configPlSqlType: z.ZodObject<{
  * @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.ZodObject<{
     port: z.ZodNumber;
@@ -118,6 +121,9 @@ export const z$configType: z.ZodObject<{
     }, z.core.$strict>>;
     uploadFileSizeLimit: z.ZodOptional<z.ZodNumber>;
     loggerFilename: z.ZodString;
+    adminRoute: z.ZodOptional<z.ZodString>;
+    adminUser: z.ZodOptional<z.ZodString>;
+    adminPassword: z.ZodOptional<z.ZodString>;
 }, z.core.$strict>;
 export type BindParameter = import("oracledb").BindParameter;
 export type Connection = import("oracledb").Connection;
@@ -217,6 +223,18 @@ export type configType = {
      * - name of the request logger filename or '' if not required.
      */
     loggerFilename: string;
+    /**
+     * - Optional route for the admin console (defaults to /admin).
+     */
+    adminRoute?: string;
+    /**
+     * - Optional username for admin console basic auth.
+     */
+    adminUser?: string;
+    /**
+     * - Optional password for admin console basic auth.
+     */
+    adminPassword?: string;
 };
 /**
  * Environment variables as string key-value pairs
@@ -284,7 +302,7 @@ export type pageType = {
     /**
      * - The body of the page.
      */
-    body: string;
+    body: string | import("node:stream").Readable;
     /**
      * - The head of the page.
      */

package/types/util/cache.d.ts

@@ -0,0 +1,69 @@
+/**
+ * @template T
+ * @typedef {{hitCount: number, value: T}} cacheEntryType
+ */
+/**
+ * Generic Cache class with LFU (Least Frequently Used) eviction policy.
+ * @template T
+ */
+export class Cache<T> {
+    /**
+     * @param {number} maxSize - Maximum number of entries in the cache.
+     */
+    constructor(maxSize?: number);
+    /** @type {Map<string, cacheEntryType<T>>} */
+    cache: Map<string, cacheEntryType<T>>;
+    maxSize: number;
+    hits: number;
+    misses: number;
+    /**
+     * Get an entry from the cache.
+     * @param {string} key - The key.
+     * @returns {T | undefined} - The value or undefined if not found.
+     */
+    get(key: string): T | undefined;
+    /**
+     * Set an entry in the cache.
+     * @param {string} key - The key.
+     * @param {T} value - The value.
+     */
+    set(key: string, value: T): void;
+    /**
+     * Delete an entry from the cache.
+     * @param {string} key - The key.
+     */
+    delete(key: string): void;
+    /**
+     * Clear the cache.
+     */
+    clear(): void;
+    /**
+     * Prune the cache by removing the least frequently used entries.
+     * Removes 10% of the cache size.
+     */
+    prune(): void;
+    /**
+     * Get the size of the cache.
+     * @returns {number} - The size.
+     */
+    get size(): number;
+    /**
+     * Get all keys in the cache.
+     * @returns {string[]} - The keys.
+     */
+    keys(): string[];
+    /**
+     * Get cache statistics.
+     * @returns {{size: number, maxSize: number, hits: number, misses: number}} - The statistics.
+     */
+    getStats(): {
+        size: number;
+        maxSize: number;
+        hits: number;
+        misses: number;
+    };
+}
+export type cacheEntryType<T> = {
+    hitCount: number;
+    value: T;
+};

package/types/util/jsonLogger.d.ts

@@ -0,0 +1,45 @@
+/**
+ * @typedef {object} LogEntry
+ * @property {string} timestamp - ISO string
+ * @property {'error'|'info'|'warning'} type - Log level
+ * @property {string} message - Error message
+ * @property {object} [req] - Request details
+ * @property {object} [details] - Additional details (stack, sql, etc)
+ */
+export class JsonLogger {
+    constructor(filename?: string);
+    stream: rotatingFileStream.RotatingFileStream;
+    /**
+     * Log an entry as NDJSON.
+     * @param {LogEntry} entry - The entry to log.
+     */
+    log(entry: LogEntry): void;
+    /**
+     * Close the stream.
+     */
+    close(): void;
+}
+export const jsonLogger: JsonLogger;
+export type LogEntry = {
+    /**
+     * - ISO string
+     */
+    timestamp: string;
+    /**
+     * - Log level
+     */
+    type: "error" | "info" | "warning";
+    /**
+     * - Error message
+     */
+    message: string;
+    /**
+     * - Request details
+     */
+    req?: object;
+    /**
+     * - Additional details (stack, sql, etc)
+     */
+    details?: object;
+};
+import * as rotatingFileStream from 'rotating-file-stream';