@n8n/frontend-module-otel 0.1.0

package/src/otel.store.test.ts

@@ -0,0 +1,391 @@
+import { createPinia, setActivePinia } from 'pinia';
+
+import * as otelApi from './otel.api';
+import type { OtelSettingsResponse } from './otel.api';
+import { useOtelStore, headersStringToPairs, headersPairsToString } from './otel.store';
+
+vi.mock('./otel.api', () => ({
+	getOtelSettings: vi.fn(),
+	updateOtelSettings: vi.fn(),
+	sendOtelTestTrace: vi.fn(),
+}));
+
+vi.mock('@n8n/stores/useRootStore', () => ({
+	useRootStore: vi.fn(() => ({
+		restApiContext: { baseUrl: 'http://localhost', pushRef: '' },
+	})),
+}));
+
+const fetchMock = vi.mocked(otelApi.getOtelSettings);
+const saveMock = vi.mocked(otelApi.updateOtelSettings);
+const testTraceMock = vi.mocked(otelApi.sendOtelTestTrace);
+
+const makeSettings = (overrides: Partial<OtelSettingsResponse> = {}): OtelSettingsResponse => ({
+	enabled: false,
+	exporterEndpoint: 'http://localhost:4318',
+	exporterTracingPath: '/v1/traces',
+	exporterServiceName: 'n8n',
+	exporterHeaders: '',
+	tracesSampleRate: 1.0,
+	startupConnectivityTimeoutMs: 2000,
+	includeNodeSpans: true,
+	injectOutbound: true,
+	productionExecutionsOnly: true,
+	envManagedFields: [],
+	...overrides,
+});
+
+function extractSettings(r: OtelSettingsResponse) {
+	const { envManagedFields: _, ...settings } = r;
+	return settings;
+}
+
+describe('headersStringToPairs', () => {
+	it('returns empty array for empty string', () => {
+		expect(headersStringToPairs('')).toEqual([]);
+	});
+
+	it('returns empty array for whitespace-only string', () => {
+		expect(headersStringToPairs('   ')).toEqual([]);
+	});
+
+	it('parses a single key=value pair', () => {
+		expect(headersStringToPairs('auth=token')).toEqual([{ key: 'auth', value: 'token' }]);
+	});
+
+	it('parses multiple comma-separated pairs', () => {
+		expect(headersStringToPairs('a=1,b=2')).toEqual([
+			{ key: 'a', value: '1' },
+			{ key: 'b', value: '2' },
+		]);
+	});
+
+	it('trims whitespace around keys and values', () => {
+		expect(headersStringToPairs(' key = val ')).toEqual([{ key: 'key', value: 'val' }]);
+	});
+
+	it('treats missing = as key with empty value', () => {
+		expect(headersStringToPairs('noequals')).toEqual([{ key: 'noequals', value: '' }]);
+	});
+
+	it('allows = in value (splits on first = only)', () => {
+		expect(headersStringToPairs('sig=a=b')).toEqual([{ key: 'sig', value: 'a=b' }]);
+	});
+
+	it('filters out pairs with empty key', () => {
+		expect(headersStringToPairs(',a=1')).toEqual([{ key: 'a', value: '1' }]);
+	});
+});
+
+describe('headersPairsToString', () => {
+	it('returns empty string for empty array', () => {
+		expect(headersPairsToString([])).toBe('');
+	});
+
+	it('serialises a single pair', () => {
+		expect(headersPairsToString([{ key: 'auth', value: 'token' }])).toBe('auth=token');
+	});
+
+	it('joins multiple pairs with comma', () => {
+		expect(
+			headersPairsToString([
+				{ key: 'a', value: '1' },
+				{ key: 'b', value: '2' },
+			]),
+		).toBe('a=1,b=2');
+	});
+
+	it('filters out pairs where key is blank', () => {
+		expect(
+			headersPairsToString([
+				{ key: '', value: 'x' },
+				{ key: 'k', value: 'v' },
+			]),
+		).toBe('k=v');
+	});
+
+	it('filters out whitespace-only keys', () => {
+		expect(headersPairsToString([{ key: '  ', value: 'x' }])).toBe('');
+	});
+});
+
+describe('useOtelStore', () => {
+	beforeEach(() => {
+		setActivePinia(createPinia());
+		fetchMock.mockReset();
+		saveMock.mockReset();
+		testTraceMock.mockReset();
+	});
+
+	describe('fetchSettings', () => {
+		it('populates settings and savedSettings from API response', async () => {
+			const remote = makeSettings({ enabled: true, exporterEndpoint: 'https://collector.io' });
+			fetchMock.mockResolvedValueOnce(remote);
+
+			const store = useOtelStore();
+			await store.fetchSettings();
+
+			expect(store.settings).toEqual(extractSettings(remote));
+			expect(store.savedSettings).toEqual(extractSettings(remote));
+		});
+
+		it('stores independent copies so mutations do not affect savedSettings', async () => {
+			const remote = makeSettings({ exporterEndpoint: 'https://original.io' });
+			fetchMock.mockResolvedValueOnce(remote);
+
+			const store = useOtelStore();
+			await store.fetchSettings();
+
+			store.settings.exporterEndpoint = 'https://changed.io';
+
+			expect(store.savedSettings.exporterEndpoint).toBe('https://original.io');
+		});
+
+		it('sets loading to true during the call and resets it after', async () => {
+			let resolve!: (v: OtelSettingsResponse) => void;
+			fetchMock.mockImplementationOnce(async () => await new Promise((r) => (resolve = r)));
+
+			const store = useOtelStore();
+			const pending = store.fetchSettings();
+
+			expect(store.loading).toBe(true);
+
+			resolve(makeSettings());
+			await pending;
+
+			expect(store.loading).toBe(false);
+		});
+
+		it('resets loading even when the API throws', async () => {
+			fetchMock.mockRejectedValueOnce(new Error('network error'));
+
+			const store = useOtelStore();
+			await expect(store.fetchSettings()).rejects.toThrow('network error');
+
+			expect(store.loading).toBe(false);
+		});
+	});
+
+	describe('saveSettings', () => {
+		it('calls updateOtelSettings with current settings and updates store from response', async () => {
+			const current = makeSettings({ enabled: true });
+			const updated = makeSettings({ enabled: true, exporterEndpoint: 'https://updated.io' });
+			fetchMock.mockResolvedValueOnce(current);
+			saveMock.mockResolvedValueOnce(updated);
+
+			const store = useOtelStore();
+			await store.fetchSettings();
+			await store.saveSettings();
+
+			expect(saveMock).toHaveBeenCalledWith(expect.anything(), extractSettings(current));
+			expect(store.settings).toEqual(extractSettings(updated));
+			expect(store.savedSettings).toEqual(extractSettings(updated));
+		});
+
+		it('sets saving to true during the call and resets it after', async () => {
+			const settings = makeSettings();
+			fetchMock.mockResolvedValueOnce(settings);
+			let resolve!: (v: OtelSettingsResponse) => void;
+			saveMock.mockImplementationOnce(async () => await new Promise((r) => (resolve = r)));
+
+			const store = useOtelStore();
+			await store.fetchSettings();
+			const pending = store.saveSettings();
+
+			expect(store.saving).toBe(true);
+
+			resolve(settings);
+			await pending;
+
+			expect(store.saving).toBe(false);
+		});
+
+		it('resets saving even when the API throws', async () => {
+			fetchMock.mockResolvedValueOnce(makeSettings());
+			saveMock.mockRejectedValueOnce(new Error('save failed'));
+
+			const store = useOtelStore();
+			await store.fetchSettings();
+
+			await expect(store.saveSettings()).rejects.toThrow('save failed');
+			expect(store.saving).toBe(false);
+		});
+	});
+
+	describe('discardChanges', () => {
+		it('resets settings to savedSettings', async () => {
+			const original = makeSettings({ exporterEndpoint: 'https://original.io' });
+			fetchMock.mockResolvedValueOnce(original);
+
+			const store = useOtelStore();
+			await store.fetchSettings();
+
+			store.settings.exporterEndpoint = 'https://changed.io';
+			store.discardChanges();
+
+			expect(store.settings.exporterEndpoint).toBe('https://original.io');
+		});
+	});
+
+	describe('isDirty', () => {
+		it('is false before fetch (settings equal default savedSettings)', () => {
+			const store = useOtelStore();
+			expect(store.isDirty).toBe(false);
+		});
+
+		it('is false immediately after fetch (settings equal savedSettings)', async () => {
+			fetchMock.mockResolvedValueOnce(makeSettings());
+			const store = useOtelStore();
+			await store.fetchSettings();
+
+			expect(store.isDirty).toBe(false);
+		});
+
+		it('is true after a field is changed', async () => {
+			fetchMock.mockResolvedValueOnce(makeSettings({ enabled: false }));
+			const store = useOtelStore();
+			await store.fetchSettings();
+
+			store.settings.enabled = true;
+
+			expect(store.isDirty).toBe(true);
+		});
+
+		it('returns to false after discardChanges', async () => {
+			fetchMock.mockResolvedValueOnce(makeSettings({ enabled: false }));
+			const store = useOtelStore();
+			await store.fetchSettings();
+
+			store.settings.enabled = true;
+			expect(store.isDirty).toBe(true);
+
+			store.discardChanges();
+			expect(store.isDirty).toBe(false);
+		});
+
+		it('returns to false after a successful save', async () => {
+			const settings = makeSettings({ enabled: false });
+			fetchMock.mockResolvedValueOnce(settings);
+			saveMock.mockResolvedValueOnce(makeSettings({ enabled: true }));
+
+			const store = useOtelStore();
+			await store.fetchSettings();
+			store.settings.enabled = true;
+			expect(store.isDirty).toBe(true);
+
+			await store.saveSettings();
+			expect(store.isDirty).toBe(false);
+		});
+	});
+
+	describe('sendTestTrace', () => {
+		it('starts in the idle state', () => {
+			const store = useOtelStore();
+			expect(store.testState).toBe('idle');
+		});
+
+		it('sends only the connection fields from the current settings', async () => {
+			fetchMock.mockResolvedValueOnce(
+				makeSettings({
+					exporterEndpoint: 'https://collector.io',
+					exporterTracingPath: '/custom',
+					exporterServiceName: 'n8n-prod',
+					exporterHeaders: 'auth=token',
+					startupConnectivityTimeoutMs: 3000,
+				}),
+			);
+			testTraceMock.mockResolvedValueOnce({ success: true });
+
+			const store = useOtelStore();
+			await store.fetchSettings();
+			await store.sendTestTrace();
+
+			expect(testTraceMock).toHaveBeenCalledWith(expect.anything(), {
+				exporterEndpoint: 'https://collector.io',
+				exporterTracingPath: '/custom',
+				exporterServiceName: 'n8n-prod',
+				exporterHeaders: 'auth=token',
+				startupConnectivityTimeoutMs: 3000,
+			});
+		});
+
+		it('transitions to sent and records a timestamp on success', async () => {
+			testTraceMock.mockResolvedValueOnce({ success: true });
+
+			const store = useOtelStore();
+			await store.sendTestTrace();
+
+			expect(store.testState).toBe('sent');
+			expect(store.testTimestamp).not.toBe('');
+			expect(store.testError).toBe('');
+		});
+
+		it('transitions to error with the collector message on failure', async () => {
+			testTraceMock.mockResolvedValueOnce({ success: false, error: '401 Unauthorized' });
+
+			const store = useOtelStore();
+			await store.sendTestTrace();
+
+			expect(store.testState).toBe('error');
+			expect(store.testError).toBe('401 Unauthorized');
+		});
+
+		it('transitions to error when the request itself throws', async () => {
+			testTraceMock.mockRejectedValueOnce(new Error('network error'));
+
+			const store = useOtelStore();
+			await store.sendTestTrace();
+
+			expect(store.testState).toBe('error');
+			expect(store.testError).toBe('network error');
+		});
+
+		it('is in the sending state while the request is in flight', async () => {
+			let resolve!: (v: { success: true }) => void;
+			testTraceMock.mockImplementationOnce(async () => await new Promise((r) => (resolve = r)));
+
+			const store = useOtelStore();
+			const pending = store.sendTestTrace();
+
+			expect(store.testState).toBe('sending');
+
+			resolve({ success: true });
+			await pending;
+
+			expect(store.testState).toBe('sent');
+		});
+
+		it('discards an in-flight result when reset before it resolves', async () => {
+			let resolve!: (v: { success: true }) => void;
+			testTraceMock.mockImplementationOnce(async () => await new Promise((r) => (resolve = r)));
+
+			const store = useOtelStore();
+			const pending = store.sendTestTrace();
+			expect(store.testState).toBe('sending');
+
+			// User edits a connection field mid-flight.
+			store.resetTestState();
+			expect(store.testState).toBe('idle');
+
+			resolve({ success: true });
+			await pending;
+
+			// The stale success must not flip the badge back to 'sent'.
+			expect(store.testState).toBe('idle');
+		});
+
+		it('resetTestState clears the result', async () => {
+			testTraceMock.mockResolvedValueOnce({ success: false, error: 'boom' });
+
+			const store = useOtelStore();
+			await store.sendTestTrace();
+			expect(store.testState).toBe('error');
+
+			store.resetTestState();
+
+			expect(store.testState).toBe('idle');
+			expect(store.testError).toBe('');
+			expect(store.testTimestamp).toBe('');
+		});
+	});
+});

