@_nazmiforreal/flutter-ota 0.1.26 → 0.1.28

package/dart-src/root/lib/src/app_version_resolver.dart

@@ -0,0 +1,36 @@
+import 'package:package_info_plus/package_info_plus.dart';
+
+/// Resolves the app version used for `appVersion`-strategy targeting.
+///
+/// If [configured] is non-empty it is honored (explicit override via
+/// `XxxUpdateConfig.appVersion` / `--dart-define=APP_VERSION`). Otherwise the
+/// real version is detected at runtime from the host app's `versionName` via
+/// `package_info_plus`. This prevents the silent failure where a missing or
+/// incorrect `APP_VERSION` made the client report a wrong version and the
+/// backend return no compatible bundle (`filterCompatibleAppVersions` then drops
+/// it).
+///
+/// Cached after the first successful detection so repeated update checks don't
+/// re-read `PackageInfo`.
+Future<String> resolveAppVersion(String? configured) async {
+  if (configured != null && configured.trim().isNotEmpty) return configured;
+  if (_cachedAppVersion != null) return _cachedAppVersion!;
+  var detected = '';
+  try {
+    final info = await PackageInfo.fromPlatform();
+    detected = info.version;
+  } catch (_) {
+    detected = '';
+  }
+  // Only cache a successful, non-empty detection. Caching '' would permanently
+  // pin the version to empty after a transient failure and silently break
+  // `appVersion`-strategy targeting forever. Callers retry on the next check.
+  if (detected.isNotEmpty) _cachedAppVersion = detected;
+  return detected;
+}
+
+String? _cachedAppVersion;
+
+/// Resets the cached detected app version. Intended for tests that need to
+/// re-run detection against a different [PackageInfo] (or simulate a failure).
+void resetAppVersionCache() => _cachedAppVersion = null;

package/dart-src/root/lib/src/aws_update_source.dart

@@ -0,0 +1,97 @@
+import 'package:flutter_ota_kit/src/pkg/core/flutter_ota_kit_core.dart'
+    show nilUuid, Platform, UpdateStrategy;
+import 'package:flutter_ota_kit/src/pkg/client/flutter_ota_kit_client.dart'
+    show ServerUpdateResult;
+import 'package:flutter_ota_kit/src/pkg/aws/flutter_ota_kit_aws.dart'
+    show s3Database, s3Storage, S3DatabaseConfig, AwsS3StorageConfig;
+
+import 'shared_update_check.dart';
+
+/// Configuration for an **AWS S3** update source.
+///
+/// Talks to AWS directly — an S3-backed blob database for bundle metadata and
+/// S3 (presigned URLs) for artifact storage — with no intermediate server.
+/// Optionally fronts downloads with CloudFront for a custom domain.
+class AwsUpdateConfig {
+  const AwsUpdateConfig({
+    required this.bucketName,
+    required this.region,
+    required this.accessKeyId,
+    required this.secretAccessKey,
+    this.basePath,
+    this.endpoint,
+    this.sessionToken,
+    this.cloudfrontDistributionId,
+    required this.channel,
+    required this.platform,
+    required this.updateStrategy,
+    this.appVersion,
+    this.fingerprintHash,
+    this.sdkVersion = '1.0.0',
+    this.cohort,
+    this.minBundleId = nilUuid,
+  });
+
+  final String bucketName;
+  final String region;
+  final String accessKeyId;
+  final String secretAccessKey;
+  final String? basePath;
+  final String? endpoint;
+  final String? sessionToken;
+  final String? cloudfrontDistributionId;
+  final String channel;
+  final Platform platform;
+  final UpdateStrategy updateStrategy;
+  final String? appVersion;
+  final String? fingerprintHash;
+  final String sdkVersion;
+  final String? cohort;
+  final String minBundleId;
+}
+
+class AwsUpdateSource {
+  const AwsUpdateSource();
+
+  Future<ServerUpdateResult> check(
+    AwsUpdateConfig config, {
+    String? currentBundleId,
+    Duration timeout = const Duration(seconds: 10),
+  }) async {
+    final dbConfig = S3DatabaseConfig(
+      bucketName: config.bucketName,
+      region: config.region,
+      accessKeyId: config.accessKeyId,
+      secretAccessKey: config.secretAccessKey,
+      basePath: config.basePath,
+      cloudfrontDistributionId: config.cloudfrontDistributionId,
+      endpoint: config.endpoint,
+      sessionToken: config.sessionToken,
+    );
+    final storageConfig = AwsS3StorageConfig(
+      bucketName: config.bucketName,
+      region: config.region,
+      accessKeyId: config.accessKeyId,
+      secretAccessKey: config.secretAccessKey,
+      basePath: config.basePath,
+      endpoint: config.endpoint,
+      sessionToken: config.sessionToken,
+    );
+
+    final db = s3Database(dbConfig)();
+    final storage = s3Storage(storageConfig);
+
+    return performSharedUpdateCheck(
+      db: db,
+      storage: storage,
+      channel: config.channel,
+      platform: config.platform,
+      updateStrategy: config.updateStrategy,
+      appVersion: config.appVersion,
+      fingerprintHash: config.fingerprintHash,
+      minBundleId: config.minBundleId,
+      currentBundleId: currentBundleId,
+      timeout: timeout,
+    );
+  }
+}

