@_nazmiforreal/flutter-ota 0.1.26 → 0.1.28

package/dart-src/root/android/build.gradle

@@ -0,0 +1,116 @@
+group = "com.flutter_patcher.flutter_patcher"
+version = "1.0-SNAPSHOT"
+
+buildscript {
+    ext.kotlin_version = "2.2.20"
+    repositories {
+        google()
+        mavenCentral()
+    }
+
+    dependencies {
+        classpath("com.android.tools.build:gradle:8.11.1")
+        classpath("org.jetbrains.kotlin:kotlin-gradle-plugin:$kotlin_version")
+    }
+}
+
+allprojects {
+    repositories {
+        google()
+        mavenCentral()
+    }
+}
+
+apply plugin: "com.android.library"
+
+// AGP 9 compiles Kotlin itself ("built-in Kotlin") and rejects the
+// kotlin-android plugin. AGP 9 hosts that opt out via
+// `android.builtInKotlin=false` -- which is what the Flutter 3.44 template
+// generates -- still need us to bring our own KGP, exactly like AGP 8 hosts.
+// So the switch is built-in Kotlin, not the AGP major on its own.
+def agpMajor = com.android.Version.ANDROID_GRADLE_PLUGIN_VERSION.tokenize('.')[0] as int
+def builtInKotlinFlag = project.findProperty("android.builtInKotlin")
+def builtInKotlin = agpMajor >= 9 &&
+    (builtInKotlinFlag == null || Boolean.parseBoolean(builtInKotlinFlag.toString()))
+
+// Keep this as a literal `apply plugin:` at line start even though it is
+// guarded. The Flutter Gradle Plugin regex-matches this file's text to decide
+// whether a subproject brings its own KGP; when it finds none it applies
+// kotlin-android to us itself, which hard-fails under built-in Kotlin. The cost
+// is that FGP prints its "plugin applies KGP" warning on AGP 9 even when this
+// branch never runs.
+if (!builtInKotlin) {
+    apply plugin: "kotlin-android"
+}
+
+tasks.withType(org.jetbrains.kotlin.gradle.tasks.KotlinCompile).configureEach {
+    // Kotlin incremental cache path relativization can fail on Windows when a
+    // Flutter plugin is compiled from Pub Cache on C: into an app on another
+    // drive. Keep this library compile non-incremental; app modules are
+    // unaffected.
+    incremental = false
+}
+
+android {
+    namespace = "com.flutter_patcher.flutter_patcher"
+
+    compileSdk = 36
+    ndkVersion = "27.0.12077973"
+
+    compileOptions {
+        sourceCompatibility = JavaVersion.VERSION_17
+        targetCompatibility = JavaVersion.VERSION_17
+    }
+
+    if (!builtInKotlin) {
+        // Contributed by KGP, not by AGP -- only exists where KGP was applied.
+        kotlinOptions {
+            jvmTarget = JavaVersion.VERSION_17
+        }
+    }
+
+    sourceSets {
+        main.java.srcDirs += "src/main/kotlin"
+        test.java.srcDirs += "src/test/kotlin"
+    }
+
+    defaultConfig {
+        minSdk = 24
+
+        // ABI 白名单：覆盖主流 Android 设备。Flutter 默认只出 arm64-v8a，
+        // 但插件要兼容 32 位旧机型和 x86_64 模拟器。
+        ndk {
+            abiFilters 'armeabi-v7a', 'arm64-v8a', 'x86_64'
+        }
+
+        // 让 AGP 把本插件的 consumer R8 规则合并到宿主 release build
+        consumerProguardFiles 'consumer-rules.pro'
+    }
+
+    dependencies {
+        testImplementation("org.jetbrains.kotlin:kotlin-test")
+        testImplementation("org.json:json:20240303")
+        testImplementation("org.mockito:mockito-core:5.0.0")
+    }
+
+    testOptions {
+        unitTests.all {
+            useJUnitPlatform()
+            jvmArgs "-Dnet.bytebuddy.experimental=true"
+
+            testLogging {
+               events "passed", "skipped", "failed", "standardOut", "standardError"
+               outputs.upToDateWhen {false}
+               showStandardStreams = true
+            }
+        }
+    }
+}
+
+if (builtInKotlin) {
+    kotlin {
+        compilerOptions {
+            jvmTarget = org.jetbrains.kotlin.gradle.dsl.JvmTarget.JVM_17
+        }
+    }
+}

