feat: OCDS v1.1 conformance — concurrent downloader (iOS + Android) + standard

[huhuanming]

Defines the OneKey Concurrent Download Standard (OCDS v1.1) and brings the iOS + Android concurrent (multi-range) downloaders into conformance.

Standard

• native-modules/react-native-range-downloader/SPEC.md — normative, platform-agnostic standard: segment-file data model, permanent-vs-transient failure classification, resume / retry / integrity / finalization / fallback / termination, trust boundary, conformance scenarios.

iOS (range-downloader core + bundle-update caller)

• Explicit typed permanent/transient failure class (no side-effect inference), forwarded across the Nitro JS bridge (RangeDownloadOutcome + RangeFallbackKind + tunable params)
• 429/5xx keep .segN — no data loss; in-place per-segment retry + stall watchdog + jittered backoff + Retry-After
• Per-hop HTTPS redirect guard; multipart/total rejection; per-destination single-flight; monotonic progress floor
• 416 transient with mandatory size re-evaluation

Android (concurrent core + bundle-update caller)

• Wire CancelHandle from the bundle caller (cancel-then-delete)
• Exhaustive HTTP-status classification (416 transient); per-segment backoff; multipart/total rejection; fsync before rename; per-destination single-flight

Validation

• Compile-verified: iOS full-workspace xcodebuild BUILD SUCCEEDED; Android gradle compileDebugKotlin BUILD SUCCESSFUL (both modules)
• All four platform classifiers verified consistent against the spec (416 transient everywhere)

Follow-ups (not in this PR)

• JVM classifier unit test (Android module has no test dir; JS side covered)
• Android shutdownNow + awaitTermination (small resurrection window)
• Device stress testing (lock/background/network/throttle) — compilation ≠ runtime validation, especially the iOS per-segment retry state machine

Pairs with the app-monorepo PR (desktop + shared orchestration).

Companion PR: app-monorepo #12121 — desktop/Node downloader + shared AppUpdate orchestration.

---

✅ Verification record

How every platform's downloader is verified against the standard, and how each
test was proven load-bearing (a green test that survives its own regression
proves nothing). Full methodology + runnable harness:
react-native-range-downloader/conformance/.

Approach

flowchart TD
    SPEC["OCDS SPEC v1.2<br/>§6 — 11 conformance scenarios"]
    SPEC --> AND["Android<br/>pure-JVM + OkHttp MockWebServer<br/>real fault injection"]
    SPEC --> NODE["Node / Desktop<br/>jest + real local HTTP/HTTPS server"]
    SPEC --> IOSU["iOS · unit<br/>SwiftPM over the real RangeDownloadLogic"]
    SPEC --> IOSE["iOS · end-to-end<br/>real Release .app on Simulator<br/>+ local fault server (silent auto-download)"]
    AND  --> MUT["Mutation verification<br/>inject the regression each test targets<br/>→ the test MUST go red"]
    NODE --> MUT
    IOSE --> EVID["evidence: server log + app-latest.log<br/>+ on-disk .segN + final SHA"]
    EVID --> ADV["adversarial verify<br/>(default FAIL unless 3 sources agree)"]
    MUT  --> OK(["load-bearing ✔"])
    ADV  --> OK

Loading

SPEC §6 coverage matrix

#	Scenario	iOS (sim)	Android	Node
1	transient error → backoff retry, no restart	✅	✅	✅
2	killed mid-run → resume from completed segments	✅	✅¹	✅¹
3	200 to a Range → permanent → single-stream	✅	✅	✅
4	416 / 5xx transient (re-evaluate, retry)	✅	✅	✅
5	short / over-long / mis-aligned / bad-total 206	✅	✅	✅
6	corrupted assembly → terminal (v1.2: no retry-once)	✅	✅	✅
7	flap / background → progress never resets to 0	✅	◑²	✅
8	user cancel mid-run	⚪³	✅	✅
9	persistent failure → bounded give-up	✅	✅	caller⁴
10	stalled socket → stall watchdog	✅	✅	✅
11	two concurrent download() → single-flight	⚪³	✅	✅

¹ resume tested via a persisted-manifest proxy — a true SIGKILL-mid-write isn't reproducible in-process; covered by the manifest-resume + intra-call-resume tests.
² Android progress: the clamp/guard math is unit-tested, but the monotonic CAS primitive stays inline in the JNI adapter (not unit-testable).
³ iOS #8/#11 need a temp shim (the iOS app has no cancel trigger at all — #8 would test dead code); both behaviors are fully covered on Android + Node.
⁴ Node #9 give-up budget lives in the shared kit caller (useAppUpdate.test.ts), not the downloader.

Test counts & strength

Platform	Tests	Mutation-proven	Driver
Android	64	9	OkHttp MockWebServer (real sockets, real .segN, real SHA)
Node / Desktop	18	3	real local HTTP/HTTPS + positioned writes + .progress.json
iOS · unit	30	n/a	SwiftPM, source-symlinked to the shipping logic
iOS · e2e	9/11 §6	adversarial	real Release .app on a booted Simulator

Mutants planted & killed (load-bearing proof)

flowchart LR
    subgraph Android
      a1["503 → permanent"] --> ka(["🔴 caught"])
      a2["416 → permanent"] --> ka
      a3["bypass multipart"] --> ka
      a4["drop total check"] --> ka
      a5["501 → transient"] --> ka
      a6["retry budget +2"] --> ka
      a7["registry identity-drop"] --> ka
      a8["progress clamp removed"] --> ka
      a9["seg-glob narrowed"] --> ka
    end
    subgraph Node
      n1["416 → permanent"] --> kn(["🔴 caught"])
      n2["break single-stream 416"] --> kn
      n3["isConcurrentFallback→false"] --> kn
    end

