Updates analytics error handling to support checking delivery failures on Context

.vscode/launch.json

@@ -6,9 +6,15 @@
     {
       "type": "node",
       "request": "launch",
-      "name": "Jest Current File",
+      "name": "(packages/browser) Jest Current File",
       "program": "${workspaceFolder}/node_modules/.bin/jest",
-      "args": ["--testTimeout=100000", "--runTestsByPath", "${relativeFile}"],
+      "args": [
+        "--testTimeout=100000",
+        "-c",
+        "${workspaceFolder}/packages/browser/jest.config.js",
+        "--runTestsByPath",
+        "${relativeFile}"
+      ],
       "console": "integratedTerminal",
       "internalConsoleOptions": "neverOpen",
       "skipFiles": [
@@ -18,9 +24,13 @@
     },
     {
       "type": "node",
-      "name": "Jest All",
+      "name": "(packages/browser) Jest All",
       "request": "launch",
-      "args": ["--runInBand"],
+      "args": [
+        "--runInBand",
+        "-c",
+        "${workspaceFolder}/packages/browser/jest.config.js"
+      ],
       "cwd": "${workspaceFolder}",
       "console": "integratedTerminal",
       "internalConsoleOptions": "neverOpen",

packages/browser/src/core/analytics/__tests__/integration.test.ts

@@ -0,0 +1,199 @@
+import { PriorityQueue } from '../../../lib/priority-queue'
+import { MiddlewareParams } from '../../../plugins/middleware'
+import { Context } from '../../context'
+import { EventQueue } from '../../queue/event-queue'
+import { Analytics } from '../index'
+import {
+  AfterPlugin,
+  BeforePlugin,
+  DestinationPlugin,
+  EnrichmentPlugin,
+} from './test-plugins'
+
+describe('Analytics', () => {
+  describe('plugin error behavior', () => {
+    const retriesEnabledScenarios = [true, false]
+    retriesEnabledScenarios.forEach((retriesEnabled) => {
+      describe(`with retries ${
+        retriesEnabled ? 'enabled' : 'disabled'
+      }`, () => {
+        let analytics: Analytics
+        const attemptCount = retriesEnabled ? 2 : 1
+
+        beforeEach(() => {
+          const queue = new EventQueue(new PriorityQueue(attemptCount, []))
+          analytics = new Analytics({ writeKey: 'writeKey' }, {}, queue)
+        })
+
+        // Indicates plugins should throw
+        const shouldThrow = true
+
+        it(`"before" plugin errors should not throw (single dispatched event)`, async () => {
+          const plugin = new BeforePlugin({ shouldThrow })
+          const trackSpy = jest.spyOn(plugin, 'track')
+
+          await analytics.register(plugin)
+          const context = await analytics.track('test')
+          expect(trackSpy).toHaveBeenCalledTimes(attemptCount)
+          expect(context).toBeInstanceOf(Context)
+          expect(context.failedDelivery()).toBeTruthy()
+        })
+
+        it(`"before" plugin errors should not throw (multiple dispatched events)`, async () => {
+          const plugin = new BeforePlugin({ shouldThrow })
+          const trackSpy = jest.spyOn(plugin, 'track')
+
+          await analytics.register(plugin)
+          const contexts = await Promise.all([
+            analytics.track('test1'),
+            analytics.track('test2'),
+            analytics.track('test3'),
+          ])
+          expect(trackSpy).toHaveBeenCalledTimes(3 * attemptCount)
+
+          for (const context of contexts) {
+            expect(context).toBeInstanceOf(Context)
+            expect(context.failedDelivery()).toBeTruthy()
+          }
+        })
+
+        it(`"before" plugin errors should not impact callbacks`, async () => {
+          const plugin = new BeforePlugin({ shouldThrow })
+          const trackSpy = jest.spyOn(plugin, 'track')
+
+          await analytics.register(plugin)
+
+          const context = await new Promise<Context>((resolve) => {
+            void analytics.track('test', resolve)
+          })
+
+          expect(trackSpy).toHaveBeenCalledTimes(attemptCount)
+          expect(context).toBeInstanceOf(Context)
+          expect(context.failedDelivery()).toBeTruthy()
+        })
+
+        const testPlugins = [
+          new EnrichmentPlugin({ shouldThrow }),
+          new DestinationPlugin({ shouldThrow }),
+          new AfterPlugin({ shouldThrow }),
+        ]
+        testPlugins.forEach((plugin) => {
+          it(`"${plugin.type}" plugin errors should not throw (single dispatched event)`, async () => {
+            const trackSpy = jest.spyOn(plugin, 'track')
+
+            await analytics.register(plugin)
+
+            const context = await analytics.track('test')
+            expect(trackSpy).toHaveBeenCalledTimes(1)
+            expect(context).toBeInstanceOf(Context)
+            expect(context.failedDelivery()).toBeFalsy()
+          })
+
+          it(`"${plugin.type}" plugin errors should not throw (multiple dispatched events)`, async () => {
+            const trackSpy = jest.spyOn(plugin, 'track')
+
+            await analytics.register(plugin)
+
+            const contexts = await Promise.all([
+              analytics.track('test1'),
+              analytics.track('test2'),
+              analytics.track('test3'),
+            ])
+
+            expect(trackSpy).toHaveBeenCalledTimes(3)
+            for (const context of contexts) {
+              expect(context).toBeInstanceOf(Context)
+              expect(context.failedDelivery()).toBeFalsy()
+            }
+          })
+
+          it(`"${plugin.type}" plugin errors should not impact callbacks`, async () => {
+            const trackSpy = jest.spyOn(plugin, 'track')
+
+            await analytics.register(plugin)
+
+            const context = await new Promise<Context>((resolve) => {
+              void analytics.track('test', resolve)
+            })
+
+            expect(trackSpy).toHaveBeenCalledTimes(1)
+            expect(context).toBeInstanceOf(Context)
+            expect(context.failedDelivery()).toBeFalsy()
+          })
+        })
+
+        it('"before" plugin supports cancelation (single dispatched event)', async () => {
+          const plugin = new BeforePlugin({ shouldCancel: true })
+          const trackSpy = jest.spyOn(plugin, 'track')
+
+          await analytics.register(plugin)
+
+          const context = await analytics.track('test')
+          expect(trackSpy).toHaveBeenCalledTimes(1)
+          expect(context).toBeInstanceOf(Context)
+          expect(context.failedDelivery()).toBeTruthy()
+        })
+
+        it('"before" plugin supports cancelation (multiple dispatched events)', async () => {
+          const plugin = new BeforePlugin({ shouldCancel: true })
+          const trackSpy = jest.spyOn(plugin, 'track')
+
+          await analytics.register(plugin)
+          const contexts = await Promise.all([
+            analytics.track('test1'),
+            analytics.track('test2'),
+            analytics.track('test3'),
+          ])
+          expect(trackSpy).toHaveBeenCalledTimes(3)
+
+          for (const context of contexts) {
+            expect(context).toBeInstanceOf(Context)
+            expect(context.failedDelivery()).toBeTruthy()
+          }
+        })
+
+        it(`source middleware should not throw when "next" not called`, async () => {
+          const sourceMiddleware = jest.fn<void, MiddlewareParams[]>(() => {})
+
+          await analytics.addSourceMiddleware(sourceMiddleware)
+
+          const context = await analytics.track('test')
+
+          expect(sourceMiddleware).toHaveBeenCalledTimes(1)
+          expect(context).toBeInstanceOf(Context)
+          expect(context.failedDelivery()).toBeTruthy()
+        })
+
+        it(`source middleware errors should not throw`, async () => {
+          const sourceMiddleware = jest.fn<void, MiddlewareParams[]>(() => {
+            throw new Error('Source middleware error')
+          })
+
+          await analytics.addSourceMiddleware(sourceMiddleware)
+
+          const context = await analytics.track('test')
+
+          expect(sourceMiddleware).toHaveBeenCalledTimes(1 * attemptCount)
+          expect(context).toBeInstanceOf(Context)
+          expect(context.failedDelivery()).toBeTruthy()
+        })
+
+        it(`source middleware errors should not impact callbacks`, async () => {
+          const sourceMiddleware = jest.fn<void, MiddlewareParams[]>(() => {
+            throw new Error('Source middleware error')
+          })
+
+          await analytics.addSourceMiddleware(sourceMiddleware)
+
+          const context = await new Promise<Context>((resolve) => {
+            void analytics.track('test', resolve)
+          })
+
+          expect(sourceMiddleware).toHaveBeenCalledTimes(1 * attemptCount)
+          expect(context).toBeInstanceOf(Context)
+          expect(context.failedDelivery()).toBeTruthy()
+        })
+      })
+    })
+  })
+})

packages/browser/src/core/analytics/__tests__/test-plugins.ts

@@ -0,0 +1,89 @@
+import { Context, ContextCancelation, Plugin } from '../../../index'
+
+export interface BasePluginOptions {
+  shouldThrow?: boolean
+  shouldCancel?: boolean
+}
+
+class BasePlugin implements Partial<Plugin> {
+  public version = '1.0.0'
+  private shouldCancel: boolean
+  private shouldThrow: boolean
+
+  constructor({
+    shouldCancel = false,
+    shouldThrow = false,
+  }: BasePluginOptions) {
+    this.shouldCancel = shouldCancel
+    this.shouldThrow = shouldThrow
+  }
+
+  isLoaded() {
+    return true
+  }
+
+  load() {
+    return Promise.resolve()
+  }
+
+  alias(ctx: Context): Context {
+    return this.task(ctx)
+  }
+
+  group(ctx: Context): Context {
+    return this.task(ctx)
+  }
+
+  identify(ctx: Context): Context {
+    return this.task(ctx)
+  }
+
+  page(ctx: Context): Context {
+    return this.task(ctx)
+  }
+
+  screen(ctx: Context): Context {
+    return this.task(ctx)
+  }
+
+  track(ctx: Context): Context {
+    return this.task(ctx)
+  }
+
+  private task(ctx: Context): Context {
+    if (this.shouldCancel) {
+      ctx.cancel(
+        new ContextCancelation({
+          retry: false,
+        })
+      )
+    } else if (this.shouldThrow) {
+      throw new Error(`Error thrown in task`)
+    }
+    return ctx
+  }
+}
+
+export class BeforePlugin extends BasePlugin implements Plugin {
+  public name = 'Test Before Error'
+  public type = 'before' as const
+}
+
+export class EnrichmentPlugin extends BasePlugin implements Plugin {
+  public name = 'Test Enrichment Error'
+  public type = 'enrichment' as const
+}
+
+export class DestinationPlugin extends BasePlugin implements Plugin {
+  public name = 'Test Destination Error'
+  public type = 'destination' as const
+
+  public ready() {
+    return Promise.resolve(true)
+  }
+}
+
+export class AfterPlugin extends BasePlugin implements Plugin {
+  public name = 'Test After Error'
+  public type = 'after' as const
+}

packages/browser/src/core/context/index.ts

@@ -24,6 +24,10 @@ interface CancelationOptions {
   type?: string
 }
 
+export interface ContextFailedDelivery {
+  reason: unknown
+}
+
 export class ContextCancelation {
   retry: boolean
   type: string
@@ -44,6 +48,7 @@ export class Context implements AbstractContext {
   public logger = new Logger()
   public stats: Stats
   private _id: string
+  private _failedDelivery?: ContextFailedDelivery
 
   constructor(event: SegmentEvent, id?: string) {
     this._attempts = 0
@@ -110,6 +115,14 @@ export class Context implements AbstractContext {
     return this._event
   }
 
+  public failedDelivery(): ContextFailedDelivery | undefined {
+    return this._failedDelivery
+  }
+
+  public setFailedDelivery(options: ContextFailedDelivery) {
+    this._failedDelivery = options
+  }
+
   public logs(): LogMessage[] {
     return this.logger.logs
   }