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

While we do create outbox messages, there are in no way user-visible
changes since the outbox messages don't end up in message list views.
We create skeletons for helpers needed from message list view, but don't
implement them yet, to make the diff smaller.

---

OutboxMessage is designed to keep the timers internal to itself, and
expose only the callback functions, to keep message store code simple.

To make sure that OutboxMessage.dispose is always called when the outbox
message is removed from the store, we expose an unmodifiable view of the
actual map.

For testing, similar to TypingNotifier.debugEnabled, we add
MessageStoreImpl.debugOutboxEnabled in case a test does 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,175 @@ 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);
+const kSendMessageTimeLimit = Duration(seconds: 10);
+
+/// 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> {
+  OutboxMessage({
+    required this.localMessageId,
+    required int selfUserId,
+    required this.content,
+    required this.onDebounceTimeout,
+    required this.onSendTimeLimitTimeout,
+  }) : senderId = selfUserId,
+       timestamp = (DateTime.timestamp().millisecondsSinceEpoch / 1000).toInt(),
+       _state = OutboxMessageLifecycle.sending,
+       _debounceTimer = Timer(kLocalEchoDebounceDuration, onDebounceTimeout),
+       _sendTimeLimitTimer = Timer(kSendMessageTimeLimit, onSendTimeLimitTimeout);
+
+  static OutboxMessage fromDestination(MessageDestination destination, {
+    required int localMessageId,
+    required int selfUserId,
+    required String content,
+    required VoidCallback onDebounceTimeout,
+    required VoidCallback onSendTimeLimitTimeout,
+  }) {
+    return switch (destination) {
+      StreamDestination() => StreamOutboxMessage(
+        localMessageId: localMessageId,
+        selfUserId: selfUserId,
+        recipient: StreamRecipient(destination.streamId, destination.topic),
+        content: content,
+        onDebounceTimeout: onDebounceTimeout,
+        onSendTimeLimitTimeout: onSendTimeLimitTimeout,
+      ),
+      DmDestination() => DmOutboxMessage(
+        localMessageId: localMessageId,
+        selfUserId: selfUserId,
+        recipient: DmRecipient.fromDmDestination(destination, selfUserId: selfUserId),
+        content: content,
+        onDebounceTimeout: onDebounceTimeout,
+        onSendTimeLimitTimeout: onSendTimeLimitTimeout,
+      ),
+    };
+  }
+
+  /// ID corresponding to [MessageEvent.localMessageId], which uniquely
+  /// identifies a locally echoed message in events from the same event queue.
+  ///
+  /// See also [sendMessage].
+  final int localMessageId;
+  @override
+  int? get id => null;
+  @override
+  final int senderId;
+  @override
+  final int timestamp;
+  final String content;
+
+  /// Called after [kLocalEchoDebounceDuration] if the outbox message is still
+  /// [hidden].
+  ///
+  /// If [hidden] gets set to false before the timeout, this will not get called.
+  final VoidCallback onDebounceTimeout;
+  final Timer _debounceTimer;
+
+  /// Called after the time limit ([kSendMessageTimeLimit]) for the message
+  /// event to arrive.
+  ///
+  /// If the [state] is [OutboxMessageLifecycle.failed] prior to the time limit
+  /// this will not get called.
+  final VoidCallback onSendTimeLimitTimeout;
+  final Timer _sendTimeLimitTimer;
+
+  OutboxMessageLifecycle get state => _state;
+  OutboxMessageLifecycle _state;
+  set state(OutboxMessageLifecycle value) {
+    assert(!_disposed);
+    // See [OutboxMessageLifecycle] for valid state transitions.
+    assert(_state != value);
+    switch (value) {
+      case OutboxMessageLifecycle.sending:
+        assert(false);
+      case OutboxMessageLifecycle.sent:
+        assert(_state == OutboxMessageLifecycle.sending);
+      case OutboxMessageLifecycle.failed:
+        assert(_state == OutboxMessageLifecycle.sending || _state == OutboxMessageLifecycle.sent);
+        _sendTimeLimitTimer.cancel();
+    }
+    _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(!_disposed);
+    assert(_hidden);
+    _debounceTimer.cancel();
+    _hidden = false;
+  }
+
+  bool _disposed = false;
+  /// Clean up all pending timers to prepare for abandoning this instance.
+  ///
+  /// This must be called whenever the outbox message is removed from the store.
+  void dispose() {
+    assert(!_disposed);
+    _disposed = true;
+    _debounceTimer.cancel();
+    _sendTimeLimitTimer.cancel();
+  }
+}
+
+class StreamOutboxMessage extends OutboxMessage<StreamRecipient> {
+  StreamOutboxMessage({
+    required super.localMessageId,
+    required super.selfUserId,
+    required this.recipient,
+    required super.content,
+    required super.onDebounceTimeout,
+    required super.onSendTimeLimitTimeout,
+  });
+
+  @override
+  final StreamRecipient recipient;
+}
+
+class DmOutboxMessage extends OutboxMessage<DmRecipient> {
+  DmOutboxMessage({
+    required super.localMessageId,
+    required super.selfUserId,
+    required this.recipient,
+    required super.content,
+    required super.onDebounceTimeout,
+    required super.onSendTimeLimitTimeout,
+  });
+
+  @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 +191,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 +213,21 @@ 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 [PerAccountStore] instance.
+  int _nextLocalMessageId = 0;
 
   @override
   final Map<int, Message> messages;
 
+  @override
+  late final UnmodifiableMapView<int, OutboxMessage> outboxMessages =
+    UnmodifiableMapView(_outboxMessages);
+  final Map<int, OutboxMessage> _outboxMessages;
+
   final Set<MessageListView> _messageListViews = {};
 
   @override
@@ -84,17 +266,111 @@ 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 outboxMessage in outboxMessages.values) {
+      outboxMessage.dispose();
+    }
+    _outboxMessages.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,
+  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));
+    _outboxMessages[localMessageId] = OutboxMessage.fromDestination(destination,
+      localMessageId: localMessageId,
+      selfUserId: selfUserId,
       content: content,
-      readBySender: true,
+      onDebounceTimeout: () {
+        assert(outboxMessages.containsKey(localMessageId));
+        _unhideOutboxMessage(localMessageId);
+      },
+      onSendTimeLimitTimeout: () {
+        assert(outboxMessages.containsKey(localMessageId));
+        // This should be called before `_unhideOutboxMessage(localMessageId)`
+        // to avoid unnecessarily notifying the listeners twice.
+        _updateOutboxMessage(localMessageId, newState: OutboxMessageLifecycle.failed);
+        _unhideOutboxMessage(localMessageId);
+      },
     );
