Merge pull request #115 from bufferings/work

Refactor logging system and add plugin logger support

Author: bufferings

.changeset/refactor-logging-system.md

@@ -0,0 +1,52 @@
+---
+'@korix/kori': patch
+'@korix/body-limit-plugin': patch
+'@korix/cors-plugin': patch
+'@korix/file-plugin-nodejs': patch
+'@korix/security-headers-plugin': patch
+'@korix/nodejs-adapter': patch
+---
+
+Refactor logging system and add plugin logger support
+
+This release significantly improves the logging infrastructure with better plugin integration and simplified API design.
+
+**Breaking Changes in @korix/kori:**
+
+The following context methods have been removed and replaced with standalone functions:
+
+- `ctx.createSysLogger()` → `createSystemLogger({ baseLogger: ctx.log() })`
+- `ctx.createPluginLogger(name)` → `createPluginLogger({ baseLogger: ctx.log(), pluginName: name })`
+
+**New Features:**
+
+- Add `createPluginLogger()` function for better plugin log organization
+- Add `createSystemLogger()` function for framework internal logging
+- Plugin loggers automatically namespace logs under `plugin.{pluginName}` channels
+- Simplified logging system with removal of complex lazy initialization
+
+**Improvements:**
+
+- All official plugins now use dedicated plugin loggers for better debugging
+- Enhanced plugin logging documentation with comprehensive examples
+- Streamlined context logger implementation and test coverage
+- Better error handling and serialization in logging infrastructure
+
+**Migration Guide:**
+
+```typescript
+// Before
+const sysLog = ctx.createSysLogger();
+const pluginLog = ctx.createPluginLogger('my-plugin');
+
+// After
+import { createSystemLogger, createPluginLogger } from '@korix/kori';
+
+const sysLog = createSystemLogger({ baseLogger: ctx.log() });
+const pluginLog = createPluginLogger({
+  baseLogger: ctx.log(),
+  pluginName: 'my-plugin',
+});
+```
+
+All official plugins and adapters have been updated to use the new logging API internally, but their public APIs remain unchanged.

.cursor/rules/tsdoc.mdc

@@ -16,13 +16,6 @@ Guidelines for writing comments and JSDoc in the Kori project.
 
 ## Public API
 
-### ✅ Required
-
-- Type parameter descriptions (`@template`)
-- Parameter descriptions (`@param`)
-- Return value descriptions (`@returns`)
-- Usage examples (`@example`)
-
 ````typescript
 /**
  * Handler context provides access to environment, request, response, and utilities
@@ -54,6 +47,29 @@ export type KoriHandlerContext<Env, Req, Res> = {
 };
 ````
 
+### ✅ Required
+
+- Type parameter descriptions (`@template`)
+- Parameter descriptions (`@param`)
+- Return value descriptions (`@returns`)
+
+### 📝 Recommended When Helpful
+
+- Usage examples (`@example`) - when the usage is not obvious from the function signature
+
+#### When to Include Examples
+
+- Complex APIs with multiple options or chaining methods
+- Non-obvious usage patterns or parameter combinations
+- Functions where type information alone doesn't clarify intended usage
+- APIs that have common misconceptions or edge cases
+
+#### When Examples Can Be Omitted
+
+- Simple, self-explanatory functions (e.g., `getUserId()`, `setName(name: string)`)
+- Standard getters/setters with obvious behavior
+- Functions where usage is clear from type definitions and parameter names
+
 ### 📝 Highlight Important Details
 
 - **Performance reasons** (mutation, caching, etc.)
@@ -80,8 +96,8 @@ const KoriRequestBrand = Symbol('kori-request');
 
 ```typescript
 /** @internal */
