yinzerflow 0.3.0 → 0.4.0

package/README.md

@@ -41,7 +41,7 @@ await app.listen();
 - **[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
+- **[Logging](docs/core/logging.md)** - Logging configuration and customization
 - **[Advanced Configuration](docs/advanced-configuration-options.md)** - Detailed configuration options
 
 ## 🛡️ Security

package/docs/configuration/advanced-configuration-options.md

@@ -210,7 +210,7 @@ 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.
+Control framework logging output with built-in Pittsburgh personality or custom logging libraries. See [Logging Documentation](../core/logging.md) for detailed setup, custom logger integration, and advanced use cases.
 
 ```typescript
 const app = new YinzerFlow({

package/docs/configuration/configuration-patterns.md

@@ -443,7 +443,7 @@ For detailed configuration options, see:
 - **[Body Parsing Security](../security/body-parsing.md)** - Body parser configuration
 - **[CORS Security](../security/cors.md)** - CORS configuration
 - **[IP Security](../security/ip-security.md)** - IP security configuration
-- **[Logging Security](../security/logging.md)** - Logging configuration
+- **[Logging Security](../core/logging.md)** - Logging configuration
 
 ## Common Issues and Solutions
 

package/docs/core/logging.md

@@ -0,0 +1,130 @@
+# Logging
+
+YinzerFlow provides a flexible logging system with built-in Pittsburgh personality and performance tracking.
+
+## Configuration
+
+```typescript
+import { YinzerFlow, createLogger } from 'yinzerflow';
+
+const logger = createLogger({
+  prefix: 'MYAPP',
+  logLevel: 'info'
+});
+
+const server = new YinzerFlow({
+  port: 3000,
+  logger,
+  networkLogs: true
+});
+```
+
+### Configuration Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `logLevel` | `'off' \| 'error' \| 'warn' \| 'info'` | `'info'` | Minimum log level to output |
+| `prefix` | `string` | `'YINZER'` | Prefix for log messages |
+| `logger` | `Logger` | `undefined` | Custom logger implementation (Winston, Pino, etc.) |
+| `networkLogs` | `boolean` | `false` | Enable nginx-style network request logging |
+| `networkLogger` | `Logger` | `undefined` | Custom logger for network logs (can be same as `logger` or different) |
+
+## Examples
+
+### Basic Example
+
+```typescript
+import { log } from 'yinzerflow';
+
+// Use the shared logger (default YINZER prefix)
+log.info('Application started');
+log.warn('Deprecated feature used');
+log.error('Operation failed');
+```
+
+### Custom Logger
+
+```typescript
+import { createLogger } from 'yinzerflow';
+
+const dbLogger = createLogger({ 
+  prefix: 'DATABASE', 
+  logLevel: 'error' 
+});
+
+dbLogger.error('Connection failed');
+// Output: [DATABASE] ❌ [timestamp] [ERROR] Connection failed - aw jeez
+```
+
+### Unified Network and App Logging
+
+```typescript
+import { YinzerFlow, createLogger } from 'yinzerflow';
+
+const logger = createLogger({ prefix: 'APP', logLevel: 'info' });
+
+const server = new YinzerFlow({
+  port: 3000,
+  logger,
+  networkLogs: true,
+  networkLogger: logger  // Route network logs to same logger
+});
+
+// Both app and network logs go to the same custom logger
+```
+
+## Common Use Cases
+
+- **Debug Development Issues**: Use default logger with `networkLogs: true` for comprehensive debugging
+- **Track Application Errors**: Use `logLevel: 'error'` to capture only critical errors  
+- **Monitor Component Health**: Create isolated loggers per subsystem with custom prefixes
+- **Integrate External Logging**: Use custom logger implementation for Winston, Pino, etc.
+- **Silent Operation**: Set `logLevel: 'off'` for environments with external log management
+- **Script and Utility Logging**: Use shared `log` instance in standalone scripts and database seeds
+
+## Methods
+
+### `createLogger(options?): Logger`
+
+Creates a logger instance with isolated state.
+
+**Parameters:**
+- `logLevel?: 'off' | 'error' | 'warn' | 'info'` - Minimum log level (default: 'info')
+- `prefix?: string` - Log message prefix (default: 'YINZER')  
+- `logger?: Logger` - Custom logger implementation
+
+**Returns:** Logger with `info`, `warn`, `error`, and `levels` methods.
+
+### Logger Methods
+
+- `info(...args): void` - Log info-level messages
+- `warn(...args): void` - Log warning messages
+- `error(...args): void` - Log error messages
+- `levels` - Access to log level constants
+
+## Properties
+
+### Log Levels
+
+- `off` (0): No logging
+- `error` (1): Only errors
+- `warn` (2): Warnings and errors
+- `info` (3): All messages (most verbose)
+
+## Security Considerations
+
+YinzerFlow implements several security measures for safe logging:
+
+### 🛡️ Safe Data Handling
+- **Problem**: Logging sensitive data can expose secrets in log files
+- **YinzerFlow Solution**: Uses native `console.log` formatting to prevent accidental serialization of sensitive objects
+
+### 🛡️ Log Level Protection
+- **Problem**: Verbose logging in production can impact performance and expose internal details  
+- **YinzerFlow Solution**: Configurable log levels with early returns to minimize overhead when logging is disabled
+
+### 🛡️ Logger Isolation
+- **Problem**: Custom loggers could interfere with framework logging
+- **YinzerFlow Solution**: Clean interface boundaries and isolated logger instances prevent conflicts
+
+These security measures ensure YinzerFlow's logging implementation follows security best practices and prevents common attack vectors while maintaining spec compliance.

package/docs/security/security-overview.md

@@ -124,7 +124,7 @@ app.onError(({ response }, error) => {
 ### 🛡️ Logging Security
 **Protection**: Log injection, sensitive data exposure
 **Implementation**: Structured logging, sensitive data filtering
-**Documentation**: [Logging Security](./logging.md)
+**Documentation**: [Logging Security](../core/logging.md)
 
 ```typescript
 const secureApp = new YinzerFlow({
@@ -272,7 +272,7 @@ For detailed security documentation:
 - **[Body Parsing](./body-parsing.md)** - File upload and JSON parsing security
 - **[CORS](./cors.md)** - Cross-origin request security
 - **[IP Security](./ip-security.md)** - Client IP validation and protection
-- **[Logging](./logging.md)** - Secure logging practices
+- **[Logging](../core/logging.md)** - Secure logging practices
 - **[Error Handling](../core/error-handling.md)** - Secure error handling patterns
 
 For security issues or questions:

package/docs/start-here.md

@@ -120,7 +120,7 @@ For custom shutdown handling, see [Advanced Configuration](./advanced-configurat
 - **[Body Parsing](./security/body-parsing.md)** - Secure parsing of JSON, file uploads, and form data with DoS protection
 - **[CORS](./security/cors.md)** - Cross-Origin Resource Sharing with comprehensive security measures
 - **[IP Security](./security/ip-security.md)** - Client IP validation and spoofing protection for load balancers and CDNs
-- **[Logging](./security/logging.md)** - Flexible logging with custom logger support and Pittsburgh personality
+- **[Logging](./core/logging.md)** - Flexible logging with custom logger support and Pittsburgh personality
 - **[Configuration Patterns](./configuration/configuration-patterns.md)** - Common configuration patterns and best practices
 - **[Advanced Configuration](./configuration/advanced-configuration-options.md)** - Fine-tune security, performance, and functionality
 
@@ -164,7 +164,7 @@ For custom shutdown handling, see [Advanced Configuration](./advanced-configurat
 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)
+4. **Customize Logging**: Implement custom loggers in [logging.md](./core/logging.md)
 5. **Advanced Configuration**: Fine-tune settings in [advanced-configuration-options.md](./advanced-configuration-options.md)
 
 ## Examples

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,27 @@
+
+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;
+
+    throw new Error("test");
+
+    return {
+        success: true,
+        message: "Hello World",
+        data: {
+            something
+        }
+    };
+};

package/example/app/index.ts

@@ -0,0 +1,163 @@
+import { registerExampleRoutes } from "@app/routes/example.ts";
+import { registerGroupExampleRoutes } from "@app/routes/group-example.ts";
+import log from "app/util/customLogger.ts";
+import { createLogger, YinzerFlow, type HandlerCallback } from "yinzerflow";
+
+const logger = createLogger({
+  prefix: "worker",
+  logLevel: "info",
+});
+
+const app = new YinzerFlow({
+  cors: {
+    enabled: true,
+    origin: "http://localhost:8085",
+    methods: ["GET", "POST", "PUT", "DELETE", "OPTIONS"],
+    allowedHeaders: ["Content-Type", "Authorization", "x-session-id"],
+    preflightContinue: false,
+  },
+  networkLogs: true,
+  logger: logger,
+  // networkLogger: log,
+});
+
+
+
+// app.onError((ctx) => {
+//   ctx.response.setStatusCode(500);
+//   return {
+//     success: false,
+//     message: "Something went wrong",
+//   };
+// });
+
+app.onNotFound(async (ctx) => {
+  ctx.response.setStatusCode(404);
+  return {
+    success: false,
+    message: "Not Found",
+  };
+});
+
+
+
+app.beforeAll([({ state }: any) => {
+  log.info("======== beforeAll ========");
+  // TODO: setup auth middleware here
+  // const user = {
+  //   id: 1,
+  // };
+  // state.user = user as any;
+  return;
+}]);
+
+app.afterAll([
+  (ctx) => {
+    // ctx.response.setStatusCode(202);
+    log.info("afterAll");
+  },
+]);
+
+const login: HandlerCallback<{
+  response: {
+    success: boolean;
+    message: string;
+  };
+  body: {
+    email: string;
+    password: string;
+  };
+}> = (({ request }) => {
+  const { email, password } = request.body;
+  log.info("========================");
+  log.info(email, password);
+  log.info("========================");
+
+  return {
+    success: true,
+    message: "Login successful",
+  };
+})
+
+app.post("/login", login);
+
+app.group("/api", (app) => {
+
+  app.group('/user', (app) => {
+    app.get('/get', ((ctx) => {
+      log.info("route handler");
+      // log.info(ctx.request);
+
+      return {
+        message: false
+      };
+    }),
+      {
+        beforeHooks: [
+          (ctx) => {
+            log.info("beforeRoute3");
+          },
+        ],
+      }
+    );
+  }, {
+    beforeHooks: [
+      (ctx) => {
+        ctx.state.test = "test state";
+        log.info("beforeRoute2");
+      },
+    ],
+    afterHooks: [
+      (ctx) => {
+        log.info("afterRoute2");
+        log.info(ctx.state.test);
+      },
+    ],
+  });
+
+  app.post(
+    "/get/:id",
+    ((ctx) => {
+      log.info("route handler");
+      log.info(ctx.request);
+
+      return {
+        message: false
+      };
+    }),
+    {
+      beforeHooks: [
+        (ctx) => {
+          ctx.response.setStatusCode(200);
+          log.info("beforeRoute");
+        },
+      ],
+      afterHooks: [
+        () => {
+          log.info("afterRoute");
+        },
+      ],
+    }
+  );
+}, {
+  beforeHooks: [
+    (ctx) => {
+      log.info("beforeRoute1");
+    },
+  ],
+  afterHooks: [
+    (ctx) => {
+      log.info("afterRoute1");
+    },
+  ],
+});
+
+// Register example routes
+registerExampleRoutes(app);
+registerGroupExampleRoutes(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/routes/group-example.ts

@@ -0,0 +1,13 @@
+import { exampleHandler } from '@app/handlers/example.ts';
+import type { YinzerFlow } from 'yinzerflow';
+
+export const registerGroupExampleRoutes = (app: YinzerFlow): void => {
+    app.group('/admin', (group) => {
+        /**
+         * Get all users
+         */
+        group.post('/get-users', exampleHandler);
+
+
+    });
+};

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,28 @@
+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:
+      - "3000:5000"
+    command: sh -c "bun install && tail -f /dev/null"
+    tty: true
+    stdin_open: true
+    networks:
+      - yinzerflow-network
+
+  benchmark:
+    image: williamyeh/wrk
+    restart: no
+    command: ["-t20", "-c400", "-d10s", "http://api:5000/status"]
+    depends_on:
+      - app
+    networks:
+      - yinzerflow-network
+
+networks:
+  yinzerflow-network:
+    driver: bridge

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"
+  }
+}