Merge remote-tracking branch 'upstream/7.x' into feat/attachments

Author: timfish

MIGRATION.md

@@ -102,7 +102,110 @@ const storeEndpoint = api.getStoreEndpointWithUrlEncodedAuth();
 const envelopeEndpoint = api.getEnvelopeEndpointWithUrlEncodedAuth();
 ```
 
-## Enum changes
+## Transport Changes
+
+The `Transport` API was simplified and some functionality (e.g. APIDetails and client reports) was refactored and moved
+to the Client. To send data to Sentry, we switched from the previously used [Store endpoint](https://develop.sentry.dev/sdk/store/) to the [Envelopes endpoint](https://develop.sentry.dev/sdk/envelopes/).
+
+This example shows the new v7 and the v6 Transport API:
+
+```js
+// New in v7:
+export interface Transport {
+  /* Sends an envelope to the Envelope endpoint in Sentry */
+  send(request: Envelope): PromiseLike<void>;
+  /* Waits for all events to be sent or the timeout to expire, whichever comes first */
+  flush(timeout?: number): PromiseLike<boolean>;
+}
+
+// Before:
+export interface Transport {
+  /* Sends the event to the Store endpoint in Sentry */
+  sendEvent(event: Event): PromiseLike<Response>;
+  /* Sends the session to the Envelope endpoint in Sentry */
+  sendSession?(session: Session | SessionAggregates): PromiseLike<Response>;
+  /* Waits for all events to be sent or the timeout to expire, whichever comes first */
+  close(timeout?: number): PromiseLike<boolean>;
+  /* Increment the counter for the specific client outcome */
+  recordLostEvent?(type: Outcome, category: SentryRequestType): void;
+}
+```
+
+### Custom Transports
+If you rely on a custom transport, you will need to make some adjustments to how it is created when migrating
+to v7. Note that we changed our transports from a class-based to a functional approach, meaning that
+the previously class-based transports are now created via functions. This also means that custom transports
+are now passed by specifying a factory function in the `Sentry.init` options object instead passing the custom
+transport's class.
+
+The following example shows how to create a custom transport in v7 vs. how it was done in v6:
+
+```js
+// New in v7:
+import { BaseTransportOptions, Transport, TransportMakeRequestResponse, TransportRequest } from '@sentry/types';
+import { createTransport } from '@sentry/core';
+
+export function makeMyCustomTransport(options: BaseTransportOptions): Transport {
+  function makeRequest(request: TransportRequest): PromiseLike<TransportMakeRequestResponse> {
+    // this is where your sending logic goes
+    const myCustomRequest = {
+      body: request.body,
+      url: options.url
+    };
+    // you define how `sendMyCustomRequest` works
+    return sendMyCustomRequest(myCustomRequest).then(response => ({
+      headers: {
+        'x-sentry-rate-limits': response.headers.get('X-Sentry-Rate-Limits'),
+        'retry-after': response.headers.get('Retry-After'),
+      },
+    }));
+  }
+
+  // `createTransport` takes care of rate limiting and flushing
+  return createTransport({ bufferSize: options.bufferSize }, makeRequest);
+}
+
+Sentry.init({
+  dsn: '...',
+  transport: makeMyCustomTransport, // this function will be called when the client is initialized
+  ...
+})
+
+
+
+// Before:
+class MyCustomTransport extends BaseTransport {
+  constructor(options: TransportOptions) {
+    // initialize your transport here
+    super(options);
+  }
+
+  public sendEvent(event: Event): PromiseLike<Response> {
+    // this is where your sending logic goes
+    // `url` is decoded from dsn in BaseTransport
+    const myCustomRequest = createMyCustomRequestFromEvent(event, this.url);
+    return sendMyCustomRequest(myCustomRequest).then(() => resolve({status: 'success'}));
+  }
+
+  public sendSession(session: Session): PromiseLike<Response> {...}
+  // ...
+}
+
+Sentry.init({
+  dsn: '...',
+  transport: MyCustomTransport, // the constructor was called when the client was initialized
+  ...
+})
+```
+
+Overall, the new way of transport creation allows you to create your custom sending implementation
+without having to deal with the conversion of events or sessions to envelopes.
+We recommend calling using the `createTransport` function from `@sentry/core` as demonstrated in the example above which, besides creating the `Transport`
+object with your custom logic, will also take care of rate limiting and flushing.
+
+For a complete v7 transport implementation, take a look at our [browser fetch transport](https://github.com/getsentry/sentry-javascript/blob/ebc938a03d6efe7d0c4bbcb47714e84c9a566a9c/packages/browser/src/transports/fetch.ts#L1-L34).
+
+## Enum Changes
 
 Given that enums have a high bundle-size impact, our long term goal is to eventually remove all enums from the SDK in
 favor of string literals.

packages/browser/src/client.ts

@@ -1,10 +1,7 @@
 import { BaseClient, Scope, SDK_VERSION } from '@sentry/core';
 import { AttachmentItem, ClientOptions, Event, EventHint, Options, Severity, SeverityLevel } from '@sentry/types';
-import { getGlobalObject, logger } from '@sentry/utils';
 
 import { eventFromException, eventFromMessage } from './eventbuilder';
-import { IS_DEBUG_BUILD } from './flags';
-import { injectReportDialog, ReportDialogOptions } from './helpers';
 import { Breadcrumbs } from './integrations';
 
 export interface BaseBrowserOptions {
@@ -62,29 +59,6 @@ export class BrowserClient extends BaseClient<BrowserClientOptions> {
     super(options);
   }
 
-  /**
-   * Show a report dialog to the user to send feedback to a specific event.
-   *
-   * @param options Set individual options for the dialog
-   */
-  public showReportDialog(options: ReportDialogOptions = {}): void {
-    // doesn't work without a document (React Native)
-    const document = getGlobalObject<Window>().document;
-    if (!document) {
-      return;
-    }
-
-    if (!this._isEnabled()) {
-      IS_DEBUG_BUILD && logger.error('Trying to call showReportDialog with Sentry Client disabled');
-      return;
-    }
-
-    injectReportDialog({
-      ...options,
-      dsn: options.dsn || this.getDsn(),
-    });
-  }
-
   /**
    * @inheritDoc
    */

packages/browser/src/exports.ts

@@ -52,6 +52,5 @@ export {
   opera11StackParser,
   winjsStackParser,
 } from './stack-parsers';
-export { injectReportDialog } from './helpers';
 export { defaultIntegrations, forceLoad, init, lastEventId, onLoad, showReportDialog, flush, close, wrap } from './sdk';
 export { SDK_NAME } from './version';

packages/browser/src/helpers.ts

@@ -1,18 +1,13 @@
-import { captureException, getReportDialogEndpoint, withScope } from '@sentry/core';
+import { captureException, withScope } from '@sentry/core';
 import { DsnLike, Event as SentryEvent, Mechanism, Scope, WrappedFunction } from '@sentry/types';
 import {
   addExceptionMechanism,
   addExceptionTypeValue,
   addNonEnumerableProperty,
-  getGlobalObject,
   getOriginalFunction,
-  logger,
   markFunctionWrapped,
 } from '@sentry/utils';
 
-import { IS_DEBUG_BUILD } from './flags';
-
-const global = getGlobalObject<Window>();
 let ignoreOnError: number = 0;
 
 /**
@@ -182,38 +177,3 @@ export interface ReportDialogOptions {
   /** Callback after reportDialog showed up */
   onLoad?(): void;
 }
-
-/**
- * Injects the Report Dialog script
- * @hidden
- */
-export function injectReportDialog(options: ReportDialogOptions = {}): void {
-  if (!global.document) {
-    return;
-  }
-
-  if (!options.eventId) {
-    IS_DEBUG_BUILD && logger.error('Missing eventId option in showReportDialog call');
-    return;
-  }
-
-  if (!options.dsn) {
-    IS_DEBUG_BUILD && logger.error('Missing dsn option in showReportDialog call');
-    return;
-  }
-
-  const script = global.document.createElement('script');
-  script.async = true;
-  script.src = getReportDialogEndpoint(options.dsn, options);
-
-  if (options.onLoad) {
-    // eslint-disable-next-line @typescript-eslint/unbound-method
-    script.onload = options.onLoad;
-  }
-
-  const injectionPoint = global.document.head || global.document.body;
-
-  if (injectionPoint) {
-    injectionPoint.appendChild(script);
-  }
-}

packages/browser/src/sdk.ts

@@ -1,5 +1,11 @@
-import { getCurrentHub, getIntegrationsToSetup, initAndBind, Integrations as CoreIntegrations } from '@sentry/core';
-import { Hub } from '@sentry/types';
+import {
+  getCurrentHub,
+  getIntegrationsToSetup,
+  getReportDialogEndpoint,
+  Hub,
+  initAndBind,
+  Integrations as CoreIntegrations,
+} from '@sentry/core';
 import {
   addInstrumentationHandler,
   getGlobalObject,
@@ -121,9 +127,21 @@ export function init(options: BrowserOptions = {}): void {
  *
  * @param options Everything is optional, we try to fetch all info need from the global scope.
  */
-export function showReportDialog(options: ReportDialogOptions = {}): void {
-  const hub = getCurrentHub();
-  const scope = hub.getScope();
+export function showReportDialog(options: ReportDialogOptions = {}, hub: Hub = getCurrentHub()): void {
+  // doesn't work without a document (React Native)
+  const global = getGlobalObject<Window>();
+  if (!global.document) {
+    IS_DEBUG_BUILD && logger.error('Global document not defined in showReportDialog call');
+    return;
+  }
+
+  const { client, scope } = hub.getStackTop();
+  const dsn = options.dsn || (client && client.getDsn());
+  if (!dsn) {
+    IS_DEBUG_BUILD && logger.error('DSN not configured for showReportDialog call');
+    return;
+  }
+
   if (scope) {
     options.user = {
       ...scope.getUser(),
@@ -134,9 +152,21 @@ export function showReportDialog(options: ReportDialogOptions = {}): void {
   if (!options.eventId) {
     options.eventId = hub.lastEventId();
   }
-  const client = hub.getClient<BrowserClient>();
-  if (client) {
-    client.showReportDialog(options);
+
+  const script = global.document.createElement('script');
+  script.async = true;
+  script.src = getReportDialogEndpoint(dsn, options);
+
+  if (options.onLoad) {
+    // eslint-disable-next-line @typescript-eslint/unbound-method
+    script.onload = options.onLoad;
+  }
+
+  const injectionPoint = global.document.head || global.document.body;
+  if (injectionPoint) {
+    injectionPoint.appendChild(script);
+  } else {
+    IS_DEBUG_BUILD && logger.error('Not injecting report dialog. No injection point found in HTML');
   }
 }
 

packages/browser/src/transports/fetch.ts

@@ -30,5 +30,5 @@ export function makeFetchTransport(
     }));
   }
 
-  return createTransport({ bufferSize: options.bufferSize }, makeRequest);
+  return createTransport(options, makeRequest);
 }

packages/browser/src/transports/xhr.ts

@@ -21,17 +21,20 @@ export interface XHRTransportOptions extends BaseTransportOptions {
  */
 export function makeXHRTransport(options: XHRTransportOptions): Transport {
   function makeRequest(request: TransportRequest): PromiseLike<TransportMakeRequestResponse> {
-    return new SyncPromise<TransportMakeRequestResponse>((resolve, _reject) => {
+    return new SyncPromise((resolve, reject) => {
       const xhr = new XMLHttpRequest();
 
+      xhr.onerror = reject;
+
       xhr.onreadystatechange = (): void => {
         if (xhr.readyState === XHR_READYSTATE_DONE) {
-          resolve({
+          const response = {
             headers: {
               'x-sentry-rate-limits': xhr.getResponseHeader('X-Sentry-Rate-Limits'),
               'retry-after': xhr.getResponseHeader('Retry-After'),
             },
-          });
+          };
+          resolve(response);
         }
       };
 
@@ -47,5 +50,5 @@ export function makeXHRTransport(options: XHRTransportOptions): Transport {
     });
   }
 
-  return createTransport({ bufferSize: options.bufferSize }, makeRequest);
+  return createTransport(options, makeRequest);
 }

packages/browser/test/unit/helper/browser-client-options.ts

@@ -6,7 +6,7 @@ import { BrowserClientOptions } from '../../../src/client';
 export function getDefaultBrowserClientOptions(options: Partial<BrowserClientOptions> = {}): BrowserClientOptions {
   return {
     integrations: [],
-    transport: () => createTransport({}, _ => resolvedSyncPromise({})),
+    transport: () => createTransport({ recordDroppedEvent: () => undefined }, _ => resolvedSyncPromise({})),
     stackParser: () => [],
     ...options,
   };

packages/browser/test/unit/index.test.ts

@@ -1,4 +1,4 @@
-import { SDK_VERSION } from '@sentry/core';
+import { getReportDialogEndpoint, SDK_VERSION } from '@sentry/core';
 
 import {
   addBreadcrumb,
@@ -24,6 +24,14 @@ const dsn = 'https://[email protected]/4291';
 // eslint-disable-next-line no-var
 declare var global: any;
 
+jest.mock('@sentry/core', () => {
+  const original = jest.requireActual('@sentry/core');
+  return {
+    ...original,
+    getReportDialogEndpoint: jest.fn(),
+  };
+});
+
 describe('SentryBrowser', () => {
   const beforeSend = jest.fn();
 
@@ -74,16 +82,14 @@ describe('SentryBrowser', () => {
   });
 
   describe('showReportDialog', () => {
+    beforeEach(() => {
+      (getReportDialogEndpoint as jest.Mock).mockReset();
+    });
+
     describe('user', () => {
       const EX_USER = { email: '[email protected]' };
       const options = getDefaultBrowserClientOptions({ dsn });
       const client = new BrowserClient(options);
-      const reportDialogSpy = jest.spyOn(client, 'showReportDialog');
-
-      beforeEach(() => {
-        reportDialogSpy.mockReset();
-      });
-
       it('uses the user on the scope', () => {
         configureScope(scope => {
           scope.setUser(EX_USER);
@@ -92,8 +98,11 @@ describe('SentryBrowser', () => {
 
         showReportDialog();
 
-        expect(reportDialogSpy).toBeCalled();
-        expect(reportDialogSpy.mock.calls[0][0]!.user!.email).toBe(EX_USER.email);
+        expect(getReportDialogEndpoint).toHaveBeenCalledTimes(1);
+        expect(getReportDialogEndpoint).toHaveBeenCalledWith(
+          expect.any(Object),
+          expect.objectContaining({ user: { email: EX_USER.email } }),
+        );
       });
 
       it('prioritizes options user over scope user', () => {
@@ -105,8 +114,11 @@ describe('SentryBrowser', () => {
         const DIALOG_OPTION_USER = { email: '[email protected]' };
         showReportDialog({ user: DIALOG_OPTION_USER });
 
-        expect(reportDialogSpy).toBeCalled();
-        expect(reportDialogSpy.mock.calls[0][0]!.user!.email).toBe(DIALOG_OPTION_USER.email);
+        expect(getReportDialogEndpoint).toHaveBeenCalledTimes(1);
+        expect(getReportDialogEndpoint).toHaveBeenCalledWith(
+          expect.any(Object),
+          expect.objectContaining({ user: { email: DIALOG_OPTION_USER.email } }),
+        );
       });
     });
   });