@applicaster/quick-brick-core 16.0.0-rc.99 → 17.0.0-alpha.1984136194

package/App/NetworkStatusProvider/NetworkStatusProvider.tsx

@@ -13,6 +13,12 @@ import {
 } from "./utils";
 import { usePrevious } from "@applicaster/zapp-react-native-utils/reactHooks/utils";
 
+import { useResumeVerifiedNetInfo } from "./useResumeVerifiedNetInfo";
+import { describeNetInfo } from "./resumeVerification";
+import { subsystemLogger } from "@applicaster/zapp-react-native-utils/logger";
+
+const logger = subsystemLogger("network/reachability", "NetworkStatusProvider");
+
 // Use default netInfo config for all platforms (important for web platform which otherwise
 // will use backend root which is not responding for HEAD request)
 if (["web", "lg_tv", "samsung_tv"].includes(Platform.OS)) {
@@ -36,10 +42,30 @@ export const NetworkStatusProvider = ({
   // NetInfo library does not have accurate information for Tizen SmartTVs, and possibly WebOS
   // This combined info helps us gather data from the native connection status APIs
   // and includes it in our definition of... online.
-  const combinedNetInfo: NetInfoState & { deviceStatus?: NetStatus } = {
-    ...currentNetInfo,
-    deviceStatus,
-  };
+  // stable reference between real changes: every new reference is a network update
+  const liveNetInfo = React.useMemo<
+    NetInfoState & { deviceStatus?: NetStatus }
+  >(
+    () => ({ ...currentNetInfo, deviceStatus }),
+    [currentNetInfo, deviceStatus]
+  );
+
+  // NetInfo reports stale offline status right after resume/unlock (iOS),
+  // publish the network status verified after the app returns to foreground
+  const { netInfo: verifiedNetInfo, stillOfflineAfterResumeCount } =
+    useResumeVerifiedNetInfo(liveNetInfo);
+
+  // Memoized so consumers only re-render when the published status changes,
+  // not on every render of this provider
+  const combinedNetInfo = React.useMemo<
+    NetInfoState & {
+      deviceStatus?: NetStatus;
+      stillOfflineAfterResumeCount: number;
+    }
+  >(
+    () => ({ ...verifiedNetInfo, stillOfflineAfterResumeCount }),
+    [verifiedNetInfo, stillOfflineAfterResumeCount]
+  );
 
   const { onConnectionTypeChanged, onConnectionLost, onConnectionRestored } =
     React.useMemo<NetworkHooks>(() => getNetworkHooks(plugins), []);
@@ -57,6 +83,16 @@ export const NetworkStatusProvider = ({
     if (!combinedNetInfo.details) return;
 
     if (previousOnline !== undefined && previousOnline !== online) {
+      logger.info({
+        message: "NetworkStatus: online status changed",
+        data: {
+          online,
+          previousOnline,
+          published: describeNetInfo(combinedNetInfo),
+          live: describeNetInfo(liveNetInfo),
+        },
+      });
+
       online
         ? onConnectionRestored &&
           callAllWith(onConnectionRestored, combinedNetInfo)

package/App/NetworkStatusProvider/ResumeVerificationController.ts

@@ -0,0 +1,282 @@
+import { AppState, AppStateStatus } from "react-native";
+import { NetInfoState } from "@react-native-community/netinfo";
+
+import { isOnline } from "./utils";
+import {
+  RESUME_VERIFICATION_DELAY_MS,
+  describeNetInfo,
+  getResumeDecision,
+  isBackgroundAppState,
+  isResumeVerificationEnabled,
+} from "./resumeVerification";
+import { subsystemLogger } from "@applicaster/zapp-react-native-utils/logger";
+
+const logger = subsystemLogger("network/reachability", "NetworkStatusProvider");
+
+export type ConnectionInfo = NetInfoState & { deviceStatus?: NetStatus };
+
+export type ResumeVerifiedState<T extends ConnectionInfo> = {
+  netInfo: T;
+  stillOfflineAfterResumeCount: number;
+};
+
+type Phase = "live" | "frozen" | "verifying";
+
+/**
+ * Holds the published network status while the app is in background and for
+ * RESUME_VERIFICATION_DELAY_MS after it becomes active again, then publishes the
+ * current state. Works around stale iOS NetInfo reachability failures on resume/unlock.
+ *
+ * start()/stop() manage the AppState subscription and timer (useLayoutEffect),
+ * setNetInfo() feeds live NetInfo, subscribe()/getState() back useSyncExternalStore.
+ */
+export class ResumeVerificationController<T extends ConnectionInfo> {
+  private phase: Phase = "live";
+  private appState: AppStateStatus;
+  private live: T;
+  private state: ResumeVerifiedState<T>;
+  private listeners = new Set<() => void>();
+  private subscription: { remove: () => void } | null = null;
+  private timer: ReturnType<typeof setTimeout> | null = null;
+
+  /**
+   * @param initialNetInfo - live NetInfo at mount, published as the initial state.
+   * Starts "frozen" when the app is created in background (e.g. iOS background launch).
+   */
+  constructor(initialNetInfo: T) {
+    this.appState = AppState.currentState;
+    this.live = initialNetInfo;
+    this.state = { netInfo: initialNetInfo, stillOfflineAfterResumeCount: 0 };
+
+    if (isResumeVerificationEnabled() && isBackgroundAppState(this.appState)) {
+      this.phase = "frozen";
+    }
+
+    this.subscribe = this.subscribe.bind(this);
+    this.getState = this.getState.bind(this);
+    this.applyAppState = this.applyAppState.bind(this);
+  }
+
+  /**
+   * useSyncExternalStore subscribe: listener is called whenever getState() changes.
+   * @param listener - called with no arguments after each publish
+   * @returns unsubscribe function
+   */
+  subscribe(listener: () => void): () => void {
+    this.listeners.add(listener);
+
+    return () => {
+      this.listeners.delete(listener);
+    };
+  }
+
+  /**
+   * useSyncExternalStore snapshot: same reference until a new state is published.
+   * @returns the verified network status and the still-offline-after-resume counter
+   */
+  getState(): ResumeVerifiedState<T> {
+    return this.state;
+  }
+
+  /**
+   * Subscribes to AppState changes and catches up with the current app state.
+   * Idempotent; no-op on platforms without resume verification (web, TV).
+   * Call from useLayoutEffect, paired with stop().
+   */
+  start(): void {
+    if (!isResumeVerificationEnabled() || this.subscription) return;
+
+    this.subscription = AppState.addEventListener("change", this.applyAppState);
+
+    // AppState may have changed since construction (e.g. initial "background"
+    // corrected to "active"), or stop() interrupted a window: catch up
+    this.applyAppState(AppState.currentState);
+  }
+
+  /**
+   * Removes the AppState subscription and cancels a pending verification.
+   * An interrupted window falls back to "frozen" and restarts on the next start() while active.
+   */
+  stop(): void {
+    this.subscription?.remove();
+    this.subscription = null;
+    this.clearTimer();
+
+    // an interrupted window is restarted by the next start() while active
+    if (this.phase === "verifying") {
+      this.phase = "frozen";
+    }
+  }
+
+  /**
+   * Feeds the latest live NetInfo. Published immediately while "live",
+   * held (and logged as ignored) while "frozen" or "verifying".
+   * @param netInfo - live NetInfo; the same reference is a no-op
+   */
+  setNetInfo(netInfo: T): void {
+    if (netInfo === this.live) return;
+
+    this.live = netInfo;
+
+    if (this.phase === "live") {
+      this.publish(netInfo);
+
+      return;
+    }
+
+    logger.info({
+      message: "NetworkStatus: network change ignored until verified",
+      data: {
+        appState: this.appState,
+        phase: this.phase,
+        published: describeNetInfo(this.state.netInfo),
+        live: describeNetInfo(netInfo),
+      },
+    });
+  }
+
+  /**
+   * AppState change handler: "background" freezes, "active" after a freeze starts verification,
+   * anything else ("inactive", "unknown") keeps the current phase.
+   * @param nextAppState - new AppState value
+   */
+  private applyAppState(nextAppState: AppStateStatus): void {
+    const previousAppState = this.appState;
+    const nextPhase = this.getNextPhase(nextAppState);
+    this.appState = nextAppState;
+
+    if (previousAppState === nextAppState && nextPhase === this.phase) return;
+
+    logger.info({
+      message: "NetworkStatus: app state changed",
+      data: {
+        appState: nextAppState,
+        previousAppState,
+        phase: this.phase,
+        nextPhase,
+        published: describeNetInfo(this.state.netInfo),
+        live: describeNetInfo(this.live),
+      },
+    });
+
+    if (nextPhase === "frozen" && this.phase !== "frozen") {
+      this.freeze();
+    } else if (nextPhase === "verifying" && this.phase === "frozen") {
+      this.startVerification();
+    }
+  }
+
+  /**
+   * @param appState - new AppState value
+   * @returns the phase the controller moves to for this app state
+   */
+  private getNextPhase(appState: AppStateStatus): Phase {
+    if (isBackgroundAppState(appState)) return "frozen";
+
+    if (appState === "active" && this.phase === "frozen") return "verifying";
+
+    return this.phase;
+  }
+
+  /**
+   * Stops publishing live changes; cancels a running verification window.
+   */
+  private freeze(): void {
+    if (this.phase === "verifying") {
+      this.clearTimer();
+
+      logger.info({
+        message: "NetworkStatus: resume verification cancelled",
+        data: {
+          appState: this.appState,
+          snapshot: describeNetInfo(this.state.netInfo),
+          live: describeNetInfo(this.live),
+        },
+      });
+    }
+
+    this.phase = "frozen";
+  }
+
+  /**
+   * Opens the RESUME_VERIFICATION_DELAY_MS window. When it ends, compares the state published
+   * before background with the current live state, publishes the live state and bumps
+   * stillOfflineAfterResumeCount when the app is still offline.
+   */
+  private startVerification(): void {
+    this.phase = "verifying";
+
+    const snapshot = this.state.netInfo;
+    const startedAt = Date.now();
+
+    logger.info({
+      message: "NetworkStatus: resume verification started",
+      data: {
+        delayMs: RESUME_VERIFICATION_DELAY_MS,
+        appState: this.appState,
+        snapshot: describeNetInfo(snapshot),
+        live: describeNetInfo(this.live),
+      },
+    });
+
+    this.timer = setTimeout(() => {
+      this.timer = null;
+
+      if (this.phase !== "verifying") return;
+
+      const decision = getResumeDecision(
+        isOnline(snapshot) === true,
+        isOnline(this.live) === true
+      );
+
+      logger.info({
+        message: "NetworkStatus: resume verification finished",
+        data: {
+          decision,
+          elapsedMs: Date.now() - startedAt,
+          appState: this.appState,
+          snapshot: describeNetInfo(snapshot),
+          live: describeNetInfo(this.live),
+        },
+      });
+
+      this.phase = "live";
+
+      this.publish(
+        this.live,
+        this.state.stillOfflineAfterResumeCount +
+          (decision === "still_offline" ? 1 : 0)
+      );
+    }, RESUME_VERIFICATION_DELAY_MS);
+  }
+
+  /**
+   * Cancels the pending verification timer, if any.
+   */
+  private clearTimer(): void {
+    if (this.timer !== null) {
+      clearTimeout(this.timer);
+      this.timer = null;
+    }
+  }
+
+  /**
+   * Replaces the snapshot and notifies subscribers; no-op when nothing changed.
+   * @param netInfo - NetInfo to publish
+   * @param stillOfflineAfterResumeCount - counter to publish, defaults to the current one
+   */
+  private publish(
+    netInfo: T,
+    stillOfflineAfterResumeCount = this.state.stillOfflineAfterResumeCount
+  ): void {
+    if (
+      netInfo === this.state.netInfo &&
+      stillOfflineAfterResumeCount === this.state.stillOfflineAfterResumeCount
+    ) {
+      return;
+    }
+
+    this.state = { netInfo, stillOfflineAfterResumeCount };
+    this.listeners.forEach((listener) => listener());
+  }
+}

package/App/NetworkStatusProvider/__tests__/NetworkStatusProvider.test.tsx

@@ -5,6 +5,69 @@ import { NetworkStatusContext } from "@applicaster/zapp-react-native-ui-componen
 import { NetworkStatusProvider } from "../NetworkStatusProvider";
 import { WrappedWithProviders } from "@applicaster/zapp-react-native-utils/testUtils";
 import NetInfo from "@react-native-community/netinfo";
+import { AppState } from "react-native";
+import { RESUME_VERIFICATION_DELAY_MS } from "../resumeVerification";
+
+const mockLogger = {
+  warning: jest.fn(),
+  debug: jest.fn(),
+  info: jest.fn(),
+  log: jest.fn(),
+  error: jest.fn(),
+};
+
+// subsystemLogger runs at module load, before mockLogger is initialised: delegate lazily
+jest.mock("@applicaster/zapp-react-native-utils/logger", () => {
+  const actual = jest.requireActual(
+    "@applicaster/zapp-react-native-utils/logger"
+  );
+
+  return {
+    ...actual,
+    // Only the logger of this subsystem is replaced; every other module keeps its real one.
+    subsystemLogger: (subsystem: string) => {
+      if (subsystem !== "network/reachability") {
+        return actual.subsystemLogger(subsystem);
+      }
+
+      const logger = {
+        warning: (event) => mockLogger.warning(event),
+        debug: (event) => mockLogger.debug(event),
+        info: (event) => mockLogger.info(event),
+        log: (event) => mockLogger.log(event),
+        error: (event) => mockLogger.error(event),
+        addSubsystem: () => logger,
+      };
+
+      return logger;
+    },
+  };
+});
+
+jest.mock("react-native/Libraries/AppState/AppState", () => {
+  const { EventEmitter } = require("events");
+  const emitter = new EventEmitter();
+
+  return {
+    emitter,
+    currentState: "active",
+    addEventListener: (type, handler) => {
+      emitter.addListener(type, handler);
+
+      return { remove: () => emitter.removeListener(type, handler) };
+    },
+  };
+});
+
+const mockAppState = AppState as any;
+
+const changeAppState = (state: string) =>
+  act(() => {
+    mockAppState.currentState = state;
+    mockAppState.emitter.emit("change", state);
+  });
+
+const OFFLINE_PATCH = { isConnected: false, isInternetReachable: false };
 
 const NetInfoMock = {
   type: "cellular",
@@ -49,7 +112,10 @@ describe("NetworkStatusProvider", function () {
       getWrapper(store)
     );
 
-    expect(result.current).toStrictEqual(NetInfoMock);
+    expect(result.current).toStrictEqual({
+      ...NetInfoMock,
+      stillOfflineAfterResumeCount: 0,
+    });
   });
 
   it("should call onConnectionLost callback when connection type changes to none", async function () {
@@ -135,3 +201,103 @@ describe("NetworkStatusProvider", function () {
     expect(onConnectionTypeChanged).toBeCalledWith("wifi");
   });
 });
+
+describe("NetworkStatusProvider – app resume", () => {
+  beforeEach(() => {
+    jest.useFakeTimers();
+    mockAppState.currentState = "active";
+    mockAppState.emitter.removeAllListeners();
+    // @ts-ignore
+    jest.spyOn(NetInfo, "useNetInfo").mockImplementation(useNetInfoMock);
+  });
+
+  afterEach(() => {
+    jest.useRealTimers();
+  });
+
+  it("does not call onConnectionLost/Restored for a reachability blip right after resume", () => {
+    const onConnectionLost = jest.fn();
+    const onConnectionRestored = jest.fn();
+
+    const store = {
+      plugins: [
+        {
+          module: { networkHooks: { onConnectionLost, onConnectionRestored } },
+        },
+      ],
+    };
+
+    renderHook(() => React.useContext(NetworkStatusContext), getWrapper(store));
+
+    changeAppState("background");
+    changeAppState("active");
+
+    act(() => setNetInfoState(R.mergeRight(NetInfoMock, OFFLINE_PATCH)));
+    act(() => jest.advanceTimersByTime(2000));
+    act(() => setNetInfoState(NetInfoMock));
+    act(() => jest.advanceTimersByTime(RESUME_VERIFICATION_DELAY_MS));
+
+    expect(onConnectionLost).not.toHaveBeenCalled();
+    expect(onConnectionRestored).not.toHaveBeenCalled();
+  });
+
+  it("calls onConnectionLost 5s after resume when the device is really offline", () => {
+    const onConnectionLost = jest.fn();
+
+    const store = {
+      plugins: [{ module: { networkHooks: { onConnectionLost } } }],
+    };
+
+    renderHook(() => React.useContext(NetworkStatusContext), getWrapper(store));
+
+    changeAppState("background");
+    changeAppState("active");
+    act(() => setNetInfoState(R.mergeRight(NetInfoMock, OFFLINE_PATCH)));
+
+    act(() => jest.advanceTimersByTime(RESUME_VERIFICATION_DELAY_MS - 1));
+    expect(onConnectionLost).not.toHaveBeenCalled();
+
+    act(() => jest.advanceTimersByTime(1));
+    expect(onConnectionLost).toHaveBeenCalledTimes(1);
+  });
+
+  it("exposes stillOfflineAfterResumeCount when the device is still offline after resume", () => {
+    const store = { plugins: [{}] };
+
+    const { result } = renderHook(
+      () => React.useContext(NetworkStatusContext) as any,
+      getWrapper(store)
+    );
+
+    act(() => setNetInfoState(R.mergeRight(NetInfoMock, OFFLINE_PATCH)));
+    expect(result.current.stillOfflineAfterResumeCount).toBe(0);
+
+    changeAppState("background");
+    changeAppState("active");
+    act(() => jest.advanceTimersByTime(RESUME_VERIFICATION_DELAY_MS));
+
+    expect(result.current.stillOfflineAfterResumeCount).toBe(1);
+    expect(result.current.isInternetReachable).toBe(false);
+  });
+
+  it("logs online status changes at info level", () => {
+    mockLogger.info.mockClear();
+    mockLogger.warning.mockClear();
+
+    renderHook(
+      () => React.useContext(NetworkStatusContext),
+      getWrapper({ plugins: [{}] })
+    );
+
+    act(() => setNetInfoState(R.mergeRight(NetInfoMock, OFFLINE_PATCH)));
+
+    expect(mockLogger.info).toHaveBeenCalledWith(
+      expect.objectContaining({
+        message: "NetworkStatus: online status changed",
+        data: expect.objectContaining({ online: false, previousOnline: true }),
+      })
+    );
+
+    expect(mockLogger.warning).not.toHaveBeenCalled();
+  });
+});