balda-js 0.0.1 → 0.0.3

package/docs/docs/plugins/log.md

@@ -1,592 +0,0 @@
----
-sidebar_position: 8
----
-
-# Log Plugin
-
-The Log plugin provides comprehensive request and response logging for your Balda.js application. It automatically logs HTTP requests and responses with configurable detail levels and can be used both globally and on specific routes.
-
-## Features
-
-- **Request Logging**: Log incoming requests with customizable detail
-- **Response Logging**: Log outgoing responses with status and body
-- **Configurable Detail**: Choose what information to log
-- **Global and Route-Level**: Apply logging globally or to specific routes
-- **Structured Logging**: JSON-formatted logs for easy parsing
-- **Performance Monitoring**: Track request timing and performance
-
-## Basic Configuration
-
-### Simple Setup
-
-```typescript
-import { Server } from 'balda-js';
-
-const server = new Server({
-  port: 3000,
-  plugins: {
-    log: {
-      logRequest: true,
-      logResponse: true
-    }
-  }
-});
-```
-
-### Detailed Configuration
-
-```typescript
-const server = new Server({
-  port: 3000,
-  plugins: {
-    log: {
-      logRequest: true,
-      logResponse: true,
-      requestPayload: {
-        method: true,
-        url: true,
-        ip: true,
-        headers: true,
-        body: false
-      },
-      responsePayload: {
-        status: true,
-        headers: false,
-        body: false
-      }
-    }
-  }
-});
-```
-
-## Configuration Options
-
-### Basic Options
-
-```typescript
-log: {
-  logRequest: true,           // Enable request logging (default: true)
-  logResponse: true,          // Enable response logging (default: true)
-  requestPayload: {
-    method: true,             // Log HTTP method (default: true)
-    url: true,                // Log request URL (default: true)
-    ip: true,                 // Log client IP (default: true)
-    headers: true,            // Log request headers (default: true)
-    body: false               // Log request body (default: false)
-  },
-  responsePayload: {
-    status: true,             // Log response status (default: true)
-    headers: false,           // Log response headers (default: false)
-    body: false               // Log response body (default: false)
-  }
-}
-```
-
-### Advanced Configuration
-
-```typescript
-log: {
-  logRequest: true,
-  logResponse: true,
-  requestPayload: {
-    method: true,
-    url: true,
-    ip: true,
-    headers: false, // Don't log headers for privacy
-    body: false
-  },
-  responsePayload: {
-    status: true,
-    headers: false,
-    body: false
-  },
-  pinoOptions: {
-    level: 'info',
-    prettyPrint: true
-  }
-}
-```
-
-## Usage Examples
-
-### Global Logging
-
-```typescript
-const server = new Server({
-  port: 3000,
-  plugins: {
-    log: {
-      logRequest: true,
-      logResponse: true,
-      requestPayload: {
-        method: true,
-        url: true,
-        ip: true,
-        headers: false,
-        body: false
-      },
-      responsePayload: {
-        status: true,
-        headers: false,
-        body: false
-      }
-    }
-  }
-});
-
-@controller('/api')
-export class ApiController {
-  @get('/users')
-  async getUsers(req: Request, res: Response) {
-    // All requests and responses will be logged automatically
-    const users = await getUsers();
-    res.json(users);
-  }
-}
-```
-
-### Route-Level Logging
-
-```typescript
-@controller('/api')
-export class ApiController {
-  @get('/public', {
-    middleware: [log({
-      logRequest: true,
-      logResponse: true,
-      requestPayload: {
-        method: true,
-        url: true,
-        ip: true,
-        headers: false,
-        body: false
-      }
-    })]
-  })
-  async publicEndpoint(req: Request, res: Response) {
-    // Only this route will be logged
-    res.json({ message: 'Public endpoint' });
-  }
-
-  @get('/private')
-  async privateEndpoint(req: Request, res: Response) {
-    // This route won't be logged
-    res.json({ message: 'Private endpoint' });
-  }
-}
-```
-
-### Different Logging Levels
-
-```typescript
-@controller('/api')
-export class LoggingController {
-  @get('/minimal', {
-    middleware: [log({
-      logRequest: true,
-      logResponse: true,
-      requestPayload: {
-        method: true,
-        url: true,
-        ip: false,
-        headers: false,
-        body: false
-      },
-      responsePayload: {
-        status: true,
-        headers: false,
-        body: false
-      }
-    })]
-  })
-  async minimalLogging(req: Request, res: Response) {
-    res.json({ message: 'Minimal logging' });
-  }
-
-  @get('/detailed', {
-    middleware: [log({
-      logRequest: true,
-      logResponse: true,
-      requestPayload: {
-        method: true,
-        url: true,
-        ip: true,
-        headers: true,
-        body: true
-      },
-      responsePayload: {
-        status: true,
-        headers: true,
-        body: true
-      }
-    })]
-  })
-  async detailedLogging(req: Request, res: Response) {
-    res.json({ message: 'Detailed logging' });
-  }
-}
-```
-
-### Conditional Logging
-
-```typescript
-@controller('/api')
-export class ConditionalController {
-  @get('/conditional', {
-    middleware: [log({
-      logRequest: true,
-      logResponse: (req, res) => {
-        // Only log responses with status >= 400
-        return res.responseStatus >= 400;
-      },
-      requestPayload: {
-        method: true,
-        url: true,
-        ip: true,
-        headers: false,
-        body: false
-      },
-      responsePayload: {
-        status: true,
-        headers: false,
-        body: true // Log body for errors
-      }
-    })]
-  })
-  async conditionalLogging(req: Request, res: Response) {
-    if (Math.random() > 0.5) {
-      res.status(500).json({ error: 'Random error' });
-    } else {
-      res.json({ message: 'Success' });
-    }
-  }
-}
-```
-
-## Log Output Examples
-
-### Request Log
-
-```json
-{
-  "level": "info",
-  "time": "2024-01-15T10:30:00.000Z",
-  "type": "request",
-  "requestId": "req-123",
-  "method": "POST",
-  "url": "/api/users",
-  "ip": "192.168.1.100",
-  "headers": {
-    "content-type": "application/json",
-    "authorization": "Bearer token123"
-  },
-  "body": {
-    "name": "John Doe",
-    "email": "john@example.com"
-  }
-}
-```
-
-### Response Log
-
-```json
-{
-  "level": "info",
-  "time": "2024-01-15T10:30:01.000Z",
-  "type": "response",
-  "requestId": "req-123",
-  "status": 201,
-  "headers": {
-    "content-type": "application/json"
-  },
-  "body": {
-    "id": 123,
-    "name": "John Doe",
-    "email": "john@example.com"
-  }
-}
-```
-
-### Minimal Log
-
-```json
-{
-  "level": "info",
-  "time": "2024-01-15T10:30:00.000Z",
-  "type": "request",
-  "requestId": "req-123",
-  "method": "GET",
-  "url": "/api/users"
-}
-```
-
-## Environment-Based Configuration
-
-### Development vs Production
-
-```typescript
-const isProduction = process.env.NODE_ENV === 'production';
-
-const server = new Server({
-  port: 3000,
-  plugins: {
-    log: {
-      logRequest: true,
-      logResponse: true,
-      requestPayload: {
-        method: true,
-        url: true,
-        ip: true,
-        headers: !isProduction, // Don't log headers in production
-        body: !isProduction     // Don't log bodies in production
-      },
-      responsePayload: {
-        status: true,
-        headers: false,
-        body: !isProduction     // Don't log response bodies in production
-      },
-      pinoOptions: {
-        level: isProduction ? 'info' : 'debug',
-        prettyPrint: !isProduction
-      }
-    }
-  }
-});
-```
-
-### Different Logging for Different Routes
-
-```typescript
-@controller('/api')
-export class DifferentLoggingController {
-  @get('/public', {
-    middleware: [log({
-      logRequest: true,
-      logResponse: true,
-      requestPayload: {
-        method: true,
-        url: true,
-        ip: true,
-        headers: false,
-        body: false
-      }
-    })]
-  })
-  async publicEndpoint(req: Request, res: Response) {
-    res.json({ message: 'Public endpoint' });
-  }
-
-  @get('/admin', {
-    middleware: [log({
-      logRequest: true,
-      logResponse: true,
-      requestPayload: {
-        method: true,
-        url: true,
-        ip: true,
-        headers: true,
-        body: true
-      },
-      responsePayload: {
-        status: true,
-        headers: true,
-        body: true
-      }
-    })]
-  })
-  async adminEndpoint(req: Request, res: Response) {
-    res.json({ message: 'Admin endpoint' });
-  }
-}
-```
-
-## Performance Monitoring
-
-### Request Timing
-
-```typescript
-@controller('/api')
-export class PerformanceController {
-  @get('/slow', {
-    middleware: [log({
-      logRequest: true,
-      logResponse: true,
-      requestPayload: {
-        method: true,
-        url: true,
-        ip: true,
-        headers: false,
-        body: false
-      },
-      responsePayload: {
-        status: true,
-        headers: false,
-        body: false
-      }
-    })]
-  })
-  async slowEndpoint(req: Request, res: Response) {
-    // Simulate slow operation
-    await new Promise(resolve => setTimeout(resolve, 2000));
-    res.json({ message: 'Slow response' });
-  }
-}
-```
-
-## Security Considerations
-
-### Sensitive Data Filtering
-
-```typescript
-@controller('/api')
-export class SecureController {
-  @post('/login', {
-    middleware: [log({
-      logRequest: true,
-      logResponse: true,
-      requestPayload: {
-        method: true,
-        url: true,
-        ip: true,
-        headers: false, // Don't log auth headers
-        body: false     // Don't log passwords
-      },
-      responsePayload: {
-        status: true,
-        headers: false,
-        body: false     // Don't log tokens
-      }
-    })]
-  })
-  async login(req: Request, res: Response) {
-    // Authentication logic
-    res.json({ token: 'secret-token' });
-  }
-}
-```
-
-## Integration with Other Plugins
-
-### With Error Handling
-
-```typescript
-@controller('/api')
-export class ErrorController {
-  @get('/error', {
-    middleware: [log({
-      logRequest: true,
-      logResponse: true,
-      requestPayload: {
-        method: true,
-        url: true,
-        ip: true,
-        headers: false,
-        body: false
-      },
-      responsePayload: {
-        status: true,
-        headers: false,
-        body: true // Log error responses
-      }
-    })]
-  })
-  async errorEndpoint(req: Request, res: Response) {
-    try {
-      throw new Error('Something went wrong');
-    } catch (error) {
-      res.status(500).json({ error: error.message });
-    }
-  }
-}
-```
-
-## Best Practices
-
-### Logging Recommendations
-
-1. **Don't Log Sensitive Data**: Avoid logging passwords, tokens, PII
-2. **Use Appropriate Detail Levels**: Different levels for different environments
-3. **Monitor Log Volume**: Be aware of log storage and performance impact
-4. **Structured Logging**: Use JSON format for easy parsing
-5. **Request ID Tracking**: Use request IDs to correlate logs
-
-### Configuration Tips
-
-```typescript
-// Production configuration
-const productionLogConfig = {
-  logRequest: true,
-  logResponse: true,
-  requestPayload: {
-    method: true,
-    url: true,
-    ip: true,
-    headers: false, // Privacy
-    body: false     // Security
-  },
-  responsePayload: {
-    status: true,
-    headers: false,
-    body: false     // Security
-  },
-  pinoOptions: {
-    level: 'info',
-    prettyPrint: false
-  }
-};
-
-// Development configuration
-const developmentLogConfig = {
-  logRequest: true,
-  logResponse: true,
-  requestPayload: {
-    method: true,
-    url: true,
-    ip: true,
-    headers: true,
-    body: true
-  },
-  responsePayload: {
-    status: true,
-    headers: true,
-    body: true
-  },
-  pinoOptions: {
-    level: 'debug',
-    prettyPrint: true
-  }
-};
-```
-
-### Monitoring and Alerting
-
-```typescript
-@controller('/api')
-export class MonitoredController {
-  @get('/monitored', {
-    middleware: [log({
-      logRequest: true,
-      logResponse: true,
-      requestPayload: {
-        method: true,
-        url: true,
-        ip: true,
-        headers: false,
-        body: false
-      },
-      responsePayload: {
-        status: true,
-        headers: false,
-        body: false
-      },
-      onError: (error, req, res) => {
-        // Send alert for errors
-        alertService.sendAlert(`Error in ${req.url}: ${error.message}`);
-      }
-    })]
-  })
-  async monitoredEndpoint(req: Request, res: Response) {
-    res.json({ message: 'Monitored endpoint' });
-  }
-}
-```