@flink-app/debug-plugin 0.12.1-alpha.7 → 0.13.0

package/CHANGELOG.md

@@ -0,0 +1,13 @@
+# @flink-app/debug-plugin
+
+## 0.13.0
+
+### Minor Changes
+
+-   Migrate to pnpm and streamlines build process.
+
+### Patch Changes
+
+-   Updated dependencies
+    -   @flink-app/management-api-plugin@0.13.0
+    -   @flink-app/flink@0.13.0

package/dist/handlers/Debug/Get.js

@@ -9,8 +9,8 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
     });
 };
 var __generator = (this && this.__generator) || function (thisArg, body) {
-    var _ = { label: 0, sent: function() { if (t[0] & 1) throw t[1]; return t[1]; }, trys: [], ops: [] }, f, y, t, g;
-    return g = { next: verb(0), "throw": verb(1), "return": verb(2) }, typeof Symbol === "function" && (g[Symbol.iterator] = function() { return this; }), g;
+    var _ = { label: 0, sent: function() { if (t[0] & 1) throw t[1]; return t[1]; }, trys: [], ops: [] }, f, y, t, g = Object.create((typeof Iterator === "function" ? Iterator : Object).prototype);
+    return g.next = verb(0), g["throw"] = verb(1), g["return"] = verb(2), typeof Symbol === "function" && (g[Symbol.iterator] = function() { return this; }), g;
     function verb(n) { return function (v) { return step([n, v]); }; }
     function step(op) {
         if (f) throw new TypeError("Generator is already executing.");

package/dist/handlers/Debug/PostDisable.js

@@ -9,8 +9,8 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
     });
 };
 var __generator = (this && this.__generator) || function (thisArg, body) {
-    var _ = { label: 0, sent: function() { if (t[0] & 1) throw t[1]; return t[1]; }, trys: [], ops: [] }, f, y, t, g;
-    return g = { next: verb(0), "throw": verb(1), "return": verb(2) }, typeof Symbol === "function" && (g[Symbol.iterator] = function() { return this; }), g;
+    var _ = { label: 0, sent: function() { if (t[0] & 1) throw t[1]; return t[1]; }, trys: [], ops: [] }, f, y, t, g = Object.create((typeof Iterator === "function" ? Iterator : Object).prototype);
+    return g.next = verb(0), g["throw"] = verb(1), g["return"] = verb(2), typeof Symbol === "function" && (g[Symbol.iterator] = function() { return this; }), g;
     function verb(n) { return function (v) { return step([n, v]); }; }
     function step(op) {
         if (f) throw new TypeError("Generator is already executing.");

package/dist/handlers/Debug/PostEnable.js

@@ -9,8 +9,8 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
     });
 };
 var __generator = (this && this.__generator) || function (thisArg, body) {
-    var _ = { label: 0, sent: function() { if (t[0] & 1) throw t[1]; return t[1]; }, trys: [], ops: [] }, f, y, t, g;
-    return g = { next: verb(0), "throw": verb(1), "return": verb(2) }, typeof Symbol === "function" && (g[Symbol.iterator] = function() { return this; }), g;
+    var _ = { label: 0, sent: function() { if (t[0] & 1) throw t[1]; return t[1]; }, trys: [], ops: [] }, f, y, t, g = Object.create((typeof Iterator === "function" ? Iterator : Object).prototype);
+    return g.next = verb(0), g["throw"] = verb(1), g["return"] = verb(2), typeof Symbol === "function" && (g[Symbol.iterator] = function() { return this; }), g;
     function verb(n) { return function (v) { return step([n, v]); }; }
     function step(op) {
         if (f) throw new TypeError("Generator is already executing.");

package/dist/models/request.d.ts

@@ -1,4 +1,3 @@
-/// <reference types="node" />
 import { IncomingHttpHeaders } from "http";
 export default interface request {
     start: Date;

package/package.json

@@ -1,29 +1,27 @@
 {
-    "name": "@flink-app/debug-plugin",
-    "version": "0.12.1-alpha.7",
-    "description": "Flink plugin that make it possbile to debug requests",
-    "scripts": {
-        "test": "echo \"Error: no test specified\"",
-        "prepublish": "tsc"
-    },
-    "author": "johan@frost.se",
-    "publishConfig": {
-        "access": "public"
-    },
-    "license": "MIT",
-    "types": "dist/index.d.ts",
-    "main": "dist/index.js",
-    "dependencies": {
-        "@flink-app/management-api-plugin": "^0.12.1-alpha.7",
-        "express": "^4.17.1",
-        "node-color-log": "^5.3.1"
-    },
-    "devDependencies": {
-        "@flink-app/flink": "^0.12.1-alpha.7",
-        "@types/express": "4.17.13",
-        "@types/node": "22.13.10",
-        "ts-node": "^9.1.1",
-        "typescript": "5.4.5"
-    },
-    "gitHead": "cd86dec5f9b3bf23c01374a729bb02d8a48c2869"
-}
+  "name": "@flink-app/debug-plugin",
+  "version": "0.13.0",
+  "description": "Flink plugin that make it possbile to debug requests",
+  "author": "johan@frost.se",
+  "publishConfig": {
+    "access": "public"
+  },
+  "license": "MIT",
+  "types": "dist/index.d.ts",
+  "main": "dist/index.js",
+  "dependencies": {
+    "node-color-log": "^5.3.1",
+    "@flink-app/management-api-plugin": "0.13.0",
+    "@flink-app/flink": "0.13.0"
+  },
+  "devDependencies": {
+    "@types/node": "22.13.10",
+    "ts-node": "^10.9.2"
+  },
+  "gitHead": "4243e3b3cd6d4e1ca001a61baa8436bf2bbe4113",
+  "scripts": {
+    "test": "echo \"Error: no test specified\"",
+    "build": "tsc",
+    "clean": "rimraf dist .flink"
+  }
+}

package/readme.md

@@ -1,74 +1,606 @@
-# Flink API Docs
+# Debug Plugin
 
-A FLINK plugin that makes it possible to debug requests in FLINK.
+A Flink plugin for debugging HTTP requests and responses in your application. Capture and inspect request/response data, enable/disable debugging on demand, and integrate with the Management API for admin panel access.
 
-## Usage
+## Installation
 
-Install plugin to your flink app project:
+Install the plugin to your Flink app project:
 
-```
-npm i -S @flink-app/debug-plugin
+```bash
+npm install @flink-app/debug-plugin
 ```
 
-Add and configure plugin in your app startup (probable the `index.ts` in root project):
+## Configuration
 
-```
-import { debugPlugin } from '@flink-app/debug-plugin';
+### Basic Setup
+
+Configure the plugin in your app startup:
+
+```typescript
+import { FlinkApp } from "@flink-app/flink";
+import { debugPlugin } from "@flink-app/debug-plugin";
 
 function start() {
   new FlinkApp<AppContext>({
     name: "My app",
     plugins: [
-        // Register plugin
-        debugPlugin({ enabledAtStart: false, logToConsole: false, keepLogs : 100 }),
+      debugPlugin({
+        enabledAtStart: false,  // Start with debugging disabled
+        logToConsole: false,    // Don't log to console
+        keepLogs: 100          // Keep last 100 requests
+      })
     ],
   }).start();
 }
+```
+
+**Plugin Options:**
+
+```typescript
+interface StaticOptions {
+  logToConsole: boolean;   // Log requests/responses to console
+  enabledAtStart: boolean; // Enable debugging when app starts
+  keepLogs?: number;       // Number of requests to keep in memory (default: 100)
+}
+```
+
+## TypeScript Setup
+
+The debug plugin doesn't require adding types to your context, but it does add properties to `ctx.plugins.debugPlugin`:
 
+```typescript
+ctx.plugins.debugPlugin: {
+  requests: request[];  // Array of captured requests
+  enabled: boolean;     // Current enabled state
+}
 ```
 
-## Use as a management-api-module
+## How It Works
+
+The debug plugin uses Express middleware to:
+1. Intercept incoming HTTP requests
+2. Capture request details (method, path, body, headers)
+3. Intercept outgoing responses by wrapping `res.write` and `res.end`
+4. Store request/response pairs in memory
+5. Keep a rolling window of the most recent N requests
+
+**What's Captured:**
+- Request method (GET, POST, etc.)
+- Request path and query parameters
+- Request headers
+- Request body
+- Response body
+- Request start and end timestamps
+
+**What's NOT Captured:**
+- Management API requests (routes starting with `/managementapi`)
+- Requests when debugging is disabled
+
+## Accessing Debug Data
+
+### From Handlers
 
-This plugin can be exposed as a management-api-module and could after setup be used both from the management-api and from flink-admin.
+Access captured requests directly from context:
 
-To enable management-api capabilities, simply craete a managment module and supply it to the managementApiPlugin.
+```typescript
+import { Handler } from "@flink-app/flink";
+import { Ctx } from "../Ctx";
 
+const GetDebugInfo: Handler<Ctx, any, any> = async ({ ctx, req }) => {
+  const debugData = ctx.plugins.debugPlugin;
 
-Example `index.ts`
+  return {
+    data: {
+      enabled: debugData.enabled,
+      requestCount: debugData.requests.length,
+      recentRequests: debugData.requests.slice(0, 10)
+    }
+  };
+};
 
+export default GetDebugInfo;
 ```
-import { FlinkApp } from '@flink-app/flink';
-import { Ctx } from './Ctx';
+
+### Enabling/Disabling Debug Mode
+
+Toggle debug mode programmatically:
+
+```typescript
+// Enable debugging
+ctx.plugins.debugPlugin.enabled = true;
+
+// Disable debugging
+ctx.plugins.debugPlugin.enabled = false;
+
+// Clear captured requests
+ctx.plugins.debugPlugin.requests = [];
+```
+
+## Management API Integration
+
+The debug plugin can be exposed as a Management API module for easy access from admin panels:
+
+### Setup Management Module
+
+```typescript
+import { FlinkApp } from "@flink-app/flink";
+import { Ctx } from "./Ctx";
 import {
   debugPlugin,
-  GetManagementModule as GetDebugManagementModule,
-} from '@flink-app/debug-plugin';
-import { managementApiPlugin } from '@flink-app/management-api-plugin';
+  GetManagementModule as GetDebugManagementModule
+} from "@flink-app/debug-plugin";
+import { managementApiPlugin } from "@flink-app/management-api-plugin";
 
 const debugManagementModule = GetDebugManagementModule({
   ui: true,
+  uiSettings: {
+    title: "Debug Console"
+  }
 });
 
 function start() {
   new FlinkApp<Ctx>({
-    name: 'My flink app',
+    name: "My flink app",
     debug: true,
     db: {
-      uri: 'mongodb://localhost:27017/my-flink-app',
+      uri: "mongodb://localhost:27017/my-flink-app"
     },
     plugins: [
-      debugPlugin({ enabledAtStart: false, logToConsole: false, keepLogs : 100 }),
+      debugPlugin({
+        enabledAtStart: false,
+        logToConsole: false,
+        keepLogs: 100
+      }),
       managementApiPlugin({
-        token: '123',
-        jwtSecret: '123',
-        modules: [debugManagementModule],
+        token: process.env.MGMT_TOKEN!,
+        jwtSecret: process.env.JWT_SECRET!,
+        modules: [debugManagementModule]
+      })
+    ]
+  }).start();
+}
+
+start();
+```
+
+**Management Module Options:**
+
+```typescript
+interface GetManagementModuleConfig {
+  pluginId?: string;   // Default: "debug"
+  ui: boolean;         // Enable UI in admin panel
+  uiSettings?: {
+    title: string;     // Module title (default: "Debug")
+  };
+}
+```
+
+### Management Endpoints
+
+When using the Management Module, these endpoints are registered under `/managementapi/{pluginId}`:
+
+#### GET /managementapi/debug/
+
+Get debug status and captured requests.
+
+**Response:**
+```typescript
+{
+  data: {
+    enabled: boolean;    // Current debug state
+    requests: request[]; // Array of captured requests
+  }
+}
+```
+
+**Example:**
+```bash
+curl http://localhost:3000/managementapi/debug/
+```
+
+#### POST /managementapi/debug/enable
+
+Enable debug mode.
+
+**Response:**
+```typescript
+{
+  data: {
+    enabled: true
+  }
+}
+```
+
+**Example:**
+```bash
+curl -X POST http://localhost:3000/managementapi/debug/enable
+```
+
+#### POST /managementapi/debug/disable
+
+Disable debug mode.
+
+**Response:**
+```typescript
+{
+  data: {
+    enabled: false
+  }
+}
+```
+
+**Example:**
+```bash
+curl -X POST http://localhost:3000/managementapi/debug/disable
+```
+
+## API Reference
+
+### Request Type
+
+Each captured request has the following structure:
+
+```typescript
+interface request {
+  start: Date;                      // When request started
+  end?: Date;                       // When response finished
+  method: string;                   // HTTP method (GET, POST, etc.)
+  path: string;                     // Request path with query params
+  headers?: IncomingHttpHeaders;    // Request headers
+  body?: any;                       // Parsed request body
+  response?: string;                // Response body as string
+}
+```
+
+### Context Properties
+
+```typescript
+ctx.plugins.debugPlugin: {
+  requests: request[];  // Array of captured requests (newest first)
+  enabled: boolean;     // Whether debugging is currently enabled
+}
+```
+
+## Complete Example
+
+Here's a complete example showing how to use the debug plugin:
+
+```typescript
+import { FlinkApp } from "@flink-app/flink";
+import { Ctx } from "./Ctx";
+import {
+  debugPlugin,
+  GetManagementModule as GetDebugManagementModule
+} from "@flink-app/debug-plugin";
+import { managementApiPlugin } from "@flink-app/management-api-plugin";
+
+// Create debug management module
+const debugManagementModule = GetDebugManagementModule({
+  ui: true,
+  uiSettings: {
+    title: "Request Debugger"
+  }
+});
+
+function start() {
+  new FlinkApp<Ctx>({
+    name: "My API",
+    debug: true,
+    db: {
+      uri: process.env.MONGODB_URI!
+    },
+    plugins: [
+      // Debug plugin - starts disabled, keeps last 200 requests
+      debugPlugin({
+        enabledAtStart: false,
+        logToConsole: true,  // Also log to console
+        keepLogs: 200
       }),
-    ],
+
+      // Management API with debug module
+      managementApiPlugin({
+        token: process.env.MGMT_TOKEN!,
+        jwtSecret: process.env.JWT_SECRET!,
+        modules: [debugManagementModule]
+      })
+    ]
   }).start();
 }
 
 start();
+```
+
+### Custom Debug Handler
+
+Create a custom handler to analyze debug data:
+
+```typescript
+import { Handler } from "@flink-app/flink";
+import { Ctx } from "../Ctx";
+
+interface DebugStatsResponse {
+  totalRequests: number;
+  methodCounts: { [method: string]: number };
+  slowestRequests: Array<{
+    path: string;
+    duration: number;
+  }>;
+  errorResponses: number;
+}
+
+const GetDebugStats: Handler<Ctx, any, DebugStatsResponse> = async ({ ctx }) => {
+  const requests = ctx.plugins.debugPlugin.requests;
+
+  // Count requests by method
+  const methodCounts: { [method: string]: number } = {};
+  for (const req of requests) {
+    methodCounts[req.method] = (methodCounts[req.method] || 0) + 1;
+  }
 
+  // Find slowest requests
+  const slowestRequests = requests
+    .filter(req => req.end)
+    .map(req => ({
+      path: req.path,
+      duration: req.end!.getTime() - req.start.getTime()
+    }))
+    .sort((a, b) => b.duration - a.duration)
+    .slice(0, 10);
+
+  // Count error responses (5xx, 4xx)
+  const errorResponses = requests.filter(req => {
+    if (!req.response) return false;
+    try {
+      const response = JSON.parse(req.response);
+      return response.status >= 400;
+    } catch {
+      return false;
+    }
+  }).length;
+
+  return {
+    data: {
+      totalRequests: requests.length,
+      methodCounts,
+      slowestRequests,
+      errorResponses
+    }
+  };
+};
+
+export default GetDebugStats;
 ```
 
-This way all static files in the `src/public` folder will be copied into dist. 
+## Use Cases
+
+### 1. Development Debugging
+
+Enable debug mode during development to inspect requests:
+
+```typescript
+debugPlugin({
+  enabledAtStart: true,
+  logToConsole: true,
+  keepLogs: 50
+})
+```
+
+### 2. Production Issue Investigation
+
+Keep debug mode off by default, enable on demand when investigating:
+
+```typescript
+debugPlugin({
+  enabledAtStart: false,
+  logToConsole: false,
+  keepLogs: 200  // Keep more logs for analysis
+})
+```
+
+Then enable via Management API when needed.
+
+### 3. API Testing
+
+Use debug data to verify request/response pairs:
+
+```typescript
+// Make test request
+await fetch("http://localhost:3000/api/users", {
+  method: "POST",
+  body: JSON.stringify({ name: "John" })
+});
+
+// Check debug data
+const debugData = ctx.plugins.debugPlugin.requests[0];
+expect(debugData.body).toEqual({ name: "John" });
+expect(JSON.parse(debugData.response!)).toHaveProperty("id");
+```
+
+### 4. Performance Monitoring
+
+Track request durations to identify slow endpoints:
+
+```typescript
+const slowRequests = ctx.plugins.debugPlugin.requests
+  .filter(req => req.end)
+  .filter(req => {
+    const duration = req.end!.getTime() - req.start.getTime();
+    return duration > 1000; // Slower than 1 second
+  });
+
+console.log(`Found ${slowRequests.length} slow requests`);
+```
+
+## Best Practices
+
+### Memory Management
+
+The plugin keeps requests in memory. Be careful with settings:
+
+```typescript
+// Good for development
+keepLogs: 50
+
+// Good for temporary production debugging
+keepLogs: 200
+
+// Be careful - could use significant memory
+keepLogs: 10000  // Avoid in production
+```
+
+Each request object includes:
+- Headers (can be large)
+- Request body (can be large)
+- Response body (can be large)
+
+### Security Considerations
+
+1. **Disable in Production**: Don't enable debug mode in production by default
+2. **Sensitive Data**: Be aware that debug logs capture request bodies and headers
+3. **Access Control**: Use Management API with proper authentication
+4. **Clear Logs**: Regularly clear captured requests to avoid memory leaks
+
+```typescript
+// Clear debug logs periodically
+setInterval(() => {
+  if (ctx.plugins.debugPlugin.requests.length > 500) {
+    ctx.plugins.debugPlugin.requests = [];
+  }
+}, 60000); // Every minute
+```
+
+### Console Logging
+
+Use `logToConsole: true` carefully:
+
+```typescript
+// Development - useful
+debugPlugin({
+  logToConsole: true,
+  enabledAtStart: true
+})
+
+// Production - avoid (too noisy)
+debugPlugin({
+  logToConsole: false,
+  enabledAtStart: false
+})
+```
+
+### Filtering Sensitive Data
+
+Consider wrapping the plugin to filter sensitive data:
+
+```typescript
+// In your handler
+const sanitizedRequests = ctx.plugins.debugPlugin.requests.map(req => ({
+  ...req,
+  headers: {
+    ...req.headers,
+    authorization: req.headers?.authorization ? "[REDACTED]" : undefined
+  },
+  body: req.body?.password ? { ...req.body, password: "[REDACTED]" } : req.body
+}));
+
+return { data: { requests: sanitizedRequests } };
+```
+
+## Implementation Details
+
+### Middleware Order
+
+The debug plugin middleware is registered during plugin initialization and runs for all requests except:
+- Routes starting with `/managementapi` (to avoid recursion)
+- Requests when `enabled` is `false`
+
+### Response Interception
+
+The plugin intercepts responses by:
+1. Saving original `res.write` and `res.end` functions
+2. Replacing them with custom implementations
+3. Collecting response chunks in a buffer
+4. Restoring original functions after response completes
+
+This ensures the plugin captures the full response without affecting normal operation.
+
+### Rolling Window
+
+When the request array exceeds `keepLogs`:
+```typescript
+requests = requests.splice(0, keep);
+```
+
+This keeps only the most recent N requests, with newest first (unshift).
+
+## Troubleshooting
+
+### Debug Mode Not Working
+
+1. **Check enabled state:**
+   ```typescript
+   console.log(ctx.plugins.debugPlugin.enabled);
+   ```
+
+2. **Verify plugin initialization:**
+   ```typescript
+   console.log(app.ctx.plugins.debugPlugin); // Should exist
+   ```
+
+3. **Check Management API routes:**
+   ```bash
+   # Should work
+   curl http://localhost:3000/managementapi/debug/
+   ```
+
+### Requests Not Being Captured
+
+1. **Enable debug mode:**
+   ```bash
+   curl -X POST http://localhost:3000/managementapi/debug/enable
+   ```
+
+2. **Check if route is excluded:**
+   - Management API routes are not captured
+   - Verify your route doesn't start with `/managementapi`
+
+3. **Check keepLogs setting:**
+   - If you have many requests, older ones get removed
+   - Increase `keepLogs` value
+
+### Memory Usage High
+
+1. **Reduce keepLogs:**
+   ```typescript
+   keepLogs: 50  // Keep fewer logs
+   ```
+
+2. **Clear logs periodically:**
+   ```typescript
+   ctx.plugins.debugPlugin.requests = [];
+   ```
+
+3. **Disable when not needed:**
+   ```bash
+   curl -X POST http://localhost:3000/managementapi/debug/disable
+   ```
+
+### Console Too Noisy
+
+Set `logToConsole: false`:
+
+```typescript
+debugPlugin({
+  enabledAtStart: true,
+  logToConsole: false,  // No console output
+  keepLogs: 100
+})
+```
+
+## Notes
+
+- The plugin automatically excludes Management API routes to avoid recursion
+- Request bodies are captured after body-parser middleware processes them
+- Response bodies are captured as strings (includes JSON, HTML, etc.)
+- The plugin adds minimal performance overhead when disabled
+- Debug data is stored in memory only (not persisted to database)
+- The `enabled` flag can be toggled at runtime without restarting the app

package/src/index.ts

@@ -1,6 +1,5 @@
-import { FlinkApp, FlinkPlugin, HttpMethod } from "@flink-app/flink";
+import { FlinkApp, FlinkPlugin, HttpMethod, ExpressRequest, ExpressResponse, ExpressNextFunction } from "@flink-app/flink";
 import { ManagementApiModule, ManagementApiType } from "@flink-app/management-api-plugin";
-import express from "express";
 import log from "node-color-log";
 import request from "./models/request";
 import * as GetHandler from "./handlers/Debug/Get";
@@ -44,7 +43,7 @@ function init(app: FlinkApp<any>, options: StaticOptions) {
         log.info(`Debug enabled`);
     }
 
-    expressApp.use((req: express.Request, res: express.Response, next: express.NextFunction) => {
+    expressApp.use((req: ExpressRequest, res: ExpressResponse, next: ExpressNextFunction) => {
         let requests = app.ctx.plugins.debugPlugin.requests as request[];
         let enabled = app.ctx.plugins.debugPlugin.enabled as boolean;
         if (!enabled) {

package/tsconfig.json

@@ -15,7 +15,7 @@
     "noEmit": false,
     "declaration": true,
     "experimentalDecorators": true,
-    "checkJs": true,
+    "checkJs": false,
     "outDir": "dist"
   },
   "include": ["./src/*"],