@grafana/faro-react-native 1.0.0-alpha.1

package/src/transports/offline/transport.test.ts

@@ -0,0 +1,311 @@
+import type { TransportItem } from '@grafana/faro-core';
+
+import { AsyncStorageOfflineCache } from './OfflineCache';
+import { OfflineTransport } from './transport';
+import type { ConnectivityService } from './types';
+
+// Mock AsyncStorage
+jest.mock('@react-native-async-storage/async-storage', () => ({
+  getItem: jest.fn(() => Promise.resolve(null)),
+  setItem: jest.fn(() => Promise.resolve()),
+  removeItem: jest.fn(() => Promise.resolve()),
+}));
+
+// Mock connectivity service
+class MockConnectivityService implements ConnectivityService {
+  private _isOnline: boolean = true;
+  private subscribers: Set<(isOnline: boolean) => void> = new Set();
+
+  get isOnline(): boolean {
+    return this._isOnline;
+  }
+
+  setOnline(value: boolean): void {
+    this._isOnline = value;
+    this.notifySubscribers();
+  }
+
+  subscribe(callback: (isOnline: boolean) => void): () => void {
+    this.subscribers.add(callback);
+    return () => this.subscribers.delete(callback);
+  }
+
+  dispose(): void {
+    this.subscribers.clear();
+  }
+
+  private notifySubscribers(): void {
+    for (const subscriber of this.subscribers) {
+      subscriber(this._isOnline);
+    }
+  }
+}
+
+// Mock cache
+class MockOfflineCache {
+  private payloads: { timestamp: number; items: TransportItem[] }[] = [];
+
+  async write(payload: { timestamp: number; items: TransportItem[] }): Promise<void> {
+    this.payloads.push(payload);
+  }
+
+  async readAll(): Promise<{ timestamp: number; items: TransportItem[] }[]> {
+    return [...this.payloads];
+  }
+
+  async clear(): Promise<void> {
+    this.payloads = [];
+  }
+
+  async removeByTimestamps(timestamps: number[]): Promise<void> {
+    const set = new Set(timestamps);
+    this.payloads = this.payloads.filter((p) => !set.has(p.timestamp));
+  }
+
+  async getCount(): Promise<number> {
+    return this.payloads.length;
+  }
+}
+
+describe('OfflineTransport', () => {
+  let transport: OfflineTransport;
+  let mockConnectivity: MockConnectivityService;
+  let mockCache: MockOfflineCache;
+
+  const createMockTransportItem = (type: string = 'log'): TransportItem => ({
+    type: type as TransportItem['type'],
+    payload: { message: 'test' },
+    meta: {},
+  });
+
+  beforeEach(() => {
+    jest.clearAllMocks();
+    jest.useFakeTimers();
+
+    mockConnectivity = new MockConnectivityService();
+    mockCache = new MockOfflineCache();
+
+    transport = new OfflineTransport({
+      maxCacheDurationMs: 24 * 60 * 60 * 1000, // 1 day
+    });
+
+    // Constructor starts DefaultConnectivityService polling; dispose it before swapping in mocks
+    const createdConnectivity = (transport as unknown as { connectivityService: ConnectivityService })
+      .connectivityService;
+    (transport as unknown as { connectivityService: ConnectivityService }).connectivityService = mockConnectivity;
+    createdConnectivity.dispose();
+
+    (transport as unknown as { cache: MockOfflineCache }).cache = mockCache;
+  });
+
+  afterEach(() => {
+    transport.dispose();
+    jest.useRealTimers();
+  });
+
+  describe('send', () => {
+    it('should cache items when offline', async () => {
+      mockConnectivity.setOnline(false);
+
+      const item = createMockTransportItem();
+      await transport.send([item]);
+
+      const count = await mockCache.getCount();
+      expect(count).toBe(1);
+    });
+
+    it('should not cache items when online', async () => {
+      mockConnectivity.setOnline(true);
+
+      const item = createMockTransportItem();
+      await transport.send([item]);
+
+      const count = await mockCache.getCount();
+      expect(count).toBe(0);
+    });
+
+    it('should handle single item', async () => {
+      mockConnectivity.setOnline(false);
+
+      const item = createMockTransportItem();
+      await transport.send(item);
+
+      const count = await mockCache.getCount();
+      expect(count).toBe(1);
+    });
+
+    it('should ignore empty items array', async () => {
+      mockConnectivity.setOnline(false);
+
+      await transport.send([]);
+
+      const count = await mockCache.getCount();
+      expect(count).toBe(0);
+    });
+  });
+
+  describe('replay', () => {
+    it('should replay cached items when connectivity is restored', async () => {
+      // Start offline and cache some items
+      mockConnectivity.setOnline(false);
+
+      const item = createMockTransportItem();
+      await transport.send([item]);
+
+      // Set up a mock transport to receive replayed items
+      const mockTransport = {
+        name: 'mock-transport',
+        version: '1.0.0',
+        send: jest.fn().mockResolvedValue(undefined),
+        getIgnoreUrls: () => [],
+        isBatched: () => false,
+      };
+
+      transport.setOtherTransports([mockTransport as any]);
+
+      // Force replay directly instead of relying on connectivity subscription
+      mockConnectivity.setOnline(true);
+      await transport.forceReplay();
+
+      expect(mockTransport.send).toHaveBeenCalled();
+    });
+
+    it('should skip expired payloads', async () => {
+      // Manually add an expired payload
+      const expiredPayload = {
+        timestamp: Date.now() - 2 * 24 * 60 * 60 * 1000, // 2 days ago
+        items: [createMockTransportItem()],
+      };
+      await mockCache.write(expiredPayload);
+
+      const mockTransport = {
+        name: 'mock-transport',
+        version: '1.0.0',
+        send: jest.fn().mockResolvedValue(undefined),
+        getIgnoreUrls: () => [],
+        isBatched: () => false,
+      };
+
+      transport.setOtherTransports([mockTransport as any]);
+
+      // Force replay
+      mockConnectivity.setOnline(true);
+      await transport.forceReplay();
+
+      // Should not send expired payload
+      expect(mockTransport.send).not.toHaveBeenCalled();
+
+      // Should have removed the expired payload
+      const count = await mockCache.getCount();
+      expect(count).toBe(0);
+    });
+  });
+
+  describe('getCachedCount', () => {
+    it('should return correct count', async () => {
+      mockConnectivity.setOnline(false);
+
+      await transport.send([createMockTransportItem()]);
+      await transport.send([createMockTransportItem()]);
+
+      const count = await transport.getCachedCount();
+      expect(count).toBe(2);
+    });
+  });
+
+  describe('clearCache', () => {
+    it('should clear all cached items', async () => {
+      mockConnectivity.setOnline(false);
+
+      await transport.send([createMockTransportItem()]);
+      await transport.send([createMockTransportItem()]);
+
+      await transport.clearCache();
+
+      const count = await transport.getCachedCount();
+      expect(count).toBe(0);
+    });
+  });
+
+  describe('isBatched', () => {
+    it('should return true', () => {
+      expect(transport.isBatched()).toBe(true);
+    });
+  });
+});
+
+describe('AsyncStorageOfflineCache', () => {
+  let cache: AsyncStorageOfflineCache;
+  const AsyncStorage = require('@react-native-async-storage/async-storage');
+
+  beforeEach(() => {
+    jest.clearAllMocks();
+    cache = new AsyncStorageOfflineCache();
+  });
+
+  describe('write and readAll', () => {
+    it('should write and read payloads', async () => {
+      const payload = {
+        timestamp: Date.now(),
+        items: [{ type: 'log' as const, payload: { message: 'test' }, meta: {} }],
+      };
+
+      AsyncStorage.getItem.mockResolvedValueOnce(null);
+      AsyncStorage.setItem.mockResolvedValueOnce(undefined);
+
+      await cache.write(payload);
+
+      expect(AsyncStorage.setItem).toHaveBeenCalled();
+    });
+
+    it('should respect maxCacheSize', async () => {
+      const smallCache = new AsyncStorageOfflineCache({ maxCacheSize: 2 });
+
+      // Simulate existing data with 2 items
+      const existingData = [
+        { timestamp: 1, items: [] },
+        { timestamp: 2, items: [] },
+      ];
+
+      AsyncStorage.getItem.mockResolvedValueOnce(JSON.stringify(existingData));
+      AsyncStorage.setItem.mockResolvedValueOnce(undefined);
+
+      // Add third item
+      await smallCache.write({ timestamp: 3, items: [] });
+
+      // Should have removed oldest and kept only 2
+      const setItemCall = AsyncStorage.setItem.mock.calls[0];
+      const savedData = JSON.parse(setItemCall[1]);
+      expect(savedData.length).toBe(2);
+      expect(savedData[0].timestamp).toBe(2);
+      expect(savedData[1].timestamp).toBe(3);
+    });
+  });
+
+  describe('clear', () => {
+    it('should remove storage key', async () => {
+      await cache.clear();
+      expect(AsyncStorage.removeItem).toHaveBeenCalled();
+    });
+  });
+
+  describe('removeByTimestamps', () => {
+    it('should remove specific payloads', async () => {
+      const existingData = [
+        { timestamp: 1, items: [] },
+        { timestamp: 2, items: [] },
+        { timestamp: 3, items: [] },
+      ];
+
+      AsyncStorage.getItem.mockResolvedValueOnce(JSON.stringify(existingData));
+      AsyncStorage.setItem.mockResolvedValueOnce(undefined);
+
+      await cache.removeByTimestamps([1, 3]);
+
+      const setItemCall = AsyncStorage.setItem.mock.calls[0];
+      const savedData = JSON.parse(setItemCall[1]);
+      expect(savedData.length).toBe(1);
+      expect(savedData[0].timestamp).toBe(2);
+    });
+  });
+});