package/dart-src/root/lib/src/blacklist.dart

@@ -0,0 +1,54 @@
+import 'package:flutter/foundation.dart';
+
+/// A local patch blacklist entry. Mirrors the native `BlacklistStore` JSON shape.
+///
+/// Typical usage on the app side:
+/// ```dart
+/// final entries = await FlutterPatcher.blacklist;
+/// for (final e in entries) {
+///   debugPrint('blacklisted ${e.version} reason=${e.reason}');
+/// }
+/// ```
+@immutable
+class BlacklistEntry {
+  /// The blacklisted patch version (matches [PatchInfo.version]).
+  final String version;
+
+  /// The blacklisted patch md5 (lowercase hex).
+  final String md5;
+
+  /// The reason the patch was blacklisted (a native constant; passed as a string
+  /// across the platform boundary instead of an enum for forward compatibility).
+  /// Possible values:
+  /// - `BOOT_CRASH`: circuit breaker tripped after repeated boot failures
+  /// - `MD5_MISMATCH`: local file md5 verification failed
+  /// - `SIGNATURE_INVALID`: Ed25519 signature verification failed
+  /// - `APPLY_FAILED`: patch apply failed (download/install error)
+  final String reason;
+
+  /// When the entry was blacklisted.
+  final DateTime blacklistedAt;
+
+  const BlacklistEntry({
+    required this.version,
+    required this.md5,
+    required this.reason,
+    required this.blacklistedAt,
+  });
+
+  factory BlacklistEntry.fromNative(Map<dynamic, dynamic> raw) {
+    final map = Map<String, dynamic>.from(raw);
+    return BlacklistEntry(
+      version: (map['version'] as String?) ?? '',
+      md5: (map['md5'] as String?) ?? '',
+      reason: (map['reason'] as String?) ?? '',
+      blacklistedAt: DateTime.fromMillisecondsSinceEpoch(
+        ((map['blacklistedAt'] as num?) ?? 0).toInt(),
+      ),
+    );
+  }
+
+  @override
+  String toString() =>
+      'BlacklistEntry(version=$version, md5=$md5, reason=$reason, at=$blacklistedAt)';
+}

package/dart-src/root/lib/src/boot_diagnostic.dart

