feat: add support for forwarding proxy headers in template requests

- Updated `fetchTemplate` to include forwarded headers when fetching templates.
- Enhanced `wildcardRequestHandlerFactory` to forward template proxy headers.
- Modified `filterHeaders` to allow extra headers to be forwarded based on configuration.
- Introduced database migrations for new settings: `FragmentProxyHeaders` and `TemplateProxyHeaders`.
- Removed deprecated `fetch-template.js` and `filter-headers.js` files, refactoring their logic into new modules.

Author: stas-nc

docs/registry.md

@@ -10,9 +10,9 @@ Currently, Registry supports authentication only. All authenticated entities wil
 
 The following authentication providers are supported:
 
--   **OpenID Connect**. Turned **off** by default.
--   **Locally configured login/password**. Default credentials: `root` / `pwd`.
--   **Locally configured Bearer token** for API machine-to-machine access. Default credentials: `Bearer cm9vdF9hcGlfdG9rZW4=:dG9rZW5fc2VjcmV0` or `Bearer root_api_token:token_secret` after base64 decoding.
+- **OpenID Connect**. Turned **off** by default.
+- **Locally configured login/password**. Default credentials: `root` / `pwd`.
+- **Locally configured Bearer token** for API machine-to-machine access. Default credentials: `Bearer cm9vdF9hcGlfdG9rZW4=:dG9rZW5fc2VjcmV0` or `Bearer root_api_token:token_secret` after base64 decoding.
 
 You can change default credentials via Registry UI, in the `Auth entities` page, or via API.
 
@@ -56,9 +56,9 @@ links to the JS/CSS bundles in the Registry after each deployment.
 
 To do this, there are the following options (at least):
 
