update readme

Author: silesky

.changeset/eight-adults-type.md

@@ -0,0 +1,5 @@
+---
+'@segment/analytics-signals': minor
+---
+
+Add globalscope strategy

packages/signals/signals-example/src/lib/analytics.ts

@@ -33,7 +33,7 @@ const isStage = process.env.STAGE === 'true'
 
 const signalsPlugin = new SignalsPlugin({
   ...(isStage ? { apiHost: 'signals.segment.build/v1' } : {}),
-  // enableDebugLogging: true,
+  sandboxStrategy: 'global',
   // processSignal: processSignalExample,
 })
 

packages/signals/signals/README.md

@@ -86,6 +86,14 @@ signalsPlugin.addSignal({ someData: 'foo' })
 }
 ```
 
+### Sandbox Strategies
+If getting CSP errors, you can use the experimental 'global' sandbox strategy.
+
+```ts
+new SignalsPlugin({ sandboxStrategy: 'global' })
+```
+
+
 ### Debugging  
 Debug mode **MUST** be enabled on the client to VIEW signals on segment.com.
 

packages/signals/signals/src/core/middleware/event-processor/index.ts

@@ -1,18 +1,17 @@
 import { Signal } from '@segment/analytics-signals-runtime'
+import { logger } from '../../../lib/logger'
 import { SignalBuffer } from '../../buffer'
 import { SignalsSubscriber, SignalsMiddlewareContext } from '../../emitter'
 import { SignalEventProcessor } from '../../processor/processor'
 import {
   normalizeEdgeFunctionURL,
   GlobalScopeSandbox,
   WorkerSandbox,
-  WorkerSandboxSettings,
+  IframeSandboxSettings,
   SignalSandbox,
   NoopSandbox,
 } from '../../processor/sandbox'
 
-const GLOBAL_SCOPE_SANDBOX = true
-
 export class SignalsEventProcessorSubscriber implements SignalsSubscriber {
   processor!: SignalEventProcessor
   buffer!: SignalBuffer
@@ -25,19 +24,26 @@ export class SignalsEventProcessorSubscriber implements SignalsSubscriber {
     )
 
     let sandbox: SignalSandbox
+    console.log('sup')
     if (!normalizedEdgeFunctionURL) {
       console.warn(
         `No processSignal function found. Have you written a processSignal function on app.segment.com?`
       )
+      logger.debug('Initializing sandbox: noop')
       sandbox = new NoopSandbox()
-    } else if (!GLOBAL_SCOPE_SANDBOX || sandboxSettings.processSignal) {
+    } else if (
+      sandboxSettings.sandboxStrategy === 'iframe' ||
+      sandboxSettings.processSignal
+    ) {
+      logger.debug('Initializing sandbox: iframe')
       sandbox = new WorkerSandbox(
-        new WorkerSandboxSettings({
+        new IframeSandboxSettings({
           processSignal: sandboxSettings.processSignal,
           edgeFnDownloadURL: normalizedEdgeFunctionURL,
         })
       )
     } else {
+      logger.debug('Initializing sandbox: global scope')
       sandbox = new GlobalScopeSandbox({
         edgeFnDownloadURL: normalizedEdgeFunctionURL,
       })

packages/signals/signals/src/core/processor/__tests__/sandbox-settings.test.ts

@@ -1,9 +1,8 @@
-import { WorkerSandboxSettings, SandboxSettingsConfig } from '../sandbox'
+import { IframeSandboxSettings, IframeSandboxSettingsConfig } from '../sandbox'
 
-describe(WorkerSandboxSettings, () => {
+describe(IframeSandboxSettings, () => {
   const edgeFnResponseBody = `function processSignal() { console.log('hello world') }`
-  const baseSettings: SandboxSettingsConfig = {
-    functionHost: undefined,
+  const baseSettings: IframeSandboxSettingsConfig = {
     processSignal: undefined,
     edgeFnDownloadURL: 'http://example.com/download',
     edgeFnFetchClient: jest.fn().mockReturnValue(
@@ -13,21 +12,21 @@ describe(WorkerSandboxSettings, () => {
     ),
   }
   test('initializes with provided settings', async () => {
-    const sandboxSettings = new WorkerSandboxSettings({ ...baseSettings })
+    const sandboxSettings = new IframeSandboxSettings({ ...baseSettings })
     expect(baseSettings.edgeFnFetchClient).toHaveBeenCalledWith(
       baseSettings.edgeFnDownloadURL
     )
     expect(await sandboxSettings.processSignal).toEqual(edgeFnResponseBody)
   })
 
   test('normalizes edgeFnDownloadURL when functionHost is provided', async () => {
-    const settings: SandboxSettingsConfig = {
+    const settings = {
       ...baseSettings,
       processSignal: undefined,
       functionHost: 'newHost.com',
       edgeFnDownloadURL: 'https://original.com/download',
     }
-    new WorkerSandboxSettings(settings)
+    new IframeSandboxSettings(settings)
     expect(baseSettings.edgeFnFetchClient).toHaveBeenCalledWith(
       'https://newHost.com/download'
     )
@@ -37,12 +36,12 @@ describe(WorkerSandboxSettings, () => {
     const consoleWarnSpy = jest
       .spyOn(console, 'warn')
       .mockImplementation(() => {})
-    const settings: SandboxSettingsConfig = {
+    const settings = {
       ...baseSettings,
       processSignal: undefined,
       edgeFnDownloadURL: undefined,
     }
-    const sandboxSettings = new WorkerSandboxSettings(settings)
+    const sandboxSettings = new IframeSandboxSettings(settings)
     expect(await sandboxSettings.processSignal).toEqual(
       'globalThis.processSignal = function processSignal() {}'
     )

packages/signals/signals/src/core/processor/sandbox.ts

@@ -172,21 +172,15 @@ export type SandboxSettingsConfig = {
   processSignal: string | undefined
   edgeFnDownloadURL: string | undefined
   edgeFnFetchClient?: typeof fetch
-  /**
-   * What sandbox strategy to use
-   * default - use a web worker and regular evaluation
-   * globalScope - evaluate everything in the global scope -- this avoids CSP errors
-   * @default 'default'
-   */
-  sandboxStrategy?: 'default' | 'globalScope'
+  sandboxStrategy: 'iframe' | 'global'
 }
 
-export type WorkerboxSettingsConfig = Pick<
+export type IframeSandboxSettingsConfig = Pick<
   SandboxSettingsConfig,
   'processSignal' | 'edgeFnFetchClient' | 'edgeFnDownloadURL'
 >
 
-export class WorkerSandboxSettings {
+export class IframeSandboxSettings {
   /**
    * Should look like:
    * ```js
