@_nazmiforreal/flutter-ota 0.1.0 → 0.1.2

package/dart-src/packages/core/lib/src/patch_info.dart

@@ -0,0 +1,284 @@
+/// Minimum metadata needed to install a patch.
+///
+/// `PatchInfo` is intentionally backend-agnostic. Your update data can come
+/// from HTTP JSON, gRPC, remote config, or hard-coded test data; as long as you
+/// can provide these fields, the patch can be passed to
+/// `FlutterPatcher.applyPatch`.
+class PatchInfo {
+  /// Patch identifier, for example `1.0.1-h1`.
+  final String version;
+
+  /// Patch payload URL.
+  ///
+  /// For a lib-only patch this points to `libapp.so`. For an asset patch this
+  /// points to `patch.zip`.
+  final String patchUrl;
+
+  /// MD5 of the patch payload, lower-case hex.
+  ///
+  /// For a lib-only patch this is the MD5 of `libapp.so`. For an asset patch
+  /// this is the MD5 of `patch.zip`. An empty string skips payload MD5
+  /// verification and also skips signature verification.
+  final String md5;
+
+  /// Base64 Ed25519 signature over the [md5] hex string.
+  ///
+  /// Empty disables signature verification. When [md5] is empty this field is
+  /// ignored because there is no signed message.
+  final String signature;
+
+  /// Host APK `versionCode` this patch targets.
+  ///
+  /// On cold start, a patch whose target versionCode no longer matches the
+  /// installed APK is dropped automatically. If null, native code binds the
+  /// patch to the current app versionCode during `applyPatch`.
+  final int? targetVersionCode;
+
+  /// Original JSON fields preserved by [PatchInfo.fromJson].
+  ///
+  /// Direct construction does not use this field.
+  final Map<String, dynamic> raw;
+
+  const PatchInfo({
+    required this.version,
+    required this.patchUrl,
+    this.md5 = '',
+    this.signature = '',
+    this.targetVersionCode,
+    this.raw = const {},
+  });
+
+  /// Parses the minimal built-in check-update protocol.
+  ///
+  /// If your server response has a different shape, construct [PatchInfo]
+  /// directly. Compatible field names:
+  ///
+  /// - `patchUrl` / `patch_url`
+  /// - `targetVersionCode` / `target_version_code`
+  factory PatchInfo.fromJson(Map<String, dynamic> json) {
+    final rawVc = json['targetVersionCode'] ?? json['target_version_code'];
+    final int? parsedVc = rawVc is num
+        ? rawVc.toInt()
+        : (rawVc is String && rawVc.isNotEmpty ? int.tryParse(rawVc) : null);
+    return PatchInfo(
+      version: (json['version'] ?? '') as String,
+      patchUrl: (json['patchUrl'] ?? json['patch_url'] ?? '') as String,
+      md5: (json['md5'] ?? '') as String,
+      signature: (json['signature'] ?? '') as String,
+      targetVersionCode: parsedVc,
+      raw: Map<String, dynamic>.from(json),
+    );
+  }
+
+  /// Serializes this patch for the native MethodChannel call.
+  Map<String, dynamic> toJson() => {
+        'version': version,
+        'patchUrl': patchUrl,
+        if (md5.isNotEmpty) 'md5': md5,
+        'signature': signature,
+        if (targetVersionCode != null) 'targetVersionCode': targetVersionCode,
+      };
+
+  @override
+  String toString() => 'PatchInfo('
+      'version=$version, url=$patchUrl, '
+      'md5=${md5.isEmpty ? 'none' : md5}, '
+      'sig=${signature.isEmpty ? 'none' : '***'})';
+}
+
+/// Stages emitted while applying a patch.
+enum PatchApplyPhase {
+  /// Payload download. [PatchApplyProgress.bytesReceived] and
+  /// [PatchApplyProgress.totalBytes] are meaningful in this phase.
+  downloading,
+
+  /// Payload MD5 / signature verification.
+  verifying,
+
+  /// Package parsing, asset installation, and transaction commit.
+  finalizing,
+}
+
+PatchApplyPhase _parsePhase(String? s) {
+  switch (s) {
+    case 'downloading':
+      return PatchApplyPhase.downloading;
+    case 'verifying':
+      return PatchApplyPhase.verifying;
+    case 'finalizing':
+      return PatchApplyPhase.finalizing;
+    default:
+      return PatchApplyPhase.downloading;
+  }
+}
+
+/// Progress event emitted by `FlutterPatcher.applyProgress`.
+class PatchApplyProgress {
+  final PatchApplyPhase phase;
+
+  /// Meaningful only when [phase] is [PatchApplyPhase.downloading].
+  final int bytesReceived;
+
+  /// Meaningful only when [phase] is [PatchApplyPhase.downloading].
+  ///
+  /// `-1` means the server did not provide `Content-Length`.
+  final int totalBytes;
+
+  const PatchApplyProgress({
+    required this.phase,
+    this.bytesReceived = 0,
+    this.totalBytes = 0,
+  });
+
+  /// Download progress from 0.0 to 1.0, or null when unknown/not downloading.
+  double? get fraction {
+    if (phase != PatchApplyPhase.downloading) return null;
+    if (totalBytes <= 0) return null;
+    return (bytesReceived / totalBytes).clamp(0.0, 1.0).toDouble();
+  }
+
+  factory PatchApplyProgress.fromNative(Object? native) {
+    if (native is! Map) {
+      return const PatchApplyProgress(phase: PatchApplyPhase.downloading);
+    }
+    final map = Map<String, dynamic>.from(native);
+    return PatchApplyProgress(
+      phase: _parsePhase(map['phase'] as String?),
+      bytesReceived: (map['received'] as num?)?.toInt() ?? 0,
+      totalBytes: (map['total'] as num?)?.toInt() ?? 0,
+    );
+  }
+
+  @override
+  String toString() {
+    if (phase != PatchApplyPhase.downloading) {
+      return 'PatchApplyProgress(${phase.name})';
+    }
+    final f = fraction;
+    final pct = f != null ? '${(f * 100).toStringAsFixed(1)}%' : '?';
+    return 'PatchApplyProgress(downloading, $bytesReceived/$totalBytes, $pct)';
+  }
+}
+
+/// Classified failure reason for `FlutterPatcher.applyPatch`.
+enum PatchApplyError {
+  /// Missing version/URL, invalid MD5 format, unsupported mode, or target
+  /// version mismatch.
+  invalidArgs,
+
+  /// The same `(version, md5)` payload is in the local bad-patch blacklist.
+  blacklisted,
+
+  /// Download failed after retries.
+  network,
+
+  /// Payload, lib, or overlay asset MD5 did not match expected metadata.
+  md5Mismatch,
+
+  /// Ed25519 verification failed, or strict mode rejected a signed patch on an
+  /// Android version without Ed25519 support.
+  signatureInvalid,
+
+  /// The patch package has no `libapp.so` for the current device ABI.
+  unsupportedAbi,
+
+  /// Invalid asset package: bad zip/schema/manifest, unsafe path, missing asset
+  /// entry, or unsupported asset mode/op.
+  assetPackageInvalid,
+
+  /// Filesystem, disk space, copy, fsync, or rename failure.
+  ioError,
+
+  /// Unclassified native/channel error.
+  unknown,
+}
+
+PatchApplyError _parseApplyError(String? code) {
+  switch (code) {
+    case 'INVALID_ARGS':
+      return PatchApplyError.invalidArgs;
+    case 'BLACKLISTED':
+      return PatchApplyError.blacklisted;
+    case 'NETWORK':
+      return PatchApplyError.network;
+    case 'MD5_MISMATCH':
+      return PatchApplyError.md5Mismatch;
+    case 'SIGNATURE_INVALID':
+      return PatchApplyError.signatureInvalid;
+    case 'UNSUPPORTED_ABI':
+      return PatchApplyError.unsupportedAbi;
+    case 'ASSET_PACKAGE_INVALID':
+      return PatchApplyError.assetPackageInvalid;
+    case 'IO_ERROR':
+      return PatchApplyError.ioError;
+    default:
+      return PatchApplyError.unknown;
+  }
+}
+
+/// Structured result returned by `FlutterPatcher.applyPatch`.
+class PatchApplyResult {
+  /// Whether the patch was installed successfully.
+  ///
+  /// Reapplying the same already-installed patch is also considered success.
+  final bool ok;
+
+  /// Failure category. Null when [ok] is true.
+  final PatchApplyError? error;
+
+  /// Developer-facing failure description. Do not show directly to users.
+  final String? message;
+
+  const PatchApplyResult._({required this.ok, this.error, this.message});
+
+  factory PatchApplyResult.success() => const PatchApplyResult._(ok: true);
+
+  factory PatchApplyResult.failure(PatchApplyError error, [String? message]) =>
+      PatchApplyResult._(ok: false, error: error, message: message);
+
+  /// Deserializes the native MethodChannel result.
+  factory PatchApplyResult.fromNative(Object? native) {
+    if (native is! Map) {
+      return PatchApplyResult.failure(
+        PatchApplyError.unknown,
+        'invalid native result: $native',
+      );
+    }
+    final map = Map<String, dynamic>.from(native);
+    if (map['ok'] == true) return PatchApplyResult.success();
+    return PatchApplyResult.failure(
+      _parseApplyError(map['error'] as String?),
+      map['message'] as String?,
+    );
+  }
+
+  @override
+  String toString() => ok
+      ? 'PatchApplyResult(ok)'
+      : 'PatchApplyResult(error=${error?.name}, message=$message)';
+}
+
+/// Result returned by `FlutterPatcher.checkUpdate`.
+class PatchCheckResult {
+  /// Whether a new patch is available.
+  final bool hasUpdate;
+
+  /// Patch metadata. Null when [hasUpdate] is false.
+  final PatchInfo? patch;
+
+  const PatchCheckResult({required this.hasUpdate, this.patch});
+
+  factory PatchCheckResult.none() =>
+      const PatchCheckResult(hasUpdate: false, patch: null);
+
+  factory PatchCheckResult.fromJson(Map<String, dynamic> json) {
+    final hasUpdate = json['hasUpdate'] == true || json['has_update'] == true;
+    if (!hasUpdate) return PatchCheckResult.none();
+    final patchJson = json['patch'];
+    final patchMap = patchJson is Map ? patchJson : json;
+    return PatchCheckResult(
+      hasUpdate: true,
+      patch: PatchInfo.fromJson(Map<String, dynamic>.from(patchMap)),
+    );
+  }
+}

