@ecopages/core 0.2.0-alpha.4 → 0.2.0-alpha.6

package/src/services/html/html-rewriter-provider.service.test.ts

@@ -0,0 +1,183 @@
+import { describe, expect, it } from 'vitest';
+import {
+	DefaultHtmlRewriterProvider,
+	type HtmlRewriterElement,
+	type HtmlRewriterLogger,
+	type HtmlRewriterRuntime,
+} from './html-rewriter-provider.service';
+
+type HtmlRewriterHandler = {
+	element: (element: HtmlRewriterElement) => void;
+};
+
+class TestHtmlRewriter implements HtmlRewriterRuntime {
+	private handlers = new Map<'head' | 'body', HtmlRewriterHandler>();
+
+	on(selector: 'head' | 'body', handler: HtmlRewriterHandler): TestHtmlRewriter {
+		this.handlers.set(selector, handler);
+		return this;
+	}
+
+	transform(response: Response): Response {
+		return response;
+	}
+}
+
+class TestLogger implements HtmlRewriterLogger {
+	public warnings: string[] = [];
+
+	warn(message: string) {
+		this.warnings.push(message);
+	}
+}
+
+describe('DefaultHtmlRewriterProvider', () => {
+	it('should prefer the native html rewriter in auto mode', async () => {
+		let workerToolsLoads = 0;
+
+		const provider = new DefaultHtmlRewriterProvider({
+			getNativeHtmlRewriter: () => TestHtmlRewriter,
+			loadWorkerToolsHtmlRewriter: async () => {
+				workerToolsLoads += 1;
+				return TestHtmlRewriter;
+			},
+		});
+
+		const htmlRewriter = await provider.createHtmlRewriter();
+
+		expect(htmlRewriter).toBeInstanceOf(TestHtmlRewriter);
+		expect(workerToolsLoads).toBe(0);
+	});
+
+	it('should load worker-tools when auto mode has no native runtime', async () => {
+		let workerToolsLoads = 0;
+
+		const provider = new DefaultHtmlRewriterProvider({
+			getNativeHtmlRewriter: () => undefined,
+			loadWorkerToolsHtmlRewriter: async () => {
+				workerToolsLoads += 1;
+				return TestHtmlRewriter;
+			},
+		});
+
+		const htmlRewriter = await provider.createHtmlRewriter();
+
+		expect(htmlRewriter).toBeInstanceOf(TestHtmlRewriter);
+		expect(workerToolsLoads).toBe(1);
+	});
+
+	it('should allow forcing worker-tools mode even when native is available', async () => {
+		let workerToolsLoads = 0;
+
+		const provider = new DefaultHtmlRewriterProvider({
+			mode: 'worker-tools',
+			getNativeHtmlRewriter: () => TestHtmlRewriter,
+			loadWorkerToolsHtmlRewriter: async () => {
+				workerToolsLoads += 1;
+				return TestHtmlRewriter;
+			},
+		});
+
+		const htmlRewriter = await provider.createHtmlRewriter();
+
+		expect(htmlRewriter).toBeInstanceOf(TestHtmlRewriter);
+		expect(workerToolsLoads).toBe(1);
+	});
+
+	it('should allow forcing fallback mode', async () => {
+		let workerToolsLoads = 0;
+
+		const provider = new DefaultHtmlRewriterProvider({
+			mode: 'fallback',
+			getNativeHtmlRewriter: () => TestHtmlRewriter,
+			loadWorkerToolsHtmlRewriter: async () => {
+				workerToolsLoads += 1;
+				return TestHtmlRewriter;
+			},
+		});
+
+		const htmlRewriter = await provider.createHtmlRewriter();
+
+		expect(htmlRewriter).toBeNull();
+		expect(workerToolsLoads).toBe(0);
+	});
+
+	it('should warn and fall back when native mode is forced without a runtime implementation', async () => {
+		const logger = new TestLogger();
+
+		const provider = new DefaultHtmlRewriterProvider({
+			mode: 'native',
+			logger,
+			getNativeHtmlRewriter: () => undefined,
+		});
+
+		const htmlRewriter = await provider.createHtmlRewriter();
+
+		expect(htmlRewriter).toBeNull();
+		expect(logger.warnings).toEqual([
+			'[HtmlTransformerService] Native HTMLRewriter was forced but is unavailable, falling back to string injection.',
+		]);
+	});
+
+	it('should reset the cached constructor when the mode changes', async () => {
+		let workerToolsLoads = 0;
+
+		const provider = new DefaultHtmlRewriterProvider({
+			getNativeHtmlRewriter: () => undefined,
+			loadWorkerToolsHtmlRewriter: async () => {
+				workerToolsLoads += 1;
+				return TestHtmlRewriter;
+			},
+		});
+
+		await provider.createHtmlRewriter();
+		await provider.createHtmlRewriter();
+		provider.setMode('fallback');
+		const fallbackHtmlRewriter = await provider.createHtmlRewriter();
+
+		expect(workerToolsLoads).toBe(1);
+		expect(fallbackHtmlRewriter).toBeNull();
+	});
+
+	it('should allow switching back to worker-tools after fallback mode', async () => {
+		let workerToolsLoads = 0;
+
+		const provider = new DefaultHtmlRewriterProvider({
+			mode: 'fallback',
+			getNativeHtmlRewriter: () => undefined,
+			loadWorkerToolsHtmlRewriter: async () => {
+				workerToolsLoads += 1;
+				return TestHtmlRewriter;
+			},
+		});
+
+		await provider.createHtmlRewriter();
+		provider.setMode('worker-tools');
+		const htmlRewriter = await provider.createHtmlRewriter();
+
+		expect(htmlRewriter).toBeInstanceOf(TestHtmlRewriter);
+		expect(workerToolsLoads).toBe(1);
+	});
+
+	it('should return null when worker-tools loading fails', async () => {
+		const logger = new TestLogger();
+
+		const provider = new DefaultHtmlRewriterProvider({
+			logger,
+			getNativeHtmlRewriter: () => undefined,
+			loadWorkerToolsHtmlRewriter: async () => {
+				logger.warn(
+					'[HtmlTransformerService] Failed to load @worker-tools/html-rewriter/base64, falling back to string injection: test failure',
+				);
+				return null;
+			},
+		});
+
+		const htmlRewriter = await provider.createHtmlRewriter();
+
+		expect(htmlRewriter).toBeNull();
+		expect(logger.warnings).toEqual([
+			'[HtmlTransformerService] Failed to load @worker-tools/html-rewriter/base64, falling back to string injection: test failure',
+		]);
+	});
+});

