@dhis2/app-service-offline 3.17.0-beta.4 → 3.17.1

package/src/lib/cacheable-section.tsx

@@ -0,0 +1,193 @@
+import PropTypes from 'prop-types'
+import React, { useCallback, useEffect, useMemo } from 'react'
+import { flushSync } from 'react-dom'
+import { RecordingState } from '../types'
+import { useRecordingState, useCachedSection } from './cacheable-section-state'
+import { useOfflineInterface } from './offline-interface'
+
+const recordingStates: { [index: string]: RecordingState } = {
+    default: 'default',
+    pending: 'pending',
+    recording: 'recording',
+    error: 'error',
+}
+
+interface CacheableSectionStartRecordingOptions {
+    recordingTimeoutDelay?: number
+    onStarted?: () => void
+    onCompleted?: () => void
+    onError?: (err: Error) => void
+}
+
+export type CacheableSectionStartRecording = (
+    options?: CacheableSectionStartRecordingOptions
+) => Promise<any>
+
+interface CacheableSectionControls {
+    recordingState: RecordingState
+    startRecording: CacheableSectionStartRecording
+    lastUpdated: Date | undefined
+    isCached: boolean
+    remove: () => Promise<boolean>
+}
+
+/**
+ * Returns the main controls for a cacheable section and manages recording
+ * state, which affects the render state of the CacheableSection component.
+ * Also returns the cached status of the section, which come straight from
+ * the `useCachedSection` hook.
+ *
+ * @param {String} id
+ * @returns {Object}
+ */
+export function useCacheableSection(id: string): CacheableSectionControls {
+    const offlineInterface = useOfflineInterface()
+    const { isCached, lastUpdated, remove, syncCachedSections } =
+        useCachedSection(id)
+    const { recordingState, setRecordingState, removeRecordingState } =
+        useRecordingState(id)
+
+    useEffect(() => {
+        // On mount, add recording state for this ID to context if needed
+        if (!recordingState) {
+            setRecordingState(recordingStates.default)
+        }
+        // On unnmount, remove recording state if not recording
+        return () => {
+            if (
+                recordingState &&
+                recordingState !== recordingStates.recording &&
+                recordingState !== recordingStates.pending
+            ) {
+                removeRecordingState()
+            }
+        }
+    }, []) // eslint-disable-line react-hooks/exhaustive-deps
+
+    const onRecordingStarted = useCallback(() => {
+        setRecordingState(recordingStates.recording)
+    }, [setRecordingState])
+
+    const onRecordingCompleted = useCallback(() => {
+        setRecordingState(recordingStates.default)
+        syncCachedSections()
+    }, [setRecordingState, syncCachedSections])
+
+    const onRecordingError = useCallback(
+        (error: Error) => {
+            console.error('Error during recording:', error)
+            setRecordingState(recordingStates.error)
+        },
+        [setRecordingState]
+    )
+
+    const startRecording = useCallback(
+        ({
+            recordingTimeoutDelay = 1000,
+            onStarted,
+            onCompleted,
+            onError,
+        }: CacheableSectionStartRecordingOptions = {}) => {
+            // This promise resolving means that the message to the service worker
+            // to start recording was successful. Waiting for resolution prevents
+            // unnecessarily rerendering the whole component in case of an error
+            return offlineInterface
+                .startRecording({
+                    sectionId: id,
+                    recordingTimeoutDelay,
+                    onStarted: () => {
+                        // Flush this state update synchronously so that the
+                        // right recordingState is set before any other callbacks
+                        flushSync(() => {
+                            onRecordingStarted()
+                        })
+                        onStarted?.()
+                    },
+                    onCompleted: () => {
+                        flushSync(() => {
+                            onRecordingCompleted()
+                        })
+                        onCompleted?.()
+                    },
+                    onError: (error) => {
+                        flushSync(() => {
+                            onRecordingError(error)
+                        })
+                        onError?.(error)
+                    },
+                })
+                .then(() => setRecordingState(recordingStates.pending))
+        },
+        [
+            id,
+            offlineInterface,
+            onRecordingCompleted,
+            onRecordingError,
+            onRecordingStarted,
+            setRecordingState,
+        ]
+    )
+
+    // isCached, lastUpdated, remove: _could_ be accessed by useCachedSection,
+    // but provided through this hook for convenience
+    return useMemo(
+        () => ({
+            recordingState,
+            startRecording,
+            lastUpdated,
+            isCached,
+            remove,
+        }),
+        [recordingState, startRecording, lastUpdated, isCached, remove]
+    )
+}
+
+interface CacheableSectionProps {
+    id: string
+    loadingMask: JSX.Element
+    children: React.ReactNode
+}
+
+/**
+ * Used to wrap the relevant component to be recorded and saved offline.
+ * Depending on the recording state of the section, this wrapper will
+ * render its children, not render its children while recording is pending,
+ * or RErerender the chilren to force data fetching to record by the service
+ * worker.
+ *
+ * During recording, a loading mask provided by props is also rendered that is
+ * intended to prevent other interaction with the app that might interfere
+ * with the recording process.
+ */
+export function CacheableSection({
+    id,
+    loadingMask,
+    children,
+}: CacheableSectionProps): JSX.Element {
+    // Accesses recording state that useCacheableSection controls
+    const { recordingState } = useRecordingState(id)
+
+    // The following causes the component to reload in the event of a recording
+    // error; the state will be cleared next time recording moves to pending.
+    // It fixes a component getting stuck while rendered without data after
+    // failing a recording while offline.
+    // Errors can be handled in the `onError` callback to `startRecording`.
+    if (recordingState === recordingStates.error) {
+        return <>{children}</>
+    }
+
+    // Handling rendering with the following conditions prevents an unncessary
+    // rerender after successful recording
+    return (
+        <>
+            {recordingState === recordingStates.recording && loadingMask}
+            {recordingState !== recordingStates.pending && children}
+        </>
+    )
+}
+
+CacheableSection.propTypes = {
+    id: PropTypes.string.isRequired,
+    children: PropTypes.node,
+    loadingMask: PropTypes.node,
+}

