From 24240e96da514dd8cfac5582dd9b4590f38c3aea Mon Sep 17 00:00:00 2001 From: Abhijeet Prasad Date: Tue, 15 Feb 2022 18:38:48 -0500 Subject: [PATCH 1/6] feat(utils): Introduce envelope helper functions This patch introduces functions that create, mutate and serialize envelopes. It also adds some basic unit tests that sanity check their functionality. It builds on top of the work done in https://github.com/getsentry/sentry-javascript/pull/4527. Users are expected to not directly interact with the Envelope instance, but instead use the helper functions to work with them. Essentially, we can treat the envelope instance as an opaque handle, similar to how void pointers are used in low-level languages. This was done to minimize the bundle impact of working with the envelopes, and as the set of possible envelope operations was fixed (and on the smaller end). To directly create an envelope, the `createEnvelope()` function was introduced. Users are encouraged to explicitly provide the generic type arg to this function so that add headers/items are typed accordingly. To add headers and items to envelopes, the `addHeaderToEnvelope()` and `addItemToEnvelope()` functions are exposed respectively. The reason that these functions are purely additive (or in the case of headers, can re-write existing ones), instead of allow for headers/items to be removed, is that removal functionality doesn't seem like it'll be used at all. In the interest of keeping the API surface small, we settled with these two functions, but we can come back and adjust this later on. Finally, there is `serializeEnvelope()`, which is used to serialize an envelope to a string. It does have some TypeScript complications, which is explained in detail in a code comment, but otherwise is a pretty simple implementation. You can notice the power of the tuple based envelope implementation, where it becomes easy to access headers/items. ```js const [headers, items] = envelope; ``` To illustrate how these functions will be used, another patch will be added that adds a `createClientReportEnvelope()` util, and the base transport in `@sentry/browser` will be updated to use that util. --- packages/utils/src/envelope.ts | 48 ++++++++++++++++++++++++++++ packages/utils/src/index.ts | 1 + packages/utils/test/envelope.test.ts | 42 ++++++++++++++++++++++++ 3 files changed, 91 insertions(+) create mode 100644 packages/utils/src/envelope.ts create mode 100644 packages/utils/test/envelope.test.ts diff --git a/packages/utils/src/envelope.ts b/packages/utils/src/envelope.ts new file mode 100644 index 000000000000..8ba572fa5779 --- /dev/null +++ b/packages/utils/src/envelope.ts @@ -0,0 +1,48 @@ +import { Envelope } from '@sentry/types'; + +/** + * Creates an envelope. + * Make sure to always explicitly provide the generic to this function + * so that the envelope types resolve correctly. + */ +export function createEnvelope(headers: E[0], items: E[1]): E { + return [headers, items] as E; +} + +/** + * Add a set of key value pairs to the envelope header. + * Make sure to always explicitly provide the generic to this function + * so that the envelope types resolve correctly. + */ +export function addHeaderToEnvelope(envelope: E, newHeaders: E[0]): E { + const [headers, items] = envelope; + return [{ ...headers, ...newHeaders }, items] as E; +} + +/** + * Add an item to an envelope. + * Make sure to always explicitly provide the generic to this function + * so that the envelope types resolve correctly. + */ +export function addItemToEnvelope(envelope: E, newItem: E[1][number]): E { + const [headers, items] = envelope; + return [headers, [...items, newItem]] as E; +} + +/** + * Serializes an envelope into a string. + */ +export function serializeEnvelope(envelope: Envelope): string { + const [headers, items] = envelope; + const serializedHeaders = JSON.stringify(headers); + + // Have to cast items to any here since Envelope is a union type + // Fixed in Typescript 4.2 + // TODO: Remove any[] cast when we upgrade to TS 4.2 + // https://github.com/microsoft/TypeScript/issues/36390 + // eslint-disable-next-line @typescript-eslint/no-explicit-any + return (items as any[]).reduce((acc, item: typeof items[number]) => { + const [itemHeaders, payload] = item; + return `${acc}\n${JSON.stringify(itemHeaders)}\n${JSON.stringify(payload)}`; + }, serializedHeaders); +} diff --git a/packages/utils/src/index.ts b/packages/utils/src/index.ts index 900e50653037..511d8a1315ca 100644 --- a/packages/utils/src/index.ts +++ b/packages/utils/src/index.ts @@ -21,3 +21,4 @@ export * from './supports'; export * from './syncpromise'; export * from './time'; export * from './env'; +export * from './envelope'; diff --git a/packages/utils/test/envelope.test.ts b/packages/utils/test/envelope.test.ts new file mode 100644 index 000000000000..451ca00ff1c8 --- /dev/null +++ b/packages/utils/test/envelope.test.ts @@ -0,0 +1,42 @@ +import { createEnvelope, addHeaderToEnvelope, addItemToEnvelope, serializeEnvelope } from '../src/envelope'; +import { EventEnvelope } from '@sentry/types'; + +describe('envelope', () => { + describe('createEnvelope()', () => { + const testTable: Array<[string, Parameters[0], Parameters[1]]> = [ + ['creates an empty envelope', {}, []], + ['creates an envelope with a header but no items', { dsn: 'https://public@example.com/1', sdk: {} }, []], + ]; + it.each(testTable)('%s', (_: string, headers, items) => { + const env = createEnvelope(headers, items); + expect(env).toHaveLength(2); + expect(env[0]).toStrictEqual(headers); + expect(env[1]).toStrictEqual(items); + }); + }); + + describe('addHeaderToEnvelope()', () => { + it('adds a header to the envelope', () => { + const env = createEnvelope({}, []); + expect(serializeEnvelope(env)).toMatchInlineSnapshot(`"{}"`); + const newEnv = addHeaderToEnvelope(env, { dsn: 'https://public@example.com/' }); + expect(serializeEnvelope(newEnv)).toMatchInlineSnapshot(`"{\\"dsn\\":\\"https://public@example.com/\\"}"`); + }); + }); + + describe('addItemToEnvelope()', () => { + const env = createEnvelope({ event_id: 'aa3ff046696b4bc6b609ce6d28fde9e2', sent_at: '123' }, []); + expect(serializeEnvelope(env)).toMatchInlineSnapshot( + `"{\\"event_id\\":\\"aa3ff046696b4bc6b609ce6d28fde9e2\\",\\"sent_at\\":\\"123\\"}"`, + ); + const newEnv = addItemToEnvelope(env, [ + { type: 'event' }, + { event_id: 'aa3ff046696b4bc6b609ce6d28fde9e2' }, + ]); + expect(serializeEnvelope(newEnv)).toMatchInlineSnapshot(` + "{\\"event_id\\":\\"aa3ff046696b4bc6b609ce6d28fde9e2\\",\\"sent_at\\":\\"123\\"} + {\\"type\\":\\"event\\"} + {\\"event_id\\":\\"aa3ff046696b4bc6b609ce6d28fde9e2\\"}" + `); + }); +}); From b3423284c9608dbcd84e724773e06e25be5490cd Mon Sep 17 00:00:00 2001 From: Abhijeet Prasad Date: Tue, 15 Feb 2022 19:36:39 -0500 Subject: [PATCH 2/6] yarn fix lint --- packages/utils/src/envelope.ts | 10 ---------- packages/utils/test/envelope.test.ts | 3 ++- 2 files changed, 2 insertions(+), 11 deletions(-) diff --git a/packages/utils/src/envelope.ts b/packages/utils/src/envelope.ts index 8ba572fa5779..0b06d3b266fe 100644 --- a/packages/utils/src/envelope.ts +++ b/packages/utils/src/envelope.ts @@ -9,16 +9,6 @@ export function createEnvelope(headers: E[0], items: E[1]): return [headers, items] as E; } -/** - * Add a set of key value pairs to the envelope header. - * Make sure to always explicitly provide the generic to this function - * so that the envelope types resolve correctly. - */ -export function addHeaderToEnvelope(envelope: E, newHeaders: E[0]): E { - const [headers, items] = envelope; - return [{ ...headers, ...newHeaders }, items] as E; -} - /** * Add an item to an envelope. * Make sure to always explicitly provide the generic to this function diff --git a/packages/utils/test/envelope.test.ts b/packages/utils/test/envelope.test.ts index 451ca00ff1c8..e6f66e492c0d 100644 --- a/packages/utils/test/envelope.test.ts +++ b/packages/utils/test/envelope.test.ts @@ -1,6 +1,7 @@ -import { createEnvelope, addHeaderToEnvelope, addItemToEnvelope, serializeEnvelope } from '../src/envelope'; import { EventEnvelope } from '@sentry/types'; +import { addHeaderToEnvelope, addItemToEnvelope, createEnvelope, serializeEnvelope } from '../src/envelope'; + describe('envelope', () => { describe('createEnvelope()', () => { const testTable: Array<[string, Parameters[0], Parameters[1]]> = [ From d7d551ee2d181a2e27c1bec408ef71140f3507da Mon Sep 17 00:00:00 2001 From: Abhijeet Prasad Date: Wed, 23 Feb 2022 09:27:22 -0500 Subject: [PATCH 3/6] update tests --- packages/utils/test/envelope.test.ts | 44 +++++++++++++++------------- packages/utils/test/testutils.ts | 4 +++ 2 files changed, 28 insertions(+), 20 deletions(-) diff --git a/packages/utils/test/envelope.test.ts b/packages/utils/test/envelope.test.ts index e6f66e492c0d..64cdbe5e39ca 100644 --- a/packages/utils/test/envelope.test.ts +++ b/packages/utils/test/envelope.test.ts @@ -1,6 +1,7 @@ import { EventEnvelope } from '@sentry/types'; -import { addHeaderToEnvelope, addItemToEnvelope, createEnvelope, serializeEnvelope } from '../src/envelope'; +import { addItemToEnvelope, createEnvelope, serializeEnvelope } from '../src/envelope'; +import { parseEnvelope } from './testutils'; describe('envelope', () => { describe('createEnvelope()', () => { @@ -16,28 +17,31 @@ describe('envelope', () => { }); }); - describe('addHeaderToEnvelope()', () => { - it('adds a header to the envelope', () => { - const env = createEnvelope({}, []); - expect(serializeEnvelope(env)).toMatchInlineSnapshot(`"{}"`); - const newEnv = addHeaderToEnvelope(env, { dsn: 'https://public@example.com/' }); - expect(serializeEnvelope(newEnv)).toMatchInlineSnapshot(`"{\\"dsn\\":\\"https://public@example.com/\\"}"`); + describe('serializeEnvelope()', () => { + it('serializes an envelope', () => { + const env = createEnvelope({ event_id: 'aa3ff046696b4bc6b609ce6d28fde9e2', sent_at: '123' }, []); + expect(serializeEnvelope(env)).toMatchInlineSnapshot( + `"{\\"event_id\\":\\"aa3ff046696b4bc6b609ce6d28fde9e2\\",\\"sent_at\\":\\"123\\"}"`, + ); }); }); describe('addItemToEnvelope()', () => { - const env = createEnvelope({ event_id: 'aa3ff046696b4bc6b609ce6d28fde9e2', sent_at: '123' }, []); - expect(serializeEnvelope(env)).toMatchInlineSnapshot( - `"{\\"event_id\\":\\"aa3ff046696b4bc6b609ce6d28fde9e2\\",\\"sent_at\\":\\"123\\"}"`, - ); - const newEnv = addItemToEnvelope(env, [ - { type: 'event' }, - { event_id: 'aa3ff046696b4bc6b609ce6d28fde9e2' }, - ]); - expect(serializeEnvelope(newEnv)).toMatchInlineSnapshot(` - "{\\"event_id\\":\\"aa3ff046696b4bc6b609ce6d28fde9e2\\",\\"sent_at\\":\\"123\\"} - {\\"type\\":\\"event\\"} - {\\"event_id\\":\\"aa3ff046696b4bc6b609ce6d28fde9e2\\"}" - `); + it('adds an item to an envelope', () => { + const env = createEnvelope({ event_id: 'aa3ff046696b4bc6b609ce6d28fde9e2', sent_at: '123' }, []); + const parsedEnvelope = parseEnvelope(serializeEnvelope(env)); + expect(parsedEnvelope).toHaveLength(1); + expect(parsedEnvelope[0]).toEqual({ event_id: 'aa3ff046696b4bc6b609ce6d28fde9e2', sent_at: '123' }); + + const newEnv = addItemToEnvelope(env, [ + { type: 'event' }, + { event_id: 'aa3ff046696b4bc6b609ce6d28fde9e2' }, + ]); + const parsedNewEnvelope = parseEnvelope(serializeEnvelope(newEnv)); + expect(parsedNewEnvelope).toHaveLength(3); + expect(parsedNewEnvelope[0]).toEqual({ event_id: 'aa3ff046696b4bc6b609ce6d28fde9e2', sent_at: '123' }); + expect(parsedNewEnvelope[1]).toEqual({ type: 'event' }); + expect(parsedNewEnvelope[2]).toEqual({ event_id: 'aa3ff046696b4bc6b609ce6d28fde9e2' }); + }); }); }); diff --git a/packages/utils/test/testutils.ts b/packages/utils/test/testutils.ts index 6130ee7ca365..aa3c5485eec1 100644 --- a/packages/utils/test/testutils.ts +++ b/packages/utils/test/testutils.ts @@ -11,3 +11,7 @@ export const testOnlyIfNodeVersionAtLeast = (minVersion: number): jest.It => { return it; }; + +export function parseEnvelope(env: string): Array> { + return env.split('\n').map(e => JSON.parse(e)); +} From 7fe5ed1964747310e66f65c4858bdb3352e725f5 Mon Sep 17 00:00:00 2001 From: Abhijeet Prasad Date: Thu, 24 Feb 2022 14:27:15 -0500 Subject: [PATCH 4/6] dont export base types --- packages/types/src/envelope.ts | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/packages/types/src/envelope.ts b/packages/types/src/envelope.ts index 2a70cea96667..aa7655db9cea 100644 --- a/packages/types/src/envelope.ts +++ b/packages/types/src/envelope.ts @@ -18,12 +18,12 @@ export type BaseEnvelopeItemHeaders = { length?: number; }; -export type BaseEnvelopeItem = [IH, P]; // P is for payload +type BaseEnvelopeItem = [IH, P]; // P is for payload -export type BaseEnvelope< - EH extends BaseEnvelopeHeaders, - I extends BaseEnvelopeItem, -> = [EH, I[]]; +type BaseEnvelope> = [ + EH, + I[], +]; type EventItemHeaders = { type: 'event' | 'transaction' }; type AttachmentItemHeaders = { type: 'attachment'; filename: string }; From a4b5541998d7beca8a91216ffa5a2375127d1c62 Mon Sep 17 00:00:00 2001 From: Abhijeet Prasad Date: Thu, 24 Feb 2022 14:34:35 -0500 Subject: [PATCH 5/6] fix import --- packages/types/src/index.ts | 2 -- 1 file changed, 2 deletions(-) diff --git a/packages/types/src/index.ts b/packages/types/src/index.ts index 996f53c4c685..13651b7cd78e 100644 --- a/packages/types/src/index.ts +++ b/packages/types/src/index.ts @@ -6,9 +6,7 @@ export { DsnComponents, DsnLike, DsnProtocol } from './dsn'; export { DebugImage, DebugImageType, DebugMeta } from './debugMeta'; export { AttachmentItem, - BaseEnvelope, BaseEnvelopeHeaders, - BaseEnvelopeItem, BaseEnvelopeItemHeaders, ClientReportEnvelope, ClientReportItem, From a9ac0ca1682469b062c37198fb1c226929d35e6b Mon Sep 17 00:00:00 2001 From: Abhijeet Prasad Date: Fri, 25 Feb 2022 09:03:40 -0500 Subject: [PATCH 6/6] default arg --- packages/utils/src/envelope.ts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/utils/src/envelope.ts b/packages/utils/src/envelope.ts index 0b06d3b266fe..7552bd339784 100644 --- a/packages/utils/src/envelope.ts +++ b/packages/utils/src/envelope.ts @@ -5,7 +5,7 @@ import { Envelope } from '@sentry/types'; * Make sure to always explicitly provide the generic to this function * so that the envelope types resolve correctly. */ -export function createEnvelope(headers: E[0], items: E[1]): E { +export function createEnvelope(headers: E[0], items: E[1] = []): E { return [headers, items] as E; }