api: Construct polls data store from submessages.

For now, we only consider the case when the submessages describe a
poll, and disgard them otherwise. It will be a simple refactor later to
support other Zulip widgets like todo lists, by extracting a common
ancestors for such widget data structures.

The `Poll` data structure will become useful when we support submessage
events, where updates to a poll can happen.

Some more comments are added here instead of earlier because of their
references to `SubmessageData`.

Signed-off-by: Zixuan James Li <[email protected]>

Author: PIG208

lib/api/model/model.dart

@@ -1,8 +1,12 @@
+import 'dart:convert';
+
 import 'package:json_annotation/json_annotation.dart';
 
+import '../../log.dart';
 import 'events.dart';
 import 'initial_snapshot.dart';
 import 'reaction.dart';
+import 'submessage.dart';
 
 export 'json.dart' show JsonNullable;
 export 'reaction.dart';
@@ -481,6 +485,9 @@ sealed class Message {
   final String senderRealmStr;
   @JsonKey(name: 'subject')
   String topic;
+  /// Poll data if "submessages" describe a poll, `null` otherwise.
+  @JsonKey(name: 'submessages', readValue: _readPoll, fromJson: _pollFromJson, toJson: _pollToJson)
+  Poll? poll;
   final int timestamp;
   String get type;
 
@@ -512,6 +519,45 @@ sealed class Message {
     return list.map((raw) => MessageFlag.fromRawString(raw as String)).toList();
   }
 
+  static List<Submessage>? _submessagesFromJson(Object? json) {
+    final list = json as List<Object?>;
+    return list.isNotEmpty
+      ? list.map((e) => Submessage.fromJson(e as Map<String, Object?>)).toList()
+      : null;
+  }
+
+  static Poll? _readPoll(Map<Object?, Object?> json, String key) {
+    final submessages = _submessagesFromJson(json[key]);
+    // If empty, [submessages] is converted to null.
+    assert(submessages == null || submessages.isNotEmpty);
+    if (submessages == null) return null;
+
+    final senderId = (json['sender_id'] as num).toInt();
+    assert(submessages.first.senderId == senderId);
+
+    final widgetData = WidgetData.fromJson(jsonDecode(submessages.first.content));
+    switch (widgetData) {
+      case PollWidgetData():
+        return Poll.fromSubmessages(
+          submessages,
+          senderId: senderId,
+          widgetData: widgetData
+        );
+      case UnsupportedWidgetData():
+        assert(debugLog('Unsupported widgetData: ${widgetData.json}'));
+        return null;
+    }
+  }
+
+  static Poll? _pollFromJson(Object? json) {
+    // Simple type cast since [_readPoll] does the heavy-lifting.
+    return json as Poll?;
+  }
+
+  static List<Submessage> _pollToJson(Poll? poll) {
+    return [];
+  }
+
   Message({
     required this.client,
     required this.content,

lib/api/model/model.g.dart

@@ -1,5 +1,9 @@
+import 'dart:convert';
+
 import 'package:json_annotation/json_annotation.dart';
 
+import '../../log.dart';
+
 part 'submessage.g.dart';
 
 /// Data used for certain experimental Zulip widgets including polls and todo
@@ -22,7 +26,7 @@ class Submessage {
   // We cannot parse the String into one of the [SubmessageData] classes because
   // information from other submessages are required. Specifically, we need:
   //   * the index of this submessage in [Message.submessages];
-  //   * the [WidgetType] of the first [Message.submessages].
+  //   * the parsed [WidgetData] from the first [Message.submessages].
   final String content;
   // final int messageId;  // ignored; redundant with [Message.id]
   final int senderId;
@@ -265,3 +269,125 @@ enum PollEventSubmessageType {
   static final _byRawString = _$PollEventSubmessageTypeEnumMap
     .map((key, value) => MapEntry(value, key));
 }
+
+/// States of a poll Zulip widget.
+///
+/// See also:
+/// - https://zulip.com/help/create-a-poll
+/// - https://github.com/zulip/zulip/blob/304d948416465c1a085122af5d752f03d6797003/web/shared/src/poll_data.ts
+class Poll {
+  Poll({
+    required this.pollSenderId,
+    required this.question,
+    required final List<String> options,
+  }) {
+    for (int index = 0; index < options.length; index += 1) {
+      // Initial poll options use a placeholder senderId.
+      // See [PollEventSubmessage.optionKey] for details.
+      _addOption(null, options[index], optionIndex: index);
+    }
+  }
+
+  factory Poll.fromSubmessages(
+    List<Submessage> submessages,
+    {required int senderId, required PollWidgetData widgetData}
+  ) {
+    assert(submessages.isNotEmpty);
+    final widgetEventSubmessages = submessages.skip(1);
+
+    final poll = Poll(
+      pollSenderId: senderId,
+      question: widgetData.extraData.question,
+      options: widgetData.extraData.options,
+    );
+
+    for (final submessage in widgetEventSubmessages) {
+      final event = PollEventSubmessage.fromJson(jsonDecode(submessage.content) as Map<String, Object?>);
+      poll.applyEvent(submessage.senderId, event);
+    }
+    return poll;
+  }
+
+  final int pollSenderId;
+  String question;
+
+  /// The limit of options any single user can add to a poll.
+  ///
+  /// See https://github.com/zulip/zulip/blob/304d948416465c1a085122af5d752f03d6797003/web/shared/src/poll_data.ts#L69-L71
+  static const maxOptionIndex = 1000; // TODO validate
+
+  Iterable<PollOption> get options => _options.values;
+  final Set<String> _optionNames = {};
+  final Map<String, PollOption> _options = {};
+
+  void applyEvent(int senderId, PollEventSubmessage event) {
+    switch (event) {
+      case PollNewOptionEventSubmessage():
+        _addOption(
+          senderId,
+          event.option,
+          optionIndex: event.latestOptionIndex,
+        );
+
+      case PollQuestionEventSubmessage():
+        if (senderId != pollSenderId) {
+          // Only the message owner can edit the question.
+          assert(debugLog('unexpected poll data: user $senderId is not allowed to edit the question')); // TODO(log)
+          return;
+        }
+
+        question = event.question;
+
+      case PollVoteEventSubmessage():
+        final option = _options[event.key];
+        if (option == null) {
+          assert(debugLog('vote for unknown key ${event.key}')); // TODO(log)
+          return;
+        }
+
+        switch (event.op) {
+          case PollVoteOp.add:
+            option.voters.add(senderId);
+          case PollVoteOp.remove:
+            option.voters.remove(senderId);
+          case PollVoteOp.unknown:
+        }
+
+      case UnknownPollEventSubmessage():
+    }
+  }
+
+  void _addOption(int? senderId, String option, {required int optionIndex}) {
+    if (optionIndex > maxOptionIndex) return;
+    final key = PollEventSubmessage.optionKey(senderId: senderId, optionIndex: optionIndex);
+    // The web client suppresses duplicate options, which can be created through
+    // the /poll command as there is no server-side validation.
+    if (_optionNames.contains(option)) return;
+    assert(!_options.containsKey(key));
+    _options[key] = PollOption(text: option);
+    _optionNames.add(option);
+  }
+}
+
+class PollOption {
+  PollOption({required this.text});
+
+  factory PollOption.withVoters(String text, Iterable<int> voters) =>
+    PollOption(text: text)..voters.addAll(voters);
+
+  final String text;
+  final Set<int> voters = {};
+
+  @override
+  bool operator ==(Object other) {
+    if (other is! PollOption) return false;
+
+    return other.hashCode == hashCode;
+  }
+
+  @override
+  int get hashCode => Object.hash('Option', text, voters.join(','));
+
+  @override
+  String toString() => 'Option(option: $text, voters: {${voters.join(', ')}})';
+}

lib/api/model/submessage.dart

@@ -1,5 +1,6 @@
 import 'package:checks/checks.dart';
 import 'package:zulip/api/model/model.dart';
+import 'package:zulip/api/model/submessage.dart';
 
 extension UserChecks on Subject<User> {
   Subject<int> get userId => has((x) => x.userId, 'userId');
@@ -42,6 +43,7 @@ extension MessageChecks on Subject<Message> {
   Subject<int> get senderId => has((e) => e.senderId, 'senderId');
   Subject<String> get senderRealmStr => has((e) => e.senderRealmStr, 'senderRealmStr');
   Subject<String> get topic => has((e) => e.topic, 'topic');
+  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');

test/api/model/model_checks.dart

@@ -37,3 +37,8 @@ extension PollVoteEventChecks on Subject<PollVoteEventSubmessage> {
   Subject<String> get key => has((e) => e.key, 'key');
   Subject<PollVoteOp> get op => has((e) => e.op, 'op');
 }
+
+extension PollChecks on Subject<Poll> {
+  Subject<String> get question => has((e) => e.question, 'question');
+  Subject<Iterable<PollOption>> get options => has((e) => e.options, 'options');
+}