add priority and headers

Author: silesky

.changeset/heavy-taxis-suffer.md

@@ -0,0 +1,23 @@
+---
+'@segment/analytics-next': minor
+---
+Add new `headers` setting, along with `fetchPriority`.
+
+```ts
+analytics.load("<YOUR_WRITE_KEY>",
+  {
+    integrations: {
+      'Segment.io': {
+        deliveryStrategy: {
+          strategy: "standard" // also works for 'batching'
+          config: {
+            headers: { 'x-api-key': 'foo' } or () => {...}
+            priority: 'low',
+          },
+        },
+      },
+    },
+  }
+)
+
+```

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

@@ -1536,3 +1536,37 @@ describe('Options', () => {
     })
   })
 })
+
+describe('setting headers', () => {
+  it('allows setting headers', async () => {
+    const [ajs] = await AnalyticsBrowser.load(
+      {
+        writeKey,
+      },
+      {
+        integrations: {
+          'Segment.io': {
+            deliveryStrategy: {
+              config: {
+                headers: {
+                  'X-Test': 'foo',
+                },
+              },
+            },
+          },
+        },
+      }
+    )
+
+    await ajs.track('sup')
+
+    await sleep(10)
+    const [call] = fetchCalls.filter((el) =>
+      el.url.toString().includes('api.segment.io')
+    )
+    expect(call.headers).toEqual({
+      'Content-Type': 'text/plain',
+      'X-Test': 'foo',
+    })
+  })
+})

packages/browser/src/plugins/segmentio/__tests__/batched-dispatcher.test.ts

@@ -102,6 +102,7 @@ describe('Batching', () => {
           },
           "keepalive": false,
           "method": "post",
+          "priority": undefined,
         },
       ]
     `)
@@ -185,6 +186,7 @@ describe('Batching', () => {
           },
           "keepalive": false,
           "method": "post",
+          "priority": undefined,
         },
       ]
     `)
@@ -220,6 +222,7 @@ describe('Batching', () => {
           },
           "keepalive": false,
           "method": "post",
+          "priority": undefined,
         },
       ]
     `)
@@ -234,6 +237,7 @@ describe('Batching', () => {
           },
           "keepalive": false,
           "method": "post",
+          "priority": undefined,
         },
       ]
     `)
