@_nazmiforreal/flutter-ota 0.1.25 → 0.1.27

package/dart-src/root/android/src/main/kotlin/com/flutter_patcher/flutter_patcher/FlutterPatcherApplication.kt

@@ -0,0 +1,201 @@
+package com.flutter_patcher.flutter_patcher
+
+import android.content.Context
+import android.util.Log
+import io.flutter.app.FlutterApplication
+
+/**
+ * 宿主 App 需在 AndroidManifest.xml 中使用这个 Application（或在自己的 Application
+ * 里调 [attachPatcher]）。
+ *
+ * 启动流程：
+ * 1. attachBaseContext
+ *    → CrashGuard.shouldLoadPatch() 熔断检查（API 30+ 走 ApplicationExitInfo
+ *      精确识别上次进程是真崩溃还是被用户/系统结束；API < 30 走朴素策略：
+ *      patch_loading=true 即视为一次崩溃）
+ *    → PatchManager.getValidPatchPath() 磁盘补丁验签
+ *    → LoaderHook.install() 反射替换 FlutterLoader
+ *    → CrashGuard.markBooting() 标记「启动中」并记录 pid（API 30+ 用于 ExitInfo 查询）
+ * 2. Dart 首帧 → MethodChannel("flutter_ota_kit#reportBootSuccess")
+ *    → CrashGuard.markBootSuccess() 重置计数
+ *
+ * API 30+ 上，用户主动从最近任务划掉 / OOM kill / 强停等「非崩溃退出」不计入
+ * crash_count，只有真崩溃（CRASH / CRASH_NATIVE / ANR / INITIALIZATION_FAILURE）
+ * 才会触发熔断。API < 30 没有这层分类，对长尾设备做 fail-fast 取舍。
+ *
+ * 用户如果已经有自己的 Application 基类，直接把 [attachPatcher] 搬过去即可，
+ * 不需要继承本类。
+ */
+open class FlutterPatcherApplication : FlutterApplication() {
+
+    companion object {
+        private const val TAG = "FlutterPatcher/App"
+
+        @Volatile
+        private var attachAttempted = false
+
+        @Volatile
+        private var attachResult = false
+
+        /**
+         * 在 Application.attachBaseContext(base) 中、super 调用之后调用。
+         * 返回补丁是否成功注入。
+         */
+        @JvmStatic
+        @Synchronized
+        fun attachPatcher(context: Context): Boolean {
+            if (attachAttempted) {
+                Log.d(TAG, "attachPatcher already ran in this process, result=$attachResult")
+                return attachResult
+            }
+            attachAttempted = true
+            attachResult = doAttachPatcher(context)
+            return attachResult
+        }
+
+        private fun doAttachPatcher(context: Context): Boolean {
+            // 本次启动是否已往 BootDiagnosticStore 写过精准 status。
+            // 用于在收尾阶段判断要不要兜底成 NO_PATCH（避免覆盖更精准的 reason）。
+            var diagRecorded = false
+            val appVc = PatcherConfig.currentVersionCode(context)
+
+            return try {
+                // 在熔断/校验丢弃前预读 (version, downloadMd5)，等会儿入黑名单要用。
+                // 即便文件后续被删，这里捕获的字符串仍有效。
+                val patchManager = PatchManager(context)
+                val crashedMeta = patchManager.currentMeta()
+
+                val guard = CrashGuard(context)
+                val canLoad = guard.shouldLoadPatch { crashCount ->
+                    // 熔断触发 ⇒ 这个补丁连续没活到 verified，加入黑名单防止重试。
+                    if (crashedMeta != null) {
+                        BlacklistStore.add(
+                            context,
+                            crashedMeta.first,
+                            crashedMeta.second,
+                            BlacklistStore.REASON_BOOT_CRASH,
+                        )
+                    }
+                    BootDiagnosticStore.record(
+                        context = context,
+                        status = BootDiagnosticStore.DROPPED_CIRCUIT_BREAKER,
+                        patchVersion = crashedMeta?.first,
+                        appVersionCode = appVc,
+                        crashCount = crashCount,
+                        message = if (crashedMeta != null)
+                            "$crashCount boot failure(s); blacklisted (version=${crashedMeta.first})"
+                        else
+                            "$crashCount boot failure(s)",
+                    )
+                    diagRecorded = true
+                }
+                if (!canLoad) {
+                    Log.w(TAG, "circuit breaker tripped, skip patch")
+                    return false
+                }
+
+                val patch = patchManager.getValidPatch { status, version, extras ->
+                    // md5 / signature 失败 = 强烈"补丁有问题"信号，连带入黑名单。
+                    // meta_corrupted / version_code_mismatch 不入黑名单（前者 key 不全，后者
+                    // 属于正常 APK 升级而非补丁本身有问题）。
+                    val blacklistMd5 = extras["blacklistMd5"] as? String
+                    val blacklistReason = when (status) {
+                        BootDiagnosticStore.DROPPED_MD5_MISMATCH ->
+                            BlacklistStore.REASON_MD5_MISMATCH
+                        BootDiagnosticStore.DROPPED_SIGNATURE_INVALID ->
+                            BlacklistStore.REASON_SIGNATURE_INVALID
+                        else -> null
+                    }
+                    if (blacklistReason != null && version != null && !blacklistMd5.isNullOrEmpty()) {
+                        BlacklistStore.add(context, version, blacklistMd5, blacklistReason)
+                    }
+
+                    BootDiagnosticStore.record(
+                        context = context,
+                        status = status,
+                        patchVersion = version,
+                        patchTargetVersionCode = extras["patchTargetVersionCode"] as? Long,
+                        appVersionCode = (extras["appVersionCode"] as? Long) ?: appVc,
+                        message = extras["message"] as? String,
+                    )
+                    diagRecorded = true
+                }
+                if (patch == null) {
+                    Log.d(TAG, "no usable patch, boot with built-in libapp.so")
+                    if (!diagRecorded) {
+                        // DROPPED_* 是用户最关心的"上次为啥被丢弃"信息，不应被这次
+                        // 无信息量的 NO_PATCH 覆盖。典型场景：上一次冷启动里 Dart 错误
+                        // 钩子把补丁判崩 + record(DROPPED_CIRCUIT_BREAKER) + 删补丁，
+                        // 但进程没死、UI 没建出来；用户划掉重开后这一次进入本分支，
+                        // 写 NO_PATCH 会让 DiagCard 看不到 trip 信息。
+                        // 后续装上新补丁时，line 127 会写 PATCHED 自然覆盖，sticky 自动解除。
+                        val existing = BootDiagnosticStore.read(context)
+                        val existingStatus = existing?.get("status") as? String
+                        val shouldPreserve = existingStatus != null &&
+                            existingStatus.startsWith("DROPPED_")
+                        if (!shouldPreserve) {
+                            BootDiagnosticStore.record(
+                                context = context,
+                                status = BootDiagnosticStore.NO_PATCH,
+                                appVersionCode = appVc,
+                            )
+                        } else {
+                            Log.d(TAG, "preserved existing $existingStatus over NO_PATCH")
+                        }
+                    }
+                    return false
+                }
+
+                // 走到这里说明补丁已通过校验。预先取版本号，方便后面 record。
+                val patchVersion = patchManager.currentVersion().ifEmpty { null }
+
+                // 标记「启动中」——必须 commit 同步写入，确保进程崩溃前状态已持久化
+                guard.markBooting()
+
+                val attemptedFields = mutableListOf<String>()
+                val ok = LoaderHook.install(
+                    context,
+                    patch.soPath,
+                    patch.assetsBundlePath,
+                    patch.assetsArchivePath,
+                    attemptedFields
+                )
+                if (ok) {
+                    BootDiagnosticStore.record(
+                        context = context,
+                        status = BootDiagnosticStore.PATCHED,
+                        patchVersion = patchVersion,
+                        appVersionCode = appVc,
+                    )
+                } else {
+                    // 注入失败：本次启动根本没换 libapp.so，不视为一次崩溃
+                    guard.reset()
+                    BootDiagnosticStore.record(
+                        context = context,
+                        status = BootDiagnosticStore.HOOK_INSTALL_FAILED,
+                        patchVersion = patchVersion,
+                        appVersionCode = appVc,
+                        attemptedLoaderFields = attemptedFields.toList(),
+                        message = "FlutterLoader reflection failed; patch retained",
+                    )
+                }
+                ok
+            } catch (e: Exception) {
+                Log.e(TAG, "attachPatcher failed, fallback to built-in", e)
+                CrashGuard(context).reset()
+                BootDiagnosticStore.record(
+                    context = context,
+                    status = BootDiagnosticStore.UNKNOWN,
+                    appVersionCode = appVc,
+                    message = e.message ?: e.javaClass.simpleName,
+                )
+                false
+            }
+        }
+    }
+
+    override fun attachBaseContext(base: Context) {
+        super.attachBaseContext(base)
+        attachPatcher(this)
+    }
+}