package/dart-src/root/android/consumer-rules.pro

@@ -0,0 +1,23 @@
+# flutter_patcher consumer ProGuard / R8 rules.
+# AGP merges this file into the host app release R8 configuration.
+# Goal: keep the small set of Android / Flutter classes referenced by manifest
+# entries or startup reflection.
+
+# Application: referenced by AndroidManifest android:name.
+-keep class com.flutter_patcher.flutter_patcher.FlutterPatcherApplication { *; }
+
+# Auto-init ContentProvider: declared by the plugin manifest.
+-keep class com.flutter_patcher.flutter_patcher.FlutterPatcherAutoInitProvider { *; }
+
+# Flutter plugin: registered by GeneratedPluginRegistrant.
+-keep class com.flutter_patcher.flutter_patcher.FlutterPatcherPlugin { *; }
+
+# PatchedFlutterLoader is installed reflectively and overrides engine init.
+-keep class com.flutter_patcher.flutter_patcher.PatchedFlutterLoader {
+    <init>(...);
+    public void ensureInitializationComplete(android.content.Context, java.lang.String[]);
+}
+
+# Flutter Engine reflection targets used by LoaderHook.
+-keep class io.flutter.FlutterInjector { *; }
+-keep class io.flutter.embedding.engine.loader.FlutterLoader { *; }

package/dart-src/root/android/settings.gradle

@@ -0,0 +1 @@
+rootProject.name = 'flutter_patcher'

package/dart-src/root/android/src/main/AndroidManifest.xml

@@ -0,0 +1,21 @@
+<manifest xmlns:android="http://schemas.android.com/apk/res/android"
+  package="com.flutter_patcher.flutter_patcher">
+  <!-- 宿主 App 必须自行声明 INTERNET 权限以允许补丁下载 / checkUpdate 发起 HTTP 请求 -->
+
+  <application>
+    <!--
+      自动初始化：在 ContentProvider.onCreate 阶段（早于 Application.onCreate /
+      任何 FlutterActivity.onCreate）完成熔断检查 + FlutterLoader 反射替换，宿主
+      无需接入 Application。
+
+      需要关掉的极少数场景（如在 Application.attachBaseContext 预热 FlutterEngine）
+      可在宿主 Manifest 里用 tools:node="remove" 移除本 provider，然后显式调
+      FlutterPatcherApplication.attachPatcher(base)。详见 README。
+    -->
+    <provider
+      android:name="com.flutter_patcher.flutter_patcher.FlutterPatcherAutoInitProvider"
+      android:authorities="${applicationId}.flutter_patcher.autoinit"
+      android:exported="false"
+      android:initOrder="100" />
+  </application>
+</manifest>

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

