feat(types): Add Envelope types #4527
Merged
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
To prep for the introduction of formal envelopes API, add types representing envelopes and their items. These are based on the documentation from the develop docs at the time of this patch. Envelope items are stored as a tuple of length 2 (item headers and payload) to reduce bundle size. This is as array access is smaller than having to access through object properties, and they will stay constant. Each Envelope is generic over a `BaseEnvelope` type, which allows for items and headers to be configured, but sets a `CommonEnvelopeHeaders` alongside a default `UnknownEnvelopeItem` (as per the spec). Each Envelope item is generic over a `BaseEnvelopeItem` type, which establishs `CommonEnvelopeItemHeaders` over an arbitrary item payload. Envelope items are defined for events, attachments, user feedback, sessions, and client reports. Envelopes are defined for events, sessions, and client reports. This is as attachments and user feedback (for now) must be in the envelope alongside the event. As User Feedback and Attachment envelopes are currently not supported in the SDK, they are not exported, but will be once v7 is introduced. The next step from the patch is to add the public API around creating and mutating Envelopes of different natures, as well as mapping from an Envelope -> `SentryRequest`.
AbhiPrasad
requested review from
a team,
Lms24 and
lobsterkatie
and removed request for
a team
size-limit report
|
There was a problem hiding this comment.
This is not a criticism of you, more like the result of some of TS's pitfalls, but overall this feels complicated and harder to grok than I feel like it ideally would be. I wonder if we could put our heads together IRL to see if it's possible to crate a more straightforward way to wrangle TS into submission.
Separately, two small suggestions below.
packages/types/src/envelope.ts
Outdated
Comment on lines
29
to
32
| type BaseEnvelope<EnvelopeHeaders extends Record<string, unknown>, EnvelopeItems extends BaseEnvelopeItem<any>> = { | ||
| h: CommonEnvelopeHeaders & EnvelopeHeaders; | ||
| i: Array<EnvelopeItems | UnknownEnvelopeItem>; | ||
| }; |
There was a problem hiding this comment.
Two things here:
-
The second generic parameter should be singular, I believe, right? Because it's what's going into the array.
-
I get that it saves on bundle size to have the properties be single letters, but in this case the loss of readability/ease of use makes it feel not worth it to me. Especially given that envelopes are something an SDK user might have to deal with (i.e., aren't purely for internal use, though, to be fair, I'd be saying this regardless), I really think we should give these real names.
Suggested change
| type BaseEnvelope<EnvelopeHeaders extends Record<string, unknown>, EnvelopeItems extends BaseEnvelopeItem<any>> = { | |
| h: CommonEnvelopeHeaders & EnvelopeHeaders; | |
| i: Array<EnvelopeItems | UnknownEnvelopeItem>; | |
| }; | |
| type BaseEnvelope<EnvelopeHeaders extends Record<string, unknown>, EnvelopeItem extends BaseEnvelopeItem<any>> = { | |
| headers: CommonEnvelopeHeaders & EnvelopeHeaders; | |
| items: Array<EnvelopeItem | UnknownEnvelopeItem>; | |
| }; |
There was a problem hiding this comment.
The second generic parameter should be singular, I believe, right? Because it's what's going into the array.
Yeah the 2nd parameter can be singular, I just kept it as this because it can be union typed, so it better fit my mental model as I was laying out the types.
I really think we should give these real names.
This is a good point that I didn't fully consider, I agree with the change
I wonder if we could put our heads together IRL to see if it's possible to crate a more straightforward way to wrangle TS into submission.
IMO I think it's pretty clear from the types what is happening. Is there a particular area that is harder to understand? It's also important to note that I'm sure these types will change a bit once we actually use them in the envelope helper functions. This is just a nice start to model out the domains appropriately.
vladanpaunovic
approved these changes
Feb 14, 2022
HofmannZ
reviewed
Feb 15, 2022
| items: Array<EnvelopeItem | UnknownEnvelopeItem>; | ||
| }; | ||
|
|
||
| export type EventEnvelopeItem = BaseEnvelopeItem<{ type: 'event' | 'transaction' }, Event>; |
There was a problem hiding this comment.
This line causes a type error on node version 14.
There was a problem hiding this comment.
Huh interesting. Could you open a GitHub issue please with your tsconfig, package.json and some details about your setup?
There was a problem hiding this comment.
I will try to do that tomorrow, we now locked the @sentry/types to 6.17.7 in our package.json and that resolves the issue.
...
"@sentry/types": "6.17.7"
AbhiPrasad
added a commit
that referenced
this pull request
Feb 15, 2022
#4527 introduced Envelope types. In that patch, we included the `Event` DOM type, which is not declared in all TS environments accidentally - we meant to include Sentry's `Event` type. This patch explicitly introduces Sentry's Event type by importing it in, fixing the build errors that folks were having.
AbhiPrasad
added a commit
that referenced
this pull request
Feb 15, 2022
#4527 introduced Envelope types. In that patch, we included the `Event` DOM type, which is not declared in all TS environments - we meant to include Sentry's `Event` type. This patch explicitly introduces Sentry's Event type by importing it in, fixing the build errors that folks were having. Also updates the changelog for `6.17.9`
AbhiPrasad
added a commit
that referenced
this pull request
Feb 15, 2022
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.
AbhiPrasad
added a commit
that referenced
this pull request
Feb 23, 2022
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.
AbhiPrasad
added a commit
that referenced
this pull request
Feb 25, 2022
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, the`addItemToEnvelope()` 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. ```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.
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
To prep for the introduction of formal envelopes API, add types
representing envelopes and their items. These are based on the
documentation from the develop docs at the time of this patch.
Envelope items are stored as a tuple of length 2 (item headers and
payload) to reduce bundle size. This is as array access is smaller than
having to access through object properties, and they will stay constant.
Each Envelope is generic over a
BaseEnvelopetype, which allows foritems and headers to be configured, but sets a
CommonEnvelopeHeadersalongside a default
UnknownEnvelopeItem(as per the spec).Each Envelope item is generic over a
BaseEnvelopeItemtype, whichestablishs
CommonEnvelopeItemHeadersover an arbitrary item payload.Envelope items are defined for events, attachments, user feedback,
sessions, and client reports. Envelopes are defined for events,
sessions, and client reports. This is as attachments and user feedback
(for now) must be in the envelope alongside the event.
As User Feedback and Attachment envelopes are currently not supported in
the SDK, they are not exported, but will be once v7 is introduced.
The next step from the patch is to add the public API around creating
and mutating Envelopes of different natures, as well as mapping from an
Envelope ->
SentryRequest.Addresses https://getsentry.atlassian.net/browse/WEB-590
See: https://develop.sentry.dev/sdk/envelopes/