pipwave-ekyc-uikit 3.4.0 → 3.5.0-beta.1

package/branch-review-sc-356160.md

@@ -0,0 +1,184 @@
+# Branch review: `hotfix-teojunjie-sc-356160-fix-face-model-load-deadlock`
+
+Compared against `origin/master`. The branch is 2 commits ahead, 0 behind.
+
+- `1cb8851` [sc-356160] Add timeout and retry to face model load
+- `09fb8c1` [sc-356160] Add Retry dialog when face model load fails
+
+```
+ src/plugins/face-camera.ts                      |  16 ++
+ src/plugins/face-detection.ts                   |  80 ++++--
+ src/plugins/test/face-detection.load.test.ts    | 221 +++++++++++++++++ (new)
+ src/plugins/{ => test}/card-detection.inference.test.ts
+ src/plugins/{ => test}/card-detection.test.ts
+ src/plugins/{ => test}/detection-failure.test.ts
+ src/plugins/{ => test}/face-detection.test.ts
+ src/translations/en.ts                          |   1 +
+ 8 files changed, 308 insertions(+), 30 deletions(-)
+```
+
+## The bug being fixed
+
+The selfie screen downloads face-api model files before it can start. The old code in
+`src/plugins/face-detection.ts` did this:
+
+1. Set `loadedModelState` to `"LOADING"`.
+2. Start the download.
+3. Wait in a loop: `while (loadedModelState === "LOADING") { sleep 500ms }`.
+
+If a download stalled but never actually failed, step 1's `"LOADING"` value was never changed. So the loop
+in step 3 kept waiting forever, and the user was stuck looking at the "Initializing Camera..." spinner with
+no error and no way forward.
+
+## What the branch changes
+
+### 1. `src/plugins/face-detection.ts` — bound the download and retry it
+
+- **One shared download.** A new module-level `loadPromise` holds the single download in progress. The
+  background pre-warm (from `src/uisdk.ts`) and the selfie screen now wait on the same promise instead of
+  each watching the `loadedModelState` variable. It is set back to `null` when the download finishes, so a
+  failed download can be tried again later.
+- **A time limit and retries.** The new `_attemptLoadModel()` wraps the four loader calls in
+  `withTimeout(..., 10000, "face model load")` and retries up to 2 more times, waiting 500ms then 1s between
+  tries. If all 3 attempts fail, it sets `loadedModelState` back to `"NOT_LOADED"` and throws.
+- **`init()` handles the failure.** It now wraps the download in try/catch. On failure it hides the spinner,
+  calls a new `onModelLoadFailed?.()` callback, and returns without starting detection. The old endless
+  `while` loop is gone.
+- **Reuses existing helpers.** `withTimeout` and `computeBackoffMs` already existed in
+  `src/plugins/detection-failure.ts` (written for the card model loader), so nothing was duplicated. It
+  skips the third helper, `classifyFailure`, and the comment explains why: face-api's loaders only download
+  files, so every failure here is worth retrying.
+
+### 2. `src/plugins/face-camera.ts` — show a Retry dialog
+
+`init()` now sets `faceDetectionSdk.onModelLoadFailed` to a new `showModelLoadFailedDialog()` method. That
+method opens a `BaseDialog` with the message `$t("face_camera_unavailable")` and a `$t("btn_retry")` button,
+plus a Cancel button.
+
+Pressing Retry calls `faceDetectionSdk.init()` again. That works because the state was already reset to
+`"NOT_LOADED"`, so it starts a genuinely new download instead of waiting on the dead one. Cancel just closes
+the dialog and leaves the back button in the header as the way out.
+
+### 3. `src/translations/en.ts` — one new string
+
+`face_camera_unavailable: "Couldn't start the camera. Please check your connection and retry."`
+
+`en.ts` is the only translation file in this repo, so there are no other languages left missing the string.
+
+### 4. Tests moved and added
+
+Four existing test files moved from `src/plugins/` into `src/plugins/test/`. I checked the diff: the only
+content change is the import paths getting one level deeper (`./card-detection` became `../card-detection`,
+`../classes/MainPage` became `../../classes/MainPage`). No config change was needed because
+`vitest.config.ts` already looks for `src/**/*.test.ts`.
+
+`face-detection.load.test.ts` is new and adds 9 tests:
+
+- a normal successful load
+- a load that fails once then succeeds on retry
+- a stalled load that times out, fails, and resets the state cleanly
+- a fresh retry working after an earlier failure
+- two callers at once sharing a single download (not downloading twice)
+- the failure reaching the second caller too, so it isn't left hanging
+- a download that finishes *after* its attempt already timed out, which must be ignored
+- `init()` hiding the spinner when the load fails
+- `init()` calling `onModelLoadFailed` so the dialog can appear
+
+## Checks I ran
+
+| Check | Result |
+| --- | --- |
+| `npx vitest run` | 5 files, **76 tests passed** |
+| `npx tsc --noEmit` | no errors |
+| `npm run build` | builds fine; only the bundle-size warnings that were already there |
+
+One thing to watch: the tests need Node 18 or newer. On Node 16 (the shell default here) vitest crashes at
+startup with a `node:util` / `styleText` SyntaxError before running a single test. Worth checking that CI and
+other developers aren't on Node 16.
+
+## Problems found
+
+### 1. The 10-second limit is probably too short (most important)
+
+The four loaders download about 7 MB in total, from `public/face-models`:
+
+| file | size |
+| --- | --- |
+| `tiny_face_detector_model-shard1` | 193 KB |
+| `face_landmark_68_model-shard1` | 357 KB |
+| `face_expression_model-shard1` | 329 KB |
+| `face_recognition_model-shard1` + `shard2` | 6.44 MB |
+| **total** | **~7.0 MB** |
+
+To finish 7 MB in 10 seconds you need about 700 KB/s, which is roughly 5.6 Mbps held steady. On a weak
+mobile connection the download is fine, just slow, but the new code gives up on it. It then retries twice,
+also giving up, and shows "Couldn't start the camera" after about 31.5 seconds (three 10s attempts plus
+500ms and 1s of waiting).
+
+So we've fixed a rare freeze but made slow connections fail where they used to eventually work.
+
+Two smaller side effects of the same setting:
+
+- `withTimeout` doesn't cancel the download it gave up on. Sometimes that helps, because the first download
+  may finish and fill the browser cache in time for retry 2 or 3 to reuse it. But that depends on the cache
+  headers on `assets.pipwave.com` and on lucky timing, so we can't rely on it.
+- Because nothing is cancelled, up to 3 attempts x 4 loaders can be downloading at the same time, all
+  fighting over the same slow connection.
+
+What I'd suggest, best option first:
+
+1. Raise the limit per attempt to 30-45 seconds. The point is to catch a download that has stopped moving,
+   not one that is merely slow, so the limit doesn't need to be tight.
+2. Or detect a stall instead of a total time (give up only when no bytes have arrived for a while).
+3. Or pass an `AbortController` so a given-up attempt stops using bandwidth. face-api's loaders may not
+   accept one, in which case option 1 matters more.
+
+Worth noting this mostly affects the slow-connection minority: the pre-warm in `src/uisdk.ts:83` starts
+downloading early in the eKYC flow, so most users are done well before they reach the selfie screen.
+
+### 2. The 90-second idle timer can fire while the Retry dialog is open
+
+`FaceCamera.init()` starts a 90-second idle timer (`src/plugins/face-camera.ts:233-245`) before the model
+download begins. One failed download cycle uses up to 31.5 seconds of that.
+
+So if the user reads the dialog and taps Retry late, the idle timer can go off in the middle of the retry.
+The timer calls `stopVideoStream()`, which kills the camera tracks, while the retrying `init()` carries on
+and calls `startDetection()` on a camera that no longer works. The result is a stuck camera with no spinner
+and no error message.
+
+Simple fix: reset the idle timer inside the Retry callback (or clear it when the load fails and restart it
+on Retry).
+
+### 3. Two dialogs could stack up (minor)
+
+`init()` doesn't check whether it is already running before starting the download. The
+`!this.iFrameRef && !this.isStartingDetection` check happens after the `await`, not before it. If the video
+element fires `loadedmetadata` twice (for example the camera stream is re-acquired, or the device rotates),
+both calls share the same failing download and both call `onModelLoadFailed`, so two dialogs appear on top
+of each other. A simple "already showed the dialog" flag would prevent it.
+
+### 4. Cosmetic
+
+- `src/plugins/face-detection.ts:745` has trailing whitespace on a new blank line inside
+  `_attemptLoadModel()`. Two similar cases were already in the file. There's no eslint config in this repo,
+  so nothing flags it.
+- The Cancel button text is hardcoded as `"Cancel"` in `src/components/baseDialog.ts:73` instead of using
+  `$t(...)`. This isn't new, and it doesn't matter while English is the only locale, but this new dialog is
+  one more place using it.
+
+## Things I checked that are correct
+
+- **No way back into the old freeze.** There is never a moment where `loadedModelState` is `"LOADING"` while
+  `loadPromise` is `null`. An async function runs up to its first `await` immediately, so `"LOADING"` is set
+  before the promise is handed to anyone, and on failure `"NOT_LOADED"` is set before the throw. So a caller
+  arriving at any point either joins the live download or starts a new one.
+- **No unhandled promise rejections.** The caller that starts the download always awaits it, and the
+  pre-warm at `src/uisdk.ts:83` has a `.catch(...)`.
+- **Retry really does start over.** The state is reset and `loadPromise` cleared before the dialog appears,
+  so Retry downloads again rather than waiting on the failed promise. Test 4 covers this.
+- **Retry shows a spinner.** `FACEDETECTIONSDK.init()` calls `createFullLoading` itself, so pressing Retry
+  gives visible feedback instead of looking like nothing happened.
+- **The `finally` block in `FaceCamera.init()`** still hides the spinner based on
+  `getLoadedModelState() !== "LOADING"`. This branch doesn't change that behaviour.
+- **`dist/pw-bundle.js` doesn't include these changes.** That's expected: this repo only commits `dist/` when
+  the version is bumped for a release.