package/src/services/html/html-rewriter-provider.service.ts

@@ -0,0 +1,103 @@
+import { appLogger } from '../../global/app-logger.js';
+
+export type HtmlRewriterElement = {
+	append(content: string, options?: { html?: boolean }): void;
+};
+
+export type HtmlRewriterRuntime = {
+	on(selector: 'head' | 'body', handler: { element: (element: HtmlRewriterElement) => void }): HtmlRewriterRuntime;
+	transform(response: Response): Response;
+};
+
+export type HtmlRewriterConstructor = new () => HtmlRewriterRuntime;
+
+export type HtmlRewriterMode = 'auto' | 'native' | 'worker-tools' | 'fallback';
+
+export interface HtmlRewriterProvider {
+	createHtmlRewriter(): Promise<HtmlRewriterRuntime | null>;
+	setMode(mode: HtmlRewriterMode): void;
+}
+
+export interface HtmlRewriterLogger {
+	warn(message: string): void;
+}
+
+export interface DefaultHtmlRewriterProviderOptions {
+	mode?: HtmlRewriterMode;
+	logger?: HtmlRewriterLogger;
+	getNativeHtmlRewriter?: () => HtmlRewriterConstructor | undefined;
+	loadWorkerToolsHtmlRewriter?: () => Promise<HtmlRewriterConstructor | null>;
+}
+
+export class DefaultHtmlRewriterProvider implements HtmlRewriterProvider {
+	private htmlRewriterConstructorPromise?: Promise<HtmlRewriterConstructor | null>;
+	private htmlRewriterMode: HtmlRewriterMode;
+	private logger: HtmlRewriterLogger;
+	private getNativeHtmlRewriter: () => HtmlRewriterConstructor | undefined;
+	private loadWorkerToolsHtmlRewriter: () => Promise<HtmlRewriterConstructor | null>;
+
+	constructor(options: DefaultHtmlRewriterProviderOptions = {}) {
+		this.htmlRewriterMode = options.mode ?? 'auto';
+		this.logger = options.logger ?? appLogger;
+		this.getNativeHtmlRewriter =
+			options.getNativeHtmlRewriter ??
+			(() => (globalThis as { HTMLRewriter?: HtmlRewriterConstructor }).HTMLRewriter);
+		this.loadWorkerToolsHtmlRewriter = options.loadWorkerToolsHtmlRewriter ?? loadWorkerToolsHtmlRewriter;
+	}
+
+	setMode(mode: HtmlRewriterMode) {
+		this.htmlRewriterMode = mode;
+		this.htmlRewriterConstructorPromise = undefined;
+	}
+
+	async createHtmlRewriter(): Promise<HtmlRewriterRuntime | null> {
+		const RuntimeHtmlRewriter = await this.resolveHtmlRewriterConstructor();
+		return RuntimeHtmlRewriter ? new RuntimeHtmlRewriter() : null;
+	}
+
+	private async resolveHtmlRewriterConstructor(): Promise<HtmlRewriterConstructor | null> {
+		if (!this.htmlRewriterConstructorPromise) {
+			const mode = this.htmlRewriterMode;
+			const RuntimeHtmlRewriter = this.getNativeHtmlRewriter();
+
+			if (mode === 'fallback') {
+				this.htmlRewriterConstructorPromise = Promise.resolve(null);
+			} else if (mode === 'native') {
+				if (RuntimeHtmlRewriter) {
+					this.htmlRewriterConstructorPromise = Promise.resolve(RuntimeHtmlRewriter);
+				} else {
+					this.logger.warn(
+						'[HtmlTransformerService] Native HTMLRewriter was forced but is unavailable, falling back to string injection.',
+					);
+					this.htmlRewriterConstructorPromise = Promise.resolve(null);
+				}
+			} else if (mode === 'auto' && RuntimeHtmlRewriter) {
+				this.htmlRewriterConstructorPromise = Promise.resolve(RuntimeHtmlRewriter);
+			} else {
+				this.htmlRewriterConstructorPromise = this.loadWorkerToolsHtmlRewriter();
+			}
+		}
+
+		return this.htmlRewriterConstructorPromise;
+	}
+}
+
+async function loadWorkerToolsHtmlRewriter(): Promise<HtmlRewriterConstructor | null> {
+	try {
+		const module = await import('@worker-tools/html-rewriter/base64');
+		return module.HTMLRewriter as HtmlRewriterConstructor;
+	} catch (primaryError) {
+		try {
+			const runtimeLocalModule = await import(
+				new URL('../node_modules/@worker-tools/html-rewriter/base64.js', import.meta.url).href
+			);
+			return runtimeLocalModule.HTMLRewriter as HtmlRewriterConstructor;
+		} catch {
+			const message = primaryError instanceof Error ? primaryError.message : String(primaryError);
+			appLogger.warn(
+				`[HtmlTransformerService] Failed to load @worker-tools/html-rewriter/base64, falling back to string injection: ${message}`,
+			);
+			return null;
+		}
+	}
+}

