yinzerflow 0.2.4 → 0.2.6

package/docs/start-here.md

@@ -0,0 +1,178 @@
+# Getting Started with YinzerFlow
+
+YinzerFlow is a lightweight, modular HTTP server framework for Node.js built with TypeScript. It provides a powerful routing system, comprehensive security features, and built-in Pittsburgh personality with flexible logging and configuration options.
+
+## What is YinzerFlow?
+
+YinzerFlow is designed for developers who want:
+- **Security-first approach** with built-in protections against common web vulnerabilities
+- **TypeScript-first development** with full type safety and IntelliSense support
+- **Flexible configuration** for different deployment environments and use cases
+- **Pittsburgh personality** with witty logging and error messages
+- **Modular architecture** that scales from simple APIs to complex microservices
+
+## Quick Start
+
+### Installation
+
+```bash
+# Using npm
+npm install yinzerflow
+
+# Using Yarn
+yarn add yinzerflow
+
+# Using Bun
+bun add yinzerflow
+```
+
+### Minimal Example
+
+```typescript
+import { YinzerFlow } from 'yinzerflow';
+
+// Create a new YinzerFlow instance
+const app = new YinzerFlow({ port: 3000 });
+
+// Add a simple route
+app.get('/hello', () => {
+  return { message: 'Hello, World!' };
+});
+
+// Start the server
+await app.listen();
+// Although you can log the server is started, the built in logging will log this for you already when the server is listening
+```
+
+### Basic API Example
+
+```typescript
+import { YinzerFlow } from 'yinzerflow';
+
+const app = new YinzerFlow({ port: 3000 });
+
+// GET route with parameters
+app.get('/api/users/:id', ({ request }) => {
+  const userId = request.params.id;
+  const includeProfile = request.query.include_profile;
+  
+  return {
+    id: userId,
+    name: 'John Doe',
+    includeProfile: !!includeProfile
+  };
+});
+
+// POST route with body parsing
+app.post('/api/users', ({ request }) => {
+  const userData = request.body;
+  
+  return {
+    message: 'User created successfully',
+    data: userData
+  };
+});
+
+await app.listen();
+```
+
+### Graceful Shutdown
+
+YinzerFlow automatically handles graceful shutdown for SIGTERM and SIGINT signals. No manual setup required:
+
+```typescript
+import { YinzerFlow } from 'yinzerflow';
+
+const app = new YinzerFlow({ port: 3000 });
+
+// Add your routes
+app.get('/hello', () => {
+  return { message: 'Hello, World!' };
+});
+
+// Start the server - graceful shutdown is automatically configured
+await app.listen();
+```
+
+**That's it!** YinzerFlow will automatically:
+- Listen for SIGTERM and SIGINT signals
+- Log the shutdown process with Pittsburgh personality
+- Close the server gracefully
+- Exit the process cleanly
+
+For custom shutdown handling, see [Advanced Configuration](./advanced-configuration-options.md).
+
+## Documentation Overview
+
+### Core Features
+
+- **[Routes](./routes.md)** - Comprehensive routing system with HTTP methods, parameters, hooks, and groups
+- **[Request Object](./request.md)** - Access headers, body, query parameters, route parameters, and raw body
+- **[Response Object](./response.md)** - Set status codes, headers, and return various response types
+- **[Body Parsing](./body-parsing.md)** - Secure parsing of JSON, file uploads, and form data with DoS protection
+
+### Security & Configuration
+
+- **[Advanced Configuration](./advanced-configuration-options.md)** - Fine-tune security, performance, and functionality
+- **[IP Security](./ip-security.md)** - Client IP validation and spoofing protection for load balancers and CDNs
+- **[CORS](./cors.md)** - Cross-Origin Resource Sharing with comprehensive security measures
+- **[Logging](./logging.md)** - Flexible logging with custom logger support and Pittsburgh personality
+
+### Common Use Cases
+
+- **API Development**: Create RESTful APIs with automatic body parsing and security
+- **File Uploads**: Handle multipart form data with size limits and type validation
+- **Authentication**: Implement middleware hooks for token validation and user sessions
+- **Rate Limiting**: Add before hooks to limit request frequency and prevent abuse
+- **Load Balancer Integration**: Configure trusted proxies for accurate client IP detection
+- **Production Monitoring**: Use custom loggers with structured logging and monitoring
+
+## Key Features
+
+### 🛡️ Security First
+- Built-in protection against DoS attacks, prototype pollution, and memory exhaustion
+- Automatic security headers and CORS validation
+- IP spoofing protection with trusted proxy validation
+- Comprehensive input validation and sanitization
+
+### 🔧 Flexible Configuration
+- Configurable body parsing limits and security settings
+- Custom logger integration (Winston, Pino, etc.)
+- Environment-specific configurations (development, production, high-security)
+- Graceful shutdown with connection timeout handling
+
+### 🚀 TypeScript Native
+- Full TypeScript support with comprehensive type definitions
+- IntelliSense support for all framework features
+- Type-safe request/response handling
+- Generic support for custom body and response types
+
+### 🎭 Pittsburgh Personality
+- Witty logging messages and error handling
+- Built-in Pittsburgh-themed personality
+- Customizable logging with familiar `log.info()` interface
+- Network request logging with nginx-style formatting
+
+## Next Steps
+
+1. **Start with Routes**: Learn the routing system in [routes.md](./routes.md)
+2. **Understand Requests**: Explore request handling in [request.md](./request.md)
+3. **Configure Security**: Set up IP security and CORS in [ip-security.md](./ip-security.md) and [cors.md](./cors.md)
+4. **Customize Logging**: Implement custom loggers in [logging.md](./logging.md)
+5. **Advanced Configuration**: Fine-tune settings in [advanced-configuration-options.md](./advanced-configuration-options.md)
+
+## Examples
+
+Check out the `/example` directory for complete working examples:
+
+- **TypeScript Example** - Full-featured API with authentication, file uploads, and custom logging
+- **Basic Example** - Minimal server setup for quick prototyping
+- **Production Example** - High-security configuration with monitoring and graceful shutdown
+
+## Contributing
+
+We welcome contributions! Please see our contribution guidelines and feel free to submit pull requests for documentation improvements, bug fixes, or new features.
+
+---
+
+**Ready to build something amazing?** Start with the [Routes documentation](./routes.md) to learn how to create your first API endpoints!