@@ -265,6 +269,7 @@ describe('Batching', () => {
           },
           "keepalive": false,
           "method": "post",
+          "priority": undefined,
         },
       ]
     `)

packages/browser/src/plugins/segmentio/__tests__/index.test.ts

@@ -65,7 +65,95 @@ describe('Segment.io', () => {
     })
   })
 
-  describe('configuring a keep alive', () => {
+  describe('configuring headers', () => {
+    it('should accept additional headers', async () => {
+      const analytics = new Analytics({ writeKey: 'foo' })
+
+      await analytics.register(
+        await segmentio(analytics, {
+          apiKey: '',
+          deliveryStrategy: {
+            config: {
+              headers: {
+                'X-My-Header': 'foo',
+              },
+            },
+          },
+        })
+      )
+
+      await analytics.track('foo')
+      const [_, params] = spyMock.mock.lastCall
+      expect(params.headers['X-My-Header']).toBe('foo')
+      expect(params.headers['Content-Type']).toBe('text/plain')
+    })
+
+    it('should allow additional headers to be a function', async () => {
+      const analytics = new Analytics({ writeKey: 'foo' })
+
+      await analytics.register(
+        await segmentio(analytics, {
+          apiKey: '',
+          deliveryStrategy: {
+            config: {
+              headers: () => ({
+                'X-My-Header': 'foo',
+              }),
+            },
+          },
+        })
+      )
+
+      await analytics.track('foo')
+      const [_, params] = spyMock.mock.lastCall
+      expect(params.headers['X-My-Header']).toBe('foo')
+      expect(params.headers['Content-Type']).toBe('text/plain')
+    })
+
+    it('should allow content type to be overridden', async () => {
+      const analytics = new Analytics({ writeKey: 'foo' })
+
+      await analytics.register(
+        await segmentio(analytics, {
+          apiKey: '',
+          deliveryStrategy: {
+            config: {
+              headers: () => ({
+                'Content-Type': 'bar',
+              }),
+            },
+          },
+        })
+      )
+
+      await analytics.track('foo')
+      const [_, params] = spyMock.mock.lastCall
+      expect(params.headers['Content-Type']).toBe('bar')
+    })
+  })
+
+  describe('configuring fetch priority', () => {
+    it('should accept fetch priority configuration', async () => {
+      const analytics = new Analytics({ writeKey: 'foo' })
+
+      await analytics.register(
+        await segmentio(analytics, {
+          apiKey: '',
+          deliveryStrategy: {
+            config: {
+              priority: 'high',
+            },
+          },
+        })
+      )
+
+      await analytics.track('foo')
+      const [_, params] = spyMock.mock.lastCall
+      expect(params.priority).toBe('high')
+    })
+  })
+
+  describe('configuring keepalive', () => {
     it('should accept keepalive configuration', async () => {
       const analytics = new Analytics({ writeKey: 'foo' })
 

packages/browser/src/plugins/segmentio/batched-dispatcher.ts

@@ -4,13 +4,7 @@ import { onPageChange } from '../../lib/on-page-change'
 import { SegmentFacade } from '../../lib/to-facade'
 import { RateLimitError } from './ratelimit-error'
 import { Context } from '../../core/context'
-
-export type BatchingDispatchConfig = {
-  size?: number
-  timeout?: number
-  maxRetries?: number
-  keepalive?: boolean
-}
+import { BatchingDispatchConfig, createHeaders } from './shared-dispatcher'
 
 const MAX_PAYLOAD_SIZE = 500
 const MAX_KEEPALIVE_SIZE = 64
@@ -84,15 +78,15 @@ export default function batch(
 
     return fetch(`https://${apiHost}/b`, {
       keepalive: config?.keepalive || pageUnloaded,
-      headers: {
-        'Content-Type': 'text/plain',
-      },
+      headers: createHeaders(config?.headers),
       method: 'post',
       body: JSON.stringify({
         writeKey,
         batch: updatedBatch,
         sentAt: new Date().toISOString(),
       }),
