web_plsql 0.18.0 → 1.2.0

package/src/admin/js/schemas.ts

@@ -0,0 +1,215 @@
+import {z} from 'zod';
+
+/**
+ * Cache statistics schema.
+ */
+export const cacheStatsSchema = z.object({
+	size: z.number(),
+	hits: z.number(),
+	misses: z.number(),
+});
+
+/**
+ * Pool cache snapshot schema.
+ */
+export const poolCacheSnapshotSchema = z.object({
+	procedureName: cacheStatsSchema,
+	argument: cacheStatsSchema,
+});
+
+/**
+ * Pool statistics schema.
+ */
+export const poolStatsSchema = z.object({
+	totalRequests: z.number(),
+	totalTimeouts: z.number(),
+	totalRequestsEnqueued: z.number().optional(),
+	totalRequestsDequeued: z.number().optional(),
+	totalRequestsFailed: z.number().optional(),
+});
+
+/**
+ * Pool information schema.
+ */
+export const poolInfoSchema = z.object({
+	name: z.string(),
+	connectionsInUse: z.number(),
+	connectionsOpen: z.number(),
+	stats: poolStatsSchema.nullable(),
+	cache: poolCacheSnapshotSchema.optional(),
+});
+
+/**
+ * Server metrics schema.
+ */
+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(),
+		}),
+	),
+});
+
+/**
+ * Route configuration schema.
+ */
+export const routeConfigSchema = z.object({
+	route: z.string(),
+	// PL/SQL specific
+	user: z.string().optional(),
+	password: z.string().optional(),
+	connectString: z.string().optional(),
+	defaultPage: z.string().optional(),
+	pathAlias: z.string().optional(),
+	pathAliasProcedure: z.string().optional(),
+	documentTable: z.string().optional(),
+	exclusionList: z.array(z.string()).optional(),
+	requestValidationFunction: z.string().optional(),
+	transactionMode: z.unknown().optional(),
+	errorStyle: z.string().optional(),
+	// Static specific
+	directoryPath: z.string().optional(),
+});
+
+/**
+ * Server configuration schema.
+ */
+export const serverConfigSchema = z.object({
+	port: z.number(),
+	adminRoute: z.string().optional(),
+	adminUser: z.string().optional(),
+	adminPassword: z.string().optional(),
+	loggerFilename: z.string(),
+	uploadFileSizeLimit: z.number().optional(),
+	routePlSql: z.array(routeConfigSchema),
+	routeStatic: z.array(routeConfigSchema),
+});
+
+/**
+ * System information schema.
+ */
+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(),
+	}),
+});
+
+/**
+ * Server status response schema.
+ */
+export const statusSchema = z.object({
+	version: z.string(),
+	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(),
+});
+
+/**
+ * Error log entry schema.
+ */
+export const errorLogSchema = z.object({
+	timestamp: z.string(),
+	req: z
+		.object({
+			method: z.string().optional(),
+			url: z.string().optional(),
+		})
+		.optional(),
+	message: z.string(),
+	details: z
+		.object({
+			fullMessage: z.string().optional(),
+		})
+		.optional(),
+});
+
+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 ErrorLogResponse = z.infer<typeof errorLogSchema>;
+export type AccessLogResponse = z.infer<typeof accessLogResponseSchema>;

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