package/dart-src/root/android/src/main/kotlin/com/flutter_patcher/flutter_patcher/FlutterPatcherAutoInitProvider.kt

@@ -0,0 +1,93 @@
+package com.flutter_patcher.flutter_patcher
+
+import android.content.ContentProvider
+import android.content.ContentValues
+import android.database.Cursor
+import android.net.Uri
+import android.util.Log
+
+/**
+ * 自动初始化 ContentProvider —— 宿主无需改 Application 即可挂上补丁加载。
+ *
+ * # 生命周期
+ * Android `ActivityThread.handleBindApplication` 的固定顺序：
+ *
+ * ```
+ * Application.attachBaseContext()
+ *   ↓
+ * installContentProviders()  ← 本 provider.onCreate 在这里触发
+ *   ↓
+ * Application.onCreate()
+ *   ↓
+ * Activity lifecycle（FlutterActivity.onCreate → 首次 new FlutterEngine）
+ * ```
+ *
+ * 插件反射替换 `FlutterInjector.flutterLoader` 只要求"早于第一次
+ * `FlutterInjector.instance()` 真正被使用"，ContentProvider 这个时机足够。
+ * 这是 Firebase / WorkManager / androidx.startup 都在用的自动初始化模式。
+ *
+ * # 边界：什么时候走不通
+ * 宿主在自己 `Application.attachBaseContext` 里 **预热 FlutterEngine**（罕见，
+ * 主要出现在大厂混合工程的冷启动优化）。此时 provider 还没轮到、Engine 已起来，
+ * 反射来不及。这类工程应在宿主 Manifest 里关掉自动初始化，改为显式调用：
+ *
+ * ```xml
+ * <provider
+ *     android:name="com.flutter_patcher.flutter_patcher.FlutterPatcherAutoInitProvider"
+ *     android:authorities="${applicationId}.flutter_patcher.autoinit"
+ *     tools:node="remove" />
+ * ```
+ *
+ * 然后在自己的 Application 里：
+ *
+ * ```kotlin
+ * override fun attachBaseContext(base: Context) {
+ *     super.attachBaseContext(base)
+ *     FlutterPatcherApplication.attachPatcher(base)
+ * }
+ * ```
+ */
+class FlutterPatcherAutoInitProvider : ContentProvider() {
+
+    companion object {
+        private const val TAG = "FlutterPatcher/AutoInit"
+    }
+
+    override fun onCreate(): Boolean {
+        val ctx = context ?: run {
+            Log.w(TAG, "context is null, skip auto init")
+            return false
+        }
+        Log.d(TAG, "auto init via ContentProvider.onCreate()")
+        FlutterPatcherApplication.attachPatcher(ctx)
+        return true
+    }
+
+    // ==================== no-op data surface ====================
+    // 本 provider 不对外暴露任何数据；所有 CRUD 都返回空 / 0 即可。
+
+    override fun query(
+        uri: Uri,
+        projection: Array<out String>?,
+        selection: String?,
+        selectionArgs: Array<out String>?,
+        sortOrder: String?
+    ): Cursor? = null
+
+    override fun getType(uri: Uri): String? = null
+
+    override fun insert(uri: Uri, values: ContentValues?): Uri? = null
+
+    override fun delete(
+        uri: Uri,
+        selection: String?,
+        selectionArgs: Array<out String>?
+    ): Int = 0
+
+    override fun update(
+        uri: Uri,
+        values: ContentValues?,
+        selection: String?,
+        selectionArgs: Array<out String>?
+    ): Int = 0
+}