Loading

Every mutant produced a real test failure (not a compile error) and was reverted.

Honesty / scope

• iOS e2e is a fake update task running through real download code. The app's own native downloader, its silent-auto-download trigger, segmentation, resume, retry, fallback and SHA-256 are all real; the update server, manifest, version and the bundle payload are synthetic (filler bytes, not a signed zip). It verifies the download layer only — the post-download unzip → signature-verify → install chain is out of OCDS scope.
• SPEC §6 fix: fix EXC_BAD_ACCESS in Skeleton on iOS #6 previously mandated a single-stream retry-once on a checksum mismatch. All three reference implementations terminate on mismatch instead (re-fetching the same object would re-corrupt), so v1.2 removed it — #6 is now conformant everywhere.
• The behavior-preserving extractions (Android RangeDownloadLogic.kt, iOS RangeDownloadLogic.swift) are pure moves — proven by the pre-existing real-path suites staying green.

---

🔩 Android APK updater — audit + fixes

The Android APK download path (react-native-app-update) shares the OCDS core, but its ~1346-line caller was never audited and had zero tests. An adversarial audit found 4 issues.

flowchart LR
  Q["'is the APK update missing changes?'"] --> AUDIT["adversarial OCDS audit<br/>of react-native-app-update"]
  AUDIT --> B1["#1 cancel race (HIGH)"] --> FIX["✅ fixed"]
  AUDIT --> B2["#2a/#2b spurious update/error"] --> FIX
  AUDIT --> B34["#3/#4 single-flight · promote-before-verify"] --> BL["📋 backlog (documented, mitigated)"]
  AUDIT --> COV["AppUpdateLogic extraction<br/>17 JVM tests · 10 mutants killed"]

Loading

Issues

Bug	Severity	Status	What
#1 cancel-then-delete race (OCDS §5.8)	HIGH	✅ fixed (213acf0f3)	concurrent download had NO cancelHandle → clearCache deleted .segN while 8 workers were still writing. Wired CancelHandle + cancel-before-delete (mirrors the bundle caller).
#2a spurious update/error on cancel	MED	✅ fixed (24d5973cb)	suppress update/error when the run was intentionally cancelled.
#2b spurious update/error when ASC offline	MED	✅ fixed (011c24a58)	a deferred (offline) signature check was mis-reported as a download error on every retry; suppressed (the Promise still rejects → JS still retries).
#3 process-global single-flight / #4 promote-before-verify	MED / LOW	📋 backlog	documented; doesn't corrupt, mitigated.

Coverage (b9caf71f9)

Extracted the dependency-free pure logic into AppUpdateLogic.kt (segment names + count, 416/206 Content-Range parse, completeness/alignment predicates); the adapter now delegates (pure move). Added junit + 17 JVM unit tests, with all 10 planted mutants killed (mutation-proven). Also wired a previously-untested inline 206-parse duplicate through the helper.

Honesty / scope

Still device/Robolectric-only: the JNI download loop, the actual .segN deletion + §5.8 cancel-race execution, and the promote/verify/install File-I/O are not exercised by these JVM tests.

[huhuanming]

OCDS conformance — adversarial review summary (native: iOS + Android)

Independent multi-agent audit of this PR against OCDS SPEC v1.2, with each high-severity finding re-checked by a separate skeptic. No blockers — every download path has a SHA256/signature backstop, so a corrupt artifact cannot be installed. Coverage was independently confirmed real (Swift 30/30, Android range 12 suites + APK 17, mutation-proven by injecting regressions).

Landed in this PR (just pushed)

• fix(android-apk) — verifyExistingApk's catch-all collapsed every exception to Indeterminate → ApkVerificationDeferredException, which is suppressed from update/error. A genuine local fault (corrupt APK, path/security rejection, runtime error) was mis-reported as a benign "verify later" and retried until the JS give-up budget drained. Now only IOException (offline / disk-I/O transient) defers; other exceptions rethrow and surface. APK unit tests green.
• docs(conformance) — corrected two overstatements: (1) verifyAPK does package-name + signing-cert verification (anti-tamper), not a whole-file SHA/GPG check vs the manifest; (2) added an explicit out-of-OCDS-scope note that the desktop full-installer (DMG/exe/AppImage) is downloaded by electron-updater, not the OCDS core.

Confirmed correct

• Android cancel-then-delete is bounded (awaitTermination(3s), catches InterruptedException) — no deadlock; worst case a 3s block on a Dispatchers.Default worker.
• The three "pure-move" extractions (iOS/Android core/APK *Logic) are genuinely behavior-preserving; the prior parse206ContentRange "tested-but-not-wired" coverage theater is now actually closed.

Backlog — real but accepted (not fixed here)

Item	Why deferred
iOS finalizePermanentFallback deletes .segN before sibling cancels run (§5.8 inversion)	Leaves orphan artifacts; whole-file SHA backstops. Real race, low impact.
Android drops all 4 §5.4/§5.11 tuning knobs incl. overall deadline (iOS honors them)	Latent — no production caller passes these today, and iOS's deadline also defaults to none; JS-layer give-up budget bounds the real flows.
iOS checksumMismatch → .fallbackPermanent (= single-stream re-download, contradicts SPEC 1.2)	Dead in prod — sole caller passes expectedSha256: nil. Landmine for any future caller; needs a distinct terminal class.
BUG #3 (process-global single-flight) / BUG #4 (promote-before-verify)	Mitigated by cert verify + installAPK TOCTOU; documented.
clearCache comment/commit "never invoked mid-download" is inaccurate; new-run TOCTOU after isDownloading=false	Rare; cancel-handle covers the in-flight-worker race.

Full report available on request.