@@ -0,0 +1,52 @@
+package com.flutter_patcher.flutter_patcher
+
+/**
+ * [PatchManager.applyPatch] 的结构化返回值。
+ *
+ * 通过 MethodChannel 以 `Map<String, Any?>` 形式序列化到 Dart 侧，由
+ * `PatchApplyResult.fromNative()` 反解。
+ *
+ * 错误码与使用建议见 [ApplyErrorCode]。
+ */
+internal data class ApplyResult(
+    val ok: Boolean,
+    val errorCode: String? = null,
+    val message: String? = null
+) {
+    fun toMap(): Map<String, Any?> = mapOf(
+        "ok" to ok,
+        "error" to errorCode,
+        "message" to message
+    )
+
+    companion object {
+        val SUCCESS = ApplyResult(ok = true)
+
+        fun failure(code: String, message: String? = null): ApplyResult =
+            ApplyResult(ok = false, errorCode = code, message = message)
+    }
+}
+
+/**
+ * applyPatch 可能的失败原因。调用方（Dart 业务层）按需要做不同处理：
+ *
+ * - [INVALID_ARGS]：服务端下发的 JSON 缺字段 → 告警服务端
+ * - [BLACKLISTED]：(version, md5) 已在本地黑名单 → 服务端告警，下架补丁
+ * - [NETWORK]：下载失败（重试后依然失败）→ 稍后重试
+ * - [MD5_MISMATCH]：下载文件 md5 不匹配 → CDN 脏数据或服务端 md5 算错，检查后重试
+ * - [SIGNATURE_INVALID]：Ed25519 验签失败（或 strict 模式下 API < 33 直接拒绝）→
+ *   可能被篡改，**不建议**自动重试
+ * - [IO_ERROR]：磁盘 / 文件系统错误（磁盘满、权限）→ 稍后重试
+ * - [UNKNOWN]：未被分类的异常 → 上报到监控，看日志定位
+ */
+internal object ApplyErrorCode {
+    const val INVALID_ARGS = "INVALID_ARGS"
+    const val BLACKLISTED = "BLACKLISTED"
+    const val NETWORK = "NETWORK"
+    const val MD5_MISMATCH = "MD5_MISMATCH"
+    const val SIGNATURE_INVALID = "SIGNATURE_INVALID"
+    const val UNSUPPORTED_ABI = "UNSUPPORTED_ABI"
+    const val ASSET_PACKAGE_INVALID = "ASSET_PACKAGE_INVALID"
+    const val IO_ERROR = "IO_ERROR"
+    const val UNKNOWN = "UNKNOWN"
+}

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

