add experimental global scope executor that is impractical because of the reliance on globals

silesky · silesky · commit a347bce764cf · 2025-04-28T17:20:25.000-05:00
diff --git a/packages/signals/signals-example/public/index.html b/packages/signals/signals-example/public/index.html
@@ -5,10 +5,17 @@
   <meta charset="UTF-8">
   <meta name="viewport" content="width=device-width, initial-scale=1.0">
   <title>React TypeScript App</title>
+  <!---
+  
+1. Requres 'unsafe-inline'
+- Refused to execute inline script because it violates the following Content Security Policy directive: [directive] Either the 'unsafe-inline' keyword, a hash ('sha256-XDT/UwTV/dYYXFad1cmKD+q1zZNK8KGVRYvIdvkmo7I='), or a nonce ('nonce-...') is required to enable inline execution.
+2. Requires 'unsafe-eval'
+processSignal() error in sandbox Error: Refused to evaluate a string as JavaScript because 'unsafe-eval' is not an allowed source of script in the following Content Security Policy directive
+  -->
+    <meta http-equiv="Content-Security-Policy" content="script-src 'self' https://*.segment.com https://*.googletagmanager.com blob:">
 </head>
-
 <body>
   <div id="root"></div>
 </body>
 
-</html>
+</html>
diff --git a/packages/signals/signals/src/core/middleware/event-processor/index.ts b/packages/signals/signals/src/core/middleware/event-processor/index.ts
@@ -2,17 +2,48 @@ import { Signal } from '@segment/analytics-signals-runtime'
 import { SignalBuffer } from '../../buffer'
 import { SignalsSubscriber, SignalsMiddlewareContext } from '../../emitter'
 import { SignalEventProcessor } from '../../processor/processor'
