emoji: Fetch server emoji data (about Unicode emoji)

This completes the data we'll need for use in zulip#669, which in turn
will let us offer an emoji picker for reactions and for use
inside message content.

The doc on fetchEmojiData is based on a comment at the corresponding
code in the legacy zulip-mobile app, in src/events/eventActions.js .

Author: gnprice

lib/model/emoji.dart

@@ -1,6 +1,7 @@
 import '../api/model/events.dart';
 import '../api/model/initial_snapshot.dart';
 import '../api/model/model.dart';
+import '../api/route/realm.dart';
 
 /// An emoji, described by how to display it in the UI.
 sealed class EmojiDisplay {
@@ -61,6 +62,12 @@ mixin EmojiStore {
     required String emojiCode,
     required String emojiName,
   });
+
+  // TODO cut debugServerEmojiData once we can query for lists of emoji;
+  //   have tests make those queries end-to-end
+  Map<String, List<String>>? get debugServerEmojiData;
+
+  void setServerEmojiData(ServerEmojiData data);
 }
 
 /// The implementation of [EmojiStore] that does the work.
@@ -72,7 +79,7 @@ class EmojiStoreImpl with EmojiStore {
   EmojiStoreImpl({
     required this.realmUrl,
     required this.realmEmoji,
-  });
+  }) : _serverEmojiData = null; // TODO(#974) maybe start from a hard-coded baseline
 
   /// The same as [PerAccountStore.realmUrl].
   final Uri realmUrl;
@@ -131,6 +138,21 @@ class EmojiStoreImpl with EmojiStore {
     );
   }
 
+  @override
+  Map<String, List<String>>? get debugServerEmojiData => _serverEmojiData;
+
+  /// The server's list of Unicode emoji and names for them,
+  /// from [ServerEmojiData].
+  ///
+  /// This is null until [UpdateMachine.fetchEmojiData] finishes
+  /// retrieving the data.
+  Map<String, List<String>>? _serverEmojiData;
+
+  @override
+  void setServerEmojiData(ServerEmojiData data) {
+    _serverEmojiData = data.codeToNames;
+  }
+
   void handleRealmEmojiUpdateEvent(RealmEmojiUpdateEvent event) {
     realmEmoji = event.realmEmoji;
   }

lib/model/store.dart

@@ -16,6 +16,7 @@ import '../api/model/model.dart';
 import '../api/route/events.dart';
 import '../api/route/messages.dart';
 import '../api/backoff.dart';
+import '../api/route/realm.dart';
 import '../log.dart';
 import '../notifications/receive.dart';
 import 'autocomplete.dart';
@@ -345,6 +346,15 @@ class PerAccountStore extends ChangeNotifier with EmojiStore, ChannelStore, Mess
       emojiType: emojiType, emojiCode: emojiCode, emojiName: emojiName);
   }
 
+  @override
+  Map<String, List<String>>? get debugServerEmojiData => _emoji.debugServerEmojiData;
+
+  @override
+  void setServerEmojiData(ServerEmojiData data) {
+    _emoji.setServerEmojiData(data);
+    notifyListeners();
+  }
+
   EmojiStoreImpl _emoji;
 
   ////////////////////////////////
@@ -746,6 +756,12 @@ class UpdateMachine {
     final updateMachine = UpdateMachine.fromInitialSnapshot(
       store: store, initialSnapshot: initialSnapshot);
     updateMachine.poll();
+    if (initialSnapshot.serverEmojiDataUrl != null) {
+      // TODO(server-6): If the server is ancient, just skip trying to have
+      //   a list of its emoji.  (The old servers that don't provide
+      //   serverEmojiDataUrl are already unsupported at time of writing.)
+      unawaited(updateMachine.fetchEmojiData(initialSnapshot.serverEmojiDataUrl!));
+    }
     // TODO do registerNotificationToken before registerQueue:
     //   https://github.com/zulip/zulip-flutter/pull/325#discussion_r1365982807
     unawaited(updateMachine.registerNotificationToken());
@@ -772,6 +788,43 @@ class UpdateMachine {
     }
   }
 
+  /// Fetch emoji data from the server, and update the store with the result.
+  ///
+  /// This functions a lot like [registerQueue] and the surrounding logic
+  /// in [load] above, but it's unusual in that we've separated it out.
+  /// Effectively it's data that *would have* been in the [registerQueue]
+  /// response, except that we pulled it out to its own endpoint as part of
+  /// a caching strategy, because the data changes infrequently.
+  ///
+  /// Conveniently (a) this deferred fetch doesn't cause any fetch/event race,
+  /// because this data doesn't get updated by events anyway (it can change
+  /// only on a server restart); and (b) we don't need this data for displaying
+  /// messages or anything else, only for certain UIs like the emoji picker,
+  /// so it's fine that we go without it for a while.
+  Future<void> fetchEmojiData(Uri serverEmojiDataUrl) async {
+    if (!debugEnableFetchEmojiData) return;
+    BackoffMachine? backoffMachine;
+    ServerEmojiData data;
+    while (true) {
+      try {
+        data = await fetchServerEmojiData(store.connection,
+          emojiDataUrl: serverEmojiDataUrl);
+        assert(debugLog('Got emoji data: ${data.codeToNames.length} emoji'));
+        break;
+      } catch (e) {
+        assert(debugLog('Error fetching emoji data: $e\n' // TODO(log)
+          'Backing off, then will retry…'));
+        // The emoji data is a lot less urgent than the initial fetch,
+        // or even the event-queue poll request.  So wait longer.
+        backoffMachine ??= BackoffMachine(firstBound: const Duration(seconds: 2),
+                                          maxBound: const Duration(minutes: 2));
+        await backoffMachine.wait();
+      }
+    }
+
+    store.setServerEmojiData(data);
+  }
+
   Completer<void>? _debugLoopSignal;
 
   /// In debug mode, causes the polling loop to pause before the next
