api [nfc]: Pull out MessageBase and Recipient

See also CZO discussion on the design of this, and the drawbacks of
the alternatives:
  https://chat.zulip.org/#narrow/channel/243-mobile-team/topic/A.20new.20variant.20of.20Zulip.20messages.20-.20inheritance.20structure/with/2141288

This will help support outbox messages in MessageListView later.

This requiring specifying the element type of `List`s in some tests (or
in some cases, the type of a variable declared).

This is a side effect of making `StreamMessage` and `DmMessage` extend
`Message<T>` with different `T`'s. When both appear in the same `List`,
the upper bound is `Object`, instead of the more specific
`Message<Recipient>`.
See "least-upper-bound" tagged issues for reference:
  https://github.com/dart-lang/language/issues?q=state%3Aopen%20label%3A%22least-upper-bound%22

We extracted Recipient instead of using MessageDestination because they
are foundamentally different. Recipient is the identifier for the
conversation that contains the message from, for example, get-messages or message
events, but MessageDestination is specifically for send-message.

Author: PIG208

lib/api/model/model.dart

@@ -1,5 +1,7 @@
 import 'package:json_annotation/json_annotation.dart';
 
+import '../../model/algorithms.dart';
+import '../route/messages.dart';
 import 'events.dart';
 import 'initial_snapshot.dart';
 import 'reaction.dart';
@@ -531,10 +533,68 @@ String? tryParseEmojiCodeToUnicode(String emojiCode) {
   }
 }
 
+/// As in [MessageBase.recipient].
+///
+/// Different from [MessageDestination], this information comes from
+/// [getMessages] or [getEvents], identifying the conversation that contains a
+/// message.
+sealed class Recipient {}
+
+/// The recipient of a stream message.
+@JsonSerializable(fieldRename: FieldRename.snake, createToJson: false)
+class StreamRecipient extends Recipient {
+  StreamRecipient(this.streamId, this.topic);
+
+  int streamId;
+
+  @JsonKey(name: 'subject')
+  TopicName topic;
+
+  factory StreamRecipient.fromJson(Map<String, dynamic> json) =>
+    _$StreamRecipientFromJson(json);
+}
+
+/// The recipient of a DM message.
+class DmRecipient extends Recipient {
+  DmRecipient({required this.allRecipientIds})
+    : assert(isSortedWithoutDuplicates(allRecipientIds.toList()));
+
+  /// The user IDs of all users in the thread, sorted numerically.
+  ///
+  /// This lists the sender as well as all (other) recipients, and it
+  /// lists each user just once.  In particular the self-user is always
+  /// included.
+  ///
+  /// This is required to have an efficient `length`.
+  final Iterable<int> allRecipientIds;
+}
+
+/// A message or message-like object, for showing in a message list.
+///
+/// Other than [Message], we use this for "outbox messages",
+/// representing outstanding [sendMessage] requests.
+abstract class MessageBase<T extends Recipient> {
+  /// The Zulip message ID.
+  ///
+  /// If null, the message doesn't have an ID acknowledged by the server
+  /// (e.g.: a locally-echoed message).
+  int? get id;
+
+  int get senderId;
+  int get timestamp;
+
+  /// The recipient of this message.
+  // When implementing this, the return type should be either [StreamRecipient]
+  // or [DmRecipient]; it should never be [Recipient], because we
+  // expect a concrete subclass of [MessageBase] to represent either
+  // a channel message or a DM message, not both.
+  T get recipient;
+}
+
 /// As in the get-messages response.
 ///
 /// https://zulip.com/api/get-messages#response
