@avtechno/sfr 1.0.17 → 2.0.0

package/README.md

@@ -1,72 +1,917 @@
 # Single File Router (SFR)
 
-### Overview
-SFR allows the declaration of services including its controllers, handlers and validators in one single file.
+> An opinionated, convention-over-configuration approach to building services in Node.js
 
-Featuring a configurable Inversion of Control pattern for dependency libraries, It allows developers to easily inject dependencies on either handlers or controllers for convenient and easy access.
+[![npm version](https://img.shields.io/npm/v/@avtechno/sfr.svg)](https://www.npmjs.com/package/@avtechno/sfr)
+[![License: ISC](https://img.shields.io/badge/License-ISC-blue.svg)](https://opensource.org/licenses/ISC)
 
-Due to it's self-contained and structured format, The SFR has allowed for the development of several extensions such as:
+---
 
-* OpenAPI Service Translator
+## Overview
 
-	`A plugin which also uses API-Bundler's ability to extract metadata from individual SFRs
-  It's main purpose is to translate and create service-level documentation which follows the OpenAPI Standard, this essentially opens up doors to extensive tooling support, instrumentation, automated endpoint testing, automated documentation generation, just to name a few.`
+**SFR** is a declarative routing framework that allows you to define your entire API service—handlers, validators, and controllers—within a single, structured file. By embracing a **convention over configuration** philosophy, SFR eliminates boilerplate and enforces consistency across your codebase.
 
-* UAC - ACM Self-Registration Scheme
+### Key Features
 
-	`The in-house API-Bundler was designed to extract useful information from individual SFRs, termed service-artifacts, they are reported to a centralized authority through the well-documented UAC - ACM Self-Registration Scheme, this is prerogative to the grand scheme of Resource Administration.`
+- **Single-File Declaration** — Define validators, handlers, and controllers together in one cohesive module
+- **Multi-Protocol Support** — Build REST APIs, WebSocket servers, and Message Queue consumers using the same patterns
+- **Automatic Validation** — Integrate [Joi](https://joi.dev/) schemas or [Multer](https://github.com/expressjs/multer) middleware for request validation
+- **Dependency Injection** — Inject shared dependencies into handlers and controllers via IoC pattern
+- **Auto-Generated Documentation** — Produces OpenAPI 3.0 specs (REST) and AsyncAPI 3.0 specs (MQ/WS) automatically
+- **File-Based Routing** — Directory structure determines endpoint paths, reducing manual configuration
 
-### Structure 
+---
 
-A regular SFR is composed of the following objects
+## Installation
 
-|Object Name|Description|
-|-|-|
-|CFG| configuration information relayed to the API-bundler (service-parser).|
-|Validators|POJO representation of what values are allowed for each endpoint.|
-|Handlers| Express middlewares which acts as the main logic block for each endpoint.|
-|Controllers|Functions that execute calls to the database.|
+```bash
+npm install @avtechno/sfr
+# or
+yarn add @avtechno/sfr
+```
+
+### Peer Dependencies
 
-### Usage
+SFR works with the following libraries (install as needed):
+
+```bash
+npm install express joi amqplib socket.io
+```
 
-``` javascript
+---
 
-import sfr from "@hawkstow/sfr";
+## Quick Start
+
+```javascript
+import sfr from "@avtechno/sfr";
 import express from "express";
 
-const api_path = "api";
-const doc_path = "docs";
+const app = express();
+const PORT = 3000;
+
+app.use(express.json());
+
+await sfr(
+  { root: "dist", path: "api", out: "docs" },
+  {
+    title: "My Service",
+    description: "A sample SFR-powered service",
+    version: "1.0.0",
+    meta: {
+      service: "my-service",
+      domain: "example-org",
+      type: "backend",
+      language: "javascript",
+      port: PORT
+    }
+  },
+  { REST: app },
+  "api"
+);
+
+app.listen(PORT, () => console.log(`Server running on port ${PORT}`));
+```
+
+---
+
+## Project Structure
+
+SFR expects your API files to be organized by protocol within the specified path:
+
+```
+project/
+├── dist/                    # Compiled output (cfg.root)
+│   └── api/                 # API directory (cfg.path)
+│       ├── rest/            # REST endpoints
+│       │   ├── users.mjs
+│       │   └── auth/
+│       │       └── login.mjs
+│       ├── ws/              # WebSocket handlers
+│       │   └── chat.mjs
+│       └── mq/              # Message Queue consumers
+│           └── notifications.mjs
+├── docs/                    # Generated OpenAPI/AsyncAPI specs (cfg.out)
+└── src/
+    └── api/
+        └── ...              # Source files
+```
+
+The file path determines the endpoint URL:
+- `rest/users.mjs` → `/api/users/*`
+- `rest/auth/login.mjs` → `/api/auth/login/*`
+
+---
+
+## SFR File Structure
+
+Each SFR module exports a default object created using `REST()`, `WS()`, or `MQ()` template functions:
+
+| Component | Description |
+|-----------|-------------|
+| **cfg** | Configuration options (base directory, public/private access) |
+| **validators** | Request validation schemas (Joi objects or Multer middleware) |
+| **handlers** | Route handlers organized by HTTP method or MQ pattern |
+| **controllers** | Reusable data access functions (database calls, external APIs) |
+
+---
+
+## Creating a REST Endpoint
+
+```javascript
+import Joi from "joi";
+import { REST } from "@avtechno/sfr";
+
+export default REST({
+  cfg: {
+    base_dir: "users",    // Optional: Prepends to endpoint path
+    public: false         // Requires authentication (default: false)
+  },
+
+  validators: {
+    "get-profile": {
+      user_id: Joi.string().uuid().required()
+    },
+    "update-profile": {
+      name: Joi.string().min(2).max(100),
+      email: Joi.string().email()
+    }
+  },
+
+  handlers: {
+    GET: {
+      "get-profile": {
+        summary: "Retrieve user profile",
+        description: "Fetches the profile for a given user ID",
+        tags: ["users", "profile"],
+        async fn(req, res) {
+          const { user_id } = req.query;
+          const profile = await this.fetch_user(user_id);
+          res.status(200).json({ data: profile });
+        }
+      }
+    },
+
+    PUT: {
+      "update-profile": {
+        summary: "Update user profile",
+        description: "Updates profile information for authenticated user",
+        tags: ["users", "profile"],
+        deprecated: false,
+        async fn(req, res) {
+          const result = await this.update_user(req.body);
+          res.status(200).json({ data: result });
+        }
+      }
+    }
+  },
+
+  controllers: {
+    async fetch_user(user_id) {
+      // Access injected dependencies via `this`
+      return this.db.users.findById(user_id);
+    },
+
+    async update_user(data) {
+      return this.db.users.update(data);
+    }
+  }
+});
+```
+
+### Resulting Endpoints
+
+| Method | Endpoint | Handler |
+|--------|----------|---------|
+| GET | `/api/users/get-profile` | `get-profile` |
+| PUT | `/api/users/update-profile` | `update-profile` |
+
+---
+
+## Creating MQ Consumers
+
+SFR supports multiple messaging patterns via RabbitMQ/AMQP:
+
+| Pattern | Description | Class |
+|---------|-------------|-------|
+| **Point-to-Point** | Direct queue consumption | `TargetedMQ` |
+| **Request-Reply** | RPC-style messaging with responses | `TargetedMQ` |
+| **Fanout** | Broadcast to all subscribers | `BroadcastMQ` |
+| **Direct** | Route by exact routing key | `BroadcastMQ` |
+| **Topic** | Route by pattern-matched routing key | `BroadcastMQ` |
+
+```javascript
+import Joi from "joi";
+import { MQ } from "@avtechno/sfr";
+
+export default MQ({
+  cfg: {
+    base_dir: "notifications"
+  },
+
+  validators: {
+    "send-email": {
+      to: Joi.string().email().required(),
+      subject: Joi.string().required(),
+      body: Joi.string().required()
+    }
+  },
+
+  handlers: {
+    "Point-to-Point": {
+      "send-email": {
+        summary: "Process email notification",
+        options: { noAck: false },
+        async fn(msg) {
+          const { to, subject, body } = msg.content;
+          await this.send_email(to, subject, body);
+          this.mq.channel.ack(msg);
+        }
+      }
+    },
+
+    "Request-Reply": {
+      "validate-email": {
+        summary: "Validate email address",
+        async fn(msg) {
+          const result = await this.validate(msg.content.email);
+          this.mq.reply(msg, { valid: result });
+        }
+      }
+    }
+  },
+
+  controllers: {
+    async send_email(to, subject, body) {
+      // Email sending logic
+    },
+
+    async validate(email) {
+      // Validation logic
+      return true;
+    }
+  }
+});
+```
+
+---
+
+## Creating WebSocket Handlers
+
+SFR supports real-time WebSocket communication via [Socket.IO](https://socket.io/). WebSocket SFRs follow the same pattern as REST and MQ:
+
+```javascript
+import Joi from "joi";
+import { WS } from "@avtechno/sfr";
+
+export default WS({
+  cfg: {
+    namespace: "/chat",  // Socket.IO namespace (optional, defaults to "/")
+    public: true         // Skip authentication checks
+  },
+
+  validators: {
+    "send-message": {
+      room: Joi.string().required(),
+      message: Joi.string().min(1).max(1000).required(),
+      sender: Joi.string().required()
+    },
+    "join-room": {
+      room: Joi.string().required(),
+      username: Joi.string().min(2).max(50).required()
+    },
+    "leave-room": {
+      room: Joi.string().required()
+    }
+  },
+
+  handlers: {
+    "send-message": {
+      summary: "Send a message to a room",
+      description: "Broadcasts a message to all users in the specified room",
+      tags: ["chat", "messaging"],
+      async fn(ctx) {
+        const { room, message, sender } = ctx.data;
+        
+        // Process via controller
+        const processed = await this.process_message(room, sender, message);
+        
+        // Broadcast to room
+        ctx.io.to(room).emit("new-message", processed);
+        
+        // Acknowledge if callback provided
+        if (ctx.ack) ctx.ack({ success: true });
+      }
+    },
+
+    "join-room": {
+      summary: "Join a chat room",
+      description: "Adds the user to a room and notifies other members",
+      tags: ["chat", "rooms"],
+      async fn(ctx) {
+        const { room, username } = ctx.data;
+        
+        // Join Socket.IO room
+        ctx.socket.join(room);
+        
+        // Notify other room members
+        ctx.socket.to(room).emit("user-joined", { 
+          username, 
+          socket_id: ctx.socket.id 
+        });
+        
+        if (ctx.ack) ctx.ack({ success: true, room });
+      }
+    },
+
+    "leave-room": {
+      summary: "Leave a chat room",
+      tags: ["chat", "rooms"],
+      async fn(ctx) {
+        const { room } = ctx.data;
+        
+        ctx.socket.leave(room);
+        ctx.socket.to(room).emit("user-left", { socket_id: ctx.socket.id });
+        
+        if (ctx.ack) ctx.ack({ success: true });
+      }
+    }
+  },
+
+  controllers: {
+    async process_message(room, sender, message) {
+      // Access injected dependencies via `this`
+      return {
+        id: `msg_${Date.now()}`,
+        room,
+        sender,
+        message,
+        timestamp: Date.now()
+      };
+    }
+  }
+});
+```
+
+### WebSocket Handler Context
+
+Each WebSocket handler receives a context object (`ctx`) with the following properties:
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `io` | `Server` | The Socket.IO server instance |
+| `socket` | `Socket` | The current client socket connection |
+| `data` | `object` | The validated event payload |
+| `ack` | `function?` | Optional acknowledgement callback |
+
+### Initializing with WebSocket
+
+```javascript
+import sfr from "@avtechno/sfr";
+import express from "express";
+import { createServer } from "http";
+import { Server } from "socket.io";
 
 const app = express();
+const httpServer = createServer(app);
+const io = new Server(httpServer);
+
+await sfr(
+  { root: "dist", path: "api", out: "docs" },
+  { /* OAS config */ },
+  {
+    REST: app,
+    WS: io      // Pass Socket.IO server
+  },
+  "api"
+);
+
+httpServer.listen(3000);
+```
+
+### WebSocket Features
+
+- **Namespaces** — Use `cfg.namespace` to organize events into logical groups
+- **Rooms** — Use `ctx.socket.join()` and `ctx.socket.to()` for room-based messaging
+- **Validation** — Joi schemas validate incoming event data before handler execution
+- **Acknowledgements** — Support for Socket.IO acknowledgement callbacks via `ctx.ack`
+- **Error Handling** — Validation errors and handler exceptions emit `{event}:error` events
+
+---
+
+## Dependency Injection
+
+Inject shared dependencies (database connections, external services, etc.) into handlers and controllers:
+
+```javascript
+import sfr, { inject } from "@avtechno/sfr";
+import { PrismaClient } from "@prisma/client";
+import Redis from "ioredis";
 
-/*
-	Note: 
-	SFR Bundler will look for two folders, named "rest" and "ws" inside the "path". 
-	The placement of SFRs define the protocol that they'll use. 
-	`
-	i.e:rest SFRs reside within "rest", websocket SFRs reside in "ws".
-*/
+const db = new PrismaClient();
+const redis = new Redis();
 
-sfr({
-  root : "dist",   //Specifies the working directory
-  path : api_path, //Specifies the API directory i.e: where SFR files reside
-  out  : doc_path  //Specifies the directory for the resulting OAS documents
-}, app);
+// Inject dependencies before initializing SFR
+inject({
+  handlers: {
+    redis,
+    logger: console
+  },
+  controllers: {
+    db,
+    redis
+  }
+});
 
+// Now all handlers can access `this.redis` and `this.logger`
+// All controllers can access `this.db` and `this.redis`
 ```
 
-### Error-Handling
-The library automatically handles errors on both handlers and controllers, however, care must be taken on how error-handling is done by the developer, the following table illustrates what error-handling styles are allowed for both cases.
+### Accessing Injected Dependencies
+
+```javascript
+// In handlers
+async fn(req, res) {
+  this.logger.info("Request received");
+  const cached = await this.redis.get(key);
+  // ...
+}
+
+// In controllers
+async fetch_data(id) {
+  return this.db.table.findUnique({ where: { id } });
+}
+```
+
+---
+
+## Validation
+
+### Joi Validation
+
+Define validation schemas as plain objects with Joi validators:
+
+```javascript
+validators: {
+  "create-user": {
+    name: Joi.string().min(2).max(50).required(),
+    email: Joi.string().email().required(),
+    age: Joi.number().integer().min(18).optional()
+  }
+}
+```
+
+- **GET requests**: Validates `req.query`
+- **POST/PUT/PATCH requests**: Validates `req.body`
+
+### Multer Validation (File Uploads)
+
+Pass Multer middleware directly as validators:
+
+```javascript
+import multer from "multer";
+
+const upload = multer({ dest: "uploads/" });
+
+validators: {
+  "upload-avatar": upload.single("avatar")
+}
+```
+
+---
+
+## Configuration Reference
+
+### Parser Configuration (`ParserCFG`)
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `root` | `string` | Root directory of compiled source files |
+| `path` | `string` | Directory containing SFR modules |
+| `out` | `string` | Output directory for generated API specs |
+
+### SFR Configuration (`SFRConfig`)
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `base_dir` | `string` | `""` | Prefix path for all endpoints in the SFR |
+| `public` | `boolean` | `false` | Skip authentication/authorization checks |
+| `rate_limit` | `RateLimitConfig \| false` | Uses global default | Per-route rate limit configuration (see Rate Limiting section) |
+
+### OAS Configuration (`OASConfig`)
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `title` | `string` | Service name |
+| `description` | `string` | Service description |
+| `version` | `string` | Semantic version |
+| `meta.service` | `string` | Service identifier |
+| `meta.domain` | `string` | Organization/domain name |
+| `meta.type` | `"backend"` \| `"frontend"` | Service type |
+| `meta.language` | `string` | Programming language |
+| `meta.port` | `number` | Service port |
+
+---
+
+## Rate Limiting
+
+SFR includes built-in rate limiting support via `express-rate-limit` to protect your APIs from abuse and ensure fair resource usage.
+
+### Global Configuration
+
+Set default rate limiting for all routes:
+
+```javascript
+import { set_rate_limit_config } from "@avtechno/sfr";
+
+set_rate_limit_config({
+  default: {
+    max: 100,              // Maximum requests
+    windowMs: 60000,       // Time window (1 minute)
+    message: "Too many requests, please try again later.",
+    statusCode: 429,
+    standardHeaders: true,  // Include RateLimit-* headers
+    legacyHeaders: false    // Include X-RateLimit-* headers
+  }
+});
+```
+
+### Per-Route Configuration
+
+Override the global default in individual SFR files:
+
+```javascript
+import { REST } from "@avtechno/sfr";
+
+export default REST({
+  cfg: {
+    base_dir: "api",
+    // Custom rate limit for this route
+    rate_limit: {
+      max: 10,           // 10 requests
+      windowMs: 60000     // per minute
+    }
+  },
+  // ... rest of config
+});
+```
+
+### Disable Rate Limiting
+
+To disable rate limiting for a specific route:
+
+```javascript
+cfg: {
+  rate_limit: false  // Disables rate limiting for this route
+}
+```
+
+### Advanced Configuration
+
+All `express-rate-limit` options are supported:
+
+```javascript
+import RedisStore from "rate-limit-redis";
+import Redis from "ioredis";
+
+const redis = new Redis();
+
+set_rate_limit_config({
+  default: {
+    max: 100,
+    windowMs: 60000,
+    // Custom key generator (e.g., by user ID)
+    keyGenerator: (req) => req.user?.id || req.ip,
+    // Skip rate limiting for certain requests
+    skip: (req) => req.user?.isAdmin === true,
+    // Custom store (Redis, MongoDB, etc.)
+    store: new RedisStore({ client: redis })
+  }
+});
+```
+
+**Note:** Rate limiting middleware is applied before validation and authentication middleware.
+
+---
+
+## Auto-Generated Documentation
+
+SFR automatically generates API documentation in standard formats:
+
+- **REST endpoints** → OpenAPI 3.0 specification
+- **MQ consumers** → AsyncAPI 3.0 specification
+
+Documentation is written to the `cfg.out` directory as YAML files, enabling integration with:
+
+- Swagger UI / ReDoc
+- Postman / Insomnia import
+- API gateways
+- SDK generators
+- Automated testing tools
+
+### Handler Metadata
+
+Enhance generated documentation with metadata:
+
+```javascript
+handlers: {
+  GET: {
+    "fetch-items": {
+      summary: "Short description",           // Brief endpoint summary
+      description: "Detailed explanation",    // Full documentation
+      tags: ["inventory", "read"],            // Categorization tags
+      deprecated: false,                      // Mark as deprecated
+      async fn(req, res) { /* ... */ }
+    }
+  }
+}
+```
+
+---
+
+## Error Handling
+
+SFR provides automatic error handling for both handlers and controllers:
+
+| Context | Supported Error Styles |
+|---------|------------------------|
+| **Handlers** | `throw new Error()`, `next(error)` |
+| **Controllers** | `Promise.reject()`, `return Promise.resolve/reject` |
+
+### Example
+
+```javascript
+handlers: {
+  GET: {
+    "risky-operation": {
+      async fn(req, res, next) {
+        try {
+          const result = await this.dangerous_call();
+          res.json({ data: result });
+        } catch (error) {
+          // Option 1: Throw (SFR catches this)
+          throw error;
+
+          // Option 2: Pass to Express error handler
+          // next(error);
+        }
+      }
+    }
+  }
+},
+
+controllers: {
+  async dangerous_call() {
+    // Rejections are automatically caught
+    if (bad_condition) {
+      return Promise.reject(new Error("Operation failed"));
+    }
+    return result;
+  }
+}
+```
+
+---
+
+## MQ Integration
+
+### Initializing with Message Queue
+
+```javascript
+import sfr, { MQLib } from "@avtechno/sfr";
+
+const mq = new MQLib();
+await mq.init(process.env.RABBITMQ_URL);
+
+await sfr(
+  { root: "dist", path: "api", out: "docs" },
+  { /* OAS config */ },
+  {
+    REST: app,
+    MQ: mq.get_channel()
+  },
+  "api"
+);
+```
+
+### Using MQ in REST Handlers
+
+When MQ is configured, handlers receive access to messaging patterns:
+
+```javascript
+handlers: {
+  POST: {
+    "trigger-job": {
+      async fn(req, res) {
+        // Access injected MQ patterns
+        await this.mq["Point-to-Point"].produce("job-queue", req.body);
+        res.json({ status: "queued" });
+      }
+    }
+  }
+}
+```
+
+---
+
+## Debugging
+
+Enable debug output by setting the environment variable:
+
+```bash
+DEBUG_SFR=true node server.js
+```
+
+This displays:
+- Number of mounted endpoints per protocol
+- Resolved paths for each SFR
+- Protocol status indicators
+
+---
+
+## API Reference
+
+### Exports
+
+| Export | Description |
+|--------|-------------|
+| `default` | Main SFR initializer function |
+| `REST` | Template function for REST endpoints |
+| `WS` | Template function for WebSocket handlers |
+| `MQ` | Template function for MQ consumers |
+| `MQLib` | Helper class for MQ connection management |
+| `BroadcastMQ` | MQ class for Fanout/Direct/Topic patterns |
+| `TargetedMQ` | MQ class for Point-to-Point/Request-Reply patterns |
+| `inject` | Dependency injection function |
+| `set_observability_options` | Configure observability settings |
+| `sfr_logger` | Logger with automatic trace context |
+| `with_span` | Create custom tracing spans |
+| `get_trace_context` | Get current trace/span IDs |
+
+---
+
+## Observability (OpenTelemetry)
+
+SFR includes built-in OpenTelemetry-compatible observability with automatic instrumentation for all protocols.
+
+### Features
+
+- **Tracing**: Distributed traces across REST, WebSocket, and MQ handlers
+- **Metrics**: Request counts, latencies, error rates, connection gauges
+- **Logging**: Structured logs with automatic trace context correlation
+- **Auto-instrumentation**: Express, Socket.IO, and AMQP are automatically traced
+
+### Quick Start
+
+Observability is enabled by default and uses your `OASConfig` for service identification:
+
+```javascript
+import sfr from "@avtechno/sfr";
+
+// Service name and version are extracted from oas_cfg automatically
+await sfr(
+  { root: "dist", path: "api", out: "docs" },
+  {
+    title: "My Service",
+    version: "1.0.0",
+    meta: {
+      service: "my-service",    // Used as service.name in traces
+      domain: "example-org",
+      type: "backend",
+      language: "javascript",
+      port: 3000
+    }
+  },
+  { REST: app }
+);
+```
+
+### Configuration
+
+Configure observability before initializing SFR:
+
+```javascript
+import sfr, { set_observability_options } from "@avtechno/sfr";
+
+set_observability_options({
+  enabled: true,                           // Enable/disable (default: true)
+  otlp_endpoint: "http://localhost:4318",  // OTLP collector endpoint
+  auto_instrumentation: true,              // Auto-instrument common libraries
+  log_format: "json",                      // 'json' or 'pretty'
+  debug: false                             // Enable OTel SDK debug logs
+});
+
+await sfr(cfg, oas_cfg, connectors);
+```
+
+### Environment Variables
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `OTEL_EXPORTER_OTLP_ENDPOINT` | OTLP collector endpoint | `http://localhost:4318` |
+| `SFR_TELEMETRY_ENABLED` | Enable/disable telemetry | `true` |
+| `SFR_LOG_FORMAT` | Log format (`json`/`pretty`) | `pretty` (dev), `json` (prod) |
+| `DEBUG_SFR` | Enable debug logging | `false` |
+
+### Custom Spans in Handlers
+
+Add custom tracing spans for fine-grained observability:
+
+```javascript
+import { REST, with_span } from "@avtechno/sfr";
+
+export default REST({
+  handlers: {
+    GET: {
+      "get-user": {
+        async fn(req, res) {
+          // Create a child span for database operation
+          const user = await with_span({
+            name: "db:fetch_user",
+            attributes: { "user.id": req.params.id }
+          }, async (span) => {
+            return this.db.users.findById(req.params.id);
+          });
+
+          res.json({ data: user });
+        }
+      }
+    }
+  }
+});
+```
+
+### Logging with Trace Context
+
+Logs automatically include trace context when a span is active:
+
+```javascript
+import { REST, sfr_logger, create_child_logger } from "@avtechno/sfr";
+
+export default REST({
+  handlers: {
+    POST: {
+      "create-order": {
+        async fn(req, res) {
+          // Logs include trace_id and span_id automatically
+          sfr_logger.info("Creating order", { user_id: req.user.id });
+
+          // Create a child logger with additional context
+          const order_logger = create_child_logger({ order_id: "ord_123" });
+          order_logger.debug("Processing payment");
+
+          res.json({ data: { success: true } });
+        }
+      }
+    }
+  }
+});
+```
+
+### Graceful Shutdown
+
+Ensure telemetry is flushed before shutdown:
+
+```javascript
+import { shutdown_observability } from "@avtechno/sfr";
+
+process.on("SIGTERM", async () => {
+  await shutdown_observability();
+  process.exit(0);
+});
+```
+
+### Metrics Available
+
+| Metric | Type | Description |
+|--------|------|-------------|
+| `sfr.rest.requests.total` | Counter | Total REST requests |
+| `sfr.rest.request.duration` | Histogram | Request latency (ms) |
+| `sfr.rest.errors.total` | Counter | Total REST errors |
+| `sfr.ws.connections.active` | Gauge | Active WebSocket connections |
+| `sfr.ws.events.total` | Counter | Total WebSocket events |
+| `sfr.mq.messages.received` | Counter | Total MQ messages received |
+| `sfr.mq.processing.duration` | Histogram | Message processing time (ms) |
+
+> 📖 **For comprehensive OpenTelemetry documentation**, including integration guides for Prometheus, Grafana, Loki, Jaeger, and other backends, see [OpenTelemetry Documentation](./docs/09-opentelemetry.md).
+
+---
+
+## Roadmap
+
+- [ ] Multer upload validation in OpenAPI specs
+- [x] Built-in structured logging
+- [x] WebSocket protocol implementation
+- [x] Rate limiting middleware integration
+- [ ] GraphQL protocol support
+
+---
+
+## Contributing
 
-|Handlers|Controllers|
-|-|-|
-|Exception Throws|Promise.resolve/reject returns|
-|Passing Exceptions to Next fn||
+Found a bug or have a feature request? Please open an issue on our [GitHub Issues](https://github.com/avtechno/sfr/issues) page.
 
+---
 
-### Bug Reporting
-If you've found a bug, please file it in our Github Issues Page so we can have a look at it, perhaps fix it XD
+## License
 
-TODO:
-* Multer Upload Validation
-* Built-in Logging
+ISC © Emmanuel Abellana