@@ -0,0 +1,147 @@
+import type {ServerConfig, RouteConfig} from '../types.js';
+
+/**
+ * Render a stat row using the standardized format.
+ * @param label - The field label.
+ * @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', title = ''): string {
+	const valClass = `${isMono ? 'font-mono' : ''} ${colorClass} font-bold break-all`.trim();
+	return `
+		<div class="stat-row text-sm" ${title ? `title="${title}"` : ''}>
+			<span>${label}</span>
+			<span class="${valClass}">${value}</span>
+		</div>
+	`;
+}
+
+/**
+ * Render a configuration section header.
+ * @param title - The section title.
+ * @param icon - The Material icon name.
+ * @returns HTML string.
+ */
+function renderSectionTitle(title: string, icon: string): string {
+	return `
+		<div class="card-header mt-6 mb-2">
+			<span class="material-symbols-rounded icon-sm">${icon}</span>
+			<h3 class="text-xs uppercase tracking-wider font-bold text-accent">${title}</h3>
+		</div>
+	`;
+}
+
+/**
+ * Render a PL/SQL route card.
+ * @param r - The route configuration.
+ * @param index - The index of the route.
+ * @returns HTML string.
+ */
+function renderPlSqlRoute(r: RouteConfig, index: number): string {
+	const exclusionList = r.exclusionList?.length ? r.exclusionList.join(', ') : '(None)';
+	const transactionMode = typeof r.transactionMode === 'string' ? r.transactionMode : r.transactionMode ? 'Custom' : 'commit';
+
+	return `
+		<div class="card mb-6">
+			<div class="flex justify-between items-center mb-4">
+				<div class="flex items-center gap-3">
+					<span class="badge badge-info">PL/SQL Route #${index + 1}</span>
+					<code class="text-lg font-bold text-bright">${r.route}</code>
+				</div>
+			</div>
+
+			<div class="grid grid-cols-1 md:grid-cols-2 gap-6">
+				<div>
+					<h4 class="text-xs font-bold text-main uppercase mb-3 opacity-75">Database Connection</h4>
+					${renderStatRow('Oracle User', r.user ?? '(Not set)')}
+					${renderStatRow('Connect String', r.connectString ?? '(Not set)')}
+					${renderStatRow('Password', r.password ?? '(None)')}
+				</div>
+				<div>
+					<h4 class="text-xs font-bold text-main uppercase mb-3 opacity-75">Request Handler</h4>
+					${renderStatRow('Default Page', r.defaultPage ?? 'index')}
+					${renderStatRow('Document Table', r.documentTable ?? '(None)')}
+					${renderStatRow('Error Style', r.errorStyle ?? 'table')}
+					${renderStatRow('Transaction Mode', transactionMode)}
+				</div>
+			</div>
+
+			<div class="mt-4 pt-4 border-t">
+				<h4 class="text-xs font-bold text-main uppercase mb-3 opacity-75">Path & Validation</h4>
+				${renderStatRow('Path Alias', r.pathAlias ?? '(None)')}
+				${renderStatRow('Path Alias Proc', r.pathAliasProcedure ?? '(None)')}
+				${renderStatRow('Exclusion List', exclusionList)}
+				${renderStatRow('Validation Func', r.requestValidationFunction ?? '(None)')}
+			</div>
+		</div>
+	`;
+}
+
+/**
+ * Render a Static route card.
+ * @param r - The route configuration.
+ * @param index - The index of the route.
+ * @returns HTML string.
+ */
+function renderStaticRoute(r: RouteConfig, index: number): string {
+	return `
+		<div class="card mb-4">
+			<div class="flex items-center gap-3 mb-4">
+				<span class="badge badge-success">Static Route #${index + 1}</span>
+				<code class="text-lg font-bold text-bright">${r.route}</code>
+			</div>
+			${renderStatRow('Directory Path', r.directoryPath ?? '(Not set)')}
+		</div>
+	`;
+}
+
+/**
+ * Render the full server configuration.
+ * @param config - The server configuration.
+ * @returns HTML string.
+ */
+export function renderConfig(config: Partial<ServerConfig>): string {
+	let html = '<div class="config-view-content">';
+
+	// Global Server Section
+	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, true, 'text-accent', 'The TCP port the server is listening on');
+	}
+	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)`, true, 'text-accent', 'Maximum allowed size for file uploads');
+	} else {
+		html += renderStatRow('Upload Size Limit', 'No limit', false, 'text-accent', 'Maximum allowed size for file uploads');
+	}
+	html += '</div>';
+
+	// PL/SQL Routes
+	html += renderSectionTitle('PL/SQL Routes', 'database');
+	if (config.routePlSql?.length) {
+		html += config.routePlSql.map((r, i) => renderPlSqlRoute(r, i)).join('');
+	} else {
+		html += '<div class="empty-state">No PL/SQL routes configured</div>';
+	}
+
+	// Static Routes
+	html += renderSectionTitle('Static Routes', 'folder_shared');
+	if (config.routeStatic?.length) {
+		html += config.routeStatic.map((r, i) => renderStaticRoute(r, i)).join('');
+	} else {
+		html += '<div class="empty-state">No static routes configured</div>';
+	}
+
+	html += '</div>';
+	return html;
+}

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

@@ -0,0 +1,21 @@
+import type {ErrorLogResponse} from '../schemas.js';
+
+/**
+ * Error log row template.
+ *
+ * @param l - The error log entry.
+ * @returns HTML string for the error row.
+ */
+export function errorRow(l: ErrorLogResponse): string {
+	return `
+        <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

@@ -0,0 +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

@@ -0,0 +1,61 @@
+import type {StatusResponse} from '../schemas.js';
+
+type PoolInfo = StatusResponse['pools'][number];
+
+/**
+ * Pool card template.
+ *
+ * @param p - The pool data.
+ * @returns HTML string for the pool card.
+ */
+export function poolCard(p: PoolInfo): string {
+	const utilization = p.connectionsOpen > 0 ? Math.round((p.connectionsInUse / p.connectionsOpen) * 100) : 0;
+	const utilColor = utilization > 90 ? 'var(--danger)' : utilization > 70 ? 'var(--warning)' : 'var(--success)';
+
+	const stats = p.stats ?? undefined;
+
+	return `
+        <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" 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>
+                </div>
+                <div class="progress-bar">
+                    <div class="progress-bar-fill transition-all duration-300" style="width: ${utilization}%; background: ${utilColor}"></div>
+                </div>
+                <small class="description mt-2 block opacity-75">Pool Utilization (Active / Open)</small>
+            </div>
+            
+            <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" 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>
+
+            ${
+				stats
+					? `
+                <div class="mt-4 pt-4 border-t">
+                    <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" 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>
+                </div>
+            `
+					: ''
+			}
+        </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/tsconfig.json

@@ -0,0 +1,24 @@
+{
+	"compilerOptions": {
+		"noEmit": true,
+		"target": "es2020",
+		"module": "es2020",
+		"moduleResolution": "bundler",
+		"esModuleInterop": true,
+		"skipLibCheck": true,
+		"allowSyntheticDefaultImports": true,
+		"allowJs": true,
+		"checkJs": true,
+		"strict": true,
+		"noImplicitAny": true,
+		"strictNullChecks": true,
+		"strictFunctionTypes": true,
+		"strictBindCallApply": true,
+		"noImplicitThis": true,
+		"useUnknownInCatchVariables": true,
+		"alwaysStrict": true,
+		"lib": ["es2020", "dom", "dom.iterable"]
+	},
+	"include": ["**/*.js", "**/*.ts", "**/*.d.ts"],
+	"exclude": ["lib/**"]
+}