-sealed class Message {
+sealed class Message<T extends Recipient> implements MessageBase<T> {
   // final String? avatarUrl; // Use [User.avatarUrl] instead; will live-update
   final String client;
   String content;
@@ -544,6 +604,7 @@ sealed class Message {
   @JsonKey(readValue: MessageEditState._readFromMessage, fromJson: Message._messageEditStateFromJson)
   MessageEditState editState;
 
+  @override
   final int id;
   bool isMeMessage;
   int? lastEditTimestamp;
@@ -554,13 +615,15 @@ sealed class Message {
   final int recipientId;
   final String senderEmail;
   final String senderFullName;
+  @override
   final int senderId;
   final String senderRealmStr;
 
   /// Poll data if "submessages" describe a poll, `null` otherwise.
   @JsonKey(name: 'submessages', readValue: _readPoll, fromJson: Poll.fromJson, toJson: Poll.toJson)
   Poll? poll;
 
+  @override
   final int timestamp;
   String get type;
 
@@ -619,6 +682,8 @@ sealed class Message {
     required this.matchTopic,
   });
 
+  // TODO(dart): This has to be a static method, because factories/constructors
+  //   do not support type parameters: https://github.com/dart-lang/language/issues/647
   static Message fromJson(Map<String, dynamic> json) {
     final type = json['type'] as String;
     if (type == 'stream') return StreamMessage.fromJson(json);
@@ -715,7 +780,7 @@ extension type const TopicName(String _value) {
 }
 
 @JsonSerializable(fieldRename: FieldRename.snake)
-class StreamMessage extends Message {
+class StreamMessage extends Message<StreamRecipient> {
   @override
   @JsonKey(includeToJson: true)
   String get type => 'stream';
@@ -726,14 +791,23 @@ class StreamMessage extends Message {
   @JsonKey(required: true, disallowNullValue: true)
   String? displayRecipient;
 
-  int streamId;
+  @JsonKey(includeToJson: true)
+  int get streamId => recipient.streamId;
 
   // The topic/subject is documented to be present on DMs too, just empty.
   // We ignore it on DMs; if a future server introduces distinct topics in DMs,
   // that will need new UI that we'll design then as part of that feature,
   // and ignoring the topics seems as good a fallback behavior as any.
-  @JsonKey(name: 'subject')
-  TopicName topic;
+  @JsonKey(name: 'subject', includeToJson: true)
+  TopicName get topic => recipient.topic;
+
+  @override
+  @JsonKey(readValue: _readRecipient, includeToJson: false)
+  StreamRecipient recipient;
+
+  static Map<String, dynamic> _readRecipient(Map<dynamic, dynamic> json, String key) {
+    return {'stream_id': json['stream_id'], 'subject': json['subject']};
+  }
 
   StreamMessage({
     required super.client,
@@ -754,8 +828,7 @@ class StreamMessage extends Message {
     required super.matchContent,
     required super.matchTopic,
     required this.displayRecipient,
-    required this.streamId,
-    required this.topic,
+    required this.recipient,
   });
 
   factory StreamMessage.fromJson(Map<String, dynamic> json) =>
@@ -809,7 +882,7 @@ class DmDisplayRecipientListConverter extends JsonConverter<List<DmDisplayRecipi
 }
 
 @JsonSerializable(fieldRename: FieldRename.snake)
-class DmMessage extends Message {
+class DmMessage extends Message<DmRecipient> {
   @override
   @JsonKey(includeToJson: true)
   String get type => 'private';
@@ -829,15 +902,12 @@ class DmMessage extends Message {
   @DmDisplayRecipientListConverter()
   final List<DmDisplayRecipient> displayRecipient;
 
-  /// The user IDs of all users in the thread, sorted numerically.
-  ///
-  /// This lists the sender as well as all (other) recipients, and it
-  /// lists each user just once.  In particular the self-user is always
-  /// included.
-  ///
-  /// This is a result of [List.map], so it has an efficient `length`.
+  // This is a result of [List.map], so it has an efficient `length`.
   Iterable<int> get allRecipientIds => displayRecipient.map((e) => e.id);
 
+  @override
+  DmRecipient get recipient => DmRecipient(allRecipientIds: allRecipientIds);
+
   DmMessage({
     required super.client,
     required super.content,

lib/api/model/model.g.dart

@@ -213,14 +213,14 @@ class MessageStoreImpl with MessageStore {
       }
 
       if (newStreamId != origStreamId) {
-        message.streamId = newStreamId;
+        message.recipient.streamId = newStreamId;
         // See [StreamMessage.displayRecipient] on why the invalidation is
         // needed.
         message.displayRecipient = null;
       }
 
       if (newTopic != origTopic) {
-        message.topic = newTopic;
+        message.recipient.topic = newTopic;
       }
 
       if (!wasResolveOrUnresolve

lib/model/message.dart

@@ -235,6 +235,7 @@ class DmNarrow extends Narrow implements SendableNarrow {
   /// See also:
   /// * [otherRecipientIds], an alternate way of identifying the conversation.
   /// * [DmMessage.allRecipientIds], which provides this same format.
+  /// * [DmRecipient.allRecipientIds], which also provides this same format.
   final List<int> allRecipientIds;
 
   /// The user ID of the self-user.

lib/model/narrow.dart

@@ -24,6 +24,13 @@ extension UserChecks on Subject<User> {
 extension ZulipStreamChecks on Subject<ZulipStream> {
 }
 
+extension MessageBaseChecks<T extends Recipient> on Subject<MessageBase<T>> {
+  Subject<int?> get id => has((e) => e.id, 'id');
+  Subject<int> get senderId => has((e) => e.senderId, 'senderId');
+  Subject<int> get timestamp => has((e) => e.timestamp, 'timestamp');
+  Subject<T> get recipient => has((e) => e.recipient, 'recipient');
+}
+
 extension MessageChecks on Subject<Message> {
   Subject<String> get client => has((e) => e.client, 'client');
   Subject<String> get content => has((e) => e.content, 'content');
@@ -36,10 +43,8 @@ extension MessageChecks on Subject<Message> {
   Subject<int> get recipientId => has((e) => e.recipientId, 'recipientId');
   Subject<String> get senderEmail => has((e) => e.senderEmail, 'senderEmail');
   Subject<String> get senderFullName => has((e) => e.senderFullName, 'senderFullName');
-  Subject<int> get senderId => has((e) => e.senderId, 'senderId');
   Subject<String> get senderRealmStr => has((e) => e.senderRealmStr, 'senderRealmStr');
   Subject<Poll?> get poll => has((e) => e.poll, 'poll');
-  Subject<int> get timestamp => has((e) => e.timestamp, 'timestamp');
   Subject<String> get type => has((e) => e.type, 'type');
   Subject<List<MessageFlag>> get flags => has((e) => e.flags, 'flags');
   Subject<String?> get matchContent => has((e) => e.matchContent, 'matchContent');

test/api/model/model_checks.dart

@@ -526,7 +526,7 @@ void main() {
     test('unmute a topic -> refetch from scratch', () => awaitFakeAsync((async) async {
       await prepare(narrow: const CombinedFeedNarrow());
       await prepareMutes(true);
-      final messages = [
+      final messages = <Message>[
         eg.dmMessage(id: 1, from: eg.otherUser, to: [eg.selfUser]),
         eg.streamMessage(id: 2, stream: stream, topic: topic),
       ];

test/model/message_list_test.dart

@@ -82,7 +82,7 @@ void main() {
       final message1 = eg.streamMessage();
       final message2 = eg.streamMessage();
       final message3 = eg.dmMessage(from: eg.otherUser, to: [eg.selfUser]);
-      final messages = [message1, message2, message3];
+      final messages = <Message>[message1, message2, message3];
       store.reconcileMessages(messages);
       check(messages).deepEquals(
         [message1, message2, message3]
@@ -97,7 +97,7 @@ void main() {
       final message1 = eg.streamMessage();
       final message2 = eg.streamMessage();
       final message3 = eg.dmMessage(from: eg.otherUser, to: [eg.selfUser]);
-      final messages = [message1, message2, message3];
+      final messages = <Message>[message1, message2, message3];
       await addMessages(messages);
       final newMessage = eg.streamMessage();
       store.reconcileMessages([newMessage]);
@@ -137,7 +137,7 @@ void main() {
 
     test('from not-empty', () async {
       await prepare();
-      final messages = [
+      final messages = <Message>[
         eg.streamMessage(),
         eg.streamMessage(),
         eg.dmMessage(from: eg.otherUser, to: [eg.selfUser]),

test/model/message_test.dart

@@ -248,7 +248,7 @@ void main() {
     final unreadChannelMessage = eg.streamMessage(flags: []);
     final readChannelMessage = eg.streamMessage(flags: [MessageFlag.read]);
 
-    final allMessages = [
+    final allMessages = <Message>[
       unreadDmMessage, unreadChannelMessage,
       readDmMessage,   readChannelMessage,
     ];
@@ -315,7 +315,7 @@ void main() {
           if (isDirectMentioned)   MessageFlag.mentioned,
           if (isWildcardMentioned) MessageFlag.wildcardMentioned,
         ];
-        final message = isStream
+        final Message message = isStream
           ? eg.streamMessage(flags: flags)
           : eg.dmMessage(from: eg.otherUser, to: [eg.selfUser], flags: flags);
         model.handleMessageEvent(eg.messageEvent(message));
@@ -402,7 +402,7 @@ void main() {
       for (final isKnownToModel in [true, false]) {
         for (final isRead in [false, true]) {
           final baseFlags = [if (isRead) MessageFlag.read];
-          for (final (messageDesc, message) in [
+          for (final (messageDesc, message) in <(String, Message)>[
             ('stream', eg.streamMessage(flags: baseFlags)),
             ('1:1 dm', eg.dmMessage(from: eg.otherUser, to: [eg.selfUser], flags: baseFlags)),
           ]) {
@@ -662,7 +662,7 @@ void main() {
     final message13 = eg.streamMessage(id: 13, stream: stream2, topic: 'b', flags: []);
     final message14 = eg.streamMessage(id: 14, stream: stream2, topic: 'b', flags: [MessageFlag.mentioned]);
 
-    final messages = [
+    final messages = <Message>[
       message1, message2, message3, message4, message5,
       message6, message7, message8, message9, message10,
       message11, message12, message13, message14,
@@ -849,7 +849,7 @@ void main() {
       // That case is indistinguishable from an unread that's unknown to
       // the model, so we get coverage for that case too.
       test('add flag: ${mentionFlag.name}', () {
-        final messages = [
+        final messages = <Message>[
           eg.streamMessage(flags: []),
           eg.streamMessage(flags: [MessageFlag.read]),
           eg.dmMessage(from: eg.otherUser, to: [eg.selfUser], flags: []),
@@ -886,7 +886,7 @@ void main() {
       // That case is indistinguishable from an unread that's unknown to
       // the model, so we get coverage for that case too.
       test('remove flag: ${mentionFlag.name}', () {
-        final messages = [
+        final messages = <Message>[
           eg.streamMessage(flags: [mentionFlag]),
           eg.streamMessage(flags: [mentionFlag, MessageFlag.read]),
           eg.dmMessage(from: eg.otherUser, to: [eg.selfUser], flags: [mentionFlag]),
@@ -925,7 +925,7 @@ void main() {
       final message2 = eg.streamMessage(id: 2, flags: [MessageFlag.mentioned]);
       final message3 = eg.dmMessage(id: 3, from: eg.otherUser, to: [eg.selfUser], flags: []);
       final message4 = eg.dmMessage(id: 4, from: eg.otherUser, to: [eg.selfUser], flags: [MessageFlag.wildcardMentioned]);
-      final messages = [message1, message2, message3, message4];
+      final messages = <Message>[message1, message2, message3, message4];
 
       prepare();
       fillWithMessages([message1, message2, message3, message4]);
@@ -974,7 +974,7 @@ void main() {
         final message13 = eg.streamMessage(id: 13, stream: stream2, topic: 'b', flags: []);
         final message14 = eg.streamMessage(id: 14, stream: stream2, topic: 'b', flags: [MessageFlag.mentioned]);
 
-        final messages = [
+        final messages = <Message>[
           message1, message2, message3, message4, message5,
           message6, message7, message8, message9, message10,
           message11, message12, message13, message14,
@@ -1086,7 +1086,7 @@ void main() {
         final message13 = eg.streamMessage(id: 13, stream: stream2, topic: 'b', flags: [MessageFlag.read]);
         final message14 = eg.streamMessage(id: 14, stream: stream2, topic: 'b', flags: [MessageFlag.mentioned, MessageFlag.read]);
 
-        final messages = [
+        final messages = <Message>[
           message1, message2, message3, message4, message5,
           message6, message7, message8, message9, message10,
           message11, message12, message13, message14,

test/model/unreads_test.dart

@@ -538,7 +538,7 @@ void main() {
     final streamMessage = eg.streamMessage();
     final topicNarrow = TopicNarrow.ofMessage(streamMessage);
 
-    for (final (description, message, narrow) in [
+    for (final (description, message, narrow) in <(String, Message, SendableNarrow)>[
       ('typing in dm',    dmMessage,      dmNarrow),
       ('typing in topic', streamMessage,  topicNarrow),
     ]) {