@dhis2/app-service-offline 3.17.0 → 3.17.1

package/src/lib/dhis2-connection-status/dhis2-connection-status.tsx

@@ -0,0 +1,241 @@
+import { useConfig } from '@dhis2/app-service-config'
+import { throttle } from 'lodash'
+import PropTypes from 'prop-types'
+import React, {
+    useCallback,
+    useState,
+    useRef,
+    useMemo,
+    useEffect,
+    useContext,
+} from 'react'
+import { useOfflineInterface } from '../offline-interface'
+import { devDebugLog } from './dev-debug-log'
+import { isPingAvailable } from './is-ping-available'
+import createSmartInterval, { SmartInterval } from './smart-interval'
+import { usePingQuery } from './use-ping-query'
+
+// Utils for saving 'last connected' datetime in local storage
+const lastConnectedKey = 'dhis2.lastConnected'
+type AppName = string | undefined
+export const getLastConnectedKey = (appName?: AppName) =>
+    appName ? `${lastConnectedKey}.${appName}` : lastConnectedKey
+const updateLastConnected = (appName: AppName) => {
+    // use Date.now() because it's easier to mock for easier unit testing
+    const now = new Date(Date.now())
+    localStorage.setItem(getLastConnectedKey(appName), now.toUTCString())
+    return now
+}
+const getLastConnected = (appName: AppName) => {
+    const lastConnected = localStorage.getItem(getLastConnectedKey(appName))
+    return lastConnected ? new Date(lastConnected) : null
+}
+const clearLastConnected = (appName: AppName) => {
+    localStorage.removeItem(getLastConnectedKey(appName))
+}
+
+export interface Dhis2ConnectionStatus {
+    isConnected: boolean
+    isDisconnected: boolean
+    lastConnected: Date | null
+}
+
+const Dhis2ConnectionStatusContext = React.createContext({
+    isConnected: true,
+    isDisconnected: false,
+    lastConnected: null,
+} as Dhis2ConnectionStatus)
+
+/**
+ * Provides a boolean indicating client's connection to the DHIS2 server,
+ * which is different from connection to the internet.
+ *
+ * The context provider subscribes to messages from the SW tracking successes
+ * and failures of requests to the DHIS2 server to determine connection status,
+ * and then will initiate periodic pings if there are no incidental requests in
+ * order to check the connection consistently
+ */
+export const Dhis2ConnectionStatusProvider = ({
+    children,
+}: {
+    children: React.ReactNode
+}): JSX.Element => {
+    const offlineInterface = useOfflineInterface()
+    const { appName, serverVersion } = useConfig()
+    // The offline interface persists the latest update from the SW so that
+    // this hook can initialize to an accurate value. The App Adapter in the
+    // platform waits for this value to be populated before rendering the
+    // the App Runtime provider (including this), but if that is not done,
+    // `latestIsConnected` may be `null` depending on the outcome of race
+    // conditions between the SW and the React component tree.
+    const [isConnected, setIsConnected] = useState(
+        offlineInterface.latestIsConnected
+    )
+    const ping = usePingQuery()
+    const smartIntervalRef = useRef(null as null | SmartInterval)
+
+    /**
+     * Update state, reset ping backoff if changed, and update
+     * the lastConnected value in localStorage
+     */
+    const updateConnectedState = useCallback(
+        (newIsConnected: boolean | null) => {
+            // use 'set' with a function as param to get latest isConnected
+            // without needing it as a dependency for useCallback
+            setIsConnected((prevIsConnected) => {
+                devDebugLog('[D2CS] updating state:', {
+                    prevIsConnected,
+                    newIsConnected,
+                })
+
+                if (newIsConnected !== prevIsConnected) {
+                    // if value changed, reset ping interval to initial delay
+                    smartIntervalRef.current?.reset()
+
+                    if (newIsConnected) {
+                        // Need to clear this here so it doesn't affect another
+                        // session that starts while offline
+                        clearLastConnected(appName)
+                    } else {
+                        updateLastConnected(appName)
+                    }
+                }
+                return newIsConnected
+            })
+        },
+        [appName]
+    )
+
+    // Note that the SW is configured to not cache ping requests and won't
+    // trigger `handleChange` below to avoid redundant signals. This also
+    // helps to detect the connectivity status when the SW is not available
+    // for some reason (maybe private browsing, first installation, or
+    // insecure browser context)
+    const pingAndHandleStatus = useCallback(() => {
+        return ping()
+            .then(() => {
+                // Ping is successful; set 'connected'
+                updateConnectedState(true)
+            })
+            .catch((err) => {
+                console.error('Ping failed:', err.message)
+                updateConnectedState(false)
+            })
+    }, [ping, updateConnectedState])
+
+    /** Called when SW reports updates from incidental network traffic */
+    const onUpdate = useCallback(
+        ({ isConnected: newIsConnected }: { isConnected: any }) => {
+            devDebugLog('[D2CS] handling update from sw')
+
+            // Snooze ping timer to reduce pings since we know state from SW
+            smartIntervalRef.current?.snooze()
+            updateConnectedState(newIsConnected)
+        },
+        [updateConnectedState]
+    )
+
+    useEffect(() => {
+        // If the /api/ping endpoint is not available on this instance, skip
+        // pinging with the smart interval. Just use the service worker
+        if (!serverVersion || !isPingAvailable(serverVersion)) {
+            return
+        }
+
+        // Only create the smart interval once
+        const smartInterval = createSmartInterval({
+            // don't ping if window isn't focused or visible
+            initialPauseValue:
+                !document.hasFocus() || document.visibilityState !== 'visible',
+            callback: pingAndHandleStatus,
+        })
+        smartIntervalRef.current = smartInterval
+
+        const handleBlur = () => smartInterval.pause()
+        const handleFocus = () => smartInterval.resume()
+        // Pinging when going offline should be low/no-cost in both online and
+        // local servers
+        const handleOffline = () => smartInterval.invokeCallbackImmediately()
+        // Pinging when going online has a cost but improves responsiveness of
+        // the connection status -- only do it once every 15 seconds at most
+        const handleOnline = throttle(
+            () => smartInterval.invokeCallbackImmediately(),
+            15000
+        )
+
+        window.addEventListener('blur', handleBlur)
+        window.addEventListener('focus', handleFocus)
+        window.addEventListener('offline', handleOffline)
+        window.addEventListener('online', handleOnline)
+
+        return () => {
+            window.removeEventListener('blur', handleBlur)
+            window.removeEventListener('focus', handleFocus)
+            window.removeEventListener('offline', handleOffline)
+            window.removeEventListener('online', handleOnline)
+
+            // clean up smart interval and throttled function
+            smartInterval.clear()
+            handleOnline.cancel()
+        }
+    }, [pingAndHandleStatus, serverVersion])
+
+    useEffect(() => {
+        if (!offlineInterface.subscribeToDhis2ConnectionStatus) {
+            // Missing this functionality from the offline interface --
+            // use a ping on startup to get the status
+            smartIntervalRef.current?.invokeCallbackImmediately()
+            console.warn(
+                'Please upgrade to @dhis2/cli-app-scripts@>10.3.8 for full connection status features'
+            )
+            return
+        }
+
+        const unsubscribe = offlineInterface.subscribeToDhis2ConnectionStatus({
+            onUpdate,
+        })
+        return () => {
+            unsubscribe()
+        }
+    }, [offlineInterface, onUpdate])
+
+    // Memoize this value to prevent unnecessary rerenders of context provider
+    const contextValue = useMemo(() => {
+        // in the unlikely circumstance that offlineInterface.latestIsConnected
+        // is `null` or `undefined` when this initializes, fail safe by defaulting to
+        // `isConnected: true`. A ping or SW update should update the status shortly.
+        const validatedIsConnected = isConnected ?? true
+        return {
+            isConnected: validatedIsConnected,
+            isDisconnected: !validatedIsConnected,
+            lastConnected: validatedIsConnected
+                ? null
+                : // Only evaluate if disconnected, since local storage
+                  // is synchronous and disk-based.
+                  // If lastConnected is not set in localStorage though, set it.
+                  // (relevant on startup)
+                  getLastConnected(appName) || updateLastConnected(appName),
+        }
+    }, [isConnected, appName])
+
+    return (
+        <Dhis2ConnectionStatusContext.Provider value={contextValue}>
+            {children}
+        </Dhis2ConnectionStatusContext.Provider>
+    )
+}
+Dhis2ConnectionStatusProvider.propTypes = {
+    children: PropTypes.node,
+}
+
+export const useDhis2ConnectionStatus = (): Dhis2ConnectionStatus => {
+    const context = useContext(Dhis2ConnectionStatusContext)
+
+    if (!context) {
+        throw new Error(
+            'useDhis2ConnectionStatus must be used within a Dhis2ConnectionStatus provider'
+        )
+    }
+
+    return context
+}

