@qwickapps/server 1.6.0 → 1.7.0

package/src/plugins/logs/API_ROUTES.md

@@ -0,0 +1,297 @@
+# Logs Plugin API Routes
+
+This document describes the API routes needed to support the LogsStatusWidget and LogsManagementPage UI components.
+
+## Routes to Add
+
+Most routes are already implemented in the logs plugin. These notes document their usage and any additional routes needed.
+
+### 1. GET /api/plugins/logs/stats
+
+Returns log statistics for the current source.
+
+**Query Parameters:**
+- `source` - Log source name (default: 'app')
+
+**Response:**
+```typescript
+{
+  totalLogs: number;
+  byLevel: {
+    debug: number;
+    info: number;
+    warn: number;
+    error: number;
+  };
+  fileSize: number;
+  fileSizeFormatted: string;
+  oldestLog: string | null;
+  newestLog: string | null;
+}
+```
+
+**Note:** This endpoint is already implemented in the logs plugin at `/logs/stats`. The UI calls it at `/api/plugins/logs/stats`.
+
+### 2. GET /api/plugins/logs/sources
+
+Returns available log sources.
+
+**Response:**
+```typescript
+{
+  sources: Array<{
+    name: string;
+    type: string;       // "file" or "api"
+  }>;
+}
+```
+
+**Note:** Already implemented at `/logs/sources`. UI calls it at `/api/plugins/logs/sources`.
+
+### 3. GET /api/plugins/logs
+
+Returns log entries with optional filtering.
+
+**Query Parameters:**
+- `source` - Source name (default: first source)
+- `limit` - Max entries to return (default: 100, max: 10000)
+- `offset` - Pagination offset (default: 0)
+- `level` - Filter by log level (debug, info, warn, error)
+- `search` - Search query to filter messages
+- `order` - Sort order ('asc' or 'desc', default: 'desc')
+
+**Response:**
+```typescript
+{
+  logs: Array<{
+    id: number;
+    level: string;
+    timestamp: string;
+    namespace: string;
+    message: string;
+    [key: string]: unknown;  // Additional fields from JSON logs
+  }>;
+  total: number;
+}
+```
+
+**Note:** Already implemented at `/logs`. UI calls it at `/api/plugins/logs`.
+
+### 4. GET /api/plugins/logs/download
+
+Downloads the full log file.
+
+**Query Parameters:**
+- `source` - Source name
+
+**Response:**
+- Content-Type: text/plain
+- Content-Disposition: attachment
+
+**Implementation:**
+```typescript
+app.get('/api/plugins/logs/download', (req, res) => {
+  const sources = getSources();
+  const sourceName = (req.query.source as string) || sources[0]?.name;
+  const source = sources.find((s) => s.name === sourceName);
+
+  if (!source || source.type !== 'file' || !source.path) {
+    return res.status(404).json({ error: 'Source not found or not a file' });
+  }
+
+  const resolvedPath = resolve(source.path);
+  if (!existsSync(resolvedPath)) {
+    return res.status(404).json({ error: 'Log file not found' });
+  }
+
+  res.download(resolvedPath, `${sourceName}.log`);
+});
+```
+
+### 5. DELETE /api/plugins/logs/clear
+
+Clears (truncates) a log file.
+
+**Query Parameters:**
+- `source` - Source name
+
+**Response:**
+```typescript
+{
+  success: boolean;
+  message: string;
+}
+```
+
+**Implementation:**
+```typescript
+app.delete('/api/plugins/logs/clear', (req, res) => {
+  const sources = getSources();
+  const sourceName = (req.query.source as string) || sources[0]?.name;
+  const source = sources.find((s) => s.name === sourceName);
+
+  if (!source || source.type !== 'file' || !source.path) {
+    return res.status(404).json({ error: 'Source not found or not a file' });
+  }
+
+  const resolvedPath = resolve(source.path);
+  if (!existsSync(resolvedPath)) {
+    return res.status(404).json({ error: 'Log file not found' });
+  }
+
+  try {
+    writeFileSync(resolvedPath, '');
+    res.json({ success: true, message: `Cleared ${sourceName} log` });
+  } catch (err) {
+    res.status(500).json({ success: false, message: err.message });
+  }
+});
+```
+
+### 6. GET /api/plugins/logs/tail
+
+Real-time log tailing (server-sent events).
+
+**Query Parameters:**
+- `source` - Source name
+- `level` - Filter by level
+
+**Response:**
+- Content-Type: text/event-stream
+- SSE stream of log entries
+
+**Implementation:**
+```typescript
+import { watch } from 'fs';
+
+app.get('/api/plugins/logs/tail', (req, res) => {
+  const sources = getSources();
+  const sourceName = (req.query.source as string) || sources[0]?.name;
+  const levelFilter = req.query.level as string;
+  const source = sources.find((s) => s.name === sourceName);
+
+  if (!source || source.type !== 'file' || !source.path) {
+    return res.status(404).json({ error: 'Source not found or not a file' });
+  }
+
+  const resolvedPath = resolve(source.path);
+
+  // Set SSE headers
+  res.setHeader('Content-Type', 'text/event-stream');
+  res.setHeader('Cache-Control', 'no-cache');
+  res.setHeader('Connection', 'keep-alive');
+
+  // Watch file for changes
+  const watcher = watch(resolvedPath, (eventType) => {
+    if (eventType === 'change') {
+      // Read last line
+      const content = readFileSync(resolvedPath, 'utf-8');
+      const lines = content.split('\n').filter((l) => l.trim());
+      const lastLine = lines[lines.length - 1];
+
+      if (lastLine) {
+        try {
+          const log = JSON.parse(lastLine);
+          if (!levelFilter || log.level === levelFilter) {
+            res.write(`data: ${JSON.stringify(log)}\n\n`);
+          }
+        } catch (err) {
+          // Not JSON, send raw line
+          res.write(`data: ${JSON.stringify({ message: lastLine })}\n\n`);
+        }
+      }
+    }
+  });
+
+  req.on('close', () => {
+    watcher.close();
+  });
+});
+```
+
+## Integration with Plugin
+
+These routes should be registered in the `onGatewayReady` hook:
+
+```typescript
+async onGatewayReady(app: Express): Promise<void> {
+  // Existing routes are already at /logs/*
+  // Add API prefix versions for UI:
+  app.get('/api/plugins/logs/stats', (req, res) => {
+    // Proxy to /logs/stats
+  });
+  app.get('/api/plugins/logs/sources', (req, res) => {
+    // Proxy to /logs/sources
+  });
+  app.get('/api/plugins/logs', (req, res) => {
+    // Proxy to /logs
+  });
+
+  // New routes:
+  app.get('/api/plugins/logs/download', ...);
+  app.delete('/api/plugins/logs/clear', ...);
+  app.get('/api/plugins/logs/tail', ...);
+}
+```
+
+## Widget Registration
+
+The plugin should also register its status widget and management page:
+
+```typescript
+async onGatewayReady(app: Express): Promise<void> {
+  // Register API routes (see above)
+
+  // Register control panel UI
+  registry.registerWidget({
+    id: 'logs-status',
+    title: 'Application Logs',
+    component: 'LogsStatusWidget',
+    props: { apiPrefix: '/api/plugins/logs' },
+    order: 40,
+  });
+
+  registry.registerPage({
+    path: '/cpanel/plugins/logs',
+    title: 'Application Logs',
+    component: 'LogsManagementPage',
+    props: { apiPrefix: '/api/plugins/logs' },
+  });
+}
+```
+
+## Log Parsing
+
+The logs plugin expects JSON-formatted log entries with this structure:
+
+```json
+{
+  "level": "info",
+  "timestamp": "2025-12-26T12:00:00.000Z",
+  "namespace": "app",
+  "message": "Server started",
+  "extra": "field"
+}
+```
+
+For plain text logs, each line is wrapped in a log entry object.
+
+## Performance Considerations
+
+1. **Large Files**: Limit results to avoid reading entire file
+2. **File Watching**: Use efficient file watching for tail feature
+3. **Memory**: Stream large file downloads instead of loading into memory
+4. **Caching**: Consider caching recent logs in memory
+5. **Rotation**: Coordinate with log rotation to avoid missing entries
+
+## Security Considerations
+
+1. **Path Traversal**: Always resolve and validate file paths
+2. **Authentication**: Require authentication for all log endpoints
+3. **Sensitive Data**: Never log sensitive information (passwords, tokens)
+4. **Download Limits**: Rate limit log downloads
+5. **Clear Permission**: Require elevated permissions to clear logs
+
+---
+
+Copyright (c) 2025 QwickApps.com. All rights reserved.

