yinzerflow 0.2.5 → 0.2.7

package/README.md

@@ -0,0 +1,58 @@
+# YinzerFlow
+
+A lightweight, modular HTTP server framework for Node.js built with TypeScript. Features comprehensive security protections, Pittsburgh personality, and flexible configuration options.
+
+## 🚀 Quick Start
+
+For complete documentation and examples, see **[docs/start-here.md](docs/start-here.md)**.
+
+## 📦 Installation
+
+```bash
+npm install yinzerflow
+# or
+bun add yinzerflow
+```
+
+## 🔧 Basic Usage
+
+```typescript
+import { YinzerFlow } from 'yinzerflow';
+
+const app = new YinzerFlow({ port: 3000 });
+
+app.get('/hello', () => {
+  return { message: 'Hello, World!' };
+});
+
+await app.listen();
+```
+
+## ✨ Features
+
+- **Security-first** - Built-in protections against common web vulnerabilities
+- **TypeScript-first** - Full type safety and IntelliSense support
+- **Pittsburgh personality** - Witty logging and error messages
+- **Flexible configuration** - Comprehensive options for different use cases
+- **Modular architecture** - Scales from simple APIs to complex applications
+
+## 📚 Documentation
+
+- **[Getting Started](docs/start-here.md)** - Complete guide and examples
+- **[Routes](docs/routes.md)** - Routing system and handlers
+- **[Request/Response](docs/request.md)** - Request and response objects
+- **[Logging](docs/logging.md)** - Logging configuration and customization
+- **[Advanced Configuration](docs/advanced-configuration-options.md)** - Detailed configuration options
+
+## 🛡️ Security
+
+YinzerFlow includes comprehensive security features:
+- IP security and rate limiting
+- CORS protection
+- Body parsing with security limits
+- Header validation and sanitization
+- Prototype pollution protection
+
+## 📄 License
+
+MIT License - see [LICENSE](LICENSE) for details.

package/docs/advanced-configuration-options.md