package/dart-src/root/android/src/main/kotlin/com/flutter_patcher/flutter_patcher/FlutterPatcherPlugin.kt

@@ -0,0 +1,245 @@
+package com.flutter_patcher.flutter_patcher
+
+import android.content.Context
+import android.os.Build
+import android.os.Handler
+import android.os.Looper
+import android.util.Log
+import io.flutter.embedding.engine.plugins.FlutterPlugin
+import io.flutter.plugin.common.EventChannel
+import io.flutter.plugin.common.MethodCall
+import io.flutter.plugin.common.MethodChannel
+import io.flutter.plugin.common.MethodChannel.MethodCallHandler
+import io.flutter.plugin.common.MethodChannel.Result
+
+/**
+ * Dart ↔ Android 的 MethodChannel 处理器。
+ *
+ * Channel 名：
+ * - MethodChannel `flutter_ota_kit` —— RPC（saveConfig / applyPatch / ...）
+ * - EventChannel  `flutter_ota_kit/events` —— applyPatch 过程的阶段 / 进度事件
+ *
+ * MethodChannel 方法：
+ * - saveConfig(publicKeyBase64, maxCrashCount, strictSignature,
+ *              loaderFieldCandidates, loaderFallbackHeuristic)
+ * - markBooting()               — Dart init 最开头调用，补写一次「启动中」
+ * - reportBootSuccess()         — Dart 首帧渲染时调用，清熔断
+ * - reportDartBootError(Map)    — 引导阶段 Dart 未捕获异常上报，等同一次真崩溃
+ * - applyPatch(Map) -> Map{ok, error, message}
+ * - rollback()
+ * - currentVersion() -> String?
+ * - lastBootDiagnostic() -> Map? — 上次冷启动补丁加载诊断（见 BootDiagnosticStore）
+ * - cacheDir() -> String — 插件可写的临时目录，供 Dart applyPatchBytes 内部 staging 使用
+ * - appVersionCode() -> Long — 当前宿主 APK versionCode，A3 便捷查询
+ * - deviceAbi() -> String — 当前设备首选 ABI，用于服务端按 ABI 分发补丁
+ * - blacklist() -> List<Map> — 已知"装上就出事"的补丁本地黑名单
+ * - clearBlacklist() — 清空黑名单（仅调试 / 显式恢复用）
+ */
+class FlutterPatcherPlugin :
+    FlutterPlugin, MethodCallHandler, EventChannel.StreamHandler {
+
+    companion object {
+        private const val TAG = "FlutterPatcher/Plugin"
+        private const val CHANNEL = "flutter_ota_kit"
+        private const val EVENT_CHANNEL = "flutter_ota_kit/events"
+    }
+
+    private lateinit var channel: MethodChannel
+    private lateinit var eventChannel: EventChannel
+    private lateinit var appContext: Context
+    private val main = Handler(Looper.getMainLooper())
+
+    @Volatile
+    private var eventSink: EventChannel.EventSink? = null
+
+    override fun onAttachedToEngine(binding: FlutterPlugin.FlutterPluginBinding) {
+        appContext = binding.applicationContext
+        channel = MethodChannel(binding.binaryMessenger, CHANNEL)
+        channel.setMethodCallHandler(this)
+        eventChannel = EventChannel(binding.binaryMessenger, EVENT_CHANNEL)
+        eventChannel.setStreamHandler(this)
+    }
+
+    // ==================== EventChannel ====================
+
+    override fun onListen(arguments: Any?, events: EventChannel.EventSink?) {
+        eventSink = events
+    }
+
+    override fun onCancel(arguments: Any?) {
+        eventSink = null
+    }
+
+    private fun emitProgress(phase: String, received: Long, total: Long) {
+        val sink = eventSink ?: return
+        val event = mapOf(
+            "phase" to phase,
+            "received" to received,
+            "total" to total
+        )
+        main.post { sink.success(event) }
+    }
+
+    override fun onMethodCall(call: MethodCall, result: Result) {
+        when (call.method) {
+            "saveConfig" -> handleSaveConfig(call, result)
+            "markBooting" -> {
+                CrashGuard(appContext).markBooting()
+                result.success(null)
+            }
+            "reportBootSuccess" -> {
+                CrashGuard(appContext).markBootSuccess()
+                result.success(null)
+            }
+            "reportDartBootError" -> handleReportDartBootError(call, result)
+            "applyPatch" -> handleApplyPatch(call, result)
+            "rollback" -> handleRollback(result)
+            "rollbackToPrevious" -> handleRollbackToPrevious(result)
+            "currentVersion" -> handleCurrentVersion(result)
+            "lastBootDiagnostic" -> handleLastBootDiagnostic(result)
+            "cacheDir" -> result.success(appContext.cacheDir.absolutePath)
+            "appVersionCode" -> result.success(PatcherConfig.currentVersionCode(appContext))
+            "deviceAbi" -> result.success(Build.SUPPORTED_ABIS.firstOrNull().orEmpty())
+            "blacklist" -> result.success(BlacklistStore.entries(appContext))
+            "clearBlacklist" -> {
+                BlacklistStore.clear(appContext)
+                result.success(null)
+            }
+            "reportApplyFailure" -> handleReportApplyFailure(call, result)
+            "isVersionBlacklisted" -> handleIsVersionBlacklisted(call, result)
+            else -> result.notImplemented()
+        }
+    }
+
+    override fun onDetachedFromEngine(binding: FlutterPlugin.FlutterPluginBinding) {
+        channel.setMethodCallHandler(null)
+        eventChannel.setStreamHandler(null)
+        eventSink = null
+    }
+
+    // ==================== handlers ====================
+
+    private fun handleSaveConfig(call: MethodCall, result: Result) {
+        val pk = call.argument<String>("publicKeyBase64") ?: ""
+        val max = call.argument<Int>("maxCrashCount") ?: PatcherConfig.DEFAULT_MAX_CRASH
+        val strict = call.argument<Boolean>("strictSignature") ?: PatcherConfig.DEFAULT_STRICT_SIG
+        val fields = call.argument<List<String>>("loaderFieldCandidates") ?: emptyList()
+        val heuristic = call.argument<Boolean>("loaderFallbackHeuristic")
+            ?: PatcherConfig.DEFAULT_LOADER_HEURISTIC
+        val maxPatchHistory = call.argument<Int>("maxPatchHistory") ?: PatcherConfig.MAX_PATCH_HISTORY
+        val maxAssetHistory = call.argument<Int>("maxAssetHistory") ?: PatcherConfig.MAX_ASSET_HISTORY
+        PatcherConfig.saveConfig(appContext, pk, max, strict, fields, heuristic, maxPatchHistory, maxAssetHistory)
+        result.success(null)
+    }
+
+    private fun handleApplyPatch(call: MethodCall, result: Result) {
+        @Suppress("UNCHECKED_CAST")
+        val args = call.arguments as? Map<String, Any?>
+        if (args == null) {
+            result.error("INVALID_ARGS", "applyPatch expects a Map", null)
+            return
+        }
+        Thread {
+            val progress: ProgressCallback = { phase, received, total ->
+                emitProgress(phase, received, total)
+            }
+            val applyResult = try {
+                PatchManager(appContext, progress).applyPatch(args)
+            } catch (e: Exception) {
+                Log.e(TAG, "applyPatch error", e)
+                ApplyResult.failure(ApplyErrorCode.UNKNOWN, e.message ?: e.javaClass.simpleName)
+            }
+            main.post { result.success(applyResult.toMap()) }
+        }.start()
+    }
+
+    private fun handleRollback(result: Result) {
+        Thread {
+            try {
+                PatchManager(appContext).rollback()
+            } catch (e: Exception) {
+                Log.e(TAG, "rollback error", e)
+            }
+            main.post { result.success(null) }
+        }.start()
+    }
+
+    private fun handleRollbackToPrevious(result: Result) {
+        Thread {
+            try {
+                val outcome = PatchManager(appContext).rollbackToPrevious()
+                main.post { result.success(outcome.name) }
+            } catch (e: Exception) {
+                Log.e(TAG, "rollbackToPrevious error", e)
+                main.post { result.success(RollbackResult.FALLBACK_TO_BASE.name) }
+            }
+        }.start()
+    }
+
+    private fun handleCurrentVersion(result: Result) {
+        val v = PatchManager(appContext).currentVersion()
+        result.success(if (v.isEmpty()) null else v)
+    }
+
+    private fun handleLastBootDiagnostic(result: Result) {
+        // null 表示从未 record 过（首次安装 / pm clear 后第一次启动且尚未到首帧）
+        result.success(BootDiagnosticStore.read(appContext))
+    }
+
+    /**
+     * Dart 侧 PlatformDispatcher.onError / FlutterError.onError 在「verifyAfter 窗口内」
+     * 抓到的未捕获异常 ⇒ 等同 ApplicationExitInfo.REASON_CRASH 处理：crash_count += 1，
+     * 达阈值则 onTrip 回调里走完整的"加黑名单 + 记诊断 + 删补丁"链路。
+     *
+     * 与 attachPatcher 里 shouldLoadPatch 的 onTrip 逻辑保持一致，让用户在 DiagCard
+     * 上看到 status=DROPPED_CIRCUIT_BREAKER 而不是上一次的 status=PATCHED 残影。
+     */
+    private fun handleReportDartBootError(call: MethodCall, result: Result) {
+        val message = call.argument<String>("message")
+        val patchManager = PatchManager(appContext)
+        val crashedMeta = patchManager.currentMeta()
+        val appVc = PatcherConfig.currentVersionCode(appContext)
+
+        CrashGuard(appContext).reportDartBootError(message) { crashCount ->
+            if (crashedMeta != null) {
+                BlacklistStore.add(
+                    appContext,
+                    crashedMeta.first,
+                    crashedMeta.second,
+                    BlacklistStore.REASON_BOOT_CRASH,
+                )
+            }
+            BootDiagnosticStore.record(
+                context = appContext,
+                status = BootDiagnosticStore.DROPPED_CIRCUIT_BREAKER,
+                patchVersion = crashedMeta?.first,
+                appVersionCode = appVc,
+                crashCount = crashCount,
+                message = if (crashedMeta != null)
+                    "$crashCount Dart boot failure(s); blacklisted (version=${crashedMeta.first}); ${message ?: ""}"
+                else
+                    "$crashCount Dart boot failure(s); ${message ?: ""}",
+            )
+        }
+        result.success(null)
+    }
+
+    private fun handleReportApplyFailure(call: MethodCall, result: Result) {
+        val version = call.argument<String>("version") ?: ""
+        val md5 = call.argument<String>("md5") ?: ""
+        val reason = call.argument<String>("reason") ?: "APPLY_FAILED"
+        BlacklistStore.add(appContext, version, md5, reason)
+        result.success(null)
+    }
+
+    private fun handleIsVersionBlacklisted(call: MethodCall, result: Result) {
+        val version = call.argument<String>("version") ?: ""
+        val md5 = call.argument<String>("md5") ?: ""
+        val found = if (md5.isNotEmpty()) {
+            BlacklistStore.contains(appContext, version, md5)
+        } else {
+            BlacklistStore.containsByVersion(appContext, version)
+        }
+        result.success(found)
+    }
+}