Add signals middleware (#1220)

Author: silesky

.changeset/warm-lies-rush.md

@@ -0,0 +1,25 @@
+---
+'@segment/analytics-signals': minor
+---
+
+Allow registration of middleware to allow for dropping and modification of signals
+
+```ts
+class MyMiddleware implements SignalsMiddleware {
+  process(signal: Signal) {
+    if (
+      signal.type === 'network' &&
+      signal.data.action === 'request' &&
+      ...
+    ) {
+      // drop or modify signal
+      return null
+    } else {
+      return signal
+    }
+  }
+}
+const signalsPlugin = new SignalsPlugin({
+  middleware: [new MyMiddleware()]
+})
+```

packages/signals/signals-integration-tests/package.json

@@ -9,7 +9,7 @@
     ".": "yarn run -T turbo run --filter=@internal/signals-integration-tests...",
     "build": "webpack",
     "test": "playwright test",
-    "test:vanilla": "playwright test src/tests/vanilla",
+    "test:vanilla": "playwright test src/tests/signals-vanilla",
     "test:perf": "playwright test src/tests/performance",
     "test:custom": "playwright test src/tests/custom",
     "watch": "webpack -w",

packages/signals/signals-integration-tests/src/helpers/base-page-object.ts

@@ -16,6 +16,12 @@ export class BasePage {
   public edgeFnDownloadURL = 'https://cdn.edgefn.segment.com/MY-WRITEKEY/foo.js'
   public edgeFn!: string
   public network!: PageNetworkUtils
+  public defaultSignalsPluginTestSettings: Partial<SignalsPluginSettingsConfig> =
+    {
+      disableSignalsRedaction: true,
+      enableSignalsIngestion: true,
+      flushInterval: 500,
+    }
 
   constructor(path: string) {
     this.url = 'http://localhost:5432/src/tests' + path
@@ -41,7 +47,12 @@ export class BasePage {
     page: Page,
     edgeFn: string,
     signalSettings: Partial<SignalsPluginSettingsConfig> = {},
-    options: { updateURL?: (url: string) => string; sampleRate?: number } = {}
+    options: {
+      updateURL?: (url: string) => string
+      sampleRate?: number
+      middleware?: string
+      skipSignalsPluginInit?: boolean
+    } = {}
   ) {
     logConsole(page)
     this.page = page
@@ -50,10 +61,12 @@ export class BasePage {
     await this.setupMockedRoutes(options.sampleRate)
     const url = options.updateURL ? options.updateURL(this.url) : this.url
     await this.page.goto(url, { waitUntil: 'domcontentloaded' })
-    void this.invokeAnalyticsLoad({
-      flushInterval: 500,
-      ...signalSettings,
-    })
+    if (!options.skipSignalsPluginInit) {
+      void this.invokeAnalyticsLoad({
+        flushInterval: 500,
+        ...signalSettings,
+      })
+    }
     return this
   }
 
@@ -76,18 +89,19 @@ export class BasePage {
     signalSettings: Partial<SignalsPluginSettingsConfig> = {}
   ) {
     await this.page.evaluate(
-      ({ signalSettings }) => {
-        window.signalsPlugin = new window.SignalsPlugin({
-          disableSignalsRedaction: true,
-          enableSignalsIngestion: true,
-          ...signalSettings,
-        })
+      ({ settings }) => {
+        window.signalsPlugin = new window.SignalsPlugin(settings)
         window.analytics.load({
           writeKey: '<SOME_WRITE_KEY>',
           plugins: [window.signalsPlugin],
         })
       },
-      { signalSettings }
+      {
+        settings: {
+          ...this.defaultSignalsPluginTestSettings,
+          ...signalSettings,
+        },
+      }
     )
     return this
   }

packages/signals/signals-integration-tests/src/helpers/log-console.ts

@@ -2,7 +2,13 @@ import { Page } from '@playwright/test'
 
 export const logConsole = (page: Page) => {
   page.on('console', (msg) => {
-    console.log(`console.${msg.type()}:`, msg.text())
+    const text = msg.text()
+    // keep stdout clean, e.g. by not printing intentional errors
+    const ignoreList = ['Bad Request']
+    if (ignoreList.some((str) => text.includes(str))) {
+      return
+    }
+    console.log(`console.${msg.type()}:`, text)
   })
   page.on('pageerror', (error) => {
     console.error('Page error:', error)

packages/signals/signals-integration-tests/src/tests/custom-elements/index.html

@@ -3,7 +3,7 @@
 
 <head>
   <!-- Dummy favicon -->
-  <link rel="icon" href="data:;base64,iVBORw0KGgo=">
+ <link rel="shortcut icon" href="#">>
 </head>
 
 <body>

packages/signals/signals-integration-tests/src/tests/performance/index.html

@@ -4,7 +4,7 @@
 <head>
   <script src="../../../dist/signals-vanilla.bundle.js"></script>
   <!-- Dummy favicon -->
-  <link rel="icon" href="data:;base64,iVBORw0KGgo=">
+  <link rel="shortcut icon" href="#">
 </head>
 
 <body>

packages/signals/signals-integration-tests/src/tests/signals-vanilla/index.bundle.ts

@@ -2,7 +2,7 @@ import { AnalyticsBrowser } from '@segment/analytics-next'
 import { SignalsPlugin } from '@segment/analytics-signals'
 
 /**
- * Not instantiating the analytics object here, as it will be instantiated in the test
+ * Not calling analytics.load() or instantiating Signals Plugin here, as all this configuration happens in the page object.
  */
 window.SignalsPlugin = SignalsPlugin
 window.analytics = new AnalyticsBrowser()

packages/signals/signals-integration-tests/src/tests/signals-vanilla/index.html

@@ -4,13 +4,13 @@
 <head>
   <script src="../../../dist/signals-vanilla.bundle.js"></script>
   <!-- Dummy favicon -->
-  <link rel="icon" href="data:;base64,iVBORw0KGgo=">
+  <link rel="shortcut icon" href="#">
 </head>
 
 <body>
   <button id="some-button">Click me</button>
   <button id="complex-button">
-    <img id="some-image" src="https://via.placeholder.com/150" alt="Placeholder Image">
+    <img id="some-image" src="data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mP8/wIAAgEBAyX8UgAAAABJRU5ErkJggg==" alt="Placeholder Image">
     <div>
       Other Example Button with <h1>Nested Text</h1>
     </div>
@@ -26,4 +26,4 @@
     <input type="submit" value="Submit">
   </form>
 </body>
-</html>
+</html>

packages/signals/signals-integration-tests/src/tests/signals-vanilla/middleware.test.ts

@@ -0,0 +1,61 @@
+import { test, expect } from '@playwright/test'
+import { IndexPage } from './index-page'
+
+const basicEdgeFn = `const processSignal = (signal) => {}`
+
+let indexPage: IndexPage
+
+test('middleware', async ({ page }) => {
+  indexPage = await new IndexPage().load(
+    page,
+    basicEdgeFn,
+    {},
+    {
+      skipSignalsPluginInit: true,
+    }
+  )
+
+  await page.evaluate(
+    ({ settings }) => {
+      window.signalsPlugin = new window.SignalsPlugin({
+        middleware: [
+          {
+            load() {
+              return undefined
+            },
+            process: function (signal) {
+              // @ts-ignore
+              signal.data['middleware'] = 'test'
+              return signal
+            },
+          },
+        ],
+        ...settings,
+      })
+      window.analytics.load({
+        writeKey: '<SOME_WRITE_KEY>',
+        plugins: [window.signalsPlugin],
+      })
+    },
+    {
+      settings: {
+        ...indexPage.defaultSignalsPluginTestSettings,
+        flushAt: 1,
+      },
+    }
+  )
+
+  /**
+   * Make an analytics.page() call, see that the middleware can modify the event
+   */
+  await Promise.all([
+    indexPage.makeAnalyticsPageCall(),
+    indexPage.waitForSignalsApiFlush(),
+  ])
+
+  const instrumentationEvents =
+    indexPage.signalsAPI.getEvents('instrumentation')
+  expect(instrumentationEvents).toHaveLength(1)
+  const ev = instrumentationEvents[0]
+  expect(ev.properties!.data['middleware']).toEqual('test')
+})

packages/signals/signals/README.md

@@ -95,6 +95,30 @@ signalsPlugin.onSignal((signal) => console.log(signal))
 ```
 
 
+### Middleware / Plugins
+#### Drop or modify signals
+```ts
+import { SignalsPlugin, SignalsMiddleware } from '@segment/analytics-signals'
+
+class MyMiddleware implements SignalsMiddleware {
+  process(signal: Signal) {
+    // drop the event if some conditions are met
+    if (
+       signal.type === 'network' &&
+       signal.data.action === 'request' &&
+       ...
+    ) {
+      return null;
+    } else {
+      return signal;
+    }
+  }
+}
+const signalsPlugin = new SignalsPlugin({ middleware: [myMiddleware]})
+analytics.register(signalsPlugin)
+```
+
+
 ### Playground / Development / Testing
 See the [signals example repo](../signals-example).