package/src/lib/dhis2-connection-status/index.ts

@@ -0,0 +1,4 @@
+export {
+    useDhis2ConnectionStatus,
+    Dhis2ConnectionStatusProvider,
+} from './dhis2-connection-status'

package/src/lib/dhis2-connection-status/is-ping-available.test.ts

@@ -0,0 +1,32 @@
+import type { Version } from '@dhis2/app-service-config'
+import { isPingAvailable } from './is-ping-available'
+
+const fixedVersions: Version[] = [
+    { full: 'unimportant', major: 2, minor: 40, patch: 0 },
+    { full: 'unimportant', major: 2, minor: 39, patch: 2 },
+    { full: 'unimportant', major: 2, minor: 38, patch: 4 },
+    { full: 'unimportant', major: 2, minor: 37, patch: 10 },
+    { full: 'unimportant', major: 2, minor: 40, tag: 'SNAPSHOT' },
+    { full: 'unimportant', major: 2, minor: 3291, patch: 0 },
+]
+
+const unsupportedVersions: Version[] = [
+    { full: 'unimportant', major: 2, minor: 39, patch: 1 },
+    { full: 'unimportant', major: 2, minor: 38, patch: 2 },
+    { full: 'unimportant', major: 2, minor: 37, patch: 9 },
+    { full: 'unimportant', major: 2, minor: 36, patch: 12 },
+    { full: 'unimportant', major: 2, minor: 35, patch: 0 },
+    { full: 'unimportant', major: 2, minor: 0, patch: 0 },
+]
+
+test('supported server versions pass', () => {
+    fixedVersions.forEach((version) => {
+        expect(isPingAvailable(version)).toBe(true)
+    })
+})
+
+test('unsupported server versions fail', () => {
+    unsupportedVersions.forEach((version) => {
+        expect(isPingAvailable(version)).toBe(false)
+    })
+})

