From d5099b2656961dbd24ac7bd9477ea5adea4c88a0 Mon Sep 17 00:00:00 2001 From: Kegan Dougal Date: Tue, 13 Jan 2015 09:51:53 +0000 Subject: [PATCH] Add session API. Add server-generated events. Moved 'Inviting' API from Final to ONGOING in light of issues brought up from PR comments and irl discussions. --- drafts/general_api.rst | 97 +++++++++++++++++++++++++++++++++++------- 1 file changed, 81 insertions(+), 16 deletions(-) diff --git a/drafts/general_api.rst b/drafts/general_api.rst index b29605bda..2e990155e 100644 --- a/drafts/general_api.rst +++ b/drafts/general_api.rst @@ -513,8 +513,22 @@ in parallel. An example of a client which may not need the use of action IDs includes bots which operate using basic request/responses in a synchronous fashion. -Inviting a user ``[Final]`` +Inviting a user ``[ONGOING]`` ~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.. NOTE:: + - Clients need to know *why* they are being invited (e.g. a ``reason`` key, + just like for kicks/bans). However, this opens up a spam vector where any + user can send any other user a string. Do we really want to do that? + - It may be useful to send other state information such as the room name, + topic, etc. How is this specified in this request? Does the inviter even + specify this, or is it a room config option which fields are shared? This + has a lot of parallels with the published room API which exposes some state + events. How do we prevent spam attacks via the room name/topic? + - The spam attack vector may be something we're just going to have to deal + with. Ultimately, we need to expose more data about the room. This data is + going to be set by the client. Compromises like "just give the event type" + don't really fix the problem "because.my.event.type.could.be.like.this". + Inputs: - User ID - Room ID @@ -722,6 +736,42 @@ Output: - A chunk of child events - A new chunk token for earlier child events. + +Session API ``[Draft]`` +----------------------- +See the "Session" section in "General client changes" for more information on +sessions. + +Starting a new session: + +Inputs: + - User ID + - Device ID + - Some sort of auth (e.g. ``access_token``) + - Desired presence status (e.g. "appear offline", "away") +Output: + - Session ID +Notes: + - This is an explicit endpoint for starting a new session. Clients typically + will not use this API to create a new session. + - Sessions will typically be started implicitly, whenever a session-less client + makes a new request to any API. + - Another form of identification e.g. ``access_token`` can be used to represent + the user ID / device ID combination. + - Presence is tied to the creation of a session. This endpoint can be used to + configure the starting presence of a new session, allowing the possibility + of an offline mode. + +Ending a session: + +Inputs: + - Session ID + - Some sort of auth (e.g. ``access_token``) +Output: + - None. +Notes: + - This is typically done when "going dark", e.g. closing an app. + Capabilities API ``[ONGOING]`` ------------------------------ .. NOTE:: @@ -846,20 +896,17 @@ General client changes These are changes which do not introduce new APIs, but are required for the new APIs in order to fix certain issues. -Sessions ``[ONGOING]`` -~~~~~~~~~~~~~~~~~~~~~~ -.. NOTE:: - - Offline mode? How does that work with sessions? Separate endpoint to say - "start a session only"? - -A session is a group of requests sent within a short amount of time by the same -client. Sessions time out after a short amount of time without any requests. -Starting a session is known as going "online". Its purpose is to wrap up the -expiry of presence and typing notifications into a clearer scope. A session -starts when the client makes any request. A session ends when the client doesn't -make a request for a particular amount of time (times out). A session can also -end when explicitly hitting a particular endpoint. This is known as going -"offline". +Sessions ``[Draft]`` +~~~~~~~~~~~~~~~~~~~~ + +A session is a group of requests sent by the same client. Sessions time out +after a short amount of time without any requests. Starting a session is known +as going "online". Its purpose is to wrap up the expiry of presence and typing +notifications into a clearer scope. A session starts when the client makes any +request. A session ends when the client doesn't make a request for a particular +amount of time (times out). A session can also end when explicitly hitting a +particular endpoint. This is known as going "offline". A session can also be +created by explicitly hitting a particular endpoint. When a session starts, a session ID is sent in response to the first request the client makes. This session ID should be sent in *all* subsequent requests. If @@ -867,7 +914,12 @@ the server expires a session and the client uses an old session ID, the server should fail the request with the old session ID and send a new session ID in response for the client to use. If the client receives a new session ID mid-session, it must re-establish its typing status and presence status, as they -are linked to the session ID. +are linked to the session ID. + +Lightweight clients who do not wish to manage their session can omit the +session ID on their requests. The home server MUST treat these requests as +coming from the active session in order to ensure that presence works correctly +for these simple clients. Action IDs ``[ONGOING]`` ~~~~~~~~~~~~~~~~~~~~~~~~ @@ -1007,4 +1059,17 @@ Events (breaking changes; event version 2) ``[Draft]`` the state key, etc. - s/user_id/sender/g given that home servers can send events, not just users. +Server-generated events ``[Draft]`` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Home servers may want to send events to their local clients or to other home +servers e.g. for server status notifications. + +These events look like regular events but have a server domain name as the +``sender`` and not a user ID. This can be easily detected by clients by the +absence of a starting ``@``. + +Different types of events (e.g. EDUs, room EDUs) are detected in the same way +as normal events (as proposed in the ``Events`` section of this document). + +