@@ -0,0 +1,154 @@
+package com.flutter_patcher.flutter_patcher
+
+import android.content.Context
+import android.util.Log
+import org.json.JSONArray
+import org.json.JSONObject
+
+/**
+ * 已知"装上就出事"的补丁本地黑名单。
+ *
+ * # 为什么需要
+ * 没有黑名单时，若服务端持续下发同一个有问题的补丁：
+ * 客户端下载 → 校验通过 → 装上 → 启动崩溃 → 自动回滚 → 下次又收到 → 死循环。
+ * 黑名单把"已经验证过的坏补丁"记下来，再次下发直接拒，连流量都不浪费。
+ *
+ * # 双键设计 (version, md5)
+ * - 只用 `version`：开发者修了 bug 后用同样 version 重发会被无脑拒绝
+ * - 只用 `md5`：可读性差，debug 时不知道是哪个补丁
+ * - 用 (version, md5) 同时作为复合键：不同 md5 视作"修了再试"，允许下载
+ *
+ * # 持久性
+ * **不**因 APK 版本升级清空。否则线上事故时若服务端配置忘下架，升 APK 后又
+ * 能下到坏补丁。除非用户主动调 [clear]，黑名单条目永久保留。
+ *
+ * # 容量
+ * FIFO 上限 [MAX_ENTRIES]=50，超出按时间淘汰最老条目。极端情况下避免无限增长。
+ */
+internal object BlacklistStore {
+
+    private const val TAG = "FlutterPatcher/Blacklist"
+
+    /** SharedPreferences key（沿用 PatcherConfig.PREFS_NAME 文件，与现有键无冲突）。*/
+    private const val KEY_BLACKLIST = "patch_blacklist"
+
+    /** 黑名单条目数上限，达到后 FIFO 淘汰最早入黑的条目。*/
+    const val MAX_ENTRIES = 50
+
+    // ---- 入黑原因常量（与 BootDiagnosticStore 命名风格保持一致）----
+
+    const val REASON_BOOT_CRASH = "BOOT_CRASH"
+    const val REASON_MD5_MISMATCH = "MD5_MISMATCH"
+    const val REASON_SIGNATURE_INVALID = "SIGNATURE_INVALID"
+    const val REASON_META_CORRUPTED = "META_CORRUPTED"
+    const val REASON_APPLY_FAILED = "APPLY_FAILED"
+
+    // ---- 字段 key ----
+
+    private const val FIELD_VERSION = "version"
+    private const val FIELD_MD5 = "md5"
+    private const val FIELD_REASON = "reason"
+    private const val FIELD_BLACKLISTED_AT = "blacklistedAt"
+
+    /**
+     * 把 (version, md5) 加入黑名单。重复 add 会更新 reason + 时间戳，不会出现重复条目。
+     * version 或 md5 为空字符串则忽略（防御性，不进黑名单）。
+     */
+    @Synchronized
+    fun add(context: Context, version: String, md5: String, reason: String) {
+        if (version.isEmpty() || md5.isEmpty()) {
+            Log.w(TAG, "skip blacklist entry: version='$version' md5='$md5'")
+            return
+        }
+        val arr = readArray(context)
+        // 找到旧条目并删除（按双键），再追加到末尾，达到"重复 add 时刷新位置 + 元数据"的语义
+        val md5Lower = md5.lowercase()
+        val filtered = JSONArray()
+        for (i in 0 until arr.length()) {
+            val obj = arr.optJSONObject(i) ?: continue
+            val v = obj.optString(FIELD_VERSION)
+            val m = obj.optString(FIELD_MD5)
+            if (v == version && m == md5Lower) continue
+            filtered.put(obj)
+        }
+        filtered.put(JSONObject().apply {
+            put(FIELD_VERSION, version)
+            put(FIELD_MD5, md5Lower)
+            put(FIELD_REASON, reason)
+            put(FIELD_BLACKLISTED_AT, System.currentTimeMillis())
+        })
+        // FIFO 淘汰：超过上限就丢最老的
+        val capped = if (filtered.length() > MAX_ENTRIES) {
+            val drop = filtered.length() - MAX_ENTRIES
+            val sliced = JSONArray()
+            for (i in drop until filtered.length()) sliced.put(filtered.opt(i))
+            sliced
+        } else {
+            filtered
+        }
+        PatcherConfig.prefs(context).edit()
+            .putString(KEY_BLACKLIST, capped.toString())
+            .commit()
+        Log.w(TAG, "blacklisted version=$version md5=$md5Lower reason=$reason (${capped.length()}/$MAX_ENTRIES)")
+    }
+
+    /** 命中 (version, md5) 双键则返回 true。md5 大小写不敏感比较。*/
+    fun contains(context: Context, version: String, md5: String): Boolean {
+        if (version.isEmpty() || md5.isEmpty()) return false
+        val arr = readArray(context)
+        val md5Lower = md5.lowercase()
+        for (i in 0 until arr.length()) {
+            val obj = arr.optJSONObject(i) ?: continue
+            if (obj.optString(FIELD_VERSION) == version &&
+                obj.optString(FIELD_MD5).equals(md5Lower, ignoreCase = true)
+            ) {
+                return true
+            }
+        }
+        return false
+    }
+
+    /**
+     * 仅以 version 维度命中黑名单。供"调用方未下发 md5"场景的下载前置检查。
+     * 同 version 任意 md5 条目都视为命中。
+     */
+    fun containsByVersion(context: Context, version: String): Boolean {
+        if (version.isEmpty()) return false
+        val arr = readArray(context)
+        for (i in 0 until arr.length()) {
+            val obj = arr.optJSONObject(i) ?: continue
+            if (obj.optString(FIELD_VERSION) == version) return true
+        }
+        return false
+    }
+
+    /** 全部黑名单条目（旧→新顺序）。供 Dart 业务侧查询展示用。*/
+    fun entries(context: Context): List<Map<String, Any?>> {
+        val arr = readArray(context)
+        return List(arr.length()) { i ->
+            val obj = arr.optJSONObject(i)
+            mapOf(
+                FIELD_VERSION to obj?.optString(FIELD_VERSION),
+                FIELD_MD5 to obj?.optString(FIELD_MD5),
+                FIELD_REASON to obj?.optString(FIELD_REASON),
+                FIELD_BLACKLISTED_AT to (obj?.optLong(FIELD_BLACKLISTED_AT) ?: 0L),
+            )
+        }
+    }
+
+    /** 清空整个黑名单。慎用：通常只在调试时调用。*/
+    fun clear(context: Context) {
+        PatcherConfig.prefs(context).edit().remove(KEY_BLACKLIST).commit()
+        Log.w(TAG, "blacklist cleared")
+    }
+
+    private fun readArray(context: Context): JSONArray {
+        val raw = PatcherConfig.prefs(context).getString(KEY_BLACKLIST, null) ?: return JSONArray()
+        return try {
+            JSONArray(raw)
+        } catch (e: Exception) {
+            Log.w(TAG, "blacklist json corrupt, resetting", e)
+            JSONArray()
+        }
+    }
+}

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