package/src/lib/clear-sensitive-caches.ts

@@ -0,0 +1,92 @@
+// IndexedDB names; should be the same as in @dhis2/pwa
+export const SECTIONS_DB = 'sections-db'
+export const SECTIONS_STORE = 'sections-store'
+
+// Non-sensitive caches that can be kept:
+const KEEPABLE_CACHES = [
+    /^workbox-precache/, // precached static assets
+]
+
+declare global {
+    interface IDBFactory {
+        databases(): Promise<[{ name: string; version: number }]>
+    }
+}
+
+/*
+ * Clears the 'sections-db' IndexedDB if it exists. Designed to avoid opening
+ * a new DB if it doesn't exist yet. Firefox can't check if 'sections-db'
+ * exists, in which circumstance the IndexedDB is unaffected. It's inelegant
+ * but acceptable because the IndexedDB has no sensitive data (only metadata
+ * of recorded sections), and the OfflineInterface handles discrepancies
+ * between CacheStorage and IndexedDB.
+ */
+const clearDB = async (dbName: string): Promise<void> => {
+    if (!('databases' in indexedDB)) {
+        // FF does not have indexedDB.databases. For that, just clear caches,
+        // and offline interface will handle discrepancies in PWA apps.
+        return
+    }
+
+    const dbs = await window.indexedDB.databases()
+    if (!dbs.some(({ name }) => name === dbName)) {
+        // Sections-db is not created; nothing to do here
+        return
+    }
+
+    return new Promise((resolve, reject) => {
+        // IndexedDB fun:
+        const openDBRequest = indexedDB.open(dbName)
+        openDBRequest.onsuccess = (e) => {
+            const db = (e.target as IDBOpenDBRequest).result
+            const tx = db.transaction(SECTIONS_STORE, 'readwrite')
+            // When the transaction completes is when the operation is done:
+            tx.oncomplete = () => resolve()
+            tx.onerror = (e) => reject((e.target as IDBRequest).error)
+            const os = tx.objectStore(SECTIONS_STORE)
+            const clearReq = os.clear()
+            clearReq.onerror = (e) => reject((e.target as IDBRequest).error)
+        }
+        openDBRequest.onerror = (e) => {
+            reject((e.target as IDBOpenDBRequest).error)
+        }
+    })
+}
+
+/**
+ * Used to clear caches and 'sections-db' IndexedDB when a user logs out or a
+ * different user logs in to prevent someone from accessing a different user's
+ * caches. Should be able to be used in a non-PWA app.
+ */
+export async function clearSensitiveCaches(
+    dbName: string = SECTIONS_DB
+): Promise<any> {
+    console.debug('Clearing sensitive caches')
+    let cacheKeys
+
+    // caches.keys can fail in insecure contexts, see:
+    // https://developer.mozilla.org/en-US/docs/Web/API/CacheStorage
+    try {
+        cacheKeys = await caches.keys()
+    } catch (e) {
+        // Return false since no caches have been cleared
+        return false
+    }
+
+    return Promise.all([
+        // (Resolves to 'false' because this can't detect if anything was deleted):
+        clearDB(dbName).then(() => false),
+        // Remove caches if not in keepable list
+        ...cacheKeys.map((key) => {
+            if (!KEEPABLE_CACHES.some((pattern) => pattern.test(key))) {
+                return caches.delete(key)
+            }
+            return false
+        }),
+    ]).then((responses) => {
+        // Return true if any caches have been cleared
+        // (caches.delete() returns true if a cache is deleted successfully)
+        // PWA apps can reload to restore their app shell cache
+        return responses.some((response) => response)
+    })
+}

package/src/lib/dhis2-connection-status/dev-debug-log.ts

@@ -0,0 +1,20 @@
+const shouldLog = localStorage.getItem('dhis2.debugConnectionStatus')
+if (shouldLog) {
+    console.log(
+        'Logging for dhis2ConnectionStatus is enabled. Remove the `dhis2.debugConnectionStatus` item in localStorage to disable logging.'
+    )
+}
+
+/**
+ * This can be used to log info if the `dhis2.debugConnectionStatus` value
+ * in localStorage is set to a truthy value during development.
+ * Set the value manually and refresh the page to see the logs.
+ *
+ * The behavior of the connection status can be quite hard to inspect without
+ * logs, but the logs are quite chatty and should be omitted normally.
+ */
+export function devDebugLog(...args: any[]) {
+    if (shouldLog) {
+        console.log(...args)
+    }
+}