package/src/lib/dhis2-connection-status/is-ping-available.ts

@@ -0,0 +1,31 @@
+import type { Version } from '@dhis2/app-service-config'
+
+/**
+ * Checks the server version to see if the /api/ping endpoint is available for
+ * this version.
+ *
+ * The endpoint was released for versions 2.37.10, 2.38.4, 2.39.2, and 2.40.0
+ * (see DHIS2-14531). All versions below that are considered unsupported
+ *
+ * If the patchVersion is undefined, it's assumed to be a dev server that's
+ * newer than the fix versions listed above
+ *
+ * Major versions above 2 aren't supported 🤷‍♂️
+ */
+export function isPingAvailable(serverVersion: Version) {
+    if (!serverVersion) {
+        return false
+    }
+
+    const { minor, patch } = serverVersion
+    switch (minor) {
+        case 39:
+            return patch === undefined || patch >= 2
+        case 38:
+            return patch === undefined || patch >= 4
+        case 37:
+            return patch === undefined || patch >= 10
+        default:
+            return minor >= 40
+    }
+}

package/src/lib/dhis2-connection-status/smart-interval.ts

@@ -0,0 +1,206 @@
+import { devDebugLog } from './dev-debug-log'
+
+// Exported for tests
+export const DEFAULT_INITIAL_DELAY_MS = 1000 * 30 // 30 sec
+export const DEFAULT_MAX_DELAY_MS = 1000 * 60 * 5 // 5 min
+export const DEFAULT_INCREMENT_FACTOR = 1.5
+const throwErrorIfNoCallbackIsProvided = (): void => {
+    throw new Error('Provide a callback')
+}
+
+export interface SmartInterval {
+    clear: () => void
+    pause: () => void
+    resume: () => void
+    invokeCallbackImmediately: () => void
+    snooze: () => void
+    reset: () => void
+}
+
+export default function createSmartInterval({
+    initialDelay = DEFAULT_INITIAL_DELAY_MS,
+    maxDelay = DEFAULT_MAX_DELAY_MS,
+    delayIncrementFactor = DEFAULT_INCREMENT_FACTOR,
+    initialPauseValue = false,
+    callback = throwErrorIfNoCallbackIsProvided,
+} = {}): SmartInterval {
+    const state = {
+        paused: initialPauseValue,
+        delay: initialDelay,
+        // Timeout types are weird; this dummy timeout helps fix them:
+        // (named to help debugging in tests)
+        timeout: setTimeout(function dummyTimeout() {
+            return
+        }, 0),
+        standbyCallback: null as null | (() => void),
+    }
+
+    /** Increment delay by the increment factor, up to a max value */
+    function incrementDelay() {
+        const newDelay = Math.min(state.delay * delayIncrementFactor, maxDelay)
+        devDebugLog('[SI] incrementing delay', {
+            prev: state.delay,
+            new: newDelay,
+        })
+        state.delay = newDelay
+    }
+
+    function invokeCallbackAndHandleDelay(): void {
+        // Increment delay before calling callback, so callback can potentially
+        // reset the delay to initial before starting the next timeout
+        incrementDelay()
+        callback()
+    }
+
+    function clearTimeoutAndStart(): void {
+        devDebugLog('[SI] clearing and starting timeout', {
+            delay: state.delay,
+        })
+
+        // Prevent parallel timeouts from occuring
+        // (weird note: `if (this.timeout) { clearTimeout(this.timeout) }`
+        // does NOT work for some reason)
+        clearTimeout(state.timeout)
+
+        // A timeout is used instead of an interval for handling slow execution
+        // https://developer.mozilla.org/en-US/docs/Web/API/setInterval#ensure_that_execution_duration_is_shorter_than_interval_frequency
+        state.timeout = setTimeout(function callbackAndRestart() {
+            if (state.paused) {
+                devDebugLog('[SI] entering regular standby')
+
+                // If paused, prepare a 'standby callback' to be invoked when
+                // `resume()` is called (see its definition below).
+                // The timer will not be started again until the standbyCallback
+                // is invoked.
+                state.standbyCallback = () => {
+                    invokeCallbackAndHandleDelay()
+                    clearTimeoutAndStart()
+                }
+
+                return
+            }
+
+            // Otherwise, invoke callback
+            invokeCallbackAndHandleDelay()
+            // and start process over again
+            clearTimeoutAndStart()
+        }, state.delay)
+    }
+
+    /** Stop the interval. Used for cleaning up */
+    function clear(): void {
+        clearTimeout(state.timeout)
+    }
+
+    /**
+     * Invoke the provided callback immediately and start the timer over.
+     * The timeout to the next invocation will not be increased
+     * (unless the timer fully elapses while this interval is paused).
+     *
+     * If the interval is 'paused', it will not invoke the callback immediately,
+     * but enter a 'partial standby', which will invoke the callback upon
+     * resuming, but without incrementing the delay. If the regular timeout
+     * elapses while paused, the regular standby is entered, overwriting this
+     * partial standby.
+     */
+    function invokeCallbackImmediately(): void {
+        if (state.paused) {
+            if (state.standbyCallback === null) {
+                // If there is not an existing standbyCallback,
+                // set one to be called upon `resume()`
+                // (but don't overwrite a previous callback).
+                // See setTimeout call above too.
+                // The timed out function set in `clearTimeoutAndStart` may
+                // overwrite this callback if the timer elapses, so that the
+                // timeout delay gets incremented appropriately.
+                devDebugLog('[SI] entering standby without timer increment')
+
+                state.standbyCallback = () => {
+                    // Invoke callback and start timer without incrementing
+                    callback()
+                    clearTimeoutAndStart()
+                }
+            }
+
+            // Skip rest of execution while paused
+            return
+        }
+
+        // Invoke callback and start timer without incrementing
+        callback()
+        clearTimeoutAndStart()
+    }
+
+    /**
+     * Sets a 'paused' flag (doesn't yet stop the timer):
+     *
+     * If the main timer elapses or `invokeCallbackImmediately` is called
+     * while the interval is paused, the timer will not be started again.
+     * Instead, a callback function will be saved that will be called when
+     * `resume()` is called (see its definition below)
+     *
+     * This decreases execution activity while 'paused'
+     */
+    function pause(): void {
+        devDebugLog('[SI] pausing')
+
+        state.paused = true
+    }
+
+    /**
+     * Removes 'paused' state
+     *
+     * If the interval is in 'standby', trigger the saved 'standbyCallback',
+     * which should start the interval timer again
+     */
+    function resume(): void {
+        devDebugLog('[SI] resuming', { standbyCb: state.standbyCallback })
+
+        // Clear paused state
+        state.paused = false
+
+        // If in standby, invoke the saved callback
+        // (invokeCallbackImmediately and clearTimeoutAndStart can set a
+        // standby callback)
+        if (state.standbyCallback !== null) {
+            state.standbyCallback()
+            // Remove existing standbyCallback
+            state.standbyCallback = null
+        }
+    }
+
+    /**
+     * Restart the timer to the next callback invocation, using the current
+     * delay
+     *
+     * Expected to be called to delay a ping in response to incidental network
+     * traffic, for example
+     */
+    function snooze(): void {
+        devDebugLog('[SI] snoozing timeout')
+
+        clearTimeoutAndStart()
+    }
+
+    /**
+     * Cancels the current timeout and starts a new one with the initial delay
+     */
+    function reset(): void {
+        devDebugLog('[SI] resetting interval from beginning')
+
+        state.delay = initialDelay
+        clearTimeoutAndStart()
+    }
+
+    // Start the timer!
+    clearTimeoutAndStart()
+
+    return {
+        clear,
+        pause,
+        resume,
+        invokeCallbackImmediately,
+        snooze,
+        reset,
+    }
+}