package/dart-src/packages/core/lib/src/platform.dart

@@ -0,0 +1,15 @@
+/// Platform enum — hot-updater keeps `ios | android`; we implement Android
+/// first but keep the full union for wire compatibility.
+library;
+
+enum Platform {
+  ios('ios'),
+  android('android');
+
+  final String value;
+  const Platform(this.value);
+
+  static Platform fromValue(String v) =>
+      Platform.values.firstWhere((p) => p.value == v,
+          orElse: () => throw ArgumentError('unknown platform: $v'));
+}

package/dart-src/packages/core/lib/src/rollout.dart

@@ -0,0 +1,209 @@
+/// Dart translation of hot-updater `packages/core/src/rollout.ts`.
+///
+/// Deterministic staged-rollout cohort math. Numeric cohorts are 1..1000;
+/// each bundle gets a per-bundle deterministic shuffle so expanding a rollout
+/// never drops devices that were already included.
+library;
+
+const int numericCohortSize = 1000;
+const int defaultRolloutCohortCount = numericCohortSize;
+const int maxCohortLength = 64;
+const String invalidCohortErrorMessage =
+    'Invalid cohort. Use 1-1000 or a lowercase slug without spaces, '
+    'up to $maxCohortLength characters.';
+
+final RegExp _digitsOnly = RegExp(r'^\d+$');
+final RegExp _customCohortPattern = RegExp(r'^[a-z0-9-]+$');
+
+int? _parseNumericCohortValue(String cohort) {
+  if (!_digitsOnly.hasMatch(cohort)) {
+    return null;
+  }
+  final parsed = int.tryParse(cohort);
+  if (parsed == null || parsed < 1 || parsed > numericCohortSize) {
+    return null;
+  }
+  return parsed;
+}
+
+int _positiveMod(int value, int modulus) => ((value % modulus) + modulus) % modulus;
+
+/// Java-style 32-bit signed rolling string hash (`(h<<5) - h + c`, truncated).
+int _hashString(String value) {
+  var hash = 0;
+  for (var i = 0; i < value.length; i++) {
+    final char = value.codeUnitAt(i);
+    hash = _toSigned32((hash << 5) - hash + char);
+  }
+  return hash;
+}
+
+int _toSigned32(int v) {
+  v &= 0xFFFFFFFF;
+  return v >= 0x80000000 ? v - 0x100000000 : v;
+}
+
+int _gcd(int a, int b) {
+  var x = a.abs();
+  var y = b.abs();
+  while (y != 0) {
+    final next = x % y;
+    x = y;
+    y = next;
+  }
+  return x;
+}
+
+int _modularInverse(int value, int modulus) {
+  var t = 0;
+  var newT = 1;
+  var r = modulus;
+  var newR = _positiveMod(value, modulus);
+  while (newR != 0) {
+    final quotient = r ~/ newR;
+    final tmpT = t - quotient * newT;
+    t = newT;
+    newT = tmpT;
+    final tmpR = r - quotient * newR;
+    r = newR;
+    newR = tmpR;
+  }
+  if (r > 1) {
+    throw ArgumentError('No modular inverse for $value mod $modulus');
+  }
+  return _positiveMod(t, modulus);
+}
+
+({int multiplier, int offset, int inverseMultiplier}) _rolloutShuffleParameters(
+    String bundleId) {
+  var multiplier = _positiveMod(_hashString('$bundleId:multiplier'), 997);
+  if (multiplier == 0) {
+    multiplier = 1;
+  }
+  while (_gcd(multiplier, numericCohortSize) != 1) {
+    multiplier = _positiveMod(multiplier + 1, numericCohortSize);
+    if (multiplier == 0) {
+      multiplier = 1;
+    }
+  }
+  final offset = _positiveMod(
+    _hashString('$bundleId:offset'),
+    numericCohortSize,
+  );
+  return (
+    multiplier: multiplier,
+    offset: offset,
+    inverseMultiplier: _modularInverse(multiplier, numericCohortSize),
+  );
+}
+
+/// Clamps a rollout percentage to 0..1000 (per-mille). Null means 100%.
+int normalizeRolloutCohortCount(int? rolloutCohortCount) {
+  if (rolloutCohortCount == null) {
+    return defaultRolloutCohortCount;
+  }
+  if (rolloutCohortCount <= 0) {
+    return 0;
+  }
+  if (rolloutCohortCount >= numericCohortSize) {
+    return numericCohortSize;
+  }
+  return rolloutCohortCount.floor();
+}
+
+String normalizeCohortValue(String cohort) {
+  final normalized = cohort.trim().toLowerCase();
+  final numeric = _parseNumericCohortValue(normalized);
+  if (numeric != null) {
+    return '$numeric';
+  }
+  return normalized;
+}
+
+int? getNumericCohortValue(String cohort) =>
+    _parseNumericCohortValue(normalizeCohortValue(cohort));
+
+bool isNumericCohort(String cohort) => getNumericCohortValue(cohort) != null;
+
+bool isCustomCohort(String cohort) {
+  final normalized = normalizeCohortValue(cohort);
+  return normalized.isNotEmpty &&
+      normalized.length <= maxCohortLength &&
+      !_digitsOnly.hasMatch(normalized) &&
+      _customCohortPattern.hasMatch(normalized);
+}
+
+bool isValidCohort(String cohort) {
+  final normalized = normalizeCohortValue(cohort);
+  return isNumericCohort(normalized) || isCustomCohort(normalized);
+}
+
+/// Default cohort derived from a device identifier (ANDROID_ID etc.).
+String getDefaultNumericCohort(String identifier) {
+  final cohortValue = _positiveMod(_hashString(identifier), numericCohortSize) + 1;
+  return '$cohortValue';
+}
+
+int getNumericCohortRolloutPosition(String bundleId, int cohortValue) {
+  if (cohortValue < 1 || cohortValue > numericCohortSize) {
+    throw ArgumentError('Invalid numeric cohort: $cohortValue');
+  }
+  final params = _rolloutShuffleParameters(bundleId);
+  final zeroBasedCohort = cohortValue - 1;
+  return _positiveMod(
+    params.inverseMultiplier * (zeroBasedCohort - params.offset),
+    numericCohortSize,
+  );
+}
+
+List<int> getRolledOutNumericCohorts(
+  String bundleId,
+  int? rolloutCohortCount,
+) {
+  final normalized = normalizeRolloutCohortCount(rolloutCohortCount);
+  if (normalized <= 0) {
+    return [];
+  }
+  return List.generate(numericCohortSize, (index) => index + 1)
+      .where((cohortValue) =>
+          normalized >= numericCohortSize ||
+          getNumericCohortRolloutPosition(bundleId, cohortValue) < normalized)
+      .toList();
+}
+
+/// Mirrors hot-updater semantics exactly:
+/// - explicit target_cohorts match always wins (even at 100%/excluded cohorts)
+/// - no cohort provided: eligible only at full rollout
+/// - custom (non-numeric) cohorts are ineligible for percentage rollouts
+bool isCohortEligibleForUpdate(
+  String bundleId,
+  String? cohort,
+  int? rolloutCohortCount,
+  List<String>? targetCohorts,
+) {
+  final normalizedCohort = cohort == null ? null : normalizeCohortValue(cohort);
+  final normalizedTargets =
+      targetCohorts?.map(normalizeCohortValue).toList() ?? <String>[];
+
+  if (normalizedCohort != null && normalizedTargets.contains(normalizedCohort)) {
+    return true;
+  }
+
+  final normalizedRollout = normalizeRolloutCohortCount(rolloutCohortCount);
+  if (normalizedRollout <= 0) {
+    return false;
+  }
+  if (normalizedCohort == null) {
+    return normalizedRollout >= numericCohortSize;
+  }
+
+  final numericCohort = getNumericCohortValue(normalizedCohort);
+  if (numericCohort == null) {
+    return false;
+  }
+  if (normalizedRollout >= numericCohortSize) {
+    return true;
+  }
+  return getNumericCohortRolloutPosition(bundleId, numericCohort) <
+      normalizedRollout;
+}

