forked from MirrorHub/synapse
spec: Added internal links to different sections. Added NOTE and WARNING admonitions and hide away loooong TODO lists behind comments. Smaller ones remain.
This commit is contained in:
Kegan Dougal
parent
044daf4fe2
commit
9613d65756
1 changed files with 122 additions and 63 deletions
|
|
@ -278,7 +278,7 @@ which can be set when creating a room:
|
||||||
The ``name`` value for the ``m.room.name`` state event.
|
The ``name`` value for the ``m.room.name`` state event.
|
||||||
Description:
|
Description:
|
||||||
If this is included, an ``m.room.name`` event will be sent into the room to indicate the
|
If this is included, an ``m.room.name`` event will be sent into the room to indicate the
|
||||||
name of the room. See "Room Events" for more information on ``m.room.name``.
|
name of the room. See `Room Events`_ for more information on ``m.room.name``.
|
||||||
|
|
||||||
``topic``
|
``topic``
|
||||||
Type:
|
Type:
|
||||||
|
|
@ -289,7 +289,7 @@ which can be set when creating a room:
|
||||||
The ``topic`` value for the ``m.room.topic`` state event.
|
The ``topic`` value for the ``m.room.topic`` state event.
|
||||||
Description:
|
Description:
|
||||||
If this is included, an ``m.room.topic`` event will be sent into the room to indicate the
|
If this is included, an ``m.room.topic`` event will be sent into the room to indicate the
|
||||||
topic for the room. See "Room Events" for more information on ``m.room.topic``.
|
topic for the room. See `Room Events`_ for more information on ``m.room.topic``.
|
||||||
|
|
||||||
Example::
|
Example::
|
||||||
|
|
||||||
|
|
@ -301,22 +301,30 @@ Example::
|
||||||
}
|
}
|
||||||
|
|
||||||
- TODO: This creates a room creation event which serves as the root of the PDU graph for this room.
|
- TODO: This creates a room creation event which serves as the root of the PDU graph for this room.
|
||||||
- TODO: Keys for speccing a room name / room topic / invite these users?
|
- TODO: Key for invite these users?
|
||||||
|
|
||||||
Modifying aliases
|
Modifying aliases
|
||||||
-----------------
|
-----------------
|
||||||
- path to edit aliases
|
.. NOTE::
|
||||||
- format when retrieving list of aliases. NOT complete list.
|
This section is a work in progress.
|
||||||
- format for adding aliases.
|
|
||||||
|
.. TODO kegan
|
||||||
|
- path to edit aliases
|
||||||
|
- format when retrieving list of aliases. NOT complete list.
|
||||||
|
- format for adding aliases.
|
||||||
|
|
||||||
Permissions
|
Permissions
|
||||||
-----------
|
-----------
|
||||||
- TODO: What is a power level? How do they work? Defaults / required levels for X. How do they change
|
.. NOTE::
|
||||||
as people join and leave rooms? What do you do if you get a clash? Examples.
|
This section is a work in progress.
|
||||||
- TODO: List all actions which use power levels (sending msgs, inviting users, banning people, etc...)
|
|
||||||
- TODO: Room config - what is the event and what are the keys/values and explanations for them.
|
.. TODO kegan
|
||||||
Link through to respective sections where necessary. How does this tie in with permissions, e.g.
|
- TODO: What is a power level? How do they work? Defaults / required levels for X. How do they change
|
||||||
give example of creating a read-only room.
|
as people join and leave rooms? What do you do if you get a clash? Examples.
|
||||||
|
- TODO: List all actions which use power levels (sending msgs, inviting users, banning people, etc...)
|
||||||
|
- TODO: Room config - what is the event and what are the keys/values and explanations for them.
|
||||||
|
Link through to respective sections where necessary. How does this tie in with permissions, e.g.
|
||||||
|
give example of creating a read-only room.
|
||||||
|
|
||||||
|
|
||||||
Joining rooms
|
Joining rooms
|
||||||
|
|
@ -345,7 +353,7 @@ by sending the following request to
|
||||||
"membership": "join"
|
"membership": "join"
|
||||||
}
|
}
|
||||||
|
|
||||||
See the "Room events" section for more information on ``m.room.member``.
|
See the `Room events`_ section for more information on ``m.room.member``.
|
||||||
|
|
||||||
After the user has joined a room, they will receive subsequent events in that room. This room
|
After the user has joined a room, they will receive subsequent events in that room. This room
|
||||||
will now appear as an entry in the ``/initialSync`` API.
|
will now appear as an entry in the ``/initialSync`` API.
|
||||||
|
|
@ -387,7 +395,7 @@ directly by sending the following request to
|
||||||
"membership": "invite"
|
"membership": "invite"
|
||||||
}
|
}
|
||||||
|
|
||||||
See the "Room events" section for more information on ``m.room.member``.
|
See the `Room events`_ section for more information on ``m.room.member``.
|
||||||
|
|
||||||
- TODO: In what circumstances will this NOT be equivalent to ``/invite``?
|
- TODO: In what circumstances will this NOT be equivalent to ``/invite``?
|
||||||
|
|
||||||
|
|
@ -408,7 +416,7 @@ directly by sending the following request to
|
||||||
"membership": "leave"
|
"membership": "leave"
|
||||||
}
|
}
|
||||||
|
|
||||||
See the "Room events" section for more information on ``m.room.member``.
|
See the `Room events`_ section for more information on ``m.room.member``.
|
||||||
|
|
||||||
Once a user has left a room, that room will no longer appear on the ``/initialSync``
|
Once a user has left a room, that room will no longer appear on the ``/initialSync``
|
||||||
API. Be aware that leaving a room is not equivalent to have never been
|
API. Be aware that leaving a room is not equivalent to have never been
|
||||||
|
|
@ -506,7 +514,7 @@ In some cases, there may be no need for a ``state_key``, so it can be omitted::
|
||||||
PUT /rooms/!roomid:domain/state/m.room.bgd.color
|
PUT /rooms/!roomid:domain/state/m.room.bgd.color
|
||||||
{ "color": "red", "hex": "#ff0000" }
|
{ "color": "red", "hex": "#ff0000" }
|
||||||
|
|
||||||
See "Room Events" for the ``m.`` event specification.
|
See `Room Events`_ for the ``m.`` event specification.
|
||||||
|
|
||||||
Non-state events
|
Non-state events
|
||||||
----------------
|
----------------
|
||||||
|
|
@ -521,7 +529,7 @@ For example::
|
||||||
PUT /rooms/!roomid:domain/send/m.custom.example.message/11
|
PUT /rooms/!roomid:domain/send/m.custom.example.message/11
|
||||||
{ "text": "Goodbye world!" }
|
{ "text": "Goodbye world!" }
|
||||||
|
|
||||||
See "Room Events" for the ``m.`` event specification.
|
See `Room Events`_ for the ``m.`` event specification.
|
||||||
|
|
||||||
Syncing rooms
|
Syncing rooms
|
||||||
-------------
|
-------------
|
||||||
|
|
@ -588,7 +596,11 @@ There are several APIs provided to ``GET`` events for a room:
|
||||||
|
|
||||||
Room Events
|
Room Events
|
||||||
===========
|
===========
|
||||||
- voip events?
|
.. NOTE::
|
||||||
|
This section is a work in progress.
|
||||||
|
|
||||||
|
.. TODO dave?
|
||||||
|
- voip events?
|
||||||
|
|
||||||
This specification outlines several standard event types, all of which are
|
This specification outlines several standard event types, all of which are
|
||||||
prefixed with ``m.``
|
prefixed with ``m.``
|
||||||
|
|
@ -637,7 +649,7 @@ prefixed with ``m.``
|
||||||
membership APIs (``/rooms/<room id>/invite`` etc) when performing membership actions
|
membership APIs (``/rooms/<room id>/invite`` etc) when performing membership actions
|
||||||
rather than adjusting the state directly as there are a restricted set of valid
|
rather than adjusting the state directly as there are a restricted set of valid
|
||||||
transformations. For example, user A cannot force user B to join a room, and trying
|
transformations. For example, user A cannot force user B to join a room, and trying
|
||||||
to force this state change directly will fail. See the "Rooms" section for how to
|
to force this state change directly will fail. See the `Rooms`_ section for how to
|
||||||
use the membership APIs.
|
use the membership APIs.
|
||||||
|
|
||||||
``m.room.config``
|
``m.room.config``
|
||||||
|
|
@ -678,7 +690,7 @@ prefixed with ``m.``
|
||||||
The ``msgtype`` key outlines the type of message, e.g. text, audio, image, video, etc.
|
The ``msgtype`` key outlines the type of message, e.g. text, audio, image, video, etc.
|
||||||
Whilst not required, the ``body`` key SHOULD be used with every kind of ``msgtype`` as
|
Whilst not required, the ``body`` key SHOULD be used with every kind of ``msgtype`` as
|
||||||
a fallback mechanism when a client cannot render the message. For more information on
|
a fallback mechanism when a client cannot render the message. For more information on
|
||||||
the types of messages which can be sent, see "m.room.message msgtypes".
|
the types of messages which can be sent, see `m.room.message msgtypes`_.
|
||||||
|
|
||||||
``m.room.message.feedback``
|
``m.room.message.feedback``
|
||||||
Summary:
|
Summary:
|
||||||
|
|
@ -799,6 +811,8 @@ The following keys can be attached to any ``m.room.message``:
|
||||||
|
|
||||||
Presence
|
Presence
|
||||||
========
|
========
|
||||||
|
.. NOTE::
|
||||||
|
This section is a work in progress.
|
||||||
|
|
||||||
Each user has the concept of presence information. This encodes the
|
Each user has the concept of presence information. This encodes the
|
||||||
"availability" of that user, suitable for display on other user's clients. This
|
"availability" of that user, suitable for display on other user's clients. This
|
||||||
|
|
@ -837,8 +851,9 @@ user was last seen online.
|
||||||
|
|
||||||
Transmission
|
Transmission
|
||||||
------------
|
------------
|
||||||
- Transmitted as an EDU.
|
.. TODO:
|
||||||
- Presence lists determine who to send to.
|
- Transmitted as an EDU.
|
||||||
|
- Presence lists determine who to send to.
|
||||||
|
|
||||||
Presence List
|
Presence List
|
||||||
-------------
|
-------------
|
||||||
|
|
@ -863,28 +878,43 @@ presence information in a user list for a room.
|
||||||
|
|
||||||
Typing notifications
|
Typing notifications
|
||||||
====================
|
====================
|
||||||
- what is the event type. Are they bundled with other event types? If so, which.
|
.. NOTE::
|
||||||
- what are the valid keys / values. What do they represent. Any gotchas?
|
This section is a work in progress.
|
||||||
- Timeouts. How do they work, who sets them and how do they expire. Does one
|
|
||||||
have priority over another? Give examples.
|
|
||||||
|
|
||||||
TODO : Leo
|
.. TODO Leo
|
||||||
|
- what is the event type. Are they bundled with other event types? If so, which.
|
||||||
|
- what are the valid keys / values. What do they represent. Any gotchas?
|
||||||
|
- Timeouts. How do they work, who sets them and how do they expire. Does one
|
||||||
|
have priority over another? Give examples.
|
||||||
|
|
||||||
Voice over IP
|
Voice over IP
|
||||||
=============
|
=============
|
||||||
- what are the event types.
|
.. NOTE::
|
||||||
- what are the valid keys/values. What do they represent. Any gotchas?
|
This section is a work in progress.
|
||||||
- In what sequence should the events be sent?
|
|
||||||
- How do you accept / decline inbound calls? How do you make outbound calls?
|
|
||||||
Give examples.
|
|
||||||
- How does negotiation work? Give examples.
|
|
||||||
- How do you hang up?
|
|
||||||
- What does call log information look like e.g. duration of call?
|
|
||||||
|
|
||||||
TODO : Dave
|
.. TODO Dave
|
||||||
|
- what are the event types.
|
||||||
|
- what are the valid keys/values. What do they represent. Any gotchas?
|
||||||
|
- In what sequence should the events be sent?
|
||||||
|
- How do you accept / decline inbound calls? How do you make outbound calls?
|
||||||
|
Give examples.
|
||||||
|
- How does negotiation work? Give examples.
|
||||||
|
- How do you hang up?
|
||||||
|
- What does call log information look like e.g. duration of call?
|
||||||
|
|
||||||
Profiles
|
Profiles
|
||||||
========
|
========
|
||||||
|
.. NOTE::
|
||||||
|
This section is a work in progress.
|
||||||
|
|
||||||
|
.. TODO
|
||||||
|
- Metadata extensibility
|
||||||
|
- Changing profile info generates m.presence events ("presencelike")
|
||||||
|
- keys on m.presence are optional, except presence which is required
|
||||||
|
- m.room.member is populated with the current displayname at that point in time.
|
||||||
|
- That is added by the HS, not you.
|
||||||
|
- Display name changes also generates m.room.member with displayname key f.e. room
|
||||||
|
the user is in.
|
||||||
|
|
||||||
Internally within Matrix users are referred to by their user ID, which is not a
|
Internally within Matrix users are referred to by their user ID, which is not a
|
||||||
human-friendly string. Profiles grant users the ability to see human-readable
|
human-friendly string. Profiles grant users the ability to see human-readable
|
||||||
|
|
@ -896,24 +926,20 @@ metadata fields that the user may wish to publish (email address, phone
|
||||||
numbers, website URLs, etc...). This specification puts no requirements on the
|
numbers, website URLs, etc...). This specification puts no requirements on the
|
||||||
display name other than it being a valid unicode string.
|
display name other than it being a valid unicode string.
|
||||||
|
|
||||||
- Metadata extensibility
|
|
||||||
- Changing profile info generates m.presence events ("presencelike")
|
|
||||||
- keys on m.presence are optional, except presence which is required
|
|
||||||
- m.room.member is populated with the current displayname at that point in time.
|
|
||||||
- That is added by the HS, not you.
|
|
||||||
- Display name changes also generates m.room.member with displayname key f.e. room
|
|
||||||
the user is in.
|
|
||||||
|
|
||||||
Registration and login
|
Registration and login
|
||||||
======================
|
======================
|
||||||
|
.. WARNING::
|
||||||
|
The registration API is likely to change.
|
||||||
|
|
||||||
|
- TODO Kegan : Make registration like login (just omit the "user" key on the
|
||||||
|
initial request?)
|
||||||
|
|
||||||
Clients must register with a home server in order to use Matrix. After
|
Clients must register with a home server in order to use Matrix. After
|
||||||
registering, the client will be given an access token which must be used in ALL
|
registering, the client will be given an access token which must be used in ALL
|
||||||
requests to that home server as a query parameter 'access_token'.
|
requests to that home server as a query parameter 'access_token'.
|
||||||
|
|
||||||
- TODO Kegan : Make registration like login (just omit the "user" key on the
|
|
||||||
initial request?)
|
|
||||||
|
|
||||||
If the client has already registered, they need to be able to login to their
|
If the client has already registered, they need to be able to login to their
|
||||||
account. The home server may provide many different ways of logging in, such
|
account. The home server may provide many different ways of logging in, such
|
||||||
as user/password auth, login via a social network (OAuth2), login by confirming
|
as user/password auth, login via a social network (OAuth2), login by confirming
|
||||||
|
|
@ -1190,9 +1216,11 @@ This MUST return an HTML page which can perform the entire login process.
|
||||||
|
|
||||||
Identity
|
Identity
|
||||||
========
|
========
|
||||||
|
.. NOTE::
|
||||||
|
This section is a work in progress.
|
||||||
|
|
||||||
TODO : Dave
|
.. TODO Dave
|
||||||
- 3PIDs and identity server, functions
|
- 3PIDs and identity server, functions
|
||||||
|
|
||||||
Federation
|
Federation
|
||||||
==========
|
==========
|
||||||
|
|
@ -1233,6 +1261,9 @@ transferred from the origin to the destination home server using an HTTP PUT req
|
||||||
|
|
||||||
Transactions
|
Transactions
|
||||||
------------
|
------------
|
||||||
|
.. WARNING::
|
||||||
|
This section may be misleading or inaccurate.
|
||||||
|
|
||||||
The transfer of EDUs and PDUs between home servers is performed by an exchange
|
The transfer of EDUs and PDUs between home servers is performed by an exchange
|
||||||
of Transaction messages, which are encoded as JSON objects, passed over an
|
of Transaction messages, which are encoded as JSON objects, passed over an
|
||||||
HTTP PUT request. A Transaction is meaningful only to the pair of home servers that
|
HTTP PUT request. A Transaction is meaningful only to the pair of home servers that
|
||||||
|
|
@ -1275,6 +1306,8 @@ mechanism to encourage peers to continue to replicate content.)
|
||||||
|
|
||||||
PDUs and EDUs
|
PDUs and EDUs
|
||||||
-------------
|
-------------
|
||||||
|
.. WARNING::
|
||||||
|
This section may be misleading or inaccurate.
|
||||||
|
|
||||||
All PDUs have:
|
All PDUs have:
|
||||||
- An ID
|
- An ID
|
||||||
|
|
@ -1345,43 +1378,69 @@ destination home server names, and the actual nested content.
|
||||||
|
|
||||||
Backfilling
|
Backfilling
|
||||||
-----------
|
-----------
|
||||||
- What it is, when is it used, how is it done
|
.. NOTE::
|
||||||
|
This section is a work in progress.
|
||||||
|
|
||||||
|
.. TODO
|
||||||
|
- What it is, when is it used, how is it done
|
||||||
|
|
||||||
SRV Records
|
SRV Records
|
||||||
-----------
|
-----------
|
||||||
- Why it is needed
|
.. NOTE::
|
||||||
|
This section is a work in progress.
|
||||||
|
|
||||||
|
.. TODO
|
||||||
|
- Why it is needed
|
||||||
|
|
||||||
Security
|
Security
|
||||||
========
|
========
|
||||||
- rate limiting
|
- rate limiting
|
||||||
- crypto (s-s auth)
|
|
||||||
- E2E
|
|
||||||
- Lawful intercept + Key Escrow
|
|
||||||
|
|
||||||
TODO Mark
|
.. NOTE::
|
||||||
|
This section is a work in progress.
|
||||||
|
|
||||||
|
.. TODO
|
||||||
|
- crypto (s-s auth)
|
||||||
|
- E2E
|
||||||
|
- Lawful intercept + Key Escrow
|
||||||
|
TODO Mark
|
||||||
|
|
||||||
Policy Servers
|
Policy Servers
|
||||||
==============
|
==============
|
||||||
TODO
|
.. NOTE::
|
||||||
|
This section is a work in progress.
|
||||||
|
|
||||||
Content repository
|
Content repository
|
||||||
==================
|
==================
|
||||||
- path to upload
|
.. NOTE::
|
||||||
- format for thumbnail paths, mention what it is protecting against.
|
This section is a work in progress.
|
||||||
- content size limit and associated M_ERROR.
|
|
||||||
|
.. TODO
|
||||||
|
- path to upload
|
||||||
|
- format for thumbnail paths, mention what it is protecting against.
|
||||||
|
- content size limit and associated M_ERROR.
|
||||||
|
|
||||||
Address book repository
|
Address book repository
|
||||||
=======================
|
=======================
|
||||||
- format: POST(?) wodges of json, some possible processing, then return wodges of json on GET.
|
.. NOTE::
|
||||||
- processing may remove dupes, merge contacts, pepper with extra info (e.g. matrix-ability of
|
This section is a work in progress.
|
||||||
contacts), etc.
|
|
||||||
- Standard json format for contacts? Piggy back off vcards?
|
.. TODO
|
||||||
|
- format: POST(?) wodges of json, some possible processing, then return wodges of json on GET.
|
||||||
|
- processing may remove dupes, merge contacts, pepper with extra info (e.g. matrix-ability of
|
||||||
|
contacts), etc.
|
||||||
|
- Standard json format for contacts? Piggy back off vcards?
|
||||||
|
|
||||||
|
|
||||||
Glossary
|
Glossary
|
||||||
========
|
========
|
||||||
- domain specific words/acronyms with definitions
|
.. NOTE::
|
||||||
|
This section is a work in progress.
|
||||||
|
|
||||||
|
.. TODO
|
||||||
|
- domain specific words/acronyms with definitions
|
||||||
|
|
||||||
User ID:
|
User ID:
|
||||||
An opaque ID which identifies an end-user, which consists of some opaque
|
An opaque ID which identifies an end-user, which consists of some opaque
|
||||||
localpart combined with the domain name of their home server.
|
localpart combined with the domain name of their home server.
|
||||||
|
|
||||||
|
|
|
||||||
Loading…
Reference in a new issue