@@ -0,0 +1,138 @@
+import 'package:flutter/foundation.dart';
+
+/// Last cold-start patch loading decision.
+///
+/// Apply-time failures are reported by `PatchApplyError`. After a patch is
+/// installed, the next cold start can still drop it because of version mismatch,
+/// md5/signature failure, crash rollback, or loader hook failure. This enum
+/// exposes those native decisions to Dart for monitoring.
+enum PatchBootStatus {
+  /// No local patch is installed or loaded.
+  noPatch,
+
+  /// This cold start loaded the patch.
+  patched,
+
+  /// The patch target versionCode does not match the installed APK.
+  droppedVersionCodeMismatch,
+
+  /// Cold-start validation found that local `libapp_patch.so` no longer
+  /// matches metadata.
+  droppedMd5Mismatch,
+
+  /// Cold-start signature validation failed.
+  droppedSignatureInvalid,
+
+  /// Metadata or required patch artifacts are missing or corrupt on disk.
+  ///
+  /// For asset patches, the on-disk asset bundle the install step produced
+  /// is missing or unreadable — typically caused by the patch directory
+  /// being partially wiped between install and boot.
+  droppedMetaCorrupted,
+
+  /// Crash protection tripped after consecutive early boot failures.
+  droppedCircuitBreaker,
+
+  /// Loader injection failed; this launch used the APK built-in version.
+  hookInstallFailed,
+
+  /// Unclassified startup failure.
+  unknown,
+}
+
+PatchBootStatus _parseStatus(String? raw) {
+  switch (raw) {
+    case 'NO_PATCH':
+      return PatchBootStatus.noPatch;
+    case 'PATCHED':
+      return PatchBootStatus.patched;
+    case 'DROPPED_VERSION_CODE_MISMATCH':
+      return PatchBootStatus.droppedVersionCodeMismatch;
+    case 'DROPPED_MD5_MISMATCH':
+      return PatchBootStatus.droppedMd5Mismatch;
+    case 'DROPPED_SIGNATURE_INVALID':
+      return PatchBootStatus.droppedSignatureInvalid;
+    case 'DROPPED_META_CORRUPTED':
+      return PatchBootStatus.droppedMetaCorrupted;
+    case 'DROPPED_CIRCUIT_BREAKER':
+      return PatchBootStatus.droppedCircuitBreaker;
+    case 'HOOK_INSTALL_FAILED':
+      return PatchBootStatus.hookInstallFailed;
+    default:
+      return PatchBootStatus.unknown;
+  }
+}
+
+/// Structured diagnostic for the last cold-start patch decision.
+@immutable
+class PatchBootDiagnostic {
+  /// Cold-start patch loading result.
+  final PatchBootStatus status;
+
+  /// Patch version involved in the decision.
+  ///
+  /// For dropped patches this is the dropped version when metadata is readable.
+  final String? patchVersion;
+
+  /// Patch target versionCode, mainly used for version mismatch diagnostics.
+  final int? patchTargetVersionCode;
+
+  /// Current host APK versionCode.
+  final int? appVersionCode;
+
+  /// Crash count when the circuit breaker tripped.
+  final int? crashCount;
+
+  /// FlutterInjector loader field candidates attempted when hook install failed.
+  final List<String>? attemptedLoaderFields;
+
+  /// Time when this diagnostic was recorded.
+  final DateTime recordedAt;
+
+  /// Developer-facing diagnostic message. Do not show directly to end users.
+  final String? message;
+
+  const PatchBootDiagnostic({
+    required this.status,
+    required this.recordedAt,
+    this.patchVersion,
+    this.patchTargetVersionCode,
+    this.appVersionCode,
+    this.crashCount,
+    this.attemptedLoaderFields,
+    this.message,
+  });
+
+  /// Whether the last boot state is normal for business monitoring.
+  bool get isHealthy =>
+      status == PatchBootStatus.patched || status == PatchBootStatus.noPatch;
+
+  /// Deserializes the native MethodChannel map.
+  factory PatchBootDiagnostic.fromNative(Map<dynamic, dynamic> raw) {
+    final map = Map<String, dynamic>.from(raw);
+    final fields = map['attemptedLoaderFields'];
+    return PatchBootDiagnostic(
+      status: _parseStatus(map['status'] as String?),
+      patchVersion: map['patchVersion'] as String?,
+      patchTargetVersionCode: (map['patchTargetVersionCode'] as num?)?.toInt(),
+      appVersionCode: (map['appVersionCode'] as num?)?.toInt(),
+      crashCount: (map['crashCount'] as num?)?.toInt(),
+      attemptedLoaderFields: fields is List
+          ? List<String>.from(fields.map((e) => e?.toString() ?? ''))
+          : null,
+      recordedAt: DateTime.fromMillisecondsSinceEpoch(
+        ((map['recordedAt'] as num?) ?? 0).toInt(),
+      ),
+      message: map['message'] as String?,
+    );
+  }
+
+  @override
+  String toString() =>
+      'PatchBootDiagnostic(${status.name}'
+      '${patchVersion != null ? ', v=$patchVersion' : ''}'
+      '${patchTargetVersionCode != null ? ', patchVc=$patchTargetVersionCode' : ''}'
+      '${appVersionCode != null ? ', appVc=$appVersionCode' : ''}'
+      '${crashCount != null ? ', crashes=$crashCount' : ''}'
+      '${message != null ? ', msg=$message' : ''})';
+}