package/src/plugins/logs/LogsManagementPage.test.tsx

@@ -0,0 +1,58 @@
+/**
+ * LogsManagementPage Tests
+ *
+ * Copyright (c) 2025 QwickApps.com. All rights reserved.
+ */
+
+import { describe, it, expect, beforeEach, vi } from 'vitest';
+import { render, screen, waitFor } from '@testing-library/react';
+import { LogsManagementPage } from './LogsManagementPage';
+
+describe('LogsManagementPage', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it('renders page title', () => {
+    (global.fetch as ReturnType<typeof vi.fn>).mockImplementation(
+      () => Promise.resolve({
+        ok: true,
+        json: async () => ([]),
+      })
+    );
+
+    render(<LogsManagementPage apiPrefix="/api/logs" />);
+
+    expect(screen.getByText('Application Logs')).toBeInTheDocument();
+  });
+
+  it('fetches logs on mount', async () => {
+    (global.fetch as ReturnType<typeof vi.fn>).mockImplementation(
+      () => Promise.resolve({
+        ok: true,
+        json: async () => ([]),
+      })
+    );
+
+    render(<LogsManagementPage apiPrefix="/api/logs" />);
+
+    await waitFor(() => {
+      expect(global.fetch).toHaveBeenCalled();
+    });
+  });
+
+  it('renders all tabs', () => {
+    (global.fetch as ReturnType<typeof vi.fn>).mockImplementation(
+      () => Promise.resolve({
+        ok: true,
+        json: async () => ([]),
+      })
+    );
+
+    render(<LogsManagementPage apiPrefix="/api/logs" />);
+
+    expect(screen.getByRole('tab', { name: /All Logs/i })).toBeInTheDocument();
+    expect(screen.getByRole('tab', { name: /Errors/i })).toBeInTheDocument();
+    expect(screen.getByRole('tab', { name: /Warnings/i })).toBeInTheDocument();
+  });
+});

