159 lines
6.0 KiB
Markdown
159 lines
6.0 KiB
Markdown
# MSC2409: Proposal to send typing, presence and receipts to appservices
|
|
|
|
*Note: This proposal is a continuation of [MSC1888](https://github.com/matrix-org/matrix-doc/pull/1888)
|
|
and deprecates that one.*
|
|
|
|
The [appservice /transactions API](https://spec.matrix.org/v1.11/application-service-api/#put_matrixappv1transactionstxnid)
|
|
currently supports pushing PDU events (regular message and state events)
|
|
however it doesn't provision for EDU events (typing, presence and receipts). This means that bridges cannot
|
|
react to Matrix users who send any typing or presence information in a room the service is part of.
|
|
|
|
There is an interest amongst the community to have equal bridging on both sides of a bridge, so that
|
|
read receipts and typing notifications can be seen on the remote side. To that end, this proposal
|
|
specifies how these can be pushed to an appservice.
|
|
|
|
## Proposal
|
|
|
|
### Changes to the registration file
|
|
|
|
In order that appservices don't get flooded with EDUs, appservices have to opt-in to receive them by
|
|
setting `receive_ephemeral` to true. A registration file could look like following:
|
|
|
|
```yaml
|
|
id: "IRC Bridge"
|
|
url: "http://127.0.0.1:1234"
|
|
as_token: "30c05ae90a248a4188e620216fa72e349803310ec83e2a77b34fe90be6081f46"
|
|
hs_token: "312df522183efd404ec1cd22d2ffa4bbc76a8c1ccf541dd692eef281356bb74e"
|
|
sender_localpart: "_irc_bot"
|
|
# We want to receive EDUs
|
|
receive_ephemeral: true
|
|
namespaces:
|
|
users:
|
|
- exclusive: true
|
|
regex: "@_irc_bridge_.*"
|
|
aliases:
|
|
- exclusive: false
|
|
regex: "#_irc_bridge_.*"
|
|
rooms: []
|
|
```
|
|
|
|
For now, receiving EDUs is all-or-nothing. A future MSC may add more granular
|
|
filtering capabilities for appservices.
|
|
|
|
### Changes to the /transactions/ API
|
|
|
|
The `PUT /_matrix/app/v1/transactions/{txnId}` API currently supports sending PDUs
|
|
via the `events` array.
|
|
|
|
```json
|
|
{
|
|
"events": [
|
|
{
|
|
"content": {
|
|
"membership": "join",
|
|
"avatar_url": "mxc://domain.com/SEsfnsuifSDFSSEF#auto",
|
|
"displayname": "Alice Margatroid"
|
|
},
|
|
"type": "m.room.member",
|
|
"event_id": "$143273582443PhrSn:domain.com",
|
|
"room_id": "!jEsUZKDJdhlrceRyVU:domain.com",
|
|
"sender": "@example:domain.com",
|
|
"origin_server_ts": 1432735824653,
|
|
"unsigned": {
|
|
"age": 1234
|
|
},
|
|
"state_key": "@alice:domain.com"
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
This proposal would extend the `PUT /_matrix/app/v1/transactions/` endpoint to include a new key
|
|
`ephemeral` to behave similar to the various sections of the CS API `/sync` endpoint. The `ephemeral` key
|
|
MAY be omitted entirely if there are no ephemeral events to send.
|
|
|
|
```json
|
|
{
|
|
"ephemeral": [
|
|
{
|
|
"type": "m.typing",
|
|
"room_id": "!jEsUZKDJdhlrceRyVU:domain.com",
|
|
"content": {
|
|
"user_ids": [
|
|
"@alice:example.com"
|
|
]
|
|
}
|
|
},
|
|
{
|
|
"type": "m.receipt",
|
|
"room_id": "!jEsUZKDJdhlrceRyVU:domain.com",
|
|
"content": {
|
|
"$1435641916114394fHBLK:matrix.org": {
|
|
"m.read": {
|
|
"@rikj:jki.re": {
|
|
"ts": 1436451550453
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
],
|
|
"events": [
|
|
// ...
|
|
]
|
|
}
|
|
```
|
|
|
|
The reason for a new key rather than bundling the events into `events` is that
|
|
existing appservices may mistake them for PDUs and might behave erratically.
|
|
While `events` may now be a somewhat misleading name, this is an acceptable tradeoff.
|
|
|
|
The array is effectively a combination of the `presence` and `ephemeral` sections of the
|
|
client-server `/sync` API. User-defined ephemeral events don't exist yet, which means there are
|
|
only three event types that can currently occur:
|
|
[`m.presence`](https://spec.matrix.org/v1.11/client-server-api/#mpresence),
|
|
[`m.typing`](https://spec.matrix.org/v1.11/client-server-api/#mtyping),
|
|
and [`m.receipt`](https://spec.matrix.org/v1.11/client-server-api/#mreceipt).
|
|
|
|
This proposal does not cover any other types of events which are sent as EDUs in the federation API,
|
|
such as to-device events or other e2ee features. Those are left to a separate MSC.
|
|
|
|
EDUs are formatted the same way as they are in C-S sync, with the addition of the `room_id` field
|
|
for room-scoped EDUs (`m.typing` and `m.receipt`). `room_id` is not present in the C-S API because
|
|
sync nests EDUs inside a room object, but appservices get a flat list of events in all rooms.
|
|
|
|
### Expectations of when an EDU should be pushed to an appservice
|
|
|
|
It is not clear at face value what should be pushed to an appservice. Appservices claim
|
|
namespaces of users which registers "interest" in the rooms where those users reside, as
|
|
well as claiming namespaces of rooms for explicit interest. However, not all EDUs are
|
|
associated with a single room (presence, etc).
|
|
|
|
If the EDU is capable of being associated to a particular room (i.e. `m.typing` and `m.receipt`),
|
|
it should be sent to the appservice under the same rules as regular events (interest in the room
|
|
means sending it). For EDUs which are not associated with a particular room, the appservice
|
|
receives the EDU if it contextually *would* apply. For example, a presence update for a user an
|
|
appservice shares a room with (or is under the appservice's namespace) would be sent to the
|
|
appservice.
|
|
|
|
For `m.receipt`, private read receipts (`m.read.private`) should only be sent for users within the
|
|
appservice's namespaces. Normal read receipts and threaded read receipts are always sent.
|
|
|
|
## Potential issues
|
|
|
|
Determining which EDUs to transmit to the appservice could lead to quite some overhead on the
|
|
homeserver side. Additionally, more network traffic is produced, potentially straining the local
|
|
network and the appservice more. As such, appservices have to opt-in to receive EDUs.
|
|
|
|
## Security considerations
|
|
|
|
The homeserver needs to accurately determine which EDUs to send to the appservice, as to not leak
|
|
any unnecessary metadata about users. Particularly `m.presence` could be tricky, as no `room_id` is present in
|
|
that EDU.
|
|
|
|
## Unstable prefix
|
|
|
|
In the transaction body, instead of `ephemeral`, `de.sorunome.msc2409.ephemeral` is used.
|
|
|
|
In the registration file, instead of `receive_ephemeral`, `de.sorunome.msc2409.push_ephemeral` is used.
|