package/dart-src/root/lib/src/cloudflare_update_source.dart

@@ -0,0 +1,97 @@
+import 'package:flutter_ota_kit/src/pkg/core/flutter_ota_kit_core.dart'
+    show nilUuid, Platform, UpdateStrategy;
+import 'package:flutter_ota_kit/src/pkg/client/flutter_ota_kit_client.dart'
+    show ServerUpdateResult;
+import 'package:flutter_ota_kit/src/pkg/cloudflare/flutter_ota_kit_cloudflare.dart'
+    show d1Database, r2Storage, D1DatabaseConfig, R2S3StorageConfig;
+
+import 'shared_update_check.dart';
+
+/// Configuration for a **Cloudflare** update source.
+///
+/// Talks to Cloudflare directly — D1 for bundle metadata and R2 (S3-compatible)
+/// for artifact storage — with no intermediate server. Presigned R2 URLs are
+/// resolved on the device, exactly like [SupabaseUpdateConfig].
+class CloudflareUpdateConfig {
+  const CloudflareUpdateConfig({
+    // D1 (database)
+    required this.databaseId,
+    required this.accountId,
+    required this.cloudflareApiToken,
+    // R2 (storage)
+    required this.bucketName,
+    required this.accessKeyId,
+    required this.secretAccessKey,
+    this.basePath,
+    this.region = 'auto',
+    this.endpoint,
+    // targeting
+    required this.channel,
+    required this.platform,
+    required this.updateStrategy,
+    this.appVersion,
+    this.fingerprintHash,
+    this.sdkVersion = '1.0.0',
+    this.cohort,
+    this.minBundleId = nilUuid,
+  });
+
+  final String databaseId;
+  final String accountId;
+  final String cloudflareApiToken;
+  final String bucketName;
+  final String accessKeyId;
+  final String secretAccessKey;
+  final String? basePath;
+  final String region;
+  final String? endpoint;
+  final String channel;
+  final Platform platform;
+  final UpdateStrategy updateStrategy;
+  final String? appVersion;
+  final String? fingerprintHash;
+  final String sdkVersion;
+  final String? cohort;
+  final String minBundleId;
+}
+
+class CloudflareUpdateSource {
+  const CloudflareUpdateSource();
+
+  Future<ServerUpdateResult> check(
+    CloudflareUpdateConfig config, {
+    String? currentBundleId,
+    Duration timeout = const Duration(seconds: 10),
+  }) async {
+    final dbConfig = D1DatabaseConfig(
+      databaseId: config.databaseId,
+      accountId: config.accountId,
+      cloudflareApiToken: config.cloudflareApiToken,
+    );
+    final storageConfig = R2S3StorageConfig(
+      accountId: config.accountId,
+      bucketName: config.bucketName,
+      accessKeyId: config.accessKeyId,
+      secretAccessKey: config.secretAccessKey,
+      basePath: config.basePath,
+      region: config.region,
+      endpoint: config.endpoint,
+    );
+
+    final db = d1Database(dbConfig)();
+    final storage = r2Storage(storageConfig);
+
+    return performSharedUpdateCheck(
+      db: db,
+      storage: storage,
+      channel: config.channel,
+      platform: config.platform,
+      updateStrategy: config.updateStrategy,
+      appVersion: config.appVersion,
+      fingerprintHash: config.fingerprintHash,
+      minBundleId: config.minBundleId,
+      currentBundleId: currentBundleId,
+      timeout: timeout,
+    );
+  }
+}

package/dart-src/root/lib/src/flutter_ota_app.dart