package/src/plugins/logs/LogsManagementPage.tsx

@@ -0,0 +1,283 @@
+/**
+ * Logs Management Page Component
+ * Full log viewer with filtering, searching, and source selection
+ *
+ * Copyright (c) 2025 QwickApps.com. All rights reserved.
+ */
+
+import React, { useEffect, useState } from 'react';
+import { PluginManagementPage } from '@qwickapps/server/ui';
+import { DataTable, StatCard, type Column } from '@qwickapps/react-framework';
+
+export interface LogsManagementPageProps {
+  apiPrefix?: string;
+}
+
+interface LogEntry {
+  id: number;
+  level: string;
+  timestamp: string;
+  namespace: string;
+  message: string;
+  [key: string]: unknown;
+}
+
+interface LogSource {
+  name: string;
+  type: string;
+}
+
+interface LogStats {
+  totalLogs: number;
+  byLevel: {
+    debug: number;
+    info: number;
+    warn: number;
+    error: number;
+  };
+  fileSize: number;
+  fileSizeFormatted: string;
+  oldestLog: string | null;
+  newestLog: string | null;
+}
+
+export const LogsManagementPage: React.FC<LogsManagementPageProps> = ({
+  apiPrefix = '/api/plugins/logs',
+}) => {
+  const [logs, setLogs] = useState<LogEntry[]>([]);
+  const [sources, setSources] = useState<LogSource[]>([]);
+  const [stats, setStats] = useState<LogStats | null>(null);
+  const [selectedSource, setSelectedSource] = useState<string>('app');
+  const [levelFilter, setLevelFilter] = useState<string>('');
+  const [searchQuery, setSearchQuery] = useState<string>('');
+  const [loading, setLoading] = useState(true);
+  const [autoRefresh, setAutoRefresh] = useState(false);
+
+  const fetchSources = async () => {
+    try {
+      const response = await fetch(`${apiPrefix}/sources`);
+      if (response.ok) {
+        const data = await response.json();
+        setSources(data.sources);
+        if (data.sources.length > 0 && !selectedSource) {
+          setSelectedSource(data.sources[0].name);
+        }
+      }
+    } catch (err) {
+      console.error('Failed to fetch sources:', err);
+    }
+  };
+
+  const fetchLogs = async () => {
+    try {
+      const params = new URLSearchParams({
+        source: selectedSource,
+        limit: '100',
+      });
+
+      if (levelFilter) params.append('level', levelFilter);
+      if (searchQuery) params.append('search', searchQuery);
+
+      const response = await fetch(`${apiPrefix}?${params}`);
+      if (response.ok) {
+        const data = await response.json();
+        setLogs(data.logs || []);
+      }
+    } catch (err) {
+      console.error('Failed to fetch logs:', err);
+    } finally {
+      setLoading(false);
+    }
+  };
+
+  const fetchStats = async () => {
+    try {
+      const response = await fetch(`${apiPrefix}/stats?source=${selectedSource}`);
+      if (response.ok) {
+        const data = await response.json();
+        setStats(data);
+      }
+    } catch (err) {
+      console.error('Failed to fetch stats:', err);
+    }
+  };
+
+  useEffect(() => {
+    fetchSources();
+  }, [apiPrefix]);
+
+  useEffect(() => {
+    if (selectedSource) {
+      fetchLogs();
+      fetchStats();
+    }
+  }, [selectedSource, levelFilter, searchQuery]);
+
+  useEffect(() => {
+    if (autoRefresh) {
+      const interval = setInterval(() => {
+        fetchLogs();
+        fetchStats();
+      }, 5000);
+      return () => clearInterval(interval);
+    }
+  }, [autoRefresh, selectedSource, levelFilter, searchQuery]);
+
+  const getLevelColor = (level: string) => {
+    switch (level.toLowerCase()) {
+      case 'error':
+        return 'bg-red-100 dark:bg-red-900 text-red-800 dark:text-red-200';
+      case 'warn':
+        return 'bg-yellow-100 dark:bg-yellow-900 text-yellow-800 dark:text-yellow-200';
+      case 'info':
+        return 'bg-blue-100 dark:bg-blue-900 text-blue-800 dark:text-blue-200';
+      case 'debug':
+        return 'bg-gray-100 dark:bg-gray-700 text-gray-800 dark:text-gray-200';
+      default:
+        return 'bg-gray-100 dark:bg-gray-700 text-gray-800 dark:text-gray-200';
+    }
+  };
+
+  const logColumns: Column<LogEntry>[] = [
+    {
+      key: 'timestamp',
+      label: 'Time',
+      sortable: true,
+      render: (_value, row) => {
+        const date = new Date(row.timestamp);
+        return (
+          <span className="text-sm text-gray-600 dark:text-gray-400">
+            {date.toLocaleTimeString()}
+          </span>
+        );
+      },
+    },
+    {
+      key: 'level',
+      label: 'Level',
+      sortable: true,
+      render: (_value, row) => (
+        <span className={`inline-block px-2 py-1 rounded text-xs font-medium ${getLevelColor(row.level)}`}>
+          {row.level.toUpperCase()}
+        </span>
+      ),
+    },
+    {
+      key: 'namespace',
+      label: 'Namespace',
+      sortable: true,
+      render: (_value, row) => (
+        <code className="text-sm text-gray-900 dark:text-gray-100">{row.namespace}</code>
+      ),
+    },
+    {
+      key: 'message',
+      label: 'Message',
+      render: (_value, row) => (
+        <span className="text-sm text-gray-900 dark:text-gray-100">{row.message}</span>
+      ),
+    },
+  ];
+
+  return (
+    <PluginManagementPage
+      title="Application Logs"
+      description="View and filter application logs from various sources"
+      breadcrumbs={[
+        { label: 'Control Panel', href: '/cpanel' },
+        { label: 'Plugins', href: '/cpanel/plugins' },
+        { label: 'Logs' },
+      ]}
+      loading={loading}
+      searchPlaceholder="Search logs..."
+      onSearch={(query) => setSearchQuery(query)}
+      actions={[
+        {
+          label: autoRefresh ? 'Stop Auto-Refresh' : 'Auto-Refresh',
+          onClick: () => setAutoRefresh(!autoRefresh),
+          variant: autoRefresh ? 'danger' : 'secondary',
+        },
+        {
+          label: 'Refresh',
+          onClick: () => {
+            fetchLogs();
+            fetchStats();
+          },
+          variant: 'secondary',
+        },
+      ]}
+      filters={
+        <div className="flex gap-4">
+          {/* Source Selector */}
+          <select
+            value={selectedSource}
+            onChange={(e) => setSelectedSource(e.target.value)}
+            className="px-3 py-2 border border-gray-300 dark:border-gray-600 rounded bg-white dark:bg-gray-800 text-gray-900 dark:text-gray-100"
+          >
+            {sources.map((source) => (
+              <option key={source.name} value={source.name}>
+                {source.name} ({source.type})
+              </option>
+            ))}
+          </select>
+
+          {/* Level Filter */}
+          <select
+            value={levelFilter}
+            onChange={(e) => setLevelFilter(e.target.value)}
+            className="px-3 py-2 border border-gray-300 dark:border-gray-600 rounded bg-white dark:bg-gray-800 text-gray-900 dark:text-gray-100"
+          >
+            <option value="">All Levels</option>
+            <option value="error">Error</option>
+            <option value="warn">Warning</option>
+            <option value="info">Info</option>
+            <option value="debug">Debug</option>
+          </select>
+        </div>
+      }
+    >
+      {/* Stats Summary */}
+      {stats && (
+        <div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-5 gap-4 mb-6">
+          <StatCard
+            label="Total Logs"
+            value={stats.totalLogs}
+            status="info"
+          />
+          <StatCard
+            label="Errors"
+            value={stats.byLevel.error}
+            status={stats.byLevel.error > 0 ? 'error' : 'healthy'}
+          />
+          <StatCard
+            label="Warnings"
+            value={stats.byLevel.warn}
+            status={stats.byLevel.warn > 0 ? 'warning' : 'healthy'}
+          />
+          <StatCard
+            label="Info"
+            value={stats.byLevel.info}
+            status="info"
+          />
+          <StatCard
+            label="File Size"
+            value={stats.fileSizeFormatted}
+            status="info"
+          />
+        </div>
+      )}
+
+      {/* Logs Table */}
+      <div className="bg-white dark:bg-gray-800 rounded-lg shadow">
+        <DataTable
+          columns={logColumns}
+          data={logs}
+          emptyMessage="No logs found"
+          getRowKey={(row) => row.id}
+        />
+      </div>
+    </PluginManagementPage>
+  );
+};
+
+export default LogsManagementPage;