+
+    try {
+      await _apiSendMessage(connection,
+        destination: destination,
+        content: content,
+        readBySender: true,
+        queueId: queueId,
+        localId: localMessageId.toString());
+      if (_outboxMessages[localMessageId]?.state == OutboxMessageLifecycle.failed) {
+        // Reached time limit while request was pending.
+        // No state update is needed.
+        return;
+      }
+      _updateOutboxMessage(localMessageId, newState: OutboxMessageLifecycle.sent);
+    } catch (e) {
+      // This should be called before `_unhideOutboxMessage(localMessageId)`
+      // to avoid unnecessarily notifying the listeners twice.
+      _updateOutboxMessage(localMessageId, newState: OutboxMessageLifecycle.failed);
+      _unhideOutboxMessage(localMessageId);
+      rethrow;
+    }
+  }
+
+  /// Unhide the [OutboxMessage] with the given [localMessageId],
+  /// and notify listeners if necessary.
+  ///
+  /// This is a no-op if the outbox message does not exist or is not hidden.
+  void _unhideOutboxMessage(int localMessageId) {
+    final outboxMessage = outboxMessages[localMessageId];
+    if (outboxMessage == null || !outboxMessage.hidden) {
+      return;
+    }
+    outboxMessage.unhide();
+    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 the outbox message does not exists, or that
+  /// [OutboxMessage.state] already equals [newState].
+  void _updateOutboxMessage(int localMessageId, {
+    required OutboxMessageLifecycle newState,
+  }) {
+    final outboxMessage = outboxMessages[localMessageId];
+    if (outboxMessage == null || outboxMessage.state == newState) {
+      return;
+    }
+    outboxMessage.state = newState;
+    if (outboxMessage.hidden) {
+      return;
+    }
+    for (final view in _messageListViews) {
+      view.notifyListenersIfOutboxMessagePresent(localMessageId);
+    }
+  }
+
+
+  @override
+  void removeOutboxMessage(int localMessageId) {
+    final removed = _outboxMessages.remove(localMessageId)?..dispose();
+    if (removed == null) {
+      assert(false, 'Removing unknown outbox message with localMessageId: $localMessageId');
+      return;
+    }
+    for (final view in _messageListViews) {
+      view.removeOutboxMessageIfExists(removed);
+    }
   }
 
   @override
@@ -132,6 +408,11 @@ 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)?.dispose();
+    }
+
     for (final view in _messageListViews) {
       view.handleMessageEvent(event);
     }
@@ -325,4 +606,29 @@ class MessageStoreImpl extends PerAccountStoreBase with MessageStore {
     // [Poll] is responsible for notifying the affected listeners.
     poll.handleSubmessageEvent(event);
   }
+
+  /// 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;
+  }
 }