web_plsql 0.17.1 → 1.0.0

package/README.md

@@ -31,10 +31,29 @@ Please visit the [node-oracledb](https://node-oracledb.readthedocs.io/en/latest/
 * Start server using `node examples/config-native.js` after having set the WEB_PLSQL_ORACLE_SERVER environment variable to the database where you just installed the sample schema.
 * Invoke a browser and open the page `http://localhost/sample`.
 
-## Container
-* Build the image using `npm run image-build`.
-* Adapt the `examples/config-docker.json` configuration file. Typically only the `connectString` property must be changed.
-* Start the container using `docker compose up -d`.
+# Admin Console
+
+`web_plsql` includes a built-in Admin Console for real-time monitoring and management of your gateway.
+
+## Features
+- **Dashboard**: Real-time charts showing requests per second and error rates.
+- **Pool Monitoring**: Visual representation of database connection pool usage.
+- **Cache Management**: View and manage the metadata cache.
+- **Access & Error Logs**: Interactive viewers for the server logs.
+- **System Info**: Overview of the server environment and configuration.
+
+## Configuration
+The admin console is enabled by default in the `startServer` API. You can configure it via the `admin` property in the main configuration object.
+
+```typescript
+/**
+ * @typedef {object} configAdminType
+ * @property {boolean} [enabled=true] - Whether the admin console is enabled.
+ * @property {string} [route='/admin'] - The route path for the admin console.
+ */
+```
+
+Access the console at `http://localhost:<port>/admin` (e.g., `http://localhost:8080/admin`).
 
 # Configuration
 
@@ -93,6 +112,7 @@ The `startServer` api uses the following configuration object:
 /**
  * @typedef {object} configType
  * @property {number} port - The server port number.
+ * @property {configAdminType} [admin] - The admin console configuration.
  * @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.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "web_plsql",
-	"version": "0.17.1",
+	"version": "1.0.0",
 	"author": "Dieter Oberkofler <dieter.oberkofler@gmail.com>",
 	"license": "MIT",
 	"description": "The Express Middleware for Oracle PL/SQL",
@@ -43,12 +43,17 @@
 	"types": "./types/index.d.ts",
 	"type": "module",
 	"scripts": {
-		"lint": "prettier --check --experimental-cli . && eslint . && tsc --noEmit",
-		"test": "node --test --test-concurrency=1 \"./tests/**/*.test.js\"",
+		"build": "npm run build:admin",
+		"build:admin": "vite build",
+		"lint": "prettier --check --experimental-cli . && eslint . && tsc --noEmit && eslint src/admin --config src/admin/js/eslint.config.js",
+		"test": "vitest run",
+		"test:coverage": "vitest run --coverage",
+		"stylelint": "stylelint \"src/admin/**/*.css\"",
 		"types": "rm -rf types && tsc  --noEmit false --declaration true --declarationDir types --emitDeclarationOnly true --allowJs true --target es2020 --module es2020 --moduleResolution node --allowSyntheticDefaultImports true src/*.js",
 		"clean": "shx rm -f *.tgz && shx rm -f *.log",
-		"ci": "npm run clean && npm run version && npm run lint && npm run test && npm run types",
 		"version": "node update-version.js",
+		"prepack": "npm run ci",
+		"ci": "npm run clean && npm run version && npm run types && npm run build && npm run lint && npm run stylelint && npm run test:coverage",
 		"create-package": "shx rm -f *.tgz && npm pack",
 		"image-build": "docker build --no-cache --progress=plain --tag=web_plsql .",
 		"image-save": "docker save web_plsql | gzip > web_plsql.tar.gz"
@@ -57,6 +62,7 @@
 		"oracledb": "6.10.0"
 	},
 	"dependencies": {
+		"chart.js": "^4.5.1",
 		"compression": "1.8.1",
 		"cookie-parser": "1.4.7",
 		"debug": "4.4.3",
@@ -65,24 +71,31 @@
 		"morgan": "1.10.1",
 		"multer": "2.0.2",
 		"rotating-file-stream": "3.2.8",
-		"zod": "4.3.6"
+		"zod": "^4.3.6"
 	},
 	"devDependencies": {
+		"@tailwindcss/vite": "^4.1.18",
 		"@types/compression": "1.8.1",
 		"@types/cookie-parser": "1.4.10",
 		"@types/debug": "4.1.12",
 		"@types/morgan": "1.9.10",
 		"@types/multer": "2.0.0",
-		"@types/node": "25.2.0",
+		"@types/node": "25.2.1",
 		"@types/oracledb": "6.10.1",
 		"@types/supertest": "6.0.3",
+		"@vitest/coverage-v8": "^4.0.18",
 		"eslint": "9.39.2",
-		"eslint-plugin-jsdoc": "62.5.1",
+		"eslint-plugin-jsdoc": "62.5.3",
 		"oracledb": "6.10.0",
 		"prettier": "3.8.1",
 		"shx": "0.4.0",
+		"stylelint": "^17.1.1",
+		"stylelint-config-standard": "^40.0.0",
 		"supertest": "7.2.2",
+		"tailwindcss": "^4.1.18",
 		"typescript": "5.9.3",
-		"typescript-eslint": "8.54.0"
+		"typescript-eslint": "8.54.0",
+		"vite": "^7.3.1",
+		"vitest": "^4.0.18"
 	}
 }

