feat(flutter): in-app update banner + Android install intent (#397 phase 2)
Closes the operator-facing half of #397. Soft banner mounts at the top of the shell when the server has a newer APK bundled at /api/client/version; tap Install → APK downloads to cache → Android PackageInstaller intent fires → user taps Install in the system dialog → app restarts on the new version. ### Dart side - lib/update/update_info.dart — wire shape for /api/client/version - lib/update/client_update_provider.dart — Riverpod AsyncNotifier polling on app start + every 24h. Compares semver via pub_semver with non-semver string-equality fallback. Server 404 = "no update channel" = silent. Companion shouldShowUpdateBannerProvider gates on a per-version dismissed-set (in-memory; resets on restart). - lib/update/installer.dart — UpdateInstaller wraps dio.download + the MethodChannel call to MainActivity.kt. - lib/update/update_banner.dart — Material banner with idle / downloading (with progress) / error stages. Mounted in _ShellWithPlayerBar above the route content; SizedBox.shrink() when no update available so non-shell routes (login, server-url) see no banner anyway. - isVersionNewer() extracted as a pure function and tested across semver, prerelease ordering, leading-v normalization, and non-semver fallback (date-tag style). ### Android side - AndroidManifest.xml — REQUEST_INSTALL_PACKAGES permission; FileProvider with authorities ${applicationId}.fileprovider. - res/xml/file_paths.xml — exposes the cache directory so the downloaded APK can be served via content:// URI (file:// is blocked since Android 7). - MainActivity.kt — MethodChannel handler builds the FileProvider URI and fires Intent.ACTION_VIEW with FLAG_GRANT_READ_URI_PERMISSION so the system installer can read across the process boundary. Phase 3 (CI sequencing — bake APK + version file into /app/client/ during release.yml's tag flow) is the remaining piece. Without it the server returns 404 from /api/client/version and the banner silently does nothing — graceful degradation, but no actual updates. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
@@ -0,0 +1,102 @@
|
||||
import 'dart:async';
|
||||
|
||||
import 'package:dio/dio.dart';
|
||||
import 'package:flutter_riverpod/flutter_riverpod.dart';
|
||||
import 'package:package_info_plus/package_info_plus.dart';
|
||||
import 'package:pub_semver/pub_semver.dart';
|
||||
|
||||
import '../library/library_providers.dart' show dioProvider;
|
||||
import 'installer.dart';
|
||||
import 'update_info.dart';
|
||||
|
||||
/// Tracks the bundled-server APK version vs. the installed app version.
|
||||
/// Polls /api/client/version on startup + every 24h. Returns null when
|
||||
/// no update is available (or the channel is unreachable / disabled).
|
||||
///
|
||||
/// Server returns 404 when no APK is bundled (dev environments, pre-CI
|
||||
/// images) — we treat that as "no update channel" and stay silent.
|
||||
class ClientUpdateController extends AsyncNotifier<UpdateInfo?> {
|
||||
static const Duration _pollInterval = Duration(hours: 24);
|
||||
|
||||
Timer? _pollTimer;
|
||||
|
||||
@override
|
||||
Future<UpdateInfo?> build() async {
|
||||
ref.onDispose(() {
|
||||
_pollTimer?.cancel();
|
||||
_pollTimer = null;
|
||||
});
|
||||
_pollTimer ??= Timer.periodic(_pollInterval, (_) => ref.invalidateSelf());
|
||||
return _check();
|
||||
}
|
||||
|
||||
Future<UpdateInfo?> _check() async {
|
||||
final dio = await ref.read(dioProvider.future);
|
||||
final Response<Map<String, dynamic>> r;
|
||||
try {
|
||||
r = await dio.get<Map<String, dynamic>>('/api/client/version');
|
||||
} on DioException catch (e) {
|
||||
// 404 = no APK bundled; any other error = treat as silent.
|
||||
if (e.response?.statusCode == 404) return null;
|
||||
return null;
|
||||
}
|
||||
if (r.data == null) return null;
|
||||
|
||||
final info = UpdateInfo.fromJson(r.data!);
|
||||
final installed = (await PackageInfo.fromPlatform()).version;
|
||||
if (!isVersionNewer(info.version, installed)) return null;
|
||||
return info;
|
||||
}
|
||||
}
|
||||
|
||||
/// True when `serverVersion` is strictly newer than `installedVersion`.
|
||||
/// Both strings are normalized (leading 'v' stripped) and parsed as
|
||||
/// semver. On parse failure, falls back to string inequality (treats
|
||||
/// any difference as "newer" — operator can dismiss if wrong).
|
||||
///
|
||||
/// Exposed for testing; the polling logic in ClientUpdateController
|
||||
/// is the only production caller.
|
||||
bool isVersionNewer(String serverVersion, String installedVersion) {
|
||||
final svr = serverVersion.replaceFirst(RegExp(r'^v'), '');
|
||||
final ins = installedVersion.replaceFirst(RegExp(r'^v'), '');
|
||||
try {
|
||||
return Version.parse(svr) > Version.parse(ins);
|
||||
} catch (_) {
|
||||
return svr != ins;
|
||||
}
|
||||
}
|
||||
|
||||
final clientUpdateProvider =
|
||||
AsyncNotifierProvider<ClientUpdateController, UpdateInfo?>(
|
||||
ClientUpdateController.new);
|
||||
|
||||
/// In-memory dismissed-versions set. Keyed by version string so a
|
||||
/// later release's banner re-appears even if the operator dismissed
|
||||
/// the previous one. Not persisted — restart re-shows the banner,
|
||||
/// which is acceptable nudging for v1.
|
||||
final _dismissedVersionsProvider = StateProvider<Set<String>>((_) => <String>{});
|
||||
|
||||
/// True when the update banner should render: an UpdateInfo is
|
||||
/// available AND the operator hasn't dismissed this specific version.
|
||||
final shouldShowUpdateBannerProvider = Provider<UpdateInfo?>((ref) {
|
||||
final info = ref.watch(clientUpdateProvider).value;
|
||||
if (info == null) return null;
|
||||
final dismissed = ref.watch(_dismissedVersionsProvider);
|
||||
if (dismissed.contains(info.version)) return null;
|
||||
return info;
|
||||
});
|
||||
|
||||
/// Dismiss controller: marks the given version as dismissed so the
|
||||
/// banner stops showing for this session.
|
||||
final dismissUpdateProvider = Provider<void Function(String)>((ref) {
|
||||
return (version) {
|
||||
ref.read(_dismissedVersionsProvider.notifier).update((s) => {...s, version});
|
||||
};
|
||||
});
|
||||
|
||||
/// Installer provider — depends on dio so the install download uses
|
||||
/// the same authenticated client (though /api/client/apk is unauthed,
|
||||
/// reusing dio keeps configuration consistent).
|
||||
final updateInstallerProvider = FutureProvider<UpdateInstaller>((ref) async {
|
||||
return UpdateInstaller(await ref.watch(dioProvider.future));
|
||||
});
|
||||
@@ -0,0 +1,46 @@
|
||||
import 'package:dio/dio.dart';
|
||||
import 'package:flutter/services.dart';
|
||||
import 'package:path_provider/path_provider.dart';
|
||||
|
||||
/// Bridges to MainActivity.kt's MethodChannel for the Android
|
||||
/// PackageInstaller intent (#397). Web / iOS don't support self-
|
||||
/// install; this class is Android-only at v1.
|
||||
class UpdateInstaller {
|
||||
UpdateInstaller(this._dio);
|
||||
final Dio _dio;
|
||||
|
||||
static const _channel = MethodChannel('com.fabledsword.minstrel/installer');
|
||||
static const _filename = 'minstrel-update.apk';
|
||||
|
||||
/// Streams the APK from `apkUrl` into the cache directory. `onProgress`
|
||||
/// receives 0..1 fractions; emits 1.0 once when the download completes.
|
||||
/// Returns the local path the install intent will read from.
|
||||
Future<String> download(
|
||||
String apkUrl, {
|
||||
void Function(double progress)? onProgress,
|
||||
}) async {
|
||||
final cacheDir = await getApplicationCacheDirectory();
|
||||
final path = '${cacheDir.path}/$_filename';
|
||||
await _dio.download(
|
||||
apkUrl,
|
||||
path,
|
||||
onReceiveProgress: (received, total) {
|
||||
if (total > 0 && onProgress != null) {
|
||||
onProgress(received / total);
|
||||
}
|
||||
},
|
||||
);
|
||||
return path;
|
||||
}
|
||||
|
||||
/// Hands the downloaded APK to Android's PackageInstaller via a
|
||||
/// FileProvider content:// URI. The system shows the install confirm
|
||||
/// dialog; user must tap Install. App restarts on the new version.
|
||||
///
|
||||
/// First-ever install attempt prompts the user to flip "Install
|
||||
/// unknown apps" for Minstrel in Settings → Apps → Special access.
|
||||
/// One-time grant; persists across updates.
|
||||
Future<void> install(String apkPath) async {
|
||||
await _channel.invokeMethod('install', {'path': apkPath});
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,129 @@
|
||||
import 'package:flutter/material.dart';
|
||||
import 'package:flutter_riverpod/flutter_riverpod.dart';
|
||||
|
||||
import '../theme/theme_extension.dart';
|
||||
import 'client_update_provider.dart';
|
||||
import 'update_info.dart';
|
||||
|
||||
/// Soft banner mounted at the top of the shell. Renders nothing when
|
||||
/// no update is available or the user has dismissed this version's
|
||||
/// banner. Tapping Install downloads the APK and fires the system
|
||||
/// install intent (Android only).
|
||||
class UpdateBanner extends ConsumerStatefulWidget {
|
||||
const UpdateBanner({super.key});
|
||||
|
||||
@override
|
||||
ConsumerState<UpdateBanner> createState() => _UpdateBannerState();
|
||||
}
|
||||
|
||||
enum _Stage { idle, downloading, error }
|
||||
|
||||
class _UpdateBannerState extends ConsumerState<UpdateBanner> {
|
||||
_Stage _stage = _Stage.idle;
|
||||
double _progress = 0;
|
||||
String? _error;
|
||||
|
||||
Future<void> _onInstall(UpdateInfo info) async {
|
||||
setState(() {
|
||||
_stage = _Stage.downloading;
|
||||
_progress = 0;
|
||||
_error = null;
|
||||
});
|
||||
try {
|
||||
final installer = await ref.read(updateInstallerProvider.future);
|
||||
final path = await installer.download(
|
||||
info.apkUrl,
|
||||
onProgress: (p) => setState(() => _progress = p),
|
||||
);
|
||||
await installer.install(path);
|
||||
// Stage stays 'downloading' — Android system install dialog has
|
||||
// taken over. If user cancels, the banner is still here.
|
||||
} catch (e) {
|
||||
if (!mounted) return;
|
||||
setState(() {
|
||||
_stage = _Stage.error;
|
||||
_error = '$e';
|
||||
});
|
||||
}
|
||||
}
|
||||
|
||||
void _onDismiss(UpdateInfo info) {
|
||||
ref.read(dismissUpdateProvider)(info.version);
|
||||
}
|
||||
|
||||
@override
|
||||
Widget build(BuildContext context) {
|
||||
final info = ref.watch(shouldShowUpdateBannerProvider);
|
||||
if (info == null) return const SizedBox.shrink();
|
||||
final fs = Theme.of(context).extension<FabledSwordTheme>()!;
|
||||
|
||||
return Material(
|
||||
color: fs.iron,
|
||||
child: SafeArea(
|
||||
bottom: false,
|
||||
child: Padding(
|
||||
padding: const EdgeInsets.fromLTRB(12, 8, 4, 8),
|
||||
child: Row(
|
||||
children: [
|
||||
Icon(Icons.system_update, color: fs.parchment, size: 18),
|
||||
const SizedBox(width: 10),
|
||||
Expanded(
|
||||
child: Column(
|
||||
crossAxisAlignment: CrossAxisAlignment.start,
|
||||
mainAxisSize: MainAxisSize.min,
|
||||
children: [
|
||||
Text(
|
||||
_stage == _Stage.error
|
||||
? 'Update failed'
|
||||
: 'Update Minstrel · ${info.version} available',
|
||||
style: TextStyle(color: fs.parchment, fontSize: 13),
|
||||
overflow: TextOverflow.ellipsis,
|
||||
),
|
||||
if (_stage == _Stage.downloading) ...[
|
||||
const SizedBox(height: 4),
|
||||
LinearProgressIndicator(
|
||||
value: _progress > 0 ? _progress : null,
|
||||
minHeight: 2,
|
||||
backgroundColor: fs.obsidian,
|
||||
valueColor: AlwaysStoppedAnimation(fs.accent),
|
||||
),
|
||||
],
|
||||
if (_stage == _Stage.error && _error != null) ...[
|
||||
const SizedBox(height: 2),
|
||||
Text(
|
||||
_error!,
|
||||
style: TextStyle(color: fs.ash, fontSize: 11),
|
||||
maxLines: 2,
|
||||
overflow: TextOverflow.ellipsis,
|
||||
),
|
||||
],
|
||||
],
|
||||
),
|
||||
),
|
||||
if (_stage == _Stage.idle)
|
||||
TextButton(
|
||||
onPressed: () => _onInstall(info),
|
||||
style: TextButton.styleFrom(
|
||||
foregroundColor: fs.accent,
|
||||
minimumSize: const Size(64, 36),
|
||||
),
|
||||
child: const Text('Install'),
|
||||
),
|
||||
if (_stage == _Stage.error)
|
||||
TextButton(
|
||||
onPressed: () => _onInstall(info),
|
||||
style: TextButton.styleFrom(foregroundColor: fs.accent),
|
||||
child: const Text('Retry'),
|
||||
),
|
||||
IconButton(
|
||||
tooltip: 'Dismiss',
|
||||
icon: Icon(Icons.close, size: 18, color: fs.ash),
|
||||
onPressed: () => _onDismiss(info),
|
||||
),
|
||||
],
|
||||
),
|
||||
),
|
||||
),
|
||||
);
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,21 @@
|
||||
// Wire shape returned by GET /api/client/version. `version` is the
|
||||
// server-bundled APK version (raw — may have a "v" prefix from the
|
||||
// git tag); `apkUrl` is server-relative (e.g. "/api/client/apk").
|
||||
|
||||
class UpdateInfo {
|
||||
const UpdateInfo({
|
||||
required this.version,
|
||||
required this.apkUrl,
|
||||
required this.sizeBytes,
|
||||
});
|
||||
|
||||
final String version;
|
||||
final String apkUrl;
|
||||
final int sizeBytes;
|
||||
|
||||
factory UpdateInfo.fromJson(Map<String, dynamic> j) => UpdateInfo(
|
||||
version: (j['version'] as String?) ?? '',
|
||||
apkUrl: (j['apk_url'] as String?) ?? '/api/client/apk',
|
||||
sizeBytes: (j['size_bytes'] as num?)?.toInt() ?? 0,
|
||||
);
|
||||
}
|
||||
Reference in New Issue
Block a user