web_plsql 1.0.0 → 1.2.0

package/src/admin/js/schemas.ts

@@ -4,25 +4,17 @@ import {z} from 'zod';
  * Cache statistics schema.
  */
 export const cacheStatsSchema = z.object({
+	size: z.number(),
 	hits: z.number(),
 	misses: z.number(),
 });
 
 /**
- * Cache information schema.
- */
-export const cacheInfoSchema = z.object({
-	size: z.number(),
-	stats: cacheStatsSchema,
-});
-
-/**
- * Cache data schema for a connection pool.
+ * Pool cache snapshot schema.
  */
-export const cacheDataSchema = z.object({
-	poolName: z.string(),
-	procedureNameCache: cacheInfoSchema,
-	argumentCache: cacheInfoSchema,
+export const poolCacheSnapshotSchema = z.object({
+	procedureName: cacheStatsSchema,
+	argument: cacheStatsSchema,
 });
 
 /**
@@ -44,6 +36,7 @@ export const poolInfoSchema = z.object({
 	connectionsInUse: z.number(),
 	connectionsOpen: z.number(),
 	stats: poolStatsSchema.nullable(),
+	cache: poolCacheSnapshotSchema.optional(),
 });
 
 /**
@@ -53,6 +46,38 @@ export const metricsSchema = z.object({
 	requestCount: z.number(),
 	errorCount: z.number(),
 	avgResponseTime: z.number(),
+	minResponseTime: z.number(),
+	maxResponseTime: z.number(),
+	maxRequestsPerSecond: z.number(),
+});
+
+/**
+ * Historical bucket schema.
+ */
+export const bucketSchema = z.object({
+	timestamp: z.number(),
+	requests: z.number(),
+	errors: z.number(),
+	durationMin: z.number(),
+	durationMax: z.number(),
+	durationAvg: z.number(),
+	durationP95: z.number(),
+	durationP99: z.number(),
+	system: z.object({
+		cpu: z.number(),
+		heapUsed: z.number(),
+		heapTotal: z.number(),
+		rss: z.number(),
+		external: z.number(),
+	}),
+	pools: z.array(
+		z.object({
+			name: z.string(),
+			connectionsInUse: z.number(),
+			connectionsOpen: z.number(),
+			cache: poolCacheSnapshotSchema.optional(),
+		}),
+	),
 });
 
 /**
@@ -97,15 +122,24 @@ export const systemInfoSchema = z.object({
 	nodeVersion: z.string(),
 	platform: z.string(),
 	arch: z.string(),
+	cpuCores: z.number().optional(),
 	memory: z.object({
 		rss: z.number(),
 		heapTotal: z.number(),
 		heapUsed: z.number(),
 		external: z.number(),
+		totalMemory: z.number().optional(),
+		rssMax: z.number().optional(),
+		heapTotalMax: z.number().optional(),
+		heapUsedMax: z.number().optional(),
+		externalMax: z.number().optional(),
 	}),
 	cpu: z.object({
 		user: z.number(),
 		system: z.number(),
+		max: z.number().optional(),
+		userMax: z.number().optional(),
+		systemMax: z.number().optional(),
 	}),
 });
 
@@ -117,7 +151,9 @@ export const statusSchema = z.object({
 	status: z.enum(['running', 'paused', 'stopped']),
 	uptime: z.number(),
 	startTime: z.string(),
+	intervalMs: z.number().optional(),
 	metrics: metricsSchema,
+	history: z.array(bucketSchema).optional(),
 	pools: z.array(poolInfoSchema),
 	system: systemInfoSchema,
 	config: serverConfigSchema.partial(),
@@ -144,10 +180,36 @@ export const errorLogSchema = z.object({
 
 export const accessLogResponseSchema = z.union([z.array(z.string()), z.object({message: z.string()})]);
 
+/**
+ * Trace entry schema.
+ */
+export const traceEntrySchema = z.object({
+	id: z.string(),
+	timestamp: z.string(),
+	source: z.string(),
+	url: z.string(),
+	method: z.string(),
+	status: z.string(),
+	duration: z.number(),
+	procedure: z.string().optional(),
+	parameters: z.record(z.string(), z.any()).optional(),
+	uploads: z.array(z.any()).optional(),
+	downloads: z
+		.object({
+			fileType: z.string(),
+			fileSize: z.number(),
+		})
+		.optional(),
+	html: z.string().optional(),
+	cookies: z.record(z.string(), z.string()).optional(),
+	headers: z.record(z.string(), z.string()).optional(),
+	cgi: z.record(z.string(), z.string()).optional(),
+	error: z.string().optional(),
+});
+
 /**
  * API response type helpers.
  */
 export type StatusResponse = z.infer<typeof statusSchema>;
-export type CacheDataResponse = z.infer<typeof cacheDataSchema>;
 export type ErrorLogResponse = z.infer<typeof errorLogSchema>;
 export type AccessLogResponse = z.infer<typeof accessLogResponseSchema>;

package/src/admin/js/templates/config.ts

@@ -6,12 +6,13 @@ import type {ServerConfig, RouteConfig} from '../types.js';
  * @param value - The value to display.
  * @param isMono - Whether to use monospaced font.
  * @param colorClass - The CSS class for coloring the value.
+ * @param title - Optional tooltip explanation.
  * @returns HTML string.
  */
-function renderStatRow(label: string, value: string | number, isMono = true, colorClass = 'text-accent'): string {
+function renderStatRow(label: string, value: string | number, isMono = true, colorClass = 'text-accent', title = ''): string {
 	const valClass = `${isMono ? 'font-mono' : ''} ${colorClass} font-bold break-all`.trim();
 	return `
-		<div class="stat-row text-sm">
+		<div class="stat-row text-sm" ${title ? `title="${title}"` : ''}>
 			<span>${label}</span>
 			<span class="${valClass}">${value}</span>
 		</div>
@@ -109,19 +110,19 @@ export function renderConfig(config: Partial<ServerConfig>): string {
 	html += '<div class="card mb-8">';
 	html += '<div class="card-header"><span class="material-symbols-rounded">dns</span><h3>Server Settings</h3></div>';
 	if (typeof config.port === 'number') {
-		html += renderStatRow('Port', config.port);
+		html += renderStatRow('Port', config.port, true, 'text-accent', 'The TCP port the server is listening on');
 	}
-	html += renderStatRow('Admin Route', config.adminRoute ?? '/admin');
-	html += renderStatRow('Admin User', config.adminUser ?? '(Not authenticated)');
-	html += renderStatRow('Admin Password', config.adminPassword ?? '(None)');
-	html += renderStatRow('Logger Filename', config.loggerFilename ?? '(Logging disabled)');
+	html += renderStatRow('Admin Route', config.adminRoute ?? '/admin', true, 'text-accent', 'The URL path for the administration console');
+	html += renderStatRow('Admin User', config.adminUser ?? '(Not authenticated)', true, 'text-accent', 'The username required for admin access');
+	html += renderStatRow('Admin Password', config.adminPassword ?? '(None)', true, 'text-accent', 'The password required for admin access');
+	html += renderStatRow('Logger Filename', config.loggerFilename ?? '(Logging disabled)', true, 'text-accent', 'The path to the server log file');
 
 	if (typeof config.uploadFileSizeLimit === 'number') {
 		const limit = config.uploadFileSizeLimit;
 		const mb = (limit / (1024 * 1024)).toFixed(2);
-		html += renderStatRow('Upload Size Limit', `${mb} MB (${limit.toLocaleString()} bytes)`);
+		html += renderStatRow('Upload Size Limit', `${mb} MB (${limit.toLocaleString()} bytes)`, true, 'text-accent', 'Maximum allowed size for file uploads');
 	} else {
-		html += renderStatRow('Upload Size Limit', 'No limit');
+		html += renderStatRow('Upload Size Limit', 'No limit', false, 'text-accent', 'Maximum allowed size for file uploads');
 	}
 	html += '</div>';
 

package/src/admin/js/templates/errorRow.ts

@@ -8,11 +8,14 @@ import type {ErrorLogResponse} from '../schemas.js';
  */
 export function errorRow(l: ErrorLogResponse): string {
 	return `
-        <tr>
-            <td>${new Date(l.timestamp).toLocaleString()}</td>
-            <td><code>${l.req?.method ?? '-'}</code></td>
-            <td>${l.req?.url ?? '-'}</td>
-            <td title="${l.details?.fullMessage ?? ''}">${l.message}</td>
+        <tr title="Click to see full error details">
+            <td title="Timestamp: ${new Date(l.timestamp).toLocaleString()}">${new Date(l.timestamp).toLocaleString()}</td>
+            <td title="Method: ${l.req?.method ?? '-'}"><code>${l.req?.method ?? '-'}</code></td>
+            <td title="URL: ${l.req?.url ?? '-'}">${l.req?.url ?? '-'}</td>
+            <td title="Click for details: ${l.details?.fullMessage ?? ''}" class="break-all">${l.message}</td>
+            <td style="width: 40px; text-align: center; color: var(--accent); opacity: 0.7">
+                <span class="material-symbols-rounded">chevron_right</span>
+            </td>
         </tr>
     `;
 }

package/src/admin/js/templates/index.ts

@@ -1,3 +1,4 @@
 export {errorRow} from './errorRow.js';
+export {traceRow} from './traceRow.js';
 export {poolCard} from './poolCard.js';
 export {renderConfig} from './config.js';

package/src/admin/js/templates/poolCard.ts

@@ -15,12 +15,12 @@ export function poolCard(p: PoolInfo): string {
 	const stats = p.stats ?? undefined;
 
 	return `
-        <div class="card card-clickable transition-all duration-200">
+        <div class="card card-clickable transition-all duration-200" title="Connection pool status for ${p.name}">
             <div class="card-header">
                 <span class="material-symbols-rounded">database</span>
                 <h3 class="text-lg font-bold text-bright">${p.name}</h3>
             </div>
-            <div class="mb-6">
+            <div class="mb-6" title="Utilization: ${utilization}% of open connections are currently in use">
                 <div class="flex justify-between items-baseline mb-2">
                     <span class="text-3xl font-bold text-bright">${utilization}%</span>
                     <span class="text-main font-mono">${p.connectionsInUse} / ${p.connectionsOpen}</span>
@@ -31,11 +31,11 @@ export function poolCard(p: PoolInfo): string {
                 <small class="description mt-2 block opacity-75">Pool Utilization (Active / Open)</small>
             </div>
             
-            <div class="stat-row text-sm">
+            <div class="stat-row text-sm" title="Total number of connections currently open in the pool">
                 <span class="text-xs uppercase font-bold opacity-75">Connections Open</span>
                 <span class="font-mono text-accent font-bold">${p.connectionsOpen}</span>
             </div>
-            <div class="stat-row text-sm">
+            <div class="stat-row text-sm" title="Number of connections currently active and handling requests">
                 <span class="text-xs uppercase font-bold opacity-75">Connections In Use</span>
                 <span class="font-mono text-accent font-bold">${p.connectionsInUse}</span>
             </div>
@@ -44,11 +44,11 @@ export function poolCard(p: PoolInfo): string {
 				stats
 					? `
                 <div class="mt-4 pt-4 border-t">
-                    <div class="stat-row text-sm">
+                    <div class="stat-row text-sm" title="Cumulative number of requests handled by this pool since server start">
                         <span>Total Requests</span>
                         <span class="font-mono text-accent font-bold">${stats.totalRequests.toLocaleString()}</span>
                     </div>
-                    <div class="stat-row text-sm">
+                    <div class="stat-row text-sm" title="Number of requests that timed out waiting for a connection">
                         <span>Total Timeouts</span>
                         <span class="font-mono ${stats.totalTimeouts > 0 ? 'text-danger' : 'text-accent'} font-bold">${stats.totalTimeouts.toLocaleString()}</span>
                     </div>

package/src/admin/js/templates/traceRow.ts

@@ -0,0 +1,24 @@
+import type {TraceEntry} from '../types.js';
+import {formatMs} from '../util/format.js';
+
+/**
+ * Render a single trace row for the trace table.
+ *
+ * @param trace - The trace log entry.
+ * @returns HTML string.
+ */
+export function traceRow(trace: TraceEntry): string {
+	const time = new Date(trace.timestamp).toLocaleTimeString();
+	const statusClass = trace.status === 'success' ? 'text-success' : 'text-danger';
+
+	return `
+		<tr class="trace-table-row cursor-pointer hover:bg-white/5 transition-colors border-b border-white/5" data-id="${trace.id}">
+			<td class="px-4 py-2 font-mono text-xs text-dim">${time}</td>
+			<td class="px-4 py-2 text-dim text-xs truncate max-w-[150px]" title="${trace.source}">${trace.source}</td>
+			<td class="px-4 py-2 text-bright font-mono text-xs truncate max-w-[300px]" title="${trace.url}">${trace.url}</td>
+			<td class="px-4 py-2 font-bold ${statusClass} text-xs uppercase">${trace.status}</td>
+			<td class="px-4 py-2 text-right font-mono text-xs text-dim">${formatMs(trace.duration)}</td>
+			<td class="px-4 py-2 text-dim text-xs truncate max-w-[200px]" title="${trace.procedure ?? ''}">${trace.procedure ?? '-'}</td>
+		</tr>
+	`;
+}

package/src/admin/js/types.ts

@@ -51,6 +51,9 @@ export type Metrics = {
 	requestCount: number;
 	errorCount: number;
 	avgResponseTime: number;
+	minResponseTime: number;
+	maxResponseTime: number;
+	maxRequestsPerSecond: number;
 };
 
 /**
@@ -96,11 +99,38 @@ export type Status = {
 	status: 'running' | 'paused' | 'stopped';
 	uptime: number;
 	startTime: string;
+	intervalMs?: number;
 	metrics: Metrics;
 	pools: PoolInfo[];
 	config: Partial<ServerConfig>;
 };
 
+/**
+ * Resident Set Size - total memory used by the process
+ */
+export type HistoryBucket = {
+	timestamp: number;
+	requests: number;
+	errors: number;
+	durationMin: number;
+	durationMax: number;
+	durationAvg: number;
+	durationP95: number;
+	durationP99: number;
+	system: {
+		cpu: number;
+		heapUsed: number;
+		heapTotal: number;
+		rss: number;
+		external: number;
+	};
+	pools: {
+		name: string;
+		connectionsInUse: number;
+		connectionsOpen: number;
+	}[];
+};
+
 /**
  * Historical data for charts.
  */
@@ -108,6 +138,8 @@ export type HistoryData = {
 	labels: string[];
 	requests: number[];
 	avgResponseTimes: number[];
+	p95ResponseTimes?: number[];
+	p99ResponseTimes?: number[];
 	poolUsage: Record<string, number[]>;
 };
 
@@ -115,45 +147,85 @@ export type HistoryData = {
  * Chart grid options.
  */
 export type ChartGridOptions = {
-	color: string;
+	color?: string;
+	display?: boolean;
+	drawBorder?: boolean;
+	drawOnChartArea?: boolean;
 };
 
 /**
  * Chart ticks options.
  */
 export type ChartTicksOptions = {
-	color: string;
+	color?: string;
 	display?: boolean;
+	stepSize?: number;
+	maxRotation?: number;
+	autoSkip?: boolean;
+	maxTicksLimit?: number;
+	callback?: (value: number | string) => string;
 };
 
 /**
  * Chart scale options.
  */
 export type ChartScaleOptions = {
+	display?: boolean;
 	grid?: ChartGridOptions;
 	ticks?: ChartTicksOptions;
+	border?: {
+		display?: boolean;
+		color?: string;
+	};
 	title?: {
 		display: boolean;
 		text: string;
 		color: string;
 	};
+	type?: string;
+	position?: string;
+	beginAtZero?: boolean;
+	max?: number;
 };
 
 /**
  * Chart options.
  */
 export type ChartOptions = {
+	responsive?: boolean;
+	maintainAspectRatio?: boolean;
 	scales?: {
 		x?: ChartScaleOptions;
 		y?: ChartScaleOptions;
 		y1?: ChartScaleOptions;
 	};
+	layout?: {
+		padding?: number;
+	};
 	plugins?: {
 		legend?: {
+			display?: boolean;
 			labels?: {
-				color: string;
+				color?: string;
 			};
 		};
+		tooltip?: {
+			enabled?: boolean;
+			position?: string;
+			intersect?: boolean;
+			callbacks?: Record<string, unknown>;
+		};
+	};
+	elements?: {
+		point?: {
+			radius?: number;
+		};
+		line?: {
+			borderWidth?: number;
+		};
+		bar?: {
+			borderWidth?: number;
+		};
 	};
 };
 
@@ -165,8 +237,13 @@ export type ChartDataset = {
 	data: number[];
 	borderColor: string;
 	backgroundColor: string | undefined;
-	fill: boolean | undefined;
-	tension: number | undefined;
+	fill?: boolean | undefined;
+	tension?: number | undefined;
+	barThickness?: number;
+	categoryPercentage?: number;
+	barPercentage?: number;
+	borderWidth?: number;
+	yAxisID?: string;
 };
 
 /**
@@ -187,25 +264,48 @@ export type ChartInstance = {
 };
 
 /**
- * Error log entry.
+ * Trace entry.
  */
-export type ErrorLog = {
+export type TraceEntry = {
+	id: string;
 	timestamp: string;
-	req:
-		| {
-				method: string;
-				url: string;
-		  }
-		| undefined;
-	message: string;
-	details:
+	source: string;
+	url: string;
+	method: string;
+	status: string;
+	duration: number;
+	procedure?: string | undefined;
+	parameters?: Record<string, unknown> | undefined;
+	uploads?: {originalname: string; mimetype: string; size: number}[] | undefined;
+	downloads?:
 		| {
-				fullMessage: string;
+				fileType: string;
+				fileSize: number;
 		  }
 		| undefined;
+	html?: string | undefined;
+	cookies?: Record<string, string> | undefined;
+	headers?: Record<string, string> | undefined;
+	cgi?: Record<string, string> | undefined;
+	error?: string | undefined;
 };
 
-import type {StatusResponse} from './schemas.js';
+import type {StatusResponse, ErrorLogResponse, AccessLogResponse} from './schemas.js';
+
+// Re-export types from schemas
+export type {StatusResponse, ErrorLogResponse, AccessLogResponse};
+
+/**
+ * System metrics for tracking min/max.
+ */
+export type SystemMetrics = {
+	heapUsed: number;
+	heapTotal: number;
+	rss: number;
+	external: number;
+	cpuUser: number;
+	cpuSystem: number;
+};
 
 /**
  * Application state.
@@ -217,7 +317,20 @@ export type State = {
 	lastRequestCount: number;
 	lastErrorCount: number;
 	lastUpdateTime: number;
-	refreshTimer: ReturnType<typeof setInterval> | null;
-	history: HistoryData;
+	lastBucketTimestamp: number;
+	nextRefreshTimeout: ReturnType<typeof setTimeout> | null;
+	nextRefreshTime: number;
+	countdownInterval: ReturnType<typeof setInterval> | null;
+	history: HistoryData & {
+		cpuUsage: number[];
+		memoryUsage: number[];
+	};
 	charts: Record<string, ChartInstance>;
+	metricsMin: Partial<SystemMetrics>;
+	metricsMax: Partial<SystemMetrics>;
 };
+
+declare global {
+	/** Injected by Vite during build */
+	const __BUILD_TIME__: string;
+}

package/src/admin/js/ui/components.ts

@@ -0,0 +1,44 @@
+/**
+ * Enhances a button with loading state logic.
+ *
+ * @param btn - The button element to enhance.
+ * @param action - The async function to execute when the button is clicked.
+ * @returns The result of the action.
+ */
+export async function withLoading<T>(btn: HTMLButtonElement, action: () => Promise<T>): Promise<T> {
+	const iconSpan = btn.querySelector('.material-symbols-rounded');
+	const originalIcon = iconSpan?.textContent;
+
+	btn.disabled = true;
+	btn.classList.add('loading');
+	if (iconSpan) {
+		iconSpan.textContent = 'sync';
+		iconSpan.classList.add('animate-spin');
+	}
+
+	try {
+		return await action();
+	} finally {
+		btn.disabled = false;
+		btn.classList.remove('loading');
+		if (iconSpan) {
+			iconSpan.textContent = originalIcon ?? '';
+			iconSpan.classList.remove('animate-spin');
+		}
+	}
+}
+
+/**
+ * Binds an async action to a button with standardized loading feedback.
+ *
+ * @param id - The ID of the button element.
+ * @param action - The async action to perform.
+ * @returns The button element or null if not found.
+ */
+export function bindLoadingButton(id: string, action: () => Promise<void>): HTMLButtonElement | null {
+	const btn = document.getElementById(id) as HTMLButtonElement | null;
+	if (btn) {
+		btn.onclick = () => void withLoading(btn, action);
+	}
+	return btn;
+}