@@ -0,0 +1,69 @@
+import 'package:flutter/widgets.dart';
+
+/// App-level host that lets [FlutterPatcher] show the forced-update progress
+/// overlay without the consuming app writing any UI code.
+///
+/// Wrap your app once:
+///
+/// ```dart
+/// void main() => runApp(FlutterOtaApp(child: MyApp()));
+/// ```
+///
+/// The overlay is injected via [MaterialApp.navigatorKey] — your [MaterialApp]
+/// must use [FlutterPatcher.navigatorKey]:
+///
+/// ```dart
+/// MaterialApp(
+///   navigatorKey: FlutterPatcher.navigatorKey,
+///   ...
+/// )
+/// ```
+///
+/// Set [showUpdateUi] to `false` to disable the built-in overlay entirely (the
+/// SDK still applies forced updates, just without the progress UI).
+class FlutterOtaApp extends StatefulWidget {
+  final Widget child;
+  final bool showUpdateUi;
+
+  const FlutterOtaApp({
+    super.key,
+    required this.child,
+    this.showUpdateUi = true,
+  });
+
+  @override
+  State<FlutterOtaApp> createState() => _FlutterOtaAppState();
+}
+
+class _FlutterOtaAppState extends State<FlutterOtaApp> {
+  @override
+  void initState() {
+    super.initState();
+    FlutterPatcherShowUpdateUiBinding.update(widget.showUpdateUi);
+  }
+
+  @override
+  void didUpdateWidget(covariant FlutterOtaApp oldWidget) {
+    super.didUpdateWidget(oldWidget);
+    if (oldWidget.showUpdateUi != widget.showUpdateUi) {
+      FlutterPatcherShowUpdateUiBinding.update(widget.showUpdateUi);
+    }
+  }
+
+  @override
+  Widget build(BuildContext context) => widget.child;
+}
+
+/// Internal binding between the widget-level [showUpdateUi] flag and the
+/// [FlutterPatcher] static flag, kept here so [flutter_ota_kit.dart] does not
+/// depend on the overlay widget directly.
+class FlutterPatcherShowUpdateUiBinding {
+  const FlutterPatcherShowUpdateUiBinding._();
+
+  static void update(bool value) {
+    // Imported lazily via the patch function set by the SDK entrypoint.
+    applyShowUpdateUi?.call(value);
+  }
+
+  static void Function(bool)? applyShowUpdateUi;
+}

package/dart-src/root/lib/src/io.dart

@@ -0,0 +1,48 @@
+import 'dart:convert';
+import 'dart:io';
+import 'dart:typed_data';
+
+bool get isAndroid => Platform.isAndroid;
+
+String get operatingSystem => Platform.operatingSystem;
+
+Future<Map<String, dynamic>> getJson(
+  String url, {
+  Map<String, String>? headers,
+  Duration timeout = const Duration(seconds: 10),
+}) async {
+  final uri = Uri.parse(url);
+  final client = HttpClient()..connectionTimeout = timeout;
+  try {
+    final req = await client.getUrl(uri).timeout(timeout);
+    headers?.forEach(req.headers.set);
+    req.headers.set(HttpHeaders.acceptHeader, 'application/json');
+    final resp = await req.close().timeout(timeout);
+    if (resp.statusCode < 200 || resp.statusCode >= 300) {
+      throw Exception('HTTP ${resp.statusCode}');
+    }
+    final body = await resp.transform(utf8.decoder).join();
+    final decoded = jsonDecode(body);
+    if (decoded is! Map) {
+      throw Exception('Invalid JSON: expected object');
+    }
+    return Map<String, dynamic>.from(decoded);
+  } finally {
+    client.close(force: true);
+  }
+}
+
+Future<String> stagePatchBytes(String dir, Uint8List bytes) async {
+  final staged = File(
+    '$dir/flutter_ota_kit_staged_${DateTime.now().microsecondsSinceEpoch}.so',
+  );
+  await staged.writeAsBytes(bytes, flush: true);
+  return staged.path;
+}
+
+Future<void> deleteFileIfExists(String path) async {
+  final file = File(path);
+  if (await file.exists()) {
+    await file.delete();
+  }
+}

package/dart-src/root/lib/src/io_stub.dart

@@ -0,0 +1,19 @@
+import 'dart:typed_data';
+
+bool get isAndroid => false;
+
+String get operatingSystem => 'unsupported';
+
+Future<Map<String, dynamic>> getJson(
+  String url, {
+  Map<String, String>? headers,
+  Duration timeout = const Duration(seconds: 10),
+}) {
+  throw UnsupportedError('flutter_ota_kit only supports Android');
+}
+
+Future<String> stagePatchBytes(String dir, Uint8List bytes) {
+  throw UnsupportedError('flutter_ota_kit only supports Android');
+}
+
+Future<void> deleteFileIfExists(String path) async {}