package/src/services/html/html-transformer.service.test.ts

@@ -0,0 +1,378 @@
+import { describe, expect, it } from 'vitest';
+import type { ProcessedAsset } from '../assets/asset-processing-service/index.js';
+import { HtmlTransformerService } from './html-transformer.service.ts';
+import type {
+	HtmlRewriterElement,
+	HtmlRewriterMode,
+	HtmlRewriterProvider,
+	HtmlRewriterRuntime,
+} from './html-rewriter-provider.service.ts';
+
+type HtmlRewriterHandler = {
+	element: (element: HtmlRewriterElement) => void;
+};
+
+class TestHtmlRewriter {
+	private handlers = new Map<'head' | 'body', HtmlRewriterHandler>();
+
+	on(selector: 'head' | 'body', handler: HtmlRewriterHandler): TestHtmlRewriter {
+		this.handlers.set(selector, handler);
+		return this;
+	}
+
+	transform(response: Response): Response {
+		const body = new ReadableStream<Uint8Array>({
+			start: async (controller) => {
+				const html = await response.text();
+				let result = html;
+
+				for (const selector of ['head', 'body'] as const) {
+					const handler = this.handlers.get(selector);
+					if (!handler) {
+						continue;
+					}
+
+					const chunks: string[] = [];
+					handler.element({
+						append: (content: string) => {
+							chunks.push(content);
+						},
+					});
+
+					const closingTag = `</${selector}>`;
+					result = result.replace(closingTag, `${chunks.join('')}${closingTag}`);
+				}
+
+				controller.enqueue(new TextEncoder().encode(result));
+				controller.close();
+			},
+		});
+
+		return new Response(body, {
+			headers: response.headers,
+			status: response.status,
+			statusText: response.statusText,
+		});
+	}
+}
+
+class TestHtmlRewriterProvider implements HtmlRewriterProvider {
+	public mode: HtmlRewriterMode = 'auto';
+
+	setMode(mode: HtmlRewriterMode) {
+		this.mode = mode;
+	}
+
+	async createHtmlRewriter(): Promise<HtmlRewriterRuntime | null> {
+		return this.mode === 'fallback' ? null : new TestHtmlRewriter();
+	}
+}
+
+type HtmlRewriterModeScenario = {
+	label: string;
+	html: string;
+	dependencies: ProcessedAsset[];
+	expectedFragments: string[];
+	unexpectedFragments?: string[];
+};
+
+type HtmlRewriterModeCase = {
+	label: string;
+	mode: 'auto' | 'native' | 'worker-tools' | 'fallback';
+};
+
+describe('HtmlTransformerService', () => {
+	const createMockResponse = (html: string) => {
+		return new Response(html, {
+			headers: { 'Content-Type': 'text/html' },
+		});
+	};
+
+	const createTransformer = (mode: HtmlRewriterMode = 'auto') => {
+		const htmlRewriterProvider = new TestHtmlRewriterProvider();
+		const transformer = new HtmlTransformerService({ htmlRewriterMode: mode, htmlRewriterProvider });
+		return { transformer, htmlRewriterProvider };
+	};
+
+	const htmlRewriterModeCases: HtmlRewriterModeCase[] = [
+		{ label: 'auto', mode: 'auto' },
+		{ label: 'native', mode: 'native' },
+		{ label: 'worker-tools', mode: 'worker-tools' },
+		{ label: 'fallback', mode: 'fallback' },
+	];
+
+	const htmlRewriterScenarios: HtmlRewriterModeScenario[] = [
+		{
+			label: 'injects mixed head and body dependencies while preserving document content',
+			html: '<html><head><title>Matrix</title></head><body><main>Page content</main></body></html>',
+			dependencies: [
+				{
+					kind: 'stylesheet',
+					inline: false,
+					position: 'head',
+					srcUrl: '/matrix.css',
+					attributes: { media: 'screen' },
+				},
+				{
+					kind: 'script',
+					inline: true,
+					content: 'window.matrix = true;',
+					position: 'head',
+					srcUrl: '/matrix-inline.js',
+					attributes: { id: 'matrix-inline' },
+				},
+				{
+					kind: 'script',
+					inline: false,
+					position: 'body',
+					srcUrl: '/matrix-body.js',
+					attributes: { defer: 'true' },
+				},
+			],
+			expectedFragments: [
+				'<title>Matrix</title>',
+				'<main>Page content</main>',
+				'<link rel="stylesheet" href="/matrix.css" media="screen">',
+				'<script id="matrix-inline">window.matrix = true;</script>',
+				'<script src="/matrix-body.js" defer="true"></script>',
+			],
+		},
+		{
+			label: 'skips excluded scripts while still injecting remaining dependencies',
+			html: '<html><head></head><body><section>Visible</section></body></html>',
+			dependencies: [
+				{
+					kind: 'script',
+					inline: false,
+					position: 'body',
+					srcUrl: '/excluded.js',
+					excludeFromHtml: true,
+				},
+				{
+					kind: 'script',
+					inline: false,
+					position: 'body',
+					srcUrl: '/included.js',
+				},
+			],
+			expectedFragments: ['<section>Visible</section>', '<script src="/included.js"></script>'],
+			unexpectedFragments: ['<script src="/excluded.js"></script>'],
+		},
+		{
+			label: 'injects inline styles and preserves nested body markup',
+			html: '<html><head></head><body><div><span>Nested</span></div></body></html>',
+			dependencies: [
+				{
+					kind: 'stylesheet',
+					inline: true,
+					position: 'head',
+					content: '.nested{color:red;}',
+					srcUrl: '/nested.css',
+					attributes: { 'data-test': 'inline-style' },
+				},
+			],
+			expectedFragments: [
+				'<div><span>Nested</span></div>',
+				'<style data-test="inline-style">.nested{color:red;}</style>',
+			],
+		},
+	];
+
+	it('should inject script dependencies correctly', async () => {
+		const dependencies: ProcessedAsset[] = [
+			{
+				kind: 'script',
+				inline: true,
+				content: "console.log('test')",
+				position: 'body',
+				srcUrl: '/test.js',
+				attributes: { id: 'test-script' },
+			},
+		];
+
+		const { transformer } = createTransformer();
+		transformer.setProcessedDependencies(dependencies);
+		const Response = createMockResponse('<html><head></head><body></body></html>');
+		const result = await transformer.transform(Response);
+		const html = await result.text();
+
+		expect(html).toContain('<script id="test-script">console.log(\'test\')</script>');
+	});
+
+	it('should inject stylesheet dependencies correctly', async () => {
+		const dependencies: ProcessedAsset[] = [
+			{
+				kind: 'stylesheet',
+				inline: false,
+				position: 'head',
+				srcUrl: '/test.css',
+				attributes: { media: 'screen' },
+			},
+		];
+
+		const { transformer } = createTransformer();
+		transformer.setProcessedDependencies(dependencies);
+		const Response = createMockResponse('<html><head></head><body></body></html>');
+		const result = await transformer.transform(Response);
+		const html = await result.text();
+
+		expect(html).toContain('<link rel="stylesheet" href="/test.css" media="screen">');
+	});
+
+	it('should handle both inline and src dependencies', async () => {
+		const dependencies: ProcessedAsset[] = [
+			{
+				kind: 'script',
+				inline: true,
+				content: 'const x = 1;',
+				position: 'head',
+				srcUrl: '/inline.js',
+			},
+			{
+				kind: 'script',
+				inline: false,
+				position: 'body',
+				srcUrl: '/external.js',
+			},
+		];
+
+		const { transformer } = createTransformer();
+		transformer.setProcessedDependencies(dependencies);
+		const Response = createMockResponse('<html><head></head><body></body></html>');
+		const result = await transformer.transform(Response);
+		const html = await result.text();
+
+		expect(html).toContain('<script>const x = 1;</script>');
+		expect(html).toContain('<script src="/external.js"></script>');
+	});
+
+	it('should preserve existing HTML content', async () => {
+		const dependencies: ProcessedAsset[] = [
+			{
+				kind: 'script',
+				inline: true,
+				content: "console.log('test')",
+				position: 'body',
+				srcUrl: '/test.js',
+			},
+		];
+
+		const originalHtml = '<html><head><title>Test</title></head><body><div>Content</div></body></html>';
+		const { transformer } = createTransformer();
+		transformer.setProcessedDependencies(dependencies);
+		const Response = createMockResponse(originalHtml);
+		const result = await transformer.transform(Response);
+		const html = await result.text();
+
+		expect(html).toContain('<title>Test</title>');
+		expect(html).toContain('<div>Content</div>');
+		expect(html).toContain("console.log('test')");
+	});
+
+	it('should use the injected html rewriter provider when available', async () => {
+		const dependencies: ProcessedAsset[] = [
+			{
+				kind: 'script',
+				inline: false,
+				position: 'body',
+				srcUrl: '/native.js',
+			},
+		];
+
+		const { transformer } = createTransformer();
+		transformer.setProcessedDependencies(dependencies);
+		const result = await transformer.transform(createMockResponse('<html><head></head><body></body></html>'));
+		const html = await result.text();
+
+		expect(html).toContain('<script src="/native.js"></script>');
+	});
+
+	it('should fall back to string injection when the provider returns no rewriter', async () => {
+		const dependencies: ProcessedAsset[] = [
+			{
+				kind: 'stylesheet',
+				inline: false,
+				position: 'head',
+				srcUrl: '/worker-tools.css',
+			},
+		];
+
+		const { transformer } = createTransformer('fallback');
+		transformer.setProcessedDependencies(dependencies);
+		const result = await transformer.transform(createMockResponse('<html><head></head><body></body></html>'));
+		const html = await result.text();
+
+		expect(html).toContain('<link rel="stylesheet" href="/worker-tools.css">');
+	});
+
+	it('should delegate html rewriter mode changes to the injected provider', () => {
+		const { transformer, htmlRewriterProvider } = createTransformer();
+
+		transformer.setHtmlRewriterMode('worker-tools');
+		expect(htmlRewriterProvider.mode).toBe('worker-tools');
+
+		transformer.setHtmlRewriterMode('fallback');
+		expect(htmlRewriterProvider.mode).toBe('fallback');
+	});
+
+	it('should support the same transformation scenarios across all html rewriter modes', async () => {
+		for (const modeCase of htmlRewriterModeCases) {
+			const { transformer } = createTransformer(modeCase.mode);
+
+			for (const scenario of htmlRewriterScenarios) {
+				transformer.setProcessedDependencies(scenario.dependencies);
+
+				const result = await transformer.transform(createMockResponse(scenario.html));
+				const html = await result.text();
+
+				for (const expectedFragment of scenario.expectedFragments) {
+					expect(html, `${modeCase.label}: ${scenario.label}`).toContain(expectedFragment);
+				}
+
+				for (const unexpectedFragment of scenario.unexpectedFragments ?? []) {
+					expect(html, `${modeCase.label}: ${scenario.label}`).not.toContain(unexpectedFragment);
+				}
+			}
+		}
+	});
+
+	it('should apply attributes to the html element', () => {
+		const { transformer } = createTransformer();
+		const result = transformer.applyAttributesToHtmlElement(
+			'<!DOCTYPE html><html lang="en"><body>Hello</body></html>',
+			{
+				'data-eco-document-owner': 'react-router',
+			},
+		);
+
+		expect(result).toContain('<html lang="en" data-eco-document-owner="react-router">');
+	});
+
+	it('should apply attributes to the first body child', () => {
+		const { transformer } = createTransformer();
+		const result = transformer.applyAttributesToFirstBodyElement(
+			'<html><body><main>Hello</main><footer>Footer</footer></body></html>',
+			{ 'data-eco-component-id': 'root-1', role: 'main' },
+		);
+
+		expect(result).toContain('<main data-eco-component-id="root-1" role="main">Hello</main>');
+	});
+
+	it('should apply attributes to the first fragment element', () => {
+		const { transformer } = createTransformer();
+		const result = transformer.applyAttributesToFirstElement('   <aside>Content</aside><div>Other</div>', {
+			'aria-live': 'polite',
+		});
+
+		expect(result).toContain('<aside aria-live="polite">Content</aside>');
+	});
+
+	it('should deduplicate processed assets while preserving order', () => {
+		const { transformer } = createTransformer();
+		const first = { kind: 'script', srcUrl: '/assets/app.js', position: 'head' } as ProcessedAsset;
+		const duplicate = { kind: 'script', srcUrl: '/assets/app.js', position: 'head' } as ProcessedAsset;
+		const second = { kind: 'stylesheet', srcUrl: '/assets/app.css', position: 'head' } as ProcessedAsset;
+
+		expect(transformer.dedupeProcessedAssets([first, duplicate, second])).toEqual([first, second]);
+	});
+});