-import { Sandbox, SandboxSettings } from '../../processor/sandbox'
+import {
+  normalizeEdgeFunctionURL,
+  GlobalScopeSandbox,
+  WorkerSandbox,
+  WorkerSandboxSettings,
+  SignalSandbox,
+  NoopSandbox,
+} from '../../processor/sandbox'
+
+const GLOBAL_SCOPE_SANDBOX = true
 
 export class SignalsEventProcessorSubscriber implements SignalsSubscriber {
   processor!: SignalEventProcessor
   buffer!: SignalBuffer
   load(ctx: SignalsMiddlewareContext) {
     this.buffer = ctx.buffer
-    this.processor = new SignalEventProcessor(
-      ctx.analyticsInstance,
-      new Sandbox(new SandboxSettings(ctx.unstableGlobalSettings.sandbox))
+    const sandboxSettings = ctx.unstableGlobalSettings.sandbox
+    const normalizedEdgeFunctionURL = normalizeEdgeFunctionURL(
+      sandboxSettings.functionHost,
+      sandboxSettings.edgeFnDownloadURL
     )
+
+    let sandbox: SignalSandbox
+    if (!normalizedEdgeFunctionURL) {
+      console.warn(
+        `No processSignal function found. Have you written a processSignal function on app.segment.com?`
+      )
+      sandbox = new NoopSandbox()
+    } else if (!GLOBAL_SCOPE_SANDBOX) {
+      sandbox = new WorkerSandbox(
+        new WorkerSandboxSettings({
+          processSignal: sandboxSettings.processSignal,
+          edgeFnDownloadURL: normalizedEdgeFunctionURL,
+        })
+      )
+    } else {
+      sandbox = new GlobalScopeSandbox({
+        edgeFnDownloadURL: normalizedEdgeFunctionURL,
+      })
+    }
+
+    this.processor = new SignalEventProcessor(ctx.analyticsInstance, sandbox)
   }
   async process(signal: Signal) {
     return this.processor.process(signal, await this.buffer.getAll())
diff --git a/packages/signals/signals/src/core/processor/__tests__/sandbox-settings.test.ts b/packages/signals/signals/src/core/processor/__tests__/sandbox-settings.test.ts
@@ -1,6 +1,6 @@
-import { SandboxSettings, SandboxSettingsConfig } from '../sandbox'
+import { WorkerSandboxSettings, SandboxSettingsConfig } from '../sandbox'
 
-describe(SandboxSettings, () => {
+describe(WorkerSandboxSettings, () => {
   const edgeFnResponseBody = `function processSignal() { console.log('hello world') }`
   const baseSettings: SandboxSettingsConfig = {
     functionHost: undefined,
@@ -13,7 +13,7 @@ describe(SandboxSettings, () => {
     ),
   }
   test('initializes with provided settings', async () => {
-    const sandboxSettings = new SandboxSettings({ ...baseSettings })
+    const sandboxSettings = new WorkerSandboxSettings({ ...baseSettings })
     expect(baseSettings.edgeFnFetchClient).toHaveBeenCalledWith(
       baseSettings.edgeFnDownloadURL
     )
@@ -27,7 +27,7 @@ describe(SandboxSettings, () => {
       functionHost: 'newHost.com',
       edgeFnDownloadURL: 'https://original.com/download',
     }
-    new SandboxSettings(settings)
+    new WorkerSandboxSettings(settings)
     expect(baseSettings.edgeFnFetchClient).toHaveBeenCalledWith(
       'https://newHost.com/download'
     )
@@ -42,7 +42,7 @@ describe(SandboxSettings, () => {
       processSignal: undefined,
       edgeFnDownloadURL: undefined,
     }
-    const sandboxSettings = new SandboxSettings(settings)
+    const sandboxSettings = new WorkerSandboxSettings(settings)
     expect(await sandboxSettings.processSignal).toEqual(
       'globalThis.processSignal = function processSignal() {}'
     )
diff --git a/packages/signals/signals/src/core/processor/processor.ts b/packages/signals/signals/src/core/processor/processor.ts
@@ -1,20 +1,21 @@
 import { logger } from '../../lib/logger'
 import { Signal } from '@segment/analytics-signals-runtime'
 import { AnyAnalytics } from '../../types'
-import { AnalyticsMethodCalls, MethodName, Sandbox } from './sandbox'
+import { AnalyticsMethodCalls, MethodName, SignalSandbox } from './sandbox'
 
 export class SignalEventProcessor {
-  private sandbox: Sandbox
-  private analytics: AnyAnalytics
-  constructor(analytics: AnyAnalytics, sandbox: Sandbox) {
+  analytics: AnyAnalytics
+  sandbox: SignalSandbox
+  constructor(analytics: AnyAnalytics, sandbox: SignalSandbox) {
     this.analytics = analytics
     this.sandbox = sandbox
   }
 
   async process(signal: Signal, signals: Signal[]) {
-    let analyticsMethodCalls: AnalyticsMethodCalls
+    await this.sandbox.isLoaded()
+    let analyticsMethodCalls: AnalyticsMethodCalls | undefined
     try {
-      analyticsMethodCalls = await this.sandbox.process(signal, signals)
+      analyticsMethodCalls = await this.sandbox.execute(signal, signals)
     } catch (err) {
       // in practice, we should never hit this error, but if we do, we should log it.
       console.error('Error processing signal', { signal, signals }, err)
@@ -34,6 +35,6 @@ export class SignalEventProcessor {
   }
 
   cleanup() {
-    return this.sandbox.jsSandbox.destroy()
+    return this.sandbox.destroy()
   }
 }
diff --git a/packages/signals/signals/src/core/processor/sandbox.ts b/packages/signals/signals/src/core/processor/sandbox.ts
@@ -3,9 +3,14 @@ import { createWorkerBox, WorkerBoxAPI } from '../../lib/workerbox'
 import { resolvers } from './arg-resolvers'
 import { AnalyticsRuntimePublicApi } from '../../types'
 import { replaceBaseUrl } from '../../lib/replace-base-url'
-import { Signal } from '@segment/analytics-signals-runtime'
+import {
+  Signal,
+  WebRuntimeConstants,
+  WebSignalsRuntime,
+} from '@segment/analytics-signals-runtime'
 import { getRuntimeCode } from '@segment/analytics-signals-runtime'
 import { polyfills } from './polyfills'
+import { loadScript } from '../../lib/load-script'
 
 export type MethodName =
   | 'page'
@@ -151,14 +156,30 @@ class JavascriptSandbox implements CodeSandbox {
   }
 }
 
+export const normalizeEdgeFunctionURL = (
+  functionHost: string | undefined,
+  edgeFnDownloadURL: string | undefined
+) => {
+  if (functionHost && edgeFnDownloadURL) {
+    replaceBaseUrl(edgeFnDownloadURL, `https://${functionHost}`)
+  } else {
+    return edgeFnDownloadURL
+  }
+}
+
 export type SandboxSettingsConfig = {
   functionHost: string | undefined
   processSignal: string | undefined
   edgeFnDownloadURL: string | undefined
   edgeFnFetchClient?: typeof fetch
 }
 
-export class SandboxSettings {
+export type WorkerboxSettingsConfig = Pick<
+  SandboxSettingsConfig,
+  'processSignal' | 'edgeFnFetchClient' | 'edgeFnDownloadURL'
+>
+
+export class WorkerSandboxSettings {
   /**
    * Should look like:
    * ```js
@@ -168,48 +189,42 @@ export class SandboxSettings {
    * ```
    */
   processSignal: Promise<string>
-  constructor(settings: SandboxSettingsConfig) {
-    const edgeFnDownloadURLNormalized =
-      settings.functionHost && settings.edgeFnDownloadURL
-        ? replaceBaseUrl(
-            settings.edgeFnDownloadURL,
-            `https://${settings.functionHost}`
-          )
-        : settings.edgeFnDownloadURL
-
-    if (!edgeFnDownloadURLNormalized && !settings.processSignal) {
-      // user may be onboarding and not have written a signal -- so do a noop so we can collect signals
-      this.processSignal = Promise.resolve(
-        `globalThis.processSignal = function processSignal() {}`
-      )
-      console.warn(
-        `No processSignal function found. Have you written a processSignal function on app.segment.com?`
-      )
-      return
-    }
-
+  constructor(settings: WorkerboxSettingsConfig) {
     const fetch = settings.edgeFnFetchClient ?? globalThis.fetch
 
     const processSignalNormalized = settings.processSignal
       ? Promise.resolve(settings.processSignal).then(
           (str) => `globalThis.processSignal = ${str}`
         )
-      : fetch(edgeFnDownloadURLNormalized!).then((res) => res.text())
+      : fetch(settings.edgeFnDownloadURL!).then((res) => res.text())
 
     this.processSignal = processSignalNormalized
   }
 }
 
-export class Sandbox {
-  settings: SandboxSettings
+export interface SignalSandbox {
+  isLoaded(): Promise<void>
+  execute(
+    signal: Signal,
+    signals: Signal[]
+  ): Promise<AnalyticsMethodCalls | undefined>
+  destroy(): void | Promise<void>
+}
+
+export class WorkerSandbox implements SignalSandbox {
+  settings: WorkerSandboxSettings
   jsSandbox: CodeSandbox
 
-  constructor(settings: SandboxSettings) {
+  constructor(settings: WorkerSandboxSettings) {
     this.settings = settings
     this.jsSandbox = new JavascriptSandbox()
   }
 
-  async process(
+  isLoaded(): Promise<any> {
+    return Promise.resolve() // TODO
+  }
+
+  async execute(
     signal: Signal,
     signals: Signal[]
   ): Promise<AnalyticsMethodCalls> {
@@ -232,4 +247,64 @@ export class Sandbox {
     const calls = analytics.getCalls()
     return calls
   }
+  destroy(): void {
+    void this.jsSandbox.destroy()
+  }
+}
+
+// This is not ideal -- but processSignal currently depends on
+
+const processWithGlobals = (
+  signalBuffer: Signal[]
+): AnalyticsMethodCalls | undefined => {
+  const g = globalThis as any
+  // Load all constants into the global scope
+  Object.entries(WebRuntimeConstants).forEach(([key, value]) => {
+    g[key] = value
+  })
+
+  // processSignal expects a global called `signals` -- of course, there can local variable naming conflict on the client, which is why globals were a bad idea.
+  g['signals'] = new WebSignalsRuntime(signalBuffer)
+
+  // expect analytics to be instantiated -- this will conflict in the global scope TODO
+  g['analytics'] = new AnalyticsRuntime()
+
+  // another possible namespace conflict?
+  // @ts-ignore
+  if (typeof processSignal != 'undefined') {
+    g['processSignal'](signalBuffer[0])
+  } else {
+    console.warn('no processSignal function is defined in the global scope')
+  }
+
+  return g['analytics'].getCalls()
+}
+
+interface GlobalScopeSandboxSettings {
+  edgeFnDownloadURL: string
+}
+export class GlobalScopeSandbox implements SignalSandbox {
+  script: Promise<HTMLScriptElement>
+  async isLoaded(): Promise<void> {
+    await this.script
+  }
+  constructor(settings: GlobalScopeSandboxSettings) {
+    this.script = loadScript(settings.edgeFnDownloadURL)
+  }
+
+  // eslint-disable-next-line @typescript-eslint/require-await
+  async execute(_signal: Signal, signals: Signal[]) {
+    return processWithGlobals(signals)
+  }
+  destroy(): void {}
+}
+
+export class NoopSandbox implements SignalSandbox {
+  async isLoaded(): Promise<void> {}
+  execute(_signal: Signal, _signals: Signal[]) {
+    return Promise.resolve(undefined)
+  }
+  destroy(): void | Promise<void> {
+    return
+  }
 }
diff --git a/packages/signals/signals/src/lib/load-script/index.ts b/packages/signals/signals/src/lib/load-script/index.ts
@@ -0,0 +1,66 @@
+function findScript(src: string): HTMLScriptElement | undefined {
+  const scripts = Array.prototype.slice.call(
+    window.document.querySelectorAll('script')
+  )
+  return scripts.find((s) => s.src === src)
+}
+
+/**
+ * Load a script from a URL and append it to the document head
+ */
+export function loadScript(
+  src: string,
+  attributes?: Record<string, string>
+): Promise<HTMLScriptElement> {
+  const found = findScript(src)
+
+  if (found !== undefined) {
+    const status = found?.getAttribute('status')
+
+    if (status === 'loaded') {
+      return Promise.resolve(found)
+    }
+
+    if (status === 'loading') {
+      return new Promise((resolve, reject) => {
+        found.addEventListener('load', () => resolve(found))
+        found.addEventListener('error', (err) => reject(err))
+      })
+    }
+  }
+
+  return new Promise((resolve, reject) => {
+    const script = window.document.createElement('script')
+
+    script.type = 'text/javascript'
+    script.src = src
+    script.async = true
+
+    script.setAttribute('status', 'loading')
+    for (const [k, v] of Object.entries(attributes ?? {})) {
+      script.setAttribute(k, v)
+    }
+
+    script.onload = (): void => {
+      script.onerror = script.onload = null
+      script.setAttribute('status', 'loaded')
+      resolve(script)
+    }
+
+    script.onerror = (): void => {
+      script.onerror = script.onload = null
+      script.setAttribute('status', 'error')
+      reject(new Error(`Failed to load ${src}`))
+    }
+
+    const firstExistingScript = window.document.querySelector('script')
+    if (!firstExistingScript) {
+      window.document.head.appendChild(script)
+    } else {
+      firstExistingScript.parentElement?.insertBefore(
+        script,
+        firstExistingScript
+      )
+    }
+  })
+}

Original file line number	Diff line number	Diff line change
`@@ -1,6 +1,6 @@`
`1`		`-import { SandboxSettings, SandboxSettingsConfig } from '../sandbox'`
	`1`	`+import { WorkerSandboxSettings, SandboxSettingsConfig } from '../sandbox'`
`2`	`2`
`3`		`-describe(SandboxSettings, () => {`
	`3`	`+describe(WorkerSandboxSettings, () => {`
`4`	`4`	const edgeFnResponseBody = `function processSignal() { console.log('hello world') }`
`5`	`5`	`const baseSettings: SandboxSettingsConfig = {`
`6`	`6`	`functionHost: undefined,`
`@@ -13,7 +13,7 @@ describe(SandboxSettings, () => {`
`13`	`13`	`),`
`14`	`14`	`}`
`15`	`15`	`test('initializes with provided settings', async () => {`
`16`		`- const sandboxSettings = new SandboxSettings({ ...baseSettings })`
	`16`	`+ const sandboxSettings = new WorkerSandboxSettings({ ...baseSettings })`
`17`	`17`	`expect(baseSettings.edgeFnFetchClient).toHaveBeenCalledWith(`
`18`	`18`	`baseSettings.edgeFnDownloadURL`
`19`	`19`	`)`
`@@ -27,7 +27,7 @@ describe(SandboxSettings, () => {`
`27`	`27`	`functionHost: 'newHost.com',`
`28`	`28`	`edgeFnDownloadURL: 'https://original.com/download',`
`29`	`29`	`}`
`30`		`- new SandboxSettings(settings)`
	`30`	`+ new WorkerSandboxSettings(settings)`
`31`	`31`	`expect(baseSettings.edgeFnFetchClient).toHaveBeenCalledWith(`
`32`	`32`	`'https://newHost.com/download'`
`33`	`33`	`)`
`@@ -42,7 +42,7 @@ describe(SandboxSettings, () => {`
`42`	`42`	`processSignal: undefined,`
`43`	`43`	`edgeFnDownloadURL: undefined,`
`44`	`44`	`}`
`45`		`- const sandboxSettings = new SandboxSettings(settings)`
	`45`	`+ const sandboxSettings = new WorkerSandboxSettings(settings)`
`46`	`46`	`expect(await sandboxSettings.processSignal).toEqual(`
`47`	`47`	`'globalThis.processSignal = function processSignal() {}'`
`48`	`48`	`)`