From b2d41b1cd94d6278f5d3e090d45762fff4219d2f Mon Sep 17 00:00:00 2001 From: Erik Johnston Date: Thu, 2 Oct 2014 14:25:47 +0100 Subject: [PATCH 1/9] All room state is currently shared. --- docs/specification.rst | 11 +++++------ 1 file changed, 5 insertions(+), 6 deletions(-) diff --git a/docs/specification.rst b/docs/specification.rst index 0a421e9e3..f45c75fca 100644 --- a/docs/specification.rst +++ b/docs/specification.rst @@ -167,7 +167,7 @@ The following diagram shows an ``m.room.message`` event being sent in the room | matrix.org |<-------Federation------->| domain.com | +------------------+ +------------------+ | ................................. | - |______| Partially Shared State |_______| + |______| Shared State |_______| | Room ID: !qporfwt:matrix.org | | Servers: matrix.org, domain.com | | 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 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 -shared state in order to participate in a room. State is scoped to a single -room, and federation ensures that all home servers have the information they -need, even if that means the home server has to request more information from -another home server before processing the event. +to, and how to process the event. State is scoped to a single room, and +federation ensures that all home servers have the information they need, even +if that means the home server has to request more information from another home +server before processing the event. Room Aliases ------------ From ff553cc9dd4fe7c9203a7c4c414e5fa27348180a Mon Sep 17 00:00:00 2001 From: Erik Johnston Date: Thu, 2 Oct 2014 14:26:58 +0100 Subject: [PATCH 2/9] Alias lookups return a server list. --- docs/specification.rst | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/docs/specification.rst b/docs/specification.rst index f45c75fca..e0609f707 100644 --- a/docs/specification.rst +++ b/docs/specification.rst @@ -190,7 +190,7 @@ Each room can also have multiple "Room Aliases", which looks like:: #room_alias:domain .. 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 rooms are publicised and discovered. The room ID the alias is pointing to can @@ -200,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 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 From 6860a18c12f9bedf59c70efca7ba2cda94f7b3dc Mon Sep 17 00:00:00 2001 From: Erik Johnston Date: Thu, 2 Oct 2014 14:27:35 +0100 Subject: [PATCH 3/9] Be less alarmist about not using an ID server. --- docs/specification.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/specification.rst b/docs/specification.rst index e0609f707..26a9c17d9 100644 --- a/docs/specification.rst +++ b/docs/specification.rst @@ -241,8 +241,8 @@ authentication of the 3PID. Identity servers are also used to preserve the 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 -the Matrix ecosystem. However, by not using an IS, discovery of users is -greatly impacted. +the Matrix ecosystem. However, without one clients will not be able to look up +user IDs using 3PIDs. API Standards ------------- From cf3188352b898c91c9c3e0ef65c9fb120b00cc13 Mon Sep 17 00:00:00 2001 From: Erik Johnston Date: Thu, 2 Oct 2014 14:28:22 +0100 Subject: [PATCH 4/9] Fix default value and key names. --- docs/specification.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/specification.rst b/docs/specification.rst index 26a9c17d9..e8790c2ad 100644 --- a/docs/specification.rst +++ b/docs/specification.rst @@ -721,7 +721,7 @@ options which can be set when creating a room: Description: 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 - 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`` Type: @@ -2038,7 +2038,7 @@ For state updates: Description: The asserted power level of the user performing the update. -``min_update`` +``required_power_level`` Type: Integer Description: @@ -2056,7 +2056,7 @@ For state updates: Description: The PDU id of the update this replaces. -``user`` +``user_id`` Type: String Description: From 918e71adb7c645ee6edf3e796204f916cee26a42 Mon Sep 17 00:00:00 2001 From: Erik Johnston Date: Thu, 2 Oct 2014 14:31:21 +0100 Subject: [PATCH 5/9] Don't use spaces in example room alias --- docs/specification.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/specification.rst b/docs/specification.rst index e8790c2ad..b5bfce59e 100644 --- a/docs/specification.rst +++ b/docs/specification.rst @@ -774,7 +774,7 @@ Example:: { "visibility": "public", - "room_alias_name": "the pub", + "room_alias_name": "thepub", "name": "The Grand Duke Pub", "topic": "All about happy hour" } From f368ad946ea987abfe5d7fc0d9f10971f8fecaef Mon Sep 17 00:00:00 2001 From: Erik Johnston Date: Thu, 2 Oct 2014 14:33:26 +0100 Subject: [PATCH 6/9] m.room.ops_levels includes redact_level --- docs/specification.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/specification.rst b/docs/specification.rst index b5bfce59e..732b50c69 100644 --- a/docs/specification.rst +++ b/docs/specification.rst @@ -792,7 +792,7 @@ includes: - ``m.room.send_event_level`` : The power level required in order to send a message in this room. - ``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. @@ -1316,7 +1316,7 @@ prefixed with ``m.`` Type: State event JSON format: - ``{ "ban_level": , "kick_level": }`` + ``{ "ban_level": , "kick_level": , "redact_level": }`` Example: ``{ "ban_level": 5, "kick_level": 5 }`` Description: From 1561ef56ed6b514aca6c21f2151af5ba892a69d2 Mon Sep 17 00:00:00 2001 From: Erik Johnston Date: Thu, 2 Oct 2014 14:34:13 +0100 Subject: [PATCH 7/9] Remove note about assymetry of having left a room. Currently, if you leave a room you still appear in the members list. This is basically a bug with the current implementation/spec, rather than something that should happen. --- docs/specification.rst | 6 +----- 1 file changed, 1 insertion(+), 5 deletions(-) diff --git a/docs/specification.rst b/docs/specification.rst index 732b50c69..081d949b4 100644 --- a/docs/specification.rst +++ b/docs/specification.rst @@ -947,11 +947,7 @@ directly by sending the following request to 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 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. +|initialSync|_ API. If all members in a room leave, that room becomes eligible for deletion. From 82e278029c92c2460976142bb2aadb3b9dcdfa93 Mon Sep 17 00:00:00 2001 From: Erik Johnston Date: Thu, 2 Oct 2014 14:38:22 +0100 Subject: [PATCH 8/9] Remove incorrect reasons for empty PDU lists. --- docs/specification.rst | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/docs/specification.rst b/docs/specification.rst index 081d949b4..dcb99d379 100644 --- a/docs/specification.rst +++ b/docs/specification.rst @@ -1949,9 +1949,7 @@ is another list containing the EDUs. This key may be entirely absent if there are no EDUs to transfer. (* 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 -other transaction IDs they should be aware of. This effectively acts as a push -mechanism to encourage peers to continue to replicate content.) +receiving an "empty" transaction.) PDUs and EDUs ------------- From 036333412d498b574075735ac5a49ce17036b11d Mon Sep 17 00:00:00 2001 From: Erik Johnston Date: Thu, 2 Oct 2014 14:38:53 +0100 Subject: [PATCH 9/9] Add todo notes --- docs/specification.rst | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/docs/specification.rst b/docs/specification.rst index dcb99d379..891470d5f 100644 --- a/docs/specification.rst +++ b/docs/specification.rst @@ -849,6 +849,7 @@ Joining rooms ------------- .. TODO-doc kegan - 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 user can join a room by making a request to |/join/|_ with:: @@ -1389,6 +1390,10 @@ prefixed with ``m.`` 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 of message being sent. Each type has their own required and optional keys, as outlined below: