store: Report polling errors with details

We delay reporting transient errors until we have retried a certain
number of times, because they might recover on their own.

Signed-off-by: Zixuan James Li <zixuan@zulip.com>

Author: PIG208

assets/l10n/app_en.arb

@@ -160,6 +160,18 @@
       "message": {"type": "String", "example": "Invalid format"}
     }
   },
+  "errorConnectingToServerShort": "Error connecting to Zulip. Retrying…",
+  "@errorConnectingToServerShort": {
+    "description": "Short error message for a generic unknown error connecting to the server."
+  },
+  "errorConnectingToServerDetails": "Error connecting to Zulip at {serverUrl}. Will retry:\n\n{error}",
+  "@errorConnectingToServerDetails": {
+    "description": "Dialog error message for a generic unknown error connecting to the server with details.",
+    "placeholders": {
+      "serverUrl": {"type": "String", "example": "http://example.com/"},
+      "error": {"type": "String", "example": "Invalid format"}
+    }
+  },
   "errorSharingFailed": "Sharing failed",
   "@errorSharingFailed": {
     "description": "Error message when sharing a message failed."

lib/model/store.dart

@@ -22,6 +22,7 @@ import '../notifications/receive.dart';
 import 'autocomplete.dart';
 import 'database.dart';
 import 'emoji.dart';
+import 'localizations.dart';
 import 'message.dart';
 import 'message_list.dart';
 import 'recent_dm_conversations.dart';
@@ -912,10 +913,28 @@ class UpdateMachine {
     }());
   }
 
