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

Jump to bottom

Remove reply fallbacks #1994

Open
wants to merge 4 commits into
base: main
Choose a base branch
from
+30 −186
Open

Remove reply fallbacks #1994

Show file tree
Hide file tree
Changes from 2 commits
Commits
Show all changes
4 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
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).
Copy link
Contributor Author

Choose a reason for hiding this comment

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

It should probably be a *.removal changelog, but given that the generated heading says "Endpoints Removed", it is not quite right.

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.

* `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:

```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.
{{% /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.
Copy link
Member

Choose a reason for hiding this comment

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

Doesn't this need to mention that it should always be stripped still?

Copy link
Contributor Author

Choose a reason for hiding this comment

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

Yes, I added a sentence here.

{{% /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" %}}

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
replies, this is no longer the case. Clients might still want to remove this
fallback before rendering the event.
Comment on lines +26 to +27
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.


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.
{{% /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