package/src/otel.store.ts

@@ -0,0 +1,145 @@
+import { useRootStore } from '@n8n/stores/useRootStore';
+import { defineStore } from 'pinia';
+import { ref, computed } from 'vue';
+
+import { getOtelSettings, updateOtelSettings, sendOtelTestTrace } from './otel.api';
+import type { OtelSettings, OtelSettingsResponse } from './otel.api';
+import { OTEL_STORE } from './otel.constants';
+
+export type OtelTestState = 'idle' | 'sending' | 'sent' | 'error';
+
+export function headersStringToPairs(str: string): Array<{ key: string; value: string }> {
+	if (!str.trim()) return [];
+	return str
+		.split(',')
+		.map((pair) => {
+			const idx = pair.indexOf('=');
+			if (idx === -1) return { key: pair.trim(), value: '' };
+			return { key: pair.slice(0, idx).trim(), value: pair.slice(idx + 1).trim() };
+		})
+		.filter((p) => p.key);
+}
+
+export function headersPairsToString(pairs: Array<{ key: string; value: string }>): string {
+	return pairs
+		.filter((p) => p.key.trim())
+		.map((p) => `${p.key}=${p.value}`)
+		.join(',');
+}
+
+const defaultSettings: OtelSettings = {
+	enabled: false,
+	exporterEndpoint: 'http://localhost:4318',
+	exporterTracingPath: '/v1/traces',
+	exporterServiceName: 'n8n',
+	exporterHeaders: '',
+	tracesSampleRate: 1.0,
+	startupConnectivityTimeoutMs: 2_000,
+	includeNodeSpans: true,
+	injectOutbound: true,
+	productionExecutionsOnly: true,
+};
+
+function extractSettings(response: OtelSettingsResponse): OtelSettings {
+	const { envManagedFields: _, ...settings } = response;
+	return settings;
+}
+
+export const useOtelStore = defineStore(OTEL_STORE, () => {
+	const rootStore = useRootStore();
+
+	const settings = ref<OtelSettings>({ ...defaultSettings });
+	const savedSettings = ref<OtelSettings>({ ...defaultSettings });
+	const envManagedFields = ref<Array<keyof OtelSettings>>([]);
+	const loading = ref(true);
+	const saving = ref(false);
+
+	const testState = ref<OtelTestState>('idle');
+	const testError = ref('');
+	const testTimestamp = ref('');
+
+	const isDirty = computed(
+		() => JSON.stringify(settings.value) !== JSON.stringify(savedSettings.value),
+	);
+
+	async function fetchSettings(): Promise<void> {
+		loading.value = true;
+		try {
+			const fetched = await getOtelSettings(rootStore.restApiContext);
+			settings.value = extractSettings(fetched);
+			savedSettings.value = extractSettings(fetched);
+			envManagedFields.value = fetched.envManagedFields;
+		} finally {
+			loading.value = false;
+		}
+	}
+
+	async function saveSettings(): Promise<void> {
+		saving.value = true;
+		try {
+			const updated = await updateOtelSettings(rootStore.restApiContext, settings.value);
+			settings.value = extractSettings(updated);
+			savedSettings.value = extractSettings(updated);
+			envManagedFields.value = updated.envManagedFields;
+		} finally {
+			saving.value = false;
+		}
+	}
+
+	function discardChanges(): void {
+		settings.value = { ...savedSettings.value };
+	}
+
+	let currentTestRun = 0;
+
+	function resetTestState(): void {
+		currentTestRun++;
+		testState.value = 'idle';
+		testError.value = '';
+		testTimestamp.value = '';
+	}
+
+	async function sendTestTrace(): Promise<void> {
+		const runId = ++currentTestRun;
+		testState.value = 'sending';
+		testError.value = '';
+		try {
+			const result = await sendOtelTestTrace(rootStore.restApiContext, {
+				exporterEndpoint: settings.value.exporterEndpoint,
+				exporterTracingPath: settings.value.exporterTracingPath,
+				exporterServiceName: settings.value.exporterServiceName,
+				exporterHeaders: settings.value.exporterHeaders,
+				startupConnectivityTimeoutMs: settings.value.startupConnectivityTimeoutMs,
+			});
+			if (runId !== currentTestRun) return;
+			if (result.success) {
+				testTimestamp.value = new Date().toLocaleTimeString();
+				testState.value = 'sent';
+			} else {
+				testError.value = result.error;
+				testState.value = 'error';
+			}
+		} catch (error) {
+			if (runId !== currentTestRun) return;
+			testError.value = error instanceof Error ? error.message : String(error);
+			testState.value = 'error';
+		}
+	}
+
+	return {
+		settings,
+		savedSettings,
+		envManagedFields,
+		loading,
+		saving,
+		isDirty,
+		testState,
+		testError,
+		testTimestamp,
+		fetchSettings,
+		saveSettings,
+		discardChanges,
+		sendTestTrace,
+		resetTestState,
+	};
+});

