wip; message: Create an outbox message on send; manage its states

While we are creating these outbox messages, they are in no way
user-visible changes since they don't end up in message list views
right now.

Similar to TypingNotifier.debugEnabled, we add
MessageStoreImpl.debugOutboxEnabled for tests that do not intend to
cover outbox messages.

Author: PIG208

lib/api/model/model.dart

@@ -559,6 +559,13 @@ class DmRecipient extends Recipient {
   DmRecipient({required this.allRecipientIds})
     : assert(isSortedWithoutDuplicates(allRecipientIds.toList()));
 
+  factory DmRecipient.fromDmDestination(DmDestination destination, {
+    required int selfUserId,
+  }) {
+    assert(destination.userIds.contains(selfUserId));
+    return DmRecipient(allRecipientIds: destination.userIds);
+  }
+
   /// The user IDs of all users in the thread, sorted numerically.
   ///
   /// This lists the sender as well as all (other) recipients, and it

lib/model/message.dart

@@ -1,5 +1,9 @@
+import 'dart:async';
+import 'dart:collection';
 import 'dart:convert';
 
+import 'package:flutter/foundation.dart';
+
 import '../api/model/events.dart';
 import '../api/model/model.dart';
 import '../api/route/messages.dart';
@@ -8,12 +12,129 @@ import 'message_list.dart';
 import 'store.dart';
 
 const _apiSendMessage = sendMessage; // Bit ugly; for alternatives, see: https://chat.zulip.org/#narrow/stream/243-mobile-team/topic/flutter.3A.20PerAccountStore.20methods/near/1545809
+const kLocalEchoDebounceDuration = Duration(milliseconds: 300);
+
+/// States outlining where an [OutboxMessage] is, in its lifecycle.
+///
+/// ```
+////                              ┌─────────────────────────────────────┐
+///                               │                  Event received,    │
+///               Send            │                  or we abandoned    │
+///            immediately.       │     200.         the queue.         ▼
+///  (create) ──────────────► sending ──────► sent ────────────────► (delete)
+///                               │                                     ▲
+///                               │ 4xx or                     User     │
+///                               │ other error.               cancels. │
+///                               └────────► failed ────────────────────┘
+/// ```
+enum OutboxMessageLifecycle {
+  sending,
+  sent,
+  failed,
+}
+
+/// A message sent by the self-user.
+sealed class OutboxMessage<T extends Recipient> implements MessageBase<T> {
+  /// Construct a new [OutboxMessage] with a unique [localMessageId].
+  OutboxMessage({
+    required this.localMessageId,
+    required int selfUserId,
+    required this.content,
+  }) : senderId = selfUserId,
+       timestamp = (DateTime.timestamp().millisecondsSinceEpoch / 1000).toInt(),
+       _state = OutboxMessageLifecycle.sending;
+
+  static OutboxMessage fromDestination(MessageDestination destination, {
+    required int localMessageId,
+    required int selfUserId,
+    required String content,
+  }) {
+    return switch (destination) {
+      StreamDestination() => StreamOutboxMessage(
+        localMessageId: localMessageId,
+        selfUserId: selfUserId,
+        recipient: StreamRecipient(destination.streamId, destination.topic),
+        content: content,
+      ),
+      DmDestination() => DmOutboxMessage(
+        localMessageId: localMessageId,
+        selfUserId: selfUserId,
+        recipient: DmRecipient.fromDmDestination(destination, selfUserId: selfUserId),
+        content: content,
+      ),
+    };
+  }
+
+  @override
+  int? get id => null;
+
+  @override
+  final int senderId;
+  @override
+  final int timestamp;
+  final String content;
+
+  /// ID corresponding to [MessageEvent.localMessageId], which identifies a
+  /// locally echoed message.
+  final int localMessageId;
+
+  OutboxMessageLifecycle get state => _state;
+  OutboxMessageLifecycle _state;
+  set state(OutboxMessageLifecycle value) {
+    // See [OutboxMessageLifecycle] for valid state transitions.
+    switch (value) {
+      case OutboxMessageLifecycle.sending:
+        assert(false);
+      case OutboxMessageLifecycle.sent:
+      case OutboxMessageLifecycle.failed:
+        assert(_state == OutboxMessageLifecycle.sending);
+    }
+    _state = value;
+  }
+
+  /// Whether the [OutboxMessage] will be hidden to [MessageListView] or not.
+  ///
+  /// When set to false with [unhide], this cannot be toggled back to true again.
+  bool get hidden => _hidden;
+  bool _hidden = true;
+  void unhide() {
+    assert(_hidden);
+    _hidden = false;
+  }
+}
+
+class StreamOutboxMessage extends OutboxMessage<StreamRecipient> {
+  StreamOutboxMessage({
+    required super.localMessageId,
+    required super.selfUserId,
+    required this.recipient,
+    required super.content,
+  });
+
+  @override
+  final StreamRecipient recipient;
+}
+
+class DmOutboxMessage extends OutboxMessage<DmRecipient> {
+  DmOutboxMessage({
+    required super.localMessageId,
+    required super.selfUserId,
+    required this.recipient,
+    required super.content,
+  });
+
+  @override
+  final DmRecipient recipient;
+}
 
 /// The portion of [PerAccountStore] for messages and message lists.
 mixin MessageStore {
   /// All known messages, indexed by [Message.id].
   Map<int, Message> get messages;
 
+  /// Messages sent by the user, indexed by [OutboxMessage.localMessageId].
+  Map<int, OutboxMessage> get outboxMessages;
+
   Set<MessageListView> get debugMessageListViews;
 
   void registerMessageList(MessageListView view);
@@ -24,6 +145,11 @@ mixin MessageStore {
     required String content,
   });
 
+  /// Remove from [outboxMessages] given the [localMessageId].
+  ///
+  /// The message to remove must already exist.
+  void removeOutboxMessage(int localMessageId);
+
   /// Reconcile a batch of just-fetched messages with the store,
   /// mutating the list.
   ///
@@ -41,11 +167,28 @@ class MessageStoreImpl extends PerAccountStoreBase with MessageStore {
   MessageStoreImpl({required super.core})
     // There are no messages in InitialSnapshot, so we don't have
     // a use case for initializing MessageStore with nonempty [messages].
-    : messages = {};
+    : messages = {},
+      _outboxMessages = {};
+
+  /// A fresh ID to use for [OutboxMessage.localMessageId], unique within the
+  /// current event queue.
+  int _nextLocalMessageId = 0;
 
   @override
   final Map<int, Message> messages;
 
+  @override
+  late final UnmodifiableMapView<int, OutboxMessage> outboxMessages =
+    UnmodifiableMapView(_outboxMessages);
+  final Map<int, OutboxMessage> _outboxMessages;
+
+  /// The timers for debouncing outbox messages, indexed by
+  /// [OutboxMessage.localMessageId].
+  ///
+  /// It is guaranteed that all timers tracked here are active, and each
+  /// corresponds to an outbox message where [OutboxMessage.hidden] is true.
+  final Map<int, Timer> _outboxMessageDebounceTimers = {};
+
   final Set<MessageListView> _messageListViews = {};
 
   @override
@@ -84,17 +227,135 @@ class MessageStoreImpl extends PerAccountStoreBase with MessageStore {
     //   [InheritedNotifier] to rebuild in the next frame) before the owner's
     //   `dispose` or `onNewStore` is called.  Discussion:
     //     https://chat.zulip.org/#narrow/channel/243-mobile-team/topic/MessageListView.20lifecycle/near/2086893
+
+    for (final timer in _outboxMessageDebounceTimers.values) {
+      timer.cancel();
+    }
+    _outboxMessageDebounceTimers.clear();
   }
 
   @override
-  Future<void> sendMessage({required MessageDestination destination, required String content}) {
-    // TODO implement outbox; see design at
-    //   https://chat.zulip.org/#narrow/stream/243-mobile-team/topic/.23M3881.20Sending.20outbox.20messages.20is.20fraught.20with.20issues/near/1405739
-    return _apiSendMessage(connection,
-      destination: destination,
-      content: content,
-      readBySender: true,
-    );
+  Future<void> sendMessage({required MessageDestination destination, required String content}) async {
+    if (!debugOutboxEnabled) {
+      await _apiSendMessage(connection,
+        destination: destination,
+        content: content,
+        readBySender: true);
+      return;
+    }
+
+    final localMessageId = _nextLocalMessageId++;
+    assert(!outboxMessages.containsKey(localMessageId));
+    assert(!_outboxMessageDebounceTimers.containsKey(localMessageId));
+    _outboxMessages[localMessageId] = OutboxMessage.fromDestination(destination,
+      localMessageId: localMessageId,
+      selfUserId: selfUserId,
+      content: content);
+    _outboxMessageDebounceTimers[localMessageId] =
+      Timer(kLocalEchoDebounceDuration, () => _unhideOutboxMessage(localMessageId));
+
+    try {
+      await _apiSendMessage(connection,
+        destination: destination,
+        content: content,
+        readBySender: true,
+        queueId: queueId,
+        localId: localMessageId.toString());
+      _updateOutboxMessage(localMessageId, newState: OutboxMessageLifecycle.sent);
+    } catch (e) {
+      final outboxMessage = outboxMessages[localMessageId];
+      if (outboxMessage == null) {
+        // The message event arrived while the message was being sent;
+        // nothing else to do here.
+        assert(!_outboxMessageDebounceTimers.containsKey(localMessageId));
+        rethrow;
+      }
+      // This should be called before `_unhideOutboxMessage(localMessageId)`
+      // to avoid unnecessarily notifying the listeners twice.
+      _updateOutboxMessage(localMessageId, newState: OutboxMessageLifecycle.failed);
+      if (outboxMessage.hidden) {
+        _unhideOutboxMessage(localMessageId);
+      }
+      rethrow;
+    }
+  }
+
+  @override
+  void removeOutboxMessage(int localMessageId) {
+    final removed = _outboxMessages.remove(localMessageId);
+    _outboxMessageDebounceTimers.remove(localMessageId)?.cancel();
+    if (removed == null) {
+      assert(false, 'Removing unknown outbox message with localMessageId: $localMessageId');
+      return;
+    }
+    for (final view in _messageListViews) {
+      view.removeOutboxMessageIfExists(removed);
+    }
+  }
+
+  /// Unhide the [OutboxMessage] with the given [localMessageId]
+  /// and notify listeners.
+  ///
+  /// The outbox message must exist and have been hidden.
+  void _unhideOutboxMessage(int localMessageId) {
+    final outboxMessage = outboxMessages[localMessageId];
+    final debounceTimer = _outboxMessageDebounceTimers.remove(localMessageId);
+    assert(debounceTimer != null,
+      'Every hidden outbox message should have a debounce timer.');
+    if (outboxMessage == null || debounceTimer == null) {
+      assert(false);
+      return;
+    }
+    outboxMessage.unhide();
+    debounceTimer.cancel();
+    for (final view in _messageListViews) {
+      view.handleOutboxMessage(outboxMessage);
+    }
+  }
+
+  /// Update the state of the [OutboxMessage] with the given [localMessageId],
+  /// and notify listeners if necessary.
+  ///
+  /// This is a no-op if no outbox message with [localMessageId] exists.
+  void _updateOutboxMessage(int localMessageId, {
+    required OutboxMessageLifecycle newState,
+  }) {
+    final outboxMessage = outboxMessages[localMessageId];
+    if (outboxMessage == null) {
+      return;
+    }
+    outboxMessage.state = newState;
+    if (outboxMessage.hidden) {
+      return;
+    }
+    for (final view in _messageListViews) {
+      view.notifyListenersIfOutboxMessagePresent(localMessageId);
+    }
+  }
+
+  /// In debug mode, controls whether outbox messages should be created when
+  /// [sendMessage] is called.
+  ///
+  /// Outside of debug mode, this is always true and the setter has no effect.
+  static bool get debugOutboxEnabled {
+    bool result = true;
+    assert(() {
+      result = _debugOutboxEnabled;
+      return true;
+    }());
+    return result;
+  }
+  static bool _debugOutboxEnabled = true;
+  static set debugOutboxEnabled(bool value) {
+    assert(() {
+      _debugOutboxEnabled = value;
+      return true;
+    }());
+  }
+
+  @visibleForTesting
+  static void debugReset() {
+    _debugOutboxEnabled = true;
   }
 
   @override
@@ -132,6 +393,12 @@ class MessageStoreImpl extends PerAccountStoreBase with MessageStore {
     // See [fetchedMessages] for reasoning.
     messages[event.message.id] = event.message;
 
+    if (event.localMessageId != null) {
+      final localMessageId = int.parse(event.localMessageId!, radix: 10);
+      _outboxMessages.remove(localMessageId);
+      _outboxMessageDebounceTimers.remove(localMessageId)?.cancel();
+    }
+
     for (final view in _messageListViews) {
       view.handleMessageEvent(event);
     }

lib/model/message_list.dart

@@ -10,6 +10,7 @@ import '../api/route/messages.dart';
 import 'algorithms.dart';
 import 'channel.dart';
 import 'content.dart';
+import 'message.dart';
 import 'narrow.dart';
 import 'store.dart';
 
@@ -650,6 +651,17 @@ class MessageListView with ChangeNotifier, _MessageSequence {
     }
   }
 
+  void handleOutboxMessage(OutboxMessage outboxMessage) {
+    // TODO: implement this
+  }
+
+  /// Remove the [outboxMessage] from the view.
+  ///
+  /// This is a no-op if the message is not found.
+  void removeOutboxMessageIfExists(OutboxMessage outboxMessage) {
+    // TODO: implement this
+  }
+
   void handleUserTopicEvent(UserTopicEvent event) {
     switch (_canAffectVisibility(event)) {
       case VisibilityEffect.none:
@@ -811,6 +823,11 @@ class MessageListView with ChangeNotifier, _MessageSequence {
     }
   }
 
+  /// Notify listeners if the given outbox message is present in this view.
+  void notifyListenersIfOutboxMessagePresent(int localMessageId) {
+    // TODO: implement this
+  }
+
   /// Called when the app is reassembled during debugging, e.g. for hot reload.
   ///
   /// This will redo from scratch any computations we can, such as parsing