package/src/admin/client/charts.ts

@@ -0,0 +1,299 @@
+import {Chart, registerables} from 'chart.js';
+import type {State, ChartInstance} from '../js/types.js';
+import type {StatusResponse} from '../js/schemas.js';
+
+// Register Chart.js components
+Chart.register(...registerables);
+
+/**
+ * Cache pie chart instances.
+ */
+const cachePieInstances = new Map<HTMLCanvasElement, Chart>();
+
+type PoolInfo = StatusResponse['pools'][number];
+
+/**
+ * Chart colors based on theme mode.
+ */
+type ChartColors = {
+	gridColor: string;
+	textColor: string;
+};
+
+/**
+ * Get chart colors for the current theme.
+ * @param isDark - Whether dark mode is active.
+ * @returns Chart color configuration.
+ */
+function getChartColors(isDark: boolean): ChartColors {
+	return {
+		gridColor: isDark ? 'rgba(255,255,255,0.1)' : 'rgba(0,0,0,0.1)',
+		textColor: isDark ? '#94a3b8' : '#475569',
+	};
+}
+
+/**
+ * Initialize charts.
+ * @param state - Application state.
+ */
+export function initCharts(state: State): void {
+	const isDark = document.body.classList.contains('dark');
+	const colors = getChartColors(isDark);
+
+	const trafficEl = document.getElementById('traffic-chart') as HTMLCanvasElement | null;
+	if (trafficEl) {
+		const chartData = {
+			labels: [],
+			datasets: [
+				{
+					label: 'Requests/s',
+					data: [],
+					borderColor: '#3b82f6',
+					backgroundColor: 'rgba(59, 130, 246, 0.1)',
+					fill: true,
+					tension: 0.4,
+					yAxisID: 'y',
+				},
+				{
+					label: 'Avg Response Time (ms)',
+					data: [],
+					borderColor: '#10b981',
+					backgroundColor: 'rgba(16, 185, 129, 0.1)',
+					fill: true,
+					tension: 0.4,
+					yAxisID: 'y1',
+				},
+			],
+		};
+
+		const chartOptions = {
+			responsive: true,
+			maintainAspectRatio: false,
+			scales: {
+				x: {
+					grid: {color: colors.gridColor},
+					ticks: {
+						color: colors.textColor,
+						maxRotation: 0,
+						autoSkip: true,
+						maxTicksLimit: 10,
+					},
+					title: {
+						display: true,
+						text: 'Time',
+						color: colors.textColor,
+					},
+				},
+				y: {
+					type: 'linear' as const,
+					display: true,
+					position: 'left' as const,
+					grid: {color: colors.gridColor},
+					ticks: {color: colors.textColor},
+					beginAtZero: true,
+					title: {
+						display: true,
+						text: 'Requests/s',
+						color: colors.textColor,
+					},
+				},
+				y1: {
+					type: 'linear' as const,
+					display: true,
+					position: 'right' as const,
+					grid: {drawOnChartArea: false, color: colors.gridColor},
+					ticks: {color: '#10b981'},
+					beginAtZero: true,
+					title: {
+						display: true,
+						text: 'Avg Response Time (ms)',
+						color: '#10b981',
+					},
+				},
+			},
+			plugins: {
+				legend: {
+					labels: {color: colors.textColor},
+				},
+			},
+		};
+
+		const chart = new Chart(trafficEl, {
+			type: 'line',
+			data: chartData,
+			options: chartOptions,
+		});
+
+		state.charts.traffic = {
+			data: chartData,
+			options: chartOptions,
+			update: () => chart.update(),
+		} as ChartInstance;
+	}
+
+	const poolEl = document.getElementById('pool-chart') as HTMLCanvasElement | null;
+	if (poolEl) {
+		const chartData = {
+			labels: [],
+			datasets: [],
+		};
+
+		const chartOptions = {
+			responsive: true,
+			maintainAspectRatio: false,
+			scales: {
+				x: {
+					grid: {color: colors.gridColor},
+					ticks: {
+						color: colors.textColor,
+						maxRotation: 0,
+						autoSkip: true,
+						maxTicksLimit: 10,
+					},
+					title: {
+						display: true,
+						text: 'Time',
+						color: colors.textColor,
+					},
+				},
+				y: {
+					grid: {color: colors.gridColor},
+					ticks: {color: colors.textColor},
+					beginAtZero: true,
+					title: {
+						display: true,
+						text: 'Connections',
+						color: colors.textColor,
+					},
+				},
+			},
+			plugins: {
+				legend: {
+					labels: {color: colors.textColor},
+				},
+			},
+		};
+
+		const chart = new Chart(poolEl, {
+			type: 'line',
+			data: chartData,
+			options: chartOptions,
+		});
+
+		state.charts.pool = {
+			data: chartData,
+			options: chartOptions,
+			update: () => chart.update(),
+		} as ChartInstance;
+	}
+}
+
+/**
+ * Update charts with new data.
+ * @param state - Application state.
+ * @param timeLabel - Time label for the data point.
+ * @param reqPerSec - Requests per second.
+ * @param avgResponseTime - Average response time in ms.
+ * @param pools - Pool information.
+ */
+export function updateCharts(state: State, timeLabel: string, reqPerSec: number, avgResponseTime: number, pools: PoolInfo[]): void {
+	const maxPoints = state.maxHistoryPoints;
+
+	state.history.labels.push(timeLabel);
+	state.history.requests.push(reqPerSec);
+	state.history.avgResponseTimes.push(avgResponseTime);
+
+	if (state.history.labels.length > maxPoints) {
+		state.history.labels.shift();
+		state.history.requests.shift();
+		state.history.avgResponseTimes.shift();
+	}
+
+	const trafficChart = state.charts.traffic;
+	if (trafficChart?.data.datasets[0] && trafficChart.data.datasets[1]) {
+		trafficChart.data.labels = state.history.labels;
+		trafficChart.data.datasets[0].data = state.history.requests;
+		trafficChart.data.datasets[1].data = state.history.avgResponseTimes;
+		trafficChart.update();
+	}
+
+	const poolChart = state.charts.pool;
+	if (poolChart) {
+		poolChart.data.labels = state.history.labels;
+		pools.forEach((p, i) => {
+			const poolName = p.name;
+			const history = state.history;
+			let usage = history.poolUsage[poolName];
+			if (!usage) {
+				usage = [];
+				history.poolUsage[poolName] = usage;
+				const colors = ['#10b981', '#f59e0b', '#3b82f6', '#8b5cf6', '#ec4899'];
+				const color = colors[i % colors.length];
+				if (color) {
+					poolChart.data.datasets.push({
+						label: poolName,
+						data: usage,
+						borderColor: color,
+						backgroundColor: undefined,
+						fill: undefined,
+						tension: 0.4,
+					});
+				}
+			}
+			usage.push(p.connectionsInUse);
+			if (usage.length > maxPoints) {
+				usage.shift();
+			}
+		});
+		poolChart.update();
+	}
+}
+
+/**
+ * Create or update a pie chart for cache statistics.
+ * @param canvas - The canvas element.
+ */
+export function renderCachePie(canvas: HTMLCanvasElement): void {
+	const hits = parseInt(canvas.dataset.hits ?? '0');
+	const misses = parseInt(canvas.dataset.misses ?? '0');
+
+	const existingChart = cachePieInstances.get(canvas);
+	if (existingChart?.data.datasets[0]) {
+		existingChart.data.datasets[0].data = [hits, misses];
+		existingChart.update();
+		return;
+	}
+
+	const chart = new Chart(canvas, {
+		type: 'pie',
+		data: {
+			labels: ['Hits', 'Misses'],
+			datasets: [
+				{
+					data: [hits, misses],
+					backgroundColor: ['#10b981', '#ef4444'],
+					borderColor: 'transparent',
+				},
+			],
+		},
+		options: {
+			responsive: true,
+			maintainAspectRatio: true,
+			plugins: {
+				legend: {display: false},
+				tooltip: {
+					callbacks: {
+						label: (context) => {
+							const value = context.raw as number;
+							const total = hits + misses;
+							const pct = total > 0 ? ((value / total) * 100).toFixed(1) : '0';
+							return `${context.label}: ${value} (${pct}%)`;
+						},
+					},
+				},
+			},
+		},
+	});
+
+	cachePieInstances.set(canvas, chart);
+}