package/src/otel.utils.test.ts

@@ -0,0 +1,44 @@
+import { createSampleRateFormat } from './otel.utils';
+
+describe('createSampleRateFormat', () => {
+	describe.each(['en-US', 'de-DE', 'fr-FR', 'ar-EG', 'fa-IR'])('locale %s', (locale) => {
+		const { format, parse } = createSampleRateFormat(locale);
+
+		test.each([0, 0.25, 0.5, 0.1234, 1])('round-trips %s through format and parse', (value) => {
+			expect(parse(format(value))).toBe(value);
+		});
+	});
+
+	describe('parse', () => {
+		const { parse } = createSampleRateFormat('en-US');
+
+		it('accepts both plain decimal separators', () => {
+			expect(parse('0.5')).toBe(0.5);
+			expect(parse('0,5')).toBe(0.5);
+		});
+
+		it('clamps to [0, 1]', () => {
+			expect(parse('5')).toBe(1);
+			expect(parse('-1')).toBe(0);
+		});
+
+		it('returns null for empty or non-numeric input', () => {
+			expect(parse('')).toBeNull();
+			expect(parse('   ')).toBeNull();
+			expect(parse('abc')).toBeNull();
+		});
+
+		it('accepts ASCII digits under a localized-digit locale', () => {
+			expect(createSampleRateFormat('ar-EG').parse('0.5')).toBe(0.5);
+		});
+	});
+
+	describe('format', () => {
+		it('renders at least two and at most four fraction digits', () => {
+			const { format } = createSampleRateFormat('en-US');
+			expect(format(1)).toBe('1.00');
+			expect(format(0.5)).toBe('0.50');
+			expect(format(0.1234)).toBe('0.1234');
+		});
+	});
+});

