From 987068cc6fe6243e6ba484d2d0f460ba1a787e94 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E5=8D=83=E4=B9=98=E5=A6=8D=20=28Xiaoyaner=29?= <258399167+xiaoyaner0201@users.noreply.github.com> Date: Mon, 2 Nov 2026 14:38:38 +0800 Subject: [PATCH] feat(analytics): register configuration-only DataFinder adapter MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Refs #989 Signed-off-by: 千乘妍 (Xiaoyaner) <258399167+xiaoyaner0201@users.noreply.github.com> --- .../skillhub/tests/configuration-contracts.sh | 9 + charts/skillhub/tests/datafinder-values.yaml | 4 + scripts/tests/web-analytics-test.py | 41 +++++ web/analytics-config.awk | 24 ++- web/docker-entrypoint.d/40-analytics.sh | 16 +- web/src/app/analytics-page-type.ts | 11 ++ web/src/bootstrap.ts | 4 +- .../analytics/adapters/datafinder/adapter.ts | 59 +++++++ .../analytics/adapters/datafinder/config.ts | 16 ++ web/src/features/analytics/config.ts | 7 +- web/src/features/analytics/controller.ts | 6 +- web/src/features/analytics/datafinder.test.ts | 155 ++++++++++++++++++ web/src/features/analytics/loader.ts | 6 +- web/src/features/analytics/registry.ts | 14 +- web/src/features/analytics/runtime.test.ts | 2 +- web/src/features/analytics/types.ts | 3 +- 16 files changed, 353 insertions(+), 24 deletions(-) create mode 100644 charts/skillhub/tests/datafinder-values.yaml create mode 100644 web/src/app/analytics-page-type.ts create mode 100644 web/src/features/analytics/adapters/datafinder/adapter.ts create mode 100644 web/src/features/analytics/adapters/datafinder/config.ts create mode 100644 web/src/features/analytics/datafinder.test.ts diff --git a/charts/skillhub/tests/configuration-contracts.sh b/charts/skillhub/tests/configuration-contracts.sh index 0685cef60..194222efd 100755 --- a/charts/skillhub/tests/configuration-contracts.sh +++ b/charts/skillhub/tests/configuration-contracts.sh @@ -527,6 +527,15 @@ assert_checksum "$TMP_DIR/analytics-default.yaml" "$TMP_DIR/analytics-enabled.ya diff <(pod_checksums "$TMP_DIR/analytics-default.yaml" | grep -v "^$web ") \ <(pod_checksums "$TMP_DIR/analytics-enabled.yaml" | grep -v "^$web ") >/dev/null \ || fail "analytics-only changes must not replace server or other pods" +# A second adapter uses the same opaque JSON/ConfigMap contract, via a values file. +render analytics-default "$CHART_DIR" -f "$CHART_DIR/tests/datafinder-values.yaml" >"$TMP_DIR/analytics-datafinder.yaml" +grep -Fq 'appId\":123456' "$TMP_DIR/analytics-datafinder.yaml" || fail "DataFinder public config missing" +grep -Fq ' upstream: "https://collector.example.com"' "$TMP_DIR/analytics-datafinder.yaml" || fail "DataFinder origin missing" +assert_checksum "$TMP_DIR/analytics-default.yaml" "$TMP_DIR/analytics-datafinder.yaml" "$web" checksum/config: changed +diff <(pod_checksums "$TMP_DIR/analytics-default.yaml" | grep -v "^$web ") \ + <(pod_checksums "$TMP_DIR/analytics-datafinder.yaml" | grep -v "^$web ") >/dev/null \ + || fail "DataFinder must not roll non-Web pods" + # Backend configuration still rolls the server. render analytics-default "$CHART_DIR" -f "$TMP_DIR/analytics-values.yaml" \ --set-string bootstrapAdmin.displayName=Changed >"$TMP_DIR/analytics-server-change.yaml" diff --git a/charts/skillhub/tests/datafinder-values.yaml b/charts/skillhub/tests/datafinder-values.yaml new file mode 100644 index 000000000..1fd170771 --- /dev/null +++ b/charts/skillhub/tests/datafinder-values.yaml @@ -0,0 +1,4 @@ +web: + analytics: + config: '{"enabled":true,"adapter":"datafinder","consent":"granted","adapterConfig":{"appId":123456,"product":"skillhub"}}' + upstream: https://collector.example.com diff --git a/scripts/tests/web-analytics-test.py b/scripts/tests/web-analytics-test.py index 300dc62f1..7b789ba45 100644 --- a/scripts/tests/web-analytics-test.py +++ b/scripts/tests/web-analytics-test.py @@ -67,4 +67,45 @@ class AnalyticsStartup(unittest.TestCase): runtime,proxy,diagnostics=self.render(raw) self.assertNotIn('proxy_pass',proxy) self.assertIn('analytics',diagnostics) +class DatafinderStartup(unittest.TestCase): + render=AnalyticsStartup.render + def datafinder(self, settings=None): + return json.dumps(dict(enabled=True, adapter='datafinder', consent='granted', adapterConfig={'appId':123456} if settings is None else settings)) + def test_datafinder_proxy(self): + runtime,proxy,diagnostics=self.render(self.datafinder()) + self.assertEqual(diagnostics,'') + self.assertEqual(proxy.count('location = '),1) + self.assertIn('location = /_skillhub-analytics/list {',proxy) + self.assertIn('limit_except POST { deny all; }',proxy) + self.assertIn('proxy_pass $skillhub_analytics_upstream/list;',proxy) + self.assertNotIn('script.js',proxy) + self.assertNotIn('api/send',proxy) + self.assertNotIn('proxy_set_header User-Agent',proxy) + for directive in ['proxy_set_header Cookie ""','proxy_set_header Authorization ""','proxy_set_header Referer ""','proxy_hide_header Set-Cookie','proxy_ssl_verify on','proxy_connect_timeout 3s','proxy_read_timeout 3s','proxy_send_timeout 3s','proxy_cache off']: + self.assertIn(directive,proxy) + self.assertNotIn('stats.example.com',runtime) + def test_datafinder_valid_settings(self): + for settings in [{'appId':1},{'appId':2147483647},{'appId':1,'product':'a_2'},{'appId':1e2}]: + runtime,proxy,diagnostics=self.render(self.datafinder(settings)) + self.assertIn('atob(',runtime) + self.assertIn('proxy_pass',proxy) + self.assertEqual(diagnostics,'') + def test_datafinder_field_diagnostics(self): + for settings,field in [({},'adapterConfig.appId'),({'appId':0},'adapterConfig.appId'),({'appId':-1},'adapterConfig.appId'),({'appId':1.1},'adapterConfig.appId'),({'appId':2147483648},'adapterConfig.appId'),({'appId':'PRIVATE'},'adapterConfig.appId'),({'appId':1,'product':'PRIVATE'},'adapterConfig.product'),({'appId':1,'product':'a'*33},'adapterConfig.product'),({'appId':1,'product':''},'adapterConfig.product'),({'appId':1,'product':None},'adapterConfig.product'),({'appId':1,'X-MCS-AppKey':'PRIVATE'},'adapterConfig')]: + runtime,proxy,diagnostics=self.render(self.datafinder(settings)) + self.assertNotIn('proxy_pass',proxy) + self.assertIn('[analytics] '+field+':',diagnostics) + self.assertNotIn('PRIVATE',runtime+proxy+diagnostics) + def test_datafinder_hostile_upstream(self): + for upstream in ['https://stats.example.com;PRIVATE','https://user:PRIVATE@stats.example.com','https://stats.example.com/list','https://stats.example.com\nPRIVATE']: + runtime,proxy,diagnostics=self.render(self.datafinder(),upstream) + self.assertNotIn('proxy_pass',proxy) + self.assertIn('upstream',diagnostics) + self.assertNotIn('PRIVATE',runtime+proxy+diagnostics) + def test_datafinder_denied_and_escaped_keys(self): + raw=self.datafinder({'appId':1,'product':'skillhub'}).replace('granted','denied').replace('appId','\\u0061ppId') + runtime,proxy,diagnostics=self.render(raw) + self.assertIn('atob(',runtime) + self.assertIn('/list',proxy) + self.assertEqual(diagnostics,'') if __name__=='__main__': unittest.main() diff --git a/web/analytics-config.awk b/web/analytics-config.awk index da18eb140..86c4a59a8 100644 --- a/web/analytics-config.awk +++ b/web/analytics-config.awk @@ -58,7 +58,7 @@ function value(depth, id,c,key,item,token) { } else if(c=="\"") { kind[id]="string"; data[id]=string(); return id } else { token=substr(s,p) - if(match(token,/^-?(0|[1-9][0-9]*)(\.[0-9]+)?([eE][+-]?[0-9]+)?/)) { kind[id]="number"; p+=RLENGTH; return id } + if(match(token,/^-?(0|[1-9][0-9]*)(\.[0-9]+)?([eE][+-]?[0-9]+)?/)) { kind[id]="number"; data[id]=substr(token,1,RLENGTH)+0; p+=RLENGTH; return id } if(substr(token,1,4)=="true") { kind[id]="boolean"; data[id]="true"; p+=4; return id } if(substr(token,1,5)=="false") { kind[id]="boolean"; data[id]="false"; p+=5; return id } if(substr(token,1,4)=="null") { kind[id]="null"; p+=4; return id } @@ -78,14 +78,24 @@ END { adapter=child[root SUBSEP "adapter"]; settings=child[root SUBSEP "adapterConfig"] if(enabled && kind[enabled]!="boolean") bad("enabled") if(consent && (kind[consent]!="string" || (data[consent]!="denied" && data[consent]!="granted"))) bad("consent") - if(adapter && (kind[adapter]!="string" || data[adapter]!="umami")) bad("adapter") + if(adapter && (kind[adapter]!="string" || (data[adapter]!="umami" && data[adapter]!="datafinder"))) bad("adapter") if(settings && kind[settings]!="object") bad("adapterConfig") if(data[enabled]=="true") { - if(data[adapter]!="umami") bad("adapter") - website=child[settings SUBSEP "websiteId"]; uuid=data[website] - if(kind[settings]!="object" || count[settings]!=1 || kind[website]!="string" || length(uuid)!=36 || uuid !~ /^[0-9a-fA-F-]+$/ || substr(uuid,9,1)!="-" || substr(uuid,14,1)!="-" || substr(uuid,19,1)!="-" || substr(uuid,24,1)!="-") bad("adapterConfig") - gsub(/-/,"",uuid); if(length(uuid)!=32) bad("adapterConfig") + if(kind[settings]!="object") bad("adapterConfig") + if(data[adapter]=="umami") { + website=child[settings SUBSEP "websiteId"]; uuid=data[website] + if(count[settings]!=1 || kind[website]!="string" || length(uuid)!=36 || uuid !~ /^[0-9a-fA-F-]+$/ || substr(uuid,9,1)!="-" || substr(uuid,14,1)!="-" || substr(uuid,19,1)!="-" || substr(uuid,24,1)!="-") bad("adapterConfig") + gsub(/-/,"",uuid); if(length(uuid)!=32) bad("adapterConfig") + } else if(data[adapter]=="datafinder") { + for(k in child) if(index(k,settings SUBSEP)==1) { + name=substr(k,length(settings SUBSEP)+1) + if(name!="appId" && name!="product") bad("adapterConfig") + } + app=child[settings SUBSEP "appId"]; product=child[settings SUBSEP "product"] + if(kind[app]!="number" || data[app]<1 || data[app]>2147483647 || int(data[app])!=data[app]) bad("adapterConfig.appId") + if(product && (kind[product]!="string" || length(data[product])>32 || data[product]!~/^[a-z][a-z0-9_]*$/)) bad("adapterConfig.product") + } else bad("adapter") # Denied pages can later call start(), so retain valid public configuration. - print (data[consent]=="granted" ? "enabled" : "denied") + print (data[consent]=="granted" ? "enabled" : "denied") " " data[adapter] } else print "disabled" } diff --git a/web/docker-entrypoint.d/40-analytics.sh b/web/docker-entrypoint.d/40-analytics.sh index 893727011..84c0e4da1 100644 --- a/web/docker-entrypoint.d/40-analytics.sh +++ b/web/docker-entrypoint.d/40-analytics.sh @@ -20,7 +20,7 @@ if [ -n "$raw" ]; then fi case "$status" in 'invalid '*) printf '[analytics] %s: invalid configuration; disabled\n' "${status#invalid }" >&2 ;; - enabled|denied) + 'enabled umami'|'denied umami'|'enabled datafinder'|'denied datafinder') upstream="${SKILLHUB_WEB_ANALYTICS_UPSTREAM:-}" # Strict origin grammar; never interpolate unvalidated input into Nginx. safe_chars=true @@ -64,10 +64,16 @@ case "$status" in # data; quotes, newlines, U+2028 and closing tags cannot become executable. printf 'try { window.__SKILLHUB_RUNTIME_CONFIG__.analytics = JSON.parse(new TextDecoder().decode(Uint8Array.from(atob("%s"), function(c) { return c.charCodeAt(0); }))); } catch (_) { console.error("[analytics] config: invalid JSON; disabled"); }\n' "$encoded" > "$root/analytics-runtime.js" printf 'set $skillhub_analytics_upstream "%s";\n' "$upstream" > "$proxy" - for endpoint in script.js api/send; do - method=GET - [ "$endpoint" != api/send ] || method=POST - printf 'location = /_skillhub-analytics/%s {\n limit_except %s { deny all; }\n proxy_pass $skillhub_analytics_upstream/%s;\n proxy_set_header Host "%s";\n proxy_set_header Cookie "";\n proxy_set_header Authorization "";\n proxy_set_header Referer "";\n proxy_hide_header Set-Cookie;\n proxy_ssl_verify on;\n proxy_ssl_server_name on;\n proxy_ssl_name %s;\n proxy_ssl_trusted_certificate /etc/ssl/certs/ca-certificates.crt;\n proxy_connect_timeout 3s;\n proxy_read_timeout 3s;\n proxy_cache off;\n}\n' "$endpoint" "$method" "$endpoint" "$authority" "$host" >> "$proxy" + case "${status#* }" in + umami) endpoints='script.js api/send' ;; + datafinder) endpoints=list ;; + esac + for endpoint in $endpoints; do + method=POST + [ "$endpoint" != script.js ] || method=GET + send_timeout='' + [ "$endpoint" != list ] || send_timeout=' proxy_send_timeout 3s;' + printf 'location = /_skillhub-analytics/%s {\n limit_except %s { deny all; }\n proxy_pass $skillhub_analytics_upstream/%s;\n proxy_set_header Host "%s";\n proxy_set_header Cookie "";\n proxy_set_header Authorization "";\n proxy_set_header Referer "";\n proxy_hide_header Set-Cookie;\n proxy_ssl_verify on;\n proxy_ssl_server_name on;\n proxy_ssl_name %s;\n proxy_ssl_trusted_certificate /etc/ssl/certs/ca-certificates.crt;\n proxy_connect_timeout 3s;\n proxy_read_timeout 3s;\n proxy_cache off;\n%s\n}\n' "$endpoint" "$method" "$endpoint" "$authority" "$host" "$send_timeout" >> "$proxy" done else printf '%s\n' '[analytics] upstream: invalid origin; disabled' >&2 diff --git a/web/src/app/analytics-page-type.ts b/web/src/app/analytics-page-type.ts new file mode 100644 index 000000000..810ee3ef1 --- /dev/null +++ b/web/src/app/analytics-page-type.ts @@ -0,0 +1,11 @@ +// Read only route metadata, never match.pathname, params, location or search. +export function currentPageType(router: { + state: { matches: ReadonlyArray<{ routeId: string; globalNotFound?: boolean; status: string }> } + routesById: Record +}): string { + const matches = router.state.matches + if (matches.some(match => match.globalNotFound || match.status === 'notFound')) return 'other' + const leaf = matches[matches.length - 1] + if (!leaf || leaf.routeId === '__root__') return 'other' + return router.routesById[leaf.routeId]?.fullPath ?? 'other' +} diff --git a/web/src/bootstrap.ts b/web/src/bootstrap.ts index 1e3d4c431..ec19240b3 100644 --- a/web/src/bootstrap.ts +++ b/web/src/bootstrap.ts @@ -7,6 +7,7 @@ import './legacy-polyfills' import { initializeTheme } from './shared/lib/theme' import { afterAppMount, installAnalyticsLoader } from './features/analytics/loader' +import { currentPageType } from './app/analytics-page-type' import type { AnalyticsAPI } from './features/analytics/types' declare global { @@ -49,8 +50,9 @@ void (async () => { } await import('./main') + const { router } = await import('./app/router') const root = document.getElementById('root') if (root) afterAppMount(root, () => { - window.skillhubAnalytics = installAnalyticsLoader(() => window.__SKILLHUB_RUNTIME_CONFIG__?.analytics) + window.skillhubAnalytics = installAnalyticsLoader(() => window.__SKILLHUB_RUNTIME_CONFIG__?.analytics, undefined, { currentPageType: () => currentPageType(router) }) }) })() diff --git a/web/src/features/analytics/adapters/datafinder/adapter.ts b/web/src/features/analytics/adapters/datafinder/adapter.ts new file mode 100644 index 000000000..2242ba5af --- /dev/null +++ b/web/src/features/analytics/adapters/datafinder/adapter.ts @@ -0,0 +1,59 @@ +import type { AnalyticsAdapter, AnalyticsContext } from '../../types' +import { validateDatafinderConfig } from './config' + +export const BROWSER_ID_KEY = 'skillhub.analytics.datafinder.browser-id' +const uuidShape = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i +let pageId: string | undefined +function anonymousId(): string { + if (pageId) return pageId + try { + const stored = localStorage.getItem(BROWSER_ID_KEY) + if (stored && uuidShape.test(stored)) return stored + const id = crypto.randomUUID() + try { localStorage.setItem(BROWSER_ID_KEY, id) } + catch { return pageId ??= id } + return id + } catch { + return pageId ??= crypto.randomUUID() + } +} + +// No remote SDK, batching, retry queue or event persistence. Each intent is bounded. +export function createDatafinderAdapter(config: Record, prefix: string, context: AnalyticsContext = {}): AnalyticsAdapter { + if (!validateDatafinderConfig(config)) return { send: async () => {}, stop() {} } + const appId = config.appId as number, product = (config.product ?? 'skillhub') as string + let stopped = false + return { + async send(intent) { + let timer: ReturnType | undefined + try { + if (stopped) return + const { id, event } = intent + if (typeof id !== 'string' || !/^[a-z]+(?:\.[a-z]+){2,}$/.test(id) || !['click', 'submit', 'keydown'].includes(event)) return + const module = context.currentPageType?.() ?? 'other' + if (stopped) return + const user = anonymousId() + const body = JSON.stringify([{ user: { user_unique_id: user, web_id: user }, header: { app_id: appId, custom: { product, module } }, events: [{ event: id, params: JSON.stringify({ event }), local_time_ms: Date.now() }] }]) + const abort = new AbortController() + // A context getter may synchronously stop collection. No async gap before fetch. + if (stopped) return + await Promise.race([ + fetch(`${prefix}/list`, { method: 'POST', headers: { 'Content-Type': 'application/json' }, body, keepalive: true, credentials: 'omit', referrerPolicy: 'no-referrer', signal: abort.signal }).then(async response => { + if (!response.ok) { + console.error('[analytics] adapter: collector did not accept event') + return + } + const reply: unknown = await response.json() + // HTTP 200 alone is not acceptance. Never log the collector's response. + if (!reply || typeof reply !== 'object' || !('e' in reply) || reply.e !== 0 || !('sc' in reply) || reply.sc !== 1) { + console.error('[analytics] adapter: collector did not accept event') + } + }), + new Promise(resolve => { timer = setTimeout(() => { abort.abort(); resolve() }, 3000) }), + ]) + } catch { /* Analytics errors must never reject into the application. */ } + finally { clearTimeout(timer) } + }, + stop() { stopped = true }, + } +} diff --git a/web/src/features/analytics/adapters/datafinder/config.ts b/web/src/features/analytics/adapters/datafinder/config.ts new file mode 100644 index 000000000..d18c45677 --- /dev/null +++ b/web/src/features/analytics/adapters/datafinder/config.ts @@ -0,0 +1,16 @@ +import type { Diagnostic } from '../../types' + +// Public browser settings only. Server ingestion credentials are not supported. +export function datafinderConfigDiagnostics(config: Record): Diagnostic[] { + if (Object.keys(config).some(key => !['appId', 'product'].includes(key))) return [{ field: 'adapterConfig', reason: 'unknown field' }] + if (typeof config.appId !== 'number' || !Number.isInteger(config.appId) || config.appId < 1 || config.appId > 2147483647) { + return [{ field: 'adapterConfig.appId', reason: 'expected positive 32-bit integer' }] + } + if (Object.prototype.hasOwnProperty.call(config, 'product') && (typeof config.product !== 'string' || !/^[a-z][a-z0-9_]{0,31}$/.test(config.product))) { + return [{ field: 'adapterConfig.product', reason: 'expected lowercase product name' }] + } + return [] +} +export function validateDatafinderConfig(config: Record): boolean { + return datafinderConfigDiagnostics(config).length === 0 +} diff --git a/web/src/features/analytics/config.ts b/web/src/features/analytics/config.ts index 81cc834ab..b4c48db9a 100644 --- a/web/src/features/analytics/config.ts +++ b/web/src/features/analytics/config.ts @@ -20,7 +20,12 @@ export function parseAnalyticsConfig(raw: unknown): { config: AnalyticsConfig | if (adapterConfig !== undefined && !object(adapterConfig)) fail('adapterConfig', 'expected object') if (enabled === true) { if (typeof adapter !== 'string' || !Object.prototype.hasOwnProperty.call(adapters, adapter)) fail('adapter', 'required registered adapter') - else if (!object(adapterConfig) || !adapters[adapter].validate(adapterConfig)) fail('adapterConfig', 'invalid public settings') + else if (!object(adapterConfig)) fail('adapterConfig', 'invalid public settings') + else { + const entry = adapters[adapter] + if (entry.diagnostics) diagnostics.push(...entry.diagnostics(adapterConfig)) + else if (!entry.validate(adapterConfig)) fail('adapterConfig', 'invalid public settings') + } } return { config: diagnostics.length ? null : { enabled, consent, adapter, adapterConfig, ...(Object.prototype.hasOwnProperty.call(value, 'rules') ? { rules } : {}) } as AnalyticsConfig, diagnostics } } catch { fail('config', 'invalid JSON or unreadable object'); return { config: null, diagnostics } } diff --git a/web/src/features/analytics/controller.ts b/web/src/features/analytics/controller.ts index d98af2c43..9ed4f417a 100644 --- a/web/src/features/analytics/controller.ts +++ b/web/src/features/analytics/controller.ts @@ -1,8 +1,8 @@ import { DEFAULT_RULES, observeSkillhubIntents, resolveRules } from './skillhub-intents.mjs' import { adapters } from './registry' -import type { AdapterFactory, AnalyticsAPI, AnalyticsConfig } from './types' +import type { AdapterFactory, AnalyticsAPI, AnalyticsConfig, AnalyticsContext } from './types' -export function createAnalyticsController(config: AnalyticsConfig, options: { root?: Document | Element; factory?: AdapterFactory; prefix?: string } = {}): AnalyticsAPI { +export function createAnalyticsController(config: AnalyticsConfig, options: { root?: Document | Element; factory?: AdapterFactory; prefix?: string; context?: AnalyticsContext } = {}): AnalyticsAPI { let generation = 0 let pending: Promise | undefined let dispose: (() => void) | undefined @@ -26,7 +26,7 @@ export function createAnalyticsController(config: AnalyticsConfig, options: { ro const factory = options.factory ?? adapters[config.adapter!]?.create pending = (async () => { try { - const adapter = await factory(config.adapterConfig ?? {}, options.prefix ?? `${import.meta.env.BASE_URL}_skillhub-analytics`, signal) + const adapter = await factory(config.adapterConfig ?? {}, options.prefix ?? `${import.meta.env.BASE_URL}_skillhub-analytics`, signal, options.context) if (own !== generation) { adapter.stop(); return } const stopObserver = observeSkillhubIntents({ root, rules: active, onIntent: intent => adapter.send(intent) }) dispose = () => { stopObserver(); try { adapter.stop() } catch { /* isolated */ } } diff --git a/web/src/features/analytics/datafinder.test.ts b/web/src/features/analytics/datafinder.test.ts new file mode 100644 index 000000000..2108d4471 --- /dev/null +++ b/web/src/features/analytics/datafinder.test.ts @@ -0,0 +1,155 @@ +/** @vitest-environment jsdom */ +import { afterEach, beforeEach, expect, it, vi } from 'vitest' +import { parseAnalyticsConfig } from './config' +import { adapters } from './registry' +import { createAnalyticsController } from './controller' +import { installAnalyticsLoader } from './loader' +import { BROWSER_ID_KEY } from './adapters/datafinder/adapter' +import { currentPageType } from '../../app/analytics-page-type' +import { createMemoryHistory, createRootRoute, createRoute, createRouter } from '@tanstack/react-router' + +let createDatafinderAdapter: typeof import('./adapters/datafinder/adapter').createDatafinderAdapter +beforeEach(async () => { vi.resetModules(); ({ createDatafinderAdapter } = await import('./adapters/datafinder/adapter')) }) + +const valid = { enabled: true, consent: 'granted' as const, adapter: 'datafinder', adapterConfig: { appId: 123456 } } +const intent = { id: 'skill.download.request', event: 'click' } +const uuid = '4398de8e-40df-4483-9eea-ed213643525f' +afterEach(() => { vi.useRealTimers(); vi.restoreAllMocks(); vi.unstubAllGlobals(); localStorage.clear(); document.body.replaceChildren() }) +it.each([{ appId: 1 }, { appId: 2147483647 }, { appId: 123456, product: 'my_product2' }])('accepts DataFinder public config %j', adapterConfig => { + expect(parseAnalyticsConfig({ ...valid, adapterConfig }).config?.adapterConfig).toEqual(adapterConfig) +}) +it.each([{}, { appId: 0 }, { appId: -1 }, { appId: 1.5 }, { appId: 2147483648 }, { appId: 'PRIVATE' }, { appId: NaN }, { appId: Infinity }])('rejects appId with field-only diagnostics %j', adapterConfig => { + const result = parseAnalyticsConfig({ ...valid, adapterConfig }) + expect(result.config).toBeNull() + expect(result.diagnostics).toEqual([{ field: 'adapterConfig.appId', reason: 'expected positive 32-bit integer' }]) +}) +it.each(['', 'PRIVATE', 'a-b', '1product', 'a'.repeat(33), null, 7])('rejects product %j without values', product => { + const result = parseAnalyticsConfig({ ...valid, adapterConfig: { appId: 1, product } }) + expect(result.config).toBeNull() + expect(result.diagnostics).toEqual([{ field: 'adapterConfig.product', reason: 'expected lowercase product name' }]) +}) +it.each(['appKey', 'X-MCS-AppKey', 'upstream', 'websiteId', 'PRIVATE'])('rejects extra setting %s without echoing its name or value', key => { + const result = parseAnalyticsConfig({ ...valid, adapterConfig: { appId: 1, [key]: 'PRIVATE' } }) + expect(result.config).toBeNull() + expect(result.diagnostics).toEqual([{ field: 'adapterConfig', reason: 'unknown field' }]) +}) +function transport() { + const fetch = vi.fn().mockImplementation(async () => new Response(JSON.stringify({ e: 0, message: 'success', sc: 1, tc: 1 }))) + vi.stubGlobal('fetch', fetch) + vi.spyOn(crypto, 'randomUUID').mockReturnValue(uuid) + return fetch +} +it('sends exact minimal JSON without SDK, account, URL or content; reads generic context at send time', async () => { + const fetch = transport(), now = vi.spyOn(Date, 'now').mockReturnValue(1234) + let pageType = '/skills' + const adapter = createDatafinderAdapter({ appId: 123456, product: 'portal' }, '/base/_skillhub-analytics', { currentPageType: () => pageType }) + pageType = '/space/$namespace/$slug' + await adapter.send({ ...intent, secret: 'PRIVATE' } as typeof intent) + expect(fetch).toHaveBeenCalledTimes(1) + const [url, options] = fetch.mock.calls[0] + expect(url).toBe('/base/_skillhub-analytics/list') + expect(options).toMatchObject({ method: 'POST', headers: { 'Content-Type': 'application/json' }, keepalive: true, credentials: 'omit', referrerPolicy: 'no-referrer' }) + expect(options?.body).toBe(JSON.stringify([{ user: { user_unique_id: uuid, web_id: uuid }, header: { app_id: 123456, custom: { product: 'portal', module: '/space/$namespace/$slug' } }, events: [{ event: intent.id, params: '{"event":"click"}', local_time_ms: 1234 }] }])) + expect(document.querySelector('script')).toBeNull() + expect(now).toHaveBeenCalled() + adapter.stop() +}) +it.each(['click', 'submit', 'keydown'])('retains dotted IDs and native %s, defaults product/module', async event => { + const fetch = transport(), adapter = createDatafinderAdapter({ appId: 1 }, '/_skillhub-analytics') + await adapter.send({ ...intent, event }) + const batch = JSON.parse(fetch.mock.calls[0][1]!.body as string)[0] + expect(batch.header.custom).toEqual({ product: 'skillhub', module: 'other' }) + expect(batch.events[0]).toMatchObject({ event: intent.id, params: JSON.stringify({ event }) }) + adapter.stop() +}) +it('persists only an anonymous UUID and reuses it across adapter instances', async () => { + const fetch = transport() + const a = createDatafinderAdapter({ appId: 1 }, '/_skillhub-analytics'); await a.send(intent); a.stop() + expect(localStorage.getItem(BROWSER_ID_KEY)).toBe(uuid) + const b = createDatafinderAdapter({ appId: 1 }, '/_skillhub-analytics'); await b.send(intent); b.stop() + expect(crypto.randomUUID).toHaveBeenCalledTimes(1) + expect(JSON.parse(fetch.mock.calls[1][1]!.body as string)[0].user).toEqual({ user_unique_id: uuid, web_id: uuid }) +}) +it.each(['getItem', 'setItem'] as const)('uses one in-memory page UUID when storage %s throws', async method => { + const fetch = transport() + vi.spyOn(Storage.prototype, method).mockImplementation(() => { throw Error('PRIVATE') }) + const a = createDatafinderAdapter({ appId: 1 }, '/_skillhub-analytics'); await a.send(intent); a.stop() + const b = createDatafinderAdapter({ appId: 1 }, '/_skillhub-analytics'); await b.send(intent); b.stop() + expect(JSON.parse(fetch.mock.calls[0][1]!.body as string)[0].user).toEqual(JSON.parse(fetch.mock.calls[1][1]!.body as string)[0].user) +}) +it('replaces non-UUID stored values instead of forwarding arbitrary storage data', async () => { + localStorage.setItem(BROWSER_ID_KEY, 'PRIVATE') + const fetch = transport(), a = createDatafinderAdapter({ appId: 1 }, '/_skillhub-analytics') + await a.send(intent); a.stop() + expect(fetch.mock.calls[0][1]?.body).not.toContain('PRIVATE') +}) +it('denied does not import or touch storage/identity; late registered chunk never starts', async () => { + const storage = vi.spyOn(Storage.prototype, 'getItem'), id = vi.spyOn(crypto, 'randomUUID'), load = vi.fn() + const api = installAnalyticsLoader(() => ({ ...valid, consent: 'denied' }), load) + expect(load).not.toHaveBeenCalled(); api.stop() + const signal = new AbortController() + const late = adapters.datafinder.create(valid.adapterConfig, '/_skillhub-analytics', signal.signal) + signal.abort(); const a = await late; await a.send(intent) + expect(storage).not.toHaveBeenCalled(); expect(id).not.toHaveBeenCalled() +}) +it('passes optional generic context through loader and controller without altering helper intents', async () => { + transport() + const context = { currentPageType: () => '/search' } + const factory = vi.fn().mockResolvedValue({ send: vi.fn().mockResolvedValue(undefined), stop() {} }) + const c = createAnalyticsController(valid, { factory, context }); await c.start() + expect(factory.mock.calls[0][3]).toBe(context); c.stop() + const create = vi.fn().mockReturnValue({ start: async () => {}, stop() {} }) + const api = installAnalyticsLoader(() => valid, async () => ({ createAnalyticsController: create }), context) + await api.start(); expect(create.mock.calls[0][1]).toEqual({ context }); api.stop() +}) +it('derives only matched route templates from real parameterized URLs and handles unmatched routes', async () => { + const root = createRootRoute(), detail = createRoute({ getParentRoute: () => root, path: '/space/$namespace/$slug' }) + const router = createRouter({ routeTree: root.addChildren([detail]), history: createMemoryHistory({ initialEntries: ['/space/private-team/private-skill?token=PRIVATE#PRIVATE'] }) }) + await router.load() + expect(currentPageType(router)).toBe('/space/$namespace/$slug') + await router.navigate({ to: '/not-found' as string }); await router.load() + expect(currentPageType(router)).toBe('other') +}) +it('stop prevents all later dispatch including stop reentrancy from context', async () => { + const fetch = transport() + const a = createDatafinderAdapter({ appId: 1 }, '/_skillhub-analytics', { currentPageType: () => { a.stop(); return '/skills' } }) + await expect(a.send(intent)).resolves.toBeUndefined(); expect(fetch).not.toHaveBeenCalled() + await a.send(intent); expect(fetch).not.toHaveBeenCalled() +}) +it.each(['network', 'throw', 'timeout', 'non-json', 'body-timeout', 'rejected', 'empty'])('send never rejects or retries on %s; bound is 3 seconds', async mode => { + vi.useFakeTimers() + const fetch = transport(), error = vi.spyOn(console, 'error').mockImplementation(() => {}) + if (mode === 'network') fetch.mockRejectedValue(Error('PRIVATE')) + if (mode === 'throw') fetch.mockImplementation(() => { throw Error('PRIVATE') }) + if (mode === 'timeout') fetch.mockImplementation(() => new Promise(() => {})) + if (mode === 'body-timeout') fetch.mockResolvedValue({ ok: true, json: () => new Promise(() => {}) } as Response) + if (mode === 'non-json') fetch.mockResolvedValue(new Response('PRIVATE')) + if (mode === 'rejected') fetch.mockResolvedValue(new Response('{"e":1,"sc":1}')) + if (mode === 'empty') fetch.mockResolvedValue(new Response('{"e":0,"sc":0}')) + const a = createDatafinderAdapter({ appId: 1 }, '/_skillhub-analytics') + const sent = a.send(intent) + await vi.advanceTimersByTimeAsync(3000); await expect(sent).resolves.toBeUndefined() + expect(fetch).toHaveBeenCalledTimes(1) + if (['timeout', 'body-timeout'].includes(mode)) expect(fetch.mock.calls[0][1]?.signal?.aborted).toBe(true) + expect(JSON.stringify(error.mock.calls)).not.toContain('PRIVATE') + a.stop() +}) +it('does not block another send behind an unfinished request and cannot recall dispatched requests', async () => { + vi.useFakeTimers(); const fetch = transport() + fetch.mockImplementationOnce(() => new Promise(() => {})) + const a = createDatafinderAdapter({ appId: 1 }, '/_skillhub-analytics') + const first = a.send(intent); await a.send(intent); expect(fetch).toHaveBeenCalledTimes(2) + a.stop(); await a.send(intent); expect(fetch).toHaveBeenCalledTimes(2) + await vi.advanceTimersByTimeAsync(3000); await first +}) +it.each([['{"e":0,"sc":0}', 200], ['{"e":1,"sc":1}', 200], ['{"e":0,"sc":"1"}', 200], ['{"e":0,"sc":1}', 400]])('does not mistake HTTP or invalid acceptance counters for success: %s %s', async (reply, status) => { + const fetch = transport(), error = vi.spyOn(console, 'error').mockImplementation(() => {}) + fetch.mockResolvedValue(new Response(reply as string, { status: status as number })) + const a = createDatafinderAdapter({ appId: 1 }, '/_skillhub-analytics') + await a.send(intent); a.stop() + expect(error).toHaveBeenCalledExactlyOnceWith('[analytics] adapter: collector did not accept event') +}) +it.each([{ id: 'bad', event: 'click' }, { ...intent, event: 'input' }])('drops invalid intents %j', async input => { + const fetch = transport(), a = createDatafinderAdapter({ appId: 1 }, '/_skillhub-analytics') + await a.send(input); expect(fetch).not.toHaveBeenCalled(); a.stop() +}) diff --git a/web/src/features/analytics/loader.ts b/web/src/features/analytics/loader.ts index 82b0f7844..038f100ef 100644 --- a/web/src/features/analytics/loader.ts +++ b/web/src/features/analytics/loader.ts @@ -1,9 +1,9 @@ import { parseAnalyticsConfig, reportDiagnostics } from './config' -import type { AnalyticsAPI } from './types' +import type { AnalyticsAPI, AnalyticsContext } from './types' import type { createAnalyticsController } from './controller' type Module = { createAnalyticsController: typeof createAnalyticsController } -export function installAnalyticsLoader(read: () => unknown, load: () => Promise = () => import('./controller')): AnalyticsAPI { +export function installAnalyticsLoader(read: () => unknown, load: () => Promise = () => import('./controller'), context?: AnalyticsContext): AnalyticsAPI { let generation = 0 let controller: AnalyticsAPI | undefined let pending: Promise | undefined @@ -28,7 +28,7 @@ export function installAnalyticsLoader(read: () => unknown, load: () => Promise< try { const module = await load() if (own !== generation) return - controller = module.createAnalyticsController({ ...config, consent: 'granted' }) + controller = module.createAnalyticsController({ ...config, consent: 'granted' }, { context }) await controller.start() } catch { console.error('[analytics] module: initialization failed') } })() diff --git a/web/src/features/analytics/registry.ts b/web/src/features/analytics/registry.ts index 23b3e9e0d..8dfdaf6ad 100644 --- a/web/src/features/analytics/registry.ts +++ b/web/src/features/analytics/registry.ts @@ -1,8 +1,18 @@ import { validateUmamiConfig } from './adapters/umami/config' -import type { AdapterFactory } from './types' +import { validateDatafinderConfig, datafinderConfigDiagnostics } from './adapters/datafinder/config' +import type { AdapterFactory, Diagnostic } from './types' // Static allowlist: metadata validation is tiny; adapter code is a lazy chunk. -export const adapters: Readonly): boolean; create: AdapterFactory }>> = Object.freeze({ +export const adapters: Readonly): boolean; diagnostics?(config: Record): Diagnostic[]; create: AdapterFactory }>> = Object.freeze({ + datafinder: { + validate: validateDatafinderConfig, + diagnostics: datafinderConfigDiagnostics, + create: async (config, prefix, signal, context) => { + const { createDatafinderAdapter } = await import('./adapters/datafinder/adapter') + if (signal?.aborted) return { send: async () => {}, stop() {} } + return createDatafinderAdapter(config, prefix, context) + }, + }, umami: { validate: validateUmamiConfig, create: async (config, prefix, signal) => { diff --git a/web/src/features/analytics/runtime.test.ts b/web/src/features/analytics/runtime.test.ts index a76f977bc..ff89e0012 100644 --- a/web/src/features/analytics/runtime.test.ts +++ b/web/src/features/analytics/runtime.test.ts @@ -24,7 +24,7 @@ it('defaults closed, preserves rules replacement and delegates adapter validatio expect(parseAnalyticsConfig({}).config).toMatchObject({ enabled: false, consent: 'denied' }) expect(parseAnalyticsConfig({ ...valid, rules: {} }).config?.rules).toEqual({}) expect(parseAnalyticsConfig(valid).config).not.toHaveProperty('websiteId') - expect(Object.keys(adapters)).toEqual(['umami']) + expect(Object.keys(adapters).sort()).toEqual(['datafinder', 'umami']) expect(parseAnalyticsConfig({ ...valid, adapter: '__proto__' }).config).toBeNull() }) it('cancels a late module before controller initialization; start explicitly grants consent', async () => { diff --git a/web/src/features/analytics/types.ts b/web/src/features/analytics/types.ts index fbe405dc0..cafc9348a 100644 --- a/web/src/features/analytics/types.ts +++ b/web/src/features/analytics/types.ts @@ -11,6 +11,7 @@ export interface AnalyticsAdapter { send(intent: SkillhubIntent): Promise stop(): void } -export type AdapterFactory = (config: Record, prefix: string, signal?: AbortSignal) => Promise +export interface AnalyticsContext { currentPageType?: () => string } +export type AdapterFactory = (config: Record, prefix: string, signal?: AbortSignal, context?: AnalyticsContext) => Promise export interface AnalyticsAPI { start(): Promise; stop(): void } export interface Diagnostic { field: string; reason: string }