package/src/lib/dhis2-connection-status/use-ping-query.ts

@@ -0,0 +1,14 @@
+import { useConfig } from '@dhis2/app-service-config'
+import { useCallback } from 'react'
+
+// This function has a separate file for easier mocking
+
+export function usePingQuery(): () => Promise<any> {
+    const { baseUrl } = useConfig()
+
+    // This endpoint doesn't need any extra headers or handling since it's
+    // public. It doesn't extend the user session. See DHIS2-14531
+    const ping = useCallback(() => fetch(baseUrl + '/api/ping'), [baseUrl])
+
+    return ping
+}

package/src/lib/global-state-service.tsx

@@ -0,0 +1,110 @@
+import isEqual from 'lodash/isEqual'
+import PropTypes from 'prop-types'
+import React, {
+    useEffect,
+    useCallback,
+    useContext,
+    useState,
+    useMemo,
+} from 'react'
+import {
+    GlobalStateStore,
+    GlobalStateStoreMutateMethod,
+    GlobalStateMutation,
+    GlobalStateStoreMutationCreator,
+} from '../types'
+
+// This file creates a redux-like state management service using React context
+// that minimizes unnecessary rerenders that consume the context.
+// See more at https://github.com/amcgee/state-service-poc
+
+const identity = (state: any) => state
+
+export const createStore = (initialState = {}): GlobalStateStore => {
+    const subscriptions: Set<(state: any) => void> = new Set()
+    let state = initialState
+
+    return {
+        getState: () => state,
+        subscribe: (callback) => {
+            subscriptions.add(callback)
+        },
+        unsubscribe: (callback) => {
+            subscriptions.delete(callback)
+        },
+        mutate: (mutation) => {
+            state = mutation(state)
+            for (const callback of subscriptions) {
+                callback(state)
+            }
+        },
+    }
+}
+
+const GlobalStateContext = React.createContext(createStore())
+const useGlobalStateStore = () => useContext(GlobalStateContext)
+
+export const GlobalStateProvider = ({
+    store,
+    children,
+}: {
+    store: GlobalStateStore
+    children: React.ReactNode
+}): JSX.Element => (
+    <GlobalStateContext.Provider value={store}>
+        {children}
+    </GlobalStateContext.Provider>
+)
+GlobalStateProvider.propTypes = {
+    children: PropTypes.node,
+    store: PropTypes.shape({}),
+}
+
+export const useGlobalState = (
+    selector = identity
+): [any, GlobalStateStoreMutateMethod] => {
+    const store = useGlobalStateStore()
+    const [selectedState, setSelectedState] = useState(
+        selector(store.getState())
+    )
+
+    useEffect(() => {
+        // NEW: deep equality check before updating
+        const callback = (state: any) => {
+            const newSelectedState = selector(state)
+            // Use this form to avoid having `selectedState` as a dep in here
+            setSelectedState((currentSelectedState: any) => {
+                // Second condition handles case where a selected object gets
+                // deleted, but state does not update
+                if (
+                    !isEqual(currentSelectedState, newSelectedState) ||
+                    currentSelectedState === undefined
+                ) {
+                    return newSelectedState
+                }
+                return currentSelectedState
+            })
+        }
+        store.subscribe(callback)
+        // Make sure to update state when selector changes
+        callback(store.getState())
+        return () => store.unsubscribe(callback)
+    }, [store, selector])
+
+    return useMemo(
+        () => [selectedState, store.mutate],
+        [selectedState, store.mutate]
+    )
+}
+
+export function useGlobalStateMutation<Type>(
+    mutationCreator: GlobalStateStoreMutationCreator<Type>
+): GlobalStateMutation<Type> {
+    const store = useGlobalStateStore()
+    return useCallback(
+        (...args) => {
+            store.mutate(mutationCreator(...args))
+        },
+        [mutationCreator, store]
+    )
+}