package/src/transports/offline/transport.ts

@@ -0,0 +1,228 @@
+import { BaseTransport, VERSION } from '@grafana/faro-core';
+import type { Patterns, Transport, TransportItem } from '@grafana/faro-core';
+
+import { DefaultConnectivityService } from './ConnectivityService';
+import { AsyncStorageOfflineCache } from './OfflineCache';
+import type { CachedPayload, ConnectivityService, OfflineCache, OfflineTransportOptions } from './types';
+
+/**
+ * Default maximum cache duration: 3 days in milliseconds.
+ */
+const DEFAULT_MAX_CACHE_DURATION_MS = 3 * 24 * 60 * 60 * 1000;
+
+/**
+ * OfflineTransport - Caches telemetry when offline and replays when online.
+ *
+ * This transport wraps other transports and provides offline caching functionality.
+ * When the device is offline, telemetry is cached to AsyncStorage.
+ * When connectivity is restored, cached telemetry is replayed through the wrapped transports.
+ *
+ * Implementation follows Flutter SDK's OfflineTransport pattern:
+ * - Uses AsyncStorage for persistent caching (matching Flutter's SharedPreferences)
+ * - Respects maxCacheDuration to skip expired entries
+ * - Uses mutex pattern for thread-safe cache access
+ * - Excludes itself when replaying to prevent infinite loops
+ *
+ * @example
+ * ```typescript
+ * import { initializeFaro, FetchTransport, OfflineTransport } from '@grafana/faro-react-native';
+ *
+ * initializeFaro({
+ *   url: 'https://collector.example.com',
+ *   transports: [
+ *     new OfflineTransport({
+ *       maxCacheDurationMs: 3 * 24 * 60 * 60 * 1000, // 3 days
+ *     }),
+ *     new FetchTransport({ url: 'https://collector.example.com' }),
+ *   ],
+ * });
+ * ```
+ */
+export class OfflineTransport extends BaseTransport {
+  readonly name = '@grafana/faro-react-native:transport-offline';
+  readonly version = VERSION;
+
+  private readonly cache: OfflineCache;
+  private readonly connectivityService: ConnectivityService;
+  private readonly maxCacheDurationMs: number;
+  private readonly otherTransports: Transport[] = [];
+  private unsubscribeConnectivity: (() => void) | null = null;
+  private isReplaying: boolean = false;
+
+  constructor(options: OfflineTransportOptions = {}) {
+    super();
+
+    this.maxCacheDurationMs = options.maxCacheDurationMs ?? DEFAULT_MAX_CACHE_DURATION_MS;
+
+    this.cache = new AsyncStorageOfflineCache({
+      storageKeyPrefix: options.storageKeyPrefix,
+      maxCacheSize: options.maxCacheSize,
+    });
+
+    this.connectivityService = new DefaultConnectivityService(options.connectivityCheckIntervalMs);
+
+    // Subscribe to connectivity changes
+    this.unsubscribeConnectivity = this.connectivityService.subscribe((isOnline) => {
+      if (isOnline && !this.isReplaying) {
+        this.replayCachedPayloads();
+      }
+    });
+  }
+
+  /**
+   * Send telemetry items.
+   *
+   * When offline, items are cached for later replay.
+   * When online, this transport does nothing (other transports handle sending).
+   */
+  async send(items: TransportItem | TransportItem[]): Promise<void> {
+    const itemsArray = Array.isArray(items) ? items : [items];
+
+    if (itemsArray.length === 0) {
+      return;
+    }
+
+    if (!this.connectivityService.isOnline) {
+      // Cache items when offline
+      const payload: CachedPayload = {
+        timestamp: Date.now(),
+        items: itemsArray,
+      };
+
+      try {
+        await this.cache.write(payload);
+        this.logDebug(`Cached ${itemsArray.length} items for offline replay`);
+      } catch (error) {
+        this.logError('Failed to cache offline payload', error);
+      }
+    }
+    // When online, do nothing - other transports handle sending
+  }
+
+  override getIgnoreUrls(): Patterns {
+    return [];
+  }
+
+  override isBatched(): boolean {
+    return true;
+  }
+
+  /**
+   * Register other transports for replay.
+   * Called by the transport system after initialization.
+   */
+  setOtherTransports(transports: Transport[]): void {
+    this.otherTransports.length = 0;
+    for (const transport of transports) {
+      if (transport !== this) {
+        this.otherTransports.push(transport);
+      }
+    }
+  }
+
+  /**
+   * Get the current number of cached payloads.
+   */
+  async getCachedCount(): Promise<number> {
+    return this.cache.getCount();
+  }
+
+  /**
+   * Manually trigger replay of cached payloads.
+   * Useful for testing or when you want to force a replay attempt.
+   */
+  async forceReplay(): Promise<void> {
+    if (this.connectivityService.isOnline) {
+      await this.replayCachedPayloads();
+    }
+  }
+
+  /**
+   * Clear all cached payloads.
+   */
+  async clearCache(): Promise<void> {
+    await this.cache.clear();
+  }
+
+  /**
+   * Clean up resources.
+   */
+  dispose(): void {
+    if (this.unsubscribeConnectivity) {
+      this.unsubscribeConnectivity();
+      this.unsubscribeConnectivity = null;
+    }
+    this.connectivityService.dispose();
+  }
+
+  /**
+   * Replay cached payloads through other transports.
+   * Follows Flutter SDK's _readFromFile pattern.
+   */
+  private async replayCachedPayloads(): Promise<void> {
+    if (this.isReplaying) {
+      return;
+    }
+
+    this.isReplaying = true;
+
+    try {
+      const payloads = await this.cache.readAll();
+
+      if (payloads.length === 0) {
+        return;
+      }
+
+      this.logDebug(`Replaying ${payloads.length} cached payloads`);
+
+      const now = Date.now();
+      const successfulTimestamps: number[] = [];
+
+      for (const payload of payloads) {
+        // Skip expired payloads
+        if (now - payload.timestamp > this.maxCacheDurationMs) {
+          this.logDebug(`Skipping expired payload from ${new Date(payload.timestamp).toISOString()}`);
+          successfulTimestamps.push(payload.timestamp);
+          continue;
+        }
+
+        const success = await this.sendToOtherTransports(payload.items);
+
+        if (success) {
+          successfulTimestamps.push(payload.timestamp);
+        }
+      }
+
+      // Remove successfully sent or expired payloads
+      if (successfulTimestamps.length > 0) {
+        await this.cache.removeByTimestamps(successfulTimestamps);
+        this.logDebug(`Removed ${successfulTimestamps.length} payloads from cache`);
+      }
+    } catch (error) {
+      this.logError('Failed to replay cached payloads', error);
+    } finally {
+      this.isReplaying = false;
+    }
+  }
+
+  /**
+   * Send items to all other registered transports.
+   * Follows Flutter SDK's _sendCachedData pattern.
+   */
+  private async sendToOtherTransports(items: TransportItem[]): Promise<boolean> {
+    if (this.otherTransports.length === 0) {
+      this.logWarn('No other transports registered for offline replay');
+      return false;
+    }
+
+    try {
+      for (const transport of this.otherTransports) {
+        await transport.send(items);
+      }
+      return true;
+    } catch (error) {
+      this.logError('Failed to send cached payload to transports', error);
+      return false;
+    }
+  }
+}

