@shadow-library/fastify 1.0.1 → 1.1.0

package/README.md

@@ -223,6 +223,89 @@ export class RoutesController {
 }
 ```
 
+#### Child Routes Configuration
+
+Child routes enable server-side route resolution, commonly used for SSR (Server-Side Rendering) and internal API composition. When enabled, you can make internal HTTP requests to your own routes without going through the network layer.
+
+**Basic Setup:**
+
+```typescript
+@Module({
+  imports: [
+    FastifyModule.forRoot({
+      controllers: [UserController, DataController],
+
+      // Enable child routes functionality
+      enableChildRoutes: true,
+
+      // Optional: Provide custom headers for child route requests
+      childRouteHeaders: () => ({
+        'x-correlation-id': '123',
+      }),
+    }),
+  ],
+})
+export class AppModule {}
+```
+
+**Usage in Controllers:**
+
+```typescript
+@HttpController('/api')
+export class DataAggregatorController {
+  constructor(@Inject(Router) private readonly fastifyRouter: FastifyRouter) {}
+
+  @Get('/dashboard')
+  async getDashboardData() {
+    // Make internal requests to other routes
+    const [users, posts, analytics] = await Promise.all([
+      this.fastifyRouter.resolveChildRoute('/api/users'),
+      this.fastifyRouter.resolveChildRoute('/api/posts?limit=10'),
+      this.fastifyRouter.resolveChildRoute('/api/analytics/summary'),
+    ]);
+
+    return {
+      dashboard: {
+        users,
+        posts,
+        analytics,
+        timestamp: new Date().toISOString(),
+      },
+    };
+  }
+}
+```
+
+**Custom Headers Function:**
+
+The `childRouteHeaders` function is called for each child route request, allowing you to:
+
+- Pass authentication context from the parent request
+- Include tenant/user-specific information
+- Add tracing or correlation IDs
+- Set internal service flags
+
+```typescript
+// Dynamic headers based on current request context
+childRouteHeaders: (contextService) => {
+  const request = contextService.getRequest();
+  return {
+    'x-user-id': contextService.get('currentUserId'),
+    'x-request-id': contextService.getRID(),
+    'x-forwarded-from': 'internal-aggregator',
+    'x-correlation-id': request.headers['x-correlation-id'],
+  };
+},
+```
+
+**Important Notes:**
+
+- Child routes always include the header `x-service: 'internal-child-route'`
+- Custom headers are merged with the default service header
+- If you provide an `x-service` header, it will be overridden with the default value
+- Child routes create isolated contexts, preventing middleware conflicts
+- Enable only when needed, as it adds routing overhead
+
 ## Configuration
 
 ### Dynamic Module Configuration
@@ -269,6 +352,12 @@ The module provides two configuration methods:
         '5xx': ErrorResponseSchema,
       },
 
+      // Child routes configuration (for SSR and internal route resolution)
+      enableChildRoutes: true,
+      childRouteHeaders: contextService => ({
+        'x-correlation-id': contextService.getRequest().headers['x-correlation-id'],
+      }),
+
       // Extend Fastify instance before registering controllers
       fastifyFactory: async fastify => {
         // Register plugins, add hooks, or configure Fastify
@@ -800,7 +889,7 @@ Check out the [examples](./examples) directory for complete working examples:
 
 - **hello-world**: Basic HTTP controller with GET/POST routes
 - **user-auth**: Advanced example with authentication guards
-- **child-routes**: Route resolution and unified endpoints
+- **child-routes**: Route resolution, unified endpoints, and custom headers for SSR
 
 ## Contributing
 

package/cjs/module/fastify-module.interface.d.ts

@@ -9,6 +9,7 @@ import { Promisable } from 'type-fest';
  * Importing user defined packages
  */
 import { ErrorHandler } from '../interfaces/index.js';
+import { ContextService } from '../services/index.js';
 /**
  * Defining types
  */
@@ -39,6 +40,11 @@ export interface FastifyConfig extends FastifyServerOptions {
      * @default false
      */
     enableChildRoutes?: boolean;
+    /**
+     * Function to provide custom headers for internal child route requests.
+     * Useful for passing authentication tokens or other necessary headers.
+     */
+    childRouteHeaders?: (contextService: ContextService) => Record<string, string>;
     /**
      * Masks fields marked as sensitive in API inputs (body, query, and URL params) when written to logs.
      * @default true

package/cjs/module/fastify-router.d.ts

@@ -82,7 +82,7 @@ export declare class FastifyRouter extends Router {
      * during SSR. Automatically reuses middleware results from the parent context to avoid
      * redundant execution and ensures correct context isolation for nested route data fetching.
      */
-    resolveChildRoute<T extends JsonValue = JsonObject>(url: string): Promise<T>;
+    resolveChildRoute<T extends JsonValue = JsonObject>(url: string, headers?: Record<string, string>): Promise<T>;
     mockRequest(): MockRequestChain;
     mockRequest(options: MockRequestOptions): Promise<MockResponse>;
 }

package/cjs/module/fastify-router.js

@@ -285,10 +285,12 @@ let FastifyRouter = class FastifyRouter extends app_1.Router {
      * during SSR. Automatically reuses middleware results from the parent context to avoid
      * redundant execution and ensures correct context isolation for nested route data fetching.
      */
-    async resolveChildRoute(url) {
+    async resolveChildRoute(url, headers = {}) {
         if (!this.childRouter)
             throw new common_1.InternalError('Child routes are not enabled');
-        const response = await this.instance.inject({ method: 'GET', url, headers: { 'x-service': 'internal-child-route' } });
+        const childHeaders = this.config.childRouteHeaders?.(this.context) ?? {};
+        Object.assign(headers, childHeaders, { 'x-service': 'internal-child-route' });
+        const response = await this.instance.inject({ method: 'GET', url, headers });
         return response.json();
     }
     mockRequest(options) {

package/esm/module/fastify-module.interface.d.ts

@@ -9,6 +9,7 @@ import { Promisable } from 'type-fest';
  * Importing user defined packages
  */
 import { ErrorHandler } from '../interfaces/index.js';
+import { ContextService } from '../services/index.js';
 /**
  * Defining types
  */
@@ -39,6 +40,11 @@ export interface FastifyConfig extends FastifyServerOptions {
      * @default false
      */
     enableChildRoutes?: boolean;
+    /**
+     * Function to provide custom headers for internal child route requests.
+     * Useful for passing authentication tokens or other necessary headers.
+     */
+    childRouteHeaders?: (contextService: ContextService) => Record<string, string>;
     /**
      * Masks fields marked as sensitive in API inputs (body, query, and URL params) when written to logs.
      * @default true

package/esm/module/fastify-router.d.ts

@@ -82,7 +82,7 @@ export declare class FastifyRouter extends Router {
      * during SSR. Automatically reuses middleware results from the parent context to avoid
      * redundant execution and ensures correct context isolation for nested route data fetching.
      */
-    resolveChildRoute<T extends JsonValue = JsonObject>(url: string): Promise<T>;
+    resolveChildRoute<T extends JsonValue = JsonObject>(url: string, headers?: Record<string, string>): Promise<T>;
     mockRequest(): MockRequestChain;
     mockRequest(options: MockRequestOptions): Promise<MockResponse>;
 }

package/esm/module/fastify-router.js

@@ -279,10 +279,12 @@ let FastifyRouter = class FastifyRouter extends Router {
      * during SSR. Automatically reuses middleware results from the parent context to avoid
      * redundant execution and ensures correct context isolation for nested route data fetching.
      */
-    async resolveChildRoute(url) {
+    async resolveChildRoute(url, headers = {}) {
         if (!this.childRouter)
             throw new InternalError('Child routes are not enabled');
-        const response = await this.instance.inject({ method: 'GET', url, headers: { 'x-service': 'internal-child-route' } });
+        const childHeaders = this.config.childRouteHeaders?.(this.context) ?? {};
+        Object.assign(headers, childHeaders, { 'x-service': 'internal-child-route' });
+        const response = await this.instance.inject({ method: 'GET', url, headers });
         return response.json();
     }
     mockRequest(options) {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@shadow-library/fastify",
   "type": "module",
-  "version": "1.0.1",
+  "version": "1.1.0",
   "sideEffects": false,
   "description": "A Fastify wrapper featuring decorator-based routing, middleware and error handling",
   "repository": {