feat: custom 404 response via headers

src/app/index.ts

@@ -41,6 +41,8 @@ import * as types from './types';
 import { IlcIntl } from './IlcIntl';
 import defaultIntlAdapter from './defaultIntlAdapter';
 import { IIlcAppSdk } from './interfaces/IIlcAppSdk';
+import { Render404 } from './interfaces/common';
+import ResponseStatus from './interfaces/ResponseStatus';
 
 export * from './types';
 export * from './GlobalBrowserApi';
@@ -74,13 +76,32 @@ export default class IlcAppSdk implements IIlcAppSdk {
     }
     /**
      * Isomorphic method to render 404 page.
+     * GLOBAL 404:
      * At SSR in processResponse it sets 404 status code to response.
      * At CSR it triggers global event which ILC listens and renders 404 page.
+     *
+     * CUSTOM 404:
+     * At SSR in processResponse it sets 404 status code and "X-ILC-Override" header to response.
+     * At CSR it renders own not found component from fragment.
      */
-    render404 = () => {
-        if (this.adapter.setStatusCode) {
-            this.adapter.setStatusCode(404);
-        } else {
+    render404: Render404 = (isCustomPage) => {
+        // SSR
+        if (this.adapter.setStatus) {
+            const status: ResponseStatus = {
+                code: 404,
+            };
+
+            if (isCustomPage) {
+                status.headers = {
+                    ['X-ILC-Override']: 'error-page-content',
+                };
+            }
+            this.adapter.setStatus(status);
+            return;
+        }
+
+        // CSR
+        if (!isCustomPage) {
             window.dispatchEvent(
                 new CustomEvent('ilc:404', {
                     detail: { appId: this.appId },

src/app/interfaces/ResponseStatus.ts

@@ -0,0 +1,6 @@
+type ResponseStatus = {
+    code?: number;
+    headers?: Record<string, string>;
+};
+
+export default ResponseStatus;

src/app/interfaces/common.ts

@@ -1,3 +1,5 @@
+import ResponseStatus from './ResponseStatus';
+
 /**
  * Result of the "processRequest" method
  */
@@ -27,11 +29,11 @@ export interface AppSdkAdapter {
     /** Unique application ID, if same app will be rendered twice on a page - it will get different IDs */
     appId: string;
     intl: IntlAdapter | null;
-    setStatusCode: (code: number) => void;
-    getStatusCode: () => number | undefined;
+    setStatus: (data: ResponseStatus) => void;
+    getStatus: () => ResponseStatus | undefined;
 }
 
-export type Render404 = () => void;
+export type Render404 = (isCustomPage?: boolean) => void;
 
 export interface IntlConfig {
     locale?: string;

src/server/IlcSdk.ts

@@ -5,6 +5,7 @@ import { intlSchema } from './IlcProtocol';
 import defaultIntlAdapter from '../app/defaultIntlAdapter';
 import * as clientTypes from '../app/interfaces/common';
 import { IlcSdkLogger } from './IlcSdkLogger';
+import ResponseStatus from '../app/interfaces/ResponseStatus';
 
 /**
  * Entrypoint for SDK that should be used within application server that executes SSR bundle
@@ -55,7 +56,7 @@ export class IlcSdk {
             originalUri = '/';
         }
 
-        let statusCode: number | undefined;
+        let responseStatus: ResponseStatus;
 
         return {
             getCurrentReqHost: () => host,
@@ -65,10 +66,10 @@ export class IlcSdk {
             getCurrentPathProps: () => passedProps,
             appId,
             intl: this.parseIntl(req),
-            setStatusCode: (code) => {
-                statusCode = code;
+            setStatus: (status) => {
+                responseStatus = status;
             },
-            getStatusCode: () => statusCode,
+            getStatus: () => responseStatus,
         };
     }
 
@@ -78,9 +79,14 @@ export class IlcSdk {
      * **WARNING:** this method should be called before response headers were send.
      */
     public processResponse(reqData: types.RequestData, res: ServerResponse, data?: types.ResponseData): void {
-        const statusCode = reqData.getStatusCode();
-        if (statusCode) {
-            res.statusCode = statusCode;
+        const status = reqData.getStatus();
+        if (status?.code) {
+            res.statusCode = status.code;
+        }
+        if (status?.headers) {
+            for (const [key, value] of Object.entries(status.headers)) {
+                res.setHeader(key, value);
+            }
         }
 
         if (!data) {

test/server/IlcSdk.spec.ts

@@ -292,19 +292,40 @@ describe('IlcSdk', () => {
             );
         });
 
-        it('should set 404 status code', () => {
+        it('should set 404 status code without headers', () => {
             const NotFound = 404;
 
             const req = new MockReq(merge({}, defReq));
             const res = new MockRes();
 
             const pRes = ilcSdk.processRequest(req);
-            pRes.setStatusCode(NotFound);
+            pRes.setStatus({ code: NotFound });
             ilcSdk.processResponse(pRes, res);
 
             expect(res.statusCode).to.eq(NotFound);
         });
 
+        it('should set 404 status code and header for custom error', () => {
+            const NotFound = 404;
+            const NotFoundHeaderKey = 'X-ILC-Override';
+            const NotFoundHeaderValue = 'error-page-content';
+
+            const req = new MockReq(merge({}, defReq));
+            const res = new MockRes();
+
+            const pRes = ilcSdk.processRequest(req);
+            pRes.setStatus({
+                code: NotFound,
+                headers: {
+                    [NotFoundHeaderKey]: NotFoundHeaderValue,
+                },
+            });
+            ilcSdk.processResponse(pRes, res);
+
+            expect(res.statusCode).to.eq(NotFound);
+            expect(res.getHeader(NotFoundHeaderKey)).to.eq(NotFoundHeaderValue);
+        });
+
         describe('appAssets', () => {
             it('should handle absolute URLs', () => {
                 const req = new MockReq(merge({}, defReq));