@zyno-io/dk-server-foundation 26.216.430

package/docs/content/worker.md

@@ -0,0 +1,177 @@
+# Workers
+
+Background job processing using BullMQ with Redis. Jobs are defined as classes, automatically discovered, and executed by a worker runner with full dependency injection.
+
+## Setup
+
+Enable the worker system in `createApp()`:
+
+```typescript
+const app = createApp({
+    config: AppConfig,
+    db: AppDB,
+    enableWorker: true
+});
+```
+
+This registers the job runner, queue registry, and CLI commands. In development, the runner auto-starts. In production, it's controlled via the `ENABLE_JOB_RUNNER` environment variable.
+
+## Defining Jobs
+
+```typescript
+import { BaseJob, WorkerJob } from '@zyno-io/dk-server-foundation';
+
+@WorkerJob()
+class SendEmailJob extends BaseJob<{ to: string; subject: string; body: string }> {
+    async handle(data) {
+        await emailProvider.send(data.to, data.subject, data.body);
+    }
+}
+```
+
+### With Return Values
+
+```typescript
+@WorkerJob()
+class ProcessImageJob extends BaseJob<{ url: string }, { width: number; height: number }> {
+    async handle(data) {
+        const result = await processImage(data.url);
+        return { width: result.width, height: result.height };
+    }
+}
+```
+
+### Cron Jobs
+
+```typescript
+@WorkerJob()
+class DailyCleanupJob extends BaseJob {
+    static CRON_SCHEDULE = '0 0 * * *'; // Midnight daily
+
+    async handle() {
+        await cleanupExpiredSessions();
+    }
+}
+```
+
+### Custom Queue
+
+```typescript
+@WorkerJob()
+class HighPriorityJob extends BaseJob<{ data: string }> {
+    static QUEUE_NAME = 'high-priority';
+
+    async handle(data) {
+        // Processed by a separate queue
+    }
+}
+```
+
+## `BaseJob<I, O>`
+
+Abstract base class for all jobs.
+
+| Static Property | Type             | Default     | Description                         |
+| --------------- | ---------------- | ----------- | ----------------------------------- |
+| `QUEUE_NAME`    | `string`         | `'default'` | BullMQ queue name                   |
+| `CRON_SCHEDULE` | `string \| null` | `null`      | Cron expression for repeatable jobs |
+
+| Method                        | Description                                                           |
+| ----------------------------- | --------------------------------------------------------------------- |
+| `handle(data: I): Promise<O>` | Job execution logic. Receives the queued data and returns the result. |
+
+## Queueing Jobs
+
+```typescript
+import { WorkerService } from '@zyno-io/dk-server-foundation';
+
+class OrderService {
+    constructor(private workerSvc: WorkerService) {}
+
+    async createOrder(order: Order) {
+        // ... create order ...
+
+        // Queue email notification
+        await this.workerSvc.queueJob(SendEmailJob, {
+            to: order.email,
+            subject: 'Order Confirmation',
+            body: `Your order #${order.id} has been placed.`
+        });
+    }
+}
+```
+
+### Queue Options
+
+```typescript
+await workerSvc.queueJob(SendEmailJob, data, {
+    delay: 5000, // Delay execution by 5 seconds
+    priority: 1, // Lower number = higher priority
+    attempts: 3, // Retry up to 3 times on failure
+    backoff: {
+        // Backoff strategy for retries
+        type: 'exponential',
+        delay: 1000
+    },
+    jobId: 'unique-id' // Deduplicate by job ID
+});
+```
+
+### Jest Environment
+
+In Jest, jobs are **not queued** -- `queueJob()` is a no-op. This prevents background job side effects during testing.
+
+## Worker Runner
+
+The `WorkerRunnerService` discovers all `@WorkerJob()` decorated classes, registers cron schedules, and processes jobs with full Deepkit dependency injection.
+
+### Starting Manually
+
+```bash
+# Via CLI
+node app.js worker:start
+```
+
+### Auto-Start (Development)
+
+In development, the runner starts automatically if `ENABLE_JOB_RUNNER` is not explicitly set to `false`.
+
+## Job Recorder
+
+The `WorkerRecorderService` monitors BullMQ queue events and logs job lifecycle to the `_jobs` database table. It tracks:
+
+- Job added, active, completed, failed
+- Execution duration
+- Error messages for failed jobs
+
+The `_jobs` table is created automatically if it doesn't exist.
+
+### Leader Election
+
+The recorder uses `LeaderService` (Redis-based leader election) so that when multiple runner instances are deployed, only one of them acts as the recorder at any given time. If the current recorder goes down, another runner automatically takes over recording duties. This eliminates the need for a separate observer process.
+
+## Queue Registry
+
+The `WorkerQueueRegistry` manages BullMQ queue instances as singletons:
+
+```typescript
+import { WorkerQueueRegistry } from '@zyno-io/dk-server-foundation';
+
+const queue = WorkerQueueRegistry.getQueue('default');
+const defaultQueue = WorkerQueueRegistry.getDefaultQueue();
+
+// Cleanup on shutdown
+await WorkerQueueRegistry.closeQueues();
+```
+
+## Configuration
+
+| Variable            | Type      | Default      | Description           |
+| ------------------- | --------- | ------------ | --------------------- |
+| `BULL_REDIS_HOST`   | `string`  | —            | Redis host for BullMQ |
+| `BULL_REDIS_PORT`   | `number`  | —            | Redis port for BullMQ |
+| `BULL_REDIS_PREFIX` | `string`  | —            | Redis key prefix      |
+| `BULL_QUEUE`        | `string`  | `default`    | Default queue name    |
+| `ENABLE_JOB_RUNNER` | `boolean` | `true` (dev) | Enable job runner     |
+
+Falls back to default `REDIS_*` settings if `BULL_REDIS_*` is not set.

package/docs/package.json

@@ -0,0 +1,16 @@
+{
+    "name": "@zyno-io/dk-server-foundation-docs",
+    "private": true,
+    "scripts": {
+        "dev": "vitepress dev",
+        "build": "vitepress build",
+        "preview": "vitepress preview",
+        "screenshots": "node scripts/capture-devconsole-screenshots.js",
+        "screenshots:headless": "node scripts/capture-devconsole-screenshots.js --headless"
+    },
+    "devDependencies": {
+        "playwright": "^1.58.2",
+        "vitepress": "^1.6.4",
+        "vue": "^3.5.28"
+    }
+}

package/docs/scripts/README-SCREENSHOTS.md

@@ -0,0 +1,145 @@
+# DevConsole Screenshot Capture
+
+This directory contains a script to capture DevConsole screenshots for documentation.
+
+## Prerequisites
+
+1. **Install dependencies** (if not already done):
+   ```bash
+   cd docs && yarn install
+   ```
+
+2. **Install Playwright browsers**:
+   ```bash
+   cd docs && npx playwright install chromium
+   ```
+
+3. **Ensure services are running**:
+   - MySQL server
+   - Redis server
+
+## Usage
+
+### Step 1: Start the Demo Application
+
+In one terminal window, start the demoapp:
+
+```bash
+yarn demoapp
+```
+
+Wait for the output to show:
+```
+DevConsole:  http://localhost:3000/_devconsole/
+Server started.
+```
+
+### Step 2: Run the Screenshot Capture Script
+
+In another terminal window, run:
+
+```bash
+yarn screenshots
+```
+
+This will:
+- Open a Chromium browser (visible by default)
+- Navigate through all 10 DevConsole views in order
+- Wait for each page to load completely
+- Capture full-page screenshots
+- Save them to `docs/content/public/images/devconsole/`
+
+### Options
+
+```bash
+# Run in headless mode (faster, no visible browser)
+yarn screenshots:headless
+
+# Use custom URL
+yarn screenshots --url http://localhost:3001/_devconsole
+
+# Use custom output directory
+yarn screenshots --output ./screenshots
+
+# Custom wait time between navigations (in milliseconds)
+yarn screenshots --wait 3000
+```
+
+## Screenshots Captured
+
+The script captures all DevConsole views in navigation order:
+
+1. **01-dashboard.png** - Dashboard with app metrics
+2. **02-routes.png** - HTTP Routes listing
+3. **03-openapi.png** - OpenAPI Schema viewer
+4. **04-requests.png** - HTTP Request detail drill-down
+5. **05-srpc.png** - SRPC message request/response detail
+6. **06-database.png** - Database query results
+7. **07-health.png** - Health checks status
+8. **08-mutex.png** - Mutex monitor
+9. **09-repl.png** - Interactive REPL
+10. **10-workers.png** - Workers/BullMQ monitor
+
+## Troubleshooting
+
+### "Connection refused" or "Navigation timeout"
+
+Make sure the demoapp is running:
+```bash
+yarn demoapp
+```
+
+Check that you can access http://localhost:3000/_devconsole in your browser.
+
+### Browser not found
+
+Install Playwright browsers:
+```bash
+npx playwright install chromium
+```
+
+### Screenshots are blank or incomplete
+
+Increase the wait time:
+```bash
+yarn screenshots --wait 8000
+```
+
+### MySQL or Redis connection errors
+
+Ensure MySQL and Redis services are running:
+```bash
+# MySQL
+sudo service mysql start
+
+# Redis
+sudo service redis-server start
+```
+
+## Manual Verification
+
+After running the script, verify the screenshots:
+
+1. Open `docs/content/public/images/devconsole/` directory
+2. Check that all 10 PNG files exist
+3. Open each image to verify:
+   - Correct view is captured
+   - Page is fully loaded
+   - No loading spinners visible
+   - Content is clearly visible
+
+## Rebuilding Documentation
+
+After capturing new screenshots, rebuild the docs:
+
+```bash
+yarn docs:build
+```
+
+Then preview locally:
+
+```bash
+yarn docs:preview
+```
+
+Open http://localhost:4173/dk-server-foundation/ to verify the documentation site with new screenshots.

package/docs/scripts/capture-devconsole-screenshots.js

@@ -0,0 +1,184 @@
+#!/usr/bin/env node
+/* eslint-disable @typescript-eslint/no-require-imports */
+
+/**
+ * DevConsole Screenshot Capture Script
+ *
+ * This script uses Playwright to capture screenshots of all DevConsole views
+ * in the correct navigation order with proper wait times.
+ *
+ * Prerequisites:
+ * 1. Install dependencies: cd docs && yarn install
+ * 2. Install browsers: cd docs && npx playwright install chromium
+ * 3. Start the demoapp: yarn demoapp
+ * 4. Wait for the server to be ready (check console output)
+ *
+ * Usage:
+ *   yarn screenshots [-- options]
+ *
+ * Options:
+ *   --url <url>       DevConsole URL (default: http://localhost:3000/_devconsole)
+ *   --output <dir>    Output directory (default: public/images/devconsole)
+ *   --wait <ms>       Wait time between navigations (default: 5000)
+ *   --headless        Run in headless mode (default: false for visibility)
+ */
+
+const { chromium } = require('playwright');
+const path = require('path');
+const fs = require('fs');
+
+// Parse command line arguments
+const args = process.argv.slice(2);
+const getArg = (name, defaultValue) => {
+    const index = args.indexOf(name);
+    return index !== -1 && args[index + 1] ? args[index + 1] : defaultValue;
+};
+
+const config = {
+    baseUrl: getArg('--url', 'http://localhost:3000/_devconsole'),
+    outputDir: getArg('--output', path.join(__dirname, '..', 'content', 'public', 'images', 'devconsole')),
+    waitTime: parseInt(getArg('--wait', '5000')),
+    headless: args.includes('--headless')
+};
+
+// DevConsole views in navigation order
+const views = [
+    { name: 'Dashboard', path: '#/', filename: '01-dashboard.png' },
+    { name: 'Routes', path: '#/routes', filename: '02-routes.png' },
+    { name: 'OpenAPI', path: '#/openapi', filename: '03-openapi.png' },
+    { name: 'Requests', path: '#/requests', filename: '04-requests.png', action: 'clickFirst' },
+    { name: 'SRPC', path: '#/srpc', filename: '05-srpc.png', action: 'clickFirstThenMessage' },
+    { name: 'Database', path: '#/database?table=notes', filename: '06-database.png', action: 'clickNotes' },
+    { name: 'Health', path: '#/health', filename: '07-health.png' },
+    { name: 'Mutex', path: '#/mutex', filename: '08-mutex.png' },
+    { name: 'REPL', path: '#/repl', filename: '09-repl.png' },
+    { name: 'Workers', path: '#/workers', filename: '10-workers.png' }
+];
+
+async function waitForDevConsole(page) {
+    // Wait for DevConsole to be fully loaded
+    await page.waitForSelector('text=DevConsole', { timeout: 30000 });
+    await page.waitForLoadState('networkidle');
+}
+
+async function captureScreenshot(page, view, outputPath) {
+    console.log(`📸 Capturing: ${view.name}`);
+
+    // Navigate to the view
+    const url = `${config.baseUrl}${view.path}`;
+    await page.goto(url, { waitUntil: 'networkidle' });
+
+    // Wait for the page to stabilize
+    await page.waitForTimeout(config.waitTime);
+
+    // Handle special actions
+    if (view.action === 'clickFirst') {
+        // Click on the first row in a table to show detail view
+        try {
+            const firstRow = await page.locator('table tbody tr').first();
+            if (await firstRow.isVisible()) {
+                await firstRow.click();
+                await page.waitForTimeout(3000);
+            }
+        } catch {
+            console.warn(`  ⚠️  Could not click first row for ${view.name}`);
+        }
+    } else if (view.action === 'clickFirstThenMessage') {
+        // Click on the first connection row, then click the first message
+        try {
+            const firstRow = await page.locator('.srpc-top table tbody tr.clickable-row').first();
+            if (await firstRow.isVisible()) {
+                await firstRow.click();
+                await page.waitForTimeout(2000);
+                const firstMsg = await page.locator('.messages-list table tbody tr.clickable-row').first();
+                if (await firstMsg.isVisible()) {
+                    await firstMsg.click();
+                    await page.waitForTimeout(2000);
+                }
+            }
+        } catch {
+            console.warn(`  ⚠️  Could not click connection/message for ${view.name}`);
+        }
+    } else if (view.action === 'clickNotes') {
+        // Click on notes entity in database view
+        try {
+            const notesEntity = await page.locator('text=notes').last();
+            if (await notesEntity.isVisible()) {
+                await notesEntity.click();
+                await page.waitForTimeout(3000);
+            }
+        } catch {
+            console.warn(`  ⚠️  Could not click notes entity for ${view.name}`);
+        }
+    }
+
+    // Take full page screenshot
+    await page.screenshot({
+        path: outputPath,
+        fullPage: true,
+        type: 'png'
+    });
+
+    console.log(`  ✅ Saved to: ${outputPath}`);
+}
+
+async function main() {
+    console.log('🚀 DevConsole Screenshot Capture Script');
+    console.log('========================================');
+    console.log(`Base URL: ${config.baseUrl}`);
+    console.log(`Output Directory: ${config.outputDir}`);
+    console.log(`Wait Time: ${config.waitTime}ms`);
+    console.log(`Headless: ${config.headless}`);
+    console.log('');
+
+    // Ensure output directory exists
+    if (!fs.existsSync(config.outputDir)) {
+        fs.mkdirSync(config.outputDir, { recursive: true });
+        console.log(`📁 Created output directory: ${config.outputDir}`);
+    }
+
+    // Launch browser
+    console.log('🌐 Launching browser...');
+    const browser = await chromium.launch({
+        headless: config.headless,
+        args: ['--no-sandbox']
+    });
+
+    const context = await browser.newContext({
+        viewport: { width: 1280, height: 800 },
+        deviceScaleFactor: 1
+    });
+
+    const page = await context.newPage();
+
+    try {
+        // Navigate to DevConsole
+        console.log('📍 Navigating to DevConsole...');
+        await page.goto(config.baseUrl, { waitUntil: 'networkidle' });
+        await waitForDevConsole(page);
+        console.log('✅ DevConsole loaded successfully\n');
+
+        // Capture each view
+        for (const view of views) {
+            const outputPath = path.join(config.outputDir, view.filename);
+            await captureScreenshot(page, view, outputPath);
+
+            // Brief pause between captures
+            await page.waitForTimeout(1000);
+        }
+
+        console.log('\n🎉 All screenshots captured successfully!');
+        console.log(`📁 Screenshots saved to: ${config.outputDir}`);
+    } catch (error) {
+        console.error('❌ Error capturing screenshots:', error);
+        throw error;
+    } finally {
+        await browser.close();
+    }
+}
+
+// Run the script
+main().catch(error => {
+    console.error('Fatal error:', error);
+    process.exit(1);
+});