Add integration for offline support

packages/integrations/package.json

@@ -18,6 +18,7 @@
   "dependencies": {
     "@sentry/types": "5.20.1",
     "@sentry/utils": "5.20.1",
+    "localforage": "^1.8.1",
     "tslib": "^1.9.3"
   },
   "devDependencies": {

packages/integrations/src/index.ts

@@ -4,6 +4,7 @@ export { Debug } from './debug';
 export { Dedupe } from './dedupe';
 export { Ember } from './ember';
 export { ExtraErrorData } from './extraerrordata';
+export { Offline } from './offline';
 export { ReportingObserver } from './reportingobserver';
 export { RewriteFrames } from './rewriteframes';
 export { SessionTiming } from './sessiontiming';

packages/integrations/src/offline.ts

@@ -0,0 +1,116 @@
+import { Event, EventProcessor, Hub, Integration } from '@sentry/types';
+import { getGlobalObject, logger, uuid4 } from '@sentry/utils';
+// @ts-ignore: Module '"localforage"' has no default export.
+import localforage from 'localforage';
+
+/**
+ * cache offline errors and send when connected
+ */
+export class Offline implements Integration {
+  /**
+   * @inheritDoc
+   */
+  public static id: string = 'Offline';
+
+  /**
+   * @inheritDoc
+   */
+  public readonly name: string = Offline.id;
+
+  /**
+   * the global instance
+   */
+  public global: Window;
+
+  /**
+   * the current hub instance
+   */
+  public hub?: Hub;
+
+  /**
+   * event cache
+   */
+  public offlineEventStore: LocalForage; // type imported from localforage
+
+  /**
+   * @inheritDoc
+   */
+  public constructor() {
+    this.global = getGlobalObject<Window>();
+    this.offlineEventStore = localforage.createInstance({
+      name: 'sentry/offlineEventStore',
+    });
+
+    if ('addEventListener' in this.global) {
+      this.global.addEventListener('online', (): void => {
+        this._sendEvents().catch(() => {
+          logger.warn('could not send cached events');
+        });
+      });
+    }
+  }
+
+  /**
+   * @inheritDoc
+   */
+  public setupOnce(addGlobalEventProcessor: (callback: EventProcessor) => void, getCurrentHub: () => Hub): void {
+    this.hub = getCurrentHub();
+
+    addGlobalEventProcessor((event: Event) => {
+      if (this.hub && this.hub.getIntegration(Offline)) {
+        // cache if we are positively offline
+        if ('navigator' in this.global && 'onLine' in this.global.navigator && !this.global.navigator.onLine) {
+          this._cacheEvent(event).catch((_error: any) => {
+            logger.warn('could not cache event while offline');
+          });
+
+          // return null on success or failure, because being offline will still result in an error
+          return null;
+        }
+      }
+
+      return event;
+    });
+
+    // if online now, send any events stored in a previous offline session
+    if ('navigator' in this.global && 'onLine' in this.global.navigator && this.global.navigator.onLine) {
+      this._sendEvents().catch(() => {
+        logger.warn('could not send cached events');
+      });
+    }
+  }
+
+  /**
+   * cache an event to send later
+   * @param event an event
+   */
+  private async _cacheEvent(event: Event): Promise<Event> {
+    return this.offlineEventStore.setItem<Event>(uuid4(), event);
+  }
+
+  /**
+   * purge event from cache
+   */
+  private async _purgeEvent(cacheKey: string): Promise<void> {
+    return this.offlineEventStore.removeItem(cacheKey);
+  }
+
+  /**
+   * send all events
+   */
+  private async _sendEvents(): Promise<void> {
+    return this.offlineEventStore.iterate<Event, void>((event: Event, cacheKey: string, _index: number): void => {
+      if (this.hub) {
+        const newEventId = this.hub.captureEvent(event);
+
+        if (newEventId) {
+          this._purgeEvent(cacheKey).catch((_error: any): void => {
+            logger.warn('could not purge event from cache');
+          });
+        }
+      } else {
+        logger.warn('no hub found - could not send cached event');
+      }
+    });
+  }
+}

packages/integrations/test/offline.test.ts

@@ -0,0 +1,162 @@
+import { Event, EventProcessor, Hub, Integration } from '@sentry/types';
+import * as utils from '@sentry/utils';
+
+import { Offline } from '../src/offline';
+
+// mock localforage methods
+jest.mock('localforage', () => ({
+  createInstance(_options: object): any {
+    let items: object[] = [];
+
+    return {
+      async getItem(key: string): object {
+        return items.find(item => item.key === key);
+      },
+      async iterate(callback: () => void): void {
+        items.forEach((item, index) => {
+          callback(item.value, item.key, index);
+        });
+      },
+      async length(): number {
+        return items.length;
+      },
+      async removeItem(key: string): void {
+        items = items.filter(item => item.key !== key);
+      },
+      async setItem(key: string, value: Event): void {
+        items.push({
+          key,
+          value,
+        });
+      },
+    };
+  },
+}));
+
+// mock sentry utils
+jest.mock('@sentry/utils');
+
+let integration: Integration;
+let online: boolean;
+
+describe('Offline', () => {
+  describe('when app is online', () => {
+    beforeEach(() => {
+      online = true;
+
+      initIntegration();
+    });
+
+    it('does not store events in offline store', async () => {
+      setupOnce();
+      processEvents();
+
+      expect(await integration.offlineEventStore.length()).toEqual(0);
+    });
+
+    describe('when there are already events in the cache from a previous offline session', () => {
+      beforeEach(done => {
+        const event = { message: 'previous event' };
+
+        integration.offlineEventStore
+          .setItem('previous', event)
+          .then(() => {
+            done();
+          })
+          .catch(error => error);
+      });
+
+      it('sends stored events', async () => {
+        expect(await integration.offlineEventStore.length()).toEqual(1);
+
+        setupOnce();
+        processEvents();
+
+        expect(await integration.offlineEventStore.length()).toEqual(0);
+      });
+    });
+  });
+
+  describe('when app is offline', () => {
+    beforeEach(() => {
+      online = false;
+
+      initIntegration();
+      setupOnce();
+      processEvents();
+    });
+
+    it('stores events in offline store', async () => {
+      expect(await integration.offlineEventStore.length()).toEqual(1);
+    });
+
+    describe('when connectivity is restored', () => {
+      it('sends stored events', async done => {
+        processEventListeners();
+
+        expect(await integration.offlineEventStore.length()).toEqual(0);
+
+        setImmediate(done);
+      });
+    });
+  });
+});
+
+let eventListeners: any[];
+let eventProcessors: EventProcessor[];
+
+/** JSDoc */
+function addGlobalEventProcessor(callback: () => void): void {
+  eventProcessors.push(callback);
+}
+
+/** JSDoc */
+function getCurrentHub(): Hub {
+  return {
+    captureEvent(_event: Event): string {
+      return 'an-event-id';
+    },
+    getIntegration(_integration: Integration): any {
+      // pretend integration is enabled
+      return true;
+    },
+  };
+}
+
+/** JSDoc */
+function initIntegration(): void {
+  eventListeners = [];
+  eventProcessors = [];
+
+  utils.getGlobalObject.mockImplementation(() => ({
+    addEventListener: (_windowEvent, callback) => {
+      eventListeners.push(callback);
+    },
+    navigator: {
+      onLine: online,
+    },
+  }));
+
+  integration = new Offline();
+}
+
+/** JSDoc */
+function processEventListeners(): void {
+  eventListeners.forEach(listener => {
+    listener();
+  });
+}
+
+/** JSDoc */
+function processEvents(): void {
+  eventProcessors.forEach(processor => {
+    processor({
+      message: 'There was an error!',
+    });
+  });
+}
+
+/** JSDoc */
+function setupOnce(): void {
+  integration.setupOnce(addGlobalEventProcessor, getCurrentHub);
+}

packages/integrations/tsconfig.json

@@ -3,6 +3,7 @@
   "include": ["src/**/*.ts", "test/**/*.ts"],
   "exclude": ["dist"],
   "compilerOptions": {
+    "esModuleInterop": true,
     "declarationMap": false,
     "rootDir": ".",
     "types": ["node", "jest"]

yarn.lock

@@ -6528,6 +6528,11 @@ ignore@^5.1.4:
   resolved "https://registry.yarnpkg.com/ignore/-/ignore-5.1.8.tgz#f150a8b50a34289b33e22f5889abd4d8016f0e57"
   integrity sha512-BMpfD7PpiETpBl/A6S498BaIJ6Y/ABT93ETbby2fP00v4EbvPBXWEoaR1UBPKs3iR53pJY7EtZk5KACI57i1Uw==
 
+immediate@~3.0.5:
+  version "3.0.6"
+  resolved "https://registry.yarnpkg.com/immediate/-/immediate-3.0.6.tgz#9db1dbd0faf8de6fbe0f5dd5e56bb606280de69b"
+  integrity sha1-nbHb0Pr43m++D13V5Wu2BigN5ps=
+
 import-fresh@^2.0.0:
   version "2.0.0"
   resolved "https://registry.yarnpkg.com/import-fresh/-/import-fresh-2.0.0.tgz#d81355c15612d386c61f9ddd3922d4304822a546"
@@ -8106,6 +8111,13 @@ libnpmpublish@^1.1.1:
     semver "^5.5.1"
     ssri "^6.0.1"
 
+lie@3.1.1:
+  version "3.1.1"
+  resolved "https://registry.yarnpkg.com/lie/-/lie-3.1.1.tgz#9a436b2cc7746ca59de7a41fa469b3efb76bd87e"
+  integrity sha1-mkNrLMd0bKWd56QfpGmz77dr2H4=
+  dependencies:
+    immediate "~3.0.5"
+
 lines-and-columns@^1.1.6:
   version "1.1.6"
   resolved "https://registry.yarnpkg.com/lines-and-columns/-/lines-and-columns-1.1.6.tgz#1c00c743b433cd0a4e80758f7b64a57440d9ff00"
@@ -8155,6 +8167,13 @@ loader-utils@^2.0.0:
     emojis-list "^3.0.0"
     json5 "^2.1.2"
 
+localforage@^1.8.1:
+  version "1.9.0"
+  resolved "https://registry.yarnpkg.com/localforage/-/localforage-1.9.0.tgz#f3e4d32a8300b362b4634cc4e066d9d00d2f09d1"
+  integrity sha512-rR1oyNrKulpe+VM9cYmcFn6tsHuokyVHFaCM3+osEmxaHTbEk8oQu6eGDfS6DQLWi/N67XRmB8ECG37OES368g==
+  dependencies:
+    lie "3.1.1"
+
 locate-path@^2.0.0:
   version "2.0.0"
   resolved "https://registry.yarnpkg.com/locate-path/-/locate-path-2.0.0.tgz#2b568b265eec944c6d9c0de9c3dbbbca0354cd8e"