Fleshed out joining/leaving rooms. Added M_LIMIT_EXCEEDED standard error code for rate limited requests.

This commit is contained in:
Kegan Dougal 2014-09-01 14:44:18 +01:00
parent 67ffc00d48
commit f500dd627a

View file

@ -168,6 +168,10 @@ Some standard error codes are below:
:``M_NOT_FOUND``: :``M_NOT_FOUND``:
No resource was found for this request. 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: Some requests have unique error codes:
:``M_USER_IN_USE``: :``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: 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 Modifying aliases
----------------- -----------------
@ -284,12 +289,37 @@ Permissions
Joining rooms Joining rooms
------------- -------------
- What is joining? What permissions / access does it give you? How does this affect /initialSync? - TODO: What does the home server have to do to join a user to a room?
- 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?
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 Inviting users
-------------- --------------
@ -331,12 +361,33 @@ See the "Room events" section for more information on ``m.room.member``.
Leaving rooms Leaving rooms
------------- -------------
- API to hit (``$roomid/leave``). See "Room events" for more info. A user can leave a room to stop receiving events for that room. A user must have
- Must be joined to leave. How does this affect /initialSync? joined the room before they are eligible to leave the room. If the room is an
- Not ever being in a room is NOT equivalent to have left it (due to membership: leave). "invite-only" room, they will need to be re-invited before they can re-join the room.
- Need to be re-invited if invite-only room. To leave a room, a request should be made to ``/rooms/<room id>/leave`` with::
- If no more HSes in room, can delete room?
- Is there a dance? {}
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 Events in a room
---------------- ----------------
@ -350,7 +401,7 @@ Events in a room
Syncing 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 Getting grouped state events
---------------------------- ----------------------------
@ -378,6 +429,7 @@ Non-state messages
------------------ ------------------
- m.room.message - m.room.message
- m.room.message.feedback (and compressed format) - m.room.message.feedback (and compressed format)
- voip?
What are they, when are they used, what do they contain, how should they be used What are they, when are they used, what do they contain, how should they be used