Add support for custom JS embeds in the App (#16650)

* add embed hook definitions

* inject embeds in the App html

* fixed typo

* removed unnecessary env parameter

* Added comment marking the custom embeds

* attempt to add test for createApp

* mock db in app test

* temporarily set log style to raw in test

* one more round

Co-authored-by: Azri Kahar <42867097+azrikahar@users.noreply.github.com>

api/src/app.test.ts

@@ -0,0 +1,204 @@
+import { Router } from 'express';
+import request from 'supertest';
+import { describe, expect, test, vi } from 'vitest';
+
+import createApp from './app';
+import { ROBOTSTXT } from './constants';
+
+vi.mock('./database', () => ({
+	default: vi.fn(),
+	getDatabaseClient: vi.fn().mockReturnValue('postgres'),
+	isInstalled: vi.fn(),
+	validateDatabaseConnection: vi.fn(),
+	validateDatabaseExtensions: vi.fn(),
+	validateMigrations: vi.fn(),
+}));
+
+vi.mock('./env', async () => {
+	const actual = (await vi.importActual('./env')) as { default: Record<string, any> };
+
+	return {
+		default: {
+			...actual.default,
+			KEY: 'xxxxxxx-xxxxxx-xxxxxxxx-xxxxxxxxxx',
+			SECRET: 'abcdef',
+			SERVE_APP: true,
+			PUBLIC_URL: 'http://localhost:8055/directus',
+			TELEMETRY: false,
+			LOG_STYLE: 'raw',
+		},
+	};
+});
+
+const mockGetEndpointRouter = vi.fn().mockReturnValue(Router());
+const mockGetEmbeds = vi.fn().mockReturnValue({ head: '', body: '' });
+
+vi.mock('./extensions', () => ({
+	getExtensionManager: vi.fn().mockImplementation(() => {
+		return {
+			initialize: vi.fn(),
+			getEndpointRouter: mockGetEndpointRouter,
+			getEmbeds: mockGetEmbeds,
+		};
+	}),
+}));
+
+vi.mock('./flows', () => ({
+	getFlowManager: vi.fn().mockImplementation(() => {
+		return {
+			initialize: vi.fn(),
+		};
+	}),
+}));
+
+vi.mock('./middleware/check-ip', () => ({
+	checkIP: Router(),
+}));
+
+vi.mock('./middleware/schema', () => ({
+	default: Router(),
+}));
+
+vi.mock('./middleware/get-permissions', () => ({
+	default: Router(),
+}));
+
+vi.mock('./auth', () => ({
+	registerAuthProviders: vi.fn(),
+}));
+
+vi.mock('./webhooks', () => ({
+	init: vi.fn(),
+}));
+
+describe('createApp', async () => {
+	describe('Content Security Policy', () => {
+		test('Should set content-security-policy header by default', async () => {
+			const app = await createApp();
+			const response = await request(app).get('/');
+
+			expect(response.headers).toHaveProperty('content-security-policy');
+		});
+	});
+
+	describe('Root Redirect', () => {
+		test('Should redirect root path by default', async () => {
+			const app = await createApp();
+			const response = await request(app).get('/');
+
+			expect(response.status).toEqual(302);
+		});
+	});
+
+	describe('robots.txt file', () => {
+		test('Should respond with default robots.txt content', async () => {
+			const app = await createApp();
+			const response = await request(app).get('/robots.txt');
+
+			expect(response.text).toEqual(ROBOTSTXT);
+		});
+	});
+
+	describe('Admin App', () => {
+		test('Should set <base /> tag href to public url with admin relative path', async () => {
+			const app = await createApp();
+			const response = await request(app).get('/admin');
+
+			expect(response.text).toEqual(expect.stringContaining(`<base href="/directus/admin/" />`));
+		});
+
+		test('Should remove <embed-head /> and <embed-body /> tags when there are no custom embeds', async () => {
+			mockGetEmbeds.mockReturnValueOnce({ head: '', body: '' });
+
+			const app = await createApp();
+			const response = await request(app).get('/admin');
+
+			expect(response.text).not.toEqual(expect.stringContaining(`<embed-head />`));
+			expect(response.text).not.toEqual(expect.stringContaining(`<embed-body />`));
+		});
+
+		test('Should replace <embed-head /> tag with custom embed head', async () => {
+			const mockEmbedHead = '<!-- Test Embed Head -->';
+			mockGetEmbeds.mockReturnValueOnce({ head: mockEmbedHead, body: '' });
+
+			const app = await createApp();
+			const response = await request(app).get('/admin');
+
+			expect(response.text).toEqual(expect.stringContaining(mockEmbedHead));
+		});
+
+		test('Should replace <embed-body /> tag with custom embed body', async () => {
+			const mockEmbedBody = '<!-- Test Embed Body -->';
+			mockGetEmbeds.mockReturnValueOnce({ head: '', body: mockEmbedBody });
+
+			const app = await createApp();
+			const response = await request(app).get('/admin');
+
+			expect(response.text).toEqual(expect.stringContaining(mockEmbedBody));
+		});
+	});
+
+	describe('Server ping endpoint', () => {
+		test('Should respond with pong', async () => {
+			const app = await createApp();
+			const response = await request(app).get('/server/ping');
+
+			expect(response.text).toEqual('pong');
+		});
+	});
+
+	describe('Custom Endpoints', () => {
+		test('Should not contain route for custom endpoint', async () => {
+			const testRoute = '/custom-endpoint-to-test';
+
+			const app = await createApp();
+			const response = await request(app).get(testRoute);
+
+			expect(response.body).toEqual({
+				errors: [
+					{
+						extensions: {
+							code: 'ROUTE_NOT_FOUND',
+						},
+						message: `Route ${testRoute} doesn't exist.`,
+					},
+				],
+			});
+		});
+
+		test('Should contain route for custom endpoint', async () => {
+			const testRoute = '/custom-endpoint-to-test';
+			const testResponse = { key: 'value' };
+			const mockRouter = Router();
+			mockRouter.use(testRoute, (_, res) => {
+				res.json(testResponse);
+			});
+			mockGetEndpointRouter.mockReturnValueOnce(mockRouter);
+
+			const app = await createApp();
+			const response = await request(app).get(testRoute);
+
+			expect(response.body).toEqual(testResponse);
+		});
+	});
+
+	describe('Not Found Handler', () => {
+		test('Should return ROUTE_NOT_FOUND error when a route does not exist', async () => {
+			const testRoute = '/this-route-does-not-exist';
+
+			const app = await createApp();
+			const response = await request(app).get(testRoute);
+
+			expect(response.body).toEqual({
+				errors: [
+					{
+						extensions: {
+							code: 'ROUTE_NOT_FOUND',
+						},
+						message: `Route ${testRoute} doesn't exist.`,
+					},
+				],
+			});
+		});
+	});
+});

api/src/app.ts

@@ -183,14 +183,19 @@ export default async function createApp(): Promise<express.Application> {
 		const adminPath = require.resolve('@directus/app');
 		const adminUrl = new Url(env.PUBLIC_URL).addPath('admin');
 
+		const embeds = extensionManager.getEmbeds();
+
 		// Set the App's base path according to the APIs public URL
 		const html = await fse.readFile(adminPath, 'utf8');
-		const htmlWithBase = html.replace(/<base \/>/, `<base href="${adminUrl.toString({ rootRelative: true })}/" />`);
+		const htmlWithVars = html
+			.replace(/<base \/>/, `<base href="${adminUrl.toString({ rootRelative: true })}/" />`)
+			.replace(/<embed-head \/>/, embeds.head)
+			.replace(/<embed-body \/>/, embeds.body);
 
 		const sendHtml = (_req: Request, res: Response) => {
 			res.setHeader('Cache-Control', 'no-cache');
 			res.setHeader('Vary', 'Origin, Cache-Control');
-			res.send(htmlWithBase);
+			res.send(htmlWithVars);
 		};
 
 		const setStaticHeaders = (res: ServerResponse) => {

api/src/extensions.ts

@@ -18,6 +18,7 @@ import {
 	HookConfig,
 	HybridExtension,
 	InitHandler,
+	EmbedHandler,
 	OperationApiConfig,
 	ScheduleHandler,
 } from '@directus/shared/types';
@@ -98,6 +99,8 @@ class ExtensionManager {
 	private apiEmitter: Emitter;
 	private hookEvents: EventHandler[] = [];
 	private endpointRouter: Router;
+	private hookEmbedsHead: string[] = [];
+	private hookEmbedsBody: string[] = [];
 
 	private reloadQueue: JobQueue;
 	private watcher: FSWatcher | null = null;
@@ -188,6 +191,18 @@ class ExtensionManager {
 		return this.endpointRouter;
 	}
 
+	public getEmbeds() {
+		return {
+			head: wrapEmbeds('Custom Embed Head', this.hookEmbedsHead),
+			body: wrapEmbeds('Custom Embed Body', this.hookEmbedsBody),
+		};
+
+		function wrapEmbeds(label: string, content: string[]): string {
+			if (content.length === 0) return '';
+			return `<!-- Start ${label} -->\n${content.join('\n')}\n<!-- End ${label} -->`;
+		}
+	}
+
 	private async load(): Promise<void> {
 		try {
 			await ensureExtensionDirs(env.EXTENSIONS_PATH, env.SERVE_APP ? EXTENSION_TYPES : API_OR_HYBRID_EXTENSION_TYPES);
@@ -489,6 +504,19 @@ class ExtensionManager {
 					logger.warn(`Couldn't register cron hook. Provided cron is invalid: ${cron}`);
 				}
 			},
+			embed: (position: 'head' | 'body', code: string | EmbedHandler) => {
+				const content = typeof code === 'function' ? code() : code;
+				if (content.trim().length === 0) {
+					logger.warn(`Couldn't register embed hook. Provided code is empty!`);
+					return;
+				}
+				if (position === 'head') {
+					this.hookEmbedsHead.push(content);
+				}
+				if (position === 'body') {
+					this.hookEmbedsBody.push(content);
+				}
+			},
 		};
 
 		register(registerFunctions, {

app/index.html

@@ -23,6 +23,7 @@
 		<link rel="mask-icon" href="/img/icons/safari-pinned-tab.svg" color="#263238" />
 		<title>Loading&hellip;</title>
 		<style id="custom-css"></style>
+		<embed-head />
 	</head>
 	<body class="auto">
 		<noscript>
@@ -35,5 +36,6 @@
 		<div id="menu-outlet"></div>
 
 		<script type="module" src="/src/main.ts"></script>
+		<embed-body />
 	</body>
 </html>

packages/shared/src/types/events.ts

@@ -16,3 +16,4 @@ export type FilterHandler<T = unknown> = (
 export type ActionHandler = (meta: Record<string, any>, context: EventContext) => void;
 export type InitHandler = (meta: Record<string, any>) => void;
 export type ScheduleHandler = () => void | Promise<void>;
+export type EmbedHandler = () => string;

packages/shared/src/types/hooks.ts

@@ -1,4 +1,4 @@
-import { ActionHandler, FilterHandler, InitHandler, ScheduleHandler } from './events';
+import { ActionHandler, FilterHandler, InitHandler, ScheduleHandler, EmbedHandler } from './events';
 import { ApiExtensionContext } from './extensions';
 
 type HookExtensionContext = ApiExtensionContext & {
@@ -10,6 +10,7 @@ type RegisterFunctions = {
 	action: (event: string, handler: ActionHandler) => void;
 	init: (event: string, handler: InitHandler) => void;
 	schedule: (cron: string, handler: ScheduleHandler) => void;
+	embed: (position: 'head' | 'body', code: string | EmbedHandler) => void;
 };
 
 type HookConfigFunction = (register: RegisterFunctions, context: HookExtensionContext) => void;