@ecopages/core 0.2.0-alpha.26 → 0.2.0-alpha.27

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,104 @@
+import { appLogger } from '../../global/app-logger.ts';
+
+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(
+				/* @vite-ignore */ 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;
+		}
+	}
+}