+  /// This controls when we start to report transient errors to the user when
+  /// polling.
+  ///
+  /// At the 6th failure, the expected time elapsed since the first failure
+  /// will be 1.55 seocnds.
+  static const transientFailureCountNotifyThreshold = 5;
+
   void poll() async {
     assert(!_disposed);
 
     BackoffMachine? backoffMachine;
+    int accumulatedTransientFailureCount = 0;
+
+    /// This only reports transient errors after reaching
+    /// a pre-defined threshold of retries.
+    void maybeReportTransientError(String? message, {String? details}) {
+      accumulatedTransientFailureCount++;
+      if (accumulatedTransientFailureCount > transientFailureCountNotifyThreshold) {
+        reportErrorToUserBriefly(message, details: details);
+      }
+    }
+
     while (true) {
       if (_debugLoopSignal != null) {
         await _debugLoopSignal!.future;
@@ -935,6 +954,8 @@ class UpdateMachine {
         if (_disposed) return;
 
         store.isLoading = true;
+        final localizations = GlobalLocalizations.zulipLocalizations;
+        final serverUrl = store.connection.realmUrl.origin;
         switch (e) {
           case ZulipApiException(code: 'BAD_EVENT_QUEUE_ID'):
             assert(debugLog('Lost event queue for $store.  Replacing…'));
@@ -946,15 +967,22 @@ class UpdateMachine {
           case Server5xxException() || NetworkException():
             assert(debugLog('Transient error polling event queue for $store: $e\n'
                 'Backing off, then will retry…'));
-            // TODO tell user if transient polling errors persist
+            maybeReportTransientError(
+              localizations.errorConnectingToServerShort,
+              details: localizations.errorConnectingToServerDetails(
+                serverUrl, e.toString()));
             await (backoffMachine ??= BackoffMachine()).wait();
             assert(debugLog('… Backoff wait complete, retrying poll.'));
             continue;
 
           default:
             assert(debugLog('Error polling event queue for $store: $e\n'
                 'Backing off and retrying even though may be hopeless…'));
-            // TODO tell user on non-transient error in polling
+            // TODO(#186): Handle unrecoverable failures
+            reportErrorToUserBriefly(
+              localizations.errorConnectingToServerShort,
+              details: localizations.errorConnectingToServerDetails(
+                serverUrl, e.toString()));
             await (backoffMachine ??= BackoffMachine()).wait();
             assert(debugLog('… Backoff wait complete, retrying poll.'));
             continue;
@@ -978,6 +1006,9 @@ class UpdateMachine {
       // and failures, the successes themselves should space out the requests.
       backoffMachine = null;
       store.isLoading = false;
+      // Dismiss existing errors, if any.
+      reportErrorToUserBriefly(null);
+      accumulatedTransientFailureCount = 0;
 
       final events = result.events;
       for (final event in events) {

test/model/store_test.dart

@@ -1,6 +1,7 @@
 import 'dart:async';
 
 import 'package:checks/checks.dart';
+import 'package:fake_async/fake_async.dart';
 import 'package:flutter/foundation.dart';
 import 'package:http/http.dart' as http;
 import 'package:test/scaffolding.dart';
@@ -12,6 +13,7 @@ import 'package:zulip/api/route/messages.dart';
 import 'package:zulip/api/route/realm.dart';
 import 'package:zulip/model/message_list.dart';
 import 'package:zulip/model/narrow.dart';
+import 'package:zulip/log.dart';
 import 'package:zulip/model/store.dart';
 import 'package:zulip/notifications/receive.dart';
 
@@ -652,6 +654,72 @@ void main() {
     test('retries on MalformedServerResponseException', () {
       checkRetry(() => connection.prepare(httpStatus: 200, body: 'nonsense'));
     });
+
+    group('reportErrorToUserBriefly', () {
+      String? lastReportedError;
+      String? takeLastReportedError() {
+        final result = lastReportedError;
+        lastReportedError = null;
+        return result;
+      }
+
+      /// This is an alternative to [ZulipApp]'s implementation of
+      /// [reportErrorToUserBriefly] for testing.
+      Future<void> logAndReportErrorToUserBriefly(String? message, {
+        String? details,
+      }) async {
+        if (message == null) return;
+        lastReportedError = '$message\n$details';
+      }
+
+      Future<void> prepare() async {
+        reportErrorToUserBriefly = logAndReportErrorToUserBriefly;
+        addTearDown(() => reportErrorToUserBriefly = defaultReportErrorToUserBriefly);
+
+        await prepareStore(lastEventId: 1);
+        updateMachine.debugPauseLoop();
+        updateMachine.poll();
+      }
+
+      late void Function() prepareError;
+
+      void pollAndFail(FakeAsync async) {
+        prepareError();
+        updateMachine.debugAdvanceLoop();
+        async.elapse(Duration.zero);
+        checkLastRequest(lastEventId: 1);
+        check(store).isLoading.isTrue();
+      }
+
+      test('report non-transient errors', () => awaitFakeAsync((async) async {
+        prepareError = () => connection.prepare(httpStatus: 400, json: {
+          'result': 'error', 'code': 'BAD_REQUEST', 'msg': 'Bad request'});
+        await prepare();
+
+        pollAndFail(async);
+        check(takeLastReportedError()).isNotNull().startsWith(
+          "Error connecting to Zulip. Retrying…\n"
+          "Error connecting to Zulip at");
+      }));
+
+      test('report transient errors', () => awaitFakeAsync((async) async {
+        prepareError = () => connection.prepare(httpStatus: 500, body: 'splat');
+        await prepare();
+
+        // There should be no user visible error messages during these retries.
+        for (int i = 0; i < UpdateMachine.transientFailureCountNotifyThreshold; i++) {
+          pollAndFail(async);
+          check(takeLastReportedError()).isNull();
+          // This would skip the pending polling backoff.
+          async.flushTimers();
+        }
+
+        pollAndFail(async);
+        check(takeLastReportedError()).isNotNull().startsWith(
+          "Error connecting to Zulip. Retrying…\n"
+          "Error connecting to Zulip at");
+      }));
+    });
   });
 
   group('UpdateMachine.registerNotificationToken', () {