Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Remove reply fallbacks #1994

Merged
merged 7 commits into from
Nov 29, 2024
Merged

Remove reply fallbacks #1994

Show file tree
Hide file tree
Changes from 3 commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
12f1ede
Remove reply fallbacks
zecakeh Nov 14, 2024
edcba83
Add changelog
zecakeh Nov 14, 2024
a98ec33
Remove rich reply fallback from threads
zecakeh Nov 14, 2024
829867f
Add sentence about stripping tag
zecakeh Nov 14, 2024
50c6ff7
Apply suggested changes to event_replacements
zecakeh Nov 28, 2024
9fa9d56
Add suggested changes to instant_messaging
zecakeh Nov 28, 2024
75b9164
Apply suggested changes to rich_replies
zecakeh Nov 28, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions changelogs/client_server/newsfragments/1994.feature
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
Remove reply fallbacks, as per [MSC2781](https://github.com/matrix-org/matrix-spec-proposals/issues/2781).
zecakeh marked this conversation as resolved.
Show resolved Hide resolved
46 changes: 6 additions & 40 deletions content/client-server-api/modules/event_replacements.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -362,43 +362,9 @@ property under `m.new_content`.

#### Edits of replies

Some particular constraints apply to events which replace a
[reply](#rich-replies). In particular:

* In contrast to the original reply, there should be no `m.in_reply_to`
property in the the `m.relates_to` object, since it would be redundant (see
[Applying `m.new_content`](#applying-mnew_content) above, which notes that
the original event's `m.relates_to` is preserved), as well as being contrary
to the spirit of the event relationships mechanism which expects only one
"parent" per event.
richvdh marked this conversation as resolved.
Show resolved Hide resolved

* `m.new_content` should **not** contain any [reply
fallback](#fallbacks-for-rich-replies),
since it is assumed that any client which can handle edits can also display
replies natively. However, the `content` of the replacement event should provide
fallback content for clients which support neither rich replies nor edits.

An example of an edit to a reply is as follows:
richvdh marked this conversation as resolved.
Show resolved Hide resolved

```json
{
"type": "m.room.message",
// irrelevant fields not shown
"content": {
"body": "> <@alice:example.org> question\n\n* reply",
"msgtype": "m.text",
"format": "org.matrix.custom.html",
"formatted_body": "<mx-reply><blockquote><a href=\"https://matrix.to/#/!somewhere:example.org/$event:example.org\">In reply to</a> <a href=\"https://matrix.to/#/@alice:example.org\">@alice:example.org</a><br />question</blockquote></mx-reply>* reply",
"m.new_content": {
"body": "reply",
"msgtype": "m.text",
"format": "org.matrix.custom.html",
"formatted_body": "reply"
},
"m.relates_to": {
"rel_type": "m.replace",
"event_id": "$original_reply_event"
}
}
}
```
{{% boxes/note %}}
{{% changed-in v="1.13" %}}
In previous versions of the specification, events which replace a [reply](#rich-replies)
could include a fallback in the `content`. They are now treated as any other
relation.
richvdh marked this conversation as resolved.
Show resolved Hide resolved
{{% /boxes/note %}}
13 changes: 5 additions & 8 deletions content/client-server-api/modules/instant_messaging.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -98,14 +98,11 @@ having appropriate closing tags, appropriate attributes (considering the
custom ones defined in this specification), and generally valid
structure.

A special tag, `mx-reply`, may appear on rich replies (described below)
and should be allowed if, and only if, the tag appears as the very first
tag in the `formatted_body`. The tag cannot be nested and cannot be
located after another tag in the tree. Because the tag contains HTML, an
`mx-reply` is expected to have a partner closing tag and should be
treated similar to a `div`. Clients that support rich replies will end
up stripping the tag and its contents and therefore may wish to exclude
the tag entirely.
{{% boxes/note %}}
{{% changed-in v="1.13" %}}
In previous versions of the specification, [rich replies](#rich-replies) could
use a special tag, `mx-reply`, this is no longer the case.
clokep marked this conversation as resolved.
Show resolved Hide resolved
{{% /boxes/note %}}

{{% boxes/note %}}
A future iteration of the specification will support more powerful and
Expand Down
151 changes: 17 additions & 134 deletions content/client-server-api/modules/rich_replies.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,7 @@
### Rich replies

{{% changed-in v="1.3" %}}
{{% changed-in v="1.13" %}}
richvdh marked this conversation as resolved.
Show resolved Hide resolved

Rich replies are a
special kind of [relationship](#forming-relationships-between-events) which
Expand All @@ -18,9 +19,22 @@ Additionally, a rich reply can reference any other event type as of v1.3.
Previously, a rich reply could only reference another `m.room.message` event.
{{% /boxes/note %}}

When possible, events SHOULD include a [fallback representation](#fallbacks-for-rich-replies)
to allow clients which do not render rich replies to still see something which
appears to be a quoted reply.
{{% boxes/note %}}
{{% changed-in v="1.13" %}}
In previous versions of the specification, rich replies could include a fallback
format in the `body` and `formatted_body` for clients that do not support rich
richvdh marked this conversation as resolved.
Show resolved Hide resolved
replies, this is no longer the case. Clients might still want to remove this
richvdh marked this conversation as resolved.
Show resolved Hide resolved
fallback before rendering the event.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think they must remove it, no?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

There is not must in the MSC. There is:

Clients […] should consider treating <mx-reply> parts as they treat other invalid html tags.

And

[…] clients may need to strip out such fallbacks.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

My understanding is that it should not be mandatory as it will allow clients to drop any special code regarding this feature when it is not sent anymore in new messages. It will only appear in historical events but it could be considered acceptable to display the fallback in that case.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fallbacks are still being sent by current clients, so receiving clients will have to remove the fallback for a while yet.

I think SHOULD captures the intent here.


To strip the fallback on the `body`, the client should iterate over each
line of the string, removing any lines that start with the fallback
prefix ("&gt; ", including the space, without quotes) and stopping when
a line is encountered without the prefix. This prefix is known as the
"fallback prefix sequence".
richvdh marked this conversation as resolved.
Show resolved Hide resolved

To strip the fallback on the `formatted_body`, the client should remove
the entirety of the `mx-reply` tag.
richvdh marked this conversation as resolved.
Show resolved Hide resolved
{{% /boxes/note %}}

Though rich replies form a relationship to another event, they do not
use `rel_type` to create this relationship. Instead, a subkey named `m.in_reply_to`
Expand Down Expand Up @@ -48,137 +62,6 @@ An example reply would be:
Note that the `event_id` of the `m.in_reply_to` object has the same requirements
as if it were to be under `m.relates_to` directly instead.

#### Fallbacks for rich replies

Some clients may not have support for rich replies and therefore need a
fallback to use instead. Clients that do not support rich replies should
render the event as if rich replies were not special.

Clients that do support rich replies SHOULD provide the fallback format on
replies, and MUST strip the fallback before rendering the reply. The
specific fallback text is different for each `msgtype`, however the
general format for the `body` is:

```text
> <@alice:example.org> This is the first line of the original body
> This is the second line

This is where the reply goes
```

The `formatted_body`, if present and using an associated `format` of
`org.matrix.custom.html`, should use the following template:

```html
<mx-reply>
<blockquote>
<a href="https://matrix.to/#/!somewhere:example.org/$event:example.org">In reply to</a>
<a href="https://matrix.to/#/@alice:example.org">@alice:example.org</a>
<br />
<!-- This is where the related event's HTML would be. -->
</blockquote>
</mx-reply>
This is where the reply goes.
```

If the related event does not have a `formatted_body`, the event's
`body` should be considered after encoding any HTML special characters.
Note that the `href` in both of the anchors use a [matrix.to
URI](/appendices#matrixto-navigation).

##### Stripping the fallback

Clients which support rich replies MUST strip the fallback from the
event before rendering the event. This is because the text provided in
the fallback cannot be trusted to be an accurate representation of the
event. After removing the fallback, clients are recommended to represent
the event referenced by `m.in_reply_to` similar to the fallback's
representation, although clients do have creative freedom for their user
interface. Clients should prefer the `formatted_body` over the `body`,
just like with other `m.room.message` events.

To strip the fallback on the `body`, the client should iterate over each
line of the string, removing any lines that start with the fallback
prefix ("&gt; ", including the space, without quotes) and stopping when
a line is encountered without the prefix. This prefix is known as the
"fallback prefix sequence".

To strip the fallback on the `formatted_body`, the client should remove
the entirety of the `mx-reply` tag.

##### Fallback for `m.text`, `m.notice`, and unrecognised message types

Using the prefix sequence, the first line of the related event's `body`
should be prefixed with the user's ID, followed by each line being
prefixed with the fallback prefix sequence. For example:

```text
> <@alice:example.org> This is the first line
> This is the second line

This is the reply
```

The `formatted_body` uses the template defined earlier in this section.

##### Fallback for `m.emote`

Similar to the fallback for `m.text`, each line gets prefixed with the
fallback prefix sequence. However an asterisk should be inserted before
the user's ID, like so:

```text
> * <@alice:example.org> feels like today is going to be a great day

This is the reply
```

The `formatted_body` has a subtle difference for the template where the
asterisk is also inserted ahead of the user's ID:

```html
<mx-reply>
<blockquote>
<a href="https://matrix.to/#/!somewhere:example.org/$event:example.org">In reply to</a>
* <a href="https://matrix.to/#/@alice:example.org">@alice:example.org</a>
<br />
<!-- This is where the related event's HTML would be. -->
</blockquote>
</mx-reply>
This is where the reply goes.
```

##### Fallback for `m.image`, `m.video`, `m.audio`, and `m.file`

The related event's `body` would be a file name, which may not be very
descriptive. The related event should additionally not have a `format`
or `formatted_body` in the `content` - if the event does have a `format`
and/or `formatted_body`, those fields should be ignored. Because the
filename alone may not be descriptive, the related event's `body` should
be considered to be `"sent a file."` such that the output looks similar
to the following:

```text
> <@alice:example.org> sent a file.

This is the reply
```
```html
<mx-reply>
<blockquote>
<a href="https://matrix.to/#/!somewhere:example.org/$event:example.org">In reply to</a>
<a href="https://matrix.to/#/@alice:example.org">@alice:example.org</a>
<br />
sent a file.
</blockquote>
</mx-reply>
This is where the reply goes.
```

For `m.image`, the text should be `"sent an image."`. For `m.video`, the
text should be `"sent a video."`. For `m.audio`, the text should be
`"sent an audio file"`.

#### Mentioning the replied to user

In order to notify users of the reply, it may be desirable to include the `sender`
Expand Down
4 changes: 0 additions & 4 deletions content/client-server-api/modules/threading.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -106,10 +106,6 @@ flag to `true`.
}
```

For `m.room.message` events represented this way, no [reply fallback](#fallbacks-for-rich-replies)
is specified. This allows thread-aware clients to discard the `m.in_reply_to` object entirely
when `is_falling_back` is `true`.

{{% boxes/note %}}
Clients which are acutely aware of threads (they do not render threads, but are otherwise
aware of the feature existing in the spec) can treat rich replies to an event with a `rel_type`
Expand Down