@@ -90,6 +90,122 @@ const app = new YinzerFlow({
 | `keepAliveTimeout` | `number` | `65000` | Keep-alive timeout |
 | `headersTimeout` | `number` | `66000` | Headers timeout (should be > keep-alive) |
 
+### Graceful Shutdown Configuration
+
+Control automatic graceful shutdown behavior:
+
+```typescript
+const app = new YinzerFlow({
+  port: 3000,
+  autoGracefulShutdown: true, // Enable automatic signal handling (default)
+});
+```
+
+| Option | Type | Default | Description |
+|-----|---|---|---|
+| `autoGracefulShutdown` | `boolean` | `true` | Enable automatic SIGTERM/SIGINT handling |
+
+**When enabled (default):**
+- Automatically sets up SIGTERM and SIGINT signal handlers
+- Logs shutdown process with Pittsburgh personality
+- Calls `app.close()` and `process.exit(0)` automatically
+- Prevents duplicate handlers when multiple instances are created
+
+**When disabled:**
+- No automatic signal handling
+- Manual graceful shutdown setup required
+- Useful for custom shutdown logic or integration with process managers
+
+### Custom Graceful Shutdown Example
+
+When `autoGracefulShutdown: false`, you can implement custom shutdown logic:
+
+```typescript
+import { YinzerFlow } from 'yinzerflow';
+
+const app = new YinzerFlow({
+  port: 3000,
+  autoGracefulShutdown: false, // Disable automatic handling
+});
+
+// Custom shutdown with additional cleanup
+const gracefulShutdown = async (signal: string) => {
+  console.log(`🛑 Received ${signal}, starting custom shutdown...`);
+  
+  // Custom cleanup logic
+  await cleanupDatabase();
+  await saveApplicationState();
+  
+  // Close the server
+  await app.close();
+  
+  console.log('✅ Custom shutdown completed');
+  process.exit(0);
+};
+
+// Set up custom signal handlers
+process.on('SIGTERM', () => gracefulShutdown('SIGTERM'));
+process.on('SIGINT', () => gracefulShutdown('SIGINT'));
+
+await app.listen();
+```
+
+### Advanced Custom Shutdown Example
+
+For complex applications with multiple cleanup steps:
+
+```typescript
+import { YinzerFlow } from 'yinzerflow';
+
+const app = new YinzerFlow({
+  port: 3000,
+  autoGracefulShutdown: false,
+});
+
+let isShuttingDown = false;
+
+const advancedShutdown = async (signal: string) => {
+  if (isShuttingDown) {
+    console.log('⚠️ Shutdown already in progress, ignoring signal');
+    return;
+  }
+  
+  isShuttingDown = true;
+  console.log(`🛑 Received ${signal}, starting advanced shutdown...`);
+  
+  try {
+    // Phase 1: Stop accepting new requests
+    console.log('📝 Phase 1: Stopping new requests...');
+    // Your logic here
+    
+    // Phase 2: Complete in-flight requests
+    console.log('📝 Phase 2: Completing in-flight requests...');
+    await waitForInFlightRequests();
+    
+    // Phase 3: Cleanup resources
+    console.log('📝 Phase 3: Cleaning up resources...');
+    await cleanupDatabase();
+    await closeFileHandles();
+    await flushLogs();
+    
+    // Phase 4: Close server
+    console.log('📝 Phase 4: Closing server...');
+    await app.close();
+    
+    console.log('✅ Advanced shutdown completed successfully');
+    process.exit(0);
+  } catch (error) {
+    console.error('❌ Shutdown failed:', error);
+    process.exit(1);
+  }
+};
+
+process.on('SIGTERM', () => advancedShutdown('SIGTERM'));
+process.on('SIGINT', () => advancedShutdown('SIGINT'));
+
+await app.listen();
+```
+
 ### Logging Configuration
 
 Control framework logging output with built-in Pittsburgh personality or custom logging libraries. See [Logging Documentation](./logging.md) for detailed setup, custom logger integration, and advanced use cases.

package/docs/request.md

@@ -36,7 +36,9 @@ YinzerFlow's request parsing includes built-in security limits that are automati
 
 These limits are built into the framework and cannot be disabled, ensuring consistent security across all YinzerFlow applications.
 
-## Basic Example
+## Examples
+
+### Basic Example
 
 ```typescript
 import { YinzerFlow } from 'yinzerflow';
@@ -56,6 +58,9 @@ app.post('/api/users/:id', ({ request }) => {
   
   // Access request body
   const userData = request.body;
+  
+  // Access raw body for manual parsing when needed
+  const rawBody = request.rawBody;
 
   const clientIp = request.ipAddress
   
@@ -68,7 +73,67 @@ app.post('/api/users/:id', ({ request }) => {
     receivedData: userData
   };
 });
-  ```
+```
+
+### 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.
+
+```typescript
+app.post('/api/users', ({ request, response }) => {
+  // Body is automatically parsed based on Content-Type
+  const userData = request.body;
+  
+  return {
+    message: 'User created successfully',
+    data: userData
+  };
+});
+```
+
+### Raw Body Access Example
+
+For advanced use cases where you need to manually parse the request body, YinzerFlow provides access to the raw body via `request.rawBody`. This is useful when:
+
+- You need to implement custom parsing logic
+- You want to validate the raw body before parsing
+- You're working with unsupported content types
+- You need to implement custom security validations
+
+```typescript
+app.post('/api/custom-parser', ({ request }) => {
+  // Access the raw body as string or Buffer
+  const rawBody = request.rawBody;
+  
+  // Implement custom parsing logic
+  if (typeof rawBody === 'string') {
+    // Custom string parsing
+    const customData = parseCustomFormat(rawBody);
+    return { parsed: customData };
+  } else if (Buffer.isBuffer(rawBody)) {
+    // Custom binary parsing
+    const binaryData = parseBinaryFormat(rawBody);
+    return { parsed: binaryData };
+  }
+  
+  return { error: 'Unsupported body format' };
+});
+
+// Example: Custom XML parser
+app.post('/api/xml', ({ request }) => {
+  const rawBody = request.rawBody;
+  
+  if (typeof rawBody === 'string') {
+    // Parse XML manually
+    const xmlData = parseXML(rawBody);
+    return { xml: xmlData };
+  }
+  
+  return { error: 'Expected string body for XML' };
+});
+```
+
+**Note**: The `rawBody` property contains the unprocessed request body as either a `string` or `Buffer`, depending on the content type and framework processing. Always validate and sanitize raw body data before processing to prevent security vulnerabilities.
 
 ## Common Use Cases
 
@@ -126,20 +191,4 @@ YinzerFlow implements several security measures to prevent common request-based
 - **Problem**: Spoofed proxy headers can bypass IP-based security controls
 - **YinzerFlow Solution**: Secure IP address extraction with proxy header validation prevents spoofing attacks
 
-## Body Parsing
-
-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.
-
-```typescript
-app.post('/api/users', ({ request, response }) => {
-  // Body is automatically parsed based on Content-Type
-  const userData = request.body;
-  
-  return {
-    message: 'User created successfully',
-    data: userData
-  };
-});
-```
-
 These security measures ensure YinzerFlow's request implementation follows security best practices and prevents common attack vectors while maintaining RFC compliance and performance.