package/src/admin/client/main.js

@@ -0,0 +1,3 @@
+import '../js/api.js';
+import '../js/app.js';
+import './tailwind.css';

package/src/admin/client/tailwind.css

@@ -0,0 +1,41 @@
+@import 'tailwindcss';
+
+@theme {
+	--color-primary: #3b82f6;
+	--color-success: #10b981;
+	--color-warning: #f59e0b;
+	--color-danger: #ef4444;
+}
+
+body {
+	font-family:
+		'Inter',
+		-apple-system,
+		BlinkMacSystemFont,
+		'Segoe UI',
+		Roboto,
+		Helvetica,
+		Arial,
+		sans-serif;
+	-webkit-font-smoothing: antialiased;
+}
+
+body.dark {
+	--bg-main: #0f172a;
+	--bg-side: #1e293b;
+	--bg-card: #1e293b;
+	--bg-hover: #334155;
+	--text-main: #94a3b8;
+	--text-bright: #f8fafc;
+	--border: #334155;
+}
+
+body:not(.dark) {
+	--bg-main: #f8fafc;
+	--bg-side: #ffffff;
+	--bg-card: #ffffff;
+	--bg-hover: #f1f5f9;
+	--text-main: #475569;
+	--text-bright: #0f172a;
+	--border: #e2e8f0;
+}

package/src/admin/favicon.svg

@@ -0,0 +1,3 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="#3b82f6">
+  <path d="M12 2C6.48 2 2 4.02 2 6.5s4.48 4.5 10 4.5 10-2.02 10-4.5S17.52 2 12 2zm0 13c-5.52 0-10-2.02-10-4.5V14c0 2.48 4.48 4.5 10 4.5s10-2.02 10-4.5v-3.5c0 2.48-4.48 4.5-10 4.5zm0 4.5c-5.52 0-10-2.02-10-4.5V19c0 2.48 4.48 4.5 10 4.5s10-2.02 10-4.5v-2.5c0 2.48-4.48 4.5-10 4.5z"/>
+</svg>