@_nazmiforreal/flutter-ota 0.1.26 → 0.1.28

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)
+    }
+}

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

@@ -0,0 +1,298 @@
+package com.flutter_patcher.flutter_patcher
+
+import android.content.Context
+import android.util.Log
+import io.flutter.FlutterInjector
+import io.flutter.embedding.engine.FlutterJNI
+import io.flutter.embedding.engine.loader.FlutterLoader
+import java.lang.reflect.Field
+import java.lang.reflect.Modifier
+import java.util.concurrent.ExecutorService
+
+/**
+ * 通过反射把 FlutterInjector 内部持有的 FlutterLoader 替换为自定义实现。
+ *
+ * # 为什么是最脆弱的部分
+ * Flutter Engine 每个大版本都可能改内部字段名 / 改 FlutterLoader 的方法签名。
+ * 本类采用「候选字段名 + 类型启发式 + Dart 侧可覆盖」三层保护：
+ *
+ * ## 已验证字段名（按 Flutter 版本）
+ * | Flutter 版本 | FlutterInjector 字段 | ensureInitializationComplete 签名         |
+ * |-------------|----------------------|-------------------------------------------|
+ * | 3.19.x      | `flutterLoader`      | (Context, @Nullable String[])             |
+ * | 3.22.x      | `flutterLoader`      | (Context, @Nullable String[])             |
+ * | 3.24.x      | `flutterLoader`      | (Context, @Nullable String[])             |
+ * | 3.27.x      | `flutterLoader`      | (Context, @Nullable String[])             |
+ * | 3.29.x      | `flutterLoader`      | (Context, @Nullable String[])             |
+ * | 3.32.x      | `flutterLoader`      | (Context, @Nullable String[])             |
+ * | 3.35.x      | `flutterLoader`      | (Context, @Nullable String[])             |
+ * | 3.38.x      | `flutterLoader`      | (Context, @Nullable String[])             |
+ *
+ * 超出此范围（比如未来 Flutter 4.x）请先通过 `FlutterPatcher.init(loaderFieldCandidates: [...])`
+ * 下发新的字段名，再升级本库。
+ *
+ * 必须 **早于** 任何 Flutter 引擎初始化（即 FlutterActivity/FlutterFragment 创建
+ * 之前）调用，最佳时机是 Application.attachBaseContext。
+ */
+internal object LoaderHook {
+
+    private const val TAG = "FlutterPatcher/Hook"
+
+    /** 默认候选字段名。多字段是为了抵御 Flutter 未来改名。 */
+    private val DEFAULT_CANDIDATES = listOf("flutterLoader")
+
+    /**
+     * 用带补丁路径的自定义 FlutterLoader 替换默认实现。
+     *
+     * @param context        用于读 PatcherConfig 中的 Dart 侧覆盖配置
+     * @param patchSoPath    补丁 libapp.so 的绝对路径
+     * @param attemptedFields 可选 out 参数：调用前传入空 MutableList，方法返回后
+     *   会包含本次按顺序尝试过的字段候选名（无论成功失败）。供
+     *   [BootDiagnosticStore.HOOK_INSTALL_FAILED] 上报使用。
+     * @return 是否成功注入
+     */
+    fun install(
+        context: Context,
+        patchSoPath: String,
+        patchAssetsPath: String? = null,
+        patchAssetsArchivePath: String? = null,
+        attemptedFields: MutableList<String>? = null,
+    ): Boolean {
+        return try {
+            val injector = FlutterInjector.instance()
+            if (!patchAssetsArchivePath.isNullOrEmpty() && !patchAssetsPath.isNullOrEmpty()) {
+                if (!verifyAssetArchiveReadable(context, patchAssetsArchivePath, patchAssetsPath)) {
+                    throw IllegalStateException(
+                        "AssetManager.addAssetPath failed: $patchAssetsArchivePath"
+                    )
+                }
+                installPatchedFlutterJniFactory(
+                    injector,
+                    context,
+                    patchAssetsArchivePath,
+                    patchAssetsPath
+                )
+            }
+            val candidates = buildCandidates(context)
+            attemptedFields?.addAll(candidates)
+            val heuristic = PatcherConfig.loaderFallbackHeuristic(context)
+            val field = findLoaderField(injector.javaClass, candidates, heuristic)
+                ?: throw IllegalStateException(
+                    "FlutterInjector has no FlutterLoader field (tried: $candidates, " +
+                        "heuristic=$heuristic). Flutter API may have changed; pass " +
+                        "loaderFieldCandidates to FlutterPatcher.init."
+                )
+            field.isAccessible = true
+
+            val patched = PatchedFlutterLoader(patchSoPath, patchAssetsPath)
+            field.set(injector, patched)
+
+            Log.d(TAG, "FlutterLoader patched via field '${field.name}' -> $patchSoPath")
+            true
+        } catch (e: Throwable) {
+            Log.e(TAG, "install failed", e)
+            false
+        }
+    }
+
+    private fun verifyAssetArchiveReadable(
+        context: Context,
+        path: String,
+        bundlePath: String
+    ): Boolean {
+        return try {
+            val packageContext = context.createPackageContext(context.packageName, 0)
+            addAssetPathTo(packageContext, path, bundlePath, verifyManifest = true)
+        } catch (e: Throwable) {
+            Log.e(TAG, "createPackageContext asset patch failed", e)
+            false
+        }
+    }
+
+    private fun installPatchedFlutterJniFactory(
+        injector: FlutterInjector,
+        context: Context,
+        archivePath: String,
+        bundlePath: String
+    ) {
+        val field = injector.javaClass.getDeclaredField("flutterJniFactory")
+        field.isAccessible = true
+        field.set(
+            injector,
+            PatchedFlutterJniFactory(context.applicationContext, archivePath, bundlePath)
+        )
+        Log.d(TAG, "FlutterJNI factory patched for asset bundle=$bundlePath")
+    }
+
+    private class PatchedFlutterJniFactory(
+        private val context: Context,
+        private val archivePath: String,
+        private val bundlePath: String
+    ) : FlutterJNI.Factory() {
+        override fun provideFlutterJNI(): FlutterJNI {
+            return PatchedFlutterJNI(context, archivePath, bundlePath)
+        }
+    }
+
+    private class PatchedFlutterJNI(
+        private val context: Context,
+        private val archivePath: String,
+        private val bundlePath: String
+    ) : FlutterJNI() {
+        override fun runBundleAndSnapshotFromLibrary(
+            bundlePath: String,
+            entrypointFunctionName: String?,
+            pathToEntrypointFunction: String?,
+            assetManager: android.content.res.AssetManager,
+            entrypointArgs: MutableList<String>?,
+            engineId: Long
+        ) {
+            try {
+                val packageContext = context.createPackageContext(context.packageName, 0)
+                if (addAssetPathTo(packageContext, archivePath, this.bundlePath)) {
+                    super.runBundleAndSnapshotFromLibrary(
+                        this.bundlePath,
+                        entrypointFunctionName,
+                        pathToEntrypointFunction,
+                        packageContext.assets,
+                        entrypointArgs,
+                        engineId
+                    )
+                    return
+                }
+            } catch (e: Throwable) {
+                Log.e(TAG, "patched FlutterJNI asset setup failed", e)
+            }
+            super.runBundleAndSnapshotFromLibrary(
+                bundlePath,
+                entrypointFunctionName,
+                pathToEntrypointFunction,
+                assetManager,
+                entrypointArgs,
+                engineId
+            )
+        }
+    }
+
+    private fun addAssetPathTo(
+        context: Context,
+        path: String,
+        bundlePath: String?,
+        verifyManifest: Boolean = false
+    ): Boolean {
+        val method = context.assets.javaClass.getMethod("addAssetPath", String::class.java)
+        val cookie = method.invoke(context.assets, path) as? Int ?: 0
+        if (cookie == 0) {
+            Log.e(TAG, "AssetManager rejected asset archive: $path")
+            return false
+        }
+        if (verifyManifest && !bundlePath.isNullOrEmpty()) {
+            val manifestPath = "${bundlePath.trimEnd('/')}/AssetManifest.bin"
+            try {
+                context.assets.open(manifestPath).use { input ->
+                    input.read()
+                }
+            } catch (e: Throwable) {
+                Log.e(TAG, "AssetManager self-check failed for $manifestPath", e)
+                return false
+            }
+        }
+        return true
+    }
+
+    private fun buildCandidates(context: Context): List<String> {
+        val override = PatcherConfig.loaderFieldCandidates(context)
+        return if (override.isNotEmpty()) override + DEFAULT_CANDIDATES.filter { it !in override }
+        else DEFAULT_CANDIDATES
+    }
+
+    /**
+     * 定位 FlutterLoader 字段：
+     * 1. 按候选名精确匹配（安全）
+     * 2. 按类型精确匹配：字段类型是 FlutterLoader 或其子类（安全）
+     * 3. 启发式回退：首个非 static、非 ExecutorService 的实例字段（**可能命错字段**）
+     *
+     * Layer 3 默认关闭：宁可退回内置 .so，也不要瞎设字段导致不可预测的崩溃。
+     * 通过 FlutterPatcher.init(loaderFallbackHeuristic: true) 显式启用。
+     */
+    private fun findLoaderField(
+        clazz: Class<*>,
+        candidates: List<String>,
+        heuristic: Boolean
+    ): Field? {
+        for (name in candidates) {
+            try {
+                return clazz.getDeclaredField(name)
+            } catch (_: NoSuchFieldException) {
+                // continue
+            }
+        }
+        Log.w(TAG, "no exact-name match, falling back to type-based detection")
+
+        clazz.declaredFields
+            .firstOrNull { FlutterLoader::class.java.isAssignableFrom(it.type) }
+            ?.let { return it }
+
+        if (!heuristic) {
+            Log.w(TAG, "type-based match failed; heuristic disabled, giving up")
+            return null
+        }
+        Log.w(TAG, "type-based match failed; using heuristic (may pick wrong field)")
+        return clazz.declaredFields.firstOrNull {
+            !Modifier.isStatic(it.modifiers) &&
+                it.type != ExecutorService::class.java
+        }
+    }
+}
+
+/**
+ * 自定义 FlutterLoader：通过 `--aot-shared-library-name` 参数让 Flutter Engine
+ * 从补丁路径加载 libapp.so，替代 APK 内置版本。
+ *
+ * `--aot-shared-library-name=<path>` 从 Flutter 1.x 开始一直稳定存在，跨大版本兼容。
+ */
+internal fun patchedAssetLookupKey(patchAssetsPath: String, asset: String): String {
+    return "${patchAssetsPath.trimEnd('/')}/${asset.trimStart('/')}"
+}
+
+internal fun patchedPackageAssetLookupKey(
+    patchAssetsPath: String,
+    asset: String,
+    packageName: String
+): String {
+    return patchedAssetLookupKey(patchAssetsPath, "packages/$packageName/$asset")
+}
+
+internal class PatchedFlutterLoader(
+    private val patchSoPath: String,
+    private val patchAssetsPath: String? = null,
+) : FlutterLoader() {
+
+    companion object {
+        private const val TAG = "FlutterPatcher/Loader"
+    }
+
+    override fun ensureInitializationComplete(context: Context, args: Array<String>?) {
+        val patched = (args ?: emptyArray()).toMutableList()
+        patched.add("--aot-shared-library-name=$patchSoPath")
+        if (!patchAssetsPath.isNullOrEmpty()) {
+            patched.add("--flutter-assets-dir=$patchAssetsPath")
+        }
+        Log.d(TAG, "load patch: so=$patchSoPath assets=${patchAssetsPath ?: "<built-in>"}")
+        super.ensureInitializationComplete(context, patched.toTypedArray())
+    }
+
+    override fun findAppBundlePath(): String {
+        return patchAssetsPath ?: super.findAppBundlePath()
+    }
+
+    override fun getLookupKeyForAsset(asset: String): String {
+        return patchAssetsPath?.let { patchedAssetLookupKey(it, asset) }
+            ?: super.getLookupKeyForAsset(asset)
+    }
+
+    override fun getLookupKeyForAsset(asset: String, packageName: String): String {
+        return patchAssetsPath?.let { patchedPackageAssetLookupKey(it, asset, packageName) }
+            ?: super.getLookupKeyForAsset(asset, packageName)
+    }
+}