api: Don't allow connecting to servers <4.0

From the README:

https://github.com/zulip/zulip-flutter?tab=readme-ov-file#server-compatibility
> We support Zulip Server 4.0 and later.

This implementation isn't ideal because it logs you out, instead of
just taking down the account's UI as we discussed:
  https://chat.zulip.org/#narrow/channel/243-mobile-team/topic/.23F267.20Disallow.20connecting.20to.20unsupported.20ancient.20servers/near/2104182
But it was simpler this way since programmatically logging out is
already an action we handle.

Fixes: #267

Author: chrisbobbe

assets/l10n/app_en.arb

@@ -538,6 +538,15 @@
   "@topicValidationErrorMandatoryButEmpty": {
     "description": "Topic validation error when topic is required but was empty."
   },
+  "errorServerVersionUnsupportedMessage": "{url} is running Zulip Server {zulipVersion}, which is unsupported. The minimum supported version is Zulip Server {minSupportedZulipVersion}.",
+  "@errorServerVersionUnsupportedMessage": {
+    "description": "Error message in the dialog for when the Zulip Server version is unsupported.",
+    "placeholders": {
+      "url": {"type": "String", "example": "http://chat.example.com/"},
+      "zulipVersion": {"type": "String", "example": "3.2"},
+      "minSupportedZulipVersion": {"type": "String", "example": "4.0"}
+    }
+  },
   "errorInvalidApiKeyMessage": "Your account at {url} could not be authenticated. Please try logging in again or use another account.",
   "@errorInvalidApiKeyMessage": {
     "description": "Error message in the dialog for invalid API key.",

lib/api/core.dart

@@ -10,6 +10,24 @@ import '../model/binding.dart';
 import '../model/localizations.dart';
 import 'exception.dart';
 
+/// The Zulip Server version below which we should refuse to connect.
+///
+/// When updating this, also update [kMinSupportedZulipFeatureLevel]
+/// and the README.
+const kMinSupportedZulipVersion = '4.0';
+
+/// The Zulip feature level reserved for the [minSupportedZulipVersion] release.
+///
+/// For this value, see the API changelog:
+///   https://zulip.com/api/changelog
+const kMinSupportedZulipFeatureLevel = 65;
+
+/// The doc stating our oldest supported server version.
+// TODO: Instead, link to new Help Center doc once we have it:
+//   https://github.com/zulip/zulip/issues/23842
+final kServerSupportDocUrl = Uri.parse(
+  'https://zulip.readthedocs.io/en/latest/overview/release-lifecycle.html#compatibility-and-upgrading');
+
 /// A fused JSON + UTF-8 decoder.
 ///
 /// This object is an instance of [`_JsonUtf8Decoder`][1] which is

lib/generated/l10n/zulip_localizations.dart

@@ -825,6 +825,12 @@ abstract class ZulipLocalizations {
   /// **'Topics are required in this organization.'**
   String get topicValidationErrorMandatoryButEmpty;
 
+  /// Error message in the dialog for when the Zulip Server version is unsupported.
+  ///
+  /// In en, this message translates to:
+  /// **'{url} is running Zulip Server {zulipVersion}, which is unsupported. The minimum supported version is Zulip Server {minSupportedZulipVersion}.'**
+  String errorServerVersionUnsupportedMessage(String url, String zulipVersion, String minSupportedZulipVersion);
+
   /// Error message in the dialog for invalid API key.
   ///
   /// In en, this message translates to:

lib/generated/l10n/zulip_localizations_ar.dart

@@ -416,6 +416,11 @@ class ZulipLocalizationsAr extends ZulipLocalizations {
   @override
   String get topicValidationErrorMandatoryButEmpty => 'Topics are required in this organization.';
 
+  @override
+  String errorServerVersionUnsupportedMessage(String url, String zulipVersion, String minSupportedZulipVersion) {
+    return '$url is running Zulip Server $zulipVersion, which is unsupported. The minimum supported version is Zulip Server $minSupportedZulipVersion.';
+  }
+
   @override
   String errorInvalidApiKeyMessage(String url) {
     return 'Your account at $url could not be authenticated. Please try logging in again or use another account.';

lib/generated/l10n/zulip_localizations_en.dart

@@ -416,6 +416,11 @@ class ZulipLocalizationsEn extends ZulipLocalizations {
   @override
   String get topicValidationErrorMandatoryButEmpty => 'Topics are required in this organization.';
 
+  @override
+  String errorServerVersionUnsupportedMessage(String url, String zulipVersion, String minSupportedZulipVersion) {
+    return '$url is running Zulip Server $zulipVersion, which is unsupported. The minimum supported version is Zulip Server $minSupportedZulipVersion.';
+  }
+
   @override
   String errorInvalidApiKeyMessage(String url) {
     return 'Your account at $url could not be authenticated. Please try logging in again or use another account.';

lib/generated/l10n/zulip_localizations_ja.dart

@@ -416,6 +416,11 @@ class ZulipLocalizationsJa extends ZulipLocalizations {
   @override
   String get topicValidationErrorMandatoryButEmpty => 'Topics are required in this organization.';
 
+  @override
+  String errorServerVersionUnsupportedMessage(String url, String zulipVersion, String minSupportedZulipVersion) {
+    return '$url is running Zulip Server $zulipVersion, which is unsupported. The minimum supported version is Zulip Server $minSupportedZulipVersion.';
+  }
+
   @override
   String errorInvalidApiKeyMessage(String url) {
     return 'Your account at $url could not be authenticated. Please try logging in again or use another account.';

lib/generated/l10n/zulip_localizations_nb.dart

@@ -416,6 +416,11 @@ class ZulipLocalizationsNb extends ZulipLocalizations {
   @override
   String get topicValidationErrorMandatoryButEmpty => 'Topics are required in this organization.';
 
+  @override
+  String errorServerVersionUnsupportedMessage(String url, String zulipVersion, String minSupportedZulipVersion) {
+    return '$url is running Zulip Server $zulipVersion, which is unsupported. The minimum supported version is Zulip Server $minSupportedZulipVersion.';
+  }
+
   @override
   String errorInvalidApiKeyMessage(String url) {
     return 'Your account at $url could not be authenticated. Please try logging in again or use another account.';

lib/generated/l10n/zulip_localizations_pl.dart

@@ -416,6 +416,11 @@ class ZulipLocalizationsPl extends ZulipLocalizations {
   @override
   String get topicValidationErrorMandatoryButEmpty => 'Wątki są wymagane przez tę organizację.';
 
+  @override
+  String errorServerVersionUnsupportedMessage(String url, String zulipVersion, String minSupportedZulipVersion) {
+    return '$url is running Zulip Server $zulipVersion, which is unsupported. The minimum supported version is Zulip Server $minSupportedZulipVersion.';
+  }
+
   @override
   String errorInvalidApiKeyMessage(String url) {
     return 'Konto w ramach $url nie zostało przyjęte. Spróbuj ponownie lub skorzystaj z innego konta.';

lib/generated/l10n/zulip_localizations_ru.dart

@@ -416,6 +416,11 @@ class ZulipLocalizationsRu extends ZulipLocalizations {
   @override
   String get topicValidationErrorMandatoryButEmpty => 'Темы обязательны в этой организации.';
 
+  @override
+  String errorServerVersionUnsupportedMessage(String url, String zulipVersion, String minSupportedZulipVersion) {
+    return '$url is running Zulip Server $zulipVersion, which is unsupported. The minimum supported version is Zulip Server $minSupportedZulipVersion.';
+  }
+
   @override
   String errorInvalidApiKeyMessage(String url) {
     return 'Your account at $url could not be authenticated. Please try logging in again or use another account.';

lib/generated/l10n/zulip_localizations_sk.dart

@@ -416,6 +416,11 @@ class ZulipLocalizationsSk extends ZulipLocalizations {
   @override
   String get topicValidationErrorMandatoryButEmpty => 'Topics are required in this organization.';
 
+  @override
+  String errorServerVersionUnsupportedMessage(String url, String zulipVersion, String minSupportedZulipVersion) {
+    return '$url is running Zulip Server $zulipVersion, which is unsupported. The minimum supported version is Zulip Server $minSupportedZulipVersion.';
+  }
+
   @override
   String errorInvalidApiKeyMessage(String url) {
     return 'Your account at $url could not be authenticated. Please try logging in again or use another account.';

lib/log.dart

@@ -36,7 +36,11 @@ bool debugLog(String message) {
 // `null` for the `message` parameter and promptly dismiss the reported errors.
 typedef ReportErrorCancellablyCallback = void Function(String? message, {String? details});
 
-typedef ReportErrorCallback = void Function(String title, {String? message});
+typedef ReportErrorCallback = void Function(
+  String title, {
+  String? message,
+  Uri? learnMoreButtonUrl,
+});
 
 /// Show the user an error message, without requiring them to interact with it.
 ///
@@ -70,7 +74,11 @@ void defaultReportErrorToUserBriefly(String? message, {String? details}) {
   _reportErrorToConsole(message, details);
 }
 
-void defaultReportErrorToUserModally(String title, {String? message}) {
+void defaultReportErrorToUserModally(
+  String title, {
+  String? message,
+  Uri? learnMoreButtonUrl,
+}) {
   _reportErrorToConsole(title, message);
 }
 

lib/model/store.dart

@@ -193,6 +193,20 @@ abstract class GlobalStore extends ChangeNotifier {
       assert(account != null); // doLoadPerAccount would have thrown AccountNotFoundException
       final zulipLocalizations = GlobalLocalizations.zulipLocalizations;
       switch (e) {
+        case _ServerVersionUnsupportedException():
+          reportErrorToUserModally(
+            zulipLocalizations.errorCouldNotConnectTitle,
+            message: zulipLocalizations.errorServerVersionUnsupportedMessage(
+              account!.realmUrl.toString(),
+              e.data.zulipVersion,
+              kMinSupportedZulipVersion),
+            learnMoreButtonUrl: kServerSupportDocUrl);
+          // The important thing is to tear down per-account UI,
+          // and logOutAccount conveniently handles that already.
+          // It's not ideal to force the user to reauthenticate when they retry,
+          // and we can revisit that later if needed.
+          await logOutAccount(this, accountId);
+          throw AccountNotFoundException();
         case HttpException(httpStatus: 401):
           // The API key is invalid and the store can never be loaded
           // unless the user retries manually.
@@ -984,8 +998,15 @@ class UpdateMachine {
     }
 
     final stopwatch = Stopwatch()..start();
-    final initialSnapshot = await _registerQueueWithRetry(connection,
-      stopAndThrowIfNoAccount: stopAndThrowIfNoAccount);
+    InitialSnapshot? initialSnapshot;
+    try {
+      initialSnapshot = await _registerQueueWithRetry(connection,
+        stopAndThrowIfNoAccount: stopAndThrowIfNoAccount);
+    } on _ServerVersionUnsupportedException catch (e) {
+      connection.close();
+      await updateZulipVersionData(e.data);
+      rethrow;
+    }
     final t = (stopwatch..stop()).elapsed;
     assert(debugLog("initial fetch time: ${t.inMilliseconds}ms"));
 
@@ -1034,7 +1055,12 @@ class UpdateMachine {
       } catch (e, s) {
         stopAndThrowIfNoAccount();
         // TODO(#890): tell user if initial-fetch errors persist, or look non-transient
+        final ZulipVersionData? zulipVersionData;
         switch (e) {
+          case MalformedServerResponseException()
+            when (zulipVersionData = ZulipVersionData.fromMalformedServerResponseException(e))
+              ?.isUnsupported == true:
+            throw _ServerVersionUnsupportedException(zulipVersionData!);
           case HttpException(httpStatus: 401):
             // We cannot recover from this error through retrying.
             // Leave it to [GlobalStore.loadPerAccount].
@@ -1052,6 +1078,10 @@ class UpdateMachine {
       }
       if (result != null) {
         stopAndThrowIfNoAccount();
+        final zulipVersionData = ZulipVersionData.fromInitialSnapshot(result);
+        if (zulipVersionData.isUnsupported) {
+          throw _ServerVersionUnsupportedException(zulipVersionData);
+        }
         return result;
       }
     }
@@ -1474,9 +1504,31 @@ class ZulipVersionData {
       zulipMergeBase: initialSnapshot.zulipMergeBase,
       zulipFeatureLevel: initialSnapshot.zulipFeatureLevel);
 
+  /// Make a [ZulipVersionData] from a [MalformedServerResponseException],
+  /// if the body was readable/valid JSON and contained the data, else null.
+  static ZulipVersionData? fromMalformedServerResponseException(MalformedServerResponseException e) {
+    try {
+      final data = e.data!;
+      return ZulipVersionData(
+        zulipVersion: data['zulip_version'] as String,
+        zulipMergeBase: data['zulip_merge_base'] as String?,
+        zulipFeatureLevel: data['zulip_feature_level'] as int);
+    } catch (inner) {
+      return null;
+    }
+  }
+
   final String zulipVersion;
   final String? zulipMergeBase;
   final int zulipFeatureLevel;
+
+  bool get isUnsupported => zulipFeatureLevel < kMinSupportedZulipFeatureLevel;
+}
+
+class _ServerVersionUnsupportedException implements Exception {
+  final ZulipVersionData data;
+
+  _ServerVersionUnsupportedException(this.data);
 }
 
 class _EventHandlingException implements Exception {

lib/widgets/app.dart

@@ -130,13 +130,18 @@ class ZulipApp extends StatefulWidget {
   }
 
   /// The callback we normally use as [reportErrorToUserModally].
-  static void _reportErrorToUserModally(String title, {String? message}) {
+  static void _reportErrorToUserModally(
+    String title, {
+    String? message,
+    Uri? learnMoreButtonUrl,
+  }) {
     assert(_ready.value);
 
     showErrorDialog(
       context: navigatorKey.currentContext!,
       title: title,
-      message: message);
+      message: message,
+      learnMoreButtonUrl: learnMoreButtonUrl);
   }
 
   void _declareReady() {

test/example_data.dart

@@ -1,6 +1,7 @@
 import 'dart:convert';
 import 'dart:math';
 
+import 'package:zulip/api/core.dart';
 import 'package:zulip/api/exception.dart';
 import 'package:zulip/api/model/events.dart';
 import 'package:zulip/api/model/initial_snapshot.dart';
@@ -77,6 +78,7 @@ Uri get _realmUrl => realmUrl;
 const String recentZulipVersion = '9.0';
 const int recentZulipFeatureLevel = 278;
 const int futureZulipFeatureLevel = 9999;
+const int ancientZulipFeatureLevel = kMinSupportedZulipFeatureLevel - 1;
 
 GetServerSettingsResult serverSettings({
   Map<String, bool>? authenticationMethods,