feat(utils): Introduce envelope helper functions #4587

AbhiPrasad · 2022-02-15T23:53:02Z

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
#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 headers/items are typed accordingly.

To add items to envelopes, theaddItemToEnvelope() functions is exposed.
In the interest of keeping the API surface small, we settled with just this one
function, but we can come back and change it later on.

Finally, there is serializeEnvelope(), which is used to serialize an
envelope to a string. It does have some TypeScript complications, which
are 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.

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.

Edit: See that PR right here: #4588

Resolves https://getsentry.atlassian.net/browse/WEB-558

github-actions · 2022-02-16T00:03:48Z

size-limit report

Path	Base Size (bb6f865)	Current Size	Change
@sentry/browser - ES5 CDN Bundle (gzipped + minified)	19.7 KB	19.7 KB	-0.01% 🔽
@sentry/browser - ES5 CDN Bundle (minified)	63.31 KB	63.31 KB	0%
@sentry/browser - ES6 CDN Bundle (gzipped + minified)	18.37 KB	18.37 KB	+0.01% 🔺
@sentry/browser - ES6 CDN Bundle (minified)	56.48 KB	56.48 KB	0%
@sentry/browser - Webpack (gzipped + minified)	22.16 KB	22.16 KB	0%
@sentry/browser - Webpack (minified)	76.18 KB	76.18 KB	0%
@sentry/react - Webpack (gzipped + minified)	22.19 KB	22.19 KB	0%
@sentry/nextjs Client - Webpack (gzipped + minified)	46.33 KB	46.33 KB	0%
@sentry/browser + @sentry/tracing - ES5 CDN Bundle (gzipped + minified)	27.16 KB	27.16 KB	0%

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 #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.

lobsterkatie

Just a few comments, but overall looks good!

lobsterkatie · 2022-02-23T17:08:51Z

packages/utils/src/envelope.ts