package/dart-src/packages/core/lib/src/semver.dart

@@ -0,0 +1,70 @@
+import 'semver_range.dart' show satisfies;
+import 'semver_version.dart';
+
+export 'semver_range.dart' show satisfies;
+export 'semver_version.dart' show SemVer;
+
+/// hot-updater `semverSatisfies(targetAppVersion, currentVersion)`
+/// (plugins/plugin-core/src/semverSatisfies.ts):
+///
+/// 1. `coerce(currentVersion)` — extract a version from loose input
+///    ("v1.2", "version 2.3.4", "1a2b3c" → 1.0.0, junk → null).
+/// 2. `satisfies(coerced, range)` against the raw target range.
+bool semverSatisfies(String targetAppVersion, String currentVersion) {
+  final coerced = semverCoerce(currentVersion);
+  if (coerced == null) {
+    return false;
+  }
+  return satisfies(coerced, targetAppVersion);
+}
+
+/// verkit `coerce` with default options: find the first plausible
+/// major[.minor[.patch]] run; prerelease/build are dropped; anything after
+/// the run (including stray dots/digits like "1.2.3.4") is ignored.
+SemVer? semverCoerce(String value) {
+  var input = value.trim();
+  if (input.isEmpty) return null;
+  final m = RegExp(
+    r'(?<![0-9.])'
+    r'(0|[1-9]\d*)'
+    r'(?:\.(0|[1-9]\d*))?'
+    r'(?:\.(0|[1-9]\d*))?',
+  ).firstMatch(input);
+  if (m == null) return null;
+
+  // Overflow guard mirroring verkit: a digit run too large for a safe
+  // integer is skipped and scanning resumes right after it, allowing a
+  // leading dot. e.g. "99999999999999999999.1.1" -> "1.1.0".
+  var majorStr = m.group(1)!;
+  if (majorStr.length > 15) {
+    return semverCoerceLoose(input.substring(m.start + majorStr.length));
+  }
+
+  return SemVer(
+    int.parse(majorStr),
+    int.tryParse(m.group(2) ?? '') ?? 0,
+    int.tryParse(m.group(3) ?? '') ?? 0,
+  );
+}
+
+/// Retry scan that allows a preceding dot (used after skipping an
+/// oversized digit run).
+SemVer? semverCoerceLoose(String input) {
+  var s = input.trim();
+  if (s.isEmpty) return null;
+  final m = RegExp(
+    r'(0|[1-9]\d*)'
+    r'(?:\.(0|[1-9]\d*))?'
+    r'(?:\.(0|[1-9]\d*))?',
+  ).firstMatch(s);
+  if (m == null) return null;
+  var majorStr = m.group(1)!;
+  if (majorStr.length > 15) {
+    return semverCoerceLoose(s.substring(m.start + majorStr.length));
+  }
+  return SemVer(
+    int.parse(majorStr),
+    int.tryParse(m.group(2) ?? '') ?? 0,
+    int.tryParse(m.group(3) ?? '') ?? 0,
+  );
+}