Filip/matrix-spec
1
0
Fork 0
mirror of https://github.com/matrix-org/matrix-spec synced 2025-12-20 16:38:37 +01:00
Code Issues Actions 3 Packages Projects Releases Wiki Activity
matrix-spec/specification/modules/instant_messaging.rst

90 lines
2.8 KiB
ReStructuredText
Raw Normal View History

Add instant_messaging module; modify batesian section rules Previously, all `m.room.*` events were wodged into `{{room_events}}` which isn't great when you want to pull specific ones out. Batesian had a 1:1 mapping of `render_foo()` to a section `{{foo}}`, and having to constantly add functions for new types is a PITA. Batesian now supports returning a `dict` instead of a section `string` where the keys are the `{{foo}}` and the value is what will be inserted. Also add conflicting section key checks to avoid multiple definitions of the same `{{foo}}`. Define dicts for event schemata and swagger HTTP APIs. Using this new feature, split out the instant messaging stuff from the events section, and replace `{{room_events}}` with a list of specific events e.g. `{{m_room_member_event}}`.
2015-09-23 11:48:49 +02:00
Instant Messaging
=================
Flesh out feature profiles section Add table detailing the profiles. Add anchors to link through to each module following a well-defined format (rather than the name of the module section). Allow UTF-8 in the spec.
2015-09-25 16:09:15 +02:00
.. _module:im:
Stub sections
2015-10-02 16:03:55 +02:00
This module adds support for sending human-readable messages to a room. It also
Flesh out more of the IM module
2015-10-05 14:45:23 +02:00
adds support for associating human-readable information with the room itself
such as a room name and topic.
Stub sections
2015-10-02 16:03:55 +02:00
Add instant_messaging module; modify batesian section rules Previously, all `m.room.*` events were wodged into `{{room_events}}` which isn't great when you want to pull specific ones out. Batesian had a 1:1 mapping of `render_foo()` to a section `{{foo}}`, and having to constantly add functions for new types is a PITA. Batesian now supports returning a `dict` instead of a section `string` where the keys are the `{{foo}}` and the value is what will be inserted. Also add conflicting section key checks to avoid multiple definitions of the same `{{foo}}`. Define dicts for event schemata and swagger HTTP APIs. Using this new feature, split out the instant messaging stuff from the events section, and replace `{{room_events}}` with a list of specific events e.g. `{{m_room_member_event}}`.
2015-09-23 11:48:49 +02:00
Events
------
{{m_room_message_event}}
Flesh out more of the IM module
2015-10-05 14:45:23 +02:00
.. admonition:: Rationale
Not all clients can display all message types. The most commonly supported
message type is raw text. As a result, we chose to have a textual fallback
display method represented by the ``body`` key. This means that even if the
client cannot display a particular ``msgtype``, they can still display
*something*, even if it is just plain text.
Add instant_messaging module; modify batesian section rules Previously, all `m.room.*` events were wodged into `{{room_events}}` which isn't great when you want to pull specific ones out. Batesian had a 1:1 mapping of `render_foo()` to a section `{{foo}}`, and having to constantly add functions for new types is a PITA. Batesian now supports returning a `dict` instead of a section `string` where the keys are the `{{foo}}` and the value is what will be inserted. Also add conflicting section key checks to avoid multiple definitions of the same `{{foo}}`. Define dicts for event schemata and swagger HTTP APIs. Using this new feature, split out the instant messaging stuff from the events section, and replace `{{room_events}}` with a list of specific events e.g. `{{m_room_member_event}}`.
2015-09-23 11:48:49 +02:00
{{m_room_message_feedback_event}}
Flesh out more of the IM module
2015-10-05 14:45:23 +02:00
Usage of this event is discouraged for several reasons:
- The number of feedback events will grow very quickly with the number of users
in the room. This event provides no way to "batch" feedback, unlike the
`receipts module`_.
- Pairing feedback to messages gets complicated when paginating as feedback
arrives before the message it is acknowledging.
- There are no guarantees that the client has seen the event ID being
acknowledged.
.. _`receipts module`: `module:receipts`_
Add instant_messaging module; modify batesian section rules Previously, all `m.room.*` events were wodged into `{{room_events}}` which isn't great when you want to pull specific ones out. Batesian had a 1:1 mapping of `render_foo()` to a section `{{foo}}`, and having to constantly add functions for new types is a PITA. Batesian now supports returning a `dict` instead of a section `string` where the keys are the `{{foo}}` and the value is what will be inserted. Also add conflicting section key checks to avoid multiple definitions of the same `{{foo}}`. Define dicts for event schemata and swagger HTTP APIs. Using this new feature, split out the instant messaging stuff from the events section, and replace `{{room_events}}` with a list of specific events e.g. `{{m_room_member_event}}`.
2015-09-23 11:48:49 +02:00
{{m_room_name_event}}
{{m_room_topic_event}}
m.room.message msgtypes
Stub sections
2015-10-02 16:03:55 +02:00
~~~~~~~~~~~~~~~~~~~~~~~
Add instant_messaging module; modify batesian section rules Previously, all `m.room.*` events were wodged into `{{room_events}}` which isn't great when you want to pull specific ones out. Batesian had a 1:1 mapping of `render_foo()` to a section `{{foo}}`, and having to constantly add functions for new types is a PITA. Batesian now supports returning a `dict` instead of a section `string` where the keys are the `{{foo}}` and the value is what will be inserted. Also add conflicting section key checks to avoid multiple definitions of the same `{{foo}}`. Define dicts for event schemata and swagger HTTP APIs. Using this new feature, split out the instant messaging stuff from the events section, and replace `{{room_events}}` with a list of specific events e.g. `{{m_room_member_event}}`.
2015-09-23 11:48:49 +02:00
Each `m.room.message`_ MUST have a ``msgtype`` key which identifies the type
of message being sent. Each type has their own required and optional keys, as
Flesh out more of the IM module
2015-10-05 14:45:23 +02:00
outlined below. If a client cannot display the given ``msgtype`` then it MUST
display the fallback plain text ``body`` key instead.
Add instant_messaging module; modify batesian section rules Previously, all `m.room.*` events were wodged into `{{room_events}}` which isn't great when you want to pull specific ones out. Batesian had a 1:1 mapping of `render_foo()` to a section `{{foo}}`, and having to constantly add functions for new types is a PITA. Batesian now supports returning a `dict` instead of a section `string` where the keys are the `{{foo}}` and the value is what will be inserted. Also add conflicting section key checks to avoid multiple definitions of the same `{{foo}}`. Define dicts for event schemata and swagger HTTP APIs. Using this new feature, split out the instant messaging stuff from the events section, and replace `{{room_events}}` with a list of specific events e.g. `{{m_room_member_event}}`.
2015-09-23 11:48:49 +02:00
{{msgtype_events}}
Stub sections
2015-10-02 16:03:55 +02:00
Client behaviour
----------------
Flesh out more of the IM module
2015-10-05 14:45:23 +02:00
Events which have attachments (e.g. ``m.image``, ``m.file``) are advised to be
uploaded using the `content repository module`_ where available. The
resulting ``mxc://`` URI can then be used in the ``url`` key. The
attachment SHOULD be uploaded *prior* to sending the event in order to stop a
race condition where the recipient receives a link to a non-existent attachment.
.. _`content repository module`: `module:content`_
Recommendations when sending messages
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- Advise using idempotent PUTs to send messages (and why)
- Retries (exp backoff, giveup eventually allowing manual retry)
- Queueing (bucket per room)
Implementing local echo
~~~~~~~~~~~~~~~~~~~~~~~
- Local echo (document bug with races) - sending state. Pairing returned event ID.
Displaying membership information with messages
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- Member name linking (incl. pagination aka historical display names)
Stub sections
2015-10-02 16:03:55 +02:00
Server behaviour
----------------
Flesh out more of the IM module
2015-10-05 14:45:23 +02:00
- SHOULD enforce the body/msgtype keys are present (can 400 them)
Stub sections
2015-10-02 16:03:55 +02:00
Security considerations
-----------------------
Flesh out more of the IM module
2015-10-05 14:45:23 +02:00
- Not encrypted, link to E2E module.
- XSS: Should sanitise ALL KEYS before injecting as unsafe HTML (name/topic/body/etc)
Reference in a new issue Copy permalink