package/example/README.md

@@ -0,0 +1,11 @@
+For the types to work, you need to connect to the docker container using the IDE
+
+1. Ensure the [Dev Containers](https://marketplace.cursorapi.com/items?itemName=ms-vscode-remote.remote-containers) extension is installed in IDE 
+2. Start this image using `docker compose up -d`
+3. To start the test server run `bun start`
+4. Use `Ctrl + Shift + P`
+5. Select "Dev Containers: Attach to Running Container ..."
+6. Select this container which should be something like `yinzerflow-testing-app...`
+7. In the IDE that just opened, select folder `/app/yinzerflow-local`
+
+To aid in development, you can use the `bun run build:watch` command in the yinzerflow (the actual module) terminal

package/example/app/handlers/example.ts

@@ -0,0 +1,30 @@
+
+import type { HandlerCallback } from 'yinzerflow';
+
+
+
+
+export const exampleHandler: HandlerCallback<{
+    body: {
+        something: string;
+    };
+    response: {
+        message: string;
+        success: boolean;
+        data: {
+            something: string;
+        }
+    }
+
+}> = async ({ request }) => {
+    const { something } = request.body;
+
+
+    return {
+        success: true,
+        message: "Hello World",
+        data: {
+            something
+        }
+    };
+};

package/example/app/index.ts

@@ -0,0 +1,110 @@
+import { registerExampleRoutes } from "@app/routes/example.ts";
+import log from "app/util/customLogger.ts";
+import { YinzerFlow, type HandlerCallback } from "yinzerflow";
+
+const app = new YinzerFlow({
+  cors: {
+    enabled: true,
+    origin: "*",
+    methods: ["GET", "POST", "PUT", "DELETE", "OPTIONS"],
+    allowedHeaders: ["Content-Type", "Authorization", "x-session-id"],
+    preflightContinue: false,
+  },
+  bodyParser: {
+    json: {
+      maxDepth: 500
+    },
+
+  },
+  logLevel: "info",
+  networkLogs: true,
+  // logger: log,
+  // networkLogger: log,
+});
+
+
+
+app.onError((ctx) => {
+  ctx.response.setStatusCode(404);
+  return {
+    success: false,
+    message: "Something went wrong",
+  };
+});
+
+app.onNotFound((ctx) => {
+  ctx.response.setStatusCode(404);
+  return {
+    success: false,
+    message: "Not Found",
+  };
+});
+
+app.beforeAll([
+  (_) => {
+    console.log("======== beforeAll ========");
+  },
+]);
+
+app.afterAll([
+  (ctx) => {
+    ctx.response.setStatusCode(202);
+    console.log("afterAll");
+  },
+]);
+
+const login: HandlerCallback<{
+  response: {
+    success: boolean;
+    message: string;
+  };
+  body: {
+    email: string;
+    password: string;
+  };
+}> = (({ request }) => {
+  const { email, password } = request.body;
+  console.log("========================");
+  console.log(email, password);
+  console.log("========================");
+
+  return {
+    success: true,
+    message: "Login successful",
+  };
+})
+
+app.post("/login", login);
+
+app.group("/api", (app) => {
+  app.post(
+    "/get/:id",
+    ((ctx) => {
+      console.log("route handler");
+      console.log(ctx.request);
+
+      return {
+        message: false
+      };
+    }),
+    {
+      beforeHooks: [
+        (ctx) => {
+          ctx.response.setStatusCode(200);
+          console.log("beforeRoute");
+        },
+      ],
+      afterHooks: [
+        () => {
+          console.log("afterRoute");
+        },
+      ],
+    }
+  );
+});
+
+// Register example routes
+registerExampleRoutes(app);
+
+// Start the server AFTER defining all routes
+await app.listen();

package/example/app/routes/example.ts

@@ -0,0 +1,18 @@
+import { exampleHandler } from '@app/handlers/example.ts';
+import type { YinzerFlow } from 'yinzerflow';
+
+/**
+ * Register example routes on the main app instance
+ */
+export const registerExampleRoutes = (app: YinzerFlow) => {
+    /**
+     * Get all users
+     */
+    app.post('/get-users', exampleHandler);
+
+    /**
+     * Add an override reason for a user to be able to add a payout method
+     * This is used to remove all requirements bypassing any checks such as the $20 minimum balance
+     */
+    // app.post('/user/update', updateUserController);
+};

package/example/app/util/customLogger.ts

@@ -0,0 +1,166 @@
+
+import type { TransformableInfo } from 'logform';
+import { addColors, createLogger, format, transports } from 'winston';
+
+/**
+ * Logging levels in winston conform to the severity ordering specified by RFC5424: severity of all levels is assumed to
+ *  be numerically ascending from most important to least important.
+ */
+enum LogLevel {
+  CRITICAL = 0,
+  ERROR = 1,
+  WARN = 2,
+  INFO = 3,
+}
+
+enum LogColor {
+  CRITICAL = 'bold white redBG',
+  ERROR = 'bold red',
+  WARN = 'bold yellow',
+  INFO = 'bold cyan',
+}
+
+interface Transports {
+  console: transports.ConsoleTransportInstance;
+  file: transports.FileTransportInstance;
+}
+
+/**
+ * Define the levels that winston will use. This is used later on
+ * when we create the logger
+ */
+const logLevels = {
+  critical: LogLevel.CRITICAL,
+  error: LogLevel.ERROR,
+  warn: LogLevel.WARN,
+  info: LogLevel.INFO,
+};
+
+
+
+/**
+ * This lets us add custom logging levels and colors so that
+ * winston recognizes them
+ */
+addColors({
+  critical: LogColor.CRITICAL,
+  error: LogColor.ERROR,
+  warn: LogColor.WARN,
+  info: LogColor.INFO,
+});
+
+/**
+ * Safely formats a message for logging, handling different types appropriately
+ */
+const formatLogMessage = (message: unknown, meta: Record<string, unknown> = {}): string => {
+  let formattedMessage = '';
+
+  if (typeof message === 'string') {
+    formattedMessage = message;
+  } else if (typeof message === 'object' && message !== null) {
+    formattedMessage = JSON.stringify(message);
+  } else {
+    formattedMessage = String(message);
+  }
+
+  const metaKeys = Object.keys(meta);
+  if (metaKeys.length === 0) {
+    return formattedMessage;
+  }
+
+  const formattedMeta = JSON.stringify(meta, null, 2);
+
+  return `${formattedMessage}\n${formattedMeta}`;
+};
+
+/**
+ * This is the format that will be used for all logs except File logs
+ */
+const formatter = format.combine(
+  /** Adds color to the format */
+  format.colorize(),
+
+  /** Adds timestamp to the format */
+  format.timestamp({ format: 'YYYY-MM-DD HH:mm:ss' }),
+
+  /** Format the way the log is output to the console */
+  format.printf((info: TransformableInfo) => {
+    const { timestamp, level, message, ...meta } = info;
+    const formattedMessage = formatLogMessage(message, Object.keys(meta).length > 0 ? meta : undefined);
+    // eslint-disable-next-line @typescript-eslint/restrict-template-expressions
+    return `${timestamp} [${level}]: ${formattedMessage}`;
+  }),
+);
+
+/**
+ * This is the format that will be used for all File logs
+ * The only difference is that we don't want to add color because it will mess up the log file
+ */
+const fileFormatter = format.combine(
+  /** Adds timestamp to the format */
+  format.timestamp({ format: 'YYYY-MM-DD HH:mm:ss' }),
+
+  /** Format the way the log is output to the console */
+  format.printf((info: TransformableInfo) => {
+    const { timestamp, level, message, ...meta } = info;
+    const formattedMessage = formatLogMessage(message, Object.keys(meta).length > 0 ? meta : undefined);
+    // eslint-disable-next-line @typescript-eslint/restrict-template-expressions
+    return `${timestamp} [${level}]: ${formattedMessage}`;
+  }),
+);
+
+/** ======================================== Defineing Transports ============================================ */
+const transporters: Transports = {
+  console: new transports.Console({
+    format: formatter,
+  }),
+  file: new transports.File({
+    filename: 'storage/logs/info.log',
+    format: fileFormatter,
+  }),
+
+};
+
+/**
+ * Creates and configures the logger based on the current configuration
+ */
+const createConfiguredLogger = (): ReturnType<typeof createLogger> => {
+  const transportsToUse = [];
+  for (const transport of ['console', 'file']) {
+    switch (transport) {
+      case 'console':
+        transportsToUse.push(transporters.console);
+        break;
+      case 'file':
+        transportsToUse.push(transporters.file);
+        break;
+      default:
+        transportsToUse.push(transporters.console);
+        break;
+    }
+  }
+
+  return createLogger({
+    level: 'info',
+    transports: transportsToUse,
+    levels: logLevels,
+  });
+};
+
+// Create the logger with the configured settings
+const log = createConfiguredLogger();
+
+export default log;
+export const networkLog = createLogger({
+  level: 'info',
+  transports: [
+    new transports.Console({
+      format: formatter,
+    }),
+    new transports.File({
+      filename: 'storage/logs/info.log',
+      format: fileFormatter,
+    }),
+  ],
+  levels: logLevels,
+});

package/example/docker-compose.yml

@@ -0,0 +1,22 @@
+services:
+  app:
+    user: bun
+    image: oven/bun:1.2.17
+    working_dir: /app/yinzerflow-local
+    volumes:
+      - .:/app/yinzerflow-local
+      - ../yinzerflow/lib:/app/yinzerflow/lib
+    ports:
+      - "5005:5000"
+    command: sh -c "bun install && tail -f /dev/null"
+    tty: true
+    stdin_open: true
+
+  benchmark:
+    image: williamyeh/wrk
+    restart: no
+    command: ["-t20", "-c400", "-d10s", "http://api:5000/status"]
+    depends_on:
+      - app
+    networks:
+      - yinzerflow-network

package/example/package.json

@@ -0,0 +1,16 @@
+{
+  "name": "yinzerflow-local",
+  "type": "module",
+  "scripts": {
+    "start": "bun --watch app/index.ts"
+  },
+  "dependencies": {
+    "logform": "^2.7.0",
+    "winston": "^3.17.0",
+    "yinzerflow": "file:../yinzerflow/lib"
+  },
+  "devDependencies": {
+    "bun-types": "1.2.17",
+    "typescript": "^5.8.2"
+  }
+}

package/example/tsconfig.json

@@ -0,0 +1,54 @@
+{
+  "compilerOptions": {
+    "composite": true,
+    "target": "ESNext",
+    "useDefineForClassFields": true,
+    "module": "NodeNext",
+    "lib": ["ESNext"],
+    "skipLibCheck": true,
+    "types": ["bun-types"],
+
+    /* Bundler mode */
+    "moduleResolution": "NodeNext",
+    "moduleDetection": "force",
+    "allowImportingTsExtensions": true,
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "noEmit": true,
+    "jsx": "preserve",
+    "alwaysStrict": true,
+    "declaration": true,
+    "outDir": "lib",
+    "declarationDir": "lib",
+    "verbatimModuleSyntax": true,
+    "baseUrl": ".",
+    "paths": {
+      "@app/*": ["./app/*"]
+    },
+    "sourceMap": false,
+    "removeComments": true,
+    "declarationMap": true,
+
+    /* Linting */
+    "strict": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "noFallthroughCasesInSwitch": true,
+    "allowSyntheticDefaultImports": true,
+    "allowJs": false,
+    "forceConsistentCasingInFileNames": true,
+    "noImplicitAny": true,
+    "noImplicitReturns": true,
+    "noImplicitThis": true,
+    "noImplicitOverride": true,
+    "strictFunctionTypes": true,
+    "strictNullChecks": true,
+    "strictPropertyInitialization": true,
+    "allowUnreachableCode": false,
+    "allowUnusedLabels": false,
+    "exactOptionalPropertyTypes": true,
+    "noUncheckedIndexedAccess": true,
+    "strictBindCallApply": true
+  },
+  "include": ["app/**/*"]
+}

package/index.d.ts

@@ -578,6 +578,12 @@ export interface InternalServerConfiguration {
 	 * Server connection options
 	 */
 	connectionOptions: InternalConnectionOptions;
+	/**
+	 * Automatic graceful shutdown configuration
+	 * When enabled, YinzerFlow automatically sets up signal handlers for SIGTERM and SIGINT
+	 * @default true
+	 */
+	autoGracefulShutdown: boolean;
 }
 export interface Setup {
 	get: InternalSetupMethod;
@@ -637,13 +643,13 @@ declare class SetupImpl implements InternalSetupImpl {
 	readonly _routeRegistry: RouteRegistryImpl;
 	readonly _hooks: HookRegistryImpl;
 	constructor(customConfiguration?: ServerConfiguration);
-	get(path: string, handler: HandlerCallback, options?: InternalRouteRegistryOptions): void;
-	head(path: string, handler: HandlerCallback, options?: InternalRouteRegistryOptions): void;
-	post(path: string, handler: HandlerCallback, options?: InternalRouteRegistryOptions): void;
-	put(path: string, handler: HandlerCallback, options?: InternalRouteRegistryOptions): void;
-	patch(path: string, handler: HandlerCallback, options?: InternalRouteRegistryOptions): void;
-	delete(path: string, handler: HandlerCallback, options?: InternalRouteRegistryOptions): void;
-	options(path: string, handler: HandlerCallback, options?: InternalRouteRegistryOptions): void;
+	get(path: string, handler: HandlerCallback<any>, options?: InternalRouteRegistryOptions): void;
+	head(path: string, handler: HandlerCallback<any>, options?: InternalRouteRegistryOptions): void;
+	post(path: string, handler: HandlerCallback<any>, options?: InternalRouteRegistryOptions): void;
+	put(path: string, handler: HandlerCallback<any>, options?: InternalRouteRegistryOptions): void;
+	patch(path: string, handler: HandlerCallback<any>, options?: InternalRouteRegistryOptions): void;
+	delete(path: string, handler: HandlerCallback<any>, options?: InternalRouteRegistryOptions): void;
+	options(path: string, handler: HandlerCallback<any>, options?: InternalRouteRegistryOptions): void;
 	group(prefix: string, callback: (group: Record<Lowercase<InternalHttpMethod>, InternalSetupMethod>) => void, options?: InternalRouteRegistryOptions): void;
 	beforeAll(handlers: Array<HandlerCallback>, options?: InternalGlobalHookOptions): void;
 	afterAll(handlers: Array<HandlerCallback>, options?: InternalGlobalHookOptions): void;
@@ -664,6 +670,7 @@ export declare class YinzerFlow extends SetupImpl {
 		port: number | undefined;
 		host: string | undefined;
 	};
+	private _setupGracefulShutdown;
 }
 export declare const log: {
 	setLogLevel: (level: "error" | "info" | "off" | "warn") => void;