package/src/transports/offline/types.ts

@@ -0,0 +1,99 @@
+import type { TransportItem } from '@grafana/faro-core';
+
+/**
+ * Configuration options for the OfflineTransport.
+ */
+export interface OfflineTransportOptions {
+  /**
+   * Maximum duration to keep cached events.
+   * Events older than this will be discarded on replay.
+   * Default: 3 days (259200000ms)
+   */
+  maxCacheDurationMs?: number;
+
+  /**
+   * Maximum number of events to cache.
+   * Oldest events will be discarded when limit is reached.
+   * Default: 1000
+   */
+  maxCacheSize?: number;
+
+  /**
+   * Interval in milliseconds to check connectivity and replay cached events.
+   * Default: 30000 (30 seconds)
+   */
+  connectivityCheckIntervalMs?: number;
+
+  /**
+   * Storage key prefix for AsyncStorage.
+   * Default: 'faro_offline_cache'
+   */
+  storageKeyPrefix?: string;
+}
+
+/**
+ * A cached telemetry payload with timestamp for expiration checking.
+ */
+export interface CachedPayload {
+  /**
+   * Timestamp when the payload was cached (milliseconds since epoch).
+   */
+  timestamp: number;
+
+  /**
+   * The transport items to be sent.
+   */
+  items: TransportItem[];
+}
+
+/**
+ * Interface for connectivity detection service.
+ */
+export interface ConnectivityService {
+  /**
+   * Whether the device currently has network connectivity.
+   */
+  readonly isOnline: boolean;
+
+  /**
+   * Subscribe to connectivity changes.
+   * @param callback Function called when connectivity state changes.
+   * @returns Unsubscribe function.
+   */
+  subscribe(callback: (isOnline: boolean) => void): () => void;
+
+  /**
+   * Clean up resources.
+   */
+  dispose(): void;
+}
+
+/**
+ * Interface for offline cache storage.
+ */
+export interface OfflineCache {
+  /**
+   * Write a payload to the cache.
+   */
+  write(payload: CachedPayload): Promise<void>;
+
+  /**
+   * Read all cached payloads.
+   */
+  readAll(): Promise<CachedPayload[]>;
+
+  /**
+   * Clear all cached payloads.
+   */
+  clear(): Promise<void>;
+
+  /**
+   * Remove specific payloads by their timestamps.
+   */
+  removeByTimestamps(timestamps: number[]): Promise<void>;
+
+  /**
+   * Get the number of cached payloads.
+   */
+  getCount(): Promise<number>;
+}