yinzerflow 0.2.8 → 0.2.9

package/docs/core/error-handling.md

@@ -0,0 +1,293 @@
+# Error Handling
+
+YinzerFlow provides comprehensive error handling with automatic error catching and custom error handlers. The framework automatically catches all errors thrown in route handlers, hooks, and middleware, ensuring your application never crashes due to unhandled exceptions.
+
+## Configuration
+
+Error handling is automatically enabled and requires no configuration for basic usage:
+
+```typescript
+import { YinzerFlow } from 'yinzerflow';
+
+const app = new YinzerFlow({ port: 3000 });
+
+// Errors are automatically caught - no configuration needed
+app.get('/api/users/:id', async ({ request }) => {
+  const user = await database.findUser(request.params.id);
+  if (!user) {
+    throw new Error('User not found'); // Automatically handled
+  }
+  return user;
+});
+```
+
+### Configuration Options
+
+YinzerFlow's error handling includes built-in security and logging features:
+
+| Feature | Default | Description |
+|---------|---------|-------------|
+| **Automatic Error Catching** | Enabled | All errors in handlers are automatically caught |
+| **Default Error Response** | 500 Internal Server Error | Structured error response with logging |
+| **Error Logging** | Enabled | All errors logged with Pittsburgh personality |
+| **CORS Headers** | Automatic | Error responses include proper CORS headers |
+| **Fallback Protection** | Enabled | Safe fallback if custom handlers fail |
+
+## Examples
+
+### Basic Example
+
+```typescript
+import { YinzerFlow } from 'yinzerflow';
+
+const app = new YinzerFlow({ port: 3000 });
+
+// No try-catch needed - errors are automatically handled
+app.get('/api/users/:id', async (ctx) => {
+  const userId = ctx.request.params.id;
+  
+  // Database errors are automatically caught
+  const user = await database.findUser(userId);
+  
+  if (!user) {
+    // This error will be handled by your error handler
+    throw new Error('User not found');
+  }
+  
+  return user;
+});
+
+// Custom error handler
+app.onError((ctx, error) => {
+  ctx.response.setStatusCode(500);
+  return {
+    success: false,
+    message: 'Something went wrong',
+    timestamp: new Date().toISOString()
+  };
+});
+
+await app.listen();
+```
+
+See [Error Handler Pattern](./examples.md#error-handler-pattern) for a complete error handler example.
+
+### Advanced Example
+
+```typescript
+import { YinzerFlow } from 'yinzerflow';
+
+const app = new YinzerFlow({ port: 3000 });
+
+// Custom error handler with different error types
+app.onError((ctx, error) => {
+  // Handle different error types
+  if (error instanceof ValidationError) {
+    ctx.response.setStatusCode(400);
+    return {
+      success: false,
+      error: 'Validation failed',
+      details: error.details,
+      path: ctx.request.path
+    };
+  }
+  
+  if (error instanceof DatabaseError) {
+    ctx.response.setStatusCode(503);
+    return {
+      success: false,
+      error: 'Service temporarily unavailable',
+      retryAfter: 30
+    };
+  }
+  
+  if (error instanceof AuthenticationError) {
+    ctx.response.setStatusCode(401);
+    return {
+      success: false,
+      error: 'Authentication required',
+      code: 'UNAUTHORIZED'
+    };
+  }
+  
+  // Default error handling
+  ctx.response.setStatusCode(500);
+  return {
+    success: false,
+    error: 'Internal server error',
+    requestId: ctx.request.headers['x-request-id'] || 'unknown'
+  };
+});
+
+// Custom not found handler
+app.onNotFound((ctx) => {
+  ctx.response.setStatusCode(404);
+  return {
+    success: false,
+    error: 'Route not found',
+    path: ctx.request.path,
+    method: ctx.request.method,
+    availableMethods: ['GET', 'POST', 'PUT', 'DELETE']
+  };
+});
+
+await app.listen();
+```
+
+## Common Use Cases
+
+- **Database Error Handling**: Automatically catch and handle database connection errors, query failures, and constraint violations
+- **Validation Error Processing**: Handle input validation errors with structured error responses and field-specific messages
+- **Authentication Error Management**: Process authentication failures, expired tokens, and authorization errors with appropriate status codes
+- **External API Error Handling**: Catch and handle errors from third-party services with retry logic and fallback responses
+- **File Upload Error Processing**: Handle file size limits, type validation errors, and upload failures with user-friendly messages
+- **Rate Limiting Error Responses**: Process rate limit violations with appropriate headers and retry information
+
+## Error Handler Parameters
+
+The error handler receives two parameters:
+
+### Context Object (`ctx`)
+The complete request context containing `request` and `response` objects. See [Context Object Documentation](./context.md) for detailed information about accessing context properties.
+
+### Error Object (`error`)
+The caught error can be any type - Error instances, strings, objects, or other values:
+
+```typescript
+app.onError((ctx, error) => {
+  // Handle different error types
+  if (error instanceof Error) {
+    return { error: error.message, stack: error.stack };
+  } else if (typeof error === 'string') {
+    return { error };
+  } else if (typeof error === 'object' && error !== null) {
+    return { error: JSON.stringify(error) };
+  } else {
+    return { error: 'Unknown error occurred' };
+  }
+});
+```
+
+## Error Handler Best Practices
+
+### Structured Error Responses
+```typescript
+app.onError((ctx, error) => {
+  const errorResponse = {
+    success: false,
+    message: error instanceof Error ? error.message : 'Internal server error',
+    timestamp: new Date().toISOString(),
+    path: ctx.request.path,
+    method: ctx.request.method,
+    requestId: ctx.request.headers['x-request-id'] || 'unknown'
+  };
+  
+  ctx.response.setStatusCode(500);
+  return errorResponse;
+});
+```
+
+### Error Type Handling
+```typescript
+app.onError((ctx, error) => {
+  // Handle specific error types
+  if (error instanceof ValidationError) {
+    ctx.response.setStatusCode(400);
+    return {
+      success: false,
+      error: 'Validation failed',
+      details: error.details,
+      fields: error.fields
+    };
+  }
+  
+  if (error instanceof DatabaseError) {
+    ctx.response.setStatusCode(503);
+    return {
+      success: false,
+      error: 'Database connection failed',
+      retryAfter: 60
+    };
+  }
+  
+  if (error instanceof RateLimitError) {
+    ctx.response.setStatusCode(429);
+    return {
+      success: false,
+      error: 'Too many requests',
+      retryAfter: error.retryAfter
+    };
+  }
+  
+  // Default handling
+  ctx.response.setStatusCode(500);
+  return { success: false, error: 'Internal server error' };
+});
+```
+
+### Error Logging and Monitoring
+```typescript
+app.onError((ctx, error) => {
+  // Log detailed error information for debugging
+  const errorInfo = {
+    message: error instanceof Error ? error.message : String(error),
+    stack: error instanceof Error ? error.stack : undefined,
+    path: ctx.request.path,
+    method: ctx.request.method,
+    userAgent: ctx.request.headers['user-agent'],
+    ipAddress: ctx.request.ipAddress,
+    timestamp: new Date().toISOString(),
+    requestId: ctx.request.headers['x-request-id'] || 'unknown'
+  };
+  
+  // Log to monitoring service (but don't expose to client)
+  console.error('Application error:', errorInfo);
+  
+  // Return sanitized response to client
+  ctx.response.setStatusCode(500);
+  return {
+    success: false,
+    error: 'Internal server error',
+    requestId: errorInfo.requestId
+  };
+});
+```
+
+## Error Handler Limitations
+
+- **No Error Throwing**: Error handlers should not throw errors - use return statements instead
+- **Response Object**: Return a response object that will be sent to the client
+- **Status Code**: Set the status code on `ctx.response.setStatusCode()` before returning
+- **CORS Headers**: CORS headers are automatically added to error responses
+- **Async Support**: Error handlers can be async functions
+- **Hook Integration**: Error handlers work with before/after hooks
+
+## Security Considerations
+
+YinzerFlow implements several security measures to prevent common error handling vulnerabilities:
+
+### 🛡️ Error Information Sanitization
+- **Problem**: Detailed error information can expose sensitive data like database credentials, file paths, or internal structure
+- **YinzerFlow Solution**: Error handlers receive the raw error but should return sanitized responses to clients
+
+### 🛡️ Stack Trace Protection
+- **Problem**: Stack traces in production can reveal application structure and sensitive information
+- **YinzerFlow Solution**: Error handlers can access stack traces for logging but should not return them to clients
+
+### 🛡️ Error Logging Security
+- **Problem**: Logged errors can contain sensitive information that could be exploited
+- **YinzerFlow Solution**: Built-in logging with Pittsburgh personality, custom loggers can implement additional sanitization
+
+### 🛡️ CORS Error Response Protection
+- **Problem**: Error responses without CORS headers can cause client-side issues
+- **YinzerFlow Solution**: CORS headers are automatically added to all error responses
+
+### 🛡️ Fallback Error Protection
+- **Problem**: If custom error handlers fail, applications can crash or expose sensitive information
+- **YinzerFlow Solution**: Built-in fallback error handler ensures graceful degradation
+
+### 🛡️ Error Handler Isolation
+- **Problem**: Malicious error handlers could modify responses or bypass security controls
+- **YinzerFlow Solution**: Error handlers are isolated and failures don't affect core functionality
+
+These security measures ensure YinzerFlow's error handling implementation follows security best practices and prevents common attack vectors while maintaining application stability and user experience. 

package/docs/core/examples.md

@@ -0,0 +1,195 @@
+# Common Examples
+
+This file contains shared examples that are referenced throughout the YinzerFlow documentation to avoid duplication.
+
+## Basic Handler Pattern
+
+```typescript
+import { YinzerFlow } from 'yinzerflow';
+
+const app = new YinzerFlow({ port: 3000 });
+
+app.post('/api/users/:id', (ctx) => {
+  // Access request properties
+  const userId = ctx.request.params.id;
+  const userData = ctx.request.body;
+  const includeProfile = ctx.request.query.include_profile;
+  const authHeader = ctx.request.headers['authorization'];
+  const clientIp = ctx.request.ipAddress;
+  
+  // Control response
+  ctx.response.setStatusCode(201);
+  ctx.response.addHeaders({
+    'Location': `/api/users/${userId}`,
+    'X-User-ID': userId
+  });
+  
+  return {
+    id: userId,
+    data: userData,
+    includeProfile: !!includeProfile,
+    clientIp
+  };
+});
+```
+
+## Request Access Pattern
+
+```typescript
+app.get('/api/users/:id', (ctx) => {
+  const { request } = ctx;
+  
+  // Access route parameters
+  const userId = request.params.id;
+  
+  // Access query parameters
+  const includeProfile = request.query.include_profile;
+  
+  // Access headers
+  const contentType = request.headers['content-type'];
+  const authorization = request.headers['authorization'];
+  
+  // Access request body
+  const userData = request.body;
+  
+  // Access raw body for manual parsing when needed
+  const rawBody = request.rawBody;
+
+  const clientIp = request.ipAddress
+  
+  return {
+    message: 'Request processed successfully',
+    userId,
+    includeProfile,
+    contentType,
+    hasAuth: !!authorization,
+    receivedData: userData
+  };
+});
+```
+
+## Response Control Pattern
+
+```typescript
+app.get('/api/users/:id', (ctx) => {
+  const { request, response } = ctx;
+  const userId = request.params.id;
+  
+  // Set successful status code
+  response.setStatusCode(200);
+  
+  // Add custom headers
+  response.addHeaders({
+    'X-User-ID': userId,
+    'Cache-Control': 'max-age=3600',
+    'X-API-Version': '1.0'
+  });
+  
+  // Return JSON response body (Content-Type automatically set)
+  return {
+    id: userId,
+    name: 'John Doe',
+    email: 'john@example.com',
+    timestamp: new Date().toISOString()
+  };
+});
+```
+
+## Error Handler Pattern
+
+```typescript
+app.onError((ctx, error) => {
+  // Access request context in error handler
+  const { path, method, headers } = ctx.request;
+  
+  // Control error response
+  ctx.response.setStatusCode(500);
+  
+  return {
+    success: false,
+    error: 'Internal server error',
+    path,
+    method,
+    timestamp: new Date().toISOString()
+  };
+});
+```
+
+## Hook Pattern
+
+```typescript
+// Before hook
+app.beforeAll([(ctx) => {
+  // Access request context
+  const authHeader = ctx.request.headers['authorization'];
+  
+  // Validate authentication
+  if (!authHeader) {
+    throw new Error('Authentication required');
+  }
+}]);
+
+// After hook
+app.afterAll([(ctx) => {
+  // Access response context
+  ctx.response.addHeaders({
+    'X-Response-Time': Date.now().toString()
+  });
+}]);
+```
+
+## TypeScript Pattern
+
+```typescript
+import type { HandlerCallback } from 'yinzerflow';
+
+// Define custom types for your API
+interface UserBody {
+  name: string;
+  email: string;
+  age: number;
+}
+
+interface UserResponse {
+  id: string;
+  name: string;
+  email: string;
+  createdAt: string;
+}
+
+interface UserQuery {
+  include_profile?: string;
+  limit?: string;
+}
+
+interface UserParams {
+  id: string;
+}
+
+// Typed handler with custom body, response, query, and params
+const createUserHandler: HandlerCallback<{
+  body: UserBody;
+  response: UserResponse;
+  query: UserQuery;
+  params: UserParams;
+}> = (ctx) => {
+  // ctx.request.body is typed as UserBody
+  const userData = ctx.request.body;
+  
+  // ctx.request.query is typed as UserQuery
+  const includeProfile = ctx.request.query.include_profile;
+  
+  // ctx.request.params is typed as UserParams
+  const userId = ctx.request.params.id;
+  
+  // Return type is typed as UserResponse
+  return {
+    id: 'user-123',
+    name: userData.name,
+    email: userData.email,
+    createdAt: new Date().toISOString()
+  };
+};
+
+app.post('/api/users/:id', createUserHandler);
+``` 

package/docs/{request.md → core/request.md}

@@ -40,44 +40,11 @@ These limits are built into the framework and cannot be disabled, ensuring consi
 
 ### Basic Example
 
-```typescript
-import { YinzerFlow } from 'yinzerflow';
-
-const app = new YinzerFlow({ port: 3000 });
-
-app.post('/api/users/:id', ({ request }) => {
-  // Access route parameters
-  const userId = request.params.id;
-  
-  // Access query parameters
-  const includeProfile = request.query.include_profile;
-  
-  // Access headers
-  const contentType = request.headers['content-type'];
-  const authorization = request.headers['authorization'];
-  
-  // Access request body
-  const userData = request.body;
-  
-  // Access raw body for manual parsing when needed
-  const rawBody = request.rawBody;
-
-  const clientIp = request.ipAddress
-  
-  return {
-    message: 'Request processed successfully',
-    userId,
-    includeProfile,
-    contentType,
-    hasAuth: !!authorization,
-    receivedData: userData
-  };
-});
-```
+See [Request Access Pattern](./examples.md#request-access-pattern) for a complete example showing how to access request properties.
 
 ### Body Parsing Example
 
-YinzerFlow automatically parses request bodies (JSON, file uploads, forms) with built-in security protections. Parsed data is available on `request.body` - see [Body Parsing Documentation](./body-parsing.md) for detailed configuration options, examples, and security considerations.
+YinzerFlow automatically parses request bodies (JSON, file uploads, forms) with built-in security protections. Parsed data is available on `request.body` - see [Body Parsing Documentation](../security/body-parsing.md) for detailed configuration options, examples, and security considerations.
 
 ```typescript
 app.post('/api/users', ({ request, response }) => {
@@ -155,7 +122,7 @@ YinzerFlow automatically handles request parsing errors and provides clear error
 - `Header value too long: maximum 8192 characters allowed`
 - `Header value contains invalid control characters`
 
-**Body parsing errors:** See [Body Parsing Documentation](./body-parsing.md) for detailed error handling
+**Body parsing errors:** See [Body Parsing Documentation](../security/body-parsing.md) for detailed error handling
 
 These errors automatically result in appropriate HTTP status codes (400 Bad Request) and prevent malformed requests from reaching your application handlers.
 

package/docs/{response.md → core/response.md}

@@ -30,46 +30,7 @@ YinzerFlow's response handling includes built-in security protections that are a
 
 ## Basic Example
 
-```typescript
-import { YinzerFlow } from 'yinzerflow';
-
-const app = new YinzerFlow({ port: 3000 });
-
-app.get('/api/users/:id', ({ request, response }) => {
-  const userId = request.params.id;
-  
-  // Set successful status code
-  response.setStatusCode(200);
-  
-  // Add custom headers
-  response.addHeaders({
-    'X-User-ID': userId,
-    'Cache-Control': 'max-age=3600',
-    'X-API-Version': '1.0'
-  });
-  
-  // Return JSON response body (Content-Type automatically set)
-  return {
-    id: userId,
-    name: 'John Doe',
-    email: 'john@example.com',
-    timestamp: new Date().toISOString()
-  };
-});
-
-app.post('/api/files', ({ request, response }) => {
-  // Set created status
-  response.setStatusCode(201);
-  
-  // Add location header for created resource
-  response.addHeaders({
-    'Location': '/api/files/12345',
-    'X-Upload-Size': request.headers['content-length'] || '0'
-  });
-  
-  return { fileId: '12345', status: 'uploaded' };
-});
-```
+See [Response Control Pattern](./examples.md#response-control-pattern) for a complete example showing how to control the response.
 
 ## Response Body Handling