package/src/otel.utils.ts

@@ -0,0 +1,38 @@
+/**
+ * Locale-aware formatting and parsing for the traces sample rate (0..1).
+ *
+ * The parser inverts the formatter: the locale's digits are mapped back to
+ * ASCII and its decimal separator is accepted alongside '.' and ',', so any
+ * value the formatter renders (or a user types) parses back to the same number.
+ */
+export function createSampleRateFormat(locale?: string) {
+	const formatter = new Intl.NumberFormat(locale, {
+		minimumFractionDigits: 2,
+		maximumFractionDigits: 4,
+	});
+	const decimalSeparator =
+		formatter.formatToParts(1.1).find((part) => part.type === 'decimal')?.value ?? '.';
+	const digitFormatter = new Intl.NumberFormat(locale);
+	const asciiDigits = new Map(
+		Array.from({ length: 10 }, (_, digit) => [digitFormatter.format(digit), String(digit)]),
+	);
+
+	/** Parse a rate in this locale; null when not a number (incl. empty). Clamps to [0, 1]. */
+	function parse(text: string): number | null {
+		// strip bidi control marks (LRM, RLM, ALM) some locales emit around numbers
+		const trimmed = text.replace(/[\u200e\u200f\u061c]/gu, '').trim();
+		if (!trimmed) return null;
+		const normalized = [...trimmed]
+			.map((char) => asciiDigits.get(char) ?? char)
+			.join('')
+			.replace(decimalSeparator, '.')
+			.replace(',', '.');
+		const parsed = Number(normalized);
+		return Number.isFinite(parsed) ? Math.min(1, Math.max(0, parsed)) : null;
+	}
+
+	return {
+		format: (value: number) => formatter.format(value),
+		parse,
+	};
+}

