Merge pull request #4 from matrix-org/erikj-spec-changes

Erikj spec changes
This commit is contained in:
Paul Evans 2014-10-02 14:46:40 +01:00
commit 96213f69a2

View File

@ -167,7 +167,7 @@ The following diagram shows an ``m.room.message`` event being sent in the room
| matrix.org |<-------Federation------->| domain.com | | matrix.org |<-------Federation------->| domain.com |
+------------------+ +------------------+ +------------------+ +------------------+
| ................................. | | ................................. |
|______| Partially Shared State |_______| |______| Shared State |_______|
| Room ID: !qporfwt:matrix.org | | Room ID: !qporfwt:matrix.org |
| Servers: matrix.org, domain.com | | Servers: matrix.org, domain.com |
| Members: | | Members: |
@ -177,11 +177,10 @@ The following diagram shows an ``m.room.message`` event being sent in the room
Federation maintains shared state between multiple home servers, such that when Federation maintains shared state between multiple home servers, such that when
an event is sent to a room, the home server knows where to forward the event on an event is sent to a room, the home server knows where to forward the event on
to, and how to process the event. Home servers do not need to have completely to, and how to process the event. State is scoped to a single room, and
shared state in order to participate in a room. State is scoped to a single federation ensures that all home servers have the information they need, even
room, and federation ensures that all home servers have the information they if that means the home server has to request more information from another home
need, even if that means the home server has to request more information from server before processing the event.
another home server before processing the event.
Room Aliases Room Aliases
------------ ------------
@ -191,7 +190,7 @@ Each room can also have multiple "Room Aliases", which looks like::
#room_alias:domain #room_alias:domain
.. TODO .. TODO
- Need to specify precise grammar for Room IDs - Need to specify precise grammar for Room Aliases
A room alias "points" to a room ID and is the human-readable label by which A room alias "points" to a room ID and is the human-readable label by which
rooms are publicised and discovered. The room ID the alias is pointing to can rooms are publicised and discovered. The room ID the alias is pointing to can
@ -201,6 +200,9 @@ over time to point to a different room ID. For this reason, Clients SHOULD
resolve the room alias to a room ID once and then use that ID on subsequent resolve the room alias to a room ID once and then use that ID on subsequent
requests. requests.
When resolving a room alias the server will also respond with a list of servers
that are in the room that can be used to join via.
:: ::
GET GET
@ -239,8 +241,8 @@ authentication of the 3PID. Identity servers are also used to preserve the
mapping indefinitely, by replicating the mappings across multiple ISes. mapping indefinitely, by replicating the mappings across multiple ISes.
Usage of an IS is not required in order for a client application to be part of Usage of an IS is not required in order for a client application to be part of
the Matrix ecosystem. However, by not using an IS, discovery of users is the Matrix ecosystem. However, without one clients will not be able to look up
greatly impacted. user IDs using 3PIDs.
API Standards API Standards
------------- -------------
@ -719,7 +721,7 @@ options which can be set when creating a room:
Description: Description:
A ``public`` visibility indicates that the room will be shown in the public A ``public`` visibility indicates that the room will be shown in the public
room list. A ``private`` visibility will hide the room from the public room room list. A ``private`` visibility will hide the room from the public room
list. Rooms default to ``public`` visibility if this key is not included. list. Rooms default to ``private`` visibility if this key is not included.
``room_alias_name`` ``room_alias_name``
Type: Type:
@ -772,7 +774,7 @@ Example::
{ {
"visibility": "public", "visibility": "public",
"room_alias_name": "the pub", "room_alias_name": "thepub",
"name": "The Grand Duke Pub", "name": "The Grand Duke Pub",
"topic": "All about happy hour" "topic": "All about happy hour"
} }
@ -790,7 +792,7 @@ includes:
- ``m.room.send_event_level`` : The power level required in order to send a - ``m.room.send_event_level`` : The power level required in order to send a
message in this room. message in this room.
- ``m.room.ops_level`` : The power level required in order to kick or ban a - ``m.room.ops_level`` : The power level required in order to kick or ban a
user from the room. user from the room or redact an event in the room.
See `Room Events`_ for more information on these events. See `Room Events`_ for more information on these events.
@ -847,6 +849,7 @@ Joining rooms
------------- -------------
.. TODO-doc kegan .. TODO-doc kegan
- TODO: What does the home server have to do to join a user to a room? - TODO: What does the home server have to do to join a user to a room?
See SPEC-30.
Users need to join a room in order to send and receive events in that room. A Users need to join a room in order to send and receive events in that room. A
user can join a room by making a request to |/join/<room_alias_or_id>|_ with:: user can join a room by making a request to |/join/<room_alias_or_id>|_ with::
@ -945,11 +948,7 @@ directly by sending the following request to
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 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 |initialSync|_ API.
never been in that room. A user who has previously left a room still maintains
some residual state in that room. Their membership state will be marked as
``leave``. This contrasts with a user who has *never been invited or joined to
that room* who will not have any membership state for that room.
If all members in a room leave, that room becomes eligible for deletion. If all members in a room leave, that room becomes eligible for deletion.
@ -1314,7 +1313,7 @@ prefixed with ``m.``
Type: Type:
State event State event
JSON format: JSON format:
``{ "ban_level": <int>, "kick_level": <int> }`` ``{ "ban_level": <int>, "kick_level": <int>, "redact_level": <int> }``
Example: Example:
``{ "ban_level": 5, "kick_level": 5 }`` ``{ "ban_level": 5, "kick_level": 5 }``
Description: Description:
@ -1391,6 +1390,10 @@ prefixed with ``m.``
m.room.message msgtypes m.room.message msgtypes
----------------------- -----------------------
.. TODO-spec
How a client should handle unknown message types.
Each ``m.room.message`` MUST have a ``msgtype`` key which identifies the type 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 of message being sent. Each type has their own required and optional keys, as
outlined below: outlined below:
@ -1951,9 +1954,7 @@ is another list containing the EDUs. This key may be entirely absent if there
are no EDUs to transfer. are no EDUs to transfer.
(* Normally the PDU list will be non-empty, but the server should cope with (* Normally the PDU list will be non-empty, but the server should cope with
receiving an "empty" transaction, as this is useful for informing peers of receiving an "empty" transaction.)
other transaction IDs they should be aware of. This effectively acts as a push
mechanism to encourage peers to continue to replicate content.)
PDUs and EDUs PDUs and EDUs
------------- -------------
@ -2036,7 +2037,7 @@ For state updates:
Description: Description:
The asserted power level of the user performing the update. The asserted power level of the user performing the update.
``min_update`` ``required_power_level``
Type: Type:
Integer Integer
Description: Description:
@ -2054,7 +2055,7 @@ For state updates:
Description: Description:
The PDU id of the update this replaces. The PDU id of the update this replaces.
``user`` ``user_id``
Type: Type:
String String
Description: Description: