feat(analytics): register configuration-only DataFinder adapter

Refs #989

Signed-off-by: 千乘妍 (Xiaoyaner) <258399167+xiaoyaner0201@users.noreply.github.com>
This commit is contained in:
千乘妍 (Xiaoyaner) 2026-11-02 14:38:38 +08:00
parent f8ab71e28e
commit 987068cc6f
16 changed files with 353 additions and 24 deletions

View file

@ -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"

View file

@ -0,0 +1,4 @@
web:
analytics:
config: '{"enabled":true,"adapter":"datafinder","consent":"granted","adapterConfig":{"appId":123456,"product":"skillhub"}}'
upstream: https://collector.example.com

View file

@ -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()

View file

@ -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"
}

View file

@ -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

View file

@ -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, { fullPath: string }>
}): 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'
}

View file

@ -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) })
})
})()

View file

@ -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<string, unknown>, 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<typeof setTimeout> | 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<void>(resolve => { timer = setTimeout(() => { abort.abort(); resolve() }, 3000) }),
])
} catch { /* Analytics errors must never reject into the application. */ }
finally { clearTimeout(timer) }
},
stop() { stopped = true },
}
}

View file

@ -0,0 +1,16 @@
import type { Diagnostic } from '../../types'
// Public browser settings only. Server ingestion credentials are not supported.
export function datafinderConfigDiagnostics(config: Record<string, unknown>): 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<string, unknown>): boolean {
return datafinderConfigDiagnostics(config).length === 0
}

View file

@ -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 } }

View file

@ -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<void> | 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 */ } }

View file

@ -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<typeof globalThis.fetch>().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()
})

View file

@ -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<Module> = () => import('./controller')): AnalyticsAPI {
export function installAnalyticsLoader(read: () => unknown, load: () => Promise<Module> = () => import('./controller'), context?: AnalyticsContext): AnalyticsAPI {
let generation = 0
let controller: AnalyticsAPI | undefined
let pending: Promise<void> | 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') }
})()

View file

@ -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<Record<string, { validate(config: Record<string, unknown>): boolean; create: AdapterFactory }>> = Object.freeze({
export const adapters: Readonly<Record<string, { validate(config: Record<string, unknown>): boolean; diagnostics?(config: Record<string, unknown>): 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) => {

View file

@ -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 () => {

View file

@ -11,6 +11,7 @@ export interface AnalyticsAdapter {
send(intent: SkillhubIntent): Promise<void>
stop(): void
}
export type AdapterFactory = (config: Record<string, unknown>, prefix: string, signal?: AbortSignal) => Promise<AnalyticsAdapter>
export interface AnalyticsContext { currentPageType?: () => string }
export type AdapterFactory = (config: Record<string, unknown>, prefix: string, signal?: AbortSignal, context?: AnalyticsContext) => Promise<AnalyticsAdapter>
export interface AnalyticsAPI { start(): Promise<void>; stop(): void }
export interface Diagnostic { field: string; reason: string }