package/stylelint.config.mjs

@@ -0,0 +1,9 @@
+import { baseConfig } from '@n8n/stylelint-config/base';
+
+export default {
+	...baseConfig,
+	rules: {
+		...baseConfig.rules,
+		'@n8n/css-var-naming': [true, { severity: 'error' }],
+	},
+};

package/vite.config.ts

@@ -0,0 +1,51 @@
+import vue from '@vitejs/plugin-vue';
+import { fileURLToPath } from 'node:url';
+import { resolve } from 'node:path';
+import icons from 'unplugin-icons/vite';
+import svgLoader from 'vite-svg-loader';
+import { defineConfig, mergeConfig } from 'vite';
+import { frontendAliases } from '@n8n/frontend-vite-config';
+import { vitestConfig } from '@n8n/vitest-config/frontend';
+
+const packageDir = fileURLToPath(new URL('.', import.meta.url));
+const packagesDir = resolve(packageDir, '..', '..', '..');
+
+export default mergeConfig(
+	defineConfig({
+		// `@n8n/design-system`'s icon set reaches for two things Vite does not handle on its
+		// own: `~icons/lucide/*` virtual modules and `./custom/*.svg` single-file components.
+		// Consuming design-system from source makes both the consumer's problem — without
+		// `svgLoader` an `.svg` import returns a data-URI string, which Vue then renders as a
+		// tag name and jsdom rejects. Every module that renders a design-system component
+		// needs these two plugins.
+		plugins: [
+			vue(),
+			// Off, so a test never reaches the network for a missing collection.
+			icons({ compiler: 'vue3', autoInstall: false }),
+			svgLoader({
+				svgoConfig: {
+					plugins: [
+						{
+							name: 'preset-default',
+							params: {
+								overrides: {
+									// The icons rely on their ids, and on a viewBox to stay scalable.
+									cleanupIds: false,
+									removeViewBox: false,
+								},
+							},
+						},
+					],
+				},
+			}),
+		],
+		resolve: {
+			// The same platform mapping the editor-ui dev server uses, so a test resolves
+			// `@n8n/stores/...` from source rather than from a stale `dist` — the two disagreeing is
+			// what put 1,111 specifiers on the wrong side of the src/dist line. Sibling modules are
+			// deliberately absent: nothing here should make a cross-module import resolve.
+			alias: frontendAliases(packagesDir),
+		},
+	}),
+	vitestConfig,
+);