local echo (3/n): Pull out MessageBase

[PIG208]

Related:

• Work toward Simplified local echo, with retry #1441
• Prep for local echo (n/n): Support simplified version of local echo #1453

[gnprice]

I feel like the name "displayable message" doesn't really capture what this is about — in particular the term "displayable" doesn't much help in saying how this relates to the Message class.

A good name would be BaseMessage. Here's also some revised dartdoc:

Suggested change

	/// A common class for messages that can appear in a [MessageList].
	abstract class DisplayableMessage<T extends MessageDestination> {
	/// 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 BaseMessage<T extends MessageDestination> {

Since you have a whole series of commits that use this name, doing the rename in a manual way might be a pain. Here's a command to do it automatically and I think quite painlessly:

$ FILTER_BRANCH_SQUELCH_WARNING=1 git filter-branch \
    --tree-filter 'perl -i -0pe s/DisplayableMessage/MessageBase/g $(git ls-files lib test)' \
    @~4..
Rewrite 282632f9fbafacfc53fa3629be22733ccfe7a791 (1/4) (0 seconds passed, remaining 0 predicted)
Rewrite 1e324588d6bf5791a50e2cd65d4175f4a903e3b0 (2/4) (1 seconds passed, remaining 1 predicted)
Rewrite 9b9265bfd4292728dfdabdea5756b8f1c3b4fd58 (2/4) (1 seconds passed, remaining 1 predicted)
Rewrite be02a05bdff9b4bc1f02a50ed2e4513efb92f305 (2/4) (1 seconds passed, remaining 1 predicted)

Ref 'refs/heads/main' was rewritten

Definitely use git diff --stat -p @{1} and git range-diff origin @{1} @ to review the results.

The reason for that environment variable at the start of the command is that git filter-branch is deprecated these days. When I tried the command without it, I got:

WARNING: git-filter-branch has a glut of gotchas generating mangled history
	 rewrites.  Hit Ctrl-C before proceeding to abort, then use an
	 alternative filtering tool such as 'git filter-repo'
	 (https://github.com/newren/git-filter-repo/) instead.  See the
	 filter-branch manual page for more details; to squelch this warning,
	 set FILTER_BRANCH_SQUELCH_WARNING=1.

The warning is accurate. But this rewrite is simple enough that I don't think any gotchas apply; and it's small enough you can review the results to confirm that. Given that that's the case, and that I already know how to use git filter-branch, I went with just squelching the warning.

If we needed to do something more complex, I would invest the time to do it with the newer out-of-tree tool git filter-repo. (And if it were a big job, I'd also be sure to ask Anders if he had any other recommendations.)

[gnprice]

Or perhaps better: MessageBase. This type alone isn't yet even a message; it's just the base for a message.

[PIG208]

Yeah. Thanks for the script! I guess one other thing filter-branch is capable of is rewriting the commit messages, but that's as fine to do manually.

One other thing I'm thinking of renaming is destination. The Zulip API uses to for send-message, Because this adds a level of nesting, perhaps shortening it to two letters will be more readable? So it might be used like message.to.streamId, message.to.userIds or final destination = message.to. But we don't seem to do that in general when naming things.

[gnprice]

Seeing this change and many of the other instances of this change, it makes me nervous that we now have something that's vague about exactly which user IDs are included and we're expecting it to match up with something that's specifically all the recipient IDs.

As a comment on DmNarrow says, Zulip has many ways of representing a DM conversation. In particular the Zulip server API has at least four different conventions for whether the self-user is included in the list. (Always; never; only for self-1:1; only for self-1:1 and groups.) This was a recurring source of bugs and confusion in zulip-mobile, until I invested substantial effort in cleaning it up with the abstractions found now in src/utils/recipient.js. That's the reason that DmMessage and DmNarrow have the very explicitly-named allRecipientIds, as well as DmNarrow.otherRecipientIds for when that's desired.

So I'd like to find a solution that preserves that explicitness about the semantics of each list of users.

I think the key here is that MessageDestination isn't quite the right class to be using for this purpose. Its doc says:

/// Which conversation to send a message to, in [sendMessage].
///
/// This is either a [StreamDestination] or a [DmDestination].
sealed class MessageDestination {

Similarly the two subclasses say things like:

/// A DM conversation, for specifying to [sendMessage].
///
/// The server accepts a list of Zulip API emails as an alternative to
/// a list of user IDs, but this binding currently doesn't.
class DmDestination extends MessageDestination {

So they're specifically about [sendMessage] — their job is to describe a parameter in a request to that endpoint. The information one says in [sendMessage] about where a message should go naturally has a lot in common with the information the server says in a [getMessages] or [getEvents] response about where a message did go… but it's also natural that it's not exactly the same information.

Let's therefore make a separate handful of small classes that are specifically for the information that belongs on [Message]. I think we can use the nice short/general name Recipient for this (and then StreamRecipient and DmRecipient).

Then the fields on StreamMessage and DmMessage can move verbatim onto the Recipient subclasses. And maybe leave behind getters on the message subclasses, which just proxy through to there, for convenience / to reduce how much code needs to churn.

[gnprice]

(I guess there's already a DmRecipient. It can get renamed first to something more specific, like DmDisplayRecipient. It's already quite local in how it's used.)

[PIG208]

I suppose that we don't want to move displayRecipient to DmRecipient (after renaming the original class to DmDisplayRecipient), right?

It shouldn't be necessary for sendMessage to construct a DmDisplayRecipient when it only has convenient access to a DmDestination and that other fields on DmDisplayRecipient are mostly unused.

I think this means that DmMessage.recipient should remain as a getter, much like how DmMessage.destination is in the current revision, but returns a DmRecipient computed from DmMessage.allRecipientIds.

[gnprice]

Hmm good question.

It looks like in main we never actually consult DmMessage.displayRecipient, except in its own test and in the allRecipientIds getter. So in any case we shouldn't let it get in the way of a structure we otherwise like — we can always just remove it instead, and deserialize straight to the list of IDs.

One way the further detail could in principle be useful is in DmRecipientHeader, if a user is unknown in the store, we could fall back to their name from the DmDisplayRecipient instead of to "(unknown user)". But we don't do that now, and it seems pretty marginal in value. So if the continued existence of DmDisplayRecipient feels like it's getting in the way, let's just rip it out, and we can decide how to add it back if we do ever implement that fallback functionality.