+ * Make sure to always explicitly provide the generic to this function
+ * so that the envelope types resolve correctly.
+ */
+export function createEnvelope<E extends Envelope>(headers: E[0], items: E[1]): E {


Suggested change

export function createEnvelope<E extends Envelope>(headers: E[0], items: E[1]): E {

export function createEnvelope<E extends Envelope>(headers: E[0], items: E[1] = []): E {

Obviously it doesn't make a ton of sense for someone to make an empty envelope, but just in case...

(This protects against return [headers, [...items, newItem]] as E; in addItemToEnvelope crashing if someone were to create an empty envelope since, stupidly, you can do {...undefined} but not [...undefined].)

lobsterkatie · 2022-02-25T04:42:44Z

packages/utils/src/envelope.ts

+  // 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


After #4609, is this workaround still necessary?

Yup, as items is still a union type.

lobsterkatie · 2022-02-25T04:49:35Z

packages/utils/test/testutils.ts

+export function parseEnvelope(env: string): Array<Record<any, any>> {
+  return env.split('\n').map(e => JSON.parse(e));
+}


FWIW, we have such a function already if you want to use it:

sentry-javascript/packages/core/test/lib/request.test.ts

Lines 22 to 30 in bb6f865

function parseEnvelopeRequest(request: SentryRequest): any {

const [envelopeHeaderString, itemHeaderString, eventString] = request.body.split('\n');

return {

envelopeHeader: JSON.parse(envelopeHeaderString),

itemHeader: JSON.parse(itemHeaderString),

event: JSON.parse(eventString),

};

}

. Up to you.

I'll leave it like this because this works with multiple envelope items - doesn't just assume a single one. Useful for when we expand the tests in the future.

This patch converts the sessions logic in `packages/core/src/request.ts` to use the recently introduced envelope helpers. ref: #4587

This patch converts the events logic in `packages/core/src/request.ts` to use the recently introduced envelope helpers. ref: #4587

This patch converts the sessions logic in `packages/core/src/request.ts` to use the recently introduced envelope helpers. ref: #4587

AbhiPrasad mentioned this pull request Feb 15, 2022

ref(browser): Introduce client reports envelope helper #4588

Merged

AbhiPrasad added 2 commits February 23, 2022 09:14

yarn fix lint

b342328

AbhiPrasad force-pushed the abhi-envelope-functions branch from 518332c to b342328 Compare February 23, 2022 14:18

update tests

d7d551e

AbhiPrasad requested a review from lobsterkatie February 23, 2022 14:28

AbhiPrasad added this to the Pre 7.0.0 Work milestone Feb 23, 2022

AbhiPrasad added 3 commits February 24, 2022 14:27

dont export base types

7fe5ed1

Merge branch 'master' into abhi-envelope-functions

4baeaa0

fix import

a4b5541

lobsterkatie approved these changes Feb 25, 2022

View reviewed changes

default arg

a9ac0ca

AbhiPrasad enabled auto-merge (squash) February 25, 2022 14:13

AbhiPrasad merged commit 041186e into master Feb 25, 2022

AbhiPrasad deleted the abhi-envelope-functions branch February 25, 2022 14:16

AbhiPrasad added a commit that referenced this pull request Mar 1, 2022

ref(core): Use helpers with session envelopes

e003307

This patch converts the sessions logic in `packages/core/src/request.ts` to use the recently introduced envelope helpers. ref: #4587

AbhiPrasad mentioned this pull request Mar 1, 2022

ref(core): Use helpers with session envelopes #4655

Merged

AbhiPrasad added a commit that referenced this pull request Mar 1, 2022

ref(core): Use helpers with event envelopes

2c4cfa9

This patch converts the events logic in `packages/core/src/request.ts` to use the recently introduced envelope helpers. ref: #4587

AbhiPrasad mentioned this pull request Mar 1, 2022

ref(core): Use helpers with event envelopes #4656

Merged

AbhiPrasad added a commit that referenced this pull request Mar 1, 2022

ref(core): Use helpers with event envelopes (#4656)

b1009b5

This patch converts the events logic in `packages/core/src/request.ts` to use the recently introduced envelope helpers. ref: #4587

AbhiPrasad added a commit that referenced this pull request Mar 2, 2022

ref(core): Use helpers with event envelopes (#4656)

209df9c

This patch converts the events logic in `packages/core/src/request.ts` to use the recently introduced envelope helpers. ref: #4587

AbhiPrasad added a commit that referenced this pull request Mar 2, 2022

ref(core): Use helpers with session envelopes

77ea0bd

This patch converts the sessions logic in `packages/core/src/request.ts` to use the recently introduced envelope helpers. ref: #4587

AbhiPrasad added a commit that referenced this pull request Mar 2, 2022

ref(core): Use helpers with session envelopes (#4655)

fcdb458

This patch converts the sessions logic in `packages/core/src/request.ts` to use the recently introduced envelope helpers. ref: #4587

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat(utils): Introduce envelope helper functions #4587

feat(utils): Introduce envelope helper functions #4587

AbhiPrasad commented Feb 15, 2022 •

edited

Loading

github-actions bot commented Feb 16, 2022 •

edited

Loading

lobsterkatie left a comment

lobsterkatie Feb 23, 2022

lobsterkatie Feb 25, 2022

AbhiPrasad Feb 25, 2022

lobsterkatie Feb 25, 2022

AbhiPrasad Feb 25, 2022

	export function createEnvelope<E extends Envelope>(headers: E[0], items: E[1]): E {
	export function createEnvelope<E extends Envelope>(headers: E[0], items: E[1] = []): E {

	function parseEnvelopeRequest(request: SentryRequest): any {
	const [envelopeHeaderString, itemHeaderString, eventString] = request.body.split('\n');

	return {
	envelopeHeader: JSON.parse(envelopeHeaderString),
	itemHeader: JSON.parse(itemHeaderString),
	event: JSON.parse(eventString),
	};
	}

feat(utils): Introduce envelope helper functions #4587

feat(utils): Introduce envelope helper functions #4587

Conversation

AbhiPrasad commented Feb 15, 2022 • edited Loading

github-actions bot commented Feb 16, 2022 • edited Loading

size-limit report

lobsterkatie left a comment

Choose a reason for hiding this comment

lobsterkatie Feb 23, 2022

Choose a reason for hiding this comment

lobsterkatie Feb 25, 2022

Choose a reason for hiding this comment

AbhiPrasad Feb 25, 2022

Choose a reason for hiding this comment

lobsterkatie Feb 25, 2022

Choose a reason for hiding this comment

AbhiPrasad Feb 25, 2022

Choose a reason for hiding this comment

AbhiPrasad commented Feb 15, 2022 •

edited

Loading

github-actions bot commented Feb 16, 2022 •

edited

Loading