--   Manually via UI (_not recommended_)
--   Using Registry API (see [API](#api) section above)
--   **Using App Assets discovery mechanism**
+- Manually via UI (_not recommended_)
+- Using Registry API (see [API](#api) section above)
+- **Using App Assets discovery mechanism**
 
 When registering micro frontend in the ILC Registry, it is possible to set a file for the "Assets discovery url" that will be periodically fetched
 by the Registry. The idea is that this file will contain actual references to JS/CSS bundles and be updated on CDN **right after** every deployment.
@@ -195,3 +195,45 @@ Applications reference shared properties via the `configSelector` field.
 ### Domain properties
 
 See [Multi-domains documentation](multi-domains.md#domain-specific-properties) for information about configuring domain-specific properties.
+
+## Settings reference
+
+ILC behavior can be tuned via the Settings page in Registry UI (`/settings`) or through the `PUT /api/v1/settings/:key` API.
+
+### `fragmentProxyHeaders`
+
+| Key                    | Type       | Default | Scope |
+| ---------------------- | ---------- | ------- | ----- |
+| `fragmentProxyHeaders` | `string[]` | `null`  | `ilc` |
+
+A list of HTTP header names that ILC will forward from the incoming end-user request to **fragment SSR requests**. When ILC renders a micro-frontend server-side, the listed headers are copied from the browser request into the outgoing HTTP call to the fragment's SSR endpoint.
+
+Headers are matched case-insensitively. Headers present in the list but absent from the incoming request are silently skipped.
+
+**`null` (default)** — no extra headers are forwarded beyond the built-in set (see below).
+
+**Built-in headers always forwarded to fragments** (regardless of `fragmentProxyHeaders`):
+
+- `authorization`, `accept-language`, `referer`, `user-agent`, `cookie`
+- `x-request-uri`, `x-request-host`, `x-request-intl`
+- Any header whose name starts with `x-forwarded-`
+
+### `templateProxyHeaders`
+
+| Key                    | Type       | Default | Scope |
+| ---------------------- | ---------- | ------- | ----- |
+| `templateProxyHeaders` | `string[]` | `null`  | `ilc` |
+
+A list of HTTP header names that ILC will forward from the incoming end-user request to **template `<include>` fetches**. When the registry renders a template containing `<include src="…" />` tags, the listed headers are copied from the ILC→Registry request into the outgoing HTTP calls to each include source.
+
+Headers are matched case-insensitively. Headers present in the list but absent from the incoming request are silently skipped.
+
+**`null` (default)** — no extra headers are forwarded to include sources.
+
+**Example — forward tracing and routing headers to both targets:**
+
+```json
+["x-forwarded-for", "x-real-ip", "x-request-id"]
+```
+
+**Caching note:** template rendering results (including fetched `<include>` content) are cached by ILC keyed on the template name, domain, and the forwarded header values. Forwarded headers are therefore expected to be **static per deployment context** (e.g. set by a reverse proxy, not by individual users). Using headers with many unique values (e.g. per-user auth tokens) will create a large number of cache entries and trigger LRU eviction — a warning is logged when this occurs.

ilc/common/EvictingCacheStorage.spec.ts

@@ -48,6 +48,27 @@ describe('EvictingCacheStorage', () => {
         expect(cache.getItem('d')).to.deep.equal({ data: 4, cachedAt: 1 });
     });
 
+    it('should call onEvict with the evicted key when maxSize is exceeded', () => {
+        const evicted: string[] = [];
+        const c = new EvictingCacheStorage({ maxSize: 2, onEvict: (key) => evicted.push(key) });
+
+        c.setItem('a', { data: 1, cachedAt: 1 });
+        c.setItem('b', { data: 2, cachedAt: 1 });
+        c.setItem('c', { data: 3, cachedAt: 1 }); // evicts 'a'
+
+        expect(evicted).to.deep.equal(['a']);
+    });
+
+    it('should not call onEvict when maxSize is not exceeded', () => {
+        const evicted: string[] = [];
+        const c = new EvictingCacheStorage({ maxSize: 3, onEvict: (key) => evicted.push(key) });
+
+        c.setItem('a', { data: 1, cachedAt: 1 });
+        c.setItem('b', { data: 2, cachedAt: 1 });
+
+        expect(evicted).to.deep.equal([]);
+    });
+
     it('should overwrite an existing key and reorder it', () => {
         cache.setItem('a', { data: 1, cachedAt: 1 });
         cache.setItem('b', { data: 2, cachedAt: 1 });

ilc/common/EvictingCacheStorage.ts

@@ -2,6 +2,7 @@ import { CacheResult, CacheStorage } from './types/CacheWrapper';
 
 type EvictingCacheStorageOptions = {
     maxSize: number;
+    onEvict?: (evictedKey: string) => void;
 };
 
 export class EvictingCacheStorage implements CacheStorage {
@@ -34,6 +35,7 @@ export class EvictingCacheStorage implements CacheStorage {
         if (this.cache.size > this.options.maxSize) {
             const oldestKey = this.cache.keys().next().value!; // Get the first key (LRU)
             this.cache.delete(oldestKey);
+            this.options.onEvict?.(oldestKey);
         }
     }
 }

ilc/server/registry/Registry.js

@@ -47,14 +47,14 @@ module.exports = class Registry {
             return filteredData;
         };
 
-        this.getTemplate = async (templateName, { locale, forDomain, routeKey } = {}) => {
+        this.getTemplate = async (templateName, { locale, forDomain, routeKey, forwardedHeaders } = {}) => {
             if (templateName === '500' && forDomain) {
                 const routerDomains = await this.getRouterDomains();
                 const redefined500 = routerDomains.data.find((item) => item.domainName === forDomain)?.template500;
                 templateName = redefined500 || templateName;
             }
 
-            return await getTemplateMemoized(templateName, { locale, domain: forDomain, routeKey });
+            return await getTemplateMemoized(templateName, { locale, domain: forDomain, routeKey, forwardedHeaders });
         };
     }
 
@@ -115,7 +115,7 @@ module.exports = class Registry {
 
     // Note: `routeKey` is intentionally unused here — it serves as a cache key differentiator
     // in the memoization layer (via JSON.stringify of args) to prevent cache collisions across routes.
-    #getTemplate = async (templateName, { locale, domain, routeKey: _routeKey }) => {
+    #getTemplate = async (templateName, { locale, domain, routeKey: _routeKey, forwardedHeaders = undefined }) => {
         if (!VALID_TEMPLATE_NAME.test(templateName)) {
             throw new ValidationRegistryError({
                 message: `Invalid template name ${templateName}`,
@@ -143,7 +143,10 @@ module.exports = class Registry {
 
         let res;
         try {
-            res = await axios.get(tplUrl, { responseType: 'json' });
+            res = await axios.get(tplUrl, {
+                responseType: 'json',
+                headers: forwardedHeaders,
+            });
         } catch (error) {
             if (axios.isAxiosError(error) && error.response?.status === 404) {
                 throw new NotFoundRegistryError({

ilc/server/registry/factory.ts

@@ -9,7 +9,20 @@ export const registryFactory = () => {
     const logger = reportPlugin.getLogger();
     return new Registry(
         config.get('registry.address'),
-        new DefaultCacheWrapper(new EvictingCacheStorage({ maxSize: 1000 }), logger, context),
+        new DefaultCacheWrapper(
+            new EvictingCacheStorage({
+                maxSize: 1000,
+                onEvict: (key) =>
+                    logger.warn(
+                        { key },
+                        'ILC registry cache eviction: maxSize (1000) exceeded. ' +
+                            'This may be caused by templateProxyHeaders producing too many unique cache keys. ' +
+                            'Consider reducing the number of distinct proxy header value combinations.',
+                    ),
+            }),
+            logger,
+            context,
+        ),
         logger,
     );
 };

ilc/server/routes/wildcardRequestHandlerFactory.spec.ts

@@ -530,6 +530,7 @@ describe('wildcardRequestHandlerFactory', () => {
                 locale: 'en-US',
                 forDomain: 'test.com',
                 routeKey: '/test',
+                forwardedHeaders: undefined,
             });
         });
 
@@ -557,6 +558,65 @@ describe('wildcardRequestHandlerFactory', () => {
                 locale: 'fr-FR',
                 forDomain: 'test.com',
                 routeKey: '/test',
+                forwardedHeaders: undefined,
+            });
+        });
+
+        it('should forward templateProxyHeaders to getTemplate when configured', async () => {
+            mockRegistryService.getConfig.resolves({
+                settings: {
+                    trailingSlash: 'disabled',
+                    overrideConfigTrustedOrigins: ['localhost'],
+                    i18n: {
+                        enabled: false,
+                        supported: { locale: {}, currency: {} },
+                        default: { locale: 'en-US', currency: 'USD' },
+                    },
+                    templateProxyHeaders: ['X-Forwarded-For', 'X-Real-IP'],
+                },
+                routes: [
+                    {
+                        routeId: 'test-route',
+                        route: '/test',
+                        next: false,
+                        slots: {},
+                        template: 'test-template',
+                    },
+                ],
+                apps: {},
+            } as any);
+
+            const mockRequest = {
+                host: 'test.com',
+                headers: {
+                    'x-forwarded-for': '1.2.3.4',
+                    'x-real-ip': '5.6.7.8',
+                    'x-secret': 'should-not-forward',
+                },
+                log: mockLogger,
+                raw: {
+                    url: '/test',
+                    ilcState: { locale: 'en-US' },
+                },
+            };
+
+            const mockReply = {
+                redirect: sinon.stub(),
+                header: sinon.stub(),
+                status: sinon.stub().returns({ send: sinon.stub() }),
+                res: {},
+            };
+
+            await wildcardRequestHandler.call({} as any, mockRequest as any, mockReply as any);
+
+            sinon.assert.calledWith(mockRegistryService.getTemplate, 'test-template', {
+                locale: 'en-US',
+                forDomain: 'test.com',
+                routeKey: '/test',
+                forwardedHeaders: {
+                    'x-forwarded-for': '1.2.3.4',
+                    'x-real-ip': '5.6.7.8',
+                },
             });
         });
     });

ilc/server/routes/wildcardRequestHandlerFactory.ts

@@ -7,6 +7,7 @@ import i18n from '../i18n';
 import CspBuilderService from '../services/CspBuilderService';
 import tailorFactory from '../tailor/factory';
 import { mergeConfigs, type OverrideConfig } from '../tailor/merge-configs';
+import { buildForwardedHeaders } from '../utils/helpers';
 import parseOverrideConfig from '../tailor/parse-override-config';
 import ServerRouter from '../tailor/server-router';
 import { TransitionHooksExecutor } from '../TransitionHooksExecutor';
@@ -98,10 +99,15 @@ export function wildcardRequestHandlerFactory(
         if (isRouteWithoutSlots) {
             const locale = req.raw.ilcState?.locale;
             const routeKey = route.route || `special:${route.specialRole}`;
+            const forwardedHeaders = buildForwardedHeaders(
+                finalRegistryConfig.settings.templateProxyHeaders,
+                req.headers,
+            );
             const { data } = await registryService.getTemplate(route.template, {
                 locale,
                 forDomain: currentDomain,
                 routeKey,
+                forwardedHeaders,
             });
 
             reply.header('Content-Type', 'text/html');

ilc/server/tailor/factory.js

@@ -4,8 +4,8 @@ const _ = require('lodash');
 const newrelic = require('newrelic');
 
 const Tailor = require('@namecheap/tailorx');
-const fetchTemplate = require('./fetch-template');
-const filterHeaders = require('./filter-headers');
+const { fetchTemplate } = require('./fetch-template');
+const { filterHeaders } = require('./filter-headers');
 const errorHandlerSetup = require('./error-handler');
 const fragmentHooks = require('./fragment-hooks');
 const ConfigsInjector = require('./configs-injector');