-export function createSysLogger(ctx: HandlerCtxState) {
-  return KoriLoggerUtils.createSysLogger({
+export function createSystemLogger(ctx: HandlerCtxState) {
+  return loggerHelpers.createSystemLogger({
     logger: getLoggerInternal(ctx),
   });
 }
@@ -92,7 +108,7 @@ export function createSysLogger(ctx: HandlerCtxState) {
 ```typescript
 /** @internal Caches logger per request for performance */
 export function getLoggerInternal(ctx: HandlerCtxState): KoriLogger {
-  ctx.loggerCache ??= KoriLoggerUtils.createRequestLogger(ctx.loggerFactory);
+  ctx.loggerCache ??= loggerHelpers.createRequestLogger(ctx.loggerFactory);
   return ctx.loggerCache;
 }
 ```

docs/en/guide/logging.md

@@ -161,3 +161,37 @@ app.get('/profile', (ctx) => {
 ```
 
 The metadata function is executed lazily - only when the log level is enabled, avoiding unnecessary computation.
+
+## Plugin Development
+
+When developing plugins, use `createPluginLogger()` for better log organization:
+
+```typescript
+export function myPlugin<
+  Env extends KoriEnvironment,
+  Req extends KoriRequest,
+  Res extends KoriResponse,
+>(): KoriPlugin<Env, Req, Res> {
+  return defineKoriPlugin({
+    name: 'my-plugin',
+    version: '0.0.0',
+    apply(kori) {
+      const log = createPluginLogger({
+        baseLogger: kori.log(),
+        pluginName: 'my-plugin',
+      });
+      log.info('Plugin initialized');
+
+      return kori.onRequest((ctx) => {
+        const requestLog = createPluginLogger({
+          baseLogger: ctx.log(),
+          pluginName: 'my-plugin',
+        });
+        requestLog.info('Processing request');
+      });
+    },
+  });
+}
+```
+
+Plugin loggers automatically namespace your logs under `plugin.{pluginName}` channel for better organization and debugging.

docs/en/guide/plugins.md

@@ -34,39 +34,53 @@ For example, a logging plugin might use multiple hooks:
 ```typescript
 import {
   defineKoriPlugin,
+  createPluginLogger,
   type KoriEnvironment,
   type KoriRequest,
   type KoriResponse,
   type KoriPlugin,
 } from '@korix/kori';
 
-// Simple logging plugin structure
+// Better logging plugin with dedicated logger
 export function loggingPlugin<
   Env extends KoriEnvironment,
   Req extends KoriRequest,
   Res extends KoriResponse,
 >(): KoriPlugin<Env, Req, Res, unknown, { startTime: number }, unknown> {
   return defineKoriPlugin({
-    name: 'simple-logging',
-    apply: (kori) =>
-      kori.onRequest((ctx) => {
+    name: 'request-logging',
+    apply: (kori) => {
+      const log = createPluginLogger({
+        baseLogger: kori.log(),
+        pluginName: 'request-logging',
+      });
+
+      log.info('Request logging plugin initialized');
+
+      return kori.onRequest((ctx) => {
+        const requestLog = createPluginLogger({
+          baseLogger: ctx.log(),
+          pluginName: 'request-logging',
+        });
+
         // Log when request starts
-        ctx.log().info('Request started', {
+        requestLog.info('Request started', {
           method: ctx.req.method(),
           path: ctx.req.url().pathname,
         });
 
         // Defer response logging
         ctx.defer(() => {
           const duration = Date.now() - ctx.req.startTime;
-          ctx.log().info('Request completed', {
+          requestLog.info('Request completed', {
             status: ctx.res.getStatus(),
             duration: `${duration}ms`,
           });
         });
 
         return ctx.withReq({ startTime: Date.now() });
-      }),
+      });
+    },
   });
 }
 ```
@@ -237,6 +251,95 @@ const requestIdPlugin = <
   });
 ```
 
+## Plugin Logging
+
+Plugins should use dedicated loggers to provide better organization and debugging capabilities. Use `createPluginLogger()` to create plugin-specific loggers that are automatically namespaced.
+
+### Plugin-Specific Loggers
+
+```typescript
+import {
+  defineKoriPlugin,
+  createPluginLogger,
+  type KoriEnvironment,
+  type KoriRequest,
+  type KoriResponse,
+  type KoriPlugin,
+} from '@korix/kori';
+
+export function authPlugin<
+  Env extends KoriEnvironment,
+  Req extends KoriRequest,
+  Res extends KoriResponse,
+>(): KoriPlugin<Env, Req, Res> {
+  return defineKoriPlugin({
+    name: 'auth',
+    apply: (kori) => {
+      // Instance-level plugin logger
+      const log = createPluginLogger({
+        baseLogger: kori.log(),
+        pluginName: 'auth',
+      });
+
+      log.info('Auth plugin initialized');
+
+      return kori.onRequest((ctx) => {
+        // Request-level plugin logger
+        const requestLog = createPluginLogger({
+          baseLogger: ctx.log(),
+          pluginName: 'auth',
+        });
+
+        requestLog.info('Checking authentication', {
+          path: ctx.req.url().pathname,
+        });
+
+        // Your authentication logic here...
+      });
+    },
+  });
+}
+```
+
+### Benefits of Plugin Loggers
+
+Plugin-specific loggers provide several advantages:
+
+- **Namespace isolation**: Logs are automatically prefixed with `plugin.{pluginName}`
+- **Better debugging**: Easy to filter logs by specific plugins
+- **Consistent formatting**: Inherits all bindings from the base logger
+- **Channel separation**: Plugin logs use dedicated channels for organization
+
+### Logger Output
+
+Plugin loggers automatically namespace their output:
+
+```json
+{
+  "time": 1754201824386,
+  "level": "info",
+  "channel": "plugin.auth",
+  "name": "request",
+  "message": "Checking authentication",
+  "meta": {
+    "path": "/api/users"
+  }
+}
+```
+
+Compare this with regular context logging:
+
+```json
+{
+  "time": 1754201824386,
+  "level": "info",
+  "channel": "app",
+  "name": "request",
+  "message": "Processing request",
+  "meta": {}
+}
+```
+
 ## Official Plugins
 
 Kori provides official plugins for common use cases. See the Extensions section for detailed documentation.

packages/body-limit-plugin/src/body-limit-plugin.ts

@@ -7,6 +7,7 @@ import {
   type KoriHandlerContext,
   HttpStatus,
   type KoriLogger,
+  createPluginLogger,
 } from '@korix/kori';
 
 import { PLUGIN_VERSION } from './version.js';
@@ -79,11 +80,9 @@ function isValidContentLength(value: string): boolean {
     return false;
   }
 
-  // Ensure parsed value exactly matches original string (catches leading zeros issues)
-  if (parsed.toString() !== value) {
-    return false;
-  }
-
+  // Allow leading zeros as per RFC 7230/9110 ABNF (1*DIGIT)
+  // While RFC 9110 5.6 recommends minimal decimal form,
+  // rejecting syntactically valid values may cause interoperability issues
   return true;
 }
 
@@ -190,14 +189,14 @@ export function bodyLimitPlugin<Env extends KoriEnvironment, Req extends KoriReq
     version: PLUGIN_VERSION,
     apply: (kori) => {
       // Instance-level logger for plugin initialization
-      const log = kori.log().channel(PLUGIN_NAME);
+      const log = createPluginLogger({ baseLogger: kori.log(), pluginName: PLUGIN_NAME });
       log.info(`Plugin initialized with max size: ${maxSize} bytes`);
 
       // Setup request monitoring for chunked transfer encoding and error handling
       return kori
         .onRequest((ctx) => {
           const { req, res } = ctx;
-          const requestLog = ctx.createPluginLogger(PLUGIN_NAME);
+          const requestLog = createPluginLogger({ baseLogger: ctx.log(), pluginName: PLUGIN_NAME });
 
           // Skip methods that don't typically have bodies
           if (!METHODS_WITH_BODY.has(req.method())) {
@@ -295,7 +294,7 @@ export function bodyLimitPlugin<Env extends KoriEnvironment, Req extends KoriReq
         .onError((ctx, error) => {
           if (error instanceof BodySizeLimitError) {
             const { req } = ctx;
-            const requestLog = ctx.log().channel(PLUGIN_NAME);
+            const requestLog = createPluginLogger({ baseLogger: ctx.log(), pluginName: PLUGIN_NAME });
             const xForwardedFor = req.headers()['x-forwarded-for']?.trim();
 
             requestLog.warn('Request body size exceeds limit', {

packages/cors-plugin/src/cors-plugin.ts

@@ -7,6 +7,7 @@ import {
   HttpStatus,
   type KoriHandlerContext,
   type KoriLogger,
+  createPluginLogger,
 } from '@korix/kori';
 
 import { type CorsPluginOptions } from './cors-plugin-options.js';
@@ -155,7 +156,7 @@ export function corsPlugin<Env extends KoriEnvironment, Req extends KoriRequest,
     name: PLUGIN_NAME,
     version: PLUGIN_VERSION,
     apply: (kori) => {
-      const log = kori.createPluginLogger(PLUGIN_NAME);
+      const log = createPluginLogger({ baseLogger: kori.log(), pluginName: PLUGIN_NAME });
       validateCorsOptions(log, options);
 
       log.info('CORS plugin initialized', {

packages/file-plugin-nodejs/src/send-file-plugin/send-file-plugin.ts

@@ -1,4 +1,4 @@
-import { defineKoriPlugin } from '@korix/kori';
+import { defineKoriPlugin, createPluginLogger } from '@korix/kori';
 import { type KoriEnvironment, type KoriPlugin, type KoriRequest, type KoriResponse } from '@korix/kori';
 
 import { PLUGIN_VERSION } from '../version/index.js';
@@ -25,11 +25,11 @@ export function sendFilePlugin<Env extends KoriEnvironment, Req extends KoriRequ
     name: PLUGIN_NAME,
     version: PLUGIN_VERSION,
     apply: (kori) => {
-      const log = kori.createPluginLogger(PLUGIN_NAME);
+      const log = createPluginLogger({ baseLogger: kori.log(), pluginName: PLUGIN_NAME });
       log.info('Send file plugin initialized', { root });
 
       return kori.onRequest((ctx) => {
-        const requestLog = ctx.createPluginLogger(PLUGIN_NAME);
+        const requestLog = createPluginLogger({ baseLogger: ctx.log(), pluginName: PLUGIN_NAME });
 
         const sendFile = (filePath: string, sendFileOptions?: SendFileOptions) =>
           handleFileResponse({