From d45557935f25e277d06d012e1475a3eec96048e4 Mon Sep 17 00:00:00 2001 From: Abhijeet Prasad Date: Wed, 9 Feb 2022 11:44:57 -0500 Subject: [PATCH 1/2] feat(types): Add Envelope types 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`. --- packages/types/src/envelope.ts | 66 ++++++++++++++++++++++++++++++++++ packages/types/src/index.ts | 9 +++++ 2 files changed, 75 insertions(+) create mode 100644 packages/types/src/envelope.ts diff --git a/packages/types/src/envelope.ts b/packages/types/src/envelope.ts new file mode 100644 index 000000000000..0c89b1ff594b --- /dev/null +++ b/packages/types/src/envelope.ts @@ -0,0 +1,66 @@ +import { SentryRequestType } from './request'; +import { SdkInfo } from './sdkinfo'; +import { Session, SessionAggregates } from './session'; +import { Outcome } from './transport'; +import { User } from './user'; + +// Based on: https://develop.sentry.dev/sdk/envelopes/ + +type CommonEnvelopeHeaders = { + dsn?: string; + sdk?: SdkInfo; +}; + +type CommonEnvelopeItemHeaders = { + length?: number; +}; + +/** + * 1st Item: Item headers + * 2nd Item: Item payload + */ +type BaseEnvelopeItem = [ + CommonEnvelopeItemHeaders & ItemHeader, + Payload, +]; + +type UnknownEnvelopeItem = BaseEnvelopeItem<{ type: '__unknown__' }>; + +type BaseEnvelope, EnvelopeItems extends BaseEnvelopeItem> = { + h: CommonEnvelopeHeaders & EnvelopeHeaders; + i: Array; +}; + +export type EventEnvelopeItem = BaseEnvelopeItem<{ type: 'event' | 'transaction' }, Event>; + +type AttachmentEnvelopeItem = BaseEnvelopeItem<{ type: 'attachment'; filename: 'string' }>; + +type UserFeedbackEnvelopeItem = BaseEnvelopeItem< + { type: 'user_report' }, + { + event_id: string; + email: User['email']; + name: string; + comments: string; + } +>; + +export type EventEnvelope = BaseEnvelope< + { event_id: string; sent_at: string }, + EventEnvelopeItem | AttachmentEnvelopeItem | UserFeedbackEnvelopeItem +>; + +export type SessionEnvelopeItem = + | BaseEnvelopeItem<{ type: 'session' }, Session> + | BaseEnvelopeItem<{ type: 'sessions' }, SessionAggregates>; + +export type SessionEnvelope = BaseEnvelope<{ sent_at: string }, SessionEnvelopeItem>; + +export type ClientReportEnvelopeItem = BaseEnvelopeItem< + { type: 'client_report' }, + { timestamp: number; discarded_events: { reason: Outcome; category: SentryRequestType; quantity: number } } +>; + +export type ClientReportEnvelope = BaseEnvelope, ClientReportEnvelopeItem>; + +export type Envelope = EventEnvelope | SessionEnvelope | ClientReportEnvelope; diff --git a/packages/types/src/index.ts b/packages/types/src/index.ts index ecb62c2937fa..818f50759fa0 100644 --- a/packages/types/src/index.ts +++ b/packages/types/src/index.ts @@ -3,6 +3,15 @@ export { Client } from './client'; export { Context, Contexts } from './context'; export { DsnComponents, DsnLike, DsnProtocol } from './dsn'; export { DebugImage, DebugImageType, DebugMeta } from './debugMeta'; +export { + ClientReportEnvelope, + ClientReportEnvelopeItem, + Envelope, + EventEnvelope, + EventEnvelopeItem, + SessionEnvelope, + SessionEnvelopeItem, +} from './envelope'; export { ExtendedError } from './error'; export { Event, EventHint } from './event'; export { EventStatus } from './eventstatus'; From 538882c8cad4144f01a8f9e590d1615f03470431 Mon Sep 17 00:00:00 2001 From: Abhijeet Prasad Date: Thu, 10 Feb 2022 08:29:37 -0500 Subject: [PATCH 2/2] address PR review comments --- packages/types/src/envelope.ts | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) diff --git a/packages/types/src/envelope.ts b/packages/types/src/envelope.ts index 0c89b1ff594b..0c981cb1557a 100644 --- a/packages/types/src/envelope.ts +++ b/packages/types/src/envelope.ts @@ -26,9 +26,12 @@ type BaseEnvelopeItem = type UnknownEnvelopeItem = BaseEnvelopeItem<{ type: '__unknown__' }>; -type BaseEnvelope, EnvelopeItems extends BaseEnvelopeItem> = { - h: CommonEnvelopeHeaders & EnvelopeHeaders; - i: Array; +type BaseEnvelope< + EnvelopeHeaders extends Record, + EnvelopeItem extends BaseEnvelopeItem<{ type: string }>, +> = { + headers: CommonEnvelopeHeaders & EnvelopeHeaders; + items: Array; }; export type EventEnvelopeItem = BaseEnvelopeItem<{ type: 'event' | 'transaction' }, Event>;