diff options
Diffstat (limited to 'docs/specification.rst')
| -rw-r--r-- | docs/specification.rst | 90 |
1 files changed, 71 insertions, 19 deletions
diff --git a/docs/specification.rst b/docs/specification.rst index 3288aac019..d47705ca0f 100644 --- a/docs/specification.rst +++ b/docs/specification.rst @@ -168,6 +168,10 @@ Some standard error codes are below: :``M_NOT_FOUND``: No resource was found for this request. +:``M_LIMIT_EXCEEDED``: + Too many requests have been sent in a short period of time. Wait a while then + try again. + Some requests have unique error codes: :``M_USER_IN_USE``: @@ -273,6 +277,7 @@ 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? Modifying aliases ----------------- @@ -284,12 +289,37 @@ Permissions Joining rooms ------------- -- What is joining? What permissions / access does it give you? How does this affect /initialSync? -- API to hit (``/join/$alias or id``). Explain how alias joining works (auto-resolving). See "Room events" for more info. -- What does the home server have to do? -- Rooms that DON'T need an invite to join. This follows through onto inviting users section. -- Outline invite join dance? +- TODO: What does the home server have to do to join a user to a room? + +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:: + + {} + +Alternatively, a user can make a request to ``/rooms/<room id>/join`` with the same request content. +This is only provided for symmetry with the other membership APIs: ``/rooms/<room id>/invite`` and +``/rooms/<room id>/leave``. If a room alias was specified, it will be automatically resolved to +a room ID, which will then be joined. The room ID that was joined will be returned in response:: + + { + "room_id": "!roomid:domain" + } + +The membership state for the joining user can also be modified directly to be ``join`` +by sending the following request to +``/rooms/<room id>/state/m.room.member/<url encoded user id>``:: + + { + "membership": "join" + } + +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. +Some rooms enforce that a user is *invited* to a room before they can join that room. Other +rooms will allow anyone to join the room even if they have not received an invite. Inviting users -------------- @@ -331,12 +361,33 @@ See the "Room events" section for more information on ``m.room.member``. Leaving rooms ------------- -- API to hit (``$roomid/leave``). See "Room events" for more info. -- Must be joined to leave. How does this affect /initialSync? -- Not ever being in a room is NOT equivalent to have left it (due to membership: leave). -- Need to be re-invited if invite-only room. -- If no more HSes in room, can delete room? -- Is there a dance? +A user can leave a room to stop receiving events for that room. A user must have +joined the room before they are eligible to leave the room. If the room is an +"invite-only" room, they will need to be re-invited before they can re-join the room. +To leave a room, a request should be made to ``/rooms/<room id>/leave`` with:: + + {} + +Alternatively, the membership state for this user in this room can be modified +directly by sending the following request to +``/rooms/<room id>/state/m.room.member/<url encoded user id>``:: + + { + "membership": "leave" + } + +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. + +If all members in a room leave, that room becomes eligible for deletion. + - TODO: Grace period before deletion? + - TODO: Under what conditions should a room NOT be purged? Events in a room ---------------- @@ -350,7 +401,7 @@ Events in a room Syncing a room -------------- -- Single room initial sync. API to hit. Why it might be used (lazy loading) +- Single room initial sync. ``rooms/<room id>/initialSync`` API to hit. Why it might be used (lazy loading) Getting grouped state events ---------------------------- @@ -378,6 +429,7 @@ Non-state messages ------------------ - m.room.message - m.room.message.feedback (and compressed format) +- voip? What are they, when are they used, what do they contain, how should they be used @@ -490,7 +542,7 @@ Each user has the concept of presence information. This encodes the "availability" of that user, suitable for display on other user's clients. This is transmitted as an ``m.presence`` event and is one of the few events which are sent *outside the context of a room*. The basic piece of presence information -is represented by the ``state`` key, which is an enum of one of the following: +is represented by the ``presence`` key, which is an enum of one of the following: - ``online`` : The default state when the user is connected to an event stream. - ``unavailable`` : The user is not reachable at this time. @@ -500,18 +552,18 @@ is represented by the ``state`` key, which is an enum of one of the following: - ``hidden`` : TODO. Behaves as offline, but allows the user to see the client state anyway and generally interact with client features. -This basic ``state`` field applies to the user as a whole, regardless of how many +This basic ``presence`` field applies to the user as a whole, regardless of how many client devices they have connected. The home server should synchronise this status choice among multiple devices to ensure the user gets a consistent experience. Idle Time --------- -As well as the basic ``state`` field, the presence information can also show a sense -of an "idle timer". This should be maintained individually by the user's -clients, and the home server can take the highest reported time as that to -report. When a user is offline, the home server can still report when the user was last -seen online. +As well as the basic ``presence`` field, the presence information can also show +a sense of an "idle timer". This should be maintained individually by the +user's clients, and the home server can take the highest reported time as that +to report. When a user is offline, the home server can still report when the +user was last seen online. Transmission ------------ |