diff options
| -rw-r--r-- | docs/specification.rst | 187 |
1 files changed, 123 insertions, 64 deletions
diff --git a/docs/specification.rst b/docs/specification.rst index 2b47009187..3c6ed6b1c0 100644 --- a/docs/specification.rst +++ b/docs/specification.rst @@ -278,7 +278,7 @@ which can be set when creating a room: The ``name`` value for the ``m.room.name`` state event. Description: 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`` Type: @@ -289,7 +289,7 @@ which can be set when creating a room: The ``topic`` value for the ``m.room.topic`` state event. Description: 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:: @@ -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: Keys for speccing a room name / room topic / invite these users? +- TODO: Key for invite these users? Modifying aliases ----------------- -- path to edit aliases -- format when retrieving list of aliases. NOT complete list. -- format for adding aliases. +.. NOTE:: + This section is a work in progress. + +.. TODO kegan + - path to edit aliases + - format when retrieving list of aliases. NOT complete list. + - format for adding aliases. Permissions ----------- -- TODO: What is a power level? How do they work? Defaults / required levels for X. How do they change - 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. +.. NOTE:: + This section is a work in progress. + +.. TODO kegan + - TODO: What is a power level? How do they work? Defaults / required levels for X. How do they change + 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 @@ -345,7 +353,7 @@ by sending the following request to "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 will now appear as an entry in the ``/initialSync`` API. @@ -387,7 +395,7 @@ directly by sending the following request to "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``? @@ -408,7 +416,7 @@ directly by sending the following request to "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`` 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 { "color": "red", "hex": "#ff0000" } -See "Room Events" for the ``m.`` event specification. +See `Room Events`_ for the ``m.`` event specification. Non-state events ---------------- @@ -521,7 +529,7 @@ For example:: PUT /rooms/!roomid:domain/send/m.custom.example.message/11 { "text": "Goodbye world!" } -See "Room Events" for the ``m.`` event specification. +See `Room Events`_ for the ``m.`` event specification. Syncing rooms ------------- @@ -588,7 +596,11 @@ There are several APIs provided to ``GET`` events for a room: 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 prefixed with ``m.`` @@ -637,7 +649,7 @@ prefixed with ``m.`` 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 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. ``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. 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 - 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`` Summary: @@ -799,6 +811,8 @@ The following keys can be attached to any ``m.room.message``: Presence ======== +.. NOTE:: + This section is a work in progress. Each user has the concept of presence information. This encodes the "availability" of that user, suitable for display on other user's clients. This @@ -837,8 +851,9 @@ user was last seen online. Transmission ------------ -- Transmitted as an EDU. -- Presence lists determine who to send to. +.. TODO: + - Transmitted as an EDU. + - Presence lists determine who to send to. Presence List ------------- @@ -863,28 +878,43 @@ presence information in a user list for a room. Typing notifications ==================== -- 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. +.. NOTE:: + This section is a work in progress. -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 ============= -- 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? - -TODO : Dave +.. NOTE:: + This section is a work in progress. + +.. 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 ======== +.. 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 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 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 ====================== +.. 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 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'. -- 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 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 @@ -1190,9 +1216,11 @@ This MUST return an HTML page which can perform the entire login process. Identity ======== +.. NOTE:: + This section is a work in progress. -TODO : Dave -- 3PIDs and identity server, functions +.. TODO Dave + - 3PIDs and identity server, functions Federation ========== @@ -1233,6 +1261,9 @@ transferred from the origin to the destination home server using an HTTP PUT req Transactions ------------ +.. WARNING:: + This section may be misleading or inaccurate. + 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 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 ------------- +.. WARNING:: + This section may be misleading or inaccurate. All PDUs have: - An ID @@ -1345,43 +1378,69 @@ destination home server names, and the actual nested content. 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 ----------- -- Why it is needed +.. NOTE:: + This section is a work in progress. + +.. TODO + - Why it is needed Security ======== - 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 ============== -TODO +.. NOTE:: + This section is a work in progress. Content repository ================== -- path to upload -- format for thumbnail paths, mention what it is protecting against. -- content size limit and associated M_ERROR. +.. NOTE:: + This section is a work in progress. + +.. TODO + - path to upload + - format for thumbnail paths, mention what it is protecting against. + - content size limit and associated M_ERROR. Address book repository ======================= -- 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? +.. NOTE:: + This section is a work in progress. + +.. 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 ======== -- domain specific words/acronyms with definitions +.. NOTE:: + This section is a work in progress. + +.. TODO + - domain specific words/acronyms with definitions User ID: An opaque ID which identifies an end-user, which consists of some opaque localpart combined with the domain name of their home server. + |