@@ -890,6 +943,26 @@ class UpdateMachine {
     NotificationService.instance.token.removeListener(_registerNotificationToken);
   }
 
+  /// In debug mode, controls whether [fetchEmojiData] should
+  /// have its normal effect.
+  ///
+  /// Outside of debug mode, this is always true and the setter has no effect.
+  static bool get debugEnableFetchEmojiData {
+    bool result = true;
+    assert(() {
+      result = _debugEnableFetchEmojiData;
+      return true;
+    }());
+    return result;
+  }
+  static bool _debugEnableFetchEmojiData = true;
+  static set debugEnableFetchEmojiData(bool value) {
+    assert(() {
+      _debugEnableFetchEmojiData = value;
+      return true;
+    }());
+  }
+
   /// In debug mode, controls whether [registerNotificationToken] should
   /// have its normal effect.
   ///

test/model/store_test.dart

@@ -4,10 +4,12 @@ import 'package:checks/checks.dart';
 import 'package:flutter/foundation.dart';
 import 'package:http/http.dart' as http;
 import 'package:test/scaffolding.dart';
+import 'package:zulip/api/core.dart';
 import 'package:zulip/api/model/events.dart';
 import 'package:zulip/api/model/model.dart';
 import 'package:zulip/api/route/events.dart';
 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/model/store.dart';
@@ -230,6 +232,8 @@ void main() {
       await globalStore.insertAccount(account.toCompanion(false));
       connection = (globalStore.apiConnectionFromAccount(account)
         as FakeApiConnection);
+      UpdateMachine.debugEnableFetchEmojiData = false;
+      addTearDown(() => UpdateMachine.debugEnableFetchEmojiData = true);
       UpdateMachine.debugEnableRegisterNotificationToken = false;
       addTearDown(() => UpdateMachine.debugEnableRegisterNotificationToken = true);
     }
@@ -317,6 +321,69 @@ void main() {
     // TODO test UpdateMachine.load calls registerNotificationToken
   });
 
+  group('UpdateMachine.fetchEmojiData', () {
+    late UpdateMachine updateMachine;
+    late PerAccountStore store;
+    late FakeApiConnection connection;
+
+    void prepareStore() {
+      updateMachine = eg.updateMachine();
+      store = updateMachine.store;
+      connection = store.connection as FakeApiConnection;
+    }
+
+    final emojiDataUrl = Uri.parse('https://cdn.example/emoji.json');
+    final data = {
+      '1f642': ['smile'],
+      '1f34a': ['orange', 'tangerine', 'mandarin'],
+    };
+
+    void checkLastRequest() {
+      check(connection.takeRequests()).single.isA<http.Request>()
+        ..method.equals('GET')
+        ..url.equals(emojiDataUrl)
+        ..headers.deepEquals(kFallbackUserAgentHeader);
+    }
+
+    test('happy case', () => awaitFakeAsync((async) async {
+      prepareStore();
+      check(store.debugServerEmojiData).isNull();
+
+      connection.prepare(json: ServerEmojiData(codeToNames: data).toJson());
+      await updateMachine.fetchEmojiData(emojiDataUrl);
+      checkLastRequest();
+      check(store.debugServerEmojiData).deepEquals(data);
+    }));
+
+    test('retries on failure', () => awaitFakeAsync((async) async {
+      prepareStore();
+      check(store.debugServerEmojiData).isNull();
+
+      // Try to fetch, inducing an error in the request.
+      connection.prepare(exception: Exception('failed'));
+      final future = updateMachine.fetchEmojiData(emojiDataUrl);
+      bool complete = false;
+      future.whenComplete(() => complete = true);
+      async.flushMicrotasks();
+      checkLastRequest();
+      check(complete).isFalse();
+      check(store.debugServerEmojiData).isNull();
+
+      // The retry doesn't happen immediately; there's a timer.
+      check(async.pendingTimers).length.equals(1);
+      async.elapse(Duration.zero);
+      check(connection.lastRequest).isNull();
+      check(async.pendingTimers).length.equals(1);
+
+      // After a timer, we retry.
+      connection.prepare(json: ServerEmojiData(codeToNames: data).toJson());
+      await future;
+      check(complete).isTrue();
+      checkLastRequest();
+      check(store.debugServerEmojiData).deepEquals(data);
+    }));
+  });
+
   group('UpdateMachine.poll', () {
     late TestGlobalStore globalStore;
     late UpdateMachine updateMachine;