@@ -0,0 +1,150 @@
+package com.flutter_patcher.flutter_patcher
+
+import android.content.Context
+import android.util.Log
+import org.json.JSONArray
+import org.json.JSONObject
+
+/**
+ * 上次冷启动时补丁加载结果的持久化存储。
+ *
+ * 现状：补丁能否生效取决于 `CrashGuard` / `PatchManager.getValidPatchPath` /
+ * `LoaderHook.install` 三处决策，事件只写 logcat。线上业务只能事后通过
+ * [PatchManager.currentVersion] 间接推测"补丁是不是又没了"，监控/告警接不上。
+ *
+ * 本对象在每次冷启动时把"补丁的加载结果 + 上下文"一次性覆写到
+ * SharedPreferences，Dart 侧通过 `FlutterPatcher.lastBootDiagnostic` 查询。
+ *
+ * # 写入时机
+ * - [FlutterPatcherApplication.attachPatcher] 三个出口（patched / hookFailed / noPatch / unknown）
+ * - [PatchManager.getValidPatchPath] 通过传入的 onDrop 闭包写入（versionCode/md5/sig/meta）
+ * - [CrashGuard.shouldLoadPatch] 通过传入的 onDrop 闭包写入（circuit breaker）
+ *
+ * # 跨边界约定
+ * status 用大写 SCREAMING_SNAKE 字符串而非 int，保证 Kotlin / Dart 两侧可读性 +
+ * 未来扩展不破坏序列化兼容。Dart 侧用 [PatchBootStatus] 枚举映射。
+ */
+internal object BootDiagnosticStore {
+
+    private const val TAG = "FlutterPatcher/Diag"
+
+    /** SharedPreferences key（沿用 PatcherConfig.PREFS_NAME 文件，与现有键无冲突）。*/
+    private const val KEY_LAST_BOOT_DIAG = "last_boot_diagnostic"
+
+    // ---- status 常量（与 Dart 侧 PatchBootStatus 一一对应）----
+
+    /** 未安装补丁，使用 APK 内置 libapp.so。属于正常状态。*/
+    const val NO_PATCH = "NO_PATCH"
+
+    /** 补丁加载成功，本次启动按补丁运行。*/
+    const val PATCHED = "PATCHED"
+
+    /** 补丁被丢弃：targetVersionCode 与当前 APK versionCode 不匹配。*/
+    const val DROPPED_VERSION_CODE_MISMATCH = "DROPPED_VERSION_CODE_MISMATCH"
+
+    /** 补丁被丢弃：本地 .so 文件 md5 与 meta.effectiveMd5 不一致。*/
+    const val DROPPED_MD5_MISMATCH = "DROPPED_MD5_MISMATCH"
+
+    /** 补丁被丢弃：Ed25519 签名校验失败 / 严格模式下 API < 33。*/
+    const val DROPPED_SIGNATURE_INVALID = "DROPPED_SIGNATURE_INVALID"
+
+    /** 补丁被丢弃：meta.json 损坏或缺关键字段（effectiveMd5 等）。*/
+    const val DROPPED_META_CORRUPTED = "DROPPED_META_CORRUPTED"
+
+    /** 补丁被丢弃：连续启动失败累计 >= maxCrashCount，熔断器触发。*/
+    const val DROPPED_CIRCUIT_BREAKER = "DROPPED_CIRCUIT_BREAKER"
+
+    /** 补丁文件保留，但反射替换 FlutterLoader 失败，本次启动用了内置 .so。*/
+    const val HOOK_INSTALL_FAILED = "HOOK_INSTALL_FAILED"
+
+    /** attachPatcher 阶段抛出未分类异常。*/
+    const val UNKNOWN = "UNKNOWN"
+
+    // ---- 字段 key（写入 / 读取共用）----
+
+    private const val FIELD_STATUS = "status"
+    private const val FIELD_PATCH_VERSION = "patchVersion"
+    private const val FIELD_PATCH_TARGET_VC = "patchTargetVersionCode"
+    private const val FIELD_APP_VC = "appVersionCode"
+    private const val FIELD_CRASH_COUNT = "crashCount"
+    private const val FIELD_ATTEMPTED_LOADER_FIELDS = "attemptedLoaderFields"
+    private const val FIELD_MESSAGE = "message"
+    private const val FIELD_RECORDED_AT = "recordedAt"
+
+    /**
+     * 覆写一条诊断记录。
+     *
+     * 使用 commit 同步写入：本方法常在 attachBaseContext 阶段调用，若进程随后
+     * 因补丁问题崩溃，commit 能保证下次启动 Dart 侧仍能查询到本次的诊断结果。
+     */
+    fun record(
+        context: Context,
+        status: String,
+        patchVersion: String? = null,
+        patchTargetVersionCode: Long? = null,
+        appVersionCode: Long? = null,
+        crashCount: Int? = null,
+        attemptedLoaderFields: List<String>? = null,
+        message: String? = null,
+    ) {
+        val json = JSONObject().apply {
+            put(FIELD_STATUS, status)
+            putOpt(FIELD_PATCH_VERSION, patchVersion)
+            putOpt(FIELD_PATCH_TARGET_VC, patchTargetVersionCode)
+            putOpt(FIELD_APP_VC, appVersionCode)
+            putOpt(FIELD_CRASH_COUNT, crashCount)
+            if (attemptedLoaderFields != null) {
+                put(FIELD_ATTEMPTED_LOADER_FIELDS, JSONArray(attemptedLoaderFields))
+            }
+            putOpt(FIELD_MESSAGE, message)
+            put(FIELD_RECORDED_AT, System.currentTimeMillis())
+        }
+        PatcherConfig.prefs(context).edit()
+            .putString(KEY_LAST_BOOT_DIAG, json.toString())
+            .commit()
+        Log.d(TAG, "record status=$status patch=$patchVersion msg=$message")
+    }
+
+    /**
+     * 读取最近一次 record。
+     *
+     * @return 诊断 Map，可直接交给 MethodChannel 发到 Dart 侧；
+     *         null 表示从未 record 过（首次安装或 pm clear 后第一次启动且尚未到首帧）。
+     */
+    fun read(context: Context): Map<String, Any?>? {
+        val raw = PatcherConfig.prefs(context).getString(KEY_LAST_BOOT_DIAG, null) ?: return null
+        return try {
+            val json = JSONObject(raw)
+            val map = mutableMapOf<String, Any?>()
+            map[FIELD_STATUS] = json.optString(FIELD_STATUS, UNKNOWN)
+            map[FIELD_PATCH_VERSION] = json.optStringOrNull(FIELD_PATCH_VERSION)
+            map[FIELD_PATCH_TARGET_VC] = json.optLongOrNull(FIELD_PATCH_TARGET_VC)
+            map[FIELD_APP_VC] = json.optLongOrNull(FIELD_APP_VC)
+            map[FIELD_CRASH_COUNT] = json.optIntOrNull(FIELD_CRASH_COUNT)
+            map[FIELD_ATTEMPTED_LOADER_FIELDS] = json.optStringListOrNull(FIELD_ATTEMPTED_LOADER_FIELDS)
+            map[FIELD_MESSAGE] = json.optStringOrNull(FIELD_MESSAGE)
+            map[FIELD_RECORDED_AT] = json.optLong(FIELD_RECORDED_AT, 0L)
+            map
+        } catch (e: Exception) {
+            Log.w(TAG, "read failed, raw=$raw", e)
+            null
+        }
+    }
+
+    // ---- 内部工具：JSONObject 缺字段时返回 null 而非 "" / 0 ----
+
+    private fun JSONObject.optStringOrNull(key: String): String? =
+        if (isNull(key) || !has(key)) null else optString(key, "").ifEmpty { null }
+
+    private fun JSONObject.optLongOrNull(key: String): Long? =
+        if (isNull(key) || !has(key)) null else optLong(key)
+
+    private fun JSONObject.optIntOrNull(key: String): Int? =
+        if (isNull(key) || !has(key)) null else optInt(key)
+
+    private fun JSONObject.optStringListOrNull(key: String): List<String>? {
+        if (isNull(key) || !has(key)) return null
+        val arr = optJSONArray(key) ?: return null
+        return List(arr.length()) { arr.optString(it) }
+    }
+}