@@ -196,7 +190,7 @@ export class WorkerSandboxSettings {
    * ```
    */
   processSignal: Promise<string>
-  constructor(settings: WorkerboxSettingsConfig) {
+  constructor(settings: IframeSandboxSettingsConfig) {
     const fetch = settings.edgeFnFetchClient ?? globalThis.fetch
 
     const processSignalNormalized = settings.processSignal
@@ -218,10 +212,10 @@ export interface SignalSandbox {
 }
 
 export class WorkerSandbox implements SignalSandbox {
-  settings: WorkerSandboxSettings
+  settings: IframeSandboxSettings
   jsSandbox: CodeSandbox
 
-  constructor(settings: WorkerSandboxSettings) {
+  constructor(settings: IframeSandboxSettings) {
     this.settings = settings
     this.jsSandbox = new JavascriptSandbox()
   }
@@ -280,11 +274,9 @@ const processWithGlobalScopeExecutionEnv = (
   const originalAnalytics = g.analytics
   try {
     if (g['analytics'] instanceof AnalyticsRuntime) {
-      console.warn(
+      throw new Error(
         'Invariant: analytics variable was not properly restored on the previous execution. This indicates a concurrency bug'
       )
-
-      return
     }
 
     g['analytics'] = analytics
@@ -319,6 +311,7 @@ export class GlobalScopeSandbox implements SignalSandbox {
   htmlScriptLoaded: Promise<HTMLScriptElement>
 
   constructor(settings: GlobalScopeSandboxSettings) {
+    logger.debug('Initializing global scope sandbox')
     this.htmlScriptLoaded = loadScript(settings.edgeFnDownloadURL)
   }
 

packages/signals/signals/src/core/signals/settings.ts

@@ -28,6 +28,7 @@ export type SignalsSettingsConfig = Pick<
   | 'mutationGenPollInterval'
   | 'mutationGenObservedAttributes'
   | 'debug'
+  | 'sandboxStrategy'
 > & {
   signalStorage?: SignalPersistentStorage
   processSignal?: string
@@ -89,6 +90,7 @@ export class SignalGlobalSettings {
       },
     }
     this.sandbox = {
+      sandboxStrategy: settings.sandboxStrategy ?? 'iframe',
       functionHost: settings.functionHost,
       processSignal: settings.processSignal,
       edgeFnDownloadURL: undefined,

packages/signals/signals/src/plugin/signals-plugin.ts

@@ -34,24 +34,11 @@ export class SignalsPlugin implements Plugin, SignalsAugmentedFunctionality {
     Object.assign(window, { SegmentSignalsPlugin: this })
 
     this.signals = new Signals({
-      debug: settings.debug,
-      disableSignalsRedaction: settings.disableSignalsRedaction,
-      enableSignalsIngestion: settings.enableSignalsIngestion,
-      flushAt: settings.flushAt,
-      flushInterval: settings.flushInterval,
-      functionHost: settings.functionHost,
-      apiHost: settings.apiHost,
-      maxBufferSize: settings.maxBufferSize,
+      ...settings,
       processSignal:
         typeof settings.processSignal === 'function'
           ? settings.processSignal.toString()
           : settings.processSignal,
-      networkSignalsAllowSameDomain: settings.networkSignalsAllowSameDomain,
-      networkSignalsAllowList: settings.networkSignalsAllowList,
-      networkSignalsDisallowList: settings.networkSignalsDisallowList,
-      signalStorage: settings.signalStorage,
-      signalStorageType: settings.signalStorageType,
-      middleware: settings.middleware,
     })
 
     logger.debug(`SignalsPlugin v${version} initializing`, {

packages/signals/signals/src/types/settings.ts

@@ -144,6 +144,14 @@ export interface SignalsPluginSettingsConfig {
    * (defaultAttributes) => defaultAttributes.filter(attr => attr.toLowerCase() !== 'aria-selected')
    */
   mutationGenObservedAttributes?: (defaultAttributes: string[]) => string[]
+
+  /**
+   * What sandbox strategy to use
+   * - global - [EXPERIMENTAL] evaluate everything in the global scope -- use this if you want to avoid CSP errors.
+   * - iframe - use a web worker and regular evaluation
+   * @default 'iframe'
+   */
+  sandboxStrategy?: 'iframe' | 'global'
 }
 
 export type RegexLike = RegExp | string