+      // @ts-ignore - not in the ts lib yet
+      priority: config?.priority,
     }).then((res) => {
       if (res.status >= 500) {
         throw new Error(`Bad response from server: ${res.status}`)

packages/browser/src/plugins/segmentio/fetch-dispatcher.ts

@@ -1,21 +1,19 @@
 import { fetch } from '../../lib/fetch'
 import { RateLimitError } from './ratelimit-error'
-
+import { createHeaders, StandardDispatcherConfig } from './shared-dispatcher'
 export type Dispatcher = (url: string, body: object) => Promise<unknown>
 
-export type StandardDispatcherConfig = {
-  keepalive?: boolean
-}
-
 export default function (config?: StandardDispatcherConfig): {
   dispatch: Dispatcher
 } {
   function dispatch(url: string, body: object): Promise<unknown> {
     return fetch(url, {
       keepalive: config?.keepalive,
-      headers: { 'Content-Type': 'text/plain' },
+      headers: createHeaders(config?.headers),
       method: 'post',
       body: JSON.stringify(body),
+      // @ts-ignore - not in the ts lib yet
+      priority: config?.priority,
     }).then((res) => {
       if (res.status >= 500) {
         throw new Error(`Bad response from server: ${res.status}`)

packages/browser/src/plugins/segmentio/index.ts

@@ -7,21 +7,12 @@ import { Plugin } from '../../core/plugin'
 import { PriorityQueue } from '../../lib/priority-queue'
 import { PersistedPriorityQueue } from '../../lib/priority-queue/persisted'
 import { toFacade } from '../../lib/to-facade'
-import batch, { BatchingDispatchConfig } from './batched-dispatcher'
-import standard, { StandardDispatcherConfig } from './fetch-dispatcher'
+import batch from './batched-dispatcher'
+import standard from './fetch-dispatcher'
 import { normalize } from './normalize'
 import { scheduleFlush } from './schedule-flush'
 import { SEGMENT_API_HOST } from '../../core/constants'
-
-type DeliveryStrategy =
-  | {
-      strategy?: 'standard'
-      config?: StandardDispatcherConfig
-    }
-  | {
-      strategy?: 'batching'
-      config?: BatchingDispatchConfig
-    }
+import { DeliveryStrategy } from './shared-dispatcher'
 
 export type SegmentioSettings = {
   apiKey: string
@@ -95,7 +86,7 @@ export function segmentio(
   const client =
     deliveryStrategy?.strategy === 'batching'
       ? batch(apiHost, deliveryStrategy.config)
-      : standard(deliveryStrategy?.config as StandardDispatcherConfig)
+      : standard(deliveryStrategy?.config)
 
   async function send(ctx: Context): Promise<Context> {
     if (isOffline()) {

packages/browser/src/plugins/segmentio/shared-dispatcher.ts

@@ -0,0 +1,82 @@
+export const createHeaders = (
+  headerSettings: AdditionalHeaders | undefined
+): Record<string, string> => {
+  return {
+    'Content-Type': 'text/plain',
+    ...(typeof headerSettings === 'function'
+      ? headerSettings()
+      : headerSettings),
+  }
+}
+
+/**
+ * Additional headers to be sent with the request.
+ * Default is `Content-Type: text/plain`. This can be overridden.
+ * If a function is provided, it will be called before each request.
+ */
+export type AdditionalHeaders =
+  | Record<string, string>
+  | (() => Record<string, string>)
+
+export type RequestPriority = 'high' | 'low' | 'auto'
+
+/**
+ * These are the options that can be passed to the fetch dispatcher.
+ * They more/less map to the Fetch RequestInit type.
+ */
+interface DispatchFetchConfig {
+  /**
+   * This is useful for ensuring that an event is sent even if the user navigates away from the page.
+   * However, it may increase the likelihood of events being lost, as there is a 64kb limit for *all* fetch requests (not just ones to segment) with keepalive (which is why it's disabled by default). So, if you're sending a lot of data, this will likely cause events to be dropped.
+
+   * @default false
+   */
+  keepalive?: boolean
+  /**
+   * Additional headers to be sent with the request.
+   * Default is `Content-Type: text/plain`. This can be overridden.
+   * If a function is provided, it will be called before each request.
+   * @example { 'Content-Type': 'application/json' } or () => { 'Content-Type': 'application/json' }
+   */
+  headers?: AdditionalHeaders
+  /**
+   * 'Request Priority' of the request
+   * @see https://developer.mozilla.org/en-US/docs/Web/API/RequestInit#priority
+   */
+  priority?: RequestPriority
+}
+
+export interface BatchingDispatchConfig extends DispatchFetchConfig {
+  /**
+   * The maximum number of events to send in a single request. If the batch reaches this size, a request will automatically be sent.
+   *
+   * @default 10
+   */
+  size?: number
+  /**
+   * The maximum time, in milliseconds, to wait before sending a request.
+   * This won't alaways be relevant, as the request will be sent when the size is reached.
+   * However, if the size is never reached, the request will be sent after this time.
+   * When it comes to retries, if there is a rate limit timeout header, that will be respected over the value here.
+   *
+   * @default 5000
+   */
+  timeout?: number
+  /**
+   * The maximum number of retries to attempt before giving up.
+   * @default 10
+   */
+  maxRetries?: number
+}
+
+export interface StandardDispatcherConfig extends DispatchFetchConfig {}
+
+export type DeliveryStrategy =
+  | {
+      strategy?: 'standard'
+      config?: StandardDispatcherConfig
+    }
+  | {
+      